@scorehub/creator-outreach 1.0.7 → 1.0.10

package/README.md

@@ -1,53 +1,44 @@
-# creator-outreach — Tiky TikTok 达人建联
+# @scorehub/creator-outreach
 
-TikTok 达人建联 WorkBuddy 智能体。支持按 GMV/类目/粉丝画像搜索达人、
-带货表现分析评分、两步会话建联（create_conversation → send_message），
-通过 ScoreHub MCP 调用 TikTok API。
+**Tiky** — TikTok 达人建联 AI 智能体。一条命令装进 Claude Code 和 WorkBuddy。
 
-## 安装
+按类目 / GMV / 粉丝画像搜索 TikTok Shop 达人，分析带货表现并打分排名，批量发送建联消息（`create_conversation` → `send_message`）。所有 TikTok API 调用通过 ScoreHub MCP 完成。
 
-### 一键安装（Claude Code + WorkBuddy）
+## 安装
 
 ```bash
 npx @scorehub/creator-outreach
 ```
 
-自动检测并安装到已安装的 AI 客户端：
-
-**Claude Code / Claude Desktop：**
-- 将 Tiky Agent 定义复制到 `~/.claude/agents/`
-- 将 ScoreHub MCP Server 配置写入 `~/.claude.json`
+命令会自动检测本机已安装的 AI 客户端并完成配置：
 
-**WorkBuddy 桌面版（检测到 `~/.workbuddy/` 时自动安装）：**
-- 将插件文件复制到 `~/.workbuddy/plugins/.../`
-- 将 ScoreHub MCP Server 配置写入 `~/.workbuddy/mcp.json`
+| 客户端 | 安装内容 |
+|--------|----------|
+| **Claude Code / Claude Desktop** | Agent 定义 → `~/.claude/agents/`；MCP 配置 → `~/.claude.json` |
+| **WorkBuddy**（检测到 `~/.workbuddy/` 时） | 插件文件 → `~/.workbuddy/plugins/.../`；MCP 配置 → `~/.workbuddy/mcp.json` |
 
-重启客户端后使用 Tiky：
-- Claude Code：`@tiktok-creator-outreach`
-- WorkBuddy：在 Agent 列表中选择 "Tiky — TikTok Creator Outreach"
+MCP Server（`@scorehub/mcp-server`）由配置中的 `npx -y` 在首次启动时自动拉取，无需单独安装。
 
-### WorkBuddy 插件市场（备选）
+安装完成后重启客户端，即可唤起 Tiky：
 
-在插件安装入口输入地址：
+- **Claude Code**：输入 `@tiktok-creator-outreach`
+- **WorkBuddy**：在 Agent 列表中选择 "Tiky — TikTok Creator Outreach"
 
-```
-@scorehub/creator-outreach
-```
+> 也可在 WorkBuddy 插件市场直接搜索 `@scorehub/creator-outreach` 安装。
 
-## 前提条件
+## 首次使用：授权
 
-插件依赖 ScoreHub MCP Server 调用 TikTok API，安装插件前需先配置：
+Tiky 首次调用 TikTok 工具时会自动打开浏览器引导登录 ScoreHub。登录一次后 Token 缓存在本地（`~/.scorehub/`），Claude Code 与 WorkBuddy 共享，无需重复授权。
 
-```bash
-npm install -g @scorehub/mcp-server
-```
+## 快速开始
 
-配置说明见 [@scorehub/mcp-server](https://www.npmjs.com/package/@scorehub/mcp-server)。
+直接对 Tiky 说：
 
-## 快速开始
+- 帮我搜索适合合作的 TikTok 达人，类目是美妆，GMV 在 1000-10000 美元区间
+- 分析这 10 个达人的带货表现，帮我打分排名
+- 用我的建联话术模板，给这 50 个达人批量发送合作消息
 
-安装完成后，可以直接对 Tiky 说：
+## 相关链接
 
-- 帮我搜索适合合作的TikTok达人，类目是美妆，GMV在1000-10000美元区间
-- 分析这10个达人的带货表现，帮我打分排名
-- 用我的建联话术模板，给这50个达人批量发送合作消息
+- MCP Server：[@scorehub/mcp-server](https://www.npmjs.com/package/@scorehub/mcp-server)
+- 仓库：[ScoreHub-AI/creator-outreach](https://github.com/ScoreHub-AI/creator-outreach)

package/agents/tiktok-creator-outreach.md

@@ -32,15 +32,17 @@ skills:
 ### 1. 达人搜索与发现
 在多维筛选条件下，从 TikTok Creator Marketplace 精准搜索达人。
 - **类目筛选（父类目优先，务必遵守）**：
-  1. 当用户提到品类/类目关键词（如"美妆"/"3C"/"beauty"/"electronics"）时，**先调用 `get_categories`** 解析为类目 ID。传入 `keyword`（品类名），并根据语言设置 `locale`（中文用 `"zh-CN"`，英文用 `"en-US"`），建议同时传 `category_version: "v2"`。
-  2. **优先匹配父类目（`is_leaf=false`）**：从返回结果中筛选 `is_leaf=false` 的非叶子类目（即品类大类/父类目）。如果匹配到父类目：
+  1. 当用户提到品类/类目关键词（如"美妆"/"3C"/"beauty"/"electronics"）时，**先调用 `get_categories`** 解析为类目 ID。传入 `keyword`（品类名），并根据语言设置 `locale`（中文用 `"zh-CN"`，英文用 `"en-US"`）。`category_version` 跟随区域：US/EU/SEA 用 `"v2"`（官方推荐），其余区域按返回情况定，不必硬性钦定版本。
+  2. **优先匹配父类目（`is_leaf=false`）**：从返回结果中筛选 `is_leaf=false` 的父类目。匹配到父类目：
      - 构造 `category` 参数：`[{parent_category_id: "父类目ID"}]` —— **不要传 `child_category_id_list`**。API 会搜索该父类目下所有子类目的达人，覆盖面最广。
      - 如果匹配到多个父类目，用表格展示让用户确认想要筛选哪些（或全部）。
-  3. **兜底匹配子类目**：仅当返回结果中**没有任何 `is_leaf=false` 的父类目**时，才降级使用叶子类目：
-     - 筛选 `is_leaf=true` 的叶子类目，按 `parent_id` 分组。
-     - 构造 `category` 参数：`[{parent_category_id: "父类目ID", child_category_id_list: ["叶子ID1", "叶子ID2"]}]`。
+  3. **兜底匹配子类目（仅限直接下一级）**：仅当没有合适父类目时降级：
+     - 只取某父类目**直接下一级**的子类目（其 `parent_id` 等于该父类目 `id`），**绝不用更深层的叶子 ID**。
+     - 构造 `category` 参数：`[{parent_category_id: "父类目ID", child_category_id_list: ["直接子类ID1", "直接子类ID2"]}]`。
      - 如果匹配到多个子类目，同样用表格展示让用户确认。
-  - **核心原则**：父类目覆盖 > 子类目精确。宁愿多搜到一些达人（由后续 GMV/粉丝画像等条件进一步筛选），也不要因为子类目划分过细而漏掉潜在合适的达人。
+  - **关键约束**：达人搜索的 `category` 只支持「父类目 + 直接下一级子类目」（TikTok 官方限制）。v2 是最深 7 级的类目树，直接取深层叶子 ID 会被搜索接口**静默忽略**、导致过滤失效返回一堆无关达人。这就是"中文类目树 ID 与搜索返回 `category_ids` 对不上"的根因。
+  - **搜索后闭环校验**：用了类目过滤就要把返回结果的 `category_ids` 与所传类目 ID 比对，**零重叠**说明过滤已静默失效——提示用户并把所传子类目换成其**父类目**（更浅一级）重搜，不要把无关结果当作合规品类结果。
+  - **核心原则**：父类目覆盖 > 子类目精确。宁愿多搜到一些达人（由后续 GMV/粉丝画像等条件进一步筛选），也不要漏掉。
   - **注意**：绝不要凭空猜测类目 ID。
 - GMV 区间筛选（0-100 / 100-1K / 1K-10K / 10K+）
 - 销量区间筛选

package/install.js

@@ -3,6 +3,10 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { execSync } = require('child_process');
+
+const pkg = require('./package.json');
+console.log(`${pkg.name} v${pkg.version}\n`);
 
 // === Claude Code 路径 ===
 const CLAUDE_DIR = path.join(os.homedir(), '.claude');
@@ -47,6 +51,22 @@ function resolveWorkBuddyNode() {
   return { npx: 'npx', binDir: null };
 }
 
+// 工具函数：查询 mcp-server 在 npm registry 的当前最新版本
+// 注意：这是 install 此刻的最新版；实际 MCP 拉起时由 npx 现场解析 @latest，
+// 若之后 registry 更新，运行时版本可能与此不同。失败时静默返回 null（不阻断安装）。
+function fetchLatestMcpServerVersion() {
+  try {
+    const out = execSync('npm view @scorehub/mcp-server version', {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 10000,
+    });
+    return out.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
 // 工具函数：合并 MCP Server 配置到 JSON 文件
 function mergeMcpConfig(configPath, serverName, serverConfig, extraFields) {
   let config = {};
@@ -123,6 +143,13 @@ if (hasWorkBuddy) {
 const platforms = ['Claude Code'];
 if (hasWorkBuddy) platforms.push('WorkBuddy');
 
+const mcpServerVersion = fetchLatestMcpServerVersion();
+if (mcpServerVersion) {
+  console.log(`\n→ mcp-server 当前最新版本：v${mcpServerVersion}（运行时由 npx 解析 @latest，届时可能更新）`);
+} else {
+  console.log('\n→ mcp-server：@latest（运行时由 npx 解析，未能查询到具体版本号）');
+}
+
 console.log(`\n安装完成！重启 ${platforms.join(' / ')} 后使用 Tiky。`);
 if (!hasWorkBuddy) {
   console.log('提示：未检测到 WorkBuddy，仅安装了 Claude Code。如需 WorkBuddy 支持请先安装 WorkBuddy 后重新运行本命令。');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scorehub/creator-outreach",
-  "version": "1.0.7",
+  "version": "1.0.10",
   "description": "ScoreHub Tiky 智能体 — Agent 定义 + Skills 配置",
   "files": [
     ".codebuddy-plugin",

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

@@ -17,18 +17,19 @@
 
 如果用户提到了品类/类目关键词（如"美妆"、"3C"、"beauty"、"electronics"），**必须**先调用 `get_categories` 获取类目 ID，再调用 `search_creators`：
 
-1. **`get_categories`** — 传入 `keyword`（品类名关键词），建议同时传 `category_version: "v2"` 和合适的 `locale`（中文用 `"zh-CN"`，英文用 `"en-US"`）
-2. **优先匹配父类目（`is_leaf=false`）** — 从返回的 `categories` 数组中筛选 `is_leaf=false` 的非叶子节点（即品类大类/父类目）。如果匹配到父类目，直接使用父类目 ID：
+1. **`get_categories`** — 传入 `keyword`（品类名关键词），并设合适的 `locale`（中文用 `"zh-CN"`，英文用 `"en-US"`）。`category_version` 跟随区域：US/EU/SEA 用 `"v2"`（官方推荐，类目树更完整），其余区域按返回情况定，不必硬性钦定某个版本。
+   - **关键层级约束（与版本无关）**：达人搜索的 `category` 过滤**只认父类目 + 其直接下一级子类目**（TikTok 官方约束："A child category is only 1 level deeper than the parent"）。类目树最深可达 7 级，若直接取深层子类目 ID 喂给搜索接口会被**静默忽略**，导致过滤失效、返回一堆无关达人（这正是"中文树 ID 和搜索返回 category_ids 对不上"的根因）。因此重点不在选哪个版本，而在**只用父类目或其直接下一级**。
+2. **优先匹配父类目** — 从返回的 `categories` 中筛 `is_leaf=false` 的父类目。匹配到就直接用：
    - 构造 `category` 参数时 **只传 `parent_category_id`，不传 `child_category_id_list`**：`[{parent_category_id: "父ID"}]`
-   - 这样 API 会搜索该父类目下**所有**子类目的达人，覆盖面最广
-   - 如果匹配到多个父类目，用**表格展示**让用户确认要筛选哪些
-3. **兜底匹配子类目** — 仅当返回结果中**没有任何 `is_leaf=false` 的父类目**时，才降级使用子类目匹配：
-   - 筛选 `is_leaf=true` 的叶子节点，按 `parent_id` 分组
-   - 构造 `category` 参数：`[{parent_category_id: "父ID", child_category_id_list: ["叶子ID1", "叶子ID2"]}]`
-   - 如果匹配到多个子类目，同样用**表格展示**让用户确认
+   - API 会搜索该父类目下**所有**子类目的达人，覆盖面最广
+   - 匹配到多个父类目，用**表格展示**让用户确认要筛选哪些
+3. **兜底匹配子类目（仅限父类目的直接下一级）** — 仅当没有合适父类目时降级：
+   - 只取某父类目**直接下一级**的子类目（`parent_id` 等于该父类目 `id`），**绝不使用更深层的叶子 ID**
+   - 构造：`[{parent_category_id: "父ID", child_category_id_list: ["直接子类ID1", "直接子类ID2"]}]`
+   - 匹配到多个，同样用**表格展示**让用户确认
 4. 将构造好的 `category` 参数传给 `search_creators`
 
-> **核心原则**：父类目覆盖 > 子类目精确。宁愿多搜到一些达人（由后续 GMV/粉丝画像等条件进一步筛选），也不要因为子类目划分过细而漏掉潜在合适的达人。
+> **核心原则**：父类目覆盖 > 子类目精确。且**层级只能到"父类目 + 直接子类目"**，深层叶子无效。宁愿多搜到一些达人（由后续 GMV/粉丝画像等条件进一步筛选），也不要漏掉。
 
 调用 MCP 工具 **`search_creators`**，不要写脚本。若已授权可直接调用；未授权时先走 `authorize`。
 
@@ -37,7 +38,7 @@
 | 参数 | 说明 |
 |------|------|
 | `keyword` | 用户名/昵称搜索（可选） |
-| `category` | 品类筛选数组（可选）。支持两种格式：① **父类目模式（推荐优先使用）**：`[{parent_category_id: "父ID"}]`，不传 `child_category_id_list`，搜索该父类目下所有子类目；② **子类目模式（仅兜底使用）**：`[{parent_category_id: "父ID", child_category_id_list: ["叶子ID1"]}]`。多个对象 OR 关系，单个对象内 child_category_id_list AND 关系。类目 ID **必须先通过 `get_categories` 获取**，不要硬编码或猜测。 |
+| `category` | 品类筛选数组（可选）。支持两种格式：① **父类目模式（推荐优先使用）**：`[{parent_category_id: "父ID"}]`，不传 `child_category_id_list`，搜索该父类目下所有子类目；② **父+直接子类目模式（仅兜底）**：`[{parent_category_id: "父ID", child_category_id_list: ["直接子类ID1"]}]`，子类目只能比父类目深一级。多个对象 OR 关系，单个对象内 child_category_id_list AND 关系。类目 ID **必须先通过 `get_categories` 获取**，不要硬编码或猜测；**禁止使用深层叶子 ID**。 |
 | `gmv_ranges` | GMV 区间数组，取值见下表（可选） |
 | `page_size` | 每页条数，默认/上限 20 |
 | `page_token` | 翻页令牌，首次不传，用上一页返回的 `next_page_token` 续拉 |
@@ -50,6 +51,15 @@
 - **务必透传每个达人的 `creator_open_id`**——这是后续 `create_conversation` 建联的必需字段，且**仅搜索结果返回**（分析接口不返回）。
 - 单页最多 20 条，大批量搜索需用 `page_token` 多次翻页。
 
+### 类目过滤闭环校验（防静默失效）
+
+用了 `category` 过滤时，搜索返回后**必须自检**：把返回结果里各达人的 `category_ids` 汇总，与本次传入的 `parent_category_id` / `child_category_id_list` 比对。
+
+- 若**零重叠**（返回的 `category_ids` 完全不含所传的类目 ID），说明类目 ID 很可能层级过深或版本不对，**过滤已静默失效**——不要把这批结果当作"符合品类"直接给用户。此时应：
+  1. 提示用户"当前类目过滤可能未生效"；
+  2. 回退到更浅的类目层级重搜：把所传的深层子类目换成其**父类目**（只传 `parent_category_id`）重新 `search_creators`；仍零重叠时再上溯一级到顶级父类目。
+- 若有重叠，说明过滤生效，正常展示。
+
 ## 降级：直接 API
 
 MCP 不可用时，降级用环境变量凭证直接调用：
@@ -59,7 +69,7 @@ POST https://open-api.tiktokglobalshop.com/affiliate_seller/202508/marketplace_c
 ```
 
 - 签名：HMAC-SHA256，body 为空 `{}` 时不参与签名；compact JSON `separators=(",", ":")`
-- 类目 ID 应通过 `GET /product/202309/categories` 获取，不要硬编码。MCP 可用时用 `get_categories` 工具；降级时可参考已知 ID：`1000001`（Beauty & Personal Care）、`600024`（Beauty 子类目）
+- 类目 ID 应通过 `GET /product/202309/categories` 获取，不要硬编码。MCP 可用时用 `get_categories` 工具。注意达人搜索的 `category` 只认「父类目 + 直接下一级子类目」，深层叶子无效；已知父类目段 ID 形如 `600001`（6 位），可作层级参考。
 
 ## 错误处理