查询指南

1. 01
   query_metrics

   已知数据集、字段和筛选原始值时的默认路径；兼容的分析合并在一次请求中。

2. 02
   search_values

   对齐用户提供的品牌、店铺和品类名称；精确 ID、标准 URL 和本轮已返回的平台原始值无需重复发现。

3. 03
   describe(dataset)

   仅在字段、能力或版本错误后用于恢复，不作为例行前置检查。

4. 04
   list_datasets

   仅在无法从用户问题判断目标数据集时使用。

规则

• 首次业务工具调用前，用用户语言写一句简洁、自包含的 task_query，并在服务该任务的每次 Asklear 调用中逐字复用，包括 docs 和错误恢复调用；不得包含凭据或直接个人标识。
• 用户提供的品牌、店铺和品类名称是待对齐输入，不是标准实体。一个相关平台原始值使用 eq，多个相关值使用 in；无法确认是否同一实体时抽取代表商品验证，不得静默合并。
• search_values 返回 status=ambiguous 或 requires_clarification=true 时必须停止并让用户确认候选；若查询后才发现歧义，需明确告知实际使用的平台原始值。
• 区分用户请求范围、实际解析范围、授权范围和数据水位；不得静默裁剪、替换月份、补零或省略不可用时间。data_range_unavailable 是范围错误，不是 503 能力故障。
• 比较结果前核对平台、时间、筛选、指标和 group_by；跨数据集比较对每个数据集分别调用 query_metrics、报告各自实际解析月份，不假设共同水位。
• group_by 就是结果粒度。Top N 商品是样本，不代表完整市场；ASP 变化本身不能证明同款商品涨跌价。
• 区分服务端指标、Agent 计算和 Agent 判断；重要或反直觉结论在能力可用时应通过商品或 SKU 级证据验证。

工具边界

时间与范围

• 当前或最新对每个数据集分别使用 time.last_complete_months=1；近 N 个完整月使用 N。
• 明确的公共时间范围应原样分别发送，并报告每个数据集实际解析范围和 data_through。

解释与验证

• 不得从被截断或 Top N 结果推断完整市场结论。
• 说明指标定义，并区分结构变化和同款变化。

成本与恢复

• approval_required 返回最多消耗；执行后的实际扣费以 charged_credits 为准。
• 优先聚合，必要时才做商品下钻。失败请求不扣费，但不要围绕同一错误循环重试。
• query_too_broad 应缩短时间或收窄筛选、字段和粒度；unknown_field 应读取支持字段；data_range_unavailable 应说明请求范围和可用范围。

用户可读口径

• 说明数据集与平台、实际时间与水位、关键平台原始值、指标定义、筛选、group_by，以及结果是全量还是 Top N。
• 说明缺失、歧义、限制和口径变化；不要播报例行内部工具调用。

输出纪律

• 先用用户语言给出业务结论。
• 说明数据集与平台、实际时间与数据水位、关键平台原始值、指标定义、筛选、group_by，以及结果是全量还是 Top N。
• 区分服务端指标、Agent 计算和 Agent 判断。
• 说明相关的数据缺失、歧义、限制、审批或口径变化，不播报例行工具调用。

可选能力

调用示例

{
  "dataset": "jd",
  "field": "category_l3",
  "kw": "示例品类",
  "limit": 10,
  "task_query": "分析京东某品类最近一个完整月的品牌销售额排名"
}

{
  "dataset": "jd",
  "filters": [
    {
      "field": "category_l3",
      "op": "eq",
      "value": "示例品类"
    }
  ],
  "group_by": [
    "brand"
  ],
  "limit": 10,
  "metrics": [
    "gmv"
  ],
  "order_by": [
    {
      "dir": "desc",
      "field": "gmv"
    }
  ],
  "task_query": "分析京东某品类最近一个完整月的品牌销售额排名",
  "time": {
    "last_complete_months": 1
  }
}

{
  "input": {
    "output_format": "markdown",
    "urls": [
      "https://example.com/"
    ]
  },
  "task_code": "raw_html_v1",
  "task_query": "获取示例网页内容并用于当前研究任务"
}

{
  "idempotency_key": "web-research-1",
  "input": {
    "output_format": "markdown",
    "urls": [
      "https://example.com/"
    ]
  },
  "max_credits": 2,
  "quote_token": "<estimate_collection 返回的 quote_token>",
  "task_code": "raw_html_v1",
  "task_query": "获取示例网页内容并用于当前研究任务"
}

{
  "job_id": "<start_collection 返回的 job_id>",
  "task_query": "获取示例网页内容并用于当前研究任务"
}

异步采集

通过可估价、需确认且可追溯的异步任务获取最新公开信息。

只有当前 tools/list 返回采集操作时才使用采集能力。

流程

1. 01
   list_collection_tasks

   获取任务代码与当前接入权限。

2. 02
   estimate_collection

   估算任务，并向用户展示 upper_bound_credits 与预计时长。

3. 03
   start_collection

   获得明确同意后，使用估价返回值和新的 idempotency_key 启动任务。

4. 04
   get_collection_job

   只按 poll_after_seconds 轮询，并在 succeeded 或 failed 时停止。