---
document_id: agent.querying
schema_version: 2
parent_document_id: agent.guide
section: querying
---

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

# Query Guide / 查询指南

Align platform values, execute the smallest sufficient query, and explain the exact scope returned by Asklear.

对齐平台原始值，执行足以回答问题的最小查询，并向用户说明 Asklear 实际返回的查询口径。

## Decision routes / 决策路径

1. `query_metrics` — `query_metrics` · `required`
   - Default route when the dataset, fields, and filter values are already known. Bundle compatible analyses in one request.
   - 已知数据集、字段和筛选原始值时的默认路径；兼容的分析合并在一次请求中。
2. `search_values` — `search_values` · `conditional`
   - Resolve user-supplied brand, shop, and category names that are not exact IDs, standard URLs, or raw values already returned in this conversation.
   - 对齐用户提供的品牌、店铺和品类名称；精确 ID、标准 URL 和本轮已返回的平台原始值无需重复发现。
3. `describe(dataset)` — `describe` · `conditional`
   - Recover after a field, capability, or version error. Do not use it as routine preflight.
   - 仅在字段、能力或版本错误后用于恢复，不作为例行前置检查。
4. `list_datasets` — `list_datasets` · `conditional`
   - Use only when the target dataset cannot be inferred from the user's question.
   - 仅在无法从用户问题判断目标数据集时使用。

## Rules / 规则

- Before the first business-tool call, write one concise, self-contained task_query in the user's language and reuse it verbatim for every Asklear call serving that task, including docs and recovery calls. Do not include credentials or direct personal identifiers.
  首次业务工具调用前，用用户语言写一句简洁、自包含的 task_query，并在服务该任务的每次 Asklear 调用中逐字复用，包括 docs 和错误恢复调用；不得包含凭据或直接个人标识。
- User-supplied brand, shop, and category names are inputs to align, not normalized entities. Use eq for one relevant platform raw value and in for multiple relevant values. If identity is uncertain, verify representative products instead of silently merging values.
  用户提供的品牌、店铺和品类名称是待对齐输入，不是标准实体。一个相关平台原始值使用 eq，多个相关值使用 in；无法确认是否同一实体时抽取代表商品验证，不得静默合并。
- Treat search_values status=ambiguous or requires_clarification=true as a stop condition. Ask the user which candidate they mean; if the ambiguity is only discovered after querying, disclose the exact raw value used.
  search_values 返回 status=ambiguous 或 requires_clarification=true 时必须停止并让用户确认候选；若查询后才发现歧义，需明确告知实际使用的平台原始值。
- Keep requested scope, resolved scope, entitled scope, and data watermark distinct. Never silently crop, substitute, zero-fill, or omit unavailable periods. data_range_unavailable is a range error, not a 503 capability failure.
  区分用户请求范围、实际解析范围、授权范围和数据水位；不得静默裁剪、替换月份、补零或省略不可用时间。data_range_unavailable 是范围错误，不是 503 能力故障。
- Compare results only after checking platform, time, filters, metrics, and group_by. A cross-dataset comparison uses a separate query_metrics call for each dataset, reports each resolved month, and never assumes a shared watermark.
  比较结果前核对平台、时间、筛选、指标和 group_by；跨数据集比较对每个数据集分别调用 query_metrics、报告各自实际解析月份，不假设共同水位。
- group_by is the result grain. A Top N product list is a sample, not the full market, and an ASP change does not by itself prove same-product price movement.
  group_by 就是结果粒度。Top N 商品是样本，不代表完整市场；ASP 变化本身不能证明同款商品涨跌价。
- Distinguish server metrics, Agent calculations, and Agent judgments. Verify important or counter-intuitive conclusions with product- or SKU-level evidence when the capability is available.
  区分服务端指标、Agent 计算和 Agent 判断；重要或反直觉结论在能力可用时应通过商品或 SKU 级证据验证。

## Tool details / 工具细则

### `query_metrics` · `core`

Aggregate supported metrics and dimensions. / 聚合受支持的指标和维度。

- Query only what is needed; place shared scope in common_filters and compatible analyses in additional_queries.
  只查询回答问题所需内容；共同范围放 common_filters，兼容分析放 additional_queries。
- Treat meta.resolved_query as the executed scope and meta.truncated as the completeness signal.
  以 meta.resolved_query 作为实际执行口径，以 meta.truncated 判断结果是否完整。
- Use meta.scope_summary as the concise user-visible projection of that executed scope.
  使用 meta.scope_summary 向用户简洁说明实际执行口径。

### `search_values` · `core`

Align searchable platform values before filtering. / 查询前对齐可搜索的平台原始值。

- Use field=category when the category level is unknown, then use the concrete field returned by the match.
  类目层级未知时使用 field=category，再使用匹配结果回显的具体字段。
- Do not repeat discovery for exact IDs, standard URLs, or raw values already returned in the current conversation.
  精确 ID、标准 URL 和本轮已返回的原始值无需重复发现。
- Stop for clarification when status is ambiguous or requires_clarification is true; never silently merge candidates.
  status 为 ambiguous 或 requires_clarification 为 true 时停止并让用户确认，不得静默合并候选。

### `docs` · `core`

Search or read the same documentation published on the web. / 检索或读取与网页同源的正式文档。

- Use the page index first when the required document ID is unknown.
  不知道文档 ID 时先读取页面索引。

### `get_pricing` · `core`

Explain current pricing rules, not a request-specific estimate. / 说明当前计价规则，不用于估算某个具体请求。

- Use the response as one versioned pricing snapshot.
  将返回内容视为同一个版本化价格快照。

### `list_datasets` · `optional`

Use only when the target dataset cannot be inferred. / 仅在无法判断目标数据集时使用。

- Select only a dataset returned by the authenticated call.
  只能选择认证调用实际返回的数据集。

### `describe` · `optional`

Recover after a contract or capability error. / 在契约或能力错误后恢复。

- Treat authenticated fields, limits, time range, and certification as runtime truth.
  以认证后返回的字段、限制、时间范围和认证状态作为运行时事实。

### `query_details` · `entitlement`

Drill into raw product fields, including title-keyword research, only when tools/list exposes it. / 仅当 tools/list 暴露该工具时，用于商品原始字段下钻，包括标题关键词研究。

- Use an explicit brand, shop, category, product reference, or other supported narrow scope.
  必须提供明确的品牌、店铺、类目、商品引用或其他受支持的窄范围。

### `export` · `entitlement`

Create a file only when the user explicitly requests one and tools/list exposes export. / 仅在用户明确要求文件且 tools/list 暴露 export 时导出。

- Follow server-provided format, expiry, access, and credit limits.
  遵循服务端返回的格式、有效期、权限和 Credits 限制。

### Time and scope / 时间与范围

- For latest/current use time.last_complete_months=1 separately for each dataset; for recent N complete months use N.
  当前或最新对每个数据集分别使用 time.last_complete_months=1；近 N 个完整月使用 N。
- Send an explicit shared range unchanged to each dataset and report each dataset's actual resolved range and data_through.
  明确的公共时间范围应原样分别发送，并报告每个数据集实际解析范围和 data_through。

### Interpretation and validation / 解释与验证

- Do not infer full-market conclusions from a truncated or Top N result.
  不得从被截断或 Top N 结果推断完整市场结论。
- Explain metric definitions and separate composition changes from same-item changes.
  说明指标定义，并区分结构变化和同款变化。

### Cost and recovery / 成本与恢复

- upper_bound_credits is the maximum charge; approval_required only decides whether user confirmation is needed. The actual debit is charged_credits after execution.
  upper_bound_credits 是最多消耗；approval_required 只表示是否需要用户确认。执行后的实际扣费以 charged_credits 为准。
- Prefer aggregation and drill into product details only when necessary. Failed requests are not charged; do not loop on the same error.
  优先聚合，必要时才做商品下钻。失败请求不扣费，但不要围绕同一错误循环重试。
- For query_too_broad narrow time, filters, fields, or result grain; for unknown_field read supported fields; for data_range_unavailable explain requested and available ranges.
  query_too_broad 应缩短时间或收窄筛选、字段和粒度；unknown_field 应读取支持字段；data_range_unavailable 应说明请求范围和可用范围。

### User-visible query scope / 用户可读口径

- State dataset and platform, resolved time and watermark, aligned raw values, metric definitions, filters, group_by, and whether results are complete or Top N.
  说明数据集与平台、实际时间与水位、关键平台原始值、指标定义、筛选、group_by，以及结果是全量还是 Top N。
- Call out missing data, ambiguity, limitations, and any scope change; do not narrate routine internal tool calls.
  说明缺失、歧义、限制和口径变化；不要播报例行内部工具调用。

## Output requirements / 输出要求

- Lead with the business conclusion in the user's language.
  先用用户语言给出业务结论。
- State the dataset and platform, resolved time and data watermark, aligned raw values, metric definitions, filters, group_by, and whether the result is complete or Top N.
  说明数据集与平台、实际时间与数据水位、关键平台原始值、指标定义、筛选、group_by，以及结果是全量还是 Top N。
- Distinguish server metrics, Agent calculations, and Agent judgments.
  区分服务端指标、Agent 计算和 Agent 判断。
- Explain relevant missing data, ambiguity, limitations, approvals, or scope changes without narrating routine tool calls.
  说明相关的数据缺失、歧义、限制、审批或口径变化，不播报例行工具调用。

## Optional capabilities / 可选能力

- `list_datasets` · `tools_list`
  - Absence from tools/list means unavailable.
    tools/list 未返回即表示不可用。
- `describe` · `tools_list`
  - Use for recovery, not routine preflight.
    用于错误恢复，不作为例行前置检查。
- `query_details` · `entitlements`
  - Use only when the authenticated tool surface exposes it.
    仅在认证后的工具面暴露时使用。
- `export` · `entitlements`
  - Use only for an explicitly requested file.
    仅用于用户明确要求的文件。

## Call examples / 调用示例

### Professional data / 专业数据查询

Replace the example category with the exact raw value returned by search_values. / 将示例品类替换为 search_values 返回的平台原始值。

`search_values`

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

`query_metrics`

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

### Public webpage / 公开网页采集

Estimate first; start directly when approval_required is false, otherwise wait for approval and pass the approved upper_bound_credits as max_credits. / 先估价；approval_required=false 时直接启动，否则等待用户确认并将获批的 upper_bound_credits 作为 max_credits。

`estimate_collection`

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

`start_collection`

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

`get_collection_job`

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


## Asynchronous collection / 异步采集

Retrieve fresh public information through an estimated, approved, and traceable asynchronous task.

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

> Use collection only when its operations appear in the current tools/list response.
> 只有当前 tools/list 返回采集操作时才使用采集能力。

### Workflow / 流程

1. `list_collection_tasks` — Discover the task code and current entitlement.
   获取任务代码与当前接入权限。
2. `describe_collection_task` — When two task codes look alike, read the one you picked: its description names the task it is confused with, and its examples and limitations are the input contract. Free, and cheaper than a rejected estimate.
   两个 task_code 看起来接近时，先读你选中的那个：描述会点名与它易混的任务，examples 和 limitations 就是入参契约。免费，比估错一次便宜。
3. `estimate_collection` — Estimate the task and obey approval_required; only show the bound and duration when approval is required.
   估算任务并遵循 approval_required；只有需要确认时才向用户展示费用上界与预计时长。
4. `start_collection` — Start immediately without max_credits when approval_required is false; otherwise start with the approved max_credits. Reuse quote_token exactly and use a new idempotency_key.
   approval_required=false 时不传 max_credits 直接启动；否则携带获批的 max_credits。逐字复用 quote_token，并使用新的 idempotency_key。
5. `get_collection_job` — Poll only after poll_after_seconds and stop at succeeded or failed.
   只按 poll_after_seconds 轮询，并在 succeeded 或 failed 时停止。

### Collection task references / 采集任务参考

- [Search notes / 搜索笔记](https://docs.asklearai.com/querying/collection/xhs_search_notes_v1) (`agent.collection.task.xhs_search_notes_v1`)
- [Note detail / 笔记详情](https://docs.asklearai.com/querying/collection/xhs_note_detail_v1) (`agent.collection.task.xhs_note_detail_v1`)
- [Note comments / 笔记评论](https://docs.asklearai.com/querying/collection/xhs_note_comments_v1) (`agent.collection.task.xhs_note_comments_v1`)
- [Comment replies / 评论回复](https://docs.asklearai.com/querying/collection/xhs_comment_sub_comments_v1) (`agent.collection.task.xhs_comment_sub_comments_v1`)
- [User notes / 用户笔记](https://docs.asklearai.com/querying/collection/xhs_user_notes_v1) (`agent.collection.task.xhs_user_notes_v1`)
- [Search videos / 搜索视频](https://docs.asklearai.com/querying/collection/douyin_search_videos_v1) (`agent.collection.task.douyin_search_videos_v1`)
- [Hot search board / 热搜榜](https://docs.asklearai.com/querying/collection/douyin_hot_search_v1) (`agent.collection.task.douyin_hot_search_v1`)
- [Video detail / 视频详情](https://docs.asklearai.com/querying/collection/douyin_video_detail_v1) (`agent.collection.task.douyin_video_detail_v1`)
- [Video comments / 视频评论](https://docs.asklearai.com/querying/collection/douyin_video_comments_v1) (`agent.collection.task.douyin_video_comments_v1`)
- [Author profile / 作者主页](https://docs.asklearai.com/querying/collection/douyin_author_profile_v1) (`agent.collection.task.douyin_author_profile_v1`)
- [Search videos / 搜索视频](https://docs.asklearai.com/querying/collection/bilibili_search_videos_v1) (`agent.collection.task.bilibili_search_videos_v1`)
- [Video detail / 视频详情](https://docs.asklearai.com/querying/collection/bilibili_video_detail_v1) (`agent.collection.task.bilibili_video_detail_v1`)
- [Video comments / 视频评论](https://docs.asklearai.com/querying/collection/bilibili_video_comments_v1) (`agent.collection.task.bilibili_video_comments_v1`)
- [Author profile / 作者主页](https://docs.asklearai.com/querying/collection/bilibili_author_profile_v1) (`agent.collection.task.bilibili_author_profile_v1`)
- [Status detail / 微博详情](https://docs.asklearai.com/querying/collection/weibo_status_detail_v1) (`agent.collection.task.weibo_status_detail_v1`)
- [Status comments / 微博评论](https://docs.asklearai.com/querying/collection/weibo_status_comments_v1) (`agent.collection.task.weibo_status_comments_v1`)
- [Author profile / 作者主页](https://docs.asklearai.com/querying/collection/weibo_author_profile_v1) (`agent.collection.task.weibo_author_profile_v1`)
- [Article detail / 文章详情](https://docs.asklearai.com/querying/collection/wechat_mp_article_detail_v1) (`agent.collection.task.wechat_mp_article_detail_v1`)
- [Account articles / 账号文章](https://docs.asklearai.com/querying/collection/wechat_mp_account_articles_v1) (`agent.collection.task.wechat_mp_account_articles_v1`)
- [Account profile / 账号资料](https://docs.asklearai.com/querying/collection/wechat_mp_account_profile_v1) (`agent.collection.task.wechat_mp_account_profile_v1`)
- [Article comments / 文章评论](https://docs.asklearai.com/querying/collection/wechat_mp_article_comments_v1) (`agent.collection.task.wechat_mp_article_comments_v1`)
- [Article stats / 文章统计](https://docs.asklearai.com/querying/collection/wechat_mp_article_stats_v1) (`agent.collection.task.wechat_mp_article_stats_v1`)
- [Account services / 账号服务](https://docs.asklearai.com/querying/collection/wechat_mp_account_services_v1) (`agent.collection.task.wechat_mp_account_services_v1`)
- [Comment replies / 评论回复](https://docs.asklearai.com/querying/collection/wechat_mp_comment_replies_v1) (`agent.collection.task.wechat_mp_comment_replies_v1`)
- [Related articles / 关联文章](https://docs.asklearai.com/querying/collection/wechat_mp_related_articles_v1) (`agent.collection.task.wechat_mp_related_articles_v1`)
- [Article ad / 文章广告](https://docs.asklearai.com/querying/collection/wechat_mp_article_ad_v1) (`agent.collection.task.wechat_mp_article_ad_v1`)
- [Channel info / 视频号信息](https://docs.asklearai.com/querying/collection/wechat_channel_info_v1) (`agent.collection.task.wechat_channel_info_v1`)
- [Channel id to username / 视频号ID转用户名](https://docs.asklearai.com/querying/collection/wechat_channel_id_to_username_v1) (`agent.collection.task.wechat_channel_id_to_username_v1`)
- [User profile / 用户资料](https://docs.asklearai.com/querying/collection/wechat_channel_user_profile_v1) (`agent.collection.task.wechat_channel_user_profile_v1`)
- [User videos / 用户作品](https://docs.asklearai.com/querying/collection/wechat_channel_user_videos_v1) (`agent.collection.task.wechat_channel_user_videos_v1`)
- [Video detail / 视频详情](https://docs.asklearai.com/querying/collection/wechat_channel_video_detail_v1) (`agent.collection.task.wechat_channel_video_detail_v1`)
- [Video comments / 视频评论](https://docs.asklearai.com/querying/collection/wechat_channel_video_comments_v1) (`agent.collection.task.wechat_channel_video_comments_v1`)
- [Share url / 分享链接](https://docs.asklearai.com/querying/collection/wechat_channel_video_share_url_v1) (`agent.collection.task.wechat_channel_video_share_url_v1`)
- [User collections / 用户合集](https://docs.asklearai.com/querying/collection/wechat_channel_user_collections_v1) (`agent.collection.task.wechat_channel_user_collections_v1`)
- [Collection videos / 合集视频](https://docs.asklearai.com/querying/collection/wechat_channel_collection_videos_v1) (`agent.collection.task.wechat_channel_collection_videos_v1`)
- [Live history / 直播回放](https://docs.asklearai.com/querying/collection/wechat_channel_live_history_v1) (`agent.collection.task.wechat_channel_live_history_v1`)
- [Live detail / 直播详情](https://docs.asklearai.com/querying/collection/wechat_channel_live_detail_v1) (`agent.collection.task.wechat_channel_live_detail_v1`)
- [Search videos / 号内搜索](https://docs.asklearai.com/querying/collection/wechat_channel_search_videos_v1) (`agent.collection.task.wechat_channel_search_videos_v1`)
- [Web collection / 网页采集](https://docs.asklearai.com/querying/collection/raw_html_v1) (`agent.collection.task.raw_html_v1`)

### Billing and retries / 计费与重试

- upper_bound_credits is a safety ceiling; a successful task settles the actual amount within that ceiling.
  upper_bound_credits 是安全上界；成功任务按不超过该上界的实际金额结算。
- A failed task releases the user's Credits reservation and does not settle a user charge.
  失败任务释放用户 Credits 预留，不结算用户扣费。
- Reuse an idempotency_key only for the same task; an intentionally new task requires a new key.
  相同 idempotency_key 只用于同一任务；明确新建任务时才使用新的键。
- For collection_external_unknown, the user's Credits were not settled but the provider-side fee is unknown; do not retry automatically and ask the user to decide.
  遇到 collection_external_unknown 时，用户 Credits 未结算但供应商侧费用未知；禁止自动重试，交由用户决定。

### Errors and access / 错误与权限

- Resolve a terminal error_code with page=agent.error.<error_code>; fall back to page=agent.errors when absent.
  用 page=agent.error.<error_code> 处理终态错误；页面不存在时回退到 page=agent.errors。
- Runtime tools/list is authoritative for collection access.
  采集权限以运行时 tools/list 为准。