---
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 / 查询指南

Use tools/list as the authoritative tool surface and take the shortest safe route: a known exact reference or resolved value goes to query_metrics, a product name or title goes through search_products, and an unresolved brand, shop, or category goes through search_values first. connection_status is free and not a heartbeat; it checks Asklear connection only. Keep remote data MCP, async collection, and local browser MCP separate. Explain Asklear billing metadata and never expose provider fields or fees.

以 tools/list 作为权威工具面并走最短安全路径：已知精确引用或已解析值直接 query_metrics，商品名称或标题先用 search_products，未解析的品牌、店铺或品类先用 search_values。connection_status 免费且不是心跳，只检查 Asklear 连接。远程 data MCP、异步采集和本地浏览器 MCP 分开。解释 Asklear 计费 metadata，绝不暴露 provider fields 或费用。

## 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. `search_products` — `search_products` · `conditional`
   - Resolve a product name or title to one or more product candidates before requesting sales metrics; use only when tools/list exposes this optional capability.
   - 在查询销售指标前，将商品名称或标题解析为一个或多个商品候选；仅当 tools/list 暴露这一可选能力时使用。
4. `describe(dataset)` — `describe` · `conditional`
   - Recover after a field, capability, or version error. Do not use it as routine preflight.
   - 仅在字段、能力或版本错误后用于恢复，不作为例行前置检查。
5. `list_datasets` — `list_datasets` · `conditional`
   - Use only when the target dataset cannot be inferred from the user's question.
   - 仅在无法从用户问题判断目标数据集时使用。

## Rules / 规则

- When possible, provide 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. If omitted, Asklear uses a fixed non-user-specific attribution and still executes the call. Do not use task_query as a locale; Accept-Language controls human text. Do not include credentials or direct personal identifiers.
  业务调用时建议用用户语言提供一句简洁、自包含的 task_query，并在服务该任务的每次 Asklear 调用中逐字复用，包括 docs 和错误恢复调用；未提供时 Asklear 使用固定的非用户归因并继续执行。task_query 是任务描述，不是 locale，人工文案由 Accept-Language 控制；不得包含凭据或直接个人标识。
- 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 级证据验证。
- Use the shortest route: an exact product URL, ID, or already resolved value goes directly to query_metrics; an unresolved brand, shop, or category uses search_values once and then query_metrics. Do not repeat an already resolved brand or add discovery, describe, or quote without a stated need.
  走最短路径：精确商品 URL、ID 或已解析值直接 query_metrics；未解析的品牌、店铺或品类只调用一次 search_values 后 query_metrics。不得重复已解析品牌，也不得无理由增加 discovery、describe 或 quote。
- A product name or title is a lookup request, not a sales query: use search_products, ask the user to choose when multiple candidates are returned, then pass the selected product_id to query_metrics or query_details. search_products does not return GMV or units.
  商品名称或标题是身份检索，不是销售指标查询：使用 search_products；返回多个候选时让用户选择，再把选定的 product_id 传给 query_metrics 或 query_details。search_products 不返回 GMV 或销量。
- tools/list is authoritative. connection_status is free and is not a per-call heartbeat or business preflight. Use only tools exposed by the current list; do not silently use a hidden browser or remote collection tool.
  tools/list 是权威能力表。connection_status 免费且不是每次调用的心跳，也不是业务预检。只使用当前列表暴露的工具，不得暗中调用隐藏的浏览器或远程采集工具。
- Keep remote data MCP, async collection, and local browser MCP separate. Collection is list_collection_tasks -> estimate_collection -> user confirmation when required -> start_collection -> bounded get_collection_job polls; a known job_id is read for recovery, not used to start a second job.
  远程 data MCP、异步采集和本地浏览器 MCP 必须分开。采集按 list_collection_tasks→estimate_collection→必要时用户确认→start_collection→有界 get_collection_job 轮询；已知 job_id 只用于恢复读取，不得启动第二个任务。
- Request only the smallest sufficient metrics. Interpret Asklear billing metadata as the returned scope, watermark, upper_bound_credits, and charged_credits; do not request or repeat provider fields, provider prices, or provider charges.
  只请求足以回答问题的最小指标。Asklear 计费 metadata 只解释返回的口径、水位、upper_bound_credits 和 charged_credits；不得请求或转述 provider fields、provider prices 或 provider charges。
- A retryable paid single operation reuses the same idempotency key and may recover only from an existing idempotency record. Bundles reject idempotency_key and are non-atomic; omit the key with additional_queries or additional_searches. Category lookup may expand into a bundle; use concrete category_lN fields for independent keyed searches. Recover only failed items whose outcome is known, never replay successful items or an unknown paid outcome. Approval control is not business data or a business replay.
  可重试的付费单次操作复用同一 idempotency key，且只能从已有幂等记录恢复。bundle 非原子且拒绝 idempotency_key；使用 additional_queries 或 additional_searches 时不要传 key。category 搜索可能展开为组合查询，需要独立幂等搜索时使用具体 category_lN 字段。只恢复结果明确的失败项，不重放成功项或付费结果未知的操作。approval control 不是业务数据，也不算业务重放。
- Ordinary MCP failures are isError=true. For collection_external_unknown, stop with no automatic replay; never send a second paid call just because the first outcome is unknown. Follow the returned recovery action and its bound.
  MCP 普通失败使用 isError=true。遇到 collection_external_unknown 时停止且 no automatic replay；第一次结果未知时不得仅因不确定就再次发起付费调用。遵循返回的恢复动作及其上限。

## 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 时停止并让用户确认，不得静默合并候选。

### `search_products` · `optional`

Find product identity candidates from a product name or title before a metrics query. / 在查询指标前，根据商品名称或标题查找商品身份候选。

- Use only when tools/list exposes search_products; this is not search_values and does not return sales metrics.
  仅当 tools/list 暴露 search_products 时使用；它不同于 search_values，也不返回销售指标。
- Ask the user to choose when status=ambiguous or more than one candidate is returned; never choose silently.
  status=ambiguous 或返回多个候选时让用户选择，不得静默代选。
- After the user selects a product_id, call query_metrics or query_details with that exact identity.
  用户选定 product_id 后，再用这个精确身份调用 query_metrics 或 query_details。

### `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 应说明请求范围和可用范围。
- Approval controls contain the plan, bound, and same-key retry instructions but no data. Retry the identical approved request once with the same idempotency key; recover a known idempotency record instead of replaying an unknown paid call.
  审批 control 只包含计划、上界和同 key 重试说明，不含业务数据。使用同一 idempotency key 对获批的相同请求最多重试一次；优先恢复已知幂等记录，不得重放结果未知的付费调用。
- Bundles are non-atomic. For collection_external_unknown, Stop. Do not automatically replay; read a known job_id when one exists and otherwise ask before a new attempt.
  bundle 是 non-atomic。collection_external_unknown 时停止且不得自动重放；有已知 job_id 就读取，没有则在新尝试前询问。

### 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.
  说明相关的数据缺失、歧义、限制、审批或口径变化，不播报例行工具调用。
- Explain Asklear billing metadata (scope_summary, data_through, upper_bound_credits, and charged_credits) in plain language; provider fields, provider prices, and provider charges are never public output.
  用通俗语言解释 Asklear 计费 metadata（scope_summary、data_through、upper_bound_credits、charged_credits）；provider fields、provider prices 和 provider charges 永不作为公开输出。

## Optional capabilities / 可选能力

- `list_datasets` · `tools_list`
  - Absence from tools/list means unavailable.
    tools/list 未返回即表示不可用。
- `describe` · `tools_list`
  - Use for recovery, not routine preflight.
    用于错误恢复，不作为例行前置检查。
- `search_products` · `tools_list`
  - Use only when tools/list exposes it; absence means product-name lookup is unavailable for this connection.
    仅当 tools/list 暴露时使用；未暴露表示当前连接不支持按商品名称检索。
  - If unavailable, ask for an exact product_id or standard product URL instead of guessing.
    如果不可用，请用户提供精确 product_id 或标准商品链接，不要猜测。
- `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
}
```

### Product identity lookup / 商品身份检索

Use search_products only when tools/list exposes it. It finds candidates by title; it does not return sales metrics. Select a product_id before the metrics query. / 仅当 tools/list 暴露 search_products 时使用。它按标题查找候选，不返回销售指标；先选定 product_id，再查询指标。

`search_products`

```json
{
  "task_query": "查找京东 AirPods Pro 商品并查看销售表现",
  "dataset": "jd",
  "query": "AirPods Pro",
  "time": {
    "last_complete_months": 3
  },
  "limit": 10,
  "idempotency_key": "product-lookup-1"
}
```

`query_metrics`

```json
{
  "task_query": "查找京东 AirPods Pro 商品并查看销售表现",
  "dataset": "jd",
  "metrics": [
    "gmv",
    "units"
  ],
  "group_by": [
    "product_id"
  ],
  "time": {
    "last_complete_months": 3
  },
  "filters": [
    {
      "field": "product_id",
      "op": "eq",
      "value": "<selected product_id>"
    }
  ]
}
```

### 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.asklear.cn/querying/collection/xhs_search_notes_v1) (`agent.collection.task.xhs_search_notes_v1`)
- [Note detail / 笔记详情](https://docs.asklear.cn/querying/collection/xhs_note_detail_v1) (`agent.collection.task.xhs_note_detail_v1`)
- [Note comments / 笔记评论](https://docs.asklear.cn/querying/collection/xhs_note_comments_v1) (`agent.collection.task.xhs_note_comments_v1`)
- [Comment replies / 评论回复](https://docs.asklear.cn/querying/collection/xhs_comment_sub_comments_v1) (`agent.collection.task.xhs_comment_sub_comments_v1`)
- [User notes / 用户笔记](https://docs.asklear.cn/querying/collection/xhs_user_notes_v1) (`agent.collection.task.xhs_user_notes_v1`)
- [Search videos / 搜索视频](https://docs.asklear.cn/querying/collection/douyin_search_videos_v1) (`agent.collection.task.douyin_search_videos_v1`)
- [Hot search board / 热搜榜](https://docs.asklear.cn/querying/collection/douyin_hot_search_v1) (`agent.collection.task.douyin_hot_search_v1`)
- [Video detail / 视频详情](https://docs.asklear.cn/querying/collection/douyin_video_detail_v1) (`agent.collection.task.douyin_video_detail_v1`)
- [Video comments / 视频评论](https://docs.asklear.cn/querying/collection/douyin_video_comments_v1) (`agent.collection.task.douyin_video_comments_v1`)
- [Author profile / 作者主页](https://docs.asklear.cn/querying/collection/douyin_author_profile_v1) (`agent.collection.task.douyin_author_profile_v1`)
- [Creator posts / 创作者作品](https://docs.asklear.cn/querying/collection/douyin_user_post_videos_v1) (`agent.collection.task.douyin_user_post_videos_v1`)
- [Search videos / 搜索视频](https://docs.asklear.cn/querying/collection/bilibili_search_videos_v1) (`agent.collection.task.bilibili_search_videos_v1`)
- [Video detail / 视频详情](https://docs.asklear.cn/querying/collection/bilibili_video_detail_v1) (`agent.collection.task.bilibili_video_detail_v1`)
- [Video comments / 视频评论](https://docs.asklear.cn/querying/collection/bilibili_video_comments_v1) (`agent.collection.task.bilibili_video_comments_v1`)
- [Author profile / 作者主页](https://docs.asklear.cn/querying/collection/bilibili_author_profile_v1) (`agent.collection.task.bilibili_author_profile_v1`)
- [Status detail / 微博详情](https://docs.asklear.cn/querying/collection/weibo_status_detail_v1) (`agent.collection.task.weibo_status_detail_v1`)
- [Status comments / 微博评论](https://docs.asklear.cn/querying/collection/weibo_status_comments_v1) (`agent.collection.task.weibo_status_comments_v1`)
- [Author profile / 作者主页](https://docs.asklear.cn/querying/collection/weibo_author_profile_v1) (`agent.collection.task.weibo_author_profile_v1`)
- [Search posts / 搜索帖子](https://docs.asklear.cn/querying/collection/weibo_search_posts_v1) (`agent.collection.task.weibo_search_posts_v1`)
- [Article detail / 文章详情](https://docs.asklear.cn/querying/collection/wechat_mp_article_detail_v1) (`agent.collection.task.wechat_mp_article_detail_v1`)
- [Account articles / 账号文章](https://docs.asklear.cn/querying/collection/wechat_mp_account_articles_v1) (`agent.collection.task.wechat_mp_account_articles_v1`)
- [Account profile / 账号资料](https://docs.asklear.cn/querying/collection/wechat_mp_account_profile_v1) (`agent.collection.task.wechat_mp_account_profile_v1`)
- [Article comments / 文章评论](https://docs.asklear.cn/querying/collection/wechat_mp_article_comments_v1) (`agent.collection.task.wechat_mp_article_comments_v1`)
- [Article stats / 文章统计](https://docs.asklear.cn/querying/collection/wechat_mp_article_stats_v1) (`agent.collection.task.wechat_mp_article_stats_v1`)
- [Account services / 账号服务](https://docs.asklear.cn/querying/collection/wechat_mp_account_services_v1) (`agent.collection.task.wechat_mp_account_services_v1`)
- [Comment replies / 评论回复](https://docs.asklear.cn/querying/collection/wechat_mp_comment_replies_v1) (`agent.collection.task.wechat_mp_comment_replies_v1`)
- [Related articles / 关联文章](https://docs.asklear.cn/querying/collection/wechat_mp_related_articles_v1) (`agent.collection.task.wechat_mp_related_articles_v1`)
- [Article ad / 文章广告](https://docs.asklear.cn/querying/collection/wechat_mp_article_ad_v1) (`agent.collection.task.wechat_mp_article_ad_v1`)
- [Search articles / 搜索文章](https://docs.asklear.cn/querying/collection/wechat_search_articles_v2) (`agent.collection.task.wechat_search_articles_v2`)
- [Channel info / 视频号信息](https://docs.asklear.cn/querying/collection/wechat_channel_info_v1) (`agent.collection.task.wechat_channel_info_v1`)
- [Channel id to username / 视频号ID转用户名](https://docs.asklear.cn/querying/collection/wechat_channel_id_to_username_v1) (`agent.collection.task.wechat_channel_id_to_username_v1`)
- [User profile / 用户资料](https://docs.asklear.cn/querying/collection/wechat_channel_user_profile_v1) (`agent.collection.task.wechat_channel_user_profile_v1`)
- [User videos / 用户作品](https://docs.asklear.cn/querying/collection/wechat_channel_user_videos_v1) (`agent.collection.task.wechat_channel_user_videos_v1`)
- [Video detail / 视频详情](https://docs.asklear.cn/querying/collection/wechat_channel_video_detail_v1) (`agent.collection.task.wechat_channel_video_detail_v1`)
- [Video comments / 视频评论](https://docs.asklear.cn/querying/collection/wechat_channel_video_comments_v1) (`agent.collection.task.wechat_channel_video_comments_v1`)
- [Share url / 分享链接](https://docs.asklear.cn/querying/collection/wechat_channel_video_share_url_v1) (`agent.collection.task.wechat_channel_video_share_url_v1`)
- [User collections / 用户合集](https://docs.asklear.cn/querying/collection/wechat_channel_user_collections_v1) (`agent.collection.task.wechat_channel_user_collections_v1`)
- [Collection videos / 合集视频](https://docs.asklear.cn/querying/collection/wechat_channel_collection_videos_v1) (`agent.collection.task.wechat_channel_collection_videos_v1`)
- [Live history / 直播回放](https://docs.asklear.cn/querying/collection/wechat_channel_live_history_v1) (`agent.collection.task.wechat_channel_live_history_v1`)
- [Live detail / 直播详情](https://docs.asklear.cn/querying/collection/wechat_channel_live_detail_v1) (`agent.collection.task.wechat_channel_live_detail_v1`)
- [Search videos / 号内搜索](https://docs.asklear.cn/querying/collection/wechat_channel_search_videos_v1) (`agent.collection.task.wechat_channel_search_videos_v1`)
- [Search posts / 搜索帖子](https://docs.asklear.cn/querying/collection/reddit_search_posts_v1) (`agent.collection.task.reddit_search_posts_v1`)
- [Search media posts / 搜索媒体帖](https://docs.asklear.cn/querying/collection/reddit_search_media_v1) (`agent.collection.task.reddit_search_media_v1`)
- [Search comments / 搜索评论](https://docs.asklear.cn/querying/collection/reddit_search_comments_v1) (`agent.collection.task.reddit_search_comments_v1`)
- [Search subreddits / 搜索版块](https://docs.asklear.cn/querying/collection/reddit_search_communities_v1) (`agent.collection.task.reddit_search_communities_v1`)
- [Search users / 搜索用户](https://docs.asklear.cn/querying/collection/reddit_search_users_v1) (`agent.collection.task.reddit_search_users_v1`)
- [Post detail / 帖子详情](https://docs.asklear.cn/querying/collection/reddit_post_detail_v1) (`agent.collection.task.reddit_post_detail_v1`)
- [Post comments / 帖子评论](https://docs.asklear.cn/querying/collection/reddit_post_comments_v1) (`agent.collection.task.reddit_post_comments_v1`)
- [Comment replies / 评论回复](https://docs.asklear.cn/querying/collection/reddit_comment_replies_v1) (`agent.collection.task.reddit_comment_replies_v1`)
- [Subreddit profile / 版块资料](https://docs.asklear.cn/querying/collection/reddit_subreddit_info_v1) (`agent.collection.task.reddit_subreddit_info_v1`)
- [User profile / 用户资料](https://docs.asklear.cn/querying/collection/reddit_user_profile_v1) (`agent.collection.task.reddit_user_profile_v1`)
- [User posts / 用户帖子](https://docs.asklear.cn/querying/collection/reddit_user_posts_v1) (`agent.collection.task.reddit_user_posts_v1`)
- [User comments / 用户评论](https://docs.asklear.cn/querying/collection/reddit_user_comments_v1) (`agent.collection.task.reddit_user_comments_v1`)
- [Trending searches / 今日热搜](https://docs.asklear.cn/querying/collection/reddit_trending_searches_v1) (`agent.collection.task.reddit_trending_searches_v1`)
- [Search posts / 搜索推文](https://docs.asklear.cn/querying/collection/twitter_search_posts_v1) (`agent.collection.task.twitter_search_posts_v1`)
- [Post detail / 推文详情](https://docs.asklear.cn/querying/collection/twitter_tweet_detail_v1) (`agent.collection.task.twitter_tweet_detail_v1`)
- [Post comments / 推文评论](https://docs.asklear.cn/querying/collection/twitter_post_comments_v1) (`agent.collection.task.twitter_post_comments_v1`)
- [User profile / 用户资料](https://docs.asklear.cn/querying/collection/twitter_user_profile_v1) (`agent.collection.task.twitter_user_profile_v1`)
- [User posts / 用户推文](https://docs.asklear.cn/querying/collection/twitter_user_posts_v1) (`agent.collection.task.twitter_user_posts_v1`)
- [User replies / 用户回复](https://docs.asklear.cn/querying/collection/twitter_user_replies_v1) (`agent.collection.task.twitter_user_replies_v1`)
- [User media / 用户媒体帖](https://docs.asklear.cn/querying/collection/twitter_user_media_v1) (`agent.collection.task.twitter_user_media_v1`)
- [Followers / 粉丝列表](https://docs.asklear.cn/querying/collection/twitter_user_followers_v1) (`agent.collection.task.twitter_user_followers_v1`)
- [Followings / 关注列表](https://docs.asklear.cn/querying/collection/twitter_user_followings_v1) (`agent.collection.task.twitter_user_followings_v1`)
- [Trends / 趋势榜](https://docs.asklear.cn/querying/collection/twitter_trending_v1) (`agent.collection.task.twitter_trending_v1`)
- [Search communities / 搜索社区](https://docs.asklear.cn/querying/collection/twitter_search_communities_v1) (`agent.collection.task.twitter_search_communities_v1`)
- [Search jobs / 搜索职位](https://docs.asklear.cn/querying/collection/linkedin_search_jobs_v1) (`agent.collection.task.linkedin_search_jobs_v1`)
- [Job detail / 职位详情](https://docs.asklear.cn/querying/collection/linkedin_job_detail_v1) (`agent.collection.task.linkedin_job_detail_v1`)
- [Post detail / 帖子详情](https://docs.asklear.cn/querying/collection/linkedin_post_detail_v1) (`agent.collection.task.linkedin_post_detail_v1`)
- [Post comments / 帖子评论](https://docs.asklear.cn/querying/collection/linkedin_post_comments_v1) (`agent.collection.task.linkedin_post_comments_v1`)
- [User profile / 用户资料](https://docs.asklear.cn/querying/collection/linkedin_user_profile_v1) (`agent.collection.task.linkedin_user_profile_v1`)
- [User posts / 用户帖子](https://docs.asklear.cn/querying/collection/linkedin_user_posts_v1) (`agent.collection.task.linkedin_user_posts_v1`)
- [Company profile / 公司资料](https://docs.asklear.cn/querying/collection/linkedin_company_profile_v1) (`agent.collection.task.linkedin_company_profile_v1`)
- [Company posts / 公司帖子](https://docs.asklear.cn/querying/collection/linkedin_company_posts_v1) (`agent.collection.task.linkedin_company_posts_v1`)
- [Product search / 商品搜索](https://docs.asklear.cn/querying/collection/amazon_search_products_v1) (`agent.collection.task.amazon_search_products_v1`)
- [Product detail and sales / 产品详情与销售趋势](https://docs.asklear.cn/querying/collection/amazon_product_detail_v1) (`agent.collection.task.amazon_product_detail_v1`)
- [Product reviews / 商品评论](https://docs.asklear.cn/querying/collection/amazon_product_reviews_v1) (`agent.collection.task.amazon_product_reviews_v1`)
- [Product search / 商品搜索](https://docs.asklear.cn/querying/collection/taobao_product_search_v1) (`agent.collection.task.taobao_product_search_v1`)
- [Product search / 商品搜索](https://docs.asklear.cn/querying/collection/xianyu_product_search_v1) (`agent.collection.task.xianyu_product_search_v1`)
- [Product detail / 商品详情](https://docs.asklear.cn/querying/collection/taobao_product_detail_v6) (`agent.collection.task.taobao_product_detail_v6`)
- [Product detail / 商品详情](https://docs.asklear.cn/querying/collection/xianyu_product_detail_v1) (`agent.collection.task.xianyu_product_detail_v1`)
- [Product questions / 商品问答](https://docs.asklear.cn/querying/collection/taobao_product_questions_v1) (`agent.collection.task.taobao_product_questions_v1`)
- [Shop products / 店铺商品](https://docs.asklear.cn/querying/collection/taobao_shop_products_v4) (`agent.collection.task.taobao_shop_products_v4`)
- [Resolve profile id / 解析主页 ID](https://docs.asklear.cn/querying/collection/facebook_get_profile_id_v1) (`agent.collection.task.facebook_get_profile_id_v1`)
- [Profile posts / 主页帖子](https://docs.asklear.cn/querying/collection/facebook_get_profile_posts_v1) (`agent.collection.task.facebook_get_profile_posts_v1`)
- [Post comments / 帖子评论](https://docs.asklear.cn/querying/collection/facebook_get_post_comments_v1) (`agent.collection.task.facebook_get_post_comments_v1`)
- [Comment replies / 评论回复](https://docs.asklear.cn/querying/collection/facebook_get_comment_replies_v1) (`agent.collection.task.facebook_get_comment_replies_v1`)
- [Product reviews / 商品评价](https://docs.asklear.cn/querying/collection/taobao_product_reviews_v3) (`agent.collection.task.taobao_product_reviews_v3`)
- [Product reviews / 商品评价](https://docs.asklear.cn/querying/collection/jd_product_reviews_v1) (`agent.collection.task.jd_product_reviews_v1`)
- [Web collection / 网页采集](https://docs.asklear.cn/querying/collection/raw_html_v1) (`agent.collection.task.raw_html_v1`)
- [Google/Bing web search / Google/Bing 网页搜索](https://docs.asklear.cn/querying/collection/web_search_v1) (`agent.collection.task.web_search_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 为准。