---
document_id: agent.workflow
schema_version: 1
---

<!-- Generated by scripts.build_agent_guide; do not edit. -->

# Developer workflow / 开发者工作流

Choose one route. Do not run these entries as a linear checklist.

选择一条匹配路径，不要把以下条目依次全部执行。

## Decision routes / 决策路径

1. `query_metrics` — `query_metrics` · `required`
   - Default route. Call once with all compatible metrics, dimensions, filters, and up to four bundled atomic analyses.
   - 默认路径。将兼容的指标、维度、筛选和最多四个原子分析合并后一次调用。
2. `search_values` — `search_values` · `conditional`
   - Before query_metrics, resolve user-supplied brand, shop, and category names that have not already been returned as platform raw values. Fold up to four alignments into this one call; use field=category when the category level is unknown. Exact IDs and standard URLs are ready to query.
   - 在 query_metrics 前，对齐本轮尚未返回过平台原始值的品牌、店铺和品类名称；最多四个名称合并为一次。类目层级未知时使用 field=category。精确 ID 和标准 URL 可直接查询。
3. `describe(dataset)` — `describe` · `conditional`
   - Recovery route after an unknown-field, unsupported-capability, or stale-version response; not a routine preflight.
   - 仅在未知字段、不支持能力或版本过期响应后用于恢复；不是例行前置步骤。
4. `list_datasets` — `list_datasets` · `conditional`
   - Use only when the user's target dataset cannot be inferred from the question; otherwise pass the matching dataset directly.
   - 仅在无法从用户问题推断目标数据集时调用；能够判断时直接传入对应 dataset。

## Rules / 规则

- For latest/current, send time.last_complete_months=1 separately for each dataset. A JD/Tmall cross-dataset comparison uses separate query_metrics calls, reports each resolved month from meta.resolved_query, and never assumes a shared watermark.
  当前或最新对每个 dataset 分别发送 time.last_complete_months=1。JD/Tmall 跨数据集比较使用分开的 query_metrics 调用，分别报告 meta.resolved_query 中的实际月份，不假设共用数据水位。
- For an explicit shared range, send the unchanged range separately to each dataset; do not silently crop it.
  用户明确指定公共时间范围时，将原范围分别发送给每个数据集，不得静默裁剪。
- Explain data_range_unavailable to the user. Do not crop, substitute months, zero-fill, or silently omit unavailable data; this is a range error, not a 503 capability failure.
  向用户解释 data_range_unavailable；不得裁剪、替换月份、补零或静默省略不可用数据。这是范围错误，不是 503 能力不可用。
- Declared metrics, groupable dimensions, filters, and sorting compose freely; recipes are examples, not allowlists.
  契约声明的指标、可分组维度、筛选和排序可自由组合；recipe 是示例，不是白名单。
- group_by is the exact result grain; include month for trends and entity identity fields for shop or product results.
  group_by 即实际结果粒度；趋势包含 month，店铺或商品结果包含实体身份字段。

## Tool details / 工具细则

### `search_values` · `core`

- Call directly. On approval_required, retry the same request once with the approved max_credits and returned plan_digest.
  直接调用；返回 approval_required 时，使用已同意的 max_credits 和服务端 plan_digest 对相同请求重试一次。
- Align up to four values in one call: one primary search plus up to three named additional_searches.
  一次调用最多对齐四个取值：一个主搜索加最多三个命名 additional_searches。
- For a category name without a level, use field=category, then query with the concrete field echoed by the match.
  品类名未说明层级时使用 field=category，再用匹配结果回显的具体 field 查询。
- Use eq for one returned platform raw value and in for all relevant returned raw values.
  一个返回的平台原始值使用 eq，相关的多个原始值使用 in 一并查询。

### `quote` · `entitlement`

Use only when tools/list exposes quote for an entitled run_sql workflow. Metric-query previews use query_metrics with dry_run=true only when explicitly requested.

仅在 tools/list 为获授权的 run_sql 工作流开放 quote 时使用。指标查询仅在用户明确要求时通过 dry_run=true 的 query_metrics 预览。

- Execute the exact quoted SQL.
  只执行完全相同的已报价 SQL。

### `query_metrics` · `core`

- Call directly. On approval_required, retry the same request once with the approved max_credits and returned plan_digest.
  直接调用；返回 approval_required 时，使用已同意的 max_credits 和服务端 plan_digest 对相同请求重试一次。
- A user-requested metric price preview uses dry_run=true; ordinary queries execute directly.
  用户要求预览指标查询价格时使用 dry_run=true；普通查询直接执行。
- Bundle compatible analyses in additional_queries and place shared scope in common_filters.
  兼容分析放入 additional_queries；共同范围放 common_filters。
- Declared fields compose without a recipe; query only requested metrics and reuse resolved follow-up context.
  契约字段无需 recipe 即可组合；只查询所需指标并复用追问上下文。
- Omit main_query_name for one query; use lowercase ASCII identifiers for bundles.
  单查询省略 main_query_name；组合查询使用小写 ASCII 标识符。
- Product-level requests must return product identity fields.
  商品级请求必须返回商品身份字段。

### `get_pricing` · `core`

Use when the user asks how pricing works.

用户询问计价体系时使用。

- Use it for pricing rules, not a request-specific estimate.
  仅用于说明计价规则，不用于估算具体请求。
- Treat scan, delivery tiers, field points, and dictionary pricing as one versioned snapshot.
  扫描价、交付阶梯、字段点数和值字典价格属于同一版本快照。

### `sample_rows` · `optional`

Inspect data shape when explicitly needed.

明确需要理解数据形态时使用。

- Samples describe shape; analytical conclusions come from query tools.
  样例用于理解数据形态；分析结论来自查询工具。

### `results` · `optional`

Revisit an existing query_id or request another format; query_metrics already returns its rows.

仅在重访现有 query_id 或需要其他格式时使用；query_metrics 已经返回查询行。

- Use rows returned by query_metrics immediately; use results for an older query_id or another format.
  query_metrics 返回的行直接使用；results 用于旧 query_id 或其他格式。

### `export` · `entitlement`

Create a result file only when the user explicitly asks for an export and the authenticated entitlement exposes it.

仅在用户明确要求导出文件且认证权益开放 export 时创建结果文件。

- Product-level grouping and up to 1000 analytical rows use query_metrics independently of export availability.
  商品级分组和最多 1000 行分析结果使用 query_metrics，不依赖 export 权益。
- Follow the server-provided expiry, format, credit limits, and denial result.
  遵循服务端返回的有效期、格式、Credits 限制和拒绝结果。

### `run_sql` · `optional`

Use only for authorized internal detail analysis when tools/list explicitly returns run_sql.

仅当 tools/list 明确返回 run_sql 时，才用于获授权的内部明细分析。

- Call quote(sql) for the exact SQL. Execute automatically when approval_required=false; otherwise show the upper bound, wait for approval, and execute the same SQL with max_credits.
  对完全相同的 SQL 调用 quote(sql)。approval_required=false 时自动执行；否则展示上界、等待同意，再以相同 SQL 和 max_credits 执行。
- Treat absence from tools/list as unavailable.
  tools/list 未返回时视为不可用。

### Cost and approval / 费用与确认

- Require explicit approval only when approval_required=true, meaning the upper bound exceeds the access key's approval_threshold_credits (default 200 Credits).
  仅当 approval_required=true，即费用上界超过访问密钥的 approval_threshold_credits（默认 200 Credits）时，才要求用户明确同意。
- Present upper_bound_credits as the maximum charge; actual Credits follow the execution result.
  将 upper_bound_credits 表述为最多消耗；实际 Credits 以执行结果为准。
- For completed paid operations, use charged_credits as the actual debit and balance_after.available as the spendable balance shown by Dashboard. credits and priced_credits are the calculated price; when billing_mode=shadow, charged_credits is zero and the wallet is unchanged. balance_after.total is the gross wallet before reserved and refund_holds are removed.
  付费操作完成后，以 charged_credits 作为实际扣点，以 balance_after.available 作为与 Dashboard 一致的可用余额。credits 与 priced_credits 表示计算价格；billing_mode=shadow 时 charged_credits 为 0，钱包不扣减。balance_after.total 是尚未扣除 reserved 和 refund_holds 的钱包总额。
- When approval is required, bind execution to the server-provided upper bound with max_credits; retry without approval whenever analytical parameters change.
  需要同意时，使用 max_credits 绑定服务端返回的上界；任何分析参数变化后都要不带确认重新请求。
- The scan implementation is server-selected; use returned plan metadata as the execution fact.
  扫描实现由服务端选择；以返回的计划元数据作为执行事实。
- Treat insufficient credits, cap rejection, denied access, and unsupported capability as terminal results.
  余额不足、预算上限拒绝、权限拒绝和能力不支持属于终止结果。

### Time defaults / 时间默认值

- For latest/current, send time.last_complete_months=1 separately for each dataset. A JD/Tmall cross-dataset comparison uses separate query_metrics calls, reports each resolved month from meta.resolved_query, and never assumes a shared watermark. For recent N complete months use N.
  当前或最新对每个 dataset 分别发送 time.last_complete_months=1。JD/Tmall 跨数据集比较使用分开的 query_metrics 调用，分别报告 meta.resolved_query 中的实际月份，不假设共用数据水位；近 N 个完整月使用 N。
- For an explicit shared range, send the unchanged range separately to each dataset; do not silently crop it.
  用户明确指定公共时间范围时，将原范围分别发送给每个数据集，不得静默裁剪。
- Explain data_range_unavailable to the user. Do not crop, substitute months, zero-fill, or silently omit unavailable data; this is a range error, not a 503 capability failure.
  向用户解释 data_range_unavailable；不得裁剪、替换月份、补零或静默省略不可用数据。这是范围错误，不是 503 能力不可用。
- Ask the user when another time range cannot be determined reliably.
  其他时间范围无法可靠确定时询问用户。

### Certification and output / 认证与输出

- Report certified=true only when every metric in the response is certified by Asklear.
  仅当响应中的全部指标均通过 Asklear 认证时，才能报告 certified=true。
- Attach data_through and definitions; distinguish server metrics from Agent computations.
  附带 data_through 和指标定义，并区分服务端指标与 Agent 计算。