@scorehub/creator-outreach 1.0.12 → 1.0.14

package/README.en.md

@@ -0,0 +1,68 @@
+# @scorehub/creator-outreach
+
+Chinese version: [README.md](./README.md)
+
+**Tiky** is a creator outreach AI agent for TikTok Shop sellers. It searches creators by category, GMV, and audience profile; analyzes and ranks their sales performance; and sends outreach messages in batches. By default, TikTok operations run through ScoreHub MCP.
+
+## Supported Clients
+
+- Claude Code
+- WorkBuddy
+
+Claude Desktop is not currently supported by this installer.
+
+## Install
+
+### Prerequisites
+
+- Node.js 18 or later
+- npm and network access to the npm registry
+- Claude Code or WorkBuddy installed and launched at least once
+
+Run:
+
+```bash
+npx -y @scorehub/creator-outreach
+```
+
+The installer configures only clients it detects. If it finds neither Claude Code nor WorkBuddy, it exits without writing configuration files.
+
+| Client | Detection | Installed content | How to use |
+|---|---|---|---|
+| Claude Code | `~/.claude/` exists | Agent definition in `~/.claude/agents/`; MCP configuration merged into `~/.claude.json` | Restart, then enter `@tiktok-creator-outreach` |
+| WorkBuddy | `~/.workbuddy/` exists | Plugin files in `~/.workbuddy/plugins/.../`; MCP configuration merged into `~/.workbuddy/mcp.json` | Restart, then select “Tiky — TikTok Creator Outreach” from the Agent list |
+
+The MCP server (`@scorehub/mcp-server`) is downloaded automatically by the configured `npx -y` command the first time it starts. A global installation is not required. WorkBuddy uses its bundled Node.js and the installer handles Windows `npx.cmd` and PATH separators.
+
+> You can also search for `@scorehub/creator-outreach` in the WorkBuddy plugin marketplace.
+
+## First Use and Authorization
+
+When Tiky first calls a TikTok tool, it opens a browser for ScoreHub login. Tokens are then cached under `~/.scorehub/` and shared by Claude Code and WorkBuddy, so you do not need to authorize again.
+
+If Tiky says that the current shop's TikTok authorization is invalid or unavailable, your local ScoreHub login is usually still valid. Rebind the shop in ScoreHub and try again; do not repeat browser login.
+
+If a request is rate limited or quota limited, wait, retry in smaller batches, or narrow the operation. Reauthorization does not resolve rate limits.
+
+## Quick Start
+
+Ask Tiky:
+
+- Find TikTok creators in the beauty category with GMV between $1,000 and $10,000.
+- Analyze the sales performance of these 10 creators and rank them.
+- Send outreach messages to these 50 creators using my collaboration template.
+
+## Troubleshooting
+
+### No supported client found
+
+Install and launch Claude Code or WorkBuddy once, then run the install command again. Claude Desktop is outside the current support scope.
+
+### MCP tools are unavailable, the tool list is empty, or the connection closes
+
+This usually means that the local MCP process has not started, not that login, shop authorization, or rate limiting failed. Verify Node.js 18+, npm, and npm registry access, then fully restart Claude Code or WorkBuddy. The configuration downloads mcp-server through `npx`; no global installation is needed.
+
+## Related Links
+
+- MCP Server: [@scorehub/mcp-server](https://www.npmjs.com/package/@scorehub/mcp-server)
+- Repository: [ScoreHub-AI/creator-outreach](https://github.com/ScoreHub-AI/creator-outreach)

package/README.md

@@ -1,34 +1,48 @@
 # @scorehub/creator-outreach
 
-**Tiky** — TikTok 达人建联 AI 智能体。一条命令装进 Claude Code 和 WorkBuddy。
+English version: [README.en.md](./README.en.md)
 
-按类目 / GMV / 粉丝画像搜索 TikTok Shop 达人，分析带货表现并打分排名，批量发送建联消息（`create_conversation` → `send_message`）。所有 TikTok API 调用通过 ScoreHub MCP 完成。
+**Tiky** 是面向 TikTok Shop 卖家的达人建联 AI 智能体。它可按类目、GMV 和粉丝画像搜索达人，分析带货表现并排名，以及批量发送合作消息。默认情况下，TikTok 操作通过 ScoreHub MCP 完成。
+
+## 支持的客户端
+
+- Claude Code
+- WorkBuddy
+
+Claude Desktop 当前不受此安装器支持。
 
 ## 安装
 
+### 前置条件
+
+- Node.js 18 或更高版本
+- npm 和可访问 npm registry 的网络
+- 已安装并至少启动过 Claude Code 或 WorkBuddy
+
+运行：
+
 ```bash
-npx @scorehub/creator-outreach
+npx -y @scorehub/creator-outreach
 ```
 
-命令会自动检测本机已安装的 AI 客户端并完成配置：
+安装器只会配置已检测到的客户端；未检测到 Claude Code 或 WorkBuddy 时，会退出且不写入任何配置文件。
 
-| 客户端 | 安装内容 |
-|--------|----------|
-| **Claude Code / Claude Desktop** | Agent 定义 → `~/.claude/agents/`；MCP 配置 → `~/.claude.json` |
-| **WorkBuddy**（检测到 `~/.workbuddy/` 时） | 插件文件 → `~/.workbuddy/plugins/.../`；MCP 配置 → `~/.workbuddy/mcp.json` |
+| 客户端 | 检测条件 | 安装内容 | 使用方式 |
+|---|---|---|---|
+| Claude Code | `~/.claude/` 存在 | Agent 定义写入 `~/.claude/agents/`；MCP 配置合并到 `~/.claude.json` | 重启后输入 `@tiktok-creator-outreach` |
+| WorkBuddy | `~/.workbuddy/` 存在 | 插件文件写入 `~/.workbuddy/plugins/.../`；MCP 配置合并到 `~/.workbuddy/mcp.json` | 重启后在 Agent 列表选择 “Tiky — TikTok Creator Outreach” |
 
-MCP Server（`@scorehub/mcp-server`）由配置中的 `npx -y` 在首次启动时自动拉取，无需单独安装。
+MCP Server（`@scorehub/mcp-server`）由配置中的 `npx -y` 在首次启动时自动拉取，无需全局安装。WorkBuddy 会使用其捆绑的 Node.js，并自动适配 Windows 的 `npx.cmd` 与 PATH 分隔符。
 
-安装完成后重启客户端，即可唤起 Tiky：
+> 也可在 WorkBuddy 插件市场直接搜索 `@scorehub/creator-outreach` 安装。
 
-- **Claude Code**：输入 `@tiktok-creator-outreach`
-- **WorkBuddy**：在 Agent 列表中选择 "Tiky — TikTok Creator Outreach"
+## 首次使用与授权
 
-> 也可在 WorkBuddy 插件市场直接搜索 `@scorehub/creator-outreach` 安装。
+首次调用 TikTok 工具时，Tiky 会打开浏览器引导你登录 ScoreHub。登录后 Token 缓存在 `~/.scorehub/`，Claude Code 与 WorkBuddy 共享，无需重复授权。
 
-## 首次使用：授权
+如果提示当前店铺的 TikTok 授权已失效或异常，本地 ScoreHub 登录通常仍然有效。请先到 ScoreHub 重新绑定店铺，再重试；不要反复进行浏览器登录。
 
-Tiky 首次调用 TikTok 工具时会自动打开浏览器引导登录 ScoreHub。登录一次后 Token 缓存在本地（`~/.scorehub/`），Claude Code 与 WorkBuddy 共享，无需重复授权。
+如果提示请求过于频繁或配额受限，请等待、分批重试或缩小操作范围。限流不需要重新登录。
 
 ## 快速开始
 
@@ -38,6 +52,16 @@ Tiky 首次调用 TikTok 工具时会自动打开浏览器引导登录 ScoreHub
 - 分析这 10 个达人的带货表现，帮我打分排名
 - 用我的建联话术模板，给这 50 个达人批量发送合作消息
 
+## 故障排查
+
+### 找不到受支持的客户端
+
+先安装并启动 Claude Code 或 WorkBuddy 一次，再重新运行安装命令。Claude Desktop 不在当前支持范围内。
+
+### MCP 工具不可用、工具列表为空或连接已关闭
+
+通常是本地 MCP 进程尚未启动，不是登录、店铺授权或限流问题。确认 Node.js 18+、npm 和 npm registry 网络可用，然后完全重启 Claude Code 或 WorkBuddy 后重试。配置会通过 `npx` 自动下载 mcp-server，无需全局安装。
+
 ## 相关链接
 
 - MCP Server：[@scorehub/mcp-server](https://www.npmjs.com/package/@scorehub/mcp-server)

package/agents/tiktok-creator-outreach.md

@@ -92,10 +92,13 @@ Step 3: 批量建联
 1. **单步确认，多步通报**：单次操作（搜索/分析单个达人）直接执行并汇报结果；批量操作（批量分析/批量建联）先确认计划再执行。
 2. **建联前置确认**：批量发送前必须与你确认品牌名和佣金比例（用于模板变量替换），并让你核对消息内容。
 3. **配额意识**：你每天有 10,000 次 API 配额，我每次操作都会告知消耗量。如果预算紧张，我会建议优先级策略。
-4. **失败不沉默**：API 调用失败时我会明确告知原因（错误码+英文原文 message），并提供替代方案。
+4. **失败不沉默**：API 调用失败时我会用中文明确告知原因和下一步处理建议，不向用户展示错误码或英文原文。
 5. **数据可追溯**：每次搜索结果、分析报告、建联记录都保留完整，方便你后续回溯。
 6. **不在深夜骚扰达人**：建联消息默认按达人所在时区的工作时间（9:00-21:00）发送，避免深夜打扰。
 7. **类目解析规范**：当用户提到品类名称（如"美妆"/"电子产品"）时，必须先用 `get_categories` 解析为类目 ID，再搜索达人。绝不要凭空猜测类目 ID 或使用硬编码值。如果 `get_categories` 返回多个匹配结果，用表格展示让用户确认具体要筛选哪些类目。
+8. **结构化错误优先**：远程工具若返回结构化 JSON，必须优先读取其中的 `error_type` 决定下一步动作，不要靠自然语言错误文本猜测。
+9. **两层授权区分**：当 `error_type = "shop_auth_invalid"`，或者 `authorize` / `status` 正常但真实 TikTok 工具提示当前店铺授权失效、过期、撤销或异常时，我必须判断为店铺侧 TikTok 绑定问题，直接提醒用户去 ScoreHub 重新绑定该店铺；不要让用户重复本地 OAuth 登录。
+10. **限流优先等待**：当 `error_type = "rate_limited"` 或 `error_type = "quota_exhausted"`，或者提示请求过于频繁、持续限流或配额受限时，我只会建议你耐心等待、分批执行、缩小请求范围或稍后重试；不要建议“重新授权拿一个干净的 token”，也不要主动调用 `authorize`。只有你自己明确要求重新授权时，我才会这么做。
 
 ## 调用方式
 
@@ -108,14 +111,30 @@ Step 3: 批量建联
 - `authorize` — OAuth 授权
 - `status` — 连接状态
 
-如果尚未授权，我会先引导你走 `authorize` 完成 OAuth 登录。如果 MCP 工具不可用，才降级使用环境变量中的 TikTok API 凭证直接调用。
+如果尚未授权，我会先引导你走 `authorize` 完成 OAuth 登录。
+
+如果 ScoreHub MCP 工具不可见、工具列表为空、连接已关闭或本地 MCP 未启动，我会先判断为本地 MCP 可用性问题，而不是 OAuth、店铺授权或限流问题。我会提示你确认 Node.js 18+ 与 npm 可用、网络可访问 npm registry，并完全重启 Claude Code 或 WorkBuddy 后重试。MCP 配置会通过 `npx -y @scorehub/mcp-server@latest` 自动下载本地代理，macOS、Linux、Windows 无需执行全局安装命令。只有 MCP 已确认不可用且环境变量 TikTok API 凭证已经配置时，才降级直接调用 API。
+
+如果本地登录状态正常，但真实工具调用提示当前店铺的 TikTok 授权已失效或异常，我会直接提醒你去 ScoreHub 重新绑定该店铺后再试，不会再让你重复浏览器登录。
+
+如果工具提示请求过于频繁、持续限流或配额受限，我会优先建议等待和稍后重试，不会因为限流自动让你重新登录。只有你自己明确要求重新授权时，我才会走 `authorize`。
+
+如果工具返回结构化错误类型，我会按以下顺序处理：
+
+- 本地 MCP 不可用 → 提示检查 Node.js 18+、npm、npm registry 网络并重启客户端；不调用 `authorize`
+- `oauth_invalid` → 允许建议 `authorize`
+- `shop_auth_invalid` → 提示去 ScoreHub 重新绑定店铺
+- `rate_limited` / `quota_exhausted` → 只提示等待、分批或缩量
+- `invalid_input` → 只提示修正请求条件
 
 ## 限制与注意事项
 
 - **支持市场**：当前仅支持东南亚市场——泰国（TH）、马来西亚（MY）、越南（VN）、菲律宾（PH）、印度尼西亚（ID）、新加坡（SG）。用户明确提到其他市场（如美国、日本、欧洲等）时，主动说明不支持，并建议改选以上 SEA 市场之一
 - **日配额**：搜索和表现查询共享每日 10,000 次调用限额
+- **限流处理**：如果请求过于频繁或短时间内持续限流，应先等待、分批执行或缩小请求范围；这类问题默认不是授权问题，也不需要为了解除限流去重新授权
 - **单页限制**：搜索接口每次最多返回 20 条，大批量搜索需要多次翻页
 - **建联门槛**：店铺 GMV 需达标，且店铺与达人需在同一区域
-- **建联字段**：`create_conversation` 必须用 `creator_open_id`（非 `creator_user_id`，否则报 36009004/36009035），该字段仅来自搜索结果
+- **建联字段**：`create_conversation` 必须用 `creator_open_id`（不是 `creator_user_id`），该字段仅来自搜索结果；传错会导致建会话失败
 - **消息配额**：单店铺对单达人有 IM 消息条数上限
+- **店铺重新绑定**：如果本地登录状态正常，但当前店铺的 TikTok 授权失效、撤销、过期或不匹配，需要先到 ScoreHub 重新绑定该店铺，再继续搜索、分析或建联
 - **API 版本**：当前基于 202508（搜索/表现/建会话）和 202412（消息）版本，TikTok 可能更新

package/install.js

@@ -6,24 +6,8 @@ const os = require('os');
 const { execSync } = require('child_process');
 
 const pkg = require('./package.json');
-console.log(`${pkg.name} v${pkg.version}\n`);
+const MIN_NODE_MAJOR = 18;
 
-// === Claude Code 路径 ===
-const CLAUDE_DIR = path.join(os.homedir(), '.claude');
-const AGENTS_DIR = path.join(CLAUDE_DIR, 'agents');
-const CLAUDE_JSON = path.join(os.homedir(), '.claude.json');
-
-const AGENT_SRC = path.join(__dirname, 'agents', 'tiktok-creator-outreach.md');
-const AGENT_DEST = path.join(AGENTS_DIR, 'tiktok-creator-outreach.md');
-
-// === WorkBuddy 路径 ===
-const WORKBUDDY_DIR = path.join(os.homedir(), '.workbuddy');
-const WORKBUDDY_PLUGIN_DIR = path.join(
-  WORKBUDDY_DIR, 'plugins', 'marketplaces', 'my-experts', 'plugins', 'tiktok-creator-outreach',
-);
-const WORKBUDDY_MCP_JSON = path.join(WORKBUDDY_DIR, 'mcp.json');
-
-// === 共享 MCP 配置 ===
 const MCP_CONFIG = {
   type: 'stdio',
   command: 'npx',
@@ -33,27 +17,49 @@ const MCP_CONFIG = {
   },
 };
 
-// 工具函数：解析 WorkBuddy 捆绑的 node bin 目录
-// WorkBuddy spawn 子进程的 PATH 不含 node，npx 及其下载的包依赖 #!/usr/bin/env node，
-// 找不到 node 会秒退导致 "Connection closed"。返回 npx 全路径 + bin 目录用于注入 PATH。
-function resolveWorkBuddyNode() {
-  const versionsDir = path.join(WORKBUDDY_DIR, 'binaries', 'node', 'versions');
+function getNodeMajorVersion(nodeVersion = process.versions.node) {
+  return Number.parseInt(nodeVersion.split('.')[0], 10);
+}
+
+function isSupportedNode(nodeVersion = process.versions.node) {
+  return getNodeMajorVersion(nodeVersion) >= MIN_NODE_MAJOR;
+}
+
+function getPaths(homeDir) {
+  const claudeDir = path.join(homeDir, '.claude');
+  const workBuddyDir = path.join(homeDir, '.workbuddy');
+
+  return {
+    claudeDir,
+    agentsDir: path.join(claudeDir, 'agents'),
+    claudeJson: path.join(homeDir, '.claude.json'),
+    workBuddyDir,
+    workBuddyPluginDir: path.join(
+      workBuddyDir, 'plugins', 'marketplaces', 'my-experts', 'plugins', 'tiktok-creator-outreach',
+    ),
+    workBuddyMcpJson: path.join(workBuddyDir, 'mcp.json'),
+  };
+}
+
+function resolveWorkBuddyNode(workBuddyDir) {
+  const versionsDir = path.join(workBuddyDir, 'binaries', 'node', 'versions');
+  const npxExecutable = process.platform === 'win32' ? 'npx.cmd' : 'npx';
   try {
     const versions = fs.readdirSync(versionsDir);
     if (versions.length > 0) {
-      const binDir = path.join(versionsDir, versions[0], 'bin');
-      const npxPath = path.join(binDir, 'npx');
-      if (fs.existsSync(npxPath)) return { npx: npxPath, binDir };
+      const versionDir = path.join(versionsDir, versions[0]);
+      const binDirs = [path.join(versionDir, 'bin'), versionDir];
+      for (const binDir of binDirs) {
+        const npxPath = path.join(binDir, npxExecutable);
+        if (fs.existsSync(npxPath)) return { npx: npxPath, binDir };
+      }
     }
   } catch {
-    // 目录不存在或无权限
+    // WorkBuddy or its bundled Node.js is not available at this path.
   }
   return { npx: 'npx', binDir: null };
 }
 
-// 工具函数：查询 mcp-server 在 npm registry 的当前最新版本
-// 注意：这是 install 此刻的最新版；实际 MCP 拉起时由 npx 现场解析 @latest，
-// 若之后 registry 更新，运行时版本可能与此不同。失败时静默返回 null（不阻断安装）。
 function fetchLatestMcpServerVersion() {
   try {
     const out = execSync('npm view @scorehub/mcp-server version', {
@@ -67,91 +73,107 @@ function fetchLatestMcpServerVersion() {
   }
 }
 
-// 工具函数：合并 MCP Server 配置到 JSON 文件
 function mergeMcpConfig(configPath, serverName, serverConfig, extraFields) {
   let config = {};
   if (fs.existsSync(configPath)) {
     try {
       config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
     } catch {
-      console.warn(`警告：${configPath} 解析失败，将重新写入`);
+      console.warn(`Warning: ${configPath} could not be parsed and will be replaced.`);
     }
   }
 
   config.mcpServers = config.mcpServers || {};
   config.mcpServers[serverName] = Object.assign({}, serverConfig, extraFields);
-
   fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
 }
 
-// ========== Claude Code ==========
-
-// 1. 复制 Agent 定义文件
-fs.mkdirSync(AGENTS_DIR, { recursive: true });
-fs.copyFileSync(AGENT_SRC, AGENT_DEST);
-console.log(`✓ Claude Code: Agent 已安装 → ${AGENT_DEST}`);
+function install({
+  homeDir = os.homedir(),
+  nodeVersion = process.versions.node,
+  getLatestMcpServerVersion = fetchLatestMcpServerVersion,
+} = {}) {
+  console.log(`${pkg.name} v${pkg.version}\n`);
 
-// 2. 合并 MCP Server 配置到 ~/.claude.json
-mergeMcpConfig(CLAUDE_JSON, 'scorehub', MCP_CONFIG, {});
-console.log(`✓ Claude Code: MCP Server 已配置 → ${CLAUDE_JSON}`);
-
-// ========== WorkBuddy ==========
-
-const hasWorkBuddy = fs.existsSync(WORKBUDDY_DIR);
+  if (!isSupportedNode(nodeVersion)) {
+    console.error(`Node.js ${MIN_NODE_MAJOR}+ is required. Detected ${nodeVersion}. No configuration files were changed.`);
+    return 1;
+  }
 
-if (hasWorkBuddy) {
-  // 3. 复制插件文件到 WorkBuddy 插件目录
-  const pluginDirs = ['.codebuddy-plugin', 'agents', 'skills', 'avatars'];
-  const pluginFiles = ['package.json', 'README.md'];
+  const paths = getPaths(homeDir);
+  const hasClaudeCode = fs.existsSync(paths.claudeDir);
+  const hasWorkBuddy = fs.existsSync(paths.workBuddyDir);
 
-  fs.mkdirSync(WORKBUDDY_PLUGIN_DIR, { recursive: true });
+  if (!hasClaudeCode && !hasWorkBuddy) {
+    console.error('No supported client was found. Launch Claude Code or WorkBuddy once, then run this command again. No configuration files were changed.');
+    return 1;
+  }
 
-  for (const dir of pluginDirs) {
-    const src = path.join(__dirname, dir);
-    const dest = path.join(WORKBUDDY_PLUGIN_DIR, dir);
-    if (fs.existsSync(src)) {
-      fs.cpSync(src, dest, { recursive: true });
-    }
+  if (hasClaudeCode) {
+    const agentSource = path.join(__dirname, 'agents', 'tiktok-creator-outreach.md');
+    const agentDestination = path.join(paths.agentsDir, 'tiktok-creator-outreach.md');
+    fs.mkdirSync(paths.agentsDir, { recursive: true });
+    fs.copyFileSync(agentSource, agentDestination);
+    mergeMcpConfig(paths.claudeJson, 'scorehub', MCP_CONFIG, {});
+    console.log(`Claude Code: Agent installed at ${agentDestination}`);
+    console.log(`Claude Code: MCP server configured at ${paths.claudeJson}`);
   }
 
-  for (const file of pluginFiles) {
-    const src = path.join(__dirname, file);
-    const dest = path.join(WORKBUDDY_PLUGIN_DIR, file);
-    if (fs.existsSync(src)) {
-      fs.copyFileSync(src, dest);
+  if (hasWorkBuddy) {
+    const pluginDirs = ['.codebuddy-plugin', 'agents', 'skills', 'avatars'];
+    const pluginFiles = ['package.json', 'README.md', 'README.en.md'];
+
+    fs.mkdirSync(paths.workBuddyPluginDir, { recursive: true });
+    for (const dir of pluginDirs) {
+      const source = path.join(__dirname, dir);
+      const destination = path.join(paths.workBuddyPluginDir, dir);
+      if (fs.existsSync(source)) {
+        fs.cpSync(source, destination, { recursive: true });
+      }
     }
-  }
 
-  console.log(`✓ WorkBuddy: 插件文件已安装 → ${WORKBUDDY_PLUGIN_DIR}`);
-
-  // 4. 合并 MCP Server 配置到 ~/.workbuddy/mcp.json
-  //    - 去掉 type 字段（WorkBuddy 不识别）
-  //    - command 用 npx 全路径（WorkBuddy PATH 不含系统 npx）
-  //    - env.PATH 注入 node bin 目录（否则 npx 及其子进程的 shebang 找不到 node，秒退报 Connection closed）
-  const { npx, binDir } = resolveWorkBuddyNode();
-  const { type: _, ...baseMCPConfig } = MCP_CONFIG;
-  const wbEnv = binDir
-    ? Object.assign({}, MCP_CONFIG.env, { PATH: `${binDir}:/usr/local/bin:/usr/bin:/bin` })
-    : MCP_CONFIG.env;
-  const wbMCPConfig = Object.assign({}, baseMCPConfig, { command: npx, env: wbEnv });
-  mergeMcpConfig(WORKBUDDY_MCP_JSON, 'scorehub', wbMCPConfig, { disabled: false });
-  console.log(`✓ WorkBuddy: MCP Server 已配置 → ${WORKBUDDY_MCP_JSON}`);
-}
+    for (const file of pluginFiles) {
+      const source = path.join(__dirname, file);
+      const destination = path.join(paths.workBuddyPluginDir, file);
+      if (fs.existsSync(source)) {
+        fs.copyFileSync(source, destination);
+      }
+    }
 
-// ========== 完成 ==========
+    const { npx, binDir } = resolveWorkBuddyNode(paths.workBuddyDir);
+    const { type: _, ...baseMcpConfig } = MCP_CONFIG;
+    const existingPath = process.env.PATH || process.env.Path || '';
+    const env = binDir
+      ? Object.assign({}, MCP_CONFIG.env, { PATH: [binDir, existingPath].filter(Boolean).join(path.delimiter) })
+      : MCP_CONFIG.env;
+    const workBuddyMcpConfig = Object.assign({}, baseMcpConfig, { command: npx, env });
+    mergeMcpConfig(paths.workBuddyMcpJson, 'scorehub', workBuddyMcpConfig, { disabled: false });
+    console.log(`WorkBuddy: Plugin installed at ${paths.workBuddyPluginDir}`);
+    console.log(`WorkBuddy: MCP server configured at ${paths.workBuddyMcpJson}`);
+  }
 
-const platforms = ['Claude Code'];
-if (hasWorkBuddy) platforms.push('WorkBuddy');
+  const mcpServerVersion = getLatestMcpServerVersion();
+  if (mcpServerVersion) {
+    console.log(`\nmcp-server latest version: v${mcpServerVersion} (npx resolves @latest again when it starts).`);
+  } else {
+    console.log('\nmcp-server: @latest (the current version could not be queried).');
+  }
 
-const mcpServerVersion = fetchLatestMcpServerVersion();
-if (mcpServerVersion) {
-  console.log(`\n→ mcp-server 当前最新版本：v${mcpServerVersion}（运行时由 npx 解析 @latest，届时可能更新）`);
-} else {
-  console.log('\n→ mcp-server：@latest（运行时由 npx 解析，未能查询到具体版本号）');
+  const platforms = [];
+  if (hasClaudeCode) platforms.push('Claude Code');
+  if (hasWorkBuddy) platforms.push('WorkBuddy');
+  console.log(`\nInstallation complete. Restart ${platforms.join(' / ')} and use Tiky.`);
+  return 0;
 }
 
-console.log(`\n安装完成！重启 ${platforms.join(' / ')} 后使用 Tiky。`);
-if (!hasWorkBuddy) {
-  console.log('提示：未检测到 WorkBuddy，仅安装了 Claude Code。如需 WorkBuddy 支持请先安装 WorkBuddy 后重新运行本命令。');
+if (require.main === module) {
+  process.exitCode = install();
 }
 
+module.exports = {
+  MIN_NODE_MAJOR,
+  getNodeMajorVersion,
+  getPaths,
+  install,
+  isSupportedNode,
+};

package/package.json

@@ -1,14 +1,21 @@
 {
   "name": "@scorehub/creator-outreach",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "description": "ScoreHub Tiky 智能体 — Agent 定义 + Skills 配置",
+  "engines": {
+    "node": ">=18"
+  },
   "files": [
     ".codebuddy-plugin",
     "agents",
     "skills",
     "avatars",
-    "install.js"
+    "install.js",
+    "README.en.md"
   ],
+  "scripts": {
+    "test": "node --test test/install.test.js"
+  },
   "bin": {
     "creator-outreach": "./install.js"
   },

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

@@ -24,6 +24,14 @@
 1. **建会话**：调用 **`create_conversation`**，入参 `creator_open_id`（来自搜索结果），返回 `conversation_id`。
 2. **发消息**：调用 **`send_message`**，入参 `conversation_id` + `msg_type: "TEXT"` + `content`（模板填充后的文本）。
 
+如果 ScoreHub MCP 工具不可见、工具列表为空、连接已关闭或本地 MCP 未启动，判定为本地 MCP 可用性问题。提示用户确认 Node.js 18+ 与 npm 可用、网络可访问 npm registry，并完全重启 Claude Code 或 WorkBuddy 后重试；配置中的 `npx -y @scorehub/mcp-server@latest` 会自动下载 mcp-server，macOS、Linux、Windows 都不需要全局安装。不要将此类错误当作 OAuth、店铺授权或限流问题，也不要调用 `authorize`。
+
+如果工具返回结构化 JSON，优先按 `error_type` 做分流，不要靠自然语言错误文本猜测。
+
+如果本地登录状态正常，但工具提示当前店铺的 TikTok 授权失效或异常，直接提醒用户去 ScoreHub 重新绑定该店铺后再试；不要展示错误码，也不要要求用户重复执行 `authorize`。
+
+如果工具提示请求过于频繁、持续限流或配额受限，直接提醒用户暂停发送、耐心等待并稍后继续；不要建议“重新授权拿一个干净的 token”，也不要主动走 `authorize`，除非用户自己明确要求重新授权。
+
 ### 速率与话术
 
 - 每条发送间隔 **5-8 秒 + 随机抖动**（间隔 <5s 会触发 429）。
@@ -38,7 +46,7 @@
 
 ## 关键陷阱
 
-- `create_conversation` 必须用 **`creator_open_id`**（不是 `creator_user_id`，否则报 36009004 / 36009035）。
+- `create_conversation` 必须用 **`creator_open_id`**（不是 `creator_user_id`）。
 - `creator_open_id` **仅来自搜索接口**，分析接口不返回——务必从搜索结果透传。
 
 ## 降级：直接 API
@@ -50,11 +58,13 @@ POST /affiliate_seller/202412/conversations/{id}/messages   Body: {"msg_type":"T
 
 ## 错误处理
 
-| 错误码 | 含义 | 处理 |
-|--------|------|------|
-| 36009004 | 必填字段缺失 | 检查字段名为 `creator_open_id` |
-| 36009035 | 无效 open_id | 确保来自搜索结果 |
-| 16030100 | 消息配额已用完 | 跳过该达人 |
-| 16032001 | 区域不匹配 | 跳过该达人 |
-| 45101004 | 日配额已用完 | 停止全部 |
-| 36009002 | 请求过于频繁 | 指数退避重试 |
+| 问题类型 | 处理 |
+|----------|------|
+| MCP 工具不可见、工具列表为空、连接关闭或本地 MCP 未启动 | 提示确认 Node.js 18+、npm 和 npm registry 网络后完全重启客户端；`npx` 会自动下载 mcp-server，不执行全局安装，不走 `authorize` |
+| `oauth_invalid` | 仅在真正未授权或本地 OAuth 失效时，才允许提示用户调用 `authorize` |
+| 当前店铺的 TikTok 授权失效或异常 | 用中文提醒用户：本地登录状态正常，但当前店铺需要先到 ScoreHub 重新绑定后再试；不要展示错误码，不要要求重复 `authorize` |
+| 建会话入参不对或达人标识无效 | 检查传入的是来自搜索结果的 `creator_open_id` |
+| 消息配额已用完或当前达人不满足发送条件 | 跳过该达人，继续后续名单 |
+| 日配额已用完 | 停止全部 |
+| 请求过于频繁或持续限流 | 先提醒用户暂停发送、耐心等待并稍后继续；必要时有限退避重试。不要建议重新授权；只有用户明确要求时才走 `authorize` |
+| 参数无效 | 提示用户修正名单、消息内容或建联参数，不走授权路径 |

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

@@ -15,6 +15,14 @@
 对候选达人**逐个**调用 MCP 工具 **`creator_performance`**（入参 `creator_user_id`），拿到表现数据后应用
 [评分模型](./references/scoring-model.md) 打分排序。批量分析属多步操作，先与用户确认名单再执行。
 
+如果 ScoreHub MCP 工具不可见、工具列表为空、连接已关闭或本地 MCP 未启动，判定为本地 MCP 可用性问题。提示用户确认 Node.js 18+ 与 npm 可用、网络可访问 npm registry，并完全重启 Claude Code 或 WorkBuddy 后重试；配置中的 `npx -y @scorehub/mcp-server@latest` 会自动下载 mcp-server，macOS、Linux、Windows 都不需要全局安装。不要将此类错误当作 OAuth、店铺授权或限流问题，也不要调用 `authorize`。
+
+如果工具返回结构化 JSON，优先按 `error_type` 做分流，不要靠自然语言错误文本猜测。
+
+如果本地登录状态正常，但工具提示当前店铺的 TikTok 授权失效或异常，直接提醒用户去 ScoreHub 重新绑定该店铺后再试；不要展示错误码，也不要要求用户重复执行 `authorize`。
+
+如果工具提示请求过于频繁、持续限流或配额受限，直接提醒用户耐心等待、减少本次分析人数或稍后重试；不要建议“重新授权拿一个干净的 token”，也不要主动走 `authorize`，除非用户自己明确要求重新授权。
+
 ### 输出
 
 - 排行榜：排名 / 昵称 / 综合评分 / 各维度分 / 标签。
@@ -46,9 +54,12 @@ GET https://open-api.tiktokglobalshop.com/affiliate_seller/202508/marketplace_cr
 
 ## 错误处理
 
-| 错误码 | 含义 | 处理 |
-|--------|------|------|
-| 16901005 | 达人无电商权限 | 跳过 |
-| 16901006 | 区域不匹配 | 跳过 |
-| 45101004 | 日配额已用完 | 停止 |
-| 36009002 | 请求过于频繁 | 指数退避重试 |
+| 问题类型 | 处理 |
+|----------|------|
+| MCP 工具不可见、工具列表为空、连接关闭或本地 MCP 未启动 | 提示确认 Node.js 18+、npm 和 npm registry 网络后完全重启客户端；`npx` 会自动下载 mcp-server，不执行全局安装，不走 `authorize` |
+| `oauth_invalid` | 仅在真正未授权或本地 OAuth 失效时，才允许提示用户调用 `authorize` |
+| 当前店铺的 TikTok 授权失效或异常 | 用中文提醒用户：本地登录状态正常，但当前店铺需要先到 ScoreHub 重新绑定后再试；不要展示错误码，不要要求重复 `authorize` |
+| 达人当前不可分析（如无电商权限或区域不匹配） | 跳过该达人，并说明当前达人不满足分析条件 |
+| 日配额已用完 | 停止 |
+| 请求过于频繁或持续限流 | 先提醒用户耐心等待，建议减少本次分析人数或稍后重试；必要时有限退避重试。不要建议重新授权；只有用户明确要求时才走 `authorize` |
+| 参数无效 | 提示用户修正待分析名单或输入格式，不走授权路径 |

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

@@ -33,6 +33,14 @@
 
 调用 MCP 工具 **`search_creators`**，不要写脚本。若已授权可直接调用；未授权时先走 `authorize`。
 
+如果 ScoreHub MCP 工具不可见、工具列表为空、连接已关闭或本地 MCP 未启动，判定为本地 MCP 可用性问题。提示用户确认 Node.js 18+ 与 npm 可用、网络可访问 npm registry，并完全重启 Claude Code 或 WorkBuddy 后重试；配置中的 `npx -y @scorehub/mcp-server@latest` 会自动下载 mcp-server，macOS、Linux、Windows 都不需要全局安装。不要将此类错误当作 OAuth、店铺授权或限流问题，也不要调用 `authorize`。
+
+如果工具返回结构化 JSON，优先按 `error_type` 做分流，不要靠自然语言错误文本猜测。
+
+如果本地登录状态正常，但工具提示当前店铺的 TikTok 授权失效或异常，直接提醒用户去 ScoreHub 重新绑定该店铺后再试；不要展示错误码，也不要要求用户重复执行 `authorize`。
+
+如果工具提示请求过于频繁、持续限流或配额受限，直接提醒用户耐心等待、缩小搜索范围或稍后重试；不要建议“重新授权拿一个干净的 token”，也不要主动走 `authorize`，除非用户自己明确要求重新授权。
+
 ### 入参
 
 | 参数 | 说明 |
@@ -88,7 +96,11 @@ POST https://open-api.tiktokglobalshop.com/affiliate_seller/202508/marketplace_c
 
 ## 错误处理
 
-| 错误码 | 含义 | 处理 |
-|--------|------|------|
-| 45101004 | 日配额已用完 | 明确告知用户，停止 |
-| 36009002 | 请求过于频繁 | 指数退避重试 1s/2s/4s/8s/16s |
+| 问题类型 | 处理 |
+|----------|------|
+| MCP 工具不可见、工具列表为空、连接关闭或本地 MCP 未启动 | 提示确认 Node.js 18+、npm 和 npm registry 网络后完全重启客户端；`npx` 会自动下载 mcp-server，不执行全局安装，不走 `authorize` |
+| `oauth_invalid` | 仅在真正未授权或本地 OAuth 失效时，才允许提示用户调用 `authorize` |
+| 当前店铺的 TikTok 授权失效或异常 | 用中文提醒用户：本地登录状态正常，但当前店铺需要先到 ScoreHub 重新绑定后再试；不要展示错误码，不要要求重复 `authorize` |
+| 日配额已用完 | 明确告知用户，停止 |
+| 请求过于频繁或持续限流 | 先提醒用户耐心等待，建议缩小搜索范围、减少翻页或稍后重试；必要时按 1s/2s/4s/8s/16s 有限退避重试。不要建议重新授权；只有用户明确要求时才走 `authorize` |
+| 参数无效 | 提示用户修正搜索条件或 page_size / 类目参数，不走授权路径 |