@scorehub/creator-outreach 1.0.13 → 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,38 +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 当前不受此安装器支持。
 
 ## 安装
 
-```bash
-npx @scorehub/creator-outreach
-```
+### 前置条件
 
-命令会自动检测本机已安装的 AI 客户端并完成配置：
+- Node.js 18 或更高版本
+- npm 和可访问 npm registry 的网络
+- 已安装并至少启动过 Claude Code 或 WorkBuddy
 
-| 客户端 | 安装内容 |
-|--------|----------|
-| **Claude Code / Claude Desktop** | Agent 定义 → `~/.claude/agents/`；MCP 配置 → `~/.claude.json` |
-| **WorkBuddy**（检测到 `~/.workbuddy/` 时） | 插件文件 → `~/.workbuddy/plugins/.../`；MCP 配置 → `~/.workbuddy/mcp.json` |
+运行：
 
-MCP Server（`@scorehub/mcp-server`）由配置中的 `npx -y` 在首次启动时自动拉取，无需单独安装。
+```bash
+npx -y @scorehub/creator-outreach
+```
 
-安装完成后重启客户端，即可唤起 Tiky：
+安装器只会配置已检测到的客户端；未检测到 Claude Code 或 WorkBuddy 时，会退出且不写入任何配置文件。
 
-- **Claude Code**：输入 `@tiktok-creator-outreach`
-- **WorkBuddy**：在 Agent 列表中选择 "Tiky — TikTok Creator Outreach"
+| 客户端 | 检测条件 | 安装内容 | 使用方式 |
+|---|---|---|---|
+| 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` 在首次启动时自动拉取，无需全局安装。WorkBuddy 会使用其捆绑的 Node.js，并自动适配 Windows 的 `npx.cmd` 与 PATH 分隔符。
 
 > 也可在 WorkBuddy 插件市场直接搜索 `@scorehub/creator-outreach` 安装。
 
-## 首次使用：授权
+## 首次使用与授权
 
-Tiky 首次调用 TikTok 工具时会自动打开浏览器引导登录 ScoreHub。登录一次后 Token 缓存在本地（`~/.scorehub/`），Claude Code 与 WorkBuddy 共享，无需重复授权。
+首次调用 TikTok 工具时，Tiky 会打开浏览器引导你登录 ScoreHub。登录后 Token 缓存在 `~/.scorehub/`，Claude Code 与 WorkBuddy 共享，无需重复授权。
 
-如果 Tiky 提示当前店铺的 TikTok 授权已失效或异常，说明本地登录通常仍是正常的，但该店铺需要先到 ScoreHub 重新绑定后再继续使用。此时不用反复重新做浏览器登录。
+如果提示当前店铺的 TikTok 授权已失效或异常，本地 ScoreHub 登录通常仍然有效。请先到 ScoreHub 重新绑定店铺，再重试；不要反复进行浏览器登录。
 
-如果 Tiky 提示当前请求过于频繁或配额受限，先耐心等待、分批重试或缩小本次操作范围即可，不需要为了解除限流去重新登录。只有你自己明确想重新授权时，才需要手动执行。
+如果提示请求过于频繁或配额受限，请等待、分批重试或缩小操作范围。限流不需要重新登录。
 
 ## 快速开始
 
@@ -42,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

@@ -111,7 +111,9 @@ 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 重新绑定该店铺后再试，不会再让你重复浏览器登录。
 
@@ -119,6 +121,7 @@ Step 3: 批量建联
 
 如果工具返回结构化错误类型，我会按以下顺序处理：
 
+- 本地 MCP 不可用 → 提示检查 Node.js 18+、npm、npm registry 网络并重启客户端；不调用 `authorize`
 - `oauth_invalid` → 允许建议 `authorize`
 - `shop_auth_invalid` → 提示去 ScoreHub 重新绑定店铺
 - `rate_limited` / `quota_exhausted` → 只提示等待、分批或缩量

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.13",
+  "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,8 @@
 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`。
@@ -58,6 +60,7 @@ POST /affiliate_seller/202412/conversations/{id}/messages   Body: {"msg_type":"T
 
 | 问题类型 | 处理 |
 |----------|------|
+| MCP 工具不可见、工具列表为空、连接关闭或本地 MCP 未启动 | 提示确认 Node.js 18+、npm 和 npm registry 网络后完全重启客户端；`npx` 会自动下载 mcp-server，不执行全局安装，不走 `authorize` |
 | `oauth_invalid` | 仅在真正未授权或本地 OAuth 失效时，才允许提示用户调用 `authorize` |
 | 当前店铺的 TikTok 授权失效或异常 | 用中文提醒用户：本地登录状态正常，但当前店铺需要先到 ScoreHub 重新绑定后再试；不要展示错误码，不要要求重复 `authorize` |
 | 建会话入参不对或达人标识无效 | 检查传入的是来自搜索结果的 `creator_open_id` |

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

@@ -15,6 +15,8 @@
 对候选达人**逐个**调用 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`。
@@ -54,6 +56,7 @@ GET https://open-api.tiktokglobalshop.com/affiliate_seller/202508/marketplace_cr
 
 | 问题类型 | 处理 |
 |----------|------|
+| MCP 工具不可见、工具列表为空、连接关闭或本地 MCP 未启动 | 提示确认 Node.js 18+、npm 和 npm registry 网络后完全重启客户端；`npx` 会自动下载 mcp-server，不执行全局安装，不走 `authorize` |
 | `oauth_invalid` | 仅在真正未授权或本地 OAuth 失效时，才允许提示用户调用 `authorize` |
 | 当前店铺的 TikTok 授权失效或异常 | 用中文提醒用户：本地登录状态正常，但当前店铺需要先到 ScoreHub 重新绑定后再试；不要展示错误码，不要要求重复 `authorize` |
 | 达人当前不可分析（如无电商权限或区域不匹配） | 跳过该达人，并说明当前达人不满足分析条件 |

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

@@ -33,6 +33,8 @@
 
 调用 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`。
@@ -96,6 +98,7 @@ POST https://open-api.tiktokglobalshop.com/affiliate_seller/202508/marketplace_c
 
 | 问题类型 | 处理 |
 |----------|------|
+| MCP 工具不可见、工具列表为空、连接关闭或本地 MCP 未启动 | 提示确认 Node.js 18+、npm 和 npm registry 网络后完全重启客户端；`npx` 会自动下载 mcp-server，不执行全局安装，不走 `authorize` |
 | `oauth_invalid` | 仅在真正未授权或本地 OAuth 失效时，才允许提示用户调用 `authorize` |
 | 当前店铺的 TikTok 授权失效或异常 | 用中文提醒用户：本地登录状态正常，但当前店铺需要先到 ScoreHub 重新绑定后再试；不要展示错误码，不要要求重复 `authorize` |
 | 日配额已用完 | 明确告知用户，停止 |