@scorehub/creator-outreach 1.1.11 → 1.2.0

package/.codebuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tiktok-creator-outreach",
-  "version": "1.1.11",
+  "version": "1.2.0",
   "description": "ScoreHub AI's TikTok creator marketing expert for building clear creator profiles and validating focused collaboration shortlists across Southeast Asia.",
   "author": {
     "name": "Ben",

package/README.en.md

@@ -21,13 +21,9 @@ For the public release, end users only need to:
 
 3. Return to WorkBuddy and open the “Tiky · TikTok Creator Marketing Expert” conversation
 
-At the start of a new conversation, Tiky first helps check:
+Tiky uses `npx -y @scorehub/creator-outreach@latest` to run a bootstrap check before every new conversation. When the machine is uninitialized, Tiky explains that the ScoreHub local component is required and waits for explicit confirmation. It then prefetches and self-checks `@scorehub/mcp-server@latest` before updating Tiky's files and the WorkBuddy `scorehub` MCP configuration. WorkBuddy must be fully restarted after the initial installation.
 
-- whether the plugin should be upgraded
-- whether the current WorkBuddy environment can run `npx -y @scorehub/creator-outreach@latest`
-- whether the local `scorehub` MCP configuration or `mcp-server` bootstrap is missing, outdated, or broken
-
-When needed, Tiky first explains the action and waits for confirmation, then runs `npx -y @scorehub/creator-outreach@latest` to complete or repair the local bootstrap. That command refreshes Tiky's local installation and rewrites the WorkBuddy `scorehub` MCP configuration. After that, `@scorehub/mcp-server` still starts through the configured `@latest` command on first use.
+That first confirmation also authorizes future silent creator-outreach updates, so Tiky does not ask again for every release. The MCP command always remains `npx -y @scorehub/mcp-server@latest`; it is never pinned to a specific version.
 
 The share link only installs Tiky into WorkBuddy. In the normal public path, users do not need to install `@scorehub/mcp-server` manually or edit `mcp.json` themselves.
 
@@ -45,11 +41,11 @@ The installer configures WorkBuddy only. If it does not find WorkBuddy, it exits
 |---|---|---|---|
 | WorkBuddy | `~/.workbuddy/` exists | Plugin files in `~/.workbuddy/plugins/.../`; MCP configuration merged into `~/.workbuddy/mcp.json` | Restart, then select “ScoreHub AI TikTok Creator Marketing Expert” from the Agent list |
 
-After Tiky completes the local bootstrap, the MCP server (`@scorehub/mcp-server`) is started automatically through `npx -y @scorehub/mcp-server@latest`. If WorkBuddy already provides a working bundled Node.js / npx, Tiky reuses it. Tiky only guides users to the official Node.js LTS installer when there is explicit evidence that the runtime is missing or too old.
+Before writing the configuration, Tiky verifies the MCP server with `--self-check --json`. WorkBuddy then starts it through `npx -y @scorehub/mcp-server@latest`. If WorkBuddy provides a working bundled Node.js / npx, Tiky reuses it. Tiky only guides users to the official Node.js LTS installer when there is explicit evidence that the runtime is missing or too old.
 
 ## First Use and Authorization
 
-At the start of every new conversation, Tiky first looks for public-onboarding signals such as an outdated plugin version, an incomplete local bootstrap, a missing or broken `mcp-server` configuration, or host-provided evidence that Node.js / npm / npx is unavailable. Only when those signals are absent does it proceed to the standard introduction of creator discovery, profile evaluation, and focused outreach validation. If bootstrap or self-upgrade is needed, Tiky explains that it will run `npx -y @scorehub/creator-outreach@latest` and waits for confirmation first. Explicit account or shop switch requests are an exception: a shop switch opens the current account's shop picker, while an account switch opens ScoreHub login. After you choose an operation, its first TikTok call opens a browser for ScoreHub login. Once authorization, reauthorization, or a shop switch succeeds, Tiky confirms the current login phone number, authorized shop, shop country, and bound brands in that order. Tokens are then cached under `~/.scorehub/`, and ScoreHub clients on the same machine can reuse them without another authorization.
+At the start of every new conversation, Tiky first checks one of four bootstrap states: `uninitialized`, `restart_required`, `ready`, or `repair_required`. Only `ready` permits the capability introduction, account or shop switching, and business operations. The first TikTok tool call then opens ScoreHub login when authorization is needed. After authorization, reauthorization, or a shop switch, Tiky confirms the login phone number, authorized shop, country, and bound brands. Tokens remain under `~/.scorehub/` and are not removed by bootstrap or updates.
 
 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.
 
@@ -71,7 +67,7 @@ Install and launch WorkBuddy once, then use the share link to launch Tiky's inst
 
 ### MCP tools are unavailable, the tool list is empty, or the connection closes
 
-Tiky first distinguishes between an outdated plugin, an incomplete `npx -y @scorehub/creator-outreach@latest` bootstrap, a broken local `mcp-server` setup, and a temporary ScoreHub outage. Follow Tiky's upgrade or repair guidance first. If there is no more specific diagnosis, fully quit and reopen WorkBuddy, then try again.
+Tiky runs the bootstrap check first. It does not attempt OAuth or business calls while installation, restart, or repair is required. If bootstrap reports `ready` but tools remain unavailable, fully quit and reopen WorkBuddy, then try again.
 
 If an error explicitly says that Node.js, npm, or npx is missing, or that Node.js is below version 18, Tiky explains the diagnosis first. After your confirmation, it guides recovery through the official Node.js LTS installation path, verifies the result, and asks you to restart WorkBuddy. This does not reauthorize or change TikTok credentials.
 

package/README.md

@@ -21,13 +21,9 @@ English version: [README.en.md](./README.en.md)
 
 3. 回到 WorkBuddy，打开 “Tiky · TikTok达人营销专家” 对话
 
-Tiky 会在新会话中优先帮助你检查：
+Tiky 每个新会话都会通过 `npx -y @scorehub/creator-outreach@latest` 执行 bootstrap 检查。未初始化时，她会说明需要安装 ScoreHub 本地组件，并等待你明确确认；确认后预拉取并自检 `@scorehub/mcp-server@latest`，再更新 Tiky 本地文件和 WorkBuddy 的 `scorehub` MCP 配置。安装完成后需要完全重启 WorkBuddy。
 
-- 当前插件是否需要升级
-- WorkBuddy 当前环境是否支持执行 `npx -y @scorehub/creator-outreach@latest`
-- 本地 `scorehub` MCP 配置或 `mcp-server` 引导是否缺失、过旧或损坏
-
-在需要时，Tiky 会先告知并征得你的确认，再执行 `npx -y @scorehub/creator-outreach@latest` 来完成或修复本地引导。该命令会刷新 Tiky 本地安装，并重写 WorkBuddy 中的 `scorehub` MCP 配置；之后 `@scorehub/mcp-server` 仍由配置中的 `@latest` 在首次启动时自动拉起。
+首次确认同时授权后续静默更新 creator-outreach，不会对每个新版本重复询问。MCP 配置始终使用 `npx -y @scorehub/mcp-server@latest`，不固定具体版本。
 
 分享链接只负责把 Tiky 放进 WorkBuddy。默认情况下，你不需要手工安装 `@scorehub/mcp-server`，也不需要自己编辑 `mcp.json`。
 
@@ -45,11 +41,11 @@ npx -y @scorehub/creator-outreach
 |---|---|---|---|
 | WorkBuddy | `~/.workbuddy/` 存在 | 插件文件写入 `~/.workbuddy/plugins/.../`；MCP 配置合并到 `~/.workbuddy/mcp.json` | 重启后在 Agent 列表选择“ScoreHub AI TikTok达人营销专家” |
 
-MCP Server（`@scorehub/mcp-server`）由 Tiky 完成本地引导后，通过配置中的 `npx -y @scorehub/mcp-server@latest` 在首次启动时自动拉起。WorkBuddy 若已自带可用 Node.js / npx，会优先复用；只有在存在明确缺失证据时，Tiky 才会引导你安装官方 Node.js LTS。
+MCP Server（`@scorehub/mcp-server`）在写入配置前会先通过 `--self-check --json` 验证可执行性，之后由 `npx -y @scorehub/mcp-server@latest` 在 WorkBuddy 启动时自动拉起。WorkBuddy 若已自带可用 Node.js / npx，会优先复用；只有在存在明确缺失证据时，Tiky 才会引导你安装官方 Node.js LTS。
 
 ## 首次使用与授权
 
-每个新对话的第一轮，Tiky 会先识别公开版初始化信号：例如当前插件版本过旧、尚未完成本地引导、`mcp-server` 配置缺失或损坏、或宿主已明确报告 Node.js / npm / npx 缺失。只有在这些信号不存在时，她才进入达人搜索、画像评估和小范围建联验证的标准能力介绍。若需要本地引导或升级，她会先说明将执行 `npx -y @scorehub/creator-outreach@latest`，在你确认后再继续。明确要求切换账号或店铺时除外：切换店铺会直接打开当前账号的店铺确认页，切换账号才会打开 ScoreHub 登录页。选择需要的操作后，它才会在首次调用 TikTok 功能时打开浏览器引导你登录 ScoreHub。授权、重新授权或店铺切换成功后，Tiky 会依次确认当前登录账号、当前授权店铺、店铺所属国家和店铺关联品牌。登录后 Token 缓存在 `~/.scorehub/`，同一台机器上的 ScoreHub 客户端会复用这些授权信息，无需重复授权。
+每个新对话的第一轮，Tiky 都先检查 `uninitialized` / `restart_required` / `ready` / `repair_required` bootstrap 状态。只有 `ready` 才进入能力介绍、账号/店铺切换或业务操作。首次 TikTok 工具调用时会打开浏览器引导你登录 ScoreHub。授权、重新授权或店铺切换成功后，Tiky 会依次确认当前登录账号、当前授权店铺、店铺所属国家和店铺关联品牌。Token 缓存在 `~/.scorehub/`，不会被 bootstrap 或升级清除。
 
 如果提示当前店铺的 TikTok 授权已失效或异常，本地 ScoreHub 登录通常仍然有效。请先到 ScoreHub 重新绑定店铺，再重试；不要反复进行浏览器登录。
 
@@ -71,7 +67,7 @@ MCP Server（`@scorehub/mcp-server`）由 Tiky 完成本地引导后，通过配
 
 ### MCP 工具不可用、工具列表为空或连接已关闭
 
-Tiky 会优先判断是当前版本需要升级、尚未完成 `npx -y @scorehub/creator-outreach@latest` 本地引导、本地 `mcp-server` 配置异常，还是 ScoreHub 服务暂时未连接。请先按她的引导完成升级或修复；如果没有更具体的诊断结果，请完全退出并重新打开 WorkBuddy 后重试。
+Tiky 会优先运行 bootstrap 检查。未安装、需重启或需修复时，她不会尝试 OAuth 或业务调用；已显示 `ready` 但工具仍不可用时，请完全退出并重新打开 WorkBuddy 后重试。
 
 如果错误明确提示找不到 Node.js、npm 或 npx，或 Node.js 版本低于 18，Tiky 会先说明诊断结论。经你确认后，它会使用 Node.js 官方 LTS 安装路径协助恢复，复检通过后提示你重启 WorkBuddy。该流程不会重新授权或修改 TikTok 凭证。
 

package/agents/tiktok-creator-outreach.md

@@ -26,9 +26,18 @@ skills:
 
 ## 新会话首轮引导（最高优先级）
 
-每个新对话的第一条回复，除“账号与店铺切换”这一会话准备操作外，**无论用户输入问候、快捷指令还是具体需求**，我都必须先完成能力介绍，不执行搜索、分析、建联或授权。不要展示工具名、技术配置、错误码或内部流程。
+每个新对话的第一条回复，**无论用户输入问候、快捷指令、账号/店铺切换还是具体业务需求**，都必须先完成 WorkBuddy bootstrap 门禁。bootstrap 未完成时不执行搜索、分析、建联、`authorize` 或 `status`，也不输出标准欢迎语。
 
-在输出欢迎语前，先识别以下明确意图：
+首先执行 `npx -y @scorehub/creator-outreach@latest bootstrap --check --json`，并严格按结构化状态处理：
+
+- `uninitialized`：只告知用户 Tiky 需要安装 ScoreHub 本地组件才能使用达人能力，且不会清除现有授权数据；**必须等待用户明确确认**。确认后执行 `npx -y @scorehub/creator-outreach@latest bootstrap --install --json`。返回 `restart_required` 后提示完全退出并重启 WorkBuddy，本轮结束。这次确认同时代表用户允许后续静默更新，不再对每个 creator-outreach 新版本重复询问。
+- `restart_required`：若当前 `status` 已可用，且返回 `config_source.managed_by = "@scorehub/creator-outreach"` 与 `config_source.client_host = "workbuddy"`，执行 `npx -y @scorehub/creator-outreach@latest bootstrap --mark-ready --json` 清除重启标记并继续；否则只提示完全退出并重启 WorkBuddy，不进入业务流程。
+- `repair_required`：说明结果中的可恢复原因。若明确是 Node.js / npm / npx 问题，进入“本地运行环境恢复”；其他情况经用户确认后重试 `bootstrap --install --json`。修复前不进入业务流程。
+- `ready`：仅当结果同时返回 `update_due = true` 时，执行 `npx -y @scorehub/creator-outreach@latest bootstrap --update --silent --json`；否则直接继续。更新返回 `ready` 时继续；返回 `restart_required` 时可继续使用当前已加载版本，但需在首轮末尾简短提示重启后使用新版本。网络检查失败但现有 MCP 仍可用时，保留当前版本并继续，不误判为 OAuth 问题。
+
+宿主不支持执行本地命令时，回退为提示用户重新打开分享链接 `https://www.workbuddy.cn/work/launch/?sharecode=lNM8H05BRKoV-dw2gac3ZwQ-p01o3C3KVz1gXJ_CwvtX02-mSRqBB3xepE4V0gr7&expertname=Tiky+%C2%B7+TikTok%E8%BE%BE%E4%BA%BA%E8%90%A5%E9%94%80%E4%B8%93%E5%AE%B6&buddy_type=workbuddy` 进行覆盖安装；不要让终端用户手工编辑 `mcp.json`。
+
+bootstrap 返回 `ready` 后，再识别以下明确意图：
 
 - 用户要求“切换店铺”“换店”“使用另一个店铺”或同义表达时，立即调用 `authorize`，参数为 `{ "switch_shop": true }`。这会直接打开当前账号的店铺确认页，**不得**传 `force`、不得要求用户重新登录、不得先输出欢迎语。
 - 用户要求“切换账号”“换号”“登录另一个账号”或同义表达时，立即调用 `authorize`，参数为 `{ "force": true }`。这会重新打开 ScoreHub 登录页，**不得**传 `switch_shop`、不得先输出欢迎语。
@@ -43,14 +52,6 @@ skills:
 
   字段值必须原样使用工具结果；“未绑定”与“未获取”也必须如实告知，不得猜测或补充。仅复用本地缓存、且工具结果未包含上述字段时，不输出这段确认信息。
 
-在 WorkBuddy 公开发布场景中，若宿主、版本检测或本地诊断结果已**明确**提供以下初始化信号，也要在欢迎语前优先处理；没有明确信号时，不猜测、不阻塞欢迎语：
-
-- **Tiky 版本落后**：优先说明将执行本地命令 `npx -y @scorehub/creator-outreach@latest` 来升级 Tiky，并明确升级不会清除本机 `~/.scorehub/` 授权缓存；**必须等待用户明确确认** 后再执行。若宿主不支持执行本地命令，或命令执行失败，再回退为提示用户重新打开分享链接 `https://www.workbuddy.cn/work/launch/?sharecode=lNM8H05BRKoV-dw2gac3ZwQ-p01o3C3KVz1gXJ_CwvtX02-mSRqBB3xepE4V0gr7&expertname=Tiky+%C2%B7+TikTok%E8%BE%BE%E4%BA%BA%E8%90%A5%E9%94%80%E4%B8%93%E5%AE%B6&buddy_type=workbuddy` 进行覆盖安装。
-- **尚未完成本地引导，或 `mcp-server` 配置缺失、过旧或损坏**：优先说明将执行本地命令 `npx -y @scorehub/creator-outreach@latest`，用它完成 Tiky 本地引导，并重写 WorkBuddy 中名为 `scorehub` 的 MCP 配置；**必须等待用户明确确认** 后再执行。只有在宿主不支持命令执行、或该命令执行失败时，才回退为提示用户重启 WorkBuddy 或重新打开分享链接。
-- **`status` 已明确返回 `local_state = "running_authorized_remote_unavailable"`**：说明本地 `mcp-server` 已启动并持有授权，但远端工具发现暂不可用。此时不要建议重新授权或安装 Node.js，只提示稍后重试、完全重启 WorkBuddy，或联系 ScoreHub 支持。
-- **`status` 已明确返回 `local_state = "running_unauthorized"`**：说明本地 `mcp-server` 已启动但尚未完成 ScoreHub OAuth；此时可以继续欢迎语，并在用户真正要调用 TikTok 能力时再引导授权。
-- **`status` 已明确返回 `config_source.managed_by = "@scorehub/creator-outreach"` 且 `config_source.client_host = "workbuddy"`**：将其视为公开版标准安装路径，不再要求终端用户手工编辑 `mcp.json`。
-
 首轮使用以下完整中文欢迎语，随后等待用户选择。若已知用户姓名，在开头称呼该姓名；未知时直接以“你好”开头，绝不猜测姓名：
 
 > 你好，我是 Tiky，ScoreHub AI 的 TikTok 达人营销专家。我先帮你建立清晰准确的达人画像，评估合作价值，再对精选候选人进行小范围建联验证。我不是面向成千上万达人的海量群发工具。以下是我能帮你做的事情：
@@ -225,9 +226,7 @@ HTML 报告必须自包含，只使用内联 CSS/JavaScript，不依赖 CDN、
 4. 用户确认后：macOS 和 Windows 打开 `https://nodejs.org/en/download` 并引导安装 LTS；Linux 先识别发行版，再使用 NodeSource 的受支持安装路径。没有终端或打开链接能力时，提供同样的官方步骤并等待用户自行完成。不得使用未验证的第三方下载源。
 5. 安装完成后，重新检查三条版本命令。只有 Node.js 为 18+、npm 和 npx 均可用时，才提示用户完全退出并重新打开 WorkBuddy；现有 `npx -y @scorehub/mcp-server@latest` 配置会自动拉取并启动本地代理。Node.js 和 npm 存在但 npx 缺失时，视为不完整安装，指导修复或重装 Node.js LTS，**不得**改写 MCP 配置为其他启动命令。
 
-如果宿主、版本检测或 `status` 工具已明确指出 Tiky 自身版本落后，先引导用户执行 `npx -y @scorehub/creator-outreach@latest` 升级 Tiky，再继续处理运行环境或 MCP 修复；避免让旧版智能体继续指导公开版安装流程。若宿主不支持执行本地命令，再回退为重新打开分享链接覆盖安装。
-
-如果没有上述明确证据，直接告诉用户：“ScoreHub 服务暂时未连接，请完全退出并重新打开 WorkBuddy 后重试；如仍无法使用，请联系 ScoreHub 支持。”不要向终端用户提及 Node.js、npm、网络、环境变量、TikTok API 凭证或直连 API，也不要调用 `authorize`。
+如果 bootstrap 已返回 `ready`，但 MCP 工具仍不可见、连接关闭或本地 MCP 未启动，直接告诉用户：“ScoreHub 服务暂时未连接，请完全退出并重新打开 WorkBuddy 后重试；如仍无法使用，请联系 ScoreHub 支持。”不要调用 `authorize`，也不要把该情况自动误判为系统级 Node.js 缺失。
 
 如果本地登录状态正常，但真实工具调用提示当前店铺的 TikTok 授权已失效或异常，我会直接提醒你去 ScoreHub 重新绑定该店铺后再试，不会再让你重复浏览器登录。
 

package/install.js

@@ -1,14 +1,18 @@
 #!/usr/bin/env node
 
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const { execSync } = require('child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
 
 const pkg = require('./package.json');
+
 const MIN_NODE_MAJOR = 18;
+const STATE_SCHEMA_VERSION = 1;
+const UPDATE_INTERVAL_MS = 24 * 60 * 60 * 1000;
 const WORKBUDDY_SHARE_URL = 'https://www.workbuddy.cn/work/launch/?sharecode=lNM8H05BRKoV-dw2gac3ZwQ-p01o3C3KVz1gXJ_CwvtX02-mSRqBB3xepE4V0gr7&expertname=Tiky+%C2%B7+TikTok%E8%BE%BE%E4%BA%BA%E8%90%A5%E9%94%80%E4%B8%93%E5%AE%B6&buddy_type=workbuddy';
 const CREATOR_OUTREACH_SELF_BOOTSTRAP_COMMAND = 'npx -y @scorehub/creator-outreach@latest';
+const MCP_SERVER_SELF_CHECK_COMMAND = 'npx -y @scorehub/mcp-server@latest --self-check --json';
 
 const MCP_CONFIG = {
   type: 'stdio',
@@ -31,6 +35,7 @@ function isSupportedNode(nodeVersion = process.versions.node) {
 
 function getPaths(homeDir) {
   const workBuddyDir = path.join(homeDir, '.workbuddy');
+  const scorehubDir = path.join(workBuddyDir, 'scorehub');
 
   return {
     workBuddyDir,
@@ -38,6 +43,8 @@ function getPaths(homeDir) {
       workBuddyDir, 'plugins', 'marketplaces', 'my-experts', 'plugins', 'tiktok-creator-outreach',
     ),
     workBuddyMcpJson: path.join(workBuddyDir, 'mcp.json'),
+    bootstrapState: path.join(scorehubDir, 'bootstrap-state.json'),
+    bootstrapDir: scorehubDir,
   };
 }
 
@@ -45,9 +52,9 @@ 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 versionDir = path.join(versionsDir, versions[0]);
+    const versions = fs.readdirSync(versionsDir).sort().reverse();
+    for (const version of versions) {
+      const versionDir = path.join(versionsDir, version);
       const binDirs = [path.join(versionDir, 'bin'), versionDir];
       for (const binDir of binDirs) {
         const npxPath = path.join(binDir, npxExecutable);
@@ -60,111 +67,349 @@ function resolveWorkBuddyNode(workBuddyDir) {
   return { npx: 'npx', binDir: null };
 }
 
-function fetchLatestMcpServerVersion() {
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function writeJsonAtomic(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
   try {
-    const out = execSync('npm view @scorehub/mcp-server version', {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-      timeout: 10000,
+    fs.renameSync(tempPath, filePath);
+  } catch (error) {
+    try { fs.rmSync(tempPath, { force: true }); } catch { /* preserve the original error */ }
+    throw error;
+  }
+}
+
+function snapshotFile(filePath) {
+  return fs.existsSync(filePath) ? fs.readFileSync(filePath) : null;
+}
+
+function restoreFile(filePath, snapshot) {
+  if (snapshot === null) {
+    fs.rmSync(filePath, { force: true });
+    return;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.restore`;
+  fs.writeFileSync(tempPath, snapshot);
+  fs.renameSync(tempPath, filePath);
+}
+
+function defaultState() {
+  return {
+    schema_version: STATE_SCHEMA_VERSION,
+    consent_granted: false,
+    status: 'uninitialized',
+    creator_outreach_version: null,
+    observed_mcp_server_version: null,
+    last_check_at: null,
+    last_error: null,
+    restart_required: false,
+  };
+}
+
+function loadState(statePath) {
+  if (!fs.existsSync(statePath)) return defaultState();
+  try {
+    const state = readJson(statePath);
+    if (state.schema_version !== STATE_SCHEMA_VERSION) throw new Error('unsupported state schema');
+    return Object.assign(defaultState(), state);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return Object.assign(defaultState(), {
+      status: 'repair_required',
+      last_error: `bootstrap state is invalid: ${reason}`,
     });
-    return out.trim() || null;
+  }
+}
+
+function readInstalledPluginVersion(pluginDir) {
+  const packagePath = path.join(pluginDir, 'package.json');
+  try {
+    const installed = readJson(packagePath);
+    return typeof installed.version === 'string' ? installed.version : null;
   } catch {
     return null;
   }
 }
 
-function mergeMcpConfig(configPath, serverName, serverConfig, extraFields) {
-  let config = {};
-  if (fs.existsSync(configPath)) {
-    try {
-      config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-    } catch {
-      console.warn(`Warning: ${configPath} could not be parsed and will be replaced.`);
-    }
+function buildMcpEnvironment(version, binDir) {
+  const existingPath = process.env.PATH || process.env.Path || '';
+  return Object.assign({}, MCP_CONFIG.env, {
+    SCOREHUB_CREATOR_OUTREACH_VERSION: version,
+    ...(binDir ? { PATH: [binDir, existingPath].filter(Boolean).join(path.delimiter) } : {}),
+  });
+}
+
+function buildMcpConfig(version, npx, binDir) {
+  return {
+    command: npx,
+    args: MCP_CONFIG.args.slice(),
+    env: buildMcpEnvironment(version, binDir),
+  };
+}
+
+function readMcpConfig(configPath) {
+  if (!fs.existsSync(configPath)) return { exists: false, config: {} };
+  try {
+    return { exists: true, config: readJson(configPath) };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return { exists: true, config: null, error: `mcp.json is invalid: ${reason}` };
   }
+}
 
+function isManagedMcpConfig(config) {
+  const server = config && config.mcpServers && config.mcpServers.scorehub;
+  return !!server
+    && Array.isArray(server.args)
+    && server.args.includes('@scorehub/mcp-server@latest')
+    && server.env
+    && server.env.SCOREHUB_MANAGED_BY === '@scorehub/creator-outreach'
+    && server.env.SCOREHUB_CLIENT_HOST === 'workbuddy';
+}
+
+function mergeMcpConfig(configPath, serverConfig) {
+  const current = readMcpConfig(configPath);
+  if (current.config === null) throw new Error(current.error);
+  const config = current.config || {};
   config.mcpServers = config.mcpServers || {};
-  config.mcpServers[serverName] = Object.assign({}, serverConfig, extraFields);
-  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  config.mcpServers.scorehub = serverConfig;
+  writeJsonAtomic(configPath, config);
 }
 
-function install({
-  homeDir = os.homedir(),
-  nodeVersion = process.versions.node,
-  getLatestMcpServerVersion = fetchLatestMcpServerVersion,
-} = {}) {
-  console.log(`${pkg.name} v${pkg.version}\n`);
+function copyPluginToStage(stageDir) {
+  const pluginDirs = ['.codebuddy-plugin', 'agents', 'skills', 'avatars'];
+  const pluginFiles = ['package.json', 'README.md', 'README.en.md', 'install.js'];
+  fs.mkdirSync(stageDir, { recursive: true });
+  for (const dir of pluginDirs) {
+    const source = path.join(__dirname, dir);
+    if (fs.existsSync(source)) fs.cpSync(source, path.join(stageDir, dir), { recursive: true });
+  }
+  for (const file of pluginFiles) {
+    const source = path.join(__dirname, file);
+    if (fs.existsSync(source)) fs.copyFileSync(source, path.join(stageDir, file));
+  }
+}
 
-  if (!isSupportedNode(nodeVersion)) {
-    console.error(`Node.js ${MIN_NODE_MAJOR}+ is required. Detected ${nodeVersion}. No configuration files were changed.`);
-    return 1;
+function replacePluginAtomic(pluginDir) {
+  const parentDir = path.dirname(pluginDir);
+  const stageDir = path.join(parentDir, `.tiktok-creator-outreach.stage-${process.pid}-${Date.now()}`);
+  const backupDir = path.join(parentDir, `.tiktok-creator-outreach.backup-${process.pid}-${Date.now()}`);
+  copyPluginToStage(stageDir);
+  try {
+    if (fs.existsSync(pluginDir)) fs.renameSync(pluginDir, backupDir);
+    fs.renameSync(stageDir, pluginDir);
+    return backupDir;
+  } catch (error) {
+    if (fs.existsSync(pluginDir) && fs.existsSync(backupDir)) fs.rmSync(pluginDir, { recursive: true, force: true });
+    if (fs.existsSync(backupDir) && !fs.existsSync(pluginDir)) fs.renameSync(backupDir, pluginDir);
+    if (fs.existsSync(stageDir)) fs.rmSync(stageDir, { recursive: true, force: true });
+    throw error;
   }
+}
 
-  const paths = getPaths(homeDir);
-  const hasWorkBuddy = fs.existsSync(paths.workBuddyDir);
+function restorePlugin(pluginDir, backupDir) {
+  if (fs.existsSync(pluginDir)) fs.rmSync(pluginDir, { recursive: true, force: true });
+  if (backupDir && fs.existsSync(backupDir)) fs.renameSync(backupDir, pluginDir);
+}
 
-  if (!hasWorkBuddy) {
-    console.error('No supported client was found. Launch WorkBuddy once, then run this command again. No configuration files were changed.');
-    return 1;
+function parseSelfCheckOutput(output) {
+  const lines = String(output).trim().split(/\r?\n/).reverse();
+  for (const line of lines) {
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed && parsed.schema_version === 1 && typeof parsed.ok === 'boolean') return parsed;
+    } catch { /* npx may print non-JSON diagnostics before the payload */ }
   }
+  throw new Error('mcp-server self-check did not return a valid JSON payload');
+}
 
-  const pluginDirs = ['.codebuddy-plugin', 'agents', 'skills', 'avatars'];
-  const pluginFiles = ['package.json', 'README.md', 'README.en.md'];
+function runMcpSelfCheck({ npx, env, selfCheck = defaultMcpSelfCheck } = {}) {
+  return selfCheck({ npx, env });
+}
 
-  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 });
+function defaultMcpSelfCheck({ npx, env }) {
+  try {
+    const output = execFileSync(npx, ['-y', '@scorehub/mcp-server@latest', '--self-check', '--json'], {
+      encoding: 'utf8',
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 30000,
+    });
+    const payload = parseSelfCheckOutput(output);
+    if (!payload.ok) throw new Error(`mcp-server self-check failed for Node.js ${payload.node_version}`);
+    return payload;
+  } catch (error) {
+    if (error && typeof error === 'object' && 'stderr' in error && error.stderr) {
+      throw new Error(String(error.stderr).trim());
     }
+    throw error;
   }
+}
 
-  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);
-    }
+function detectStatus({ paths, state, nodeVersion }) {
+  if (!isSupportedNode(nodeVersion)) {
+    return { status: 'repair_required', reason: `Node.js ${MIN_NODE_MAJOR}+ is required. Detected ${nodeVersion}.` };
+  }
+  if (!fs.existsSync(paths.workBuddyDir)) {
+    return { status: 'repair_required', reason: 'WorkBuddy has not been started on this machine.' };
   }
+  const mcp = readMcpConfig(paths.workBuddyMcpJson);
+  if (mcp.config === null) return { status: 'repair_required', reason: mcp.error };
+  if (state.status === 'repair_required') return { status: 'repair_required', reason: state.last_error || 'Bootstrap requires repair.' };
+  if (!state.consent_granted || !isManagedMcpConfig(mcp.config)) {
+    return { status: 'uninitialized', reason: 'WorkBuddy MCP bootstrap has not been confirmed.' };
+  }
+  if (state.restart_required) return { status: 'restart_required', reason: 'WorkBuddy must be restarted to load the updated plugin and MCP configuration.' };
+  return { status: 'ready', reason: null };
+}
 
-  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, {
-      SCOREHUB_CREATOR_OUTREACH_VERSION: pkg.version,
-      PATH: [binDir, existingPath].filter(Boolean).join(path.delimiter),
-    })
-    : Object.assign({}, MCP_CONFIG.env, {
-      SCOREHUB_CREATOR_OUTREACH_VERSION: pkg.version,
-    });
-  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}`);
+function check({ homeDir = os.homedir(), nodeVersion = process.versions.node, now = Date.now() } = {}) {
+  const paths = getPaths(homeDir);
+  const state = loadState(paths.bootstrapState);
+  const detected = detectStatus({ paths, state, nodeVersion });
+  const lastCheckAt = state.last_check_at ? Date.parse(state.last_check_at) : Number.NaN;
+  const updateDue = detected.status === 'ready'
+    && (!Number.isFinite(lastCheckAt) || now - lastCheckAt >= UPDATE_INTERVAL_MS);
+  return {
+    schema_version: STATE_SCHEMA_VERSION,
+    status: detected.status,
+    reason: detected.reason,
+    creator_outreach_version: pkg.version,
+    consent_granted: state.consent_granted,
+    mcp_configured: detected.status === 'ready' || detected.status === 'restart_required',
+    restart_required: state.restart_required,
+    update_due: updateDue,
+  };
+}
 
-  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).');
+function assertInstallable({ homeDir, nodeVersion }) {
+  const paths = getPaths(homeDir);
+  if (!isSupportedNode(nodeVersion)) throw new Error(`Node.js ${MIN_NODE_MAJOR}+ is required. Detected ${nodeVersion}.`);
+  if (!fs.existsSync(paths.workBuddyDir)) throw new Error('No supported client was found. Launch WorkBuddy once, then retry.');
+  return { paths, node: resolveWorkBuddyNode(paths.workBuddyDir) };
+}
+
+function install({
+  homeDir = os.homedir(),
+  nodeVersion = process.versions.node,
+  selfCheck = defaultMcpSelfCheck,
+  markConsent = true,
+  replacePlugin = replacePluginAtomic,
+} = {}) {
+  const { paths, node } = assertInstallable({ homeDir, nodeVersion });
+  const env = buildMcpEnvironment(pkg.version, node.binDir);
+  const mcpCheck = runMcpSelfCheck({ npx: node.npx, env, selfCheck });
+  const mcpSnapshot = snapshotFile(paths.workBuddyMcpJson);
+  const stateSnapshot = snapshotFile(paths.bootstrapState);
+  let pluginBackup = null;
+  let pluginReplaced = false;
+  try {
+    mergeMcpConfig(paths.workBuddyMcpJson, buildMcpConfig(pkg.version, node.npx, node.binDir));
+    pluginBackup = replacePlugin(paths.workBuddyPluginDir);
+    pluginReplaced = true;
+
+    const state = loadState(paths.bootstrapState);
+    state.consent_granted = markConsent || state.consent_granted;
+    state.status = 'restart_required';
+    state.creator_outreach_version = pkg.version;
+    state.observed_mcp_server_version = mcpCheck.server_version || null;
+    state.last_check_at = new Date().toISOString();
+    state.last_error = null;
+    state.restart_required = true;
+    writeJsonAtomic(paths.bootstrapState, state);
+  } catch (error) {
+    if (pluginReplaced) restorePlugin(paths.workBuddyPluginDir, pluginBackup);
+    restoreFile(paths.workBuddyMcpJson, mcpSnapshot);
+    restoreFile(paths.bootstrapState, stateSnapshot);
+    throw error;
   }
+  if (pluginBackup && fs.existsSync(pluginBackup)) fs.rmSync(pluginBackup, { recursive: true, force: true });
+  return { status: 'restart_required', mcp_server_version: mcpCheck.server_version || null };
+}
 
-  console.log('\nInstallation complete. Restart WorkBuddy and use Tiky.');
-  return 0;
+function markReady({ homeDir = os.homedir(), nodeVersion = process.versions.node } = {}) {
+  const paths = getPaths(homeDir);
+  const state = loadState(paths.bootstrapState);
+  const detected = detectStatus({ paths, state: Object.assign({}, state, { restart_required: false }), nodeVersion });
+  if (detected.status !== 'ready') throw new Error(detected.reason || `Cannot mark bootstrap as ready: ${detected.status}`);
+  state.status = 'ready';
+  state.restart_required = false;
+  state.last_error = null;
+  writeJsonAtomic(paths.bootstrapState, state);
+  return { status: 'ready' };
 }
 
-if (require.main === module) {
-  process.exitCode = install();
+function update({
+  homeDir = os.homedir(),
+  nodeVersion = process.versions.node,
+  selfCheck = defaultMcpSelfCheck,
+} = {}) {
+  const paths = getPaths(homeDir);
+  const state = loadState(paths.bootstrapState);
+  if (!state.consent_granted) return { status: 'uninitialized', reason: 'Initial installation confirmation is required.' };
+  const detected = detectStatus({ paths, state: Object.assign({}, state, { restart_required: false }), nodeVersion });
+  if (detected.status === 'repair_required' || detected.status === 'uninitialized') {
+    return { status: detected.status, reason: detected.reason };
+  }
+  if (state.restart_required) return { status: 'restart_required', reason: 'WorkBuddy must be restarted to load the updated plugin and MCP configuration.' };
+  if (readInstalledPluginVersion(paths.workBuddyPluginDir) === pkg.version) {
+    state.status = 'ready';
+    state.creator_outreach_version = pkg.version;
+    state.last_check_at = new Date().toISOString();
+    state.last_error = null;
+    writeJsonAtomic(paths.bootstrapState, state);
+    return { status: 'ready', creator_outreach_version: pkg.version };
+  }
+  return install({ homeDir, nodeVersion, selfCheck, markConsent: false });
+}
+
+function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+function runCli(argv = process.argv.slice(2)) {
+  const action = argv[0];
+  const options = {
+    homeDir: process.env.SCOREHUB_BOOTSTRAP_HOME || os.homedir(),
+    nodeVersion: process.versions.node,
+  };
+  try {
+    let result;
+    if (action === 'bootstrap' && argv.includes('--check')) result = check(options);
+    else if (action === 'bootstrap' && argv.includes('--install')) result = install(options);
+    else if (action === 'bootstrap' && argv.includes('--update')) result = update(options);
+    else if (action === 'bootstrap' && argv.includes('--mark-ready')) result = markReady(options);
+    else result = install(options);
+    printJson(result);
+    return result.status === 'repair_required' ? 1 : 0;
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    printJson({ schema_version: STATE_SCHEMA_VERSION, status: 'repair_required', reason });
+    return 1;
+  }
 }
 
+if (require.main === module) process.exitCode = runCli();
+
 module.exports = {
   CREATOR_OUTREACH_SELF_BOOTSTRAP_COMMAND,
+  MCP_SERVER_SELF_CHECK_COMMAND,
   MIN_NODE_MAJOR,
+  UPDATE_INTERVAL_MS,
   WORKBUDDY_SHARE_URL,
+  check,
+  detectStatus,
   getNodeMajorVersion,
   getPaths,
   install,
+  isManagedMcpConfig,
   isSupportedNode,
+  markReady,
+  runCli,
+  update,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scorehub/creator-outreach",
-  "version": "1.1.11",
+  "version": "1.2.0",
   "description": "ScoreHub AI TikTok达人营销专家 Tiky — Agent 定义 + Skills 配置",
   "engines": {
     "node": ">=18"