@scorehub/creator-outreach 1.0.12 → 1.0.13
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.
package/README.md
CHANGED
|
@@ -30,6 +30,10 @@ MCP Server（`@scorehub/mcp-server`）由配置中的 `npx -y` 在首次启动
|
|
|
30
30
|
|
|
31
31
|
Tiky 首次调用 TikTok 工具时会自动打开浏览器引导登录 ScoreHub。登录一次后 Token 缓存在本地（`~/.scorehub/`），Claude Code 与 WorkBuddy 共享，无需重复授权。
|
|
32
32
|
|
|
33
|
+
如果 Tiky 提示当前店铺的 TikTok 授权已失效或异常，说明本地登录通常仍是正常的，但该店铺需要先到 ScoreHub 重新绑定后再继续使用。此时不用反复重新做浏览器登录。
|
|
34
|
+
|
|
35
|
+
如果 Tiky 提示当前请求过于频繁或配额受限，先耐心等待、分批重试或缩小本次操作范围即可，不需要为了解除限流去重新登录。只有你自己明确想重新授权时，才需要手动执行。
|
|
36
|
+
|
|
33
37
|
## 快速开始
|
|
34
38
|
|
|
35
39
|
直接对 Tiky 说：
|
|
@@ -92,10 +92,13 @@ Step 3: 批量建联
|
|
|
92
92
|
1. **单步确认，多步通报**：单次操作（搜索/分析单个达人）直接执行并汇报结果；批量操作（批量分析/批量建联）先确认计划再执行。
|
|
93
93
|
2. **建联前置确认**：批量发送前必须与你确认品牌名和佣金比例（用于模板变量替换），并让你核对消息内容。
|
|
94
94
|
3. **配额意识**：你每天有 10,000 次 API 配额，我每次操作都会告知消耗量。如果预算紧张，我会建议优先级策略。
|
|
95
|
-
4. **失败不沉默**：API
|
|
95
|
+
4. **失败不沉默**：API 调用失败时我会用中文明确告知原因和下一步处理建议，不向用户展示错误码或英文原文。
|
|
96
96
|
5. **数据可追溯**：每次搜索结果、分析报告、建联记录都保留完整，方便你后续回溯。
|
|
97
97
|
6. **不在深夜骚扰达人**：建联消息默认按达人所在时区的工作时间（9:00-21:00）发送，避免深夜打扰。
|
|
98
98
|
7. **类目解析规范**：当用户提到品类名称（如"美妆"/"电子产品"）时，必须先用 `get_categories` 解析为类目 ID，再搜索达人。绝不要凭空猜测类目 ID 或使用硬编码值。如果 `get_categories` 返回多个匹配结果，用表格展示让用户确认具体要筛选哪些类目。
|
|
99
|
+
8. **结构化错误优先**：远程工具若返回结构化 JSON，必须优先读取其中的 `error_type` 决定下一步动作，不要靠自然语言错误文本猜测。
|
|
100
|
+
9. **两层授权区分**：当 `error_type = "shop_auth_invalid"`，或者 `authorize` / `status` 正常但真实 TikTok 工具提示当前店铺授权失效、过期、撤销或异常时，我必须判断为店铺侧 TikTok 绑定问题，直接提醒用户去 ScoreHub 重新绑定该店铺；不要让用户重复本地 OAuth 登录。
|
|
101
|
+
10. **限流优先等待**：当 `error_type = "rate_limited"` 或 `error_type = "quota_exhausted"`，或者提示请求过于频繁、持续限流或配额受限时，我只会建议你耐心等待、分批执行、缩小请求范围或稍后重试；不要建议“重新授权拿一个干净的 token”，也不要主动调用 `authorize`。只有你自己明确要求重新授权时，我才会这么做。
|
|
99
102
|
|
|
100
103
|
## 调用方式
|
|
101
104
|
|
|
@@ -110,12 +113,25 @@ Step 3: 批量建联
|
|
|
110
113
|
|
|
111
114
|
如果尚未授权，我会先引导你走 `authorize` 完成 OAuth 登录。如果 MCP 工具不可用，才降级使用环境变量中的 TikTok API 凭证直接调用。
|
|
112
115
|
|
|
116
|
+
如果本地登录状态正常，但真实工具调用提示当前店铺的 TikTok 授权已失效或异常，我会直接提醒你去 ScoreHub 重新绑定该店铺后再试，不会再让你重复浏览器登录。
|
|
117
|
+
|
|
118
|
+
如果工具提示请求过于频繁、持续限流或配额受限，我会优先建议等待和稍后重试，不会因为限流自动让你重新登录。只有你自己明确要求重新授权时，我才会走 `authorize`。
|
|
119
|
+
|
|
120
|
+
如果工具返回结构化错误类型，我会按以下顺序处理：
|
|
121
|
+
|
|
122
|
+
- `oauth_invalid` → 允许建议 `authorize`
|
|
123
|
+
- `shop_auth_invalid` → 提示去 ScoreHub 重新绑定店铺
|
|
124
|
+
- `rate_limited` / `quota_exhausted` → 只提示等待、分批或缩量
|
|
125
|
+
- `invalid_input` → 只提示修正请求条件
|
|
126
|
+
|
|
113
127
|
## 限制与注意事项
|
|
114
128
|
|
|
115
129
|
- **支持市场**：当前仅支持东南亚市场——泰国（TH）、马来西亚（MY）、越南（VN）、菲律宾（PH）、印度尼西亚（ID）、新加坡（SG）。用户明确提到其他市场（如美国、日本、欧洲等）时，主动说明不支持，并建议改选以上 SEA 市场之一
|
|
116
130
|
- **日配额**：搜索和表现查询共享每日 10,000 次调用限额
|
|
131
|
+
- **限流处理**：如果请求过于频繁或短时间内持续限流，应先等待、分批执行或缩小请求范围；这类问题默认不是授权问题，也不需要为了解除限流去重新授权
|
|
117
132
|
- **单页限制**：搜索接口每次最多返回 20 条，大批量搜索需要多次翻页
|
|
118
133
|
- **建联门槛**：店铺 GMV 需达标，且店铺与达人需在同一区域
|
|
119
|
-
- **建联字段**：`create_conversation` 必须用 `creator_open_id
|
|
134
|
+
- **建联字段**：`create_conversation` 必须用 `creator_open_id`（不是 `creator_user_id`），该字段仅来自搜索结果；传错会导致建会话失败
|
|
120
135
|
- **消息配额**：单店铺对单达人有 IM 消息条数上限
|
|
136
|
+
- **店铺重新绑定**：如果本地登录状态正常，但当前店铺的 TikTok 授权失效、撤销、过期或不匹配，需要先到 ScoreHub 重新绑定该店铺，再继续搜索、分析或建联
|
|
121
137
|
- **API 版本**：当前基于 202508（搜索/表现/建会话）和 202412（消息）版本，TikTok 可能更新
|
package/package.json
CHANGED
|
@@ -24,6 +24,12 @@
|
|
|
24
24
|
1. **建会话**：调用 **`create_conversation`**，入参 `creator_open_id`（来自搜索结果），返回 `conversation_id`。
|
|
25
25
|
2. **发消息**：调用 **`send_message`**，入参 `conversation_id` + `msg_type: "TEXT"` + `content`（模板填充后的文本）。
|
|
26
26
|
|
|
27
|
+
如果工具返回结构化 JSON，优先按 `error_type` 做分流，不要靠自然语言错误文本猜测。
|
|
28
|
+
|
|
29
|
+
如果本地登录状态正常，但工具提示当前店铺的 TikTok 授权失效或异常，直接提醒用户去 ScoreHub 重新绑定该店铺后再试；不要展示错误码，也不要要求用户重复执行 `authorize`。
|
|
30
|
+
|
|
31
|
+
如果工具提示请求过于频繁、持续限流或配额受限，直接提醒用户暂停发送、耐心等待并稍后继续；不要建议“重新授权拿一个干净的 token”，也不要主动走 `authorize`，除非用户自己明确要求重新授权。
|
|
32
|
+
|
|
27
33
|
### 速率与话术
|
|
28
34
|
|
|
29
35
|
- 每条发送间隔 **5-8 秒 + 随机抖动**（间隔 <5s 会触发 429）。
|
|
@@ -38,7 +44,7 @@
|
|
|
38
44
|
|
|
39
45
|
## 关键陷阱
|
|
40
46
|
|
|
41
|
-
- `create_conversation` 必须用 **`creator_open_id`**（不是 `creator_user_id
|
|
47
|
+
- `create_conversation` 必须用 **`creator_open_id`**（不是 `creator_user_id`）。
|
|
42
48
|
- `creator_open_id` **仅来自搜索接口**，分析接口不返回——务必从搜索结果透传。
|
|
43
49
|
|
|
44
50
|
## 降级：直接 API
|
|
@@ -50,11 +56,12 @@ POST /affiliate_seller/202412/conversations/{id}/messages Body: {"msg_type":"T
|
|
|
50
56
|
|
|
51
57
|
## 错误处理
|
|
52
58
|
|
|
53
|
-
|
|
|
54
|
-
|
|
55
|
-
|
|
|
56
|
-
|
|
|
57
|
-
|
|
|
58
|
-
|
|
|
59
|
-
|
|
|
60
|
-
|
|
|
59
|
+
| 问题类型 | 处理 |
|
|
60
|
+
|----------|------|
|
|
61
|
+
| `oauth_invalid` | 仅在真正未授权或本地 OAuth 失效时，才允许提示用户调用 `authorize` |
|
|
62
|
+
| 当前店铺的 TikTok 授权失效或异常 | 用中文提醒用户：本地登录状态正常，但当前店铺需要先到 ScoreHub 重新绑定后再试；不要展示错误码，不要要求重复 `authorize` |
|
|
63
|
+
| 建会话入参不对或达人标识无效 | 检查传入的是来自搜索结果的 `creator_open_id` |
|
|
64
|
+
| 消息配额已用完或当前达人不满足发送条件 | 跳过该达人，继续后续名单 |
|
|
65
|
+
| 日配额已用完 | 停止全部 |
|
|
66
|
+
| 请求过于频繁或持续限流 | 先提醒用户暂停发送、耐心等待并稍后继续；必要时有限退避重试。不要建议重新授权；只有用户明确要求时才走 `authorize` |
|
|
67
|
+
| 参数无效 | 提示用户修正名单、消息内容或建联参数，不走授权路径 |
|
|
@@ -15,6 +15,12 @@
|
|
|
15
15
|
对候选达人**逐个**调用 MCP 工具 **`creator_performance`**（入参 `creator_user_id`），拿到表现数据后应用
|
|
16
16
|
[评分模型](./references/scoring-model.md) 打分排序。批量分析属多步操作，先与用户确认名单再执行。
|
|
17
17
|
|
|
18
|
+
如果工具返回结构化 JSON，优先按 `error_type` 做分流，不要靠自然语言错误文本猜测。
|
|
19
|
+
|
|
20
|
+
如果本地登录状态正常，但工具提示当前店铺的 TikTok 授权失效或异常，直接提醒用户去 ScoreHub 重新绑定该店铺后再试；不要展示错误码，也不要要求用户重复执行 `authorize`。
|
|
21
|
+
|
|
22
|
+
如果工具提示请求过于频繁、持续限流或配额受限，直接提醒用户耐心等待、减少本次分析人数或稍后重试；不要建议“重新授权拿一个干净的 token”，也不要主动走 `authorize`，除非用户自己明确要求重新授权。
|
|
23
|
+
|
|
18
24
|
### 输出
|
|
19
25
|
|
|
20
26
|
- 排行榜：排名 / 昵称 / 综合评分 / 各维度分 / 标签。
|
|
@@ -46,9 +52,11 @@ GET https://open-api.tiktokglobalshop.com/affiliate_seller/202508/marketplace_cr
|
|
|
46
52
|
|
|
47
53
|
## 错误处理
|
|
48
54
|
|
|
49
|
-
|
|
|
50
|
-
|
|
51
|
-
|
|
|
52
|
-
|
|
|
53
|
-
|
|
|
54
|
-
|
|
|
55
|
+
| 问题类型 | 处理 |
|
|
56
|
+
|----------|------|
|
|
57
|
+
| `oauth_invalid` | 仅在真正未授权或本地 OAuth 失效时，才允许提示用户调用 `authorize` |
|
|
58
|
+
| 当前店铺的 TikTok 授权失效或异常 | 用中文提醒用户：本地登录状态正常，但当前店铺需要先到 ScoreHub 重新绑定后再试；不要展示错误码，不要要求重复 `authorize` |
|
|
59
|
+
| 达人当前不可分析（如无电商权限或区域不匹配） | 跳过该达人，并说明当前达人不满足分析条件 |
|
|
60
|
+
| 日配额已用完 | 停止 |
|
|
61
|
+
| 请求过于频繁或持续限流 | 先提醒用户耐心等待，建议减少本次分析人数或稍后重试；必要时有限退避重试。不要建议重新授权；只有用户明确要求时才走 `authorize` |
|
|
62
|
+
| 参数无效 | 提示用户修正待分析名单或输入格式，不走授权路径 |
|
|
@@ -33,6 +33,12 @@
|
|
|
33
33
|
|
|
34
34
|
调用 MCP 工具 **`search_creators`**，不要写脚本。若已授权可直接调用；未授权时先走 `authorize`。
|
|
35
35
|
|
|
36
|
+
如果工具返回结构化 JSON，优先按 `error_type` 做分流，不要靠自然语言错误文本猜测。
|
|
37
|
+
|
|
38
|
+
如果本地登录状态正常，但工具提示当前店铺的 TikTok 授权失效或异常，直接提醒用户去 ScoreHub 重新绑定该店铺后再试；不要展示错误码，也不要要求用户重复执行 `authorize`。
|
|
39
|
+
|
|
40
|
+
如果工具提示请求过于频繁、持续限流或配额受限，直接提醒用户耐心等待、缩小搜索范围或稍后重试；不要建议“重新授权拿一个干净的 token”，也不要主动走 `authorize`，除非用户自己明确要求重新授权。
|
|
41
|
+
|
|
36
42
|
### 入参
|
|
37
43
|
|
|
38
44
|
| 参数 | 说明 |
|
|
@@ -88,7 +94,10 @@ POST https://open-api.tiktokglobalshop.com/affiliate_seller/202508/marketplace_c
|
|
|
88
94
|
|
|
89
95
|
## 错误处理
|
|
90
96
|
|
|
91
|
-
|
|
|
92
|
-
|
|
93
|
-
|
|
|
94
|
-
|
|
|
97
|
+
| 问题类型 | 处理 |
|
|
98
|
+
|----------|------|
|
|
99
|
+
| `oauth_invalid` | 仅在真正未授权或本地 OAuth 失效时，才允许提示用户调用 `authorize` |
|
|
100
|
+
| 当前店铺的 TikTok 授权失效或异常 | 用中文提醒用户：本地登录状态正常，但当前店铺需要先到 ScoreHub 重新绑定后再试；不要展示错误码，不要要求重复 `authorize` |
|
|
101
|
+
| 日配额已用完 | 明确告知用户，停止 |
|
|
102
|
+
| 请求过于频繁或持续限流 | 先提醒用户耐心等待，建议缩小搜索范围、减少翻页或稍后重试；必要时按 1s/2s/4s/8s/16s 有限退避重试。不要建议重新授权；只有用户明确要求时才走 `authorize` |
|
|
103
|
+
| 参数无效 | 提示用户修正搜索条件或 page_size / 类目参数，不走授权路径 |
|