--- document_id: agent.querying schema_version: 2 parent_document_id: agent.guide section: querying --- # 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 expose only Asklear's public fields and Credits. 以 tools/list 作为权威工具面并走最短安全路径：已知精确引用或已解析值直接 query_metrics，商品名称或标题先用 search_products，未解析的品牌、店铺或品类先用 search_values。connection_status 免费且不是心跳，只检查 Asklear 连接。远程 data MCP、异步采集和本地浏览器 MCP 分开。解释 Asklear 计费 metadata，只输出 Asklear 公开字段和 Credits。 ## Agent social workflow / Agent 社媒任务流程 - Use this path only when authenticated `discover` lists a published and authorized social `operation_id` for the current region. Static examples do not grant access; availability and production readiness come from the current discovery response. 仅当认证后的 `discover` 列出当前区域已发布且有权使用的社媒 `operation_id` 时走此路径。静态示例不授予权限，也不代表来源路线或生产验收已完成。 - Use the discovered input schema with `run` and a stable `idempotency_key`. A covering server-side BudgetGrant enters `queued`; otherwise `run` returns `awaiting_approval` and a bound, with no execution, reservation, or charge. After approval, retry the same operation, input, and key. 按发现的入参 schema 调用 `run`，使用稳定的 `idempotency_key`。服务端 BudgetGrant 覆盖时进入 `queued`；否则返回 `awaiting_approval` 与费用上界，审批前不外呼、不预留、不收费。获批后用原 operation、入参和键重试。 - For controlled programmatic submissions, use `wait_seconds=0`. When `run` returns a task reference, read status and results with `task` after `poll_after_seconds`; saved results are free to read. Use `cancel` for work not yet executed; never automatically replay an unknown execution outcome. 程序化受控提交可用 `wait_seconds=0`。`run` 返回任务引用时，按 `poll_after_seconds` 用 `task` 读取状态和结果；已保存结果免费读回。用 `cancel` 取消未执行部分；执行结果未知时不得自动重采。 - For supported social searches, request one platform at a time; the default is three pages with details off. Request details only when supported and explicitly approved. Historical dataset queries keep their existing Data API path. 对已支持的社媒搜索，一次只请求一个平台；默认三页且不补详情。只有能力支持并明确获批时才请求详情。历史数据集查询继续走既有 Data API 路径。 ## 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 / 规则 > The Collection rule below applies only to legacy tools; eligible Agent social work follows the discover/run/task path above. / 下方 Collection 规则仅适用于旧工具；符合条件的 Agent 社媒任务按上方 discover/run/task 流程执行。 - 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 时必须停止并让用户确认候选；若查询后才发现歧义，需明确告知实际使用的平台原始值。 - When search_values fails with query_too_broad, do not retry with narrower keywords; the leading-wildcard scan does not shrink. Align through query_metrics instead: for one single month, group_by the target field with a contains filter on it (works for brand, shop, and every category_lN; scan-priced, so set max_credits or quote first), or drill the tree with eq filters level by level (group_by category_l1, then lower levels under eq filters on resolved upper levels); search_products / query_details on a representative product can also reverse-resolve exact values. search_values 返回 query_too_broad 时不得换更具体的关键词重试（前缀通配扫描量不随关键词变化）。改用 query_metrics 对齐：单月 group_by 目标字段并用 contains 过滤（brand、shop 与各级 category_lN 均适用；按扫描计费，先用 quote/dry_run 或设置 max_credits），或用 eq 过滤逐级下钻品类树（先 group_by category_l1，再以已解析上层品类 eq 过滤下层）；代表商品的 search_products / query_details 亦可反查精确值。 - 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 private source fields or fee details. 只请求足以回答问题的最小指标。Asklear 计费 metadata 只解释返回的口径、水位、upper_bound_credits 和 charged_credits；不得请求或转述内部来源字段或费用细节。 - Native HTTP follows each published method, path and version-specific input schema. Its data contains the complete sanitized business response, including available full text, nested fields and null values; raw and need_format may change that layout. Use meta.credits_charged for the actual charge. Synthetic offline examples describe structure, not live availability or a price quote. Saved result reads keep their original contract and do not execute or charge again. Native HTTP 按每项已发布的 method、path 和对应版本 input schema 调用。data 保留完整脱敏业务响应，包括实际提供的完整正文、嵌套字段与 null；raw、need_format 可能改变结构。实际费用读取 meta.credits_charged。离线合成示例说明结构，不代表线上可用性或价格报价；已保存结果按原合同读回，不重复执行或扣费。 - When Native HTTP publishes meta.next_input, copy its complete non-null object into the next request's input and use a new Idempotency-Key and budget; null means no validated next page is provided. Do not substitute a raw response token for that cursor contract. If the field is absent, follow that operation's published pagination inputs. An unavailable HTTP version is not permission to switch versions or create an Agent Task. Native HTTP 发布 meta.next_input 时，把非 null 的完整对象复制为下一页请求的 input，使用新的 Idempotency-Key 与预算；null 表示未提供经校验的下一页。不要用原始响应 token 替代该游标合同；没有该字段时按该操作已发布的分页参数调用。某 HTTP 版本不可用不代表可以切换版本或创建 Agent Task。 - 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 就读取，没有则在新尝试前询问。 ### Request quotas and concurrency / 请求配额与并发 - Every configured API-key and shared tenant limit applies: RPM counts requests per minute, optional RPS counts requests per second, daily and billing-period quotas count accepted requests, and concurrency limits in-flight HTTP/MCP calls. Async Task submissions release HTTP concurrency when the call ends; worker capacity remains separate. API Key 和租户共享的所有已配置限额同时生效：RPM 为每分钟请求数，可选 RPS 为每秒请求数，每日及账期配额统计准入请求数，并发限制进行中的 HTTP/MCP 调用。异步 Task 提交在调用结束时释放 HTTP 并发，worker 容量独立管理。 - Defaults follow the actual subscription SKU. Admin tenant overrides and then key overrides replace inherited key values, within system caps; tenant aggregate limits still apply independently. A null override restores inheritance; a null plan default disables that dimension. Overrides may raise plan limits within system caps. 默认值来自实际订阅 SKU。管理员租户覆盖、再到 Key 覆盖可替换继承的 Key 限额，但不得超过系统硬上限；租户聚合限额仍独立生效。override 为 null 表示恢复继承，套餐默认值为 null 表示关闭该维度。管理员覆盖可在硬上限内提高套餐限额。 - Daily quotas reset at midnight in the account billing timezone. Monthly quotas use the current subscription billing period; accounts without a subscription use the billing-timezone calendar month. Buying several months does not combine them into one request-quota period. 每日配额按账户 billing timezone 的自然日重置。月度配额采用当前订阅账期；无订阅账户按该时区的自然月计算。购买多个月份不代表将其合并为一个请求配额账期。 - Rate, quota and concurrency rejections consume no daily or billing-period request quota. An admitted request counts once even if later business work fails. Request quotas are separate from Credits, wallet balances and prices; provider QPS and worker execution permits also remain independent. 速率、次数或并发拒绝不消耗每日及账期请求配额；准入后即计一次请求，即使后续业务失败。请求配额独立于 Credits、钱包和价格；Provider QPS 与 worker execution permit 也各自独立。 - Dashboard shows the effective limits read-only, keeps the real commercial plan name and labels Admin customization separately. Request-limit writes require Admin access; existing Credits self-service controls are separate. Dashboard 只读展示生效限额，保留真实商业套餐名，另标注管理员定制限额。请求限额仅允许管理员修改，原有 Credits 自助控制独立保留。 - Customer-limit 429 responses use rate_limited or concurrency_limited. error.metric is rpm, rps, daily_quota, monthly_quota, api_key_concurrency or tenant_concurrency. Honor Retry-After in seconds. X-RateLimit-Limit identifies the exhausted limit, X-RateLimit-Remaining is zero and X-RateLimit-Reset is a UTC Unix timestamp for the window end or suggested concurrency retry time. If admission cannot be verified, the service returns 503. 客户限额 429 使用 rate_limited 或 concurrency_limited，error.metric 为 rpm、rps、daily_quota、monthly_quota、api_key_concurrency 或 tenant_concurrency。遵守以秒为单位的 Retry-After；X-RateLimit-Limit 表示触发的限额，X-RateLimit-Remaining 为 0，X-RateLimit-Reset 为窗口结束或并发建议重试时刻的 UTC Unix 时间戳。无法确认准入时返回 503。 ### 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; private source fields and fee details are never public output. 用通俗语言解释 Asklear 计费 metadata（scope_summary、data_through、upper_bound_credits、charged_credits）；内部来源字段和费用细节永不作为公开输出。 ## 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": "" } ] } ``` ### 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": "", "idempotency_key": "web-research-1" } ``` `get_collection_job` ```json { "task_query": "获取示例网页内容并用于当前研究任务", "job_id": "" } ``` ## Asynchronous collection / 异步采集 > Legacy Collection compatibility / 旧 Collection 兼容 Legacy Collection workflow for public URLs and unmigrated Collection tasks; use it only when those operations are available to your account. 旧 Collection 流程适用于公开 URL 和尚未迁移的采集任务；仅在当前账号可用时使用。 > Use these legacy Collection tools only when they appear in the current tools/list response; they are not the default path for eligible Agent social tasks. > 仅当当前 tools/list 返回旧 Collection 工具时才使用；已具备统一能力的 Agent 社媒任务默认不走此路径。 ### 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.kleardata.ai/zh/querying/collection/xhs_search_notes_v1) (`agent.collection.task.xhs_search_notes_v1`) - [Note detail / 笔记详情](https://docs.kleardata.ai/zh/querying/collection/xhs_note_detail_v1) (`agent.collection.task.xhs_note_detail_v1`) - [Note comments / 笔记评论](https://docs.kleardata.ai/zh/querying/collection/xhs_note_comments_v1) (`agent.collection.task.xhs_note_comments_v1`) - [Comment replies / 评论回复](https://docs.kleardata.ai/zh/querying/collection/xhs_comment_sub_comments_v1) (`agent.collection.task.xhs_comment_sub_comments_v1`) - [User notes / 用户笔记](https://docs.kleardata.ai/zh/querying/collection/xhs_user_notes_v1) (`agent.collection.task.xhs_user_notes_v1`) - [Search videos / 搜索视频](https://docs.kleardata.ai/zh/querying/collection/douyin_search_videos_v1) (`agent.collection.task.douyin_search_videos_v1`) - [Hot search board / 热搜榜](https://docs.kleardata.ai/zh/querying/collection/douyin_hot_search_v1) (`agent.collection.task.douyin_hot_search_v1`) - [Video detail / 视频详情](https://docs.kleardata.ai/zh/querying/collection/douyin_video_detail_v1) (`agent.collection.task.douyin_video_detail_v1`) - [Video comments / 视频评论](https://docs.kleardata.ai/zh/querying/collection/douyin_video_comments_v1) (`agent.collection.task.douyin_video_comments_v1`) - [Author profile / 作者主页](https://docs.kleardata.ai/zh/querying/collection/douyin_author_profile_v1) (`agent.collection.task.douyin_author_profile_v1`) - [Creator posts / 创作者作品](https://docs.kleardata.ai/zh/querying/collection/douyin_user_post_videos_v1) (`agent.collection.task.douyin_user_post_videos_v1`) - [Search videos / 搜索视频](https://docs.kleardata.ai/zh/querying/collection/bilibili_search_videos_v1) (`agent.collection.task.bilibili_search_videos_v1`) - [Video detail / 视频详情](https://docs.kleardata.ai/zh/querying/collection/bilibili_video_detail_v1) (`agent.collection.task.bilibili_video_detail_v1`) - [Video comments / 视频评论](https://docs.kleardata.ai/zh/querying/collection/bilibili_video_comments_v1) (`agent.collection.task.bilibili_video_comments_v1`) - [Author profile / 作者主页](https://docs.kleardata.ai/zh/querying/collection/bilibili_author_profile_v1) (`agent.collection.task.bilibili_author_profile_v1`) - [Status detail / 微博详情](https://docs.kleardata.ai/zh/querying/collection/weibo_status_detail_v1) (`agent.collection.task.weibo_status_detail_v1`) - [Status comments / 微博评论](https://docs.kleardata.ai/zh/querying/collection/weibo_status_comments_v1) (`agent.collection.task.weibo_status_comments_v1`) - [Author profile / 作者主页](https://docs.kleardata.ai/zh/querying/collection/weibo_author_profile_v1) (`agent.collection.task.weibo_author_profile_v1`) - [Search posts / 搜索帖子](https://docs.kleardata.ai/zh/querying/collection/weibo_search_posts_v1) (`agent.collection.task.weibo_search_posts_v1`) - [Article detail / 文章详情](https://docs.kleardata.ai/zh/querying/collection/wechat_mp_article_detail_v1) (`agent.collection.task.wechat_mp_article_detail_v1`) - [Account articles / 账号文章](https://docs.kleardata.ai/zh/querying/collection/wechat_mp_account_articles_v1) (`agent.collection.task.wechat_mp_account_articles_v1`) - [Account profile / 账号资料](https://docs.kleardata.ai/zh/querying/collection/wechat_mp_account_profile_v1) (`agent.collection.task.wechat_mp_account_profile_v1`) - [Article comments / 文章评论](https://docs.kleardata.ai/zh/querying/collection/wechat_mp_article_comments_v1) (`agent.collection.task.wechat_mp_article_comments_v1`) - [Article stats / 文章统计](https://docs.kleardata.ai/zh/querying/collection/wechat_mp_article_stats_v1) (`agent.collection.task.wechat_mp_article_stats_v1`) - [Account services / 账号服务](https://docs.kleardata.ai/zh/querying/collection/wechat_mp_account_services_v1) (`agent.collection.task.wechat_mp_account_services_v1`) - [Comment replies / 评论回复](https://docs.kleardata.ai/zh/querying/collection/wechat_mp_comment_replies_v1) (`agent.collection.task.wechat_mp_comment_replies_v1`) - [Related articles / 关联文章](https://docs.kleardata.ai/zh/querying/collection/wechat_mp_related_articles_v1) (`agent.collection.task.wechat_mp_related_articles_v1`) - [Article ad / 文章广告](https://docs.kleardata.ai/zh/querying/collection/wechat_mp_article_ad_v1) (`agent.collection.task.wechat_mp_article_ad_v1`) - [Search articles / 搜索文章](https://docs.kleardata.ai/zh/querying/collection/wechat_search_articles_v2) (`agent.collection.task.wechat_search_articles_v2`) - [Channel info / 视频号信息](https://docs.kleardata.ai/zh/querying/collection/wechat_channel_info_v1) (`agent.collection.task.wechat_channel_info_v1`) - [Channel id to username / 视频号ID转用户名](https://docs.kleardata.ai/zh/querying/collection/wechat_channel_id_to_username_v1) (`agent.collection.task.wechat_channel_id_to_username_v1`) - [User profile / 用户资料](https://docs.kleardata.ai/zh/querying/collection/wechat_channel_user_profile_v1) (`agent.collection.task.wechat_channel_user_profile_v1`) - [User videos / 用户作品](https://docs.kleardata.ai/zh/querying/collection/wechat_channel_user_videos_v1) (`agent.collection.task.wechat_channel_user_videos_v1`) - [Video detail / 视频详情](https://docs.kleardata.ai/zh/querying/collection/wechat_channel_video_detail_v1) (`agent.collection.task.wechat_channel_video_detail_v1`) - [Video comments / 视频评论](https://docs.kleardata.ai/zh/querying/collection/wechat_channel_video_comments_v1) (`agent.collection.task.wechat_channel_video_comments_v1`) - [Share url / 分享链接](https://docs.kleardata.ai/zh/querying/collection/wechat_channel_video_share_url_v1) (`agent.collection.task.wechat_channel_video_share_url_v1`) - [User collections / 用户合集](https://docs.kleardata.ai/zh/querying/collection/wechat_channel_user_collections_v1) (`agent.collection.task.wechat_channel_user_collections_v1`) - [Collection videos / 合集视频](https://docs.kleardata.ai/zh/querying/collection/wechat_channel_collection_videos_v1) (`agent.collection.task.wechat_channel_collection_videos_v1`) - [Live history / 直播回放](https://docs.kleardata.ai/zh/querying/collection/wechat_channel_live_history_v1) (`agent.collection.task.wechat_channel_live_history_v1`) - [Live detail / 直播详情](https://docs.kleardata.ai/zh/querying/collection/wechat_channel_live_detail_v1) (`agent.collection.task.wechat_channel_live_detail_v1`) - [Search videos / 号内搜索](https://docs.kleardata.ai/zh/querying/collection/wechat_channel_search_videos_v1) (`agent.collection.task.wechat_channel_search_videos_v1`) - [Search posts / 搜索帖子](https://docs.kleardata.ai/zh/querying/collection/reddit_search_posts_v1) (`agent.collection.task.reddit_search_posts_v1`) - [Search media posts / 搜索媒体帖](https://docs.kleardata.ai/zh/querying/collection/reddit_search_media_v1) (`agent.collection.task.reddit_search_media_v1`) - [Search comments / 搜索评论](https://docs.kleardata.ai/zh/querying/collection/reddit_search_comments_v1) (`agent.collection.task.reddit_search_comments_v1`) - [Search subreddits / 搜索版块](https://docs.kleardata.ai/zh/querying/collection/reddit_search_communities_v1) (`agent.collection.task.reddit_search_communities_v1`) - [Search users / 搜索用户](https://docs.kleardata.ai/zh/querying/collection/reddit_search_users_v1) (`agent.collection.task.reddit_search_users_v1`) - [Post detail / 帖子详情](https://docs.kleardata.ai/zh/querying/collection/reddit_post_detail_v1) (`agent.collection.task.reddit_post_detail_v1`) - [Post comments / 帖子评论](https://docs.kleardata.ai/zh/querying/collection/reddit_post_comments_v1) (`agent.collection.task.reddit_post_comments_v1`) - [Comment replies / 评论回复](https://docs.kleardata.ai/zh/querying/collection/reddit_comment_replies_v1) (`agent.collection.task.reddit_comment_replies_v1`) - [Subreddit profile / 版块资料](https://docs.kleardata.ai/zh/querying/collection/reddit_subreddit_info_v1) (`agent.collection.task.reddit_subreddit_info_v1`) - [User profile / 用户资料](https://docs.kleardata.ai/zh/querying/collection/reddit_user_profile_v1) (`agent.collection.task.reddit_user_profile_v1`) - [User posts / 用户帖子](https://docs.kleardata.ai/zh/querying/collection/reddit_user_posts_v1) (`agent.collection.task.reddit_user_posts_v1`) - [User comments / 用户评论](https://docs.kleardata.ai/zh/querying/collection/reddit_user_comments_v1) (`agent.collection.task.reddit_user_comments_v1`) - [Trending searches / 今日热搜](https://docs.kleardata.ai/zh/querying/collection/reddit_trending_searches_v1) (`agent.collection.task.reddit_trending_searches_v1`) - [Post detail / 推文详情](https://docs.kleardata.ai/zh/querying/collection/twitter_tweet_detail_v1) (`agent.collection.task.twitter_tweet_detail_v1`) - [Post comments / 推文评论](https://docs.kleardata.ai/zh/querying/collection/twitter_post_comments_v1) (`agent.collection.task.twitter_post_comments_v1`) - [User profile / 用户资料](https://docs.kleardata.ai/zh/querying/collection/twitter_user_profile_v1) (`agent.collection.task.twitter_user_profile_v1`) - [User posts / 用户推文](https://docs.kleardata.ai/zh/querying/collection/twitter_user_posts_v1) (`agent.collection.task.twitter_user_posts_v1`) - [User replies / 用户回复](https://docs.kleardata.ai/zh/querying/collection/twitter_user_replies_v1) (`agent.collection.task.twitter_user_replies_v1`) - [User media / 用户媒体帖](https://docs.kleardata.ai/zh/querying/collection/twitter_user_media_v1) (`agent.collection.task.twitter_user_media_v1`) - [Followers / 粉丝列表](https://docs.kleardata.ai/zh/querying/collection/twitter_user_followers_v1) (`agent.collection.task.twitter_user_followers_v1`) - [Followings / 关注列表](https://docs.kleardata.ai/zh/querying/collection/twitter_user_followings_v1) (`agent.collection.task.twitter_user_followings_v1`) - [Trends / 趋势榜](https://docs.kleardata.ai/zh/querying/collection/twitter_trending_v1) (`agent.collection.task.twitter_trending_v1`) - [Search communities / 搜索社区](https://docs.kleardata.ai/zh/querying/collection/twitter_search_communities_v1) (`agent.collection.task.twitter_search_communities_v1`) - [Search jobs / 搜索职位](https://docs.kleardata.ai/zh/querying/collection/linkedin_search_jobs_v1) (`agent.collection.task.linkedin_search_jobs_v1`) - [Job detail / 职位详情](https://docs.kleardata.ai/zh/querying/collection/linkedin_job_detail_v1) (`agent.collection.task.linkedin_job_detail_v1`) - [Post detail / 帖子详情](https://docs.kleardata.ai/zh/querying/collection/linkedin_post_detail_v1) (`agent.collection.task.linkedin_post_detail_v1`) - [Post comments / 帖子评论](https://docs.kleardata.ai/zh/querying/collection/linkedin_post_comments_v1) (`agent.collection.task.linkedin_post_comments_v1`) - [User profile / 用户资料](https://docs.kleardata.ai/zh/querying/collection/linkedin_user_profile_v1) (`agent.collection.task.linkedin_user_profile_v1`) - [User posts / 用户帖子](https://docs.kleardata.ai/zh/querying/collection/linkedin_user_posts_v1) (`agent.collection.task.linkedin_user_posts_v1`) - [Company profile / 公司资料](https://docs.kleardata.ai/zh/querying/collection/linkedin_company_profile_v1) (`agent.collection.task.linkedin_company_profile_v1`) - [Company posts / 公司帖子](https://docs.kleardata.ai/zh/querying/collection/linkedin_company_posts_v1) (`agent.collection.task.linkedin_company_posts_v1`) - [Product search / 商品搜索](https://docs.kleardata.ai/zh/querying/collection/amazon_search_products_v1) (`agent.collection.task.amazon_search_products_v1`) - [Product detail and sales / 产品详情与销售趋势](https://docs.kleardata.ai/zh/querying/collection/amazon_product_detail_v1) (`agent.collection.task.amazon_product_detail_v1`) - [Product reviews / 商品评论](https://docs.kleardata.ai/zh/querying/collection/amazon_product_reviews_v1) (`agent.collection.task.amazon_product_reviews_v1`) - [Product search / 商品搜索](https://docs.kleardata.ai/zh/querying/collection/taobao_product_search_v1) (`agent.collection.task.taobao_product_search_v1`) - [Product search / 商品搜索](https://docs.kleardata.ai/zh/querying/collection/xianyu_product_search_v1) (`agent.collection.task.xianyu_product_search_v1`) - [Product detail / 商品详情](https://docs.kleardata.ai/zh/querying/collection/taobao_product_detail_v6) (`agent.collection.task.taobao_product_detail_v6`) - [Product detail / 商品详情](https://docs.kleardata.ai/zh/querying/collection/xianyu_product_detail_v1) (`agent.collection.task.xianyu_product_detail_v1`) - [Product questions / 商品问答](https://docs.kleardata.ai/zh/querying/collection/taobao_product_questions_v1) (`agent.collection.task.taobao_product_questions_v1`) - [Shop products / 店铺商品](https://docs.kleardata.ai/zh/querying/collection/taobao_shop_products_v4) (`agent.collection.task.taobao_shop_products_v4`) - [Resolve profile id / 解析主页 ID](https://docs.kleardata.ai/zh/querying/collection/facebook_get_profile_id_v1) (`agent.collection.task.facebook_get_profile_id_v1`) - [Profile posts / 主页帖子](https://docs.kleardata.ai/zh/querying/collection/facebook_get_profile_posts_v1) (`agent.collection.task.facebook_get_profile_posts_v1`) - [Post comments / 帖子评论](https://docs.kleardata.ai/zh/querying/collection/facebook_get_post_comments_v1) (`agent.collection.task.facebook_get_post_comments_v1`) - [Comment replies / 评论回复](https://docs.kleardata.ai/zh/querying/collection/facebook_get_comment_replies_v1) (`agent.collection.task.facebook_get_comment_replies_v1`) - [Product reviews / 商品评价](https://docs.kleardata.ai/zh/querying/collection/taobao_product_reviews_v3) (`agent.collection.task.taobao_product_reviews_v3`) - [Product reviews / 商品评价](https://docs.kleardata.ai/zh/querying/collection/jd_product_reviews_v1) (`agent.collection.task.jd_product_reviews_v1`) - [Web collection / 网页采集](https://docs.kleardata.ai/zh/querying/collection/raw_html_v1) (`agent.collection.task.raw_html_v1`) - [Google/Bing web search / Google/Bing 网页搜索](https://docs.kleardata.ai/zh/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 execution outcome is unconfirmed; this failed task did not charge user Credits and its reservation was released. Do not retry automatically. Read the known job and credits_charged, and ask the user before a new attempt with a new idempotency key. 遇到 collection_external_unknown 时，执行结果无法确认；本次失败任务未扣取用户 Credits，预留已释放。禁止自动重试。先读取已知任务及 credits_charged，再由用户确认是否使用新的幂等键创建新尝试。 ### Errors and access / 错误与权限 - Resolve a terminal error_code with page=agent.error.; fall back to page=agent.errors when absent. 用 page=agent.error. 处理终态错误；页面不存在时回退到 page=agent.errors。 - Runtime tools/list is authoritative for collection access. 采集权限以运行时 tools/list 为准。