@scorehub/creator-outreach 1.1.4 → 1.1.6

package/.codebuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tiktok-creator-outreach",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "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/agents/tiktok-creator-outreach.md

@@ -52,7 +52,7 @@ skills:
 > - 按 GMV 区间（1K-10K / 10K+ 等）
 > - 按粉丝画像（年龄、性别、地区）
 > - 按用户名或昵称关键词
-> - 支持翻页获取更多结果
+> - 支持在单轮 60 人上限内继续翻页
 >
 > **2. 建立达人画像** — 拉取近 30 天详细表现并打分
 > - 带货数据：GMV、销量、客单价
@@ -113,8 +113,8 @@ skills:
 - 销量区间筛选
 - 关键词搜索（用户名/昵称匹配）
 - 粉丝画像筛选（年龄/性别/地区）
-- 支持翻页拉取全量结果
-- 搜索结果透传 `creator_open_id`（后续建联必需）
+- 支持在单轮 60 人上限内继续翻页
+- 搜索结果透传 `creator_open_id`（后续分析和建联共用）
 
 ### 2. 达人表现分析
 获取单个达人的近30天详细表现数据，并给出综合评分。
@@ -156,10 +156,11 @@ Step 3: 小范围建联验证
 
 搜索和评分结果不直接展示 MCP 原始 JSON，统一遵守对应 Skill 的固定输出契约：
 
-- 搜索结果先给摘要，再按“排名 / 昵称 / 用户名 / 粉丝数 / 近 30 天 GMV 区间 / 类目匹配 / 标识”展示列表，最后给分页状态和下一步。
-- 默认保持搜索接口返回顺序；只有用户明确要求时才重排。分页只展示“已显示 X / 共 Y”和是否还有更多，不暴露 `page_token`。
+- 搜索条件确定后不等待二次确认；类目闭环校验和回退重搜完成后，先展示最终实际生效的市场、类目、GMV、关键词、粉丝画像和目标展示人数，再给结果摘要与达人列表。未设置的维度写“未设置”，未显式指定市场时写“由当前授权店铺决定”。
+- 搜索结果按“搜索条件 / 结果摘要 / 排名 / 昵称 / 用户名 / 粉丝数 / 近 30 天 GMV 区间 / 类目匹配 / 达人 ID / 分页状态 / 下一步”顺序展示。默认保持搜索接口返回顺序；只有用户明确要求时才重排。
+- 用户未指定数量时默认展示 20 位；用户指定超过 60 位时按 60 位执行并提前告知。相同条件下的首次搜索和继续翻页累计最多展示 60 位，条件变更或明确重新搜索才重置额度。达到上限时提示调整条件后重新搜索，不再建议继续翻页；内部 `page_token` 永不展示。
 - 搜索结果若包含 `username`，则“昵称”列链接到 `https://www.tiktok.com/@{username}`；“用户名”列继续显示纯文本 `@username`。`username` 缺失时昵称保持纯文本，不猜测主页地址。
-- 每位达人必须保留 `creator_user_id`（分析用）和 `creator_open_id`（建联用）的一一映射。ID 在界面中弱化展示，但不得丢失、混用、截断或推断。
+- 每位达人只保留搜索结果返回的 `creator_open_id`。表现分析时将该值放入兼容入参 `creator_user_id`，建联时将同一个值放入 `creator_open_id`。ID 在界面中弱化展示，但不得丢失、改写或推断。
 - 单达人只展示表现画像、数据缺口和合作建议，不生成候选集相对综合分；至少 2 位候选人才输出综合评分排行榜。
 - 多人评分固定展示综合分、五个维度分、标签，并补充逐人详情、数据缺口、合作建议和失败名单。默认按综合分、带货分、内容分、粉丝数依次降序处理并列。
 - 字段缺失显示 `—` 并说明原因；失败达人不以 0 分参与排名；禁止编造缺失指标、内容风格或合作历史。
@@ -188,7 +189,7 @@ HTML 报告必须自包含，只使用内联 CSS/JavaScript，不依赖 CDN、
 优先使用 ScoreHub MCP 工具（本地 MCP Server 已连接）：
 - `search_creators` — 搜索达人
 - `get_categories` — 获取商品类目树，将品类名称（如"美妆"/"电子产品"）转换为类目 ID。**搜索达人前如果用户提到了品类关键词，必须先调用此工具获取类目 ID，禁止凭空猜测**
-- `creator_performance` — 获取达人表现
+- `creator_performance` — 获取达人表现；入参名为 `creator_user_id`，值使用搜索结果中的 `creator_open_id`
 - `create_conversation` — 创建达人会话（建联前置，用 `creator_open_id`）
 - `send_message` — 发送建联消息
 - `authorize` — OAuth 授权；切换店铺时传 `{ "switch_shop": true }`，切换账号时传 `{ "force": true }`
@@ -217,9 +218,9 @@ HTML 报告必须自包含，只使用内联 CSS/JavaScript，不依赖 CDN、
 - **支持市场**：当前仅支持东南亚市场——泰国（TH）、马来西亚（MY）、越南（VN）、菲律宾（PH）、印度尼西亚（ID）、新加坡（SG）。用户明确提到其他市场（如美国、日本、欧洲等）时，主动说明不支持，并建议改选以上 SEA 市场之一
 - **日配额**：搜索和表现查询共享每日 10,000 次调用限额
 - **限流处理**：如果请求过于频繁或短时间内持续限流，应先等待、分批执行或缩小请求范围；这类问题默认不是授权问题，也不需要为了解除限流去重新授权
-- **单页限制**：搜索接口每次最多返回 20 条，大批量搜索需要多次翻页
+- **搜索人数限制**：搜索接口每页最多返回 20 条；同一搜索条件下的首次搜索和继续翻页累计最多展示 60 位达人
 - **建联门槛**：店铺 GMV 需达标，且店铺与达人需在同一区域
-- **建联字段**：`create_conversation` 必须用 `creator_open_id`（不是 `creator_user_id`），该字段仅来自搜索结果；传错会导致建会话失败
+- **达人标识字段**：搜索结果只返回 `creator_open_id`。表现分析将该值传入 `creator_user_id`，建联将同一个值传入 `creator_open_id`；不得构造第二套达人 ID
 - **消息配额**：单店铺对单达人有 IM 消息条数上限
 - **店铺重新绑定**：如果本地登录状态正常，但当前店铺的 TikTok 授权失效、撤销、过期或不匹配，需要先到 ScoreHub 重新绑定该店铺，再继续搜索、分析或建联
 - **API 版本**：当前基于 202508（搜索/表现/建会话）和 202412（消息）版本，TikTok 可能更新

package/package.json

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

package/skills/tiktok-batch-outreach/SKILL.md

@@ -52,8 +52,8 @@
 
 ## 关键陷阱
 
-- `create_conversation` 必须用 **`creator_open_id`**（不是 `creator_user_id`）。
-- `creator_open_id` **仅来自搜索接口**，分析接口不返回——务必从搜索结果透传。
+- `create_conversation` 的入参名是 **`creator_open_id`**，其值与表现分析兼容入参 `creator_user_id` 使用的是同一个搜索结果 ID。
+- `creator_open_id` **仅来自搜索接口**，分析接口不返回——务必从搜索结果透传，不要构造第二套达人 ID。
 
 ## 错误处理
 

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

@@ -17,7 +17,7 @@ description: 获取 TikTok 达人近 30 天表现数据，按候选集相对评
 
 ## 执行方式（MCP 优先）
 
-对候选达人**逐个**调用 MCP 工具 **`creator_performance`**（入参 `creator_user_id`），拿到表现数据后应用
+对候选达人**逐个**调用 MCP 工具 **`creator_performance`**：工具入参名保留为 `creator_user_id`，其值必须直接使用搜索结果中的 `creator_open_id`。拿到表现数据后应用
 [评分模型](./references/scoring-model.md) 打分排序。批量分析属多步操作，先与用户确认名单再执行。
 
 如果 ScoreHub MCP 工具不可见、工具列表为空、连接已关闭或本地 MCP 未启动，直接提示用户：“ScoreHub 服务暂时未连接，请完全退出并重新打开 Claude Code 或 WorkBuddy 后重试；如仍无法使用，请联系 ScoreHub 支持。”不要向终端用户提及 Node.js、npm、网络、环境变量、TikTok API 凭证或直连 API，也不要调用 `authorize`。
@@ -50,15 +50,15 @@ description: 获取 TikTok 达人近 30 天表现数据，按候选集相对评
 
 - 默认按综合分降序；并列时依次按带货能力分、内容影响力分、粉丝数降序，仍相同则保持原候选顺序。
 - 分数均按评分模型取整并以 `/100` 展示；品类数据未授权或维度无法计算时显示 `—` 和原因，不用无说明的 0 分掩盖缺口。
-- 必须保留搜索结果中的 `creator_user_id` 和 `creator_open_id` 映射。`creator_performance` 不返回 `creator_open_id`，只能从当前对话中的搜索结果透传，不能猜测或推断。
-- 无法关联 `creator_open_id` 时显示“未保留建联标识”，并说明该达人暂不能直接建联；Markdown 中弱化为详情末项，HTML 中放入可展开复制区域。
+- 必须保留搜索结果中的 `creator_open_id`。`creator_performance` 不返回该 ID，只能从当前对话中的搜索结果透传，不能猜测或推断。
+- 无法关联 `creator_open_id` 时显示“达人 ID 不可用”，并说明该达人暂不能分析或建联；Markdown 中弱化为详情末项，HTML 中放入可展开复制区域。
 - 建议必须由实际指标、维度分、相对排名和数据缺口支撑，不得编造内容风格、合作历史或转化表现。
 
 ### WorkBuddy HTML 可视化
 
 - 成功结果为 1–5 位时使用 Markdown；达到 **6 位**时，若当前宿主提供 HTML/可视化产物能力，默认生成自包含的响应式 HTML 报告。用户明确要求 HTML 时不受人数限制。
 - 宿主不支持 HTML，或 HTML 生成失败时，必须回退为包含完整排行榜、详情和失败名单的 Markdown。
-- HTML 评分报告必须包含：评分摘要、可排序排行榜、五维分数、达人详情、数据缺口、合作建议和弱化的双 ID 复制区域。
+- HTML 评分报告必须包含：评分摘要、可排序排行榜、五维分数、达人详情、数据缺口、合作建议和弱化的达人 ID 复制区域。
 - 只使用内联 CSS/JavaScript，不依赖 CDN、远程字体或外部图片；只实现真实可用的搜索、排序、展开和复制交互，不添加无法触发 Agent 或 MCP 操作的伪按钮。
 - 昵称、用户名、标签及所有工具返回文本写入 HTML 前必须转义；禁止把工具内容作为 HTML 或脚本执行。
 - 生成 HTML 后仍需在对话中给出成功/失败数量、前三名和数据完整性的简短摘要。只有实际生成产物时才可声明存在 HTML，不得虚构文件名或 `outputs` 路径。

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

@@ -5,7 +5,7 @@ description: 在 TikTok Shop Creator Marketplace 中按关键词、类目、GMV
 
 # TikTok Creator Search — 达人搜索
 
-在 TikTok Shop Creator Marketplace 中按多维度筛选搜索达人，支持翻页获取全量结果。
+在 TikTok Shop Creator Marketplace 中按多维度筛选搜索达人，支持在单轮搜索的 60 人上限内继续翻页。
 
 ## 触发条件
 
@@ -58,14 +58,23 @@ description: 在 TikTok Shop Creator Marketplace 中按关键词、类目、GMV
 
 **GMV 区间取值**：`GMV_RANGE_0_100` / `GMV_RANGE_100_1000` / `GMV_RANGE_1000_10000` / `GMV_RANGE_10000_AND_ABOVE`
 
+### 搜索条件与人数上限
+
+- 用户的已明确条件构成达人画像；不新增等待用户二次确认的回合。类目解析、类目过滤闭环校验和必要的回退重搜完成后，才以最终实际生效的条件作为本轮搜索条件。
+- 将同一组规范化搜索条件下的首次搜索和“继续翻页”视为同一搜索会话。用户修改任一搜索条件或明确要求重新搜索时，创建新的搜索会话并重置人数预算。
+- 用户未指定数量时，默认展示 20 位达人。用户指定正整数时，目标展示数为该数量；超过 60 时按 60 执行，并在结果列表前明确说明“本次搜索最多展示 60 位达人”。数量小于 1 或无法识别时，要求用户给出 1–60 的数量。
+- 每次工具调用的 `page_size` 保持 20。为满足目标数量可顺序使用内部 `page_token` 拉取后续页；展示到目标数量、无下一页或累计展示 60 位时必须停止。最后一页只展示仍在目标范围内的记录。
+- 必须在当前对话中保留搜索条件、已展示数量和下一页令牌。用户继续翻页时，最多再展示 `min(20, 60 - 已展示数量)` 位；内部令牌永不对外展示。
+
 ### 输出与后续（固定格式）
 
 禁止直接展示 MCP 原始 JSON。每次成功搜索都按以下顺序输出：
 
-1. **结果摘要**：实际返回数、`total_count`、用户可读的搜索条件、当前排序、是否还有下一页。
-2. **达人列表**：固定展示“排名 / 昵称 / 用户名 / 粉丝数 / 近 30 天 GMV 区间 / 类目匹配 / 标识”。
-3. **分页状态**：使用“已显示 X / 共 Y；还有更多结果，可继续获取下一页”或“已显示全部结果”。不要向用户展示 `page_token`。
-4. **下一步**：只建议分析选中达人、继续翻页或调整条件，不要擅自开始批量分析或建联。
+1. **本次搜索条件**：先展示最终实际生效的市场、类目、GMV、关键词、粉丝画像和目标展示人数；未设置的维度明确写“未设置”，市场未显式指定时写“由当前授权店铺决定”。该区块必须位于任何结果统计和达人列表之前。
+2. **结果摘要**：实际展示数、`total_count`、当前排序和是否还有下一页；不重复罗列条件。
+3. **达人列表**：固定展示“排名 / 昵称 / 用户名 / 粉丝数 / 近 30 天 GMV 区间 / 类目匹配 / 达人 ID”。
+4. **分页状态**：有更多结果且未达到 60 人时，使用“已显示 X / 共 Y；本轮最多展示 60 位达人，还可继续获取最多 Z 位”。没有下一页时使用“已显示全部结果”。达到 60 人且仍有更多结果时，固定说明“本次搜索已达到 60 位达人上限；请调整条件后重新搜索”，不再建议继续翻页。不要向用户展示 `page_token`。
+5. **下一步**：只建议分析选中达人、在剩余预算内继续翻页或调整条件，不要擅自开始批量分析或建联。
 
 格式化规则：
 
@@ -74,22 +83,22 @@ description: 在 TikTok Shop Creator Marketplace 中按关键词、类目、GMV
 - 粉丝数使用千位分隔；GMV 区间转换为用户可读值（`0–100` / `100–1K` / `1K–10K` / `10K+`）；缺失字段统一显示 `—`，不要猜测。
 - `username` 缺失、为空或明显不合法时，昵称回退为纯文本，不要猜测用户名，也不要用 `nickname`、`creator_user_id`、`profile_tt_uri` 或其他字段拼接链接。
 - 类目匹配在使用类目筛选并完成闭环校验后显示“命中”；没有类目筛选时显示“未校验”；过滤疑似失效时不要展示为合格结果。
-- 必须为每位达人保留 `creator_user_id` 和 `creator_open_id` 的一一映射：前者供 `creator_performance` 使用，后者供 `create_conversation` 使用。不得混用、截断、改写或从其他字段推断。
-- Markdown 的“标识”列弱化展示“分析 ID / 建联 ID”；HTML 将两个 ID 放在可展开详情和复制区域，不占主表视觉焦点。
-- `creator_open_id` 缺失时显示“建联 ID 不可用”，并明确该达人暂不可建联；`creator_user_id` 缺失时显示“分析 ID 不可用”，不得调用表现分析。
-- 结果为空时不生成空表。固定输出“未找到符合条件的达人”，复述本次条件，并建议放宽类目、GMV 或关键词。
-- 单页最多 20 条，大批量搜索需用 `page_token` 多次翻页，但内部令牌永不对外展示。
+- 必须为每位达人保留搜索结果返回的 `creator_open_id`。调用 `creator_performance` 时将该值放入兼容入参 `creator_user_id`；调用 `create_conversation` 时将同一个值放入 `creator_open_id`。不得截断、改写或从其他字段推断。
+- Markdown 的“达人 ID”列弱化展示 `creator_open_id`；HTML 将该 ID 放在可展开详情和复制区域，不占主表视觉焦点。
+- `creator_open_id` 缺失时显示“达人 ID 不可用”，并明确该达人暂不可分析或建联。
+- 结果为空时不生成空表。在“本次搜索条件”后固定输出“未找到符合条件的达人”，并建议放宽类目、GMV 或关键词。
+- 单页最多 20 条；同一搜索会话最多展示 60 位达人，不承诺获取全量结果。
 
 ### WorkBuddy HTML 可视化
 
 - 结果为 1–5 条时使用 Markdown 表格；达到 **6 条**时，若当前宿主提供 HTML/可视化产物能力，默认生成自包含的响应式 HTML 报告。用户明确要求 HTML 时不受条数限制。
 - 宿主不支持 HTML，或 HTML 生成失败时，必须回退为包含全部记录的 Markdown，不能只给摘要或丢失达人。
-- HTML 搜索报告必须包含：搜索条件摘要、返回数/总数/分页状态、可搜索和排序的达人表格、达人详情、双 ID 复制区域和下一步建议。
+- HTML 搜索报告必须先包含实际生效的搜索条件和目标展示人数，再包含返回数/总数/分页状态、可搜索和排序的达人表格、达人详情、达人 ID 复制区域和下一步建议；达到 60 人上限时必须展示上限提示而非继续翻页入口。
 - HTML 报告中的昵称链接使用 `<a>` 指向 `https://www.tiktok.com/@{username}`，并带 `target="_blank"` 与 `rel="noopener noreferrer"`；链接文本与 URL 都必须先安全转义/编码。
 - 只使用内联 CSS/JavaScript，不依赖 CDN、远程字体或外部图片；只实现真实可用的搜索、排序、展开和复制交互，不添加无法触发 Agent 或 MCP 操作的伪按钮。
 - 昵称、用户名及所有工具返回文本写入 HTML 前必须转义；禁止把工具内容作为 HTML 或脚本执行。
 - Markdown 表格中的昵称也应输出为可点击链接；若宿主对链接渲染有限，至少保留标准 Markdown 链接语法和可辨认的主页 URL。
-- 生成 HTML 后仍需在对话中给出结果数量、排序和分页的简短摘要。只有实际生成产物时才可声明存在 HTML，不得虚构文件名或 `outputs` 路径。
+- 生成 HTML 后仍需在对话中按“搜索条件 → 结果数量/排序/分页”的顺序给出简短摘要。只有实际生成产物时才可声明存在 HTML，不得虚构文件名或 `outputs` 路径。
 
 ### 类目过滤闭环校验（防静默失效）