开发者工作流
默认直接查询，仅在歧义或契约错误时发现能力。
Markdown文档 ID:
agent.workflow租户实际范围和当前数据时间以认证后的 describe 返回为准。
- 01
query_metrics默认路径。将兼容的指标、维度、筛选和最多四个原子分析合并后一次调用。
- 02
search_values在 query_metrics 前，对齐本轮尚未返回过平台原始值的品牌、店铺和品类名称；最多四个名称合并为一次。类目层级未知时使用 field=category。精确 ID 和标准 URL 可直接查询。
- 03
describe(dataset)仅在未知字段、不支持能力或版本过期响应后用于恢复；不是例行前置步骤。
- 04
list_datasets仅在无法从用户问题推断目标数据集时调用；能够判断时直接传入对应 dataset。
规则
- 当前或最新对每个 dataset 分别发送 time.last_complete_months=1。JD/Tmall 跨数据集比较使用分开的 query_metrics 调用，分别报告 meta.resolved_query 中的实际月份，不假设共用数据水位。
- 用户明确指定公共时间范围时，将原范围分别发送给每个数据集，不得静默裁剪。
- 向用户解释 data_range_unavailable；不得裁剪、替换月份、补零或静默省略不可用数据。这是范围错误，不是 503 能力不可用。
- 契约声明的指标、可分组维度、筛选和排序可自由组合；recipe 是示例，不是白名单。
- group_by 即实际结果粒度；趋势包含 month，店铺或商品结果包含实体身份字段。
运行时与计费策略
list_datasets
目标数据集未知时用于恢复或发现；京东问题使用 jd。
- 只能选择本次调用返回的数据集。
describe
在能力、字段或版本错误后恢复；相对时间由服务端在查询时解析。
- 认证后返回的字段、限制、time_range 和指标认证状态是运行时事实；recipe 仅供参考。
- 以 tools/list 作为当前完整可用工具范围。
search_values
对齐声明为可搜索字段的用户品牌、店铺和品类名称；精确引用可直接查询。
- 直接调用；返回 approval_required 时，使用已同意的 max_credits 和服务端 plan_digest 对相同请求重试一次。
- 一次调用最多对齐四个取值：一个主搜索加最多三个命名 additional_searches。
- 品类名未说明层级时使用 field=category，再用匹配结果回显的具体 field 查询。
- 一个返回的平台原始值使用 eq，相关的多个原始值使用 in 一并查询。
quote
仅在 tools/list 为获授权的 run_sql 工作流开放 quote 时使用。指标查询仅在用户明确要求时通过 dry_run=true 的 query_metrics 预览。
- 只执行完全相同的已报价 SQL。
query_metrics
使用已对齐的筛选值执行用户要求的指标和结果维度。
- 直接调用；返回 approval_required 时，使用已同意的 max_credits 和服务端 plan_digest 对相同请求重试一次。
- 用户要求预览指标查询价格时使用 dry_run=true；普通查询直接执行。
- 兼容分析放入 additional_queries；共同范围放 common_filters。
- 契约字段无需 recipe 即可组合；只查询所需指标并复用追问上下文。
- 单查询省略 main_query_name；组合查询使用小写 ASCII 标识符。
- 商品级请求必须返回商品身份字段。
get_pricing
用户询问计价体系时使用。
- 仅用于说明计价规则，不用于估算具体请求。
- 扫描价、交付阶梯、字段点数和值字典价格属于同一版本快照。
sample_rows
明确需要理解数据形态时使用。
- 样例用于理解数据形态；分析结论来自查询工具。
results
仅在重访现有 query_id 或需要其他格式时使用；query_metrics 已经返回查询行。
- query_metrics 返回的行直接使用；results 用于旧 query_id 或其他格式。
export
仅在用户明确要求导出文件且认证权益开放 export 时创建结果文件。
- 商品级分组和最多 1000 行分析结果使用 query_metrics，不依赖 export 权益。
- 遵循服务端返回的有效期、格式、Credits 限制和拒绝结果。
run_sql
仅当 tools/list 明确返回 run_sql 时，才用于获授权的内部明细分析。
- 对完全相同的 SQL 调用 quote(sql)。approval_required=false 时自动执行；否则展示上界、等待同意，再以相同 SQL 和 max_credits 执行。
- tools/list 未返回时视为不可用。
费用与确认
- 仅当 approval_required=true，即费用上界超过访问密钥的 approval_threshold_credits（默认 200 Credits）时，才要求用户明确同意。
- 将 upper_bound_credits 表述为最多消耗；实际 Credits 以执行结果为准。
- 付费操作完成后，以 charged_credits 作为实际扣点，以 balance_after.available 作为与 Dashboard 一致的可用余额。credits 与 priced_credits 表示计算价格；billing_mode=shadow 时 charged_credits 为 0，钱包不扣减。balance_after.total 是尚未扣除 reserved 和 refund_holds 的钱包总额。
- 需要同意时，使用 max_credits 绑定服务端返回的上界；任何分析参数变化后都要不带确认重新请求。
- 扫描实现由服务端选择；以返回的计划元数据作为执行事实。
- 余额不足、预算上限拒绝、权限拒绝和能力不支持属于终止结果。
时间默认值
- 当前或最新对每个 dataset 分别发送 time.last_complete_months=1。JD/Tmall 跨数据集比较使用分开的 query_metrics 调用，分别报告 meta.resolved_query 中的实际月份，不假设共用数据水位；近 N 个完整月使用 N。
- 用户明确指定公共时间范围时，将原范围分别发送给每个数据集，不得静默裁剪。
- 向用户解释 data_range_unavailable；不得裁剪、替换月份、补零或静默省略不可用数据。这是范围错误，不是 503 能力不可用。
- 其他时间范围无法可靠确定时询问用户。
认证与输出
- 仅当响应中的全部指标均通过 Asklear 认证时，才能报告 certified=true。
- 附带 data_through 和指标定义，并区分服务端指标与 Agent 计算。
可选能力
list_datasets
- 数据集未知时使用；Asklear 京东问题使用 jd。
describe
- 用于契约或能力错误后的恢复，不作为例行前置检查。
quote
- 仅在获授权的 run_sql 工作流中出现；指标查询永远不要求先调用它。
sample_rows
- 用于查看数据形态；分析证据来自查询工具。
results
- 用于重访现有结果或转换格式。
export
- 当前认证权益开放时使用。
run_sql
- tools/list 未返回即表示不可用。