@scorehub/creator-outreach 1.3.0 → 1.3.1

package/.codebuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tiktok-creator-outreach",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "ScoreHub AI's TikTok creator marketing expert for building clear creator profiles and validating focused collaboration shortlists across Southeast Asia.",
   "author": {
     "name": "Ben",

package/package.json

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

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

@@ -22,7 +22,7 @@
 - 维度分 = round(min(followers / maxFollowers × 100, 100))
 
 ### 4. 品类匹配（20%）
-- **目标类目 ID 集合**（`target_cat_ids`）：由用户品类意图决定，通过 `get_categories` 获取后传入。**默认使用父类目 ID**；仅当用户明确指定某个子类目时，才改用该子类目 ID。示例（美妆父类目）：`{600024, 601303, 602118, 602284, 601450, 600025, 600026}`
+- **目标类目 ID 集合**（`target_cat_ids`）：由用户品类意图决定，通过 `get_categories` 获取后传入。默认使用 `parent_id == "0"` 的顶层类目 ID；仅当用户明确指定某个直接子类目时，才改用该子类目 ID。示例（美妆顶层类目）：`{600024, 601303, 602118, 602284, 601450, 600025, 600026}`
 - 若有 `category_gmv_distribution`（API 返回的 `category_id` 为**顶级父类目 ID**，与 `target_cat_ids` 同层级）：
   - 取 GMV 占比最高的类目，判断其 `category_id` 是否在 `target_cat_ids` 中
     - **命中**（最理想路径）→ 维度分 = round(该类目 GMV 占比 × 100)，上限 100

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

@@ -26,18 +26,21 @@ description: 在 TikTok Shop Creator Marketplace 中按关键词、类目、商
 如果用户提到了品类/类目关键词（如"美妆"、"3C"、"beauty"、"electronics"），**必须**先调用 `get_categories` 获取类目 ID，再调用 `search_creators`：
 
 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 会搜索该父类目下**所有**子类目的达人，覆盖面最广
-   - 匹配到多个同样合理、无法从用户原话判定的父类目时，按下方“WorkBuddy 选项交互”调用 `AskUserQuestion` 多选；唯一明确匹配时直接继续
-3. **兜底匹配子类目（仅限父类目的直接下一级）** — 仅当没有合适父类目时降级：
-   - 只取某父类目**直接下一级**的子类目（`parent_id` 等于该父类目 `id`），**绝不使用更深层的叶子 ID**
-   - 构造：`[{parent_category_id: "父ID", child_category_id_list: ["直接子类ID1", "直接子类ID2"]}]`
-   - 匹配到多个同样合理且无法从用户原话判定的子类目时，同样调用 `AskUserQuestion` 多选；唯一明确匹配时直接继续
+   - **顶层定义**：只有 `parent_id == "0"` 的类目才是达人搜索默认使用的顶层类目；`is_leaf=false` 只能说明不是叶子节点，不能据此把中间层当作顶层。
+   - **关键层级约束（与版本无关）**：达人搜索的 `category` 过滤只支持顶层类目及其直接下一级子类目（TikTok 官方约束："A child category is only 1 level deeper than the parent"）。禁止把更深层命中项直接作为搜索子类目，否则过滤可能被静默忽略。
+2. **默认匹配顶层类目** — 用户只表达宽泛品类或未明确点名子类目时，只使用 `parent_id == "0"` 的顶层类目：
+   - 构造 `category` 参数时只传 `parent_category_id`，不传 `child_category_id_list`：`[{parent_category_id: "顶层ID"}]`
+   - 关键词结果包含对应顶层类目时直接使用；只返回中间层或深层命中项时，再调用一次不带 `keyword`、保持相同 `locale` 与 `category_version` 的 `get_categories` 获取顶层列表，并按命中项的类目归属选择对应顶层
+   - 无法从工具结果可靠确认深层命中项所属顶层时，不猜测类目 ID；按下方“WorkBuddy 选项交互”让用户从相关顶层类目中选择
+   - 匹配到多个同样合理、无法从用户原话判定的顶层类目时，调用 `AskUserQuestion` 多选；唯一明确匹配时直接继续
+3. **仅按用户明确意图使用子类目** — 只有用户原话明确点名具体子类目时，才允许传 `child_category_id_list`：
+   - 子类目必须是所传顶层类目的直接下一级，即子类目的 `parent_id` 等于该顶层类目的 `id`
+   - 构造：`[{parent_category_id: "顶层ID", child_category_id_list: ["直接子类ID1"]}]`
+   - 用户明确点名的是更深层类目时，将其映射到所属的直接子类目；无法从工具结果可靠完成映射时，回退为只传顶层类目，不猜测或传入深层 ID
+   - 仅因关键词查询返回子类目，或没有合适的顶层名称匹配，不视为用户明确指定子类目，不得自动降级使用子类目
 4. 将构造好的 `category` 参数传给 `search_creators`
 
-> **核心原则**：父类目覆盖 > 子类目精确。且**层级只能到"父类目 + 直接子类目"**，深层叶子无效。宁愿多搜到一些达人（由后续 GMV/粉丝画像等条件进一步筛选），也不要漏掉。
+> **核心原则**：默认顶层覆盖；只有用户明确指定子类目时才缩小范围。层级只能到“顶层类目 + 直接子类目”，宁愿回退顶层多搜，也不要猜测或使用深层 ID。
 
 调用 MCP 工具 **`search_creators`**，不要写脚本。若已授权可直接调用；未授权时先走 `authorize`。
 
@@ -62,7 +65,7 @@ description: 在 TikTok Shop Creator Marketplace 中按关键词、类目、商
 | 参数 | 说明 |
 |------|------|
 | `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` 获取**，不要硬编码或猜测；**禁止使用深层叶子 ID**。 |
+| `category` | 品类筛选数组（可选）。默认使用顶层模式：`[{parent_category_id: "顶层ID"}]`，其中顶层类目的 `parent_id == "0"`。只有用户明确指定具体子类目时才使用顶层+直接子类目模式：`[{parent_category_id: "顶层ID", child_category_id_list: ["直接子类ID1"]}]`；直接子类目的 `parent_id` 必须等于顶层 ID。多个对象 OR 关系，单个对象内 child_category_id_list AND 关系。类目 ID 必须先通过 `get_categories` 获取，不得猜测或使用深层 ID。 |
 | `gmv_ranges` / `units_sold_ranges` | GMV 与销量档位（可选） |
 | `follower_demographics` | 粉丝数、年龄段、主要性别及最低占比（可选） |
 | `content_performance` | 视频、带货视频、互动率和直播观看表现（可选） |