@scorehub/creator-outreach 1.4.0 → 1.6.0

package/.codebuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tiktok-creator-outreach",
-  "version": "1.4.0",
+  "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.",
   "author": {
     "name": "Ben",
@@ -12,7 +12,8 @@
   "skills": [
     "./skills/tiktok-creator-search",
     "./skills/tiktok-creator-analysis",
-    "./skills/tiktok-batch-outreach"
+    "./skills/tiktok-batch-outreach",
+    "./skills/tiktok-similar-creators"
   ],
   "expertType": "agent",
   "agentName": "tiktok-creator-outreach",

package/agents/tiktok-creator-outreach.md

@@ -12,6 +12,7 @@ skills:
   - tiktok-creator-search
   - tiktok-creator-analysis
   - tiktok-batch-outreach
+  - tiktok-similar-creators
 ---
 
 # ScoreHub AI TikTok达人营销专家 · Tiky
@@ -56,7 +57,7 @@ bootstrap 返回 `ready` 后，再识别以下明确意图：
 
 > 你好，我是 Tiky，ScoreHub AI 的 TikTok 达人营销专家。我先帮你建立清晰准确的达人画像，评估合作价值，再对精选候选人进行小范围建联验证。我不是面向成千上万达人的海量群发工具。以下是我能帮你做的事情：
 >
-> ## 三大核心能力
+> ## 四大核心能力
 >
 > **1. 搜索达人** — 从 TikTok Creator Marketplace 多维度筛选
 > - 按品类、用户名或昵称
@@ -122,6 +123,12 @@ bootstrap 返回 `ready` 后，再识别以下明确意图：
 对经过画像评估的精选候选人创建会话并发送建联消息，用于快速验证合作假设，不以海量群发为目标。
 - 发送前确认、会话创建、消息类型、话术、速率和进度展示完整遵循 `tiktok-batch-outreach` Skill，不在 Agent 中重复定义。
 
+### 4. 相似达人推荐
+以某位达人为模板，通过多路召回和两阶段加权评分找到表现特征相似的其他达人。
+- 输入目标达人的 `creator_open_id`（来自搜索结果的唯一标识），返回按相似度降序排名的 Top-N 推荐列表。
+- 默认返回 20 位相似达人，可按需调整为 1–50。
+- 相似度计算、两阶段评分、召回策略和结果展示完整遵循 `tiktok-similar-creators` Skill，不在 Agent 中重复定义。
+
 ## 标准工作流程
 
 当你找到我时，通常走这三步：
@@ -182,8 +189,10 @@ Step 3: 小范围建联验证
 - `search_creators` — 搜索达人
 - `get_categories` — 获取商品类目树，将品类名称转换为搜索可用的类目 ID
 - `creator_performance` — 获取达人表现；入参名为 `creator_user_id`，值使用搜索结果中的 `creator_open_id`
+- `rank_creators` — 对两位及以上达人进行排序，值使用搜索结果中的 `creator_open_id`
 - `create_conversation` — 创建达人会话（建联前置，用 `creator_open_id`）
 - `send_message` — 发送建联消息
+- `find_similar_creators` — 以目标达人为模板寻找相似达人
 - `authorize` — OAuth 授权；切换店铺时传 `{ "switch_shop": true }`，切换账号时传 `{ "force": true }`
 - `status` — 连接状态
 

package/package.json

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

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

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

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

@@ -43,6 +43,8 @@ description: 在 TikTok Shop Creator Marketplace 中按关键词、类目、商
 4. 将构造好的 `category` 参数传给 `search_creators`
 
 > **核心原则**：默认顶层覆盖；只有用户明确指定子类目时才缩小范围。层级只能到“顶层类目 + 直接子类目”，宁愿回退顶层多搜，也不要猜测或使用深层 ID。
+>
+> **服务端兜底（无需 Agent 额外处理）**：`search_creators` 会用当前店铺类目树自动规整 `category`——只传 `parent_category_id` 时补全其直接子类目（美国市场必需，否则被 TikTok 拒绝并返回 `16032001`）；传入的子类目若是更深层级会被上卷到所属的直接子类目，与父类目无关的 ID 被剔除。仍应按上述规则构造，兜底只用于防止漏传或层级偏差导致的空结果。
 
 调用 MCP 工具 **`search_creators`**，不要写脚本。若已授权可直接调用；未授权时先走 `authorize`。
 

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

@@ -0,0 +1,88 @@
+---
+name: tiktok-similar-creators
+description: 以目标达人为模板，通过多路召回和两阶段加权评分寻找表现特征相似的达人，返回按相似度降序排列的 Top-N 推荐列表。用于"找相似达人"、"以他为模板"、"有没有类似的达人"等请求。
+---
+
+# TikTok Similar Creators — 相似达人推荐
+
+以某位达人为模板，基于多路召回和加权评分找到带货表现特征相似的其他达人。
+
+本文件是相似达人推荐专项行为的权威来源；Agent 只保留能力摘要。若执行流程、输出或失败处理存在冲突，以本文件为准。
+
+## 触发条件
+
+当用户提到以下意图时加载本技能：
+- "找相似达人"/"找类似的达人"
+- "similar to this creator"/"find similar creators"
+- "以他为模板"/"有没有类似的达人"
+- "这批达人里有没有跟 @xxx 很像的"
+
+## 执行方式（MCP 优先）
+
+调用 MCP 工具 **`find_similar_creators`**：
+
+| 参数 | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| `creator_user_id` | ✅ | — | 目标达人的 `creator_open_id`，只能来自当前对话上下文中的搜索结果，不可编造 |
+| `top_n` | ❌ | 20 | 返回数量（1–50） |
+| `include_reasoning` | ❌ | true | 是否包含各维度相似度得分 |
+
+相似度模型、召回策略、权重和标签规则的唯一权威来源是 [相似达人推荐模型](./references/similarity-model.md)，本 Skill 不重复其实现细节。
+
+授权、限流、MCP 不可用和本地运行环境恢复遵循 Agent 的权威规则，本技能不重复展开。
+
+### 执行流程
+
+1. 从当前对话上下文中提取目标达人的 `creator_open_id`（搜索结果中保留的标识）
+2. 调用 `find_similar_creators`，传入 `creator_user_id`
+3. 按输出格式展示结果
+
+如果上下文中没有可用的 `creator_open_id`（例如用户只说"找个跟美妆达人相似的"但没指定具体达人），先引导用户通过搜索找到目标达人，或请用户提供达人名称。
+
+### 输出（固定格式）
+
+禁止直接展示 MCP 原始 JSON。工具返回的结果按以下规则展示：
+
+#### Markdown 展示
+
+**1. 目标达人摘要**
+```
+🎯 目标达人：@username（nickname）
+   粉丝：<follower_count>  ·  GMV：<gmv_amount> <gmv_currency>  ·  内容形式：<直播型/视频型/混合型>
+```
+
+**2. 相似达人列表** — 按相似度得分降序的表格：
+
+| 排名 | 达人 | 用户名 | 粉丝数 | 相似度 | 亮点 |
+|------|------|--------|--------|--------|------|
+| 1 | nickname | @username | follower_count | 0.85 | 同品类 · 更高GMV |
+| 2 | ... | ... | ... | ... | ... |
+
+- "亮点"列展示 `differentiator_tags`（以 "·" 连接），无标签时显示 `—`。
+- 相似度保留两位小数。
+- 保留每位达人的 `creator_open_id` 供后续分析或建联使用。
+
+**3. 召回说明** — 简短一行：
+```
+共评估 <total_candidates_evaluated> 位候选人（<召回路列表，逗号分隔>），返回 Top-<N>
+```
+
+#### WorkBuddy HTML 可视化
+
+- HTML 报告的共享品牌配色遵循 Agent 的"WorkBuddy HTML 共享配色"契约，本 Skill 不自行定义。
+- 结果 ≥ 6 位时，若当前宿主提供 HTML/可视化产物能力，默认生成自包含的响应式 HTML 报告。用户明确要求 HTML 时不受人数限制。
+- 宿主不支持 HTML 或生成失败时，回退为 Markdown 表格 + 摘要。
+- HTML 报告必须包含：目标达人摘要卡片、相似达人排名列表（含相似度分、亮点标签、各维度得分展开区）、召回说明。
+- 只使用内联 CSS/JavaScript，不依赖 CDN、远程字体或外部图片。
+- 昵称、用户名及所有工具返回文本写入 HTML 前必须转义。
+
+### 错误处理
+
+| 情况 | 处理方式 |
+|------|---------|
+| 目标达人 Performance 查询失败 | 根据结构化错误（`shop_auth_invalid`/`oauth_invalid`/`rate_limited`等）按 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

@@ -0,0 +1,87 @@
+# 相似达人推荐模型
+
+本文件是相似度评分模型的唯一权威 Reference。`tiktok-similar-creators` Skill 和 Agent 只做引用摘要，不重复展开。
+
+## 一、两阶段评分
+
+| 阶段 | 数据源 | API 调用 | 维度 | 用途 |
+|------|--------|---------|------|------|
+| 粗排 | `searchCreators` 返回字段 | 0 | 品类 + 粉丝量 | 从候选池（≤24）筛出 Top-K 进入精排 |
+| 精排 | `getCreatorPerformance` 全量指标 | ≤12 | 6 维完整评分 | 排序取 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` 传入 `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 路召回策略
+
+| 召回路径 | 搜索参数 | 取前 | 触发条件 |
+|----------|---------|------|----------|
+| 同品类 | `category: [{parent_category_id: id_from_category_gmv_distribution}]` | 10 | `category_gmv_distribution` 非空 |
+| 同粉丝量级 | `follower_demographics: {count_range: {count_ge: floor(f×0.5), count_le: ceil(f×2)}}` | 10 | 始终 |
+| 全市场多样性 | 无筛选条件 | 10 | 始终 |
+
+各路结果合并 → 按 `creator_open_id` 去重 → 排除目标自身 → **上限 24 人**。
+
+## 六、粗排公式
+
+仅用 `searchCreators` 已返回字段（品类 + 粉丝量），零额外 API 调用：
+
+```
+coarseScore = computeCategorySimilarity(targetCatIds, candidateCategoryIds) × (0.25/0.45)
+            + computeFollowerSimilarity(targetFollowers, candidateFollowers) × (0.20/0.45)
+```
+
+权重归一化至总和 1。
+
+## 七、差异化标签规则
+
+| 标签 | 触发条件 |
+|------|---------|
+| 同品类 | 精排品类 Jaccard ≥ 0.8 |
+| 更高GMV | 候选 GMV > 目标 × 1.2 |
+| 更高互动率 | 候选互动率 > 目标 × 1.2 |
+| 更大粉丝量 | 候选粉丝 > 目标 × 1.5 |
+| 更小粉丝量，高性价比 | 候选粉丝 < 目标 × 0.67 且 > 0 |
+
+标签按触发条件从上到下顺序展示。