@whobot/cli 1.0.1 → 2.0.1

package/README.md

@@ -14,15 +14,24 @@ npx --yes @whobot/cli@latest install
 
 全局包已安装而当前 PATH 看不到 `whobot` 时，使用 npm prefix 解析出的全局入口绝对路径，仍经过 JS 启动器；不要枚举 CLI 数据目录下的 Go 文件。
 
-显式更新：
+首次从 v1 升级到 v2 时，先从原渠道获取最新稳定版的具体版本，再执行升级提示中的固定版本安装命令，例如目标为 `2.0.0` 时：
 
 ```bash
-whobot update apply --json
-# 或
-npx --yes @whobot/cli@latest install
+npx --yes @whobot/cli@2.0.0 install
 ```
 
-更新走 npm，不向数据 Home/bin 写入程序文件。
+首次迁移不要运行旧的 `update apply`，也不要直接复用 `npx @whobot/cli@latest install` 或 `@intranet install`。已发布 v1 的全局程序可能软链接到同一标签的 npx 缓存；再次解析同标签可能在安装器启动前覆盖旧程序，使活动检查和原凭据端点校验失去依据。固定的新版本使用独立缓存入口，安装器先检查旧身份、原编译端点和活动通话，再替换程序。新安装的全局包与 npx 缓存分离。
+
+v2 后续更新：
+
+```bash
+whobot update
+# 确认后执行返回的 next.command，包含实际目标版本
+```
+
+更新走 npm，不向数据 Home/bin 写入程序文件。安装成功会核对 npm 注册、实际二进制版本与协议、命令入口；PATH 仍优先解析旧入口时明确失败。存在身份但原程序损坏、端点符号缺失或新旧 API Origin / OAuth Issuer 不同，必须先恢复原程序或使用原端点的发行，不会清空身份来绕过检查。
+
+CLI 软件安装完成后，还需要通过原平台或官方完整包更新 Skill，重载宿主或新建任务，再执行一次预检。安装器不覆盖宿主 Skill，也不将 CLI 完成当作联合升级完成。
 
 ## 程序位置与数据目录
 
@@ -30,6 +39,8 @@ npx --yes @whobot/cli@latest install
 
 ## 校验
 
+SHA-256 用于核对下载内容与 manifest 一致，不声称提供公开签名或来源认证。
+
 - 只接受已知 `schemaVersion`、OS（darwin/linux/windows）与 arch（amd64/arm64）
 - 解压前核对 size 与 SHA-256
 - 拒绝路径穿越、重名、意外顶层文件、缺失 checksum、制品内脚本
@@ -41,3 +52,5 @@ npx --yes @whobot/cli@latest install
 ```bash
 bun test
 ```
+
+发布人员在启用最低版本前，应对实际发行源执行仓库的 `bun deploy/check-upgrade-release.mjs latest`（内网使用 `intranet`），验证两项门槛可满足、完整 Skill 包和说明可取，以及隔离 npm/native 安装成功。配置、先制品后门槛的顺序与用户人工宿主清单见仓库 `docs/releases/skill-cli-v2-cutover.md`；检查通过只覆盖当前平台，不表示真实宿主已验收。

package/bin/install.mjs

@@ -28,10 +28,32 @@ const pkg = JSON.parse(
   await fs.readFile(path.join(pkgRoot, "package.json"), "utf8"),
 );
 
+// The release profile (ADR-0015) is baked into the published package: its npm
+// entry command is the single package.json bin key and its CLI home directory
+// is bootstrap.homeName.
+const COMMAND = cliCommand(pkg);
+const HOME_NAME = cliHomeName(bootstrap);
+
+function cliCommand(p) {
+  const names = Object.keys(p.bin || {});
+  if (names.length !== 1 || !/^whobot(-[a-z]+)?$/.test(names[0])) {
+    throw new Error(`package.json must register exactly one whobot command, got ${JSON.stringify(p.bin)}`);
+  }
+  return names[0];
+}
+
+function cliHomeName(b) {
+  const name = String(b.homeName || "");
+  if (!/^\.whobot(-[a-z]+)?-cli$/.test(name)) {
+    throw new Error(`bootstrap.json homeName is missing or invalid: ${JSON.stringify(b.homeName)}`);
+  }
+  return name;
+}
+
 const OS_MAP = { darwin: "darwin", linux: "linux", win32: "windows" };
 const ARCH_MAP = { x64: "amd64", arm64: "arm64" };
-const BINARY_UNIX = "whobot";
-const BINARY_WINDOWS = "whobot.exe";
+const BINARY_UNIX = COMMAND;
+const BINARY_WINDOWS = `${COMMAND}.exe`;
 const ALLOWED_FILES = new Set([
   BINARY_UNIX,
   BINARY_WINDOWS,
@@ -48,6 +70,8 @@ const ALLOWED_FILES = new Set([
 const DIST_TAGS = new Set(["latest", "next", "canary", "stable", "intranet", "*"]);
 const SEMVER =
   /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const STABLE_TARGET =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 const SHA256_HEX = /^[0-9a-fA-F]{64}$/;
 const DOWNLOAD_TIMEOUT_MS = 60_000;
 const SMOKE_TIMEOUT_MS = 15_000;
@@ -69,12 +93,19 @@ export class InstallerError extends Error {
 function writeJSONFailure(code, message) {
   const body = {
     ok: false,
-    error: { code, message, retryable: false },
+    error: {
+      code,
+      category: code === "CHANNEL_INVALID" ? "input" : "unavailable",
+      userMessage: code === "CHANNEL_INVALID" ? "安装包的发行渠道信息有误，请重新安装。" : "CLI 更新未完成，已有身份数据已保留。",
+      detail: message,
+      retry: { safe: false },
+    },
+    next: { action: "stop" },
     meta: {
       requestId: "req_00000000000000000000000000000000",
-      cliVersion: pkg.version,
-      apiVersion: "v1",
-      protocolVersion: 1,
+      cli: pkg.version,
+      protocol: 2,
+      notices: [],
     },
   };
   process.stdout.write(`${JSON.stringify(body)}\n`);
@@ -88,10 +119,8 @@ function bakedChannel() {
   return ch;
 }
 
-const WORKSPACE_HOME_NAME = ".whobot-cli";
-
 function logStderr(message) {
-  process.stderr.write(`whobot: ${message}\n`);
+  process.stderr.write(`${COMMAND}: ${message}\n`);
 }
 
 export function nativeBinaryPath(root = pkgRoot) {
@@ -197,7 +226,7 @@ export async function runPostinstall(env) {
   }
 }
 
-export function whichCommand(name, env) {
+export function whichCommand(name, env, ignoreRealpath = "") {
   const pathEnv = env.PATH || env.Path || "";
   const exts = process.platform === "win32" ? [".cmd", ".exe", ".bat", ""] : [""];
   for (const dir of pathEnv.split(path.delimiter)) {
@@ -208,6 +237,7 @@ export function whichCommand(name, env) {
       const candidate = path.join(dir, name + ext);
       try {
         accessSync(candidate, constants.X_OK);
+        if (ignoreRealpath && realpathSync(candidate) === ignoreRealpath) continue;
         return candidate;
       } catch {
         // try next
@@ -271,9 +301,9 @@ export function globalNpmEnv(env) {
 
 export function globalWhobotEntry(prefix) {
   if (process.platform === "win32") {
-    return path.join(prefix, "whobot.cmd");
+    return path.join(prefix, `${COMMAND}.cmd`);
   }
-  return path.join(prefix, "bin", "whobot");
+  return path.join(prefix, "bin", COMMAND);
 }
 
 function spawnNpm(tools, args, env, timeoutMs) {
@@ -331,6 +361,7 @@ function npmInstallGlobalFrom(tools, spec, env) {
       "--no-fund",
       "--no-audit",
       "--foreground-scripts",
+      "--install-links",
       spec,
     ],
     env,
@@ -368,7 +399,7 @@ function positionalCommands(argv) {
     if (a === "--json") {
       continue;
     }
-    if (a === "-Q" || a === "--global-config" || a === "--channel") {
+    if (a === "-Q" || a === "--global-config" || a === "--channel" || a === "--target-version") {
       i++;
       continue;
     }
@@ -387,14 +418,26 @@ function positionalCommands(argv) {
 
 export function isUpdateApply(argv) {
   const cmds = positionalCommands(argv);
-  return cmds[0] === "update" && cmds[1] === "apply";
+  return cmds.length === 1 && cmds[0] === "update" && argv.some((a) => a === "--yes" || a === "--yes=true");
+}
+
+function confirmedTargetVersion(argv) {
+  const targets = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--target-version") targets.push(argv[++i]);
+    else if (argv[i].startsWith("--target-version=")) targets.push(argv[i].slice("--target-version=".length));
+  }
+  if (targets.length !== 1 || !STABLE_TARGET.test(targets[0] || "")) {
+    throw new InstallerError("请使用更新预览返回的含目标版本的 next.command", "UPDATE_VERIFY_FAILED");
+  }
+  return targets[0];
 }
 
 export function globalPackageDir(prefix, nodeOS = process.platform) {
   if (nodeOS === "win32") {
-    return path.join(prefix, "node_modules", "@whobot", "cli");
+    return path.join(prefix, "node_modules", ...pkg.name.split("/"));
   }
-  return path.join(prefix, "lib", "node_modules", "@whobot", "cli");
+  return path.join(prefix, "lib", "node_modules", ...pkg.name.split("/"));
 }
 
 export function packageNativeBinary(prefix, nodeOS = process.platform, nodeArch = process.arch) {
@@ -508,21 +551,6 @@ function readDistTags(tools, env) {
   }
 }
 
-function readRegistryVersion(tools, env, channel) {
-  const spec = `${pkg.name}@${channel}`;
-  const result = spawnNpm(tools, ["view", spec, "version"], env, 30_000);
-  const ver = String(result.stdout || "").trim();
-  if (result.error) {
-    throw new InstallerError(`cannot resolve ${spec}: ${result.error.message}`);
-  }
-  if (result.status !== 0 || ver === "") {
-    throw new InstallerError(
-      `cannot resolve ${spec}: ${String(result.stderr || result.stdout || "").trim()}`,
-    );
-  }
-  return ver;
-}
-
 function rejectExternalChannel(env) {
   if (String(env.WHOBOT_CLI_CHANNEL || "").trim()) {
     throw new InstallerError("发行渠道由发行包内置，不接受 WHOBOT_CLI_CHANNEL", "CHANNEL_INVALID");
@@ -536,6 +564,7 @@ function verifyNpmEntryVersion(entry, wantVersion, env) {
     timeout: VERIFY_TIMEOUT_MS,
     windowsHide: true,
     stdio: ["ignore", "pipe", "pipe"],
+    shell: process.platform === "win32" && /\.(cmd|bat)$/i.test(entry),
   });
   const combined = `${result.stdout || ""}\n${result.stderr || ""}`;
   if (result.error) {
@@ -572,9 +601,9 @@ function verifyNpmEntryVersion(entry, wantVersion, env) {
   if (parsed.ok !== true) {
     throw new InstallerError("version --json verification ok=false");
   }
-  if (parsed.data?.protocolVersion !== 1) {
+  if (parsed.meta?.protocol !== 2) {
     throw new InstallerError(
-      `protocolVersion ${parsed.data?.protocolVersion} is not 1`,
+      `protocol ${parsed.meta?.protocol} is not 2`,
     );
   }
   if (parsed.data?.version !== wantVersion) {
@@ -585,20 +614,56 @@ function verifyNpmEntryVersion(entry, wantVersion, env) {
   return parsed;
 }
 
+async function repairAndVerifyNative(native, version, env) {
+  try {
+    verifyNpmEntryVersion(native, version, env);
+  } catch {
+    // npm registration can survive a missing, damaged or stale native file.
+    // Restore that exact package version, then verify the real executable.
+    await ensureNativeBinary(env, { force: true, dest: native, version });
+    verifyNpmEntryVersion(native, version, env);
+  }
+}
+
+export async function verifyInstalledCLI(tools, npmEnv, prefix, version, env, ignoreLauncher = "") {
+  const registered = readGlobalPackageVersion(tools, npmEnv);
+  if (registered !== version) {
+    throw new InstallerError(`npm registered version ${registered} does not match ${version}`, "UPDATE_VERIFY_FAILED");
+  }
+  const native = packageNativeBinary(prefix);
+  await repairAndVerifyNative(native, version, env);
+  const entry = globalWhobotEntry(prefix);
+  verifyNpmEntryVersion(entry, version, env);
+  const onPath = whichCommand(COMMAND, env, ignoreLauncher);
+  if (onPath && realpathSync(onPath) !== realpathSync(entry)) {
+    throw new InstallerError(`PATH resolves ${COMMAND} to another entry: ${onPath}; remove or replace it before using ${entry}`, "UPDATE_VERIFY_FAILED");
+  }
+  return { entry, native };
+}
+
 function parseExplicitInstallArgs(argv) {
   const { forwarded } = parseChannelAndForward(argv);
+  let resetLocal = false;
   for (const a of forwarded) {
+    if (a === "--reset-local") {
+      resetLocal = true;
+      continue;
+    }
     if (a.startsWith("-")) {
       throw new InstallerError(`unknown flag ${a}`);
     }
     throw new InstallerError(`unexpected argument ${a}`);
   }
+  return { resetLocal };
 }
 
 export async function runExplicitInstall(argv, env) {
   rejectExternalChannel(env);
-  parseExplicitInstallArgs(argv);
+  const { resetLocal } = parseExplicitInstallArgs(argv);
   bakedChannel();
+  if (!STABLE_TARGET.test(pkg.version)) {
+    throw new InstallerError("安装目标必须是完整的稳定 SemVer 版本", "UPDATE_VERIFY_FAILED");
+  }
   const tools = findRuntimeTools(env);
   if (tools.missing.length) {
     throw new InstallerError(runtimeMissingMessage(tools.missing));
@@ -607,20 +672,72 @@ export async function runExplicitInstall(argv, env) {
   const prefix = readNpmGlobalPrefix(tools, npmEnv);
   const entry = globalWhobotEntry(prefix);
   const registered = readGlobalPackageVersion(tools, npmEnv);
-  if (registered !== pkg.version || !(await pathExists(entry))) {
-    logStderr(
-      registered
-        ? `installing global ${pkg.name}@${pkg.version} (was ${registered})`
-        : `installing global ${pkg.name}@${pkg.version}`,
-    );
-    npmInstallGlobalFrom(tools, pkgRoot, npmEnv);
-  } else {
-    logStderr(`global ${pkg.name}@${pkg.version} already registered`);
+  logStderr(`install target ${pkg.name}@${pkg.version} (channel ${bakedChannel()})`);
+  // Validate with the new reader before replacing the installed program.
+  // Published v1 updaters cannot validate the v2 output protocol.
+  const staging = await fs.mkdtemp(path.join(os.tmpdir(), "whobot-install-preflight-"));
+  const stagedNative = path.join(staging, path.basename(packageNativeBinary(prefix)));
+  const updateArgs = ["update", "--yes", "--target-version", pkg.version];
+  let prepared;
+  try {
+    await ensureNativeBinary(env, { force: true, dest: stagedNative, version: pkg.version });
+    verifyNpmEntryVersion(stagedNative, pkg.version, env);
+    if (resetLocal) runResetLocal(stagedNative, env);
+    runInstallPhase(stagedNative, ["update", "check-install", "--previous-binary", packageNativeBinary(prefix)], env, "binding", registered);
+    runInstallPhase(stagedNative, updateArgs, env, "preflight", registered);
+    prepared = await prepareNativeReplace(packageNativeBinary(prefix));
+    if (registered !== pkg.version || !(await pathExists(entry))) {
+      logStderr(registered ? `installing global ${pkg.name}@${pkg.version} (was ${registered})` : `installing global ${pkg.name}@${pkg.version}`);
+      npmInstallGlobalFrom(tools, pkgRoot, npmEnv);
+    }
+    // Ignore this npx cache launcher only, not other stale host PATH entries.
+    const ignoreLauncher = isNpxPath(pkgRoot) ? realpathSync(path.join(pkgRoot, "bin", "run.mjs")) : "";
+    const installed = await verifyInstalledCLI(tools, npmEnv, prefix, pkg.version, env, ignoreLauncher);
+    runInstallPhase(installed.native, updateArgs, env, "verify", registered);
+    await prepared.discard();
+    if (resetLocal) logStderr("本机登录已清理，请重新登录。");
+    logStderr(`CLI 软件安装已完成；请更新 Skill 至对应渠道最新版，重载宿主或新建任务后重新预检。v2 后续更新请运行 ${COMMAND} update，并执行确认卡中的命令。`);
+    return entry;
+  } catch (err) {
+    if (prepared) await prepared.restore();
+    throw err;
+  } finally {
+    await fs.rm(staging, { recursive: true, force: true });
   }
-  if (!(await pathExists(entry))) {
-    throw new InstallerError(`global command entry is missing: ${entry}`);
+}
+
+function runInstallPhase(native, args, env, phase, previous, wantVersion = pkg.version) {
+  const result = spawnSync(native, args, {
+    encoding: "utf8",
+    env: { ...env, WHOBOT_UPDATE_PHASE: phase, WHOBOT_UPDATE_LOCK_PID: String(process.pid), WHOBOT_UPDATE_PREVIOUS_VERSION: previous || "" },
+    windowsHide: true,
+  });
+  if (result.error || result.signal) throw new InstallerError(`安装${phase}检查未完成: ${result.error?.message || result.signal}`, "UPDATE_VERIFY_FAILED");
+  let response;
+  try { response = JSON.parse(result.stdout); } catch { throw new InstallerError("安装检查没有返回合法 JSON", "UPDATE_VERIFY_FAILED"); }
+  if (result.status !== 0 || !response.ok || response.next?.action !== "done" || response.data?.installedVersion !== wantVersion) {
+    const code = response.error?.code || "UPDATE_VERIFY_FAILED";
+    // These two already name the recovery (install --reset-local, then sign in again).
+    const tail = RESET_LOCAL_CODES.has(code) ? "。" : "；请按上述原因处理后重试，不要删除客户端安装身份。";
+    throw new InstallerError(`安装未完成: ${code} ${response.error?.detail || response.error?.userMessage || "目标程序未通过验收"}${tail}`, "UPDATE_VERIFY_FAILED");
+  }
+  return response;
+}
+
+const RESET_LOCAL_CODES = new Set(["PREVIOUS_CLI_MISSING", "CREDENTIAL_ORIGIN_MISMATCH"]);
+
+// install --reset-local: the verified target program clears this profile's
+// local login before the binding check. Nothing is sent to any endpoint; the
+// user signs in again after installing.
+function runResetLocal(native, env) {
+  const result = spawnSync(native, ["reset", "--local-only", "--yes"], { encoding: "utf8", env, windowsHide: true });
+  if (result.error || result.signal) throw new InstallerError(`清理本机登录未完成: ${result.error?.message || result.signal}`, "UPDATE_VERIFY_FAILED");
+  let response;
+  try { response = JSON.parse(result.stdout); } catch { throw new InstallerError("清理本机登录没有返回合法 JSON", "UPDATE_VERIFY_FAILED"); }
+  if (result.status !== 0 || !response.ok || response.data?.scope !== "local") {
+    throw new InstallerError(`清理本机登录未完成: ${response.error?.code || "UPDATE_VERIFY_FAILED"} ${response.error?.detail || response.error?.userMessage || ""}`, "UPDATE_VERIFY_FAILED");
   }
-  return entry;
+  logStderr("cleared local login before install");
 }
 
 export async function runExplicitUpdate(argv, env) {
@@ -635,12 +752,22 @@ export async function runExplicitUpdate(argv, env) {
   const entry = globalWhobotEntry(prefix);
   const previous = readGlobalPackageVersion(tools, npmEnv);
   const channel = bakedChannel();
-  const spec = `${pkg.name}@${channel}`;
-  const targetVersion = readRegistryVersion(tools, npmEnv, channel);
+  const targetVersion = confirmedTargetVersion(argv);
+  const spec = `${pkg.name}@${targetVersion}`;
   const replacing = previous !== targetVersion || !(await pathExists(entry));
   const native = packageNativeBinary(prefix);
-  const prepared = replacing ? await prepareNativeReplace(native) : { restore: async () => {}, discard: async () => {} };
+  const staging = await fs.mkdtemp(path.join(os.tmpdir(), "whobot-update-target-"));
+  let prepared;
   try {
+    const targetNative = path.join(staging, path.basename(native));
+    await ensureNativeBinary(env, { force: true, dest: targetNative, version: targetVersion });
+    const checkArgs = ["update", "check-install", "--previous-binary", native];
+    for (let i = 0; i < argv.length; i++) {
+      if (argv[i] === "--global-config" || argv[i] === "-Q") checkArgs.push(argv[i], argv[++i]);
+      else if (argv[i].startsWith("--global-config=") || argv[i].startsWith("-Q=")) checkArgs.push(argv[i]);
+    }
+    runInstallPhase(targetNative, checkArgs, env, "binding", previous, targetVersion);
+    prepared = replacing ? await prepareNativeReplace(native) : { restore: async () => {}, discard: async () => {} };
     if (replacing) {
       logStderr(
         previous
@@ -654,18 +781,7 @@ export async function runExplicitUpdate(argv, env) {
     if (!(await pathExists(entry))) {
       throw new InstallerError(`global command entry is missing: ${entry}`);
     }
-    if (!(await isRegularFile(native))) {
-      try {
-        await ensureNativeBinary(env, { force: true, dest: native, version: targetVersion });
-      } catch (err) {
-        const message = err && err.message ? err.message : String(err);
-        throw new InstallerError(`更新后未找到原生 CLI: ${message}`, "UPDATE_VERIFY_FAILED");
-      }
-    }
-    if (!(await isRegularFile(native))) {
-      throw new InstallerError(`更新后未找到原生 CLI: ${native}`, "UPDATE_VERIFY_FAILED");
-    }
-    verifyNpmEntryVersion(native, targetVersion, env);
+    await verifyInstalledCLI(tools, npmEnv, prefix, targetVersion, env);
     await prepared.discard();
     return {
       entry,
@@ -676,19 +792,18 @@ export async function runExplicitUpdate(argv, env) {
       channel,
     };
   } catch (err) {
-    await prepared.restore();
+    if (prepared) await prepared.restore();
     throw err;
+  } finally {
+    await fs.rm(staging, { recursive: true, force: true });
   }
 }
 
 function launcherExitCode(code) {
   if (code === "CHANNEL_INVALID") {
-    return 76;
-  }
-  if (code === "UPDATE_VERIFY_FAILED") {
-    return 77;
+    return 2;
   }
-  return 1;
+  return 7;
 }
 
 function reportNativeFailure(dest, spawnErr, { jsonFailure = false } = {}) {
@@ -697,7 +812,7 @@ function reportNativeFailure(dest, spawnErr, { jsonFailure = false } = {}) {
     : `in-package binary cannot be executed: ${dest}`;
   if (jsonFailure) {
     writeJSONFailure("UPDATE_VERIFY_FAILED", message);
-    process.exitCode = 77;
+    process.exitCode = 7;
   } else {
     process.stderr.write(`${message}\n`);
     process.exitCode = 1;
@@ -744,22 +859,38 @@ export async function runWhobot(argv, env) {
     try {
       rejectExternalChannel(env);
       parseChannelAndForward(argv);
+      confirmedTargetVersion(argv);
       let currentNative = nativeBinaryPath(pkgRoot);
-      if (!(await isRegularFile(currentNative))) {
-        currentNative = await ensureNativeBinary(env);
+      let preflightDir;
+      let pre;
+      try {
+        try {
+          verifyNpmEntryVersion(currentNative, pkg.version, env);
+        } catch {
+          // A broken current program cannot check activity. Run a verified
+          // copy from temporary storage without replacing the installed file.
+          preflightDir = await fs.mkdtemp(path.join(os.tmpdir(), "whobot-preflight-"));
+          currentNative = path.join(preflightDir, path.basename(currentNative));
+          await ensureNativeBinary(env, { force: true, dest: currentNative, version: pkg.version });
+        }
+        pre = spawnSync(currentNative, argv, {
+          encoding: "utf8",
+          env: {
+            ...env,
+            WHOBOT_UPDATE_PHASE: "preflight",
+            WHOBOT_UPDATE_LOCK_PID: String(process.pid),
+          },
+          windowsHide: false,
+        });
+      } finally {
+        if (preflightDir) await fs.rm(preflightDir, { recursive: true, force: true });
       }
-      const pre = spawnSync(currentNative, argv, {
-        encoding: "utf8",
-        env: {
-          ...env,
-          WHOBOT_UPDATE_PHASE: "preflight",
-          WHOBOT_UPDATE_LOCK_PID: String(process.pid),
-        },
-        windowsHide: false,
-      });
       if (pre.stderr) {
         process.stderr.write(pre.stderr);
       }
+      if (pre.error || pre.signal) {
+        throw new InstallerError(`更新前检查未完成: ${pre.error?.message || pre.signal}`, "UPDATE_VERIFY_FAILED");
+      }
       if (pre.status !== 0) {
         if (pre.stdout) {
           process.stdout.write(pre.stdout);
@@ -767,6 +898,10 @@ export async function runWhobot(argv, env) {
         process.exitCode = pre.status ?? 1;
         return;
       }
+      const preflight = JSON.parse(pre.stdout);
+      if (!preflight.ok || preflight.data?.installedVersion !== pkg.version || preflight.next?.action !== "done") {
+        throw new InstallerError("更新前检查没有确认可以替换程序", "UPDATE_VERIFY_FAILED");
+      }
       const updated = await runExplicitUpdate(argv, env);
       spawnNative(
         updated.native,
@@ -780,7 +915,7 @@ export async function runWhobot(argv, env) {
         { jsonFailure: true },
       );
     } catch (err) {
-      const code = err && err.code ? err.code : "INTERNAL";
+      const code = err?.code === "CHANNEL_INVALID" ? "CHANNEL_INVALID" : "UPDATE_VERIFY_FAILED";
       const message = err && err.message ? err.message : String(err);
       writeJSONFailure(code, message);
       process.stderr.write(`${message}\n`);
@@ -832,7 +967,7 @@ export async function runInstall(argv, env) {
     smoke(smokeStage, version, home, env);
     await replaceAtomically(smokeStage, dest);
     smoke(dest, version, home, env);
-    await fs.writeFile(path.join(home, ".installer-managed"), "npx @whobot/cli\n", {
+    await fs.writeFile(path.join(home, ".installer-managed"), `npx ${pkg.name}\n`, {
       encoding: "utf8",
       mode: 0o644,
     });
@@ -924,9 +1059,9 @@ export function resolveHome(env, platform) {
   }
   const home = lookupUserHome(env, platform);
   if (!home) {
-    return WORKSPACE_HOME_NAME;
+    return HOME_NAME;
   }
-  return path.join(home, WORKSPACE_HOME_NAME);
+  return path.join(home, HOME_NAME);
 }
 
 function lookupUserHome(env, platform) {
@@ -997,7 +1132,7 @@ export async function resolveInstallHome(env, platform, cwd) {
       return path.resolve(preferred);
     }
   }
-  const fallback = path.resolve(cwd, WORKSPACE_HOME_NAME);
+  const fallback = path.resolve(cwd, HOME_NAME);
   if (await dirWritable(path.join(fallback, "bin"))) {
     return await fs.realpath(fallback);
   }
@@ -1129,7 +1264,7 @@ function normalizeArtifact(raw, known) {
 
 function archiveFileName(version, osName, arch) {
   const ext = osName === "windows" ? ".zip" : ".tar.gz";
-  return `whobot_${version}_${osName}_${arch}${ext}`;
+  return `${COMMAND}_${version}_${osName}_${arch}${ext}`;
 }
 
 async function downloadFile(url, dest, expectedSize, expectedSHA, env) {
@@ -1449,9 +1584,9 @@ function smoke(binPath, version, home, env) {
   if (parsed.ok !== true) {
     throw new InstallerError("version smoke ok=false");
   }
-  if (parsed.data?.protocolVersion !== 1) {
+  if (parsed.meta?.protocol !== 2) {
     throw new InstallerError(
-      `protocolVersion ${parsed.data?.protocolVersion} is not 1`,
+      `protocol ${parsed.meta?.protocol} is not 2`,
     );
   }
   if (parsed.data?.version !== version) {

package/bootstrap.json

@@ -2,6 +2,7 @@
   "schemaVersion": 1,
   "channel": "latest",
   "downloadBase": "https://download.whobot.com/agent-cli",
+  "homeName": ".whobot-cli",
   "knownOs": [
     "darwin",
     "linux",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whobot/cli",
-  "version": "1.0.1",
+  "version": "2.0.1",
   "description": "Whobot CLI: npm-managed JS launcher that runs the in-package Go binary.",
   "type": "module",
   "bin": {