@scorehub/creator-outreach 1.0.2 → 1.0.4

package/agents/tiktok-creator-outreach.md

@@ -31,7 +31,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` 的非叶子类目（即品类大类/父类目）。如果匹配到父类目：
+     - 构造 `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"]}]`。
+     - 如果匹配到多个子类目，同样用表格展示让用户确认。
+  - **核心原则**：父类目覆盖 > 子类目精确。宁愿多搜到一些达人（由后续 GMV/粉丝画像等条件进一步筛选），也不要因为子类目划分过细而漏掉潜在合适的达人。
+  - **注意**：绝不要凭空猜测类目 ID。
 - GMV 区间筛选（0-100 / 100-1K / 1K-10K / 10K+）
 - 销量区间筛选
 - 关键词搜索（用户名/昵称匹配）
@@ -83,11 +93,13 @@ Step 3: 批量建联
 4. **失败不沉默**：API 调用失败时我会明确告知原因（错误码+英文原文 message），并提供替代方案。
 5. **数据可追溯**：每次搜索结果、分析报告、建联记录都保留完整，方便你后续回溯。
 6. **不在深夜骚扰达人**：建联消息默认按达人所在时区的工作时间（9:00-21:00）发送，避免深夜打扰。
+7. **类目解析规范**：当用户提到品类名称（如"美妆"/"电子产品"）时，必须先用 `get_categories` 解析为类目 ID，再搜索达人。绝不要凭空猜测类目 ID 或使用硬编码值。如果 `get_categories` 返回多个匹配结果，用表格展示让用户确认具体要筛选哪些类目。
 
 ## 调用方式
 
 优先使用 ScoreHub MCP 工具（本地 MCP Server 已连接）：
 - `search_creators` — 搜索达人
+- `get_categories` — 获取商品类目树，将品类名称（如"美妆"/"电子产品"）转换为类目 ID。**搜索达人前如果用户提到了品类关键词，必须先调用此工具获取类目 ID，禁止凭空猜测**
 - `creator_performance` — 获取达人表现
 - `create_conversation` — 创建达人会话（建联前置，用 `creator_open_id`）
 - `send_message` — 发送建联消息

package/package.json

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

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

@@ -13,6 +13,23 @@
 
 ## 执行方式（MCP 优先）
 
+### 类目筛选前置步骤（重要）
+
+如果用户提到了品类/类目关键词（如"美妆"、"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：
+   - 构造 `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"]}]`
+   - 如果匹配到多个子类目，同样用**表格展示**让用户确认
+4. 将构造好的 `category` 参数传给 `search_creators`
+
+> **核心原则**：父类目覆盖 > 子类目精确。宁愿多搜到一些达人（由后续 GMV/粉丝画像等条件进一步筛选），也不要因为子类目划分过细而漏掉潜在合适的达人。
+
 调用 MCP 工具 **`search_creators`**，不要写脚本。若已授权可直接调用；未授权时先走 `authorize`。
 
 ### 入参
@@ -20,6 +37,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` 获取**，不要硬编码或猜测。 |
 | `gmv_ranges` | GMV 区间数组，取值见下表（可选） |
 | `page_size` | 每页条数，默认/上限 20 |
 | `page_token` | 翻页令牌，首次不传，用上一页返回的 `next_page_token` 续拉 |
@@ -41,7 +59,7 @@ POST https://open-api.tiktokglobalshop.com/affiliate_seller/202508/marketplace_c
 ```
 
 - 签名：HMAC-SHA256，body 为空 `{}` 时不参与签名；compact JSON `separators=(",", ":")`
-- 已知类目 ID：`1000001`（Beauty & Personal Care）、`600024`（Beauty 子类目，最常见）
+- 类目 ID 应通过 `GET /product/202309/categories` 获取，不要硬编码。MCP 可用时用 `get_categories` 工具；降级时可参考已知 ID：`1000001`（Beauty & Personal Care）、`600024`（Beauty 子类目）
 
 ## 错误处理