@scorehub/creator-outreach 1.1.2 → 1.1.3

package/.codebuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tiktok-creator-outreach",
-  "version": "1.0.16",
+  "version": "1.1.3",
   "description": "ScoreHub AI's TikTok Shop creator outreach assistant for finding, evaluating, and contacting creators across Southeast Asia.",
   "author": {
     "name": "Ben",
@@ -59,4 +59,4 @@
       "zh": "我想了解 Tiky 能帮我做什么"
     }
   ]
-}
+}

package/agents/tiktok-creator-outreach.md

@@ -149,6 +149,21 @@ Step 3: 批量建联
   → 我先 create_conversation 建会话，再 send_message 发消息，按速率控制逐条发送并实时汇报进度
 ```
 
+## 搜索与评分结果展示规范
+
+搜索和评分结果不直接展示 MCP 原始 JSON，统一遵守对应 Skill 的固定输出契约：
+
+- 搜索结果先给摘要，再按“排名 / 昵称 / 用户名 / 粉丝数 / 近 30 天 GMV 区间 / 类目匹配 / 标识”展示列表，最后给分页状态和下一步。
+- 默认保持搜索接口返回顺序；只有用户明确要求时才重排。分页只展示“已显示 X / 共 Y”和是否还有更多，不暴露 `page_token`。
+- 每位达人必须保留 `creator_user_id`（分析用）和 `creator_open_id`（建联用）的一一映射。ID 在界面中弱化展示，但不得丢失、混用、截断或推断。
+- 单达人只展示表现画像、数据缺口和合作建议，不生成候选集相对综合分；至少 2 位候选人才输出综合评分排行榜。
+- 多人评分固定展示综合分、五个维度分、标签，并补充逐人详情、数据缺口、合作建议和失败名单。默认按综合分、带货分、内容分、粉丝数依次降序处理并列。
+- 字段缺失显示 `—` 并说明原因；失败达人不以 0 分参与排名；禁止编造缺失指标、内容风格或合作历史。
+
+结果为 1–5 条时使用 Markdown；达到 6 条时，如果当前宿主提供 HTML/可视化产物能力，默认生成响应式 HTML 报告。用户明确要求 HTML 时不受条数限制；能力不可用或生成失败时回退完整 Markdown。
+
+HTML 报告必须自包含，只使用内联 CSS/JavaScript，不依赖 CDN、远程字体或外部图片；工具返回文本必须先做 HTML 转义。只实现真实可用的搜索、排序、展开和复制交互，不添加无法调用 Agent/MCP 的伪按钮。生成报告后仍在对话中保留简短摘要，且只有实际生成产物时才可声明存在 HTML，不得虚构文件名或 `outputs` 路径。
+
 ## 行为准则
 
 1. **单步确认，多步通报**：单次操作（搜索/分析单个达人）直接执行并汇报结果；批量操作（批量分析/批量建联）先确认计划再执行。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scorehub/creator-outreach",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "ScoreHub Tiky 智能体 — Agent 定义 + Skills 配置",
   "engines": {
     "node": ">=18"

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

@@ -1,3 +1,8 @@
+---
+name: tiktok-creator-analysis
+description: 获取 TikTok 达人近 30 天表现数据，按候选集相对评分模型分析、排名，并以固定 Markdown 或 WorkBuddy HTML 格式展示结果。用于达人表现分析、评分、比较、排名和合作建议请求。
+---
+
 # TikTok Creator Analysis — 达人表现分析与评分
 
 获取达人近 30 天表现数据，按 100 分制评分模型综合评估并排序。
@@ -23,10 +28,40 @@
 
 如果工具提示请求过于频繁、持续限流或配额受限，直接提醒用户耐心等待、减少本次分析人数或稍后重试；不要建议“重新授权拿一个干净的 token”，也不要主动走 `authorize`，除非用户自己明确要求重新授权。
 
-### 输出
+### 输出（固定格式）
+
+禁止直接展示 MCP 原始 JSON。评分是候选集内归一化后的**相对分**，按以下两种情况输出：
+
+#### 单个达人
+
+- 不输出综合分或五维相对分，避免单元素归一化造成虚高分数。
+- 固定展示：达人身份、近 30 天 GMV/销量、直播和视频表现、粉丝数与画像、品类分布、标签、数据缺口、优势/风险、合作建议。
+- 明确说明：“当前仅有 1 位达人，无法生成有意义的相对评分；至少需要 2 位候选人才可评分排名。”
+
+#### 两个及以上达人
+
+1. **评分摘要**：成功分析数、失败数、评分对象范围和相对评分说明。
+2. **排行榜**：固定展示“排名 / 达人 / 综合分 / 带货能力 / 内容影响力 / 粉丝规模 / 品类匹配 / 粉丝质量 / 标签”。
+3. **达人详情**：逐人展示关键原始指标、优势/风险、数据缺口、合作建议，以及从搜索上下文保留的标识。
+4. **失败名单**：部分分析失败时单列达人和用户可理解的原因，不得把失败值作为 0 分参与排序。
+5. **下一步**：建议选择达人建联、补充候选人或调整筛选，不自动发送消息。
+
+排序与字段规则：
+
+- 默认按综合分降序；并列时依次按带货能力分、内容影响力分、粉丝数降序，仍相同则保持原候选顺序。
+- 分数均按评分模型取整并以 `/100` 展示；品类数据未授权或维度无法计算时显示 `—` 和原因，不用无说明的 0 分掩盖缺口。
+- 必须保留搜索结果中的 `creator_user_id` 和 `creator_open_id` 映射。`creator_performance` 不返回 `creator_open_id`，只能从当前对话中的搜索结果透传，不能猜测或推断。
+- 无法关联 `creator_open_id` 时显示“未保留建联标识”，并说明该达人暂不能直接建联；Markdown 中弱化为详情末项，HTML 中放入可展开复制区域。
+- 建议必须由实际指标、维度分、相对排名和数据缺口支撑，不得编造内容风格、合作历史或转化表现。
+
+### WorkBuddy HTML 可视化
 
-- 排行榜：排名 / 昵称 / 综合评分 / 各维度分 / 标签。
-- 每个达人保留 `creator_open_id`（从搜索结果透传而来），供后续建联使用。
+- 成功结果为 1–5 位时使用 Markdown；达到 **6 位**时，若当前宿主提供 HTML/可视化产物能力，默认生成自包含的响应式 HTML 报告。用户明确要求 HTML 时不受人数限制。
+- 宿主不支持 HTML，或 HTML 生成失败时，必须回退为包含完整排行榜、详情和失败名单的 Markdown。
+- HTML 评分报告必须包含：评分摘要、可排序排行榜、五维分数、达人详情、数据缺口、合作建议和弱化的双 ID 复制区域。
+- 只使用内联 CSS/JavaScript，不依赖 CDN、远程字体或外部图片；只实现真实可用的搜索、排序、展开和复制交互，不添加无法触发 Agent 或 MCP 操作的伪按钮。
+- 昵称、用户名、标签及所有工具返回文本写入 HTML 前必须转义；禁止把工具内容作为 HTML 或脚本执行。
+- 生成 HTML 后仍需在对话中给出成功/失败数量、前三名和数据完整性的简短摘要。只有实际生成产物时才可声明存在 HTML，不得虚构文件名或 `outputs` 路径。
 
 ## 评分模型（100 分制）
 

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

@@ -1,3 +1,8 @@
+---
+name: tiktok-creator-search
+description: 在 TikTok Shop Creator Marketplace 中按关键词、类目、GMV 和市场条件搜索达人，并以固定 Markdown 或 WorkBuddy HTML 格式展示结果。用于搜索、查找、筛选 TikTok 达人或继续翻页的请求。
+---
+
 # TikTok Creator Search — 达人搜索
 
 在 TikTok Shop Creator Marketplace 中按多维度筛选搜索达人，支持翻页获取全量结果。
@@ -53,11 +58,34 @@
 
 **GMV 区间取值**：`GMV_RANGE_0_100` / `GMV_RANGE_100_1000` / `GMV_RANGE_1000_10000` / `GMV_RANGE_10000_AND_ABOVE`
 
-### 输出与后续
+### 输出与后续（固定格式）
+
+禁止直接展示 MCP 原始 JSON。每次成功搜索都按以下顺序输出：
+
+1. **结果摘要**：实际返回数、`total_count`、用户可读的搜索条件、当前排序、是否还有下一页。
+2. **达人列表**：固定展示“排名 / 昵称 / 用户名 / 粉丝数 / 近 30 天 GMV 区间 / 类目匹配 / 标识”。
+3. **分页状态**：使用“已显示 X / 共 Y；还有更多结果，可继续获取下一页”或“已显示全部结果”。不要向用户展示 `page_token`。
+4. **下一步**：只建议分析选中达人、继续翻页或调整条件，不要擅自开始批量分析或建联。
+
+格式化规则：
+
+- 默认保持 `search_creators` 返回顺序并以此编号；只有用户明确要求按某字段排序时才调整，并在摘要说明排序依据。
+- 粉丝数使用千位分隔；GMV 区间转换为用户可读值（`0–100` / `100–1K` / `1K–10K` / `10K+`）；缺失字段统一显示 `—`，不要猜测。
+- 类目匹配在使用类目筛选并完成闭环校验后显示“命中”；没有类目筛选时显示“未校验”；过滤疑似失效时不要展示为合格结果。
+- 必须为每位达人保留 `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` 多次翻页，但内部令牌永不对外展示。
+
+### WorkBuddy HTML 可视化
 
-- 结果用**表格**展示关键字段（昵称 / 用户名 / 粉丝数 / GMV 区间 / 类目），避免大段 JSON。
-- **务必透传每个达人的 `creator_open_id`**——这是后续 `create_conversation` 建联的必需字段，且**仅搜索结果返回**（分析接口不返回）。
-- 单页最多 20 条，大批量搜索需用 `page_token` 多次翻页。
+- 结果为 1–5 条时使用 Markdown 表格；达到 **6 条**时，若当前宿主提供 HTML/可视化产物能力，默认生成自包含的响应式 HTML 报告。用户明确要求 HTML 时不受条数限制。
+- 宿主不支持 HTML，或 HTML 生成失败时，必须回退为包含全部记录的 Markdown，不能只给摘要或丢失达人。
+- HTML 搜索报告必须包含：搜索条件摘要、返回数/总数/分页状态、可搜索和排序的达人表格、达人详情、双 ID 复制区域和下一步建议。
+- 只使用内联 CSS/JavaScript，不依赖 CDN、远程字体或外部图片；只实现真实可用的搜索、排序、展开和复制交互，不添加无法触发 Agent 或 MCP 操作的伪按钮。
+- 昵称、用户名及所有工具返回文本写入 HTML 前必须转义；禁止把工具内容作为 HTML 或脚本执行。
+- 生成 HTML 后仍需在对话中给出结果数量、排序和分页的简短摘要。只有实际生成产物时才可声明存在 HTML，不得虚构文件名或 `outputs` 路径。
 
 ### 类目过滤闭环校验（防静默失效）