@scorehub/creator-outreach 1.7.0 → 1.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/.codebuddy-plugin/plugin.json +1 -1
  2. package/agents/tiktok-creator-outreach.md +4 -4
  3. package/install.js +1 -0
  4. package/package.json +1 -1
  5. package/skills/tiktok-similar-creators/SKILL.md +10 -6
  6. package/skills/tiktok-similar-creators/references/similarity-model.md +18 -44
package/.codebuddy-plugin/plugin.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tiktok-creator-outreach",
3
- "version": "1.7.0",
3
+ "version": "1.8.1",
4
4
  "description": "ScoreHub AI's TikTok creator marketing expert for building clear creator profiles and validating focused collaboration shortlists across 13 markets in Southeast Asia, the United States, and Europe.",
5
5
  "author": {
6
6
  "name": "Ben",
package/agents/tiktok-creator-outreach.md CHANGED
@@ -27,12 +27,12 @@ skills:
27
27
 
28
28
  ## 新会话首轮引导（最高优先级）
29
29
 
30
- 每个新对话的第一条回复，**无论用户输入问候、快捷指令、账号/店铺切换还是具体业务需求**，都必须先完成 WorkBuddy bootstrap 门禁。bootstrap 未完成时不执行搜索、分析、建联、`authorize` 或 `status`，也不输出标准欢迎语。
30
+ 每个新对话的第一条回复，**无论用户输入问候、快捷指令、账号/店铺切换还是具体业务需求**，都必须先完成 WorkBuddy bootstrap 门禁。bootstrap 未完成时不执行搜索、分析、建联或 `authorize`，也不输出标准欢迎语。`restart_required` 分支允许仅为验证重启是否生效而调用本地 `status`，不得把该调用当作业务操作。
31
31
 
32
32
  首先执行 `npx -y @scorehub/creator-outreach@latest bootstrap --check --json`，并严格按结构化状态处理：
33
33
 
34
34
  - `uninitialized`：只告知用户 Tiky 需要安装 ScoreHub 本地组件才能使用达人能力，且不会清除现有授权数据；**必须等待用户明确确认**。确认后执行 `npx -y @scorehub/creator-outreach@latest bootstrap --install --json`。返回 `restart_required` 后提示完全退出并重启 WorkBuddy，本轮结束。这次确认同时代表用户允许后续静默更新，不再对每个 creator-outreach 新版本重复询问。
35
- - `restart_required`：若当前 `status` 已可用，且返回 `config_source.managed_by = "@scorehub/creator-outreach"` 与 `config_source.client_host = "workbuddy"`，执行 `npx -y @scorehub/creator-outreach@latest bootstrap --mark-ready --json` 清除重启标记并继续；否则只提示完全退出并重启 WorkBuddy，不进入业务流程。
35
+ - `restart_required`：仅为确认重启是否生效调用本地 `status`。若返回 `config_source.managed_by = "@scorehub/creator-outreach"`、`config_source.client_host = "workbuddy"`，且 `config_source.creator_outreach_version` 与本次 bootstrap 检查返回的 `installed_creator_outreach_version` 一致，执行 `npx -y @scorehub/creator-outreach@latest bootstrap --mark-ready --json` 清除重启标记并继续；若 `status` 不可用、版本不一致、返回其他托管信息或调用失败，只提示完全退出并重启 WorkBuddy，不进入业务流程。
36
36
  - `repair_required`：说明结果中的可恢复原因。若明确是 Node.js / npm / npx 问题，进入“本地运行环境恢复”；其他情况经用户确认后重试 `bootstrap --install --json`。修复前不进入业务流程。
37
37
  - `ready`：仅当结果同时返回 `update_due = true` 时，执行 `npx -y @scorehub/creator-outreach@latest bootstrap --update --silent --json`；否则直接继续。更新返回 `ready` 时继续；返回 `restart_required` 时可继续使用当前已加载版本，但需在首轮末尾简短提示重启后使用新版本。网络检查失败但现有 MCP 仍可用时，保留当前版本并继续，不误判为 OAuth 问题。
38
38
 
@@ -124,10 +124,10 @@ bootstrap 返回 `ready` 后，再识别以下明确意图：
124
124
  - 发送前确认、会话创建、消息类型、话术、速率和进度展示完整遵循 `tiktok-batch-outreach` Skill，不在 Agent 中重复定义。
125
125
 
126
126
  ### 4. 相似达人推荐
127
- 以某位达人为模板，通过多路召回和两阶段加权评分找到表现特征相似的其他达人。
127
+ 以某位达人为模板，通过多路召回、候选粗排和外部相似度服务找到表现特征相似的其他达人。
128
128
  - 输入目标达人的 `creator_open_id`（来自搜索结果的唯一标识），返回按相似度降序排名的 Top-N 推荐列表。
129
129
  - 默认返回 20 位相似达人，可按需调整为 1–50。
130
- - 相似度计算、两阶段评分、召回策略和结果展示完整遵循 `tiktok-similar-creators` Skill，不在 Agent 中重复定义。
130
+ - 外部评分、候选筛选、召回策略和结果展示完整遵循 `tiktok-similar-creators` Skill，不在 Agent 中重复定义。
131
131
 
132
132
  ## 标准工作流程
133
133
 
package/install.js CHANGED
@@ -316,6 +316,7 @@ function check({
316
316
  status: detected.status,
317
317
  reason: detected.reason,
318
318
  creator_outreach_version: pkg.version,
319
+ installed_creator_outreach_version: state.creator_outreach_version,
319
320
  consent_granted: state.consent_granted,
320
321
  mcp_configured: detected.status === 'ready' || detected.status === 'restart_required',
321
322
  restart_required: state.restart_required,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@scorehub/creator-outreach",
3
- "version": "1.7.0",
3
+ "version": "1.8.1",
4
4
  "description": "ScoreHub AI TikTok达人营销专家 Tiky — Agent 定义 + Skills 配置",
5
5
  "engines": {
6
6
  "node": ">=18"
package/skills/tiktok-similar-creators/SKILL.md CHANGED
@@ -1,11 +1,11 @@
1
1
  ---
2
2
  name: tiktok-similar-creators
3
- description: 以目标达人为模板，通过多路召回和两阶段加权评分寻找表现特征相似的达人，返回按相似度降序排列的 Top-N 推荐列表。用于"找相似达人"、"以他为模板"、"有没有类似的达人"等请求。
3
+ description: 以目标达人为模板，通过多路召回、候选粗排和外部相似度服务寻找表现特征相似的达人，返回按相似度降序排列的 Top-N 推荐列表。用于"找相似达人"、"以他为模板"、"有没有类似的达人"等请求。
4
4
  ---
5
5
 
6
6
  # TikTok Similar Creators — 相似达人推荐
7
7
 
8
- 以某位达人为模板，基于多路召回和加权评分找到带货表现特征相似的其他达人。
8
+ 以某位达人为模板，基于多路召回和外部相似度评分找到带货表现特征相似的其他达人。
9
9
 
10
10
  本文件是相似达人推荐专项行为的权威来源；Agent 只保留能力摘要。若执行流程、输出或失败处理存在冲突，以本文件为准。
11
11
 
@@ -25,9 +25,9 @@ description: 以目标达人为模板，通过多路召回和两阶段加权评
25
25
  |------|------|--------|------|
26
26
  | `creator_user_id` | ✅ | — | 目标达人的 `creator_open_id`，只能来自当前对话上下文中的搜索结果，不可编造 |
27
27
  | `top_n` | ❌ | 20 | 返回数量（1–50） |
28
- | `include_reasoning` | ❌ | true | 是否包含各维度相似度得分 |
28
+ | `include_reasoning` | ❌ | true | 是否包含外部服务返回的相似度 breakdown |
29
29
 
30
- 相似度模型、召回策略、权重和标签规则的唯一权威来源是 [相似达人推荐模型](./references/similarity-model.md)，本 Skill 不重复其实现细节。
30
+ 相似度服务接口、评分流程、召回策略和标签规则的唯一权威来源是 [相似达人推荐模型](./references/similarity-model.md)，外部服务请求字段以仓库顶层的 [达人相似度服务调用说明](../../../../creator-similarity-api.md) 为准；本 Skill 不重复实现细节。
31
31
 
32
32
  授权、限流、MCP 不可用和本地运行环境恢复遵循 Agent 的权威规则，本技能不重复展开。
33
33
 
@@ -60,6 +60,8 @@ description: 以目标达人为模板，通过多路召回和两阶段加权评
60
60
 
61
61
  - "亮点"列展示 `differentiator_tags`（以 "·" 连接），无标签时显示 `—`。
62
62
  - 相似度保留两位小数。
63
+ - 每个结果的 `similarity_confidence` 单独展示为数据置信度；它不等于相似度，低置信度时提示数据不足。
64
+ - 外部服务返回 `similarity_config_version` 时作为结果诊断信息保留。
63
65
  - 保留每位达人的 `creator_open_id` 供后续分析或建联使用。
64
66
 
65
67
  **3. 召回说明** — 简短一行：
@@ -72,7 +74,7 @@ description: 以目标达人为模板，通过多路召回和两阶段加权评
72
74
  - HTML 报告的共享品牌配色遵循 Agent 的"WorkBuddy HTML 共享配色"契约，本 Skill 不自行定义。
73
75
  - 结果 ≥ 6 位时，若当前宿主提供 HTML/可视化产物能力，默认生成自包含的响应式 HTML 报告。用户明确要求 HTML 时不受人数限制。
74
76
  - 宿主不支持 HTML 或生成失败时，回退为 Markdown 表格 + 摘要。
75
- - HTML 报告必须包含：目标达人摘要卡片、相似达人排名列表（含相似度分、亮点标签、各维度得分展开区）、召回说明。
77
+ - HTML 报告必须包含：目标达人摘要卡片、相似达人排名列表（含相似度分、亮点标签、外部服务 breakdown 展开区）、召回说明。
76
78
  - 只使用内联 CSS/JavaScript，不依赖 CDN、远程字体或外部图片。
77
79
  - 昵称、用户名及所有工具返回文本写入 HTML 前必须转义。
78
80
 
@@ -81,8 +83,10 @@ description: 以目标达人为模板，通过多路召回和两阶段加权评
81
83
  | 情况 | 处理方式 |
82
84
  |------|---------|
83
85
  | 目标达人 Performance 查询失败 | 根据结构化错误（`shop_auth_invalid`/`oauth_invalid`/`rate_limited`等）按 Agent 规则分流 |
86
+ | 所有可执行的召回渠道均失败 | 保留最需处理的结构化错误并按 Agent 规则分流，不展示为“未找到候选” |
84
87
  | 候选池为空（无人召回） | 说明该达人在当前市场的可召回范围（品类、粉丝量级、全市场）均未找到其他达人，建议换一个目标达人再试 |
85
- | 候选池非空但精排后全部失败 | 展示目标达人摘要，说明精排阶段调用失败，建议稍后重试或换目标达人 |
88
+ | 候选池非空但候选 Performance 全部失败 | 保留最需处理的结构化错误并按 Agent 规则分流，不调用相似度服务 |
86
89
  | 精排候选全部成功但相似度偏低（最高分 < 0.3） | 结果仍正常展示，但在摘要中提示"未找到高度相似的达人，当前结果仅供参考" |
87
90
  | `rate_limited` / `quota_exhausted` | 建议等待后重试，不主动调用 `authorize` |
91
+ | 外部相似度服务未配置或不可用 | 返回结构化错误，提示检查服务配置或稍后重试；不切换到其他评分方法 |
88
92
  | 上下文中没有 `creator_open_id` | 引导先搜索达人（`tiktok-creator-search` Skill）获取 ID，再使用本功能 |
package/skills/tiktok-similar-creators/references/similarity-model.md CHANGED
@@ -2,58 +2,32 @@
2
2
 
3
3
  本文件是相似度评分模型的唯一权威 Reference。`tiktok-similar-creators` Skill 和 Agent 只做引用摘要，不重复展开。
4
4
 
5
- ## 一、两阶段评分
5
+ ## 一、外部评分与两阶段流程
6
+
7
+ 外部双达人相似度服务是 `find_similar_creators` 的唯一评分来源，接口字段和错误契约见仓库顶层的 [达人相似度服务调用说明](../../../../../creator-similarity-api.md)。调用 `POST /v1/creator-similarities` 时，目标达人和候选达人均使用 TikTok Performance 返回的 `data.creator` 对象。
8
+
9
+ - 外部服务返回的 `similarity_score`（0–100）在 MCP 层归一化为 0–1 后再展示。
10
+ - 外部服务为每个评分结果返回 `confidence`；它是数据覆盖置信度，不是相似度，低置信度结果必须标明数据不足，不能仅按分数解读。
11
+ - 外部结果是最终排序唯一依据，不与其他评分方法平均或加权混合。
12
+ - 服务未配置、调用失败或响应不符合契约时返回结构化错误，不返回替代评分结果。
13
+
14
+ 召回和候选预算仍由 `find_similar_creators` 负责：三路召回合并去重后最多保留 24 位，默认最多对 12 位候选获取 Performance 并送入评分服务。粗排只用于控制 TikTok Performance 调用量，不作为最终对外分数。
6
15
 
7
16
  | 阶段 | 数据源 | API 调用 | 维度 | 用途 |
8
17
  |------|--------|---------|------|------|
9
18
  | 粗排 | `searchCreators` 返回字段 | 0 | 品类 + 粉丝量 | 从候选池（≤24）筛出 Top-K 进入精排 |
10
- | 精排 | `getCreatorPerformance` 全量指标 | ≤12 | 6 维完整评分 | 排序取 Top-N 返回 |
19
+ | 精排 | `getCreatorPerformance` + 外部相似度服务 | TikTok ≤12 + 服务 1 次 | 以服务返回的分数和 breakdown 为准 | 排序取 Top-N 返回 |
11
20
 
12
21
  粗排 Top-K 计算：`K = min(ceil(top_n × 1.5), 12)`。
13
22
 
14
- ## 二、6 个维度及权重（精排）
15
-
16
- | 维度 | 权重 | 相似度函数 | 数据字段 |
17
- |------|------|-----------|----------|
18
- | 品类匹配 | 0.25 | Jaccard（交集/并集） | `category_ids`（叶子 ID，两侧同层级可比） |
19
- | 粉丝量级 | 0.20 | `1 - \|log10(fA) - log10(fB)\| / 6` | `follower_count` |
20
- | GMV | 0.20 | `1 - \|A-B\| / max(A,B)` | `gmv.amount`（parseFloat） |
21
- | 互动率 | 0.15 | `1 - \|A-B\| / max(A,B)` | 见互动率取值规则 |
22
- | 客单价 | 0.10 | `1 - \|A-B\| / max(A,B)` | `gmv.amount / units_sold` |
23
- | 内容形式 | 0.10 | 匹配 = 1，否则 = 0 | 见内容形式推断规则 |
24
-
25
- ### 品类匹配字段约束（关键）
23
+ ## 二、召回字段约束
26
24
 
27
25
  `search_creators` 的 `category` 参数只接受**顶层类目 ID**（`parent_id == "0"`），描述明文「禁止传更深层 ID」。
28
26
  - **召回用**：目标达人的 `category_gmv_distribution[].category_id`（顶级父类目 ID，与 `get_categories` 顶层 `id` 同级）。
29
- - **相似度计算用**：目标与候选的 `category_ids`（叶子 ID）做 Jaccard——两侧字段同层级，可比。
27
+ - **候选粗排与展示标签用**：目标与候选的 `category_ids`（叶子 ID）做 Jaccard；该值不作为最终相似度。
30
28
  - **禁止混用**：不可将叶子 `category_ids` 传入 `searchCreators` 的 `parent_category_id`，否则被搜索接口静默忽略，返回无关达人。
31
29
 
32
- ## 三、互动率取值规则
33
-
34
- 先用 `inferContentFormat` 判断内容形式，再按形式取对应互动率：
35
-
36
- | 内容形式 | 互动率取值 |
37
- |----------|-----------|
38
- | 直播型 | `parseFloat(ec_live_engagement_rate) / 100` |
39
- | 视频型 | `parseFloat(ec_video_engagement_rate) / 100` |
40
- | 混合型 | 两者均值（缺失或为 "0" 的一侧不计入分母） |
41
-
42
- 字段单位为**百分之一百分点**（如 `"6000"` = 60%），使用前 `/100` 换算为百分比值。
43
- 缺失率记为 0，不参与均值时跳过。
44
-
45
- ## 四、内容形式推断规则
46
-
47
- 从 `ec_live_count` 和 `ec_video_count` 推断：
48
-
49
- | 条件 | 结果 |
50
- |------|------|
51
- | 两者均为 0 | `mixed` |
52
- | 直播占比 > 70% | `live` |
53
- | 视频占比 > 70% | `video` |
54
- | 其他 | `mixed` |
55
-
56
- ## 五、3 路召回策略
30
+ ## 三、3 路召回策略
57
31
 
58
32
  | 召回路径 | 搜索参数 | 取前 | 触发条件 |
59
33
  |----------|---------|------|----------|
@@ -63,7 +37,7 @@
63
37
 
64
38
  各路结果合并 → 按 `creator_open_id` 去重 → 排除目标自身 → **上限 24 人**。
65
39
 
66
- ## 六、粗排公式
40
+ ## 四、粗排公式
67
41
 
68
42
  仅用 `searchCreators` 已返回字段（品类 + 粉丝量），零额外 API 调用：
69
43
 
@@ -72,13 +46,13 @@ coarseScore = computeCategorySimilarity(targetCatIds, candidateCategoryIds) × (
72
46
  + computeFollowerSimilarity(targetFollowers, candidateFollowers) × (0.20/0.45)
73
47
  ```
74
48
 
75
- 权重归一化至总和 1。
49
+ 权重归一化至总和 1。该分数只决定哪些候选进入外部评分，不能写入 `similarity_score`，也不能作为失败时的替代结果。
76
50
 
77
- ## 七、差异化标签规则
51
+ ## 五、差异化标签规则
78
52
 
79
53
  | 标签 | 触发条件 |
80
54
  |------|---------|
81
- | 同品类 | 精排品类 Jaccard ≥ 0.8 |
55
+ | 同品类 | 目标与候选的叶子品类 Jaccard ≥ 0.8 |
82
56
  | 更高GMV | 候选 GMV > 目标 × 1.2 |
83
57
  | 更高互动率 | 候选互动率 > 目标 × 1.2 |
84
58
  | 更大粉丝量 | 候选粉丝 > 目标 × 1.5 |