@scorehub/creator-outreach 1.3.3 → 1.5.0

package/.codebuddy-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tiktok-creator-outreach",
-  "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.",
+  "version": "1.5.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",
     "email": "bennyworks@foxmail.com"
@@ -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",
@@ -51,6 +52,10 @@
     {
       "en": "Southeast Asia",
       "zh": "东南亚"
+    },
+    {
+      "en": "United States",
+      "zh": "美国"
     }
   ],
   "quickPrompts": [

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 多维度筛选
 > - 按品类、用户名或昵称
@@ -80,7 +81,7 @@ bootstrap 返回 `ready` 后，再识别以下明确意图：
 >
 > ## 支持的市场
 >
-> 东南亚六国：印度尼西亚（ID）、泰国（TH）、马来西亚（MY）、越南（VN）、菲律宾（PH）、新加坡（SG）。
+> 东南亚六国及美国：印度尼西亚（ID）、泰国（TH）、马来西亚（MY）、越南（VN）、菲律宾（PH）、新加坡（SG）、美国（US）。
 >
 > ## 典型用法
 >
@@ -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 中重复定义。
+
 ## 标准工作流程
 
 当你找到我时，通常走这三步：
@@ -184,6 +191,7 @@ Step 3: 小范围建联验证
 - `creator_performance` — 获取达人表现；入参名为 `creator_user_id`，值使用搜索结果中的 `creator_open_id`
 - `create_conversation` — 创建达人会话（建联前置，用 `creator_open_id`）
 - `send_message` — 发送建联消息
+- `find_similar_creators` — 以目标达人为模板寻找相似达人
 - `authorize` — OAuth 授权；切换店铺时传 `{ "switch_shop": true }`，切换账号时传 `{ "force": true }`
 - `status` — 连接状态
 
@@ -222,7 +230,7 @@ Step 3: 小范围建联验证
 
 ## 限制与注意事项
 
-- **支持市场**：当前仅支持东南亚市场——泰国（TH）、马来西亚（MY）、越南（VN）、菲律宾（PH）、印度尼西亚（ID）、新加坡（SG）。用户明确提到其他市场（如美国、日本、欧洲等）时，主动说明不支持，并建议改选以上 SEA 市场之一
+- **支持市场**：当前支持东南亚及美国市场——泰国（TH）、马来西亚（MY）、越南（VN）、菲律宾（PH）、印度尼西亚（ID）、新加坡（SG）、美国（US）。用户明确提到其他市场（如日本、欧洲等）时，主动说明不支持，并建议改选以上支持的市场之一
 - **日配额**：搜索和表现查询共享每日 10,000 次调用限额
 - **限流处理**：如果请求过于频繁或短时间内持续限流，应先等待、分批执行或缩小请求范围；这类问题默认不是授权问题，也不需要为了解除限流去重新授权
 - **建联门槛**：店铺 GMV 需达标，且店铺与达人需在同一区域

package/package.json

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

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

@@ -25,7 +25,7 @@ description: 在 TikTok Shop Creator Marketplace 中按关键词、类目、商
 
 如果用户提到了品类/类目关键词（如"美妆"、"3C"、"beauty"、"electronics"），**必须**先从当前授权店铺的 `get_categories` 结果获取类目 ID，再调用 `search_creators`：
 
-1. **店铺市场类目树** — 对当前支持的 SEA 店铺调用 `get_categories` 时传 `category_version: "v2"`，不传 `locale`；TikTok 按当前 `shop_cipher` 使用店铺市场的默认语言和类目 ID。
+1. **店铺市场类目树** — 对当前支持的店铺调用 `get_categories` 时传 `category_version: "v2"`，不传 `locale`；TikTok 按当前 `shop_cipher` 使用店铺市场的默认语言和类目 ID。
    - 用户表达宽泛品类时，首次不传 `keyword`，获取当前店铺的顶层类目，再按当地语言 `local_name` 与用户意图进行语义匹配。
    - 只有用户明确指定具体子类目时，才将该意图翻译为店铺当地语言关键词后传入 `keyword`；不得将中文关键词与其他市场 locale 组合获取过滤 ID。翻译或匹配不唯一时使用 WorkBuddy 选项交互，不猜测 ID。
    - **顶层定义**：只有 `parent_id == "0"` 的类目才是达人搜索默认使用的顶层类目；`is_leaf=false` 只能说明不是叶子节点，不能据此把中间层当作顶层。
@@ -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`。
 
@@ -144,8 +146,9 @@ description: 在 TikTok Shop Creator Marketplace 中按关键词、类目、商
 | 菲律宾 | PH |
 | 印度尼西亚 | ID |
 | 新加坡 | SG |
+| 美国 | US |
 
-用户在搜索前若明确指定目标市场（如"帮我找日本的达人"、"搜索美国市场创作者"），应**立即告知不支持该市场**，并建议用户改选以上 SEA 市场之一，不要直接调用 `search_creators`。
+用户在搜索前若明确指定目标市场（如"帮我找日本的达人"），应**立即告知不支持该市场**，并建议用户改选以上支持的市场之一，不要直接调用 `search_creators`。
 
 ## 错误处理
 

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 |
+
+标签按触发条件从上到下顺序展示。