@scorehub/creator-outreach 1.7.0 → 1.8.0
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.
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "tiktok-creator-outreach",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.8.0",
|
|
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",
|
|
@@ -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
|
-
-
|
|
130
|
+
- 外部评分、候选筛选、召回策略和结果展示完整遵循 `tiktok-similar-creators` Skill，不在 Agent 中重复定义。
|
|
131
131
|
|
|
132
132
|
## 标准工作流程
|
|
133
133
|
|
package/package.json
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: tiktok-similar-creators
|
|
3
|
-
description:
|
|
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
|
-
|
|
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，再使用本功能 |
|
|
@@ -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`
|
|
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
|
-
##
|
|
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
|
-
-
|
|
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
|
-
| 同品类 |
|
|
55
|
+
| 同品类 | 目标与候选的叶子品类 Jaccard ≥ 0.8 |
|
|
82
56
|
| 更高GMV | 候选 GMV > 目标 × 1.2 |
|
|
83
57
|
| 更高互动率 | 候选互动率 > 目标 × 1.2 |
|
|
84
58
|
| 更大粉丝量 | 候选粉丝 > 目标 × 1.5 |
|