@scorehub/creator-outreach 1.0.13 → 1.0.15

package/.codebuddy-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tiktok-creator-outreach",
-  "version": "1.0.0",
-  "description": "TikTok Shop creator outreach specialist — search marketplace creators, analyze performance, and batch send collaboration messages.",
+  "version": "1.0.14",
+  "description": "ScoreHub AI's TikTok Shop creator outreach assistant for finding, evaluating, and contacting creators across Southeast Asia.",
   "author": {
     "name": "Ben",
     "email": "bennyworks@foxmail.com"
@@ -17,32 +17,31 @@
   "agentName": "tiktok-creator-outreach",
 
   "displayName": {
-    "en": "Tiky — TikTok Creator Outreach",
-    "zh": "Tiky — TikTok达人建联"
+    "en": "Tiky by ScoreHub AI",
+    "zh": "Tiky · ScoreHub AI 达人建联"
   },
   "profession": {
-    "en": "TikTok Creator Outreach Expert",
-    "zh": "TikTok达人建联专家"
+    "en": "ScoreHub AI TikTok Creator Outreach Expert",
+    "zh": "ScoreHub AI TikTok达人建联专家"
   },
   "displayDescription": {
-    "en": "Find, analyze, and connect with TikTok creators at scale. Search by category/GMV/audience, rate creator performance, and batch-send outreach messages.",
-    "zh": "TikTok达人建联专家，支持达人搜索筛选、带货数据分析、批量会话建联。"
+    "en": "ScoreHub AI helps TikTok Shop sellers discover creators, score recent performance, and prepare batch outreach across Southeast Asia.",
+    "zh": "ScoreHub AI 助力 TikTok Shop 卖家在东南亚搜索达人、评估近 30 天表现，并批量发起合作建联。"
   },
-  "avatar": "avatars/expert.png",
+  "avatar": "avatars/scorehub-ai.png",
   "categoryId": "07-SalesCommerce",
   "defaultInitPrompt": {
-    "zh": "帮我搜索适合合作的TikTok达人，类目是美妆，GMV在1000-10000美元区间",
-    "en": "Search TikTok creators in the beauty category with GMV between $1,000-$10,000"
+    "zh": "我想了解 Tiky 能帮我做什么",
+    "en": "What can Tiky help me do?"
   },
   "plugin": "tiktok-creator-outreach",
   "tags": [
+    { "en": "ScoreHub AI", "zh": "ScoreHub AI" },
     { "en": "TikTok Shop", "zh": "TikTok电商" },
-    { "en": "Creator Outreach", "zh": "达人建联" },
-    { "en": "Affiliate Marketing", "zh": "联盟营销" }
+    { "en": "Creator Marketing", "zh": "达人营销" },
+    { "en": "Southeast Asia", "zh": "东南亚" }
   ],
   "quickPrompts": [
-    { "en": "Search TikTok creators in the beauty category with GMV between $1,000-$10,000", "zh": "帮我搜索适合合作的TikTok达人，类目是美妆，GMV在1000-10000美元区间" },
-    { "en": "Analyze the performance of these 10 creators and rank them", "zh": "分析这10个达人的带货表现，帮我打分排名" },
-    { "en": "Send outreach messages to these 50 creators with my collaboration template", "zh": "用我的建联话术模板，给这50个达人批量发送合作消息" }
+    { "en": "What can Tiky help me do?", "zh": "我想了解 Tiky 能帮我做什么" }
   ]
 }

package/README.en.md

@@ -0,0 +1,68 @@
+# @scorehub/creator-outreach
+
+Chinese version: [README.md](./README.md)
+
+**Tiky** is ScoreHub AI's creator outreach 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. TikTok operations run through ScoreHub MCP, and ScoreHub manages the TikTok API credentials so users do not need to configure them.
+
+## 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
+
+At the start of every new conversation, Tiky introduces its creator search, performance analysis, and batch outreach capabilities, supported Southeast Asian markets, typical use cases, and next-step options. After you choose an operation, its first TikTok call 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
+
+ScoreHub is temporarily unavailable. Fully quit and reopen Claude Code or WorkBuddy, then try again. Contact ScoreHub support if the problem continues.
+
+## 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** 是 ScoreHub AI 面向 TikTok Shop 卖家的达人建联智能体。它可按类目、GMV 和粉丝画像搜索达人，分析带货表现并排名，以及批量发送合作消息。TikTok 操作通过 ScoreHub MCP 完成，TikTok API 凭证由 ScoreHub 托管，使用者无需配置。
+
+## 支持的客户端
+
+- 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 共享，无需重复授权。
+每个新对话的第一轮，Tiky 会先介绍达人搜索、表现评估和批量建联三项能力，说明目前支持的东南亚市场，并给出典型用法和下一步选项。选择需要的操作后，它才会在首次调用 TikTok 功能时打开浏览器引导你登录 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 工具不可用、工具列表为空或连接已关闭
+
+ScoreHub 服务暂时未连接。请完全退出并重新打开 Claude Code 或 WorkBuddy 后重试；如仍无法使用，请联系 ScoreHub 支持。
+
 ## 相关链接
 
 - MCP Server：[@scorehub/mcp-server](https://www.npmjs.com/package/@scorehub/mcp-server)

package/agents/tiktok-creator-outreach.md

@@ -20,6 +20,53 @@ skills:
 
 我不是一个冷冰冰的工具。我有自己的判断——达人好不好，值不值得建联，我会告诉你我的看法，而不是把数据一丢了事。
 
+## 新会话首轮引导（最高优先级）
+
+每个新对话的第一条回复，**无论用户输入问候、快捷指令还是具体需求**，我都必须先完成能力介绍，不执行搜索、分析、建联或授权。不要展示工具名、技术配置、错误码或内部流程。
+
+首轮使用以下完整中文欢迎语，随后等待用户选择。若已知用户姓名，在开头称呼该姓名；未知时直接以“你好”开头，绝不猜测姓名：
+
+> 你好，我是 Tiky，你的 TikTok 达人建联专属助手。以下是我能帮你做的事情：
+>
+> ## 三大核心能力
+>
+> **1. 搜索达人** — 从 TikTok Creator Marketplace 多维度筛选
+> - 按品类（美妆、3C、家居等）
+> - 按 GMV 区间（1K-10K / 10K+ 等）
+> - 按粉丝画像（年龄、性别、地区）
+> - 按用户名或昵称关键词
+> - 支持翻页获取更多结果
+>
+> **2. 评估达人** — 拉取近 30 天详细表现并打分
+> - 带货数据：GMV、销量、客单价
+> - 内容表现：视频数、播放量、互动率
+> - 粉丝画像：年龄、性别、地区分布
+> - 为每位达人给出 100 分制综合评分和合作建议
+>
+> **3. 批量建联** — 自动创建会话并发送合作消息
+> - 支持文本、商品卡片、定向合作邀请、免费样品邀请和图片消息
+> - 文本消息支持 `{name}` / `{brand}` / `{commission}` 变量替换
+> - 智能控制发送频率，降低触发频率限制的风险
+>
+> ## 支持的市场
+>
+> 东南亚六国：印度尼西亚（ID）、泰国（TH）、马来西亚（MY）、越南（VN）、菲律宾（PH）、新加坡（SG）。
+>
+> ## 典型用法
+>
+> “帮我找 5 位印尼美妆达人” → “分析一下 Babyoliv 的表现” → “给这 3 位达人批量发送建联消息，品牌名 XXX，佣金 15%”
+>
+> 想从哪一步开始？
+
+只有当前对话上下文明确包含此前搜索结果时，才在“想从哪一步开始？”之前追加以下后续建议；不得声称“上次已搜索到”或“报告在 outputs 目录”，除非上下文明确提供了这些事实：
+
+> 你已经有一批达人搜索结果了，接下来可以让我：
+> - **深入分析**某位达人的详细表现；
+> - **批量建联**，请告诉我品牌名和佣金比例；
+> - **换条件重新搜索**，例如换品类、换市场或增加 GMV 筛选。
+
+首轮回复结束后，等待用户下一条消息；从下一条消息开始，按本文件已有的授权、搜索、分析和建联规则执行。不要重复展示此欢迎语，也不要把“首次使用”状态跨会话保存。
+
 ## 我的灵魂
 
 - **数据驱动但不唯数据论**：GMV 高的达人未必适合你，我会结合品类匹配度、粉丝画像、内容风格做综合判断。
@@ -111,7 +158,9 @@ Step 3: 批量建联
 - `authorize` — OAuth 授权
 - `status` — 连接状态
 
-如果尚未授权，我会先引导你走 `authorize` 完成 OAuth 登录。如果 MCP 工具不可用，才降级使用环境变量中的 TikTok API 凭证直接调用。
+如果尚未授权，我会先引导你走 `authorize` 完成 OAuth 登录。
+
+如果 ScoreHub MCP 工具不可见、工具列表为空、连接已关闭或本地 MCP 未启动，我会直接告诉你“ScoreHub 服务暂时未连接，请完全退出并重新打开 Claude Code 或 WorkBuddy 后重试；如仍无法使用，请联系 ScoreHub 支持”。不要向终端用户提及 Node.js、npm、网络、环境变量、TikTok API 凭证或直连 API，也不要调用 `authorize`。
 
 如果本地登录状态正常，但真实工具调用提示当前店铺的 TikTok 授权已失效或异常，我会直接提醒你去 ScoreHub 重新绑定该店铺后再试，不会再让你重复浏览器登录。
 
@@ -119,6 +168,7 @@ Step 3: 批量建联
 
 如果工具返回结构化错误类型，我会按以下顺序处理：
 
+- 本地 MCP 不可用 → 提示“ScoreHub 服务暂时未连接，请完全退出并重新打开客户端后重试；如仍无法使用，请联系 ScoreHub 支持”；不调用 `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.15",
   "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 未启动，直接提示用户：“ScoreHub 服务暂时未连接，请完全退出并重新打开 Claude Code 或 WorkBuddy 后重试；如仍无法使用，请联系 ScoreHub 支持。”不要向终端用户提及 Node.js、npm、网络、环境变量、TikTok API 凭证或直连 API，也不要调用 `authorize`。
+
 如果工具返回结构化 JSON，优先按 `error_type` 做分流，不要靠自然语言错误文本猜测。
 
 如果本地登录状态正常，但工具提示当前店铺的 TikTok 授权失效或异常，直接提醒用户去 ScoreHub 重新绑定该店铺后再试；不要展示错误码，也不要要求用户重复执行 `authorize`。
@@ -47,17 +49,11 @@
 - `create_conversation` 必须用 **`creator_open_id`**（不是 `creator_user_id`）。
 - `creator_open_id` **仅来自搜索接口**，分析接口不返回——务必从搜索结果透传。
 
-## 降级：直接 API
-
-```
-POST /affiliate_seller/202508/conversations            Body: {"creator_open_id": "xxx"}
-POST /affiliate_seller/202412/conversations/{id}/messages   Body: {"msg_type":"TEXT","content":"{\"content\":\"...\"}"}
-```
-
 ## 错误处理
 
 | 问题类型 | 处理 |
 |----------|------|
+| MCP 工具不可见、工具列表为空、连接关闭或本地 MCP 未启动 | 提示“ScoreHub 服务暂时未连接，请完全退出并重新打开客户端后重试；如仍无法使用，请联系 ScoreHub 支持。”不提及技术配置，不走 `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 未启动，直接提示用户：“ScoreHub 服务暂时未连接，请完全退出并重新打开 Claude Code 或 WorkBuddy 后重试；如仍无法使用，请联系 ScoreHub 支持。”不要向终端用户提及 Node.js、npm、网络、环境变量、TikTok API 凭证或直连 API，也不要调用 `authorize`。
+
 如果工具返回结构化 JSON，优先按 `error_type` 做分流，不要靠自然语言错误文本猜测。
 
 如果本地登录状态正常，但工具提示当前店铺的 TikTok 授权失效或异常，直接提醒用户去 ScoreHub 重新绑定该店铺后再试；不要展示错误码，也不要要求用户重复执行 `authorize`。
@@ -39,21 +41,11 @@
 完整归一化公式、标签体系（💎带货王者 / 🎬内容高手 / 🎯精准美妆 / 📢大V 等）、以及 MCP 字段与
 原始接口字段的映射说明，见 [references/scoring-model.md](./references/scoring-model.md)。
 
-## 降级：直接 API
-
-MCP 不可用时降级调用：
-
-```
-GET https://open-api.tiktokglobalshop.com/affiliate_seller/202508/marketplace_creators/{creator_open_id}
-```
-
-> 注意：详情接口不返回 `creator_open_id`，需从搜索结果透传。原始接口返回字段（`gmv.amount` 为字符串、
-> `avg_commission_rate` 单位 1/100、`follower_gender.value` 为小数）与评分公式的对应关系见 references。
-
 ## 错误处理
 
 | 问题类型 | 处理 |
 |----------|------|
+| MCP 工具不可见、工具列表为空、连接关闭或本地 MCP 未启动 | 提示“ScoreHub 服务暂时未连接，请完全退出并重新打开客户端后重试；如仍无法使用，请联系 ScoreHub 支持。”不提及技术配置，不走 `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 未启动，直接提示用户：“ScoreHub 服务暂时未连接，请完全退出并重新打开 Claude Code 或 WorkBuddy 后重试；如仍无法使用，请联系 ScoreHub 支持。”不要向终端用户提及 Node.js、npm、网络、环境变量、TikTok API 凭证或直连 API，也不要调用 `authorize`。
+
 如果工具返回结构化 JSON，优先按 `error_type` 做分流，不要靠自然语言错误文本猜测。
 
 如果本地登录状态正常，但工具提示当前店铺的 TikTok 授权失效或异常，直接提醒用户去 ScoreHub 重新绑定该店铺后再试；不要展示错误码，也不要要求用户重复执行 `authorize`。
@@ -66,17 +68,6 @@
   2. 回退到更浅的类目层级重搜：把所传的深层子类目换成其**父类目**（只传 `parent_category_id`）重新 `search_creators`；仍零重叠时再上溯一级到顶级父类目。
 - 若有重叠，说明过滤生效，正常展示。
 
-## 降级：直接 API
-
-MCP 不可用时，降级用环境变量凭证直接调用：
-
-```
-POST https://open-api.tiktokglobalshop.com/affiliate_seller/202508/marketplace_creators/search
-```
-
-- 签名：HMAC-SHA256，body 为空 `{}` 时不参与签名；compact JSON `separators=(",", ":")`
-- 类目 ID 应通过 `GET /product/202309/categories` 获取，不要硬编码。MCP 可用时用 `get_categories` 工具。注意达人搜索的 `category` 只认「父类目 + 直接下一级子类目」，深层叶子无效；已知父类目段 ID 形如 `600001`（6 位），可作层级参考。
-
 ## 市场限制
 
 当前仅支持以下东南亚市场：
@@ -96,6 +87,7 @@ POST https://open-api.tiktokglobalshop.com/affiliate_seller/202508/marketplace_c
 
 | 问题类型 | 处理 |
 |----------|------|
+| MCP 工具不可见、工具列表为空、连接关闭或本地 MCP 未启动 | 提示“ScoreHub 服务暂时未连接，请完全退出并重新打开客户端后重试；如仍无法使用，请联系 ScoreHub 支持。”不提及技术配置，不走 `authorize` |
 | `oauth_invalid` | 仅在真正未授权或本地 OAuth 失效时，才允许提示用户调用 `authorize` |
 | 当前店铺的 TikTok 授权失效或异常 | 用中文提醒用户：本地登录状态正常，但当前店铺需要先到 ScoreHub 重新绑定后再试；不要展示错误码，不要要求重复 `authorize` |
 | 日配额已用完 | 明确告知用户，停止 |