kolsprite-search

KOLSprite 搜索

通过当前连接，将直接 TikTok 数据请求路由到满足需求的最小调用，该连接需提供兼容的 KOLSprite 工具契约。自动使用 MCP；不要询问是否使用 MCP。

兼容的 MCP 路由

• 如果 SellerSpace Yunya 统一 MCP 可用且已通过身份验证，优先使用它。
• 支持直接业务工具以及当前和旧版 Yunya 门面入口。
• 在直接模式下，按语义业务名称解析并调用所需的类别、创作者、产品、视频或店铺工具。
• 在 Yunya 门面模式下，如果所需业务工具未显示在主机顶层，最多进行一次主机级发现尝试，并优先使用产品专用的 yunya_search_kolsprite_tools。查询所需的最少工具集；使用返回的确切内部工具名称和完整输入架构，然后通过 call_read_tool 调用。
• 如果产品专用入口不可用，但能发现旧版通用 yunya__search_tools，则使用它，并指定 provider kolsprite、operation read 和相同的查询。产品专用入口可用时，不要优先使用通用入口。
• 不要猜测门面命名空间、内部工具名称、包装器、类别值或参数。在整个查询过程中复用已发现的名称和架构。
• 主机级未找到业务工具，并不能证明它不在内部目录中。只有在直接工具不可用，且当前或旧版门面查询均失败后，才能报告依赖缺失。如果无法发现任一门面入口，应报告连接器发现失败，不要改用无关数据源并将其视为等效来源。
• 独立的 KOLSprite MCP 只有在提供相同的所需语义工具名称、输入架构和响应格式时才兼容。
• 如果两个连接都已启用，整个查询只使用一个连接，优先使用 Yunya，并且绝不在两个服务上重复进行付费调用。
• 如果缺少所需工具或其架构不兼容，应报告依赖缺口，并缩小查询范围或停止查询，而不是猜测替代工具。

工具路由

• 创作者类别值解析：如果用户请求创作者内容类别，且当前运行中没有已验证可接受的值，则在调用 creator_search 前先调用 creator_category_list。
• 产品类别 ID 解析：如果当前运行中没有已验证可接受的 ID，则在按类别筛选创作者、产品、视频或店铺搜索之前，先调用 product_category_list。
• 创作者身份、受众规模、互动情况、内容类别、带货活动、联系方式或创作者候选名单：调用 creator_search。
• 产品身份、价格、评分、评论、上架日期、销量、增长、创作者数量或视频数量：调用 product_search。
• 可购物视频的身份、创作者、产品、观看量、互动情况、销量、新近程度或时长：调用 video_search。
• 店铺身份、类型、类别、评分、产品、销量、创作者或视频：调用 shop_search。

只有当用户的直接查询确实需要关联记录时，才使用多个工具。如果下游工具接受已返回的 ID，应复用这些 ID。例如，先调用 shop_search，再使用 shop_id 调用 product_search；或先调用 product_search，再使用 product_id 调用 video_search。

不要声称 creator_search 能识别推广过特定产品的确切创作者：当前公开的创作者工具支持按类别和表现筛选，但不支持按产品 ID 查询关联关系。

类别解析

• 将类别列表工具视为参数解析器，而非面向用户的搜索结果或必需的预检调用。无需类别筛选，或当前运行中已返回有效值时，跳过这些工具。
• 将用户使用中文或英文描述的创作者类别与 creator_category_list 匹配；将返回的 value 传给 creator_search.category_list。
• 遍历递归的 product_category_list 树，并匹配 categoryCn 或 categoryEn；根据适用情况，将返回的完整 category 值传给 product_search.cat_ids、shop_search.category、video_search.product_category_list 或 creator_search.product_category_list。
• 将内容领域或账号定位理解为创作者类别，将销售、推广商品或合作方向理解为商品类别。对于“美妆创作者”这类含义模糊的表达，不要为了规避歧义而同时设置两个类别筛选；应根据请求上下文判断，说明会实质影响结果的假设，或仅在选择会实质改变结果时询问一次。
• 当前搜索架构接受数组，但仅支持一个类别值。选择最窄且无歧义、同时符合用户意图的类别。如果两种可能的映射会实质改变结果，则询问一次；否则使用更宽泛且有效的父类别，并说明这一点。
• 需要有效值或 ID 时，绝不能传入展示标签、编造 ID，或在 Skill 文本中固定实时目录内容。当前运行中成功映射后，应复用该映射。如果解析器不可用或找不到安全匹配项，则省略类别筛选；在有帮助时使用明确标注的关键词限定查询，并说明限制。
• 使用上述语义工具名称。MCP 主机可能会在可调用名称前添加客户端或服务端特定的命名空间；不要硬编码某个 Agent 的前缀。

查询规则

1. 推断明确的筛选条件，例如市场、关键词、类别、价格、粉丝数、互动率、销量、增长、日期、排序和页大小。
2. 如果可选输入的选择不会实质影响答案，则使用工具默认值。说明会实质影响结果的假设。
3. 仅询问必需且无法安全推断的信息。
4. 将用户要求的结果数量转换为满足要求所需的最少分页计划。用户要求“全部”时，使用支持的最大页大小，并持续查询，直到没有下一页、请求范围已穷尽、达到服务限制，或发生错误导致收集停止。
5. 根据稳定的对象 ID 对分页记录去重。报告请求数量、页码范围、原始行数、去重后行数和停止原因。
6. 按用户要求排序。如果实时架构未确认服务端排序值，则仅在明确说明的已收集范围内进行本地排序。
7. 编码百分比增长筛选条件前，检查实时架构或经过验证的官方示例。绝不要猜测 50% 应表示为 50 还是 0.5；如果仍无法确定，则省略该筛选条件并说明限制。
8. 如果初始查询没有结果，在仍能满足用户意图的前提下，放宽一个非必要筛选条件，或尝试一个相近的同义词。报告放宽了什么，不要悄然改变范围。
9. 用户要求的查询或有界比较得到答案后即停止。将面向决策的后续请求交由 tiktok-shop-growth-research 处理。

按点数执行

• 点数消耗遵循当前账户规则下实际执行的工具；选择此 Skill 本身不构成扣费记录。
• 使用满足请求所需的最少调用次数和分页计划，复用已返回的记录；没有说明理由时，不要重复完全相同的付费调用。
• 不要硬编码或估算点数价格。只有当前 MCP 响应或主机客户端明确提供时，才报告扣除点数或剩余余额。
• 点数不足时停止，并标明已完成的页数／行数以及剩余工作。如果超出用户要求范围的扩展会显著增加点数消耗，则在额外使用工具或增加页数前征求用户同意。

错误和未完成的收集

• 遇到身份验证失败、工具不可用、积分或权益不足、速率限制错误或服务器反复故障时，停止受影响的调用链。
• 遇到积分、权益、速率限制或身份验证错误时，绝不要通过更改凭据、规避限制或缩小请求来掩盖中断并重试。
• 将中断的收集标记为未完成，并说明已完成的页面/行数、剩余的请求工作，以及哪些结论仅适用于已收集的样本。
• 绝不要把第一页或受速率限制的收集称为“全部结果”。
• 遇到当前服务器错误、架构不匹配、类别结果为空或稳定 ID 页面疑似重复时，请查阅带日期的已知问题记录。将其作为复测指南，而非历史问题仍在发生的证明。

证据与回复规则

• TikTok 相关事实只能基于当前 MCP 输出。绝不捏造缺失的记录或指标。
• 当来源、市场、筛选条件、排序方式、周期口径、页码和返回的样本量会影响解读时，应标明这些信息。
• 保留字段实际对应的时间窗口。不要把总销量或未注明周期的销量重新标注为 7 天或 30 天销量。
• 区分 MCP 字段和客户端计算结果。对于任何计算得出的比率、排名或集中度，都应展示公式或用通俗语言说明计算方法。
• 在核实关键词匹配结果与产品/类别的相关性之前，应将其视为候选项。
• 结果为空时，应表述为“在这些条件下未返回记录”，而非证明该对象或市场不存在。
• 有帮助时使用返回的对象链接。不要编造 TikTok 或 KOLSprite 网址。
• 先给出结果或候选清单；除非次要维度会影响用户决策，否则不要加入这些内容。
• 对于分析类请求，结尾应给出按优先级排序的行动、支持该行动的证据、要观察的指标，以及复核或停止条件。用户未要求行动计划时，不要为简单查询附加行动计划。
• 对于可复用的分析运行或面向合作伙伴的示例，应采用共享的运行证据展示规范，且不要将查询执行描述为经过衡量的客户成果。