@scorehub/creator-outreach 1.6.0 → 1.8.0

package/.codebuddy-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tiktok-creator-outreach",
-  "version": "1.6.0",
-  "description": "ScoreHub AI's TikTok creator marketing expert for building clear creator profiles and validating focused collaboration shortlists across Southeast Asia and the United States.",
+  "version": "1.8.0",
+  "description": "ScoreHub AI's TikTok creator marketing expert for building clear creator profiles and validating focused collaboration shortlists across 13 markets in Southeast Asia, the United States, and Europe.",
   "author": {
     "name": "Ben",
     "email": "bennyworks@foxmail.com"
@@ -56,6 +56,10 @@
     {
       "en": "United States",
       "zh": "美国"
+    },
+    {
+      "en": "Europe",
+      "zh": "欧洲"
     }
   ],
   "quickPrompts": [

package/README.en.md

@@ -4,6 +4,10 @@ Chinese version: [README.md](./README.md)
 
 **ScoreHub AI TikTok Creator Marketing Expert · Tiky** is ScoreHub AI's creator marketing expert for TikTok Shop sellers. Tiky discovers suitable creators by category, GMV, units sold, follower count and age/gender profile, content performance, and collaboration traits, then combines recent commerce, content, category, and audience data into clear, comparable creator profiles. Sellers can use those profiles to select a focused shortlist and quickly validate collaboration hypotheses through targeted outreach. Tiky is not a mass-messaging tool for contacting thousands of creators. TikTok operations run through ScoreHub MCP, and ScoreHub manages the TikTok API credentials so users do not need to configure them.
 
+## Supported Markets
+
+Tiky currently covers 13 country markets: Indonesia (ID), Thailand (TH), Malaysia (MY), Vietnam (VN), the Philippines (PH), Singapore (SG), the United States (US), the United Kingdom (GB), Germany (DE), Italy (IT), France (FR), Spain (ES), and Ireland (IE). The Agent specification is authoritative for this market boundary.
+
 ## Supported Clients
 
 - WorkBuddy

package/README.md

@@ -4,6 +4,10 @@ English version: [README.en.md](./README.en.md)
 
 **ScoreHub AI TikTok达人营销专家 · Tiky** 是 ScoreHub AI 面向 TikTok Shop 卖家打造的达人营销专家。Tiky 可按类目、GMV、销量、粉丝量级与年龄/性别、内容表现和合作特征发现合适的达人，结合近 30 天带货、内容、品类和受众数据建立清晰可比较的达人画像，并通过精选后的小范围建联快速验证合作假设。Tiky 不是面向成千上万达人的海量群发工具。TikTok 操作通过 ScoreHub MCP 完成，TikTok API 凭证由 ScoreHub 托管，使用者无需配置。
 
+## 支持市场
+
+Tiky 当前覆盖 13 个国家市场：印度尼西亚（ID）、泰国（TH）、马来西亚（MY）、越南（VN）、菲律宾（PH）、新加坡（SG）、美国（US）、英国（GB）、德国（DE）、意大利（IT）、法国（FR）、西班牙（ES）和爱尔兰（IE）。市场边界以 Agent 规范为准。
+
 ## 支持的客户端
 
 - WorkBuddy

package/agents/tiktok-creator-outreach.md

@@ -71,7 +71,7 @@ bootstrap 返回 `ready` 后，再识别以下明确意图：
 > - 带货数据：GMV、销量、客单价
 > - 内容表现：视频数、播放量、互动率
 > - 粉丝画像：年龄与性别分布、市场归属
-> - 单人给出画像与合作建议，2 位及以上可进行 100 分制相对评分排名
+> - 单人或多人均可使用 Rank 返回的分数和排名；评分请求不设人数下限或上限
 >
 > **3. 建联验证** — 对精选候选人创建会话并发送合作消息
 > - 支持文本、商品卡片、定向合作邀请、免费样品邀请和图片消息
@@ -81,7 +81,7 @@ bootstrap 返回 `ready` 后，再识别以下明确意图：
 >
 > ## 支持的市场
 >
-> 东南亚六国及美国：印度尼西亚（ID）、泰国（TH）、马来西亚（MY）、越南（VN）、菲律宾（PH）、新加坡（SG）、美国（US）。
+> 当前覆盖 13 个国家市场：东南亚的印度尼西亚（ID）、泰国（TH）、马来西亚（MY）、越南（VN）、菲律宾（PH）、新加坡（SG），美国（US），以及欧洲的英国（GB）、德国（DE）、意大利（IT）、法国（FR）、西班牙（ES）、爱尔兰（IE）。
 >
 > ## 典型用法
 >
@@ -116,18 +116,18 @@ bootstrap 返回 `ready` 后，再识别以下明确意图：
 
 ### 2. 达人表现分析
 获取达人的近 30 天表现并给出合作判断。
-- 单人输出画像与建议；候选集至少有 2 位达人时才进行相对评分排名。
-- 数据字段、评分模型、缺口处理和结果展示完整遵循 `tiktok-creator-analysis` Skill，不在 Agent 中重复定义。
+- 单人或多人评分都调用 `rank_creators` 使用 Rank 分数和排名；只有纯事实画像请求才单独调用 `creator_performance`。
+- 数据字段、Rank 分数、缺口处理和结果展示完整遵循 `tiktok-creator-analysis` Skill，不在 Agent 中重复定义。
 
 ### 3. 小范围建联验证
 对经过画像评估的精选候选人创建会话并发送建联消息，用于快速验证合作假设，不以海量群发为目标。
 - 发送前确认、会话创建、消息类型、话术、速率和进度展示完整遵循 `tiktok-batch-outreach` Skill，不在 Agent 中重复定义。
 
 ### 4. 相似达人推荐
-以某位达人为模板，通过多路召回和两阶段加权评分找到表现特征相似的其他达人。
+以某位达人为模板，通过多路召回、候选粗排和外部相似度服务找到表现特征相似的其他达人。
 - 输入目标达人的 `creator_open_id`（来自搜索结果的唯一标识），返回按相似度降序排名的 Top-N 推荐列表。
 - 默认返回 20 位相似达人，可按需调整为 1–50。
-- 相似度计算、两阶段评分、召回策略和结果展示完整遵循 `tiktok-similar-creators` Skill，不在 Agent 中重复定义。
+- 外部评分、候选筛选、召回策略和结果展示完整遵循 `tiktok-similar-creators` Skill，不在 Agent 中重复定义。
 
 ## 标准工作流程
 
@@ -152,7 +152,7 @@ Step 3: 小范围建联验证
 不直接展示 MCP 原始 JSON。各能力的详细输入输出契约由对应 Skill 统一维护：
 
 - 搜索参数、选项交互、分页、字段、排序、主页链接与 WorkBuddy HTML 领域规则遵循 `tiktok-creator-search` Skill。
-- 单人画像、多人评分、数据缺口、排名与 WorkBuddy HTML 领域规则遵循 `tiktok-creator-analysis` Skill。
+- 单人或多人 Rank 评分、事实画像、数据缺口、排名与 WorkBuddy HTML 领域规则遵循 `tiktok-creator-analysis` Skill。
 - 建联确认、速率、消息和进度规则遵循 `tiktok-batch-outreach` Skill。
 - 搜索返回的 `creator_open_id` 是分析与建联共用的唯一达人标识，不得丢失、改写或推断。
 - 任何能力都不得编造缺失指标、内容风格、合作历史或不存在的报告产物。
@@ -189,7 +189,7 @@ Step 3: 小范围建联验证
 - `search_creators` — 搜索达人
 - `get_categories` — 获取商品类目树，将品类名称转换为搜索可用的类目 ID
 - `creator_performance` — 获取达人表现；入参名为 `creator_user_id`，值使用搜索结果中的 `creator_open_id`
-- `rank_creators` — 对两位及以上达人进行排序，值使用搜索结果中的 `creator_open_id`
+- `rank_creators` — 对一个或多个达人评分和排序，值使用搜索结果中的 `creator_open_id`
 - `create_conversation` — 创建达人会话（建联前置，用 `creator_open_id`）
 - `send_message` — 发送建联消息
 - `find_similar_creators` — 以目标达人为模板寻找相似达人
@@ -231,7 +231,7 @@ Step 3: 小范围建联验证
 
 ## 限制与注意事项
 
-- **支持市场**：当前支持东南亚及美国市场——泰国（TH）、马来西亚（MY）、越南（VN）、菲律宾（PH）、印度尼西亚（ID）、新加坡（SG）、美国（US）。用户明确提到其他市场（如日本、欧洲等）时，主动说明不支持，并建议改选以上支持的市场之一
+- **支持市场**：当前覆盖 13 个国家市场——泰国（TH）、马来西亚（MY）、越南（VN）、菲律宾（PH）、印度尼西亚（ID）、新加坡（SG）、美国（US）、英国（GB）、德国（DE）、意大利（IT）、法国（FR）、西班牙（ES）、爱尔兰（IE）。用户明确提到其他市场（如日本、加拿大、巴西等）时，主动说明不支持，并建议改选以上支持的市场之一
 - **日配额**：搜索和表现查询共享每日 10,000 次调用限额
 - **限流处理**：如果请求过于频繁或短时间内持续限流，应先等待、分批执行或缩小请求范围；这类问题默认不是授权问题，也不需要为了解除限流去重新授权
 - **建联门槛**：店铺 GMV 需达标，且店铺与达人需在同一区域

package/package.json

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

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

@@ -1,13 +1,13 @@
 ---
 name: tiktok-creator-analysis
-description: 获取 TikTok 达人近 30 天表现数据并完成统一评分排名，以固定 Markdown 或 WorkBuddy HTML 格式展示结果。用于达人表现分析、评分、比较、排名和合作建议请求。
+description: 获取 TikTok 达人近 30 天表现数据，并使用 Rank 返回的分数和排名，以固定 Markdown 或 WorkBuddy HTML 格式展示结果。用于达人表现分析、评分、比较、排名和合作建议请求。
 ---
 
-# TikTok Creator Analysis — 达人表现分析与评分
+# TikTok Creator Analysis — 达人表现分析与 Rank 评分
 
-获取达人近 30 天表现数据，并优先通过统一排序工具完成综合评估与最终排序。
+获取达人近 30 天表现数据，并通过 `rank_creators` 使用 Rank 服务完成一个或多个候选的评分与最终排序。
 
-本文件是达人分析与评分专项行为的权威来源；Agent 只保留能力摘要与跨能力编排。若分析流程、输出或失败处理存在冲突，以本文件为准。
+本文件是达人分析专项行为的权威来源；Agent 只保留能力摘要与跨能力编排。若分析流程、输出或失败处理存在冲突，以本文件为准。
 
 ## 触发条件
 
@@ -19,47 +19,52 @@ description: 获取 TikTok 达人近 30 天表现数据并完成统一评分排
 
 ## 执行方式（MCP 优先）
 
-单个达人仍调用 MCP 工具 **`creator_performance`**，入参名保留为 `creator_user_id`，其值必须直接使用搜索结果中的 `creator_open_id`。两位及以上候选先与用户确认名单，再调用 **`rank_creators`**，传入搜索结果中的 `creator_open_id` 列表。若工具返回非空 `ranking`，严格沿用其顺序；若 `ranking` 为 `null`，则仅使用同一响应中的 `performance_documents`，依据 [评分模型](./references/scoring-model.md) 在 Agent 内完成排序，不得再次调用 `creator_performance` 或 `rank_creators`。该分支只在内部处理，不询问或说明使用了哪种排序实现。评分公式、权重、标签、字段映射和缺失值计算的唯一权威来源仍是该 Reference，本 Skill 不重复其实现细节。
+评分请求无论包含 1 位还是任意数量的候选，都先与用户确认名单（单次明确指定单人时直接执行），再调用 **`rank_creators`**，传入搜索结果中的 `creator_open_id` 列表。Rank 是候选分数、可用性分组和最终顺序唯一权威来源；本 Skill 不计算分数、不重排结果，也不得为同一批候选另行调用 `creator_performance` 代替 Rank。若用户只请求事实画像而未请求评分，才可单独调用 `creator_performance`；入参名保留为 `creator_user_id`，其值必须直接使用搜索结果中的 `creator_open_id`。
+
+`rank_creators` 返回非空 `ranking` 时，严格使用其中 `ranked[].rank` 和 `ranked[].score`。若 `ranking` 为 `null`，只使用同一响应中的 `performance_documents` 展示事实和数据缺口，并明确当前无法完成 Rank 排名；不得按旧版五维评分模型回算或补充分数。
+
+Rank 分数来源、格式和缺失处理以 [Rank 分数契约](./references/scoring-model.md) 为准。本 Skill 不复制其实现细节。
 
 授权、限流、MCP 不可用和本地运行环境恢复遵循 Agent 的权威规则，本技能不重复展开。
 
 ### 输出（固定格式）
 
-禁止直接展示 MCP 原始 JSON，也不得在摘要或报告头部复述候选人来源搜索的市场、类目、GMV、关键词、粉丝画像或目标人数等完整条件。推荐理由可引用与单个达人决策直接相关的简短目标，但不得借此重建完整搜索条件。排名只用于当前候选集内的相对比较，按以下两种情况输出：
+禁止直接展示 MCP 原始 JSON，也不得在摘要或报告头部复述候选人来源搜索的市场、类目、GMV、关键词、粉丝画像或目标人数等完整条件。推荐理由只能引用 Rank 结果和原始 Performance 中实际存在的事实。
 
-#### 单个达人
+#### 一个或多个达人
 
-- 不输出综合分或五维相对分，避免单元素归一化造成虚高分数。
-- 固定展示：达人身份、近 30 天 GMV/销量、直播和视频表现、粉丝数与画像、品类分布、标签、数据缺口、优势/风险、合作判断、推荐理由与合作建议。
-- 明确说明：“当前仅有 1 位达人，无法生成有意义的相对评分；至少需要 2 位候选人才可评分排名。”
+- 评分请求必须调用 `rank_creators`；成功时展示 Rank 返回的 `score`，单人也照常展示，不把它改写成相对分或百分位。
+- 固定展示：达人身份、近 30 天 GMV/销量、直播和视频表现、粉丝数与画像、品类分布、数据缺口、Rank 分数（如有）、优势/风险、合作判断、推荐理由与合作建议。
+- `ranking` 为 `null` 或候选无有效分数时，展示 Performance 事实和数据缺口，并明确当前无法完成 Rank 评分；禁止按旧版五维评分模型回算。
 
-#### 两个及以上达人
+#### 多个达人
 
-1. **评分摘要**：成功分析数、失败数、评分对象范围和相对评分说明；不展示原搜索条件。
-2. **排行榜**：严格按工具顺序展示“排名 / 达人 / 关键表现 / 标签 / 推荐结论 / 推荐理由”，不展示或推断内部排序分数。
-3. **达人详情**：逐人展示关键原始指标、优势/风险、数据缺口、推荐结论、两条推荐依据、主要风险、建议动作，以及从搜索上下文保留的标识。
-4. **失败名单**：部分分析失败时单列达人和用户可理解的原因，不得把失败值作为 0 分参与排序。
-5. **下一步**：建议选择达人建联、补充候选人或调整筛选，不自动发送消息。
+1. **评分摘要**：成功分析数、失败数、Rank 返回的评分对象范围和数据完整性；不展示原搜索条件。
+2. **排行榜**：严格按 Rank 顺序展示“排名 / 达人 / Rank 分数 / 关键表现 / 推荐结论 / 推荐理由”。分数按 Rank 原值展示，不自行归一化、取整或追加 `/100`。
+3. **达人详情**：逐人展示关键原始指标、Rank 分数（如有）、优势/风险、数据缺口、推荐结论、推荐依据、主要风险、建议动作，以及从搜索上下文保留的标识。
+4. **失败名单**：`undisclosed`、`source_failed`、`invalid` 或 Performance 获取失败时单列达人和用户可理解的原因，不得把失败值作为 0 分参与排序。
+5. **Rank 不可用**：`ranking` 为 `null` 时展示 Performance 事实和数据缺口，并说明暂时无法生成统一排名；不执行本地重排。
+6. **下一步**：建议选择达人建联、补充候选人或稍后重试，不自动发送消息。
 
-排序与字段规则：
+### 排序与字段规则
 
-- 有非空 `ranking` 时严格沿用 `rank_creators` 返回的顺序和排名；仅当 `ranking` 为 `null` 时，才按评分模型使用同一响应的 `performance_documents` 完成一次降级排序。
-- 降级时只评分 `acquisition.status = "succeeded"` 且 `payload.code = 0` 的 `payload.data.creator`；其余候选列入失败名单，不得以 0 分参与排序。
-- 除上述降级计算外，Performance 数据只用于事实画像、数据缺口和推荐说明；不得展示或推断内部排序实现、分数或维度。
+- 严格沿用 `rank_creators` 返回的顺序和排名（`ranked[].rank`），不得根据 Performance 数据二次评分或重排。
+- `ranked[].score` 是 Rank 返回的综合分；只展示该字段，不推断分数含义、维度、权重或模型策略。
+- `undisclosed`、`source_failed` 和 `invalid` 没有分数，按原因字段展示，不填零、不补算。
 - 必须保留搜索结果中的 `creator_open_id`。`creator_performance` 不返回该 ID，只能从当前对话中的搜索结果透传，不能猜测或推断。
 - 无法关联 `creator_open_id` 时显示“达人 ID 不可用”，并说明该达人暂不能分析或建联；Markdown 中弱化为详情末项，HTML 中放入可展开复制区域。
-- 推荐结论、理由和建议必须由用户目标、实际指标、相对排名和数据缺口支撑，不得编造内容风格、合作历史或转化表现。目标覆盖、证据选择和单达人合作判断遵循评分模型 Reference。
+- 推荐结论、理由和建议必须由 Rank 顺序、Rank 分数、用户目标、实际指标和数据缺口支撑，不得编造内容风格、合作历史或转化表现。
 
 ### WorkBuddy HTML 可视化
 
 - HTML 报告的共享品牌配色遵循 Agent 的“WorkBuddy HTML 共享配色”契约，本 Skill 不自行定义另一套主色或色阶。
 - 成功结果为 1–5 位时使用 Markdown；达到 **6 位**时，若当前宿主提供 HTML/可视化产物能力，默认生成自包含的响应式 HTML 报告。用户明确要求 HTML 时不受人数限制。
 - 宿主不支持 HTML，或 HTML 生成失败时，必须回退为包含完整排行榜、详情和失败名单的 Markdown。
-- HTML 评分报告必须包含：不含完整原搜索条件的评分摘要、按工具顺序展示的排行榜、推荐结论、一句话推荐理由、达人详情证据链、数据缺口、合作建议和弱化的达人 ID 复制区域。
-- 只使用内联 CSS/JavaScript，不依赖 CDN、远程字体或外部图片；只实现真实可用的搜索、展开和复制交互，不添加无法触发 Agent 或 MCP 操作的伪按钮。
+- HTML 评分报告必须包含：不含完整原搜索条件的评分摘要、按 Rank 顺序展示的排行榜（含 Rank 分数）、推荐结论、一句话推荐理由、达人详情证据链、数据缺口、合作建议和弱化的达人 ID 复制区域。
+- 只使用内联 CSS/JavaScript，不依赖 CDN、远程字体或外部图片；只实现真实可用的搜索、展开和复制交互，不添加本地排序或无法触发 Agent 或 MCP 操作的伪按钮。
 - 昵称、用户名、标签及所有工具返回文本写入 HTML 前必须转义；禁止把工具内容作为 HTML 或脚本执行。
 - 生成 HTML 后仍需在对话中给出成功/失败数量、前三名和数据完整性的简短摘要。只有实际生成产物时才可声明存在 HTML，不得虚构文件名或 `outputs` 路径。
 
 ## 错误处理
 
-分析专属错误分支仅处理候选名单无效、达人当前不可分析、数据缺口导致维度无法计算，以及 `creator_open_id` 无法从搜索上下文透传；其余授权、限流、MCP 可用性与本地环境问题均遵循 Agent 权威规则。
+分析专属错误分支仅处理候选名单无效、达人当前不可分析、Rank 返回的候选数据缺口，以及 `creator_open_id` 无法从搜索上下文透传；其余授权、限流、MCP 可用性与本地运行环境问题均遵循 Agent 权威规则。Rank 请求级失败或响应无有效分数时，不触发旧版本地评分，保留 Performance 事实并提示稍后重试或缩小候选范围。

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

@@ -1,187 +1,40 @@
-# 达人评分模型（100 分制）
+# Rank 分数与达人分析契约
 
-综合评分 = 带货能力×30% + 内容影响力×25% + 粉丝规模×15% + 品类匹配×20% + 粉丝质量×10%。
+本 Reference 记录 `creator-outreach` 消费的 Rank 公共结果边界。Rank 服务负责综合评分、候选可用性分组和最终顺序；本包不再维护或执行旧版五维本地评分公式。
 
-各维度分先在**候选集内归一化**（除以集合内最大值再×100，封顶 100），因此评分是**相对排序**用途，
-需要一批达人一起算才有意义；单个达人无法得到有意义的归一化分。
+## 分数来源
 
-## 各维度算法
+分析调用 `rank_creators` 后，只消费响应中的：
 
-### 1. 带货能力（30%）
-- GMV 分 = min(gmv / maxGmv × 100, 100) × 0.6
-- 销量分 = min(units / maxUnits × 100, 100) × 0.4
-- 维度分 = round(GMV 分 + 销量分)
+- `ranking.ranked[].creator_open_id`
+- `ranking.ranked[].input_index`
+- `ranking.ranked[].rank`
+- `ranking.ranked[].score`
 
-### 2. 内容影响力（25%）
-- 观看分 = min((直播均观看 + 视频均播放) / max总观看 × 100, 100) × 0.5
-- 直播互动分 = min(直播互动率 / max直播互动率 × 100, 100) × 0.3
-- 视频互动分 = min(视频互动率 / max视频互动率 × 100, 100) × 0.2
-- 维度分 = round(三者之和)
+`score` 是 `mcp-remote` 从 Rank 响应提取并归一为 JSON number 的候选综合分。客户端优先读取 Rank 候选的顶层 `score`；兼容 Rank 1.0 响应时读取 `model_output.strategy_score`。`model_output` 中的模型配置、策略标识、权重和其他字段不是公共契约，不得展示或推断。
 
-### 3. 粉丝规模（15%）
-- 维度分 = round(min(followers / maxFollowers × 100, 100))
+分数保持 Rank 的原始数值含义：不自行归一化、取整、乘除比例或追加 `/100`。如果 Rank 使用的量纲或范围未在响应中说明，只显示数值，不为它添加标签或解释。
 
-### 4. 品类匹配（20%）
-- **目标类目 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
-    - **未命中** → 计算分布中所有类目与 `target_cat_ids` 的交集：overlap = 交集类目数 / 分布中类目总数；维度分 = round(overlap × 100)
-- 若无 `category_gmv_distribution` → 维度分记 **null**（标注「品类数据未授权」），不参与品类维度排序
-  - **禁止用 `category_ids` 替代**：该字段是达人发帖产品的**叶子类目 ID**，层级远深于父类目，与 `target_cat_ids`（父类目）直接求交集结果恒为空，会错误地将匹配达人评为零分
+## 顺序与候选状态
 
-### 5. 粉丝质量（10%，示例以美妆女性受众为基准）
-- 女性占比分 = min(female_pct × 100 / 0.8, 100)（female_pct 为小数，>1 时按 /100 归一）
-- 核心年龄分 = min((18-24 + 25-34 + 35-44 占比之和) × 100 / 0.8, 100)
-- 维度分 = round(女性占比分 × 0.5 + 核心年龄分 × 0.5)
+- `ranked` 必须严格按 Rank 返回的顺序展示，`rank` 只用于显示，不得用 Performance 数据重排。
+- `undisclosed` 表示数据未披露，展示 `missing_fields`，不填 0 分。
+- `source_failed` 表示上游数据获取失败，展示安全的 `reason_code` 和可重试状态，不填 0 分。
+- `invalid` 表示候选数据不符合 Rank 契约，展示安全的 `issues`，不得在本地修正后继续评分。
+- 每位候选只能出现在四类结果之一；展示前核对 `summary.input_count` 等于四类数组长度之和。
 
-## 标签体系
+## 分析流程
 
-| 标签 | 触发条件 |
-|------|---------|
-| 💎带货王者 | 带货分 ≥ 80 |
-| 💰有潜力 | 50 ≤ 带货分 < 80 |
-| 🎬内容高手 | 内容分 ≥ 70 |
-| 🎯精准美妆 | 品类分 ≥ 80 |
-| 👩优质粉丝 | 粉丝质量分 ≥ 60 |
-| 📢大V / 🎤腰部 / 🌱尾部达人 | 粉丝数 >50K / 10K–50K / <10K |
-| 🔴直播型 / 🟣混合型 / 🟢视频型 | 直播 GMV 占比 >0.8 / >0.5 / 其他 |
+1. 用户请求评分时，无论确认 1 位还是任意数量达人，都调用 `rank_creators`，直接使用 Rank 的 `rank` 和 `score`；工具只拒绝空列表，不设本地人数上限。
+2. 用户只请求事实画像而未请求评分时，才单独调用 `creator_performance`，并且不生成 Rank 分数。
+3. Rank 返回 `ranking: null`、缺少有效分数或请求级失败时，只展示同一响应中的 Performance 事实和数据缺口，说明当前无法统一排名。
+4. 禁止用 `creator_performance` 替代同一批候选的 Rank 评分，禁止恢复旧版五维公式、标签阈值或百分位结论。
 
 ## 推荐结论与理由
 
-推荐结论解释的是**当前候选集内的合作优先级**，不是对达人能力的绝对评级。理由只能使用用户本轮目标、原始指标、五维分、相对排名、标签和已标注的数据缺口，不得根据昵称、简介或常识补写内容风格、合作历史、转化表现等未返回事实。
+推荐结论不是 Rank 服务之外的第二套评分。只能结合 Rank 排名/分数、用户明确目标、Performance 原始指标和已标注的数据缺口给出：
 
-### 多达人结论
-
-成功评分数 `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`）。
-所有评分所需字段位于 `data.creator.*` 路径下，字段对应关系如下：
-
-| 评分所需 | MCP 返回字段（`data.creator.*`） | 类型 | 使用方式 |
-|---------|------------------------------|------|---------|
-| GMV | `gmv.amount` | string（如 `"3434.23"`） | `parseFloat()` 后使用 |
-| 销量 | `units_sold` | int | 直接用 |
-| 直播观看 | `avg_ec_live_view_count` | int | 直接用 |
-| 视频播放 | `avg_ec_video_play_count` | int | 直接用 |
-| 直播互动率 | `ec_live_engagement_rate` | string（如 `"6000"` = 60%） | `parseFloat() / 100` 换算为百分比小数 |
-| 视频互动率 | `ec_video_engagement_rate` | string（如 `"3000"` = 30%） | `parseFloat() / 100` 换算为百分比小数 |
-| 粉丝性别 | `follower_gender[].key` / `.value` | key 为 string（`"Male"` / `"Female"`，首字母大写），value 为 string 小数（如 `"0.5000"`） | `parseFloat(value)` 后使用；key 比较需兼容大小写 |
-| 粉丝年龄 | `follower_age[].key` / `.value` | key 为 string（如 `"18-23"`），value 为 string 小数（如 `"0.2500"`） | `parseFloat(value)` 后使用 |
-| 品类 GMV 分布 | `category_gmv_distribution[].category_id` / `.value` | category_id 为 string（**顶级父类目 ID**），value 为 string 小数（如 `"0.3035"`） | `parseFloat(value)` 后作为 GMV 占比 |
-| 品类列表 | `category_ids` | string[]（**叶子类目 ID**） | **不用于品类匹配**（与父类目 ID 层级不同，交集恒为空） |
-
-**执行建议**：优先使用上表字段代入完整公式；若某字段缺失（接口未返回），对应子维度记 0 或 null 并**标注数据缺口**：
-- `avg_ec_live_view_count` 或 `avg_ec_video_play_count` 缺失 → 对应观看子分记 0，注明数据缺口
-- `ec_live_engagement_rate` 或 `ec_video_engagement_rate` 缺失 → 对应互动子分记 0，注明数据缺口
-- `follower_gender` 或 `follower_age` 缺失 → 对应粉丝质量子分记 0，注明数据缺口
-- `category_gmv_distribution` 缺失 → 品类匹配维度记 **null**（不参与排序），注明「品类数据未授权」
-
-字段缺失时对应维度**标注数据缺口**，不要静默填 0 造成排序失真。
-
-## 参考实现（Python）
-
-以下 `score_creator()` 仅用于帮助理解上文规则，不是独立权威口径，也不是项目运行代码。如果示例与上文公式、字段映射或缺失值规则冲突，以上文正文中的明文规则为准。
-
-```python
-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
-    max_views = max((x.get("avg_ec_live_view_count", 0) or 0) + (x.get("avg_ec_video_play_count", 0) or 0)
-                    for x in all_creators) + 1
-
-    # 1. 带货能力 (30%)
-    gmv = float(c.get("gmv", {}).get("amount", 0) or 0)
-    units = c.get("units_sold", 0) or 0
-    max_units = max((x.get("units_sold", 0) or 0) for x in all_creators) + 1
-    scores["sales"] = round(min(gmv / max_gmv * 100, 100) * 0.6 + min(units / max_units * 100, 100) * 0.4)
-
-    # 2. 内容影响力 (25%)
-    live_views = c.get("avg_ec_live_view_count", 0) or 0
-    video_plays = c.get("avg_ec_video_play_count", 0) or 0
-    live_eng = float(c.get("ec_live_engagement_rate", 0) or 0)
-    video_eng = float(c.get("ec_video_engagement_rate", 0) or 0)
-    max_live_eng = max(max(float(x.get("ec_live_engagement_rate", 0) or 0) for x in all_creators), 1)
-    max_video_eng = max(max(float(x.get("ec_video_engagement_rate", 0) or 0) for x in all_creators), 1)
-    scores["content"] = round(
-        min((live_views + video_plays) / max_views * 100, 100) * 0.5
-        + min(live_eng / max_live_eng * 100, 100) * 0.3
-        + min(video_eng / max_video_eng * 100, 100) * 0.2
-    )
-
-    # 3. 粉丝规模 (15%)
-    scores["followers"] = round(min((c.get("follower_count", 0) or 0) / max_followers * 100, 100))
-
-    # 4. 品类匹配 (20%)
-    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))
-        if top_cat.get("category_id", "") in target_cat_ids:
-            scores["category"] = round(min(float(top_cat.get("value", 0) or 0) * 100, 100))
-        else:
-            dist_ids = {x.get("category_id", "") for x in cat_gmv_dist}
-            overlap = len(dist_ids & target_cat_ids) / max(len(dist_ids), 1)
-            scores["category"] = round(overlap * 100)
-    else:
-        scores["category"] = None  # 品类数据未授权，不参与排序
-
-    # 5. 粉丝质量 (10%)
-    female_pct = 0
-    for g in c.get("follower_gender", []):
-        if g.get("key", "").lower() == "female":
-            female_pct = float(g.get("value", 0) or 0)
-    q = min((female_pct if female_pct <= 1 else female_pct / 100) * 100 / 0.8, 100)
-    core_age = sum(float(a.get("value", 0) or 0) for a in c.get("follower_age", [])
-                   if a.get("key") in ("18-24", "25-34", "35-44"))
-    scores["follower_quality"] = round(q * 0.5 + min(core_age * 100 / 0.8, 100) * 0.5)
-
-    scores["total"] = round(
-        scores["sales"] * 0.30 + scores["content"] * 0.25 + scores["followers"] * 0.15
-        + (scores["category"] or 0) * 0.20 + scores["follower_quality"] * 0.10
-    )
-    return scores
-```
+- 不得因未知的分数范围自行设定“高分/低分”阈值。
+- 不得把排名靠后直接解释为能力不合格；需要引用可验证的目标不匹配或数据缺口。
+- 不得根据昵称、简介或常识补写内容风格、合作历史或转化表现。
+- 榜单短理由只引用一至两项实际证据；没有足够证据时说明数据不足。

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

@@ -94,7 +94,7 @@ description: 在 TikTok Shop Creator Marketplace 中按关键词、类目、商
 1. **结果摘要**：实际展示数、`total_count`、当前排序、是否还有下一页，以及一行用户可读的“已应用画像”。画像摘要只包含最终实际传入并生效的筛选条件，格式遵循筛选字段 Reference；零条件搜索显示“已应用画像：未设置筛选条件”。
 2. **达人列表**：固定展示“排名 / 昵称 / 用户名 / 粉丝数 / 近 30 天 GMV 区间 / 类目 / 达人 ID”。
 3. **分页状态**：有更多结果且未达到 60 人时，使用“已显示 X / 共 Y；本轮最多展示 60 位达人，还可继续获取最多 Z 位”。没有下一页时使用“已显示全部结果”。达到 60 人且仍有更多结果时，固定说明“本次搜索已达到 60 位达人上限；请调整条件后重新搜索”，不再建议继续翻页。不要向用户展示 `page_token`。
-4. **下一步**：建议分析选中达人、在剩余预算内继续翻页或调整条件；新增建议“选择 2 位及以上达人进行相对评分排名”。必须等待用户明确指定候选人后才调用 `creator_performance`，不要擅自开始批量分析或建联。
+4. **下一步**：建议分析或评分选中达人、在剩余预算内继续翻页或调整条件；新增建议“选择一位或多位达人进行 Rank 评分”。必须等待用户明确指定候选人后才调用分析工具，不要擅自开始批量分析或建联。
 
 格式化规则：
 
@@ -118,7 +118,7 @@ description: 在 TikTok Shop Creator Marketplace 中按关键词、类目、商
 - HTML 报告的共享品牌配色遵循 Agent 的“WorkBuddy HTML 共享配色”契约，本 Skill 不自行定义另一套主色或色阶。
 - 结果为 1–5 条时使用 Markdown 表格。在 **WorkBuddy** 中达到 **6 条**时，必须通过当前宿主的 HTML 产物通道创建自包含的响应式 HTML 报告；用户明确要求 HTML 时不受条数限制。非 WorkBuddy 宿主使用 Markdown。
 - 在 WorkBuddy 中，不得仅因宿主未显式声明 HTML/可视化能力而回退 Markdown。仅当 HTML 产物实际创建失败时，必须回退为包含全部记录的 Markdown，不能只给摘要或丢失达人，并如实说明未生成报告。
-- HTML 搜索报告包含用户可读的“已应用画像”，但不得包含内部字段、枚举、类目 ID、搜索键、分页令牌或目标展示人数；主表类目最多显示 3 个名称和“+N”，展开详情显示全部本地化名称及合并后的“未识别类目（N）”。其余包含返回数/总数/分页状态、可搜索和排序的达人表格、达人详情、达人 ID 复制区域和下一步建议；下一步建议包含“选择 2 位及以上达人进行相对评分排名”。不添加无法调用 Agent 或 MCP 的伪按钮，也不自动开始分析；达到 60 人上限时必须展示上限提示而非继续翻页入口。
+- HTML 搜索报告包含用户可读的“已应用画像”，但不得包含内部字段、枚举、类目 ID、搜索键、分页令牌或目标展示人数；主表类目最多显示 3 个名称和“+N”，展开详情显示全部本地化名称及合并后的“未识别类目（N）”。其余包含返回数/总数/分页状态、可搜索和排序的达人表格、达人详情、达人 ID 复制区域和下一步建议；下一步建议包含“选择一位或多位达人进行 Rank 评分”。不添加无法调用 Agent 或 MCP 的伪按钮，也不自动开始分析；达到 60 人上限时必须展示上限提示而非继续翻页入口。
 - HTML 报告中的昵称链接使用 `<a>` 指向 `https://www.tiktok.com/@{username}`，并带 `target="_blank"` 与 `rel="noopener noreferrer"`；链接文本与 URL 都必须先安全转义/编码。
 - 只使用内联 CSS/JavaScript，不依赖 CDN、远程字体或外部图片；只实现真实可用的搜索、排序、展开和复制交互，不添加无法触发 Agent 或 MCP 操作的伪按钮。
 - 昵称、用户名及所有工具返回文本写入 HTML 前必须转义；禁止把工具内容作为 HTML 或脚本执行。
@@ -136,19 +136,9 @@ description: 在 TikTok Shop Creator Marketplace 中按关键词、类目、商
 
 ## 市场限制
 
-当前仅支持以下东南亚市场：
+支持市场 allowlist 属于共享产品边界，以 Agent“限制与注意事项”中的“支持市场”为唯一权威来源，本 Skill 不重复维护国家表。
 
-| 国家 | 代码 |
-|------|------|
-| 泰国 | TH |
-| 马来西亚 | MY |
-| 越南 | VN |
-| 菲律宾 | PH |
-| 印度尼西亚 | ID |
-| 新加坡 | SG |
-| 美国 | US |
-
-用户在搜索前若明确指定目标市场（如"帮我找日本的达人"），应**立即告知不支持该市场**，并建议用户改选以上支持的市场之一，不要直接调用 `search_creators`。
+用户在搜索前若明确指定目标市场（如“帮我找日本的达人”），先按 Agent 的支持市场判断；不在 allowlist 中时应**立即告知不支持该市场**，并建议用户改选受支持的市场，不要直接调用 `search_creators`。
 
 ## 错误处理
 

package/skills/tiktok-similar-creators/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: tiktok-similar-creators
-description: 以目标达人为模板，通过多路召回和两阶段加权评分寻找表现特征相似的达人，返回按相似度降序排列的 Top-N 推荐列表。用于"找相似达人"、"以他为模板"、"有没有类似的达人"等请求。
+description: 以目标达人为模板，通过多路召回、候选粗排和外部相似度服务寻找表现特征相似的达人，返回按相似度降序排列的 Top-N 推荐列表。用于"找相似达人"、"以他为模板"、"有没有类似的达人"等请求。
 ---
 
 # TikTok Similar Creators — 相似达人推荐
 
-以某位达人为模板，基于多路召回和加权评分找到带货表现特征相似的其他达人。
+以某位达人为模板，基于多路召回和外部相似度评分找到带货表现特征相似的其他达人。
 
 本文件是相似达人推荐专项行为的权威来源；Agent 只保留能力摘要。若执行流程、输出或失败处理存在冲突，以本文件为准。
 
@@ -25,9 +25,9 @@ description: 以目标达人为模板，通过多路召回和两阶段加权评
 |------|------|--------|------|
 | `creator_user_id` | ✅ | — | 目标达人的 `creator_open_id`，只能来自当前对话上下文中的搜索结果，不可编造 |
 | `top_n` | ❌ | 20 | 返回数量（1–50） |
-| `include_reasoning` | ❌ | true | 是否包含各维度相似度得分 |
+| `include_reasoning` | ❌ | true | 是否包含外部服务返回的相似度 breakdown |
 
-相似度模型、召回策略、权重和标签规则的唯一权威来源是 [相似达人推荐模型](./references/similarity-model.md)，本 Skill 不重复其实现细节。
+相似度服务接口、评分流程、召回策略和标签规则的唯一权威来源是 [相似达人推荐模型](./references/similarity-model.md)，外部服务请求字段以仓库顶层的 [达人相似度服务调用说明](../../../../creator-similarity-api.md) 为准；本 Skill 不重复实现细节。
 
 授权、限流、MCP 不可用和本地运行环境恢复遵循 Agent 的权威规则，本技能不重复展开。
 
@@ -60,6 +60,8 @@ description: 以目标达人为模板，通过多路召回和两阶段加权评
 
 - "亮点"列展示 `differentiator_tags`（以 "·" 连接），无标签时显示 `—`。
 - 相似度保留两位小数。
+- 每个结果的 `similarity_confidence` 单独展示为数据置信度；它不等于相似度，低置信度时提示数据不足。
+- 外部服务返回 `similarity_config_version` 时作为结果诊断信息保留。
 - 保留每位达人的 `creator_open_id` 供后续分析或建联使用。
 
 **3. 召回说明** — 简短一行：
@@ -72,7 +74,7 @@ description: 以目标达人为模板，通过多路召回和两阶段加权评
 - HTML 报告的共享品牌配色遵循 Agent 的"WorkBuddy HTML 共享配色"契约，本 Skill 不自行定义。
 - 结果 ≥ 6 位时，若当前宿主提供 HTML/可视化产物能力，默认生成自包含的响应式 HTML 报告。用户明确要求 HTML 时不受人数限制。
 - 宿主不支持 HTML 或生成失败时，回退为 Markdown 表格 + 摘要。
-- HTML 报告必须包含：目标达人摘要卡片、相似达人排名列表（含相似度分、亮点标签、各维度得分展开区）、召回说明。
+- HTML 报告必须包含：目标达人摘要卡片、相似达人排名列表（含相似度分、亮点标签、外部服务 breakdown 展开区）、召回说明。
 - 只使用内联 CSS/JavaScript，不依赖 CDN、远程字体或外部图片。
 - 昵称、用户名及所有工具返回文本写入 HTML 前必须转义。
 
@@ -81,8 +83,10 @@ description: 以目标达人为模板，通过多路召回和两阶段加权评
 | 情况 | 处理方式 |
 |------|---------|
 | 目标达人 Performance 查询失败 | 根据结构化错误（`shop_auth_invalid`/`oauth_invalid`/`rate_limited`等）按 Agent 规则分流 |
+| 所有可执行的召回渠道均失败 | 保留最需处理的结构化错误并按 Agent 规则分流，不展示为“未找到候选” |
 | 候选池为空（无人召回） | 说明该达人在当前市场的可召回范围（品类、粉丝量级、全市场）均未找到其他达人，建议换一个目标达人再试 |
-| 候选池非空但精排后全部失败 | 展示目标达人摘要，说明精排阶段调用失败，建议稍后重试或换目标达人 |
+| 候选池非空但候选 Performance 全部失败 | 保留最需处理的结构化错误并按 Agent 规则分流，不调用相似度服务 |
 | 精排候选全部成功但相似度偏低（最高分 < 0.3） | 结果仍正常展示，但在摘要中提示"未找到高度相似的达人，当前结果仅供参考" |
 | `rate_limited` / `quota_exhausted` | 建议等待后重试，不主动调用 `authorize` |
+| 外部相似度服务未配置或不可用 | 返回结构化错误，提示检查服务配置或稍后重试；不切换到其他评分方法 |
 | 上下文中没有 `creator_open_id` | 引导先搜索达人（`tiktok-creator-search` Skill）获取 ID，再使用本功能 |

package/skills/tiktok-similar-creators/references/similarity-model.md

@@ -2,58 +2,32 @@
 
 本文件是相似度评分模型的唯一权威 Reference。`tiktok-similar-creators` Skill 和 Agent 只做引用摘要，不重复展开。
 
-## 一、两阶段评分
+## 一、外部评分与两阶段流程
+
+外部双达人相似度服务是 `find_similar_creators` 的唯一评分来源，接口字段和错误契约见仓库顶层的 [达人相似度服务调用说明](../../../../../creator-similarity-api.md)。调用 `POST /v1/creator-similarities` 时，目标达人和候选达人均使用 TikTok Performance 返回的 `data.creator` 对象。
+
+- 外部服务返回的 `similarity_score`（0–100）在 MCP 层归一化为 0–1 后再展示。
+- 外部服务为每个评分结果返回 `confidence`；它是数据覆盖置信度，不是相似度，低置信度结果必须标明数据不足，不能仅按分数解读。
+- 外部结果是最终排序唯一依据，不与其他评分方法平均或加权混合。
+- 服务未配置、调用失败或响应不符合契约时返回结构化错误，不返回替代评分结果。
+
+召回和候选预算仍由 `find_similar_creators` 负责：三路召回合并去重后最多保留 24 位，默认最多对 12 位候选获取 Performance 并送入评分服务。粗排只用于控制 TikTok Performance 调用量，不作为最终对外分数。
 
 | 阶段 | 数据源 | API 调用 | 维度 | 用途 |
 |------|--------|---------|------|------|
 | 粗排 | `searchCreators` 返回字段 | 0 | 品类 + 粉丝量 | 从候选池（≤24）筛出 Top-K 进入精排 |
-| 精排 | `getCreatorPerformance` 全量指标 | ≤12 | 6 维完整评分 | 排序取 Top-N 返回 |
+| 精排 | `getCreatorPerformance` + 外部相似度服务 | TikTok ≤12 + 服务 1 次 | 以服务返回的分数和 breakdown 为准 | 排序取 Top-N 返回 |
 
 粗排 Top-K 计算：`K = min(ceil(top_n × 1.5), 12)`。
 
-## 二、6 个维度及权重（精排）
-
-| 维度 | 权重 | 相似度函数 | 数据字段 |
-|------|------|-----------|----------|
-| 品类匹配 | 0.25 | Jaccard（交集/并集） | `category_ids`（叶子 ID，两侧同层级可比） |
-| 粉丝量级 | 0.20 | `1 - \|log10(fA) - log10(fB)\| / 6` | `follower_count` |
-| GMV | 0.20 | `1 - \|A-B\| / max(A,B)` | `gmv.amount`（parseFloat） |
-| 互动率 | 0.15 | `1 - \|A-B\| / max(A,B)` | 见互动率取值规则 |
-| 客单价 | 0.10 | `1 - \|A-B\| / max(A,B)` | `gmv.amount / units_sold` |
-| 内容形式 | 0.10 | 匹配 = 1，否则 = 0 | 见内容形式推断规则 |
-
-### 品类匹配字段约束（关键）
+## 二、召回字段约束
 
 `search_creators` 的 `category` 参数只接受**顶层类目 ID**（`parent_id == "0"`），描述明文「禁止传更深层 ID」。
 - **召回用**：目标达人的 `category_gmv_distribution[].category_id`（顶级父类目 ID，与 `get_categories` 顶层 `id` 同级）。
-- **相似度计算用**：目标与候选的 `category_ids`（叶子 ID）做 Jaccard——两侧字段同层级，可比。
+- **候选粗排与展示标签用**：目标与候选的 `category_ids`（叶子 ID）做 Jaccard；该值不作为最终相似度。
 - **禁止混用**：不可将叶子 `category_ids` 传入 `searchCreators` 的 `parent_category_id`，否则被搜索接口静默忽略，返回无关达人。
 
-## 三、互动率取值规则
-
-先用 `inferContentFormat` 判断内容形式，再按形式取对应互动率：
-
-| 内容形式 | 互动率取值 |
-|----------|-----------|
-| 直播型 | `parseFloat(ec_live_engagement_rate) / 100` |
-| 视频型 | `parseFloat(ec_video_engagement_rate) / 100` |
-| 混合型 | 两者均值（缺失或为 "0" 的一侧不计入分母） |
-
-字段单位为**百分之一百分点**（如 `"6000"` = 60%），使用前 `/100` 换算为百分比值。
-缺失率记为 0，不参与均值时跳过。
-
-## 四、内容形式推断规则
-
-从 `ec_live_count` 和 `ec_video_count` 推断：
-
-| 条件 | 结果 |
-|------|------|
-| 两者均为 0 | `mixed` |
-| 直播占比 > 70% | `live` |
-| 视频占比 > 70% | `video` |
-| 其他 | `mixed` |
-
-## 五、3 路召回策略
+## 三、3 路召回策略
 
 | 召回路径 | 搜索参数 | 取前 | 触发条件 |
 |----------|---------|------|----------|
@@ -63,7 +37,7 @@
 
 各路结果合并 → 按 `creator_open_id` 去重 → 排除目标自身 → **上限 24 人**。
 
-## 六、粗排公式
+## 四、粗排公式
 
 仅用 `searchCreators` 已返回字段（品类 + 粉丝量），零额外 API 调用：
 
@@ -72,13 +46,13 @@ coarseScore = computeCategorySimilarity(targetCatIds, candidateCategoryIds) × (
             + computeFollowerSimilarity(targetFollowers, candidateFollowers) × (0.20/0.45)
 ```
 
-权重归一化至总和 1。
+权重归一化至总和 1。该分数只决定哪些候选进入外部评分，不能写入 `similarity_score`，也不能作为失败时的替代结果。
 
-## 七、差异化标签规则
+## 五、差异化标签规则
 
 | 标签 | 触发条件 |
 |------|---------|
-| 同品类 | 精排品类 Jaccard ≥ 0.8 |
+| 同品类 | 目标与候选的叶子品类 Jaccard ≥ 0.8 |
 | 更高GMV | 候选 GMV > 目标 × 1.2 |
 | 更高互动率 | 候选互动率 > 目标 × 1.2 |
 | 更大粉丝量 | 候选粉丝 > 目标 × 1.5 |