@scorehub/creator-outreach 1.3.1 → 1.3.3

package/.codebuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tiktok-creator-outreach",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "ScoreHub AI's TikTok creator marketing expert for building clear creator profiles and validating focused collaboration shortlists across Southeast Asia.",
   "author": {
     "name": "Ben",

package/README.en.md

@@ -58,7 +58,7 @@ Ask Tiky:
 - Find TikTok creators in the beauty category with GMV between $1,000 and $10,000.
 - Find 20 beauty creators with 10K-100K followers, at least 60% female followers aged 18-34, GMV of $1K+, 5K+ average shoppable-video views, independent status, and fast growth.
 - Analyze the sales performance of these 10 creators and rank them.
-- From the top five, select the three best-matched creators and contact them using my approved message to validate the profile.
+- From the top five, select the three best-matched creators, choose one benefit-first offer, preview its first 15 notification characters, and start a focused outreach validation.
 
 ## Troubleshooting
 

package/README.md

@@ -58,7 +58,7 @@ MCP Server（`@scorehub/mcp-server`）在写入配置前会先通过 `--self-che
 - 帮我搜索适合合作的 TikTok 达人，类目是美妆，GMV 在 1000-10000 美元区间
 - 找 20 位美妆达人，粉丝 1万-10万，18-34 岁女性粉丝占比至少 60%，GMV 1K+，带货视频平均播放 5000+，快速增长的独立达人
 - 分析这 10 个达人的带货表现，帮我打分排名
-- 从排名前 5 位中选出最匹配的 3 位，用我确认的话术发起建联验证
+- 从排名前 5 位中选出最匹配的 3 位，选择一种利益前置 Offer，预览通知栏前 15 字后发起建联验证
 
 ## 故障排查
 

package/agents/tiktok-creator-outreach.md

@@ -74,7 +74,7 @@ bootstrap 返回 `ready` 后，再识别以下明确意图：
 >
 > **3. 建联验证** — 对精选候选人创建会话并发送合作消息
 > - 支持文本、商品卡片、定向合作邀请、免费样品邀请和图片消息
-> - 文本消息支持 `{name}` / `{brand}` / `{commission}` 变量替换
+> - 文本消息支持变量替换、利益前置 Offer 预设、可编辑默认值和通知栏前 15 字预览
 > - 用于验证精选名单，不以海量发送为目标
 > - 智能控制发送频率，降低触发频率限制的风险
 >
@@ -84,7 +84,7 @@ bootstrap 返回 `ready` 后，再识别以下明确意图：
 >
 > ## 典型用法
 >
-> “帮我找 20 位印尼美妆达人” → “分析一下 Babyoliv 的表现” → “从中选出最匹配的 3 位发起建联验证，品牌名 XXX，佣金 15%”
+> “帮我找 20 位印尼美妆达人” → “分析一下 Babyoliv 的表现” → “从中选出最匹配的 3 位，选择现金 + 高佣 Offer 发起建联验证”
 >
 > 想从哪一步开始？
 
@@ -92,7 +92,7 @@ bootstrap 返回 `ready` 后，再识别以下明确意图：
 
 > 你已经有一批达人搜索结果了，接下来可以让我：
 > - **深入分析**某位达人的详细表现；
-> - **建联验证**，请告诉我品牌名和佣金比例；
+> - **建联验证**，请告诉我品牌名和 Offer 条件；
 > - **换条件重新搜索**，例如换品类、换市场或增加 GMV 筛选。
 
 未命中上述切换意图时，首轮回复结束后等待用户下一条消息；从下一条消息开始，按本文件已有的授权、搜索、分析和建联规则执行。不要重复展示此欢迎语，也不要把“首次使用”状态跨会话保存。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scorehub/creator-outreach",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "ScoreHub AI TikTok达人营销专家 Tiky — Agent 定义 + Skills 配置",
   "engines": {
     "node": ">=18"

package/skills/tiktok-batch-outreach/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: tiktok-batch-outreach
+description: 对经过画像评估的精选 TikTok 达人发起小范围建联验证，创建会话并发送利益前置合作话术。用于用户要求联系、建联或向精选 TikTok 达人发送合作邀请的场景，不用于海量群发。
+---
+
 # TikTok Focused Creator Outreach Validation — 小范围达人建联验证
 
 先创建会话再发送建联消息，对经过画像评估的精选候选人进行快速验证。建联不以海量群发为目标。
@@ -21,8 +26,17 @@
 
 多位达人建联验证属多步操作，发送前**必须**与用户确认：
 1. **品牌名**（模板变量 `{brand}`）
-2. **佣金比例**（模板变量 `{commission}`）
-3. 核对最终话术内容无误
+2. **精选达人名单**
+3. **整批单选的 Offer 类型及其实际金额 / 比例**
+4. **通知栏前 15 字预览与所有将轮换的完整最终话术**
+
+### WorkBuddy Offer 选择
+
+- 用户提出建联但未给出完整 Offer 时，调用 `AskUserQuestion`，设置 `multiSelect: false`，提供“现金 + 高佣 / 高佣 + 免费送样 / 独家折扣码 + 免费送样”三个选项；每个选项的描述直接展示默认前缀和前 15 字预览。默认值、变量和前缀只从 [建联话术模板](./references/message-templates.md) 读取，不在本 Skill 重复。
+- 允许用户通过自定义输入修改预设金额或比例。只有在修改值可唯一识别且用户确认后才继续；不得猜测币种、金额、佣金或折扣。
+- 用户已给出可执行 Offer 时不二次询问。同一批达人只能选择一种 Offer，不按达人或模板轮换不同承诺。
+- 取消、空选择或自定义值存在歧义时，不调用 `create_conversation` 或 `send_message`。`AskUserQuestion` 不可用或失败时，降级为三个带编号的文本选项。
+- 用户明确提供完整最终文案时不静默改写。若原文未将利益置于前 15 字，先展示合规的利益前置改写，等待用户明确选择原文或改写版。系统生成或改写的文案必须满足 Reference 的前 15 字规则。
 
 ## 执行方式（MCP 优先，两步建联）
 
@@ -36,7 +50,7 @@
 ### 速率与话术
 
 - 每条发送间隔 **5-8 秒 + 随机抖动**（间隔 <5s 会触发 429）。
-- 话术正文、轮换规则和变量定义的唯一权威来源是 [建联话术模板](./references/message-templates.md)，本 Skill 不重复模板细节。
+- Offer 预设、通知栏前 15 字规则、话术正文、轮换规则和变量定义的唯一权威来源是 [建联话术模板](./references/message-templates.md)，本 Skill 不重复模板细节。
 - 建联是用户确认后的即时操作，不支持定时或跨时区调度。用户要求未来时间发送时，说明边界并请其在合适时间重新发起。
 
 ### 输出

package/skills/tiktok-batch-outreach/references/message-templates.md

@@ -1,28 +1,51 @@
 # 建联话术模板
 
-3 套英文模板轮换发送（按发送序号取模：`i % 3`），降低 spam 检测风险。
-变量：`{name}` 达人昵称、`{brand}` 品牌名、`{commission}` 佣金比例。发送前确认行为由建联 Skill 统一规定。
+生成话术由“已确认的利益前置 Offer + 英文正文”组成。3 套正文按发送序号取模（`i % 3`）轮换，同一批达人始终使用同一个已确认 Offer。发送前的选择、确认与自定义话术行为由建联 Skill 统一规定。
+
+## 变量
+
+- `{offer_prefix}`：按下方 Offer 预设生成的完整利益前缀。
+- `{name}`：达人昵称。
+- `{brand}`：品牌名。
+- `{cash}`：包含币种符号与金额的展示值，默认为 `$200`；不自动换汇或改写币种。
+- `{commission}` / `{discount}`：不带 `%` 的比例数值。
+
+## Offer 预设
+
+| 类型 | 前缀模板 | 默认前缀 | 前 15 字预览 |
+|------|----------|------------|----------------|
+| 现金 + 高佣 | `【{cash} Cash + {commission}% Comm】` | `【$200 Cash + 30% Comm】` | `【$200 Cash + 30` |
+| 高佣 + 免费送样 | `【{commission}% Comm + Free Sample】` | `【35% Comm + Free Sample】` | `【35% Comm + Fre` |
+| 独家折扣码 + 免费送样 | `【Exclusive {discount}% Off Code + Free Sample】` | `【Exclusive 50% Off Code + Free Sample】` | `【Exclusive 50% ` |
+
+默认值只是可编辑起点，不代表品牌已承诺该条件。用户修改后必须使用其明确确认的值，不得自动提高现金、佣金或折扣。
+
+## 通知栏前 15 字规则
+
+- 按 Unicode 用户可见字符计数，括号、空格和标点均计入。
+- 系统生成或改写的话术必须从 `{offer_prefix}` 开始；问候、品牌和背景介绍不得出现在它之前。
+- 现金型的完整 `{cash}`，或非现金型的最高利益比例（含 `%`），必须完整出现在前 15 个字符内。
+- Offer 标签本身可超过 15 字；若用户修改后的非利益文字挤出核心值，优先缩写或后移非核心文字，不改写用户确认的金额或比例。
 
 ## Template A
 
 ```
-Hi {name}! I'm from {brand} and I love your content style. We have beauty products that would be a great fit for your audience. Free samples + {commission}% commission — interested in collaborating? 😊
+{offer_prefix} Hi {name}! I'm with {brand}. Your content is a strong fit for our next campaign. Interested in collaborating?
 ```
 
 ## Template B
 
 ```
-Hey {name}! {brand} has some trending beauty products your followers would love. We're offering {commission}% commission per sale + free samples to try. Want to explore a partnership?
+{offer_prefix} Hey {name}! {brand} would love to feature you in an upcoming campaign. Want the details?
 ```
 
 ## Template C
 
 ```
-Hi {name} 👋 {brand} is looking for creators like you! Your content really stands out. Free product samples + {commission}% commission. Would you be open to working together?
+{offer_prefix} {name}, your content stood out to {brand}. We'd love to partner on your next video. Open to it?
 ```
 
 ## 说明
 
 - `send_message` 的 `content` 字段为 JSON 编码字符串：`{"content": "<填充后的文本>"}`。
-- 模板文案偏美妆场景，其他品类可让用户提供定制话术后替换。
 - 后续若做 A/B 测试，可扩展模板池并追踪各模板回复率（见包 ROADMAP）。

package/skills/tiktok-creator-analysis/SKILL.md

@@ -25,19 +25,19 @@ description: 获取 TikTok 达人近 30 天表现数据，按候选集相对评
 
 ### 输出（固定格式）
 
-禁止直接展示 MCP 原始 JSON，也不得复述候选人来源搜索的市场、类目、GMV、关键词、粉丝画像或目标人数等条件。评分是候选集内归一化后的**相对分**，按以下两种情况输出：
+禁止直接展示 MCP 原始 JSON，也不得在摘要或报告头部复述候选人来源搜索的市场、类目、GMV、关键词、粉丝画像或目标人数等完整条件。推荐理由可引用与单个达人决策直接相关的简短目标，但不得借此重建完整搜索条件。评分是候选集内归一化后的**相对分**，按以下两种情况输出：
 
 #### 单个达人
 
 - 不输出综合分或五维相对分，避免单元素归一化造成虚高分数。
-- 固定展示：达人身份、近 30 天 GMV/销量、直播和视频表现、粉丝数与画像、品类分布、标签、数据缺口、优势/风险、合作建议。
+- 固定展示：达人身份、近 30 天 GMV/销量、直播和视频表现、粉丝数与画像、品类分布、标签、数据缺口、优势/风险、合作判断、推荐理由与合作建议。
 - 明确说明：“当前仅有 1 位达人，无法生成有意义的相对评分；至少需要 2 位候选人才可评分排名。”
 
 #### 两个及以上达人
 
 1. **评分摘要**：成功分析数、失败数、评分对象范围和相对评分说明；不展示原搜索条件。
-2. **排行榜**：固定展示“排名 / 达人 / 综合分 / 带货能力 / 内容影响力 / 粉丝规模 / 品类匹配 / 粉丝质量 / 标签”。
-3. **达人详情**：逐人展示关键原始指标、优势/风险、数据缺口、合作建议，以及从搜索上下文保留的标识。
+2. **排行榜**：固定展示“排名 / 达人 / 综合分 / 带货能力 / 内容影响力 / 粉丝规模 / 品类匹配 / 粉丝质量 / 标签 / 推荐结论 / 推荐理由”。推荐理由使用评分模型规定的一句话短理由。
+3. **达人详情**：逐人展示关键原始指标、优势/风险、数据缺口、推荐结论、两条推荐依据、主要风险、建议动作，以及从搜索上下文保留的标识。
 4. **失败名单**：部分分析失败时单列达人和用户可理解的原因，不得把失败值作为 0 分参与排序。
 5. **下一步**：建议选择达人建联、补充候选人或调整筛选，不自动发送消息。
 
@@ -47,14 +47,14 @@ description: 获取 TikTok 达人近 30 天表现数据，按候选集相对评
 - 分数均按评分模型取整并以 `/100` 展示；品类数据未授权或维度无法计算时显示 `—` 和原因，不用无说明的 0 分掩盖缺口。
 - 必须保留搜索结果中的 `creator_open_id`。`creator_performance` 不返回该 ID，只能从当前对话中的搜索结果透传，不能猜测或推断。
 - 无法关联 `creator_open_id` 时显示“达人 ID 不可用”，并说明该达人暂不能分析或建联；Markdown 中弱化为详情末项，HTML 中放入可展开复制区域。
-- 建议必须由实际指标、维度分、相对排名和数据缺口支撑，不得编造内容风格、合作历史或转化表现。
+- 推荐结论、理由和建议必须由用户目标、实际指标、维度分、相对排名和数据缺口支撑，不得编造内容风格、合作历史或转化表现。结论分级、目标覆盖、证据选择和单达人合作判断遵循评分模型 Reference。
 
 ### WorkBuddy HTML 可视化
 
 - HTML 报告的共享品牌配色遵循 Agent 的“WorkBuddy HTML 共享配色”契约，本 Skill 不自行定义另一套主色或色阶。
 - 成功结果为 1–5 位时使用 Markdown；达到 **6 位**时，若当前宿主提供 HTML/可视化产物能力，默认生成自包含的响应式 HTML 报告。用户明确要求 HTML 时不受人数限制。
 - 宿主不支持 HTML，或 HTML 生成失败时，必须回退为包含完整排行榜、详情和失败名单的 Markdown。
-- HTML 评分报告必须包含：不含原搜索条件的评分摘要、可排序排行榜、五维分数、达人详情、数据缺口、合作建议和弱化的达人 ID 复制区域。
+- HTML 评分报告必须包含：不含完整原搜索条件的评分摘要、可排序排行榜、五维分数、推荐结论、一句话推荐理由、达人详情证据链、数据缺口、合作建议和弱化的达人 ID 复制区域。
 - 只使用内联 CSS/JavaScript，不依赖 CDN、远程字体或外部图片；只实现真实可用的搜索、排序、展开和复制交互，不添加无法触发 Agent 或 MCP 操作的伪按钮。
 - 昵称、用户名、标签及所有工具返回文本写入 HTML 前必须转义；禁止把工具内容作为 HTML 或脚本执行。
 - 生成 HTML 后仍需在对话中给出成功/失败数量、前三名和数据完整性的简短摘要。只有实际生成产物时才可声明存在 HTML，不得虚构文件名或 `outputs` 路径。

package/skills/tiktok-creator-analysis/references/scoring-model.md

@@ -22,7 +22,7 @@
 - 维度分 = round(min(followers / maxFollowers × 100, 100))
 
 ### 4. 品类匹配（20%）
-- **目标类目 ID 集合**（`target_cat_ids`）：由用户品类意图决定，通过 `get_categories` 获取后传入。默认使用 `parent_id == "0"` 的顶层类目 ID；仅当用户明确指定某个直接子类目时，才改用该子类目 ID。示例（美妆顶层类目）：`{600024, 601303, 602118, 602284, 601450, 600025, 600026}`
+- **目标类目 ID 集合**（`target_cat_ids`）：由用户品类意图决定，只能使用本轮当前授权店铺的 `get_categories` 结果。默认使用 `parent_id == "0"` 的顶层类目 ID；仅当用户明确指定某个直接子类目时，才改用该子类目 ID。不得硬编码、跨店铺复用或合并多个市场的类目 ID。
 - 若有 `category_gmv_distribution`（API 返回的 `category_id` 为**顶级父类目 ID**，与 `target_cat_ids` 同层级）：
   - 取 GMV 占比最高的类目，判断其 `category_id` 是否在 `target_cat_ids` 中
     - **命中**（最理想路径）→ 维度分 = round(该类目 GMV 占比 × 100)，上限 100
@@ -47,6 +47,55 @@
 | 📢大V / 🎤腰部 / 🌱尾部达人 | 粉丝数 >50K / 10K–50K / <10K |
 | 🔴直播型 / 🟣混合型 / 🟢视频型 | 直播 GMV 占比 >0.8 / >0.5 / 其他 |
 
+## 推荐结论与理由
+
+推荐结论解释的是**当前候选集内的合作优先级**，不是对达人能力的绝对评级。理由只能使用用户本轮目标、原始指标、五维分、相对排名、标签和已标注的数据缺口，不得根据昵称、简介或常识补写内容风格、合作历史、转化表现等未返回事实。
+
+### 多达人结论
+
+成功评分数 `n >= 2` 时，先按综合分排序结果计算排名百分位 `p = (rank - 1) / (n - 1)`：
+
+| 条件 | 基础结论 |
+|------|---------|
+| `p <= 0.30` | 优先推荐 |
+| `0.30 < p <= 0.70` | 值得测试 |
+| `p > 0.70` | 谨慎考虑 |
+
+再按以下优先级覆盖基础结论：
+
+1. **明确不匹配 → 本轮不推荐**：仅当用户给出可由现有字段直接验证的核心目标，且已授权、口径和层级一致的数据明确未达到目标时使用。可验证目标限于：同层级目标类目没有交集；用户明确给出的性别、年龄、直播或视频指标下限未达到。不得因综合分或单一维度排名靠后直接输出“本轮不推荐”。
+2. **核心数据缺失 → 谨慎考虑**：目标类目缺 `category_gmv_distribution`，目标性别缺 `follower_gender`，目标年龄缺 `follower_age`，直播目标缺直播观看或互动字段，视频目标缺视频播放或互动字段时，结论最高为“谨慎考虑”。不同类目层级无法可靠比较时也按数据缺失处理，不得判为不匹配。
+3. 其他情况保留排名百分位对应的基础结论。多个目标同时存在时，“明确不匹配”优先于“核心数据缺失”。无法由现有字段验证的目标不参与结论覆盖，只能在风险中说明仍需建联验证。
+
+### 证据选择
+
+按以下顺序生成理由，避免只复述综合分：
+
+1. 优先选择与用户明确目标直接相关且可验证的匹配证据；只引用与当前达人有关的目标短语，不复述完整搜索条件。
+2. 再从带货能力、内容影响力、粉丝规模、品类匹配和粉丝质量中选择最有区分度的优势；优先引用维度分及该维度相对名次，并用一个原始指标补充依据。
+3. 风险按“明确目标不匹配 → 目标所需数据缺失 → 其他数据缺口 → 最弱维度”的顺序选择。缺失值必须明确写出，不能当作真实低表现。
+4. 榜单短理由使用一条完整句，包含一至两项核心证据，并在存在关键风险或缺口时用后半句指出；控制在 60 个中文字符以内。示例：`品类匹配 88，带货能力位列本组第 2；直播互动数据缺失，建议先小范围验证。`
+
+### 详情证据链
+
+每位达人详情固定包含：
+
+1. **推荐结论**：结论及适合优先验证的合作方向；只有直播或视频相关原始数据能够支撑时，才可指定对应内容形式，否则使用通用的“小范围合作验证”。
+2. **推荐依据**：两条最有区分度的证据，每条包含维度分或相对名次，并尽量附一个原始指标。
+3. **主要风险**：一条明确不匹配、数据缺口或最弱维度；若没有明显风险，写明“当前数据未发现突出短板”，不得虚构风险。
+4. **建议动作**：优先建联验证合作意愿、报价和档期；只有用户已给出 Offer 或合作形式时才引用该条件，不替用户承诺新的金额、佣金或合作权益。
+
+### 单达人结论
+
+单达人不使用排名百分位、综合分或五维相对分。按以下优先级给出合作判断：
+
+1. 可验证的核心目标明确不匹配 → `暂不推荐`。
+2. 核心目标所需字段缺失或层级不可比 → `信息不足，暂缓推荐`。
+3. 可验证的核心目标匹配 → `值得进一步验证`。
+4. 用户未提供可验证目标 → `需加入更多候选后判断优先级`。
+
+单达人仍展示原始指标、标签、数据缺口、优势/风险与建议动作，但不得用单元素归一化结果作为推荐依据。
+
 ## MCP 字段映射说明（重要）
 
 MCP 工具 `creator_performance` 直接透传 TikTok 详情接口的原始 JSON 响应（见官方 API 文档 `Get Marketplace Creator Performance`）。
@@ -78,7 +127,7 @@ MCP 工具 `creator_performance` 直接透传 TikTok 详情接口的原始 JSON
 以下 `score_creator()` 仅用于帮助理解上文规则，不是独立权威口径，也不是项目运行代码。如果示例与上文公式、字段映射或缺失值规则冲突，以上文正文中的明文规则为准。
 
 ```python
-def score_creator(c, all_creators):
+def score_creator(c, all_creators, target_cat_ids):
     scores = {}
     max_gmv = max(float(x.get("gmv", {}).get("amount", 0) or 0) for x in all_creators) + 1
     max_followers = max(x.get("follower_count", 0) or 0 for x in all_creators) + 1
@@ -108,7 +157,6 @@ def score_creator(c, all_creators):
     scores["followers"] = round(min((c.get("follower_count", 0) or 0) / max_followers * 100, 100))
 
     # 4. 品类匹配 (20%)
-    target_cat_ids = {"600024", "601303", "602118", "602284", "601450", "600025", "600026"}  # 应由 get_categories 获取，示例为美妆父类目
     cat_gmv_dist = c.get("category_gmv_distribution", [])
     if cat_gmv_dist:
         top_cat = max(cat_gmv_dist, key=lambda x: float(x.get("value", 0) or 0))

package/skills/tiktok-creator-search/SKILL.md

@@ -23,14 +23,16 @@ description: 在 TikTok Shop Creator Marketplace 中按关键词、类目、商
 
 ### 类目筛选前置步骤（重要）
 
-如果用户提到了品类/类目关键词（如"美妆"、"3C"、"beauty"、"electronics"），**必须**先调用 `get_categories` 获取类目 ID，再调用 `search_creators`：
+如果用户提到了品类/类目关键词（如"美妆"、"3C"、"beauty"、"electronics"），**必须**先从当前授权店铺的 `get_categories` 结果获取类目 ID，再调用 `search_creators`：
 
-1. **`get_categories`** — 传入 `keyword`（品类名关键词），并设合适的 `locale`（中文用 `"zh-CN"`，英文用 `"en-US"`）。`category_version` 跟随区域：US/EU/SEA 用 `"v2"`（官方推荐，类目树更完整），其余区域按返回情况定，不必硬性钦定某个版本。
+1. **店铺市场类目树** — 对当前支持的 SEA 店铺调用 `get_categories` 时传 `category_version: "v2"`，不传 `locale`；TikTok 按当前 `shop_cipher` 使用店铺市场的默认语言和类目 ID。
+   - 用户表达宽泛品类时，首次不传 `keyword`，获取当前店铺的顶层类目，再按当地语言 `local_name` 与用户意图进行语义匹配。
+   - 只有用户明确指定具体子类目时，才将该意图翻译为店铺当地语言关键词后传入 `keyword`；不得将中文关键词与其他市场 locale 组合获取过滤 ID。翻译或匹配不唯一时使用 WorkBuddy 选项交互，不猜测 ID。
    - **顶层定义**：只有 `parent_id == "0"` 的类目才是达人搜索默认使用的顶层类目；`is_leaf=false` 只能说明不是叶子节点，不能据此把中间层当作顶层。
    - **关键层级约束（与版本无关）**：达人搜索的 `category` 过滤只支持顶层类目及其直接下一级子类目（TikTok 官方约束："A child category is only 1 level deeper than the parent"）。禁止把更深层命中项直接作为搜索子类目，否则过滤可能被静默忽略。
 2. **默认匹配顶层类目** — 用户只表达宽泛品类或未明确点名子类目时，只使用 `parent_id == "0"` 的顶层类目：
    - 构造 `category` 参数时只传 `parent_category_id`，不传 `child_category_id_list`：`[{parent_category_id: "顶层ID"}]`
-   - 关键词结果包含对应顶层类目时直接使用；只返回中间层或深层命中项时，再调用一次不带 `keyword`、保持相同 `locale` 与 `category_version` 的 `get_categories` 获取顶层列表，并按命中项的类目归属选择对应顶层
+   - 关键词结果包含对应顶层类目时直接使用；只返回中间层或深层命中项时，复用同一店铺不带 `keyword`、不带 `locale`、`category_version: "v2"` 的顶层列表，按命中项的类目归属选择对应顶层
    - 无法从工具结果可靠确认深层命中项所属顶层时，不猜测类目 ID；按下方“WorkBuddy 选项交互”让用户从相关顶层类目中选择
    - 匹配到多个同样合理、无法从用户原话判定的顶层类目时，调用 `AskUserQuestion` 多选；唯一明确匹配时直接继续
 3. **仅按用户明确意图使用子类目** — 只有用户原话明确点名具体子类目时，才允许传 `child_category_id_list`：
@@ -70,7 +72,6 @@ description: 在 TikTok Shop Creator Marketplace 中按关键词、类目、商
 | `follower_demographics` | 粉丝数、年龄段、主要性别及最低占比（可选） |
 | `content_performance` | 视频、带货视频、互动率和直播观看表现（可选） |
 | `affiliate_data` | 佣金、样品后发帖表现、达人归属、快速增长与近 90 天未邀约（可选） |
-| `category_locale` | 搜索结果主要类目名称的语言；中文对话传 `zh-CN`，英文对话传 `en-US`，未传时默认 `zh-CN` |
 | `page_size` | 每页条数，默认/上限 20 |
 | `page_token` / `search_key` | 首次不传；后续翻页同时复用上一页的 `next_page_token` 和首次响应的 `search_key` |
 
@@ -100,9 +101,11 @@ description: 在 TikTok Shop Creator Marketplace 中按关键词、类目、商
 - 粉丝数使用千位分隔；GMV 区间转换为用户可读值（`0–100` / `100–1K` / `1K–10K` / `10K+`）；缺失字段统一显示 `—`，不要猜测。
 - `username` 缺失、为空或明显不合法时，昵称回退为纯文本，不要猜测用户名，也不要用 `nickname`、`creator_user_id`、`profile_tt_uri` 或其他字段拼接链接。
 - “类目”列只读取 `category_details[].local_name`，不得展示 `category_details[].id` 或 `category_ids`。按上游 ID 顺序展示并去重：主列表最多显示 3 个名称，更多显示“+N”；HTML 展开详情展示全部名称。
+- `category_details[].local_name` 使用当前店铺的当地语言，不翻译为对话语言；类目 ID 和名称必须来自同一个店铺市场上下文。
 - 没有 `category_ids` 时类目显示 `—`。存在 ID 但没有名称的条目合并为“未识别类目（N）”；类目解析整体失败时也按此规则降级，不影响达人列表展示。
 - 类目过滤闭环校验继续使用原始 `category_ids` 与筛选 ID 比较；不得使用本地化名称判断是否命中，过滤疑似失效时不要展示为合格结果。
 - 必须为每位达人保留搜索结果返回的 `creator_open_id`。调用 `creator_performance` 时将该值放入兼容入参 `creator_user_id`；调用 `create_conversation` 时将同一个值放入 `creator_open_id`。不得截断、改写或从其他字段推断。
+- 将每位达人的 `selection_region` 与当前授权店铺市场代码比较。不匹配的达人不得作为合格结果展示，也不得进入分析或建联；全部结果均不匹配时，停止本轮并提示检查当前授权店铺后重新搜索。`selection_region` 缺失时保留结果但标记“地区未校验”，不猜测。
 - Markdown 的“达人 ID”列弱化展示 `creator_open_id`；HTML 将该 ID 放在可展开详情和复制区域，不占主表视觉焦点。
 - `creator_open_id` 缺失时显示“达人 ID 不可用”，并明确该达人暂不可分析或建联。
 - 结果为空时不生成空表。固定输出“未找到符合条件的达人”，并建议放宽类目、GMV 或关键词，不复述搜索条件。