@bolloon/bolloon-agent 0.4.28 → 0.4.29

package/bin/bolloon.cjs

@@ -1,157 +1,27 @@
 #!/usr/bin/env node
+/**
+ * 遗留 CJS 入口 (兼容老脚本/老文档里的 `node bin/bolloon.cjs`)。
+ * 真入口是 dist/cli-entry.js; 这里只转发, 不重复实现任何命令。
+ * NOTE: 本文件由 scripts/build-cli.js 生成 —— 改行为请改生成器, 别只改这里。
+ */
 const path = require("path");
-const { spawn } = require("child_process");
 const fs = require("fs");
+const { spawn } = require("child_process");
 
-const RESET = "\x1b[0m";
-const BOLD = "\x1b[1m";
-const CYAN = "\x1b[36m";
-const GREEN = "\x1b[32m";
-const MAGENTA = "\x1b[35m";
-
-function log(msg, color) {
-  console.log((color || RESET) + msg + RESET);
-}
-
-function printBanner() {
-  console.log("\n" + CYAN + BOLD + [
-    "   ╔═══════════════════════════════════════════╗",
-    "   ║      🤖 Bolloon Agent                     ║",
-    "   ║      P2P AI Document Processor            ║",
-    "   ╚═══════════════════════════════════════════╝"
-  ].join("\n") + RESET + "\n");
-}
-
-function getMainEntry() {
-  const distDir = path.dirname(require.main.filename);
-  const distIndex = path.join(distDir, "index.js");
-  if (fs.existsSync(distIndex)) {
-    return distIndex;
-  }
-  return path.join(process.cwd(), "src", "index.ts");
-}
-
-function parseArgs() {
-  const args = process.argv.slice(2);
-  if (args.length === 0) {
-    return { mode: "gui", args: [] };
-  }
-  const first = args[0];
-  switch (first) {
-    case "-v":
-    case "--version":
-      return { mode: "version", args: [] };
-    case "-h":
-    case "--help":
-      return { mode: "help", args: [] };
-    case "-g":
-    case "--gui":
-      return { mode: "gui", args: args.slice(1) };
-    case "-w":
-    case "--web":
-      return { mode: "web", args: args.slice(1) };
-    case "-c":
-    case "--cli":
-      return { mode: "cli", args: args.slice(1) };
-    default:
-      return { mode: "passthrough", args };
-  }
-}
-
-async function startElectron(additionalArgs) {
-  try {
-    const electron = require("electron");
-    const distDir = path.dirname(require.main.filename);
-    let mainPath = path.join(distDir, "electron.js");
-    if (!fs.existsSync(mainPath)) {
-      mainPath = path.join(process.cwd(), "src", "electron.ts");
-    }
-    log("启动 Electron...", CYAN);
-    const child = spawn(electron, [mainPath, ...additionalArgs], {
-      stdio: "inherit",
-      env: { ...process.env, NODE_ENV: "development" }
-    });
-    child.on("error", (err) => {
-      log("Electron 启动失败: " + err.message, MAGENTA);
-      process.exit(1);
-    });
-    child.on("exit", (code) => process.exit(code || 0));
-  } catch (err) {
-    log("Electron 不可用，切换到 Web 模式...", CYAN);
-    await startWebServer(additionalArgs);
-  }
-}
-
-async function startWebServer(additionalArgs) {
-  const mainPath = getMainEntry();
-  const webArgs = ["--web", ...additionalArgs];
-  log("启动 Web 服务...", CYAN);
-  const child = spawn(process.execPath, [mainPath, ...webArgs], { stdio: "inherit" });
-  child.on("error", (err) => {
-    log("Web 服务启动失败: " + err.message, MAGENTA);
-    process.exit(1);
-  });
-  child.on("exit", (code) => process.exit(code || 0));
-}
-
-async function startCLI(additionalArgs) {
-  const mainPath = getMainEntry();
-  log("启动命令行界面...", CYAN);
-  const child = spawn(process.execPath, [mainPath, ...additionalArgs], { stdio: "inherit" });
-  child.on("error", (err) => {
-    log("CLI 启动失败: " + err.message, MAGENTA);
-    process.exit(1);
-  });
-  child.on("exit", (code) => process.exit(code || 0));
-}
+const candidates = [
+  path.join(__dirname, "..", "dist", "cli-entry.js"),
+  path.join(__dirname, "..", "dist", "cli-entry.cjs"),
+];
+const entry = candidates.find((p) => fs.existsSync(p));
 
-async function main() {
-  const { mode, args } = parseArgs();
-  switch (mode) {
-    case "version":
-      console.log("Bolloon Agent v0.1.1");
-      break;
-    case "help":
-      printBanner();
-      console.log(BOLD + "用法:" + RESET + "  bolloon [选项] [命令] [参数]");
-      console.log(BOLD + "选项:" + RESET + "  --gui, -g           启动图形界面");
-      console.log("         --web, -w           启动 Web UI");
-      console.log("         --cli, -c           启动命令行界面");
-      console.log("         --version, -v       显示版本");
-      console.log("         --help, -h          显示帮助");
-      console.log(BOLD + "示例:" + RESET + "  bolloon              # 启动图形界面");
-      console.log("         bolloon --web        # 启动 Web UI");
-      console.log("         bolloon --read file  # 读取文档");
-      break;
-    case "gui":
-      printBanner();
-      await startElectron(args);
-      break;
-    case "web":
-      printBanner();
-      await startWebServer(args);
-      break;
-    case "cli":
-      await startCLI(args);
-      break;
-    case "passthrough":
-      const mainPath = getMainEntry();
-      const child = spawn(process.execPath, [mainPath, ...args], { stdio: "inherit" });
-      child.on("error", (err) => {
-        log("执行失败: " + err.message, MAGENTA);
-        process.exit(1);
-      });
-      child.on("exit", (code) => process.exit(code || 0));
-      break;
-    default:
-      log("未知模式: " + mode, MAGENTA);
-      printBanner();
-      console.log("输入 --help 查看帮助");
-      process.exit(1);
-  }
+if (!entry) {
+  console.error("❌ 找不到 dist/cli-entry.js —— 请先构建: npm run build:main");
+  process.exit(1);
 }
 
-main().catch((err) => {
-  console.error("Fatal error:", err);
+const child = spawn(process.execPath, [entry, ...process.argv.slice(2)], { stdio: "inherit" });
+child.on("error", (err) => {
+  console.error("启动失败:", err.message);
   process.exit(1);
 });
+child.on("exit", (code) => process.exit(code || 0));

package/bin/bolloon.cmd

@@ -2,10 +2,13 @@
 set "BOLLOON_ROOT=%~dp0"
 set "BOLLOON_ROOT=%BOLLOON_ROOT:~0,-1%"
 
-REM 确定入口文件
-set "ENTRY=%BOLLOON_ROOT%\dist\index.js"
+set "ENTRY=%BOLLOON_ROOT%\dist\cli-entry.js"
 if not exist "%ENTRY%" (
-    set "ENTRY=%BOLLOON_ROOT%\src\index.ts"
+    set "ENTRY=%BOLLOON_ROOT%\dist\index.js"
+)
+if not exist "%ENTRY%" (
+    echo 找不到 dist 入口, 请先构建: npm run build:main
+    exit /b 1
 )
 
 node "%ENTRY%" %*

package/dist/agents/pi-sdk-tools.js

@@ -1,6 +1,7 @@
 import * as fs from 'fs/promises';
 import * as fsSync from 'fs';
 import * as path from 'path';
+import { currentPackageRoot } from '../utils/version-info.js';
 import { documentReader } from '../documents/reader.js';
 import { p2pNetwork } from '../network/p2p.js';
 import { shellExec } from './shell-tool.js';
@@ -2453,7 +2454,8 @@ export function registerBuiltinTools(ctx) {
             try {
                 // fs 读 manifests/mcp-catalog.json — 构建后 dist/agents/../../manifests = 仓库根/manifests
                 const { readFileSync } = await import('fs');
-                const raw = readFileSync(new URL('../../manifests/mcp-catalog.json', import.meta.url), 'utf-8');
+                // 2026-09-19: 原为 new URL('../../manifests/...', import.meta.url) —— electron 构建(CommonJS)下 TS1343。
+                const raw = readFileSync(path.join(currentPackageRoot(), 'manifests', 'mcp-catalog.json'), 'utf-8');
                 const catalog = JSON.parse(raw);
                 const entries = (catalog?.entries ?? []);
                 if (entries.length === 0) {

package/dist/agents/pi-sdk.js

@@ -14,9 +14,12 @@ import * as os from 'os';
 import * as path from 'path';
 import { getContextManager } from '../bootstrap/context-manager.js';
 import { createRequire } from 'module';
+import { currentPackageRoot } from '../utils/version-info.js';
 // 2026-08-07: ESM 下裸 require 抛错被 catch 吞掉 → estimateHistoryTokens/maxContextTokens 静默失效
 //   (状态栏恒 0 的第二层根因). 统一用 createRequire 加载 CJS 模块.
-const _piRequire = createRequire(import.meta.url);
+// 2026-09-19: 原为 createRequire(import.meta.url) —— electron 构建(CommonJS)下 TS1343。
+//   createRequire 只用来解析裸模块名, 给包内任意文件路径即可, 用包根 package.json 最稳。
+const _piRequire = createRequire(path.join(currentPackageRoot(), 'package.json'));
 import { documentReader } from '../documents/reader.js';
 import { getMinimax } from '../constraints/index.js';
 import { p2pNetwork } from '../network/p2p.js';

package/dist/cli/update-commands.js

@@ -0,0 +1,349 @@
+/**
+ * update-commands.ts — `bolloon --version` / `bolloon update` / `bolloon doctor` 的实现
+ * (Phase 1-7 的对外出口, 2026-09-19)
+ *
+ * 三个命令都只读同一个 `VersionInfo` / `UpdateState`, 不各自拼字符串:
+ *   --version [--verbose|--json]  版本身份 (普通 / 诊断 / 机器)
+ *   update [--plan|--status|--history|--now]  检查(默认) / 计划 / 状态 / 历史 / 执行
+ *   doctor                        安装入口 + 版本事实 + 更新状态的自洽性
+ *
+ * 退出码 (供脚本用, 稳定约定):
+ *   0  正常 (检查成功 / 更新成功 / doctor healthy|degraded)
+ *   1  执行失败 (更新失败 / doctor failed)
+ *   2  检查不可用 (离线 / registry 不可用 / 读不到本地版本) —— 与"没有更新"区分开
+ */
+import { resolveBolloonHome } from '../setup/setup-store.js';
+import { collectVersionInfo, renderVersionText, renderVersionJson, } from '../utils/version-info.js';
+import { checkForUpdate, buildUpdatePlan, renderUpdatePlan, applyUpdate, readUpdateStatus, readHistory, renderHistory, updateSummaryFor, compareVersions, } from '../utils/update-manager.js';
+import { runDoctor, renderDoctor } from '../utils/update-health.js';
+import { detectRuntimeReport, bootstrapRuntimes, renderRuntimeReport, renderBootstrapPlan, RUNTIME_MIN, readRuntimeConfigWithFallback, } from '../utils/runtime-bootstrap.js';
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const CYAN = '\x1b[38;2;196;214;64m';
+const GREEN = '\x1b[38;2;34;197;94m';
+const YELLOW = '\x1b[38;2;245;158;11m';
+const RED = '\x1b[38;2;239;68;68m';
+const out = (s) => process.stdout.write(s + '\n');
+const err = (s) => process.stderr.write(s + '\n');
+// ── 版本 ────────────────────────────────────────────────────────────────────
+export async function runVersionCommand(args = []) {
+    // 2026-09-19 (leo): 子命令一律**裸词**, 不再带 `--` 前缀 (只有 `--version` 本身保留 --)
+    // 为了不打断已经有脚本/肌肉记忆的用法, 旧的 `--verbose` / `--json` 仍然被接受。
+    const json = args.includes('json') || args.includes('--json');
+    const verbose = args.includes('verbose') || args.includes('--verbose') || args.includes('-V') || args.includes('all');
+    const home = resolveBolloonHome();
+    const update = await updateSummaryFor(home).catch(() => null);
+    // 运行时配置 (leo 2026-09-19: 展示安装信息时要展示这些配置)。
+    // 普通版做浅探测 (路径 + 版本); verbose/json 做**真执行验证** (git 建临时仓库/python 真跑脚本/node 真加载 CLI)。
+    const runtime = await detectRuntimeReport({ home, deep: verbose || json }).catch(() => null);
+    const rtCfg = await readRuntimeConfigWithFallback(home).catch(() => ({}));
+    const runtimeConfigBacked = Boolean(rtCfg.node);
+    // 机器版也要完整身份 (git commit / npm / Python) —— "给问题报告用"就必须有这些;
+    // 只有启动横幅那种高频场景才走 light。
+    const info = collectVersionInfo({ home, update, runtime, runtimeConfigBacked, light: false });
+    if (json) {
+        out(renderVersionJson(info));
+        return 0;
+    }
+    if (!verbose) {
+        // 普通版: 首次问"我运行的到底是什么"时也顺手把更新事实刷新一次
+        // (不发通知, 只是别让用户看到永远空白的"尚未检查"; 迁移自旧缓存时 lastCheckStatus 为 null)
+        if (!info.update || !info.update.lastCheckAt || !info.update.lastCheckStatus) {
+            const r = await checkForUpdate({ home, force: false }).catch(() => null);
+            if (r) {
+                const fresh = await updateSummaryFor(home).catch(() => null);
+                if (fresh)
+                    info.update = fresh;
+            }
+        }
+    }
+    out(renderVersionText(info, { verbose }));
+    if (verbose) {
+        out('');
+        out('提示: bolloon --version json 给脚本/问题报告用; bolloon doctor 看安装是否自洽。');
+    }
+    return 0;
+}
+// ── 更新状态渲染 ────────────────────────────────────────────────────────────
+function statusConclusion(status, latest, current) {
+    switch (status) {
+        case 'up_to_date': return `${GREEN}已是最新${RESET} (${current})`;
+        case 'update_available': return `${YELLOW}有新版可用${RESET} (${current} → ${latest || '未知'})`;
+        case 'check_skipped': return `${CYAN}使用缓存结论${RESET} (未打网络)`;
+        case 'offline': return `${RED}离线${RESET} — 连不上 npm registry, ${BOLD}不能判定为最新${RESET}`;
+        case 'registry_unavailable': return `${RED}registry 不可用${RESET} — ${BOLD}不能判定为最新${RESET}`;
+        case 'local_version_unknown': return `${RED}读不到本地版本${RESET} — 不判断是否有更新`;
+        case 'unsupported_installation': {
+            // 仍然把"和最新比到底差多少"说清楚 —— 不支持自动更新 ≠ 不需要知道有没有新版
+            const cmp = !latest ? '' : compareVersions(current, latest) < 0 ? ` — 已有更新版 ${latest}, 需按该安装方式手动升级` : ` — 本地 ${current} 已是 registry 上最新`;
+            return `${YELLOW}当前安装方式不支持自动更新${RESET}${cmp}`;
+        }
+        default: return '尚未检查';
+    }
+}
+export function renderCheckResult(r) {
+    const L = [];
+    L.push(`当前版本: ${r.currentVersion}`);
+    L.push(`最新版本: ${r.latestVersion || '未知'}`);
+    L.push(`更新通道: ${r.channel} (来源: ${r.source})`);
+    L.push(`安装方式: ${r.installMethod}`);
+    L.push(`检查时间: ${r.checkedAt}${r.fromCache ? ' (缓存)' : ''}`);
+    L.push(`结论: ${statusConclusion(r.status, r.latestVersion, r.currentVersion)}`);
+    if (r.reason)
+        L.push(`说明: ${r.reason}`);
+    L.push('');
+    if (r.status === 'update_available') {
+        L.push(`下一步: ${BOLD}bolloon update plan${RESET} 看计划, ${BOLD}bolloon update now${RESET} 执行更新`);
+    }
+    else if (r.status === 'unsupported_installation') {
+        L.push('下一步: 按上面"说明"里对应安装方式更新 (源码目录: git pull && npm install && npm run build:all)');
+    }
+    else if (r.status === 'offline' || r.status === 'registry_unavailable') {
+        L.push('下一步: 检查网络/代理后重跑 `bolloon update`; 也可以 `bolloon update status` 看上次结论');
+    }
+    else if (r.status === 'local_version_unknown') {
+        L.push('下一步: 重新安装 (npm install -g @bolloon/bolloon-agent) 以恢复 package.json');
+    }
+    return L.join('\n');
+}
+export function renderStatusReport(s) {
+    const L = [];
+    const lu = s.lastUpdate;
+    L.push(`${BOLD}更新状态${RESET}`);
+    L.push(`当前版本:   ${s.currentVersion}`);
+    L.push(`最新版本:   ${s.latestVersion || (s.lastCheckStatus ? '未知' : '尚未检查')}`);
+    L.push(`是否最新:   ${statusConclusion(s.lastCheckStatus, s.latestVersion, s.currentVersion)}`);
+    L.push(`更新通道:   ${s.channel}`);
+    L.push(`安装方式:   ${s.installMethod}`);
+    L.push(`安装目录:   ${s.installDir}`);
+    L.push(`运行入口:   ${s.entryPath}`);
+    L.push(`最近检查:   ${s.lastCheckAt || '从未'}${s.lastCheckReason ? ` (${s.lastCheckReason})` : ''}`);
+    L.push(`最近更新:   ${lu ? `${lu.at} ${lu.from} → ${lu.to} [${lu.status}]${lu.reason ? ` ${lu.reason}` : ''}` : '无记录'}`);
+    L.push(`最近失败:   ${s.lastFailure ? `${s.lastFailure.at} @${s.lastFailure.stage}: ${s.lastFailure.reason}` : '无'}`);
+    L.push(`需要重启:   ${s.needsRestart ? '是 (新版已就位, 重启后生效)' : '否'}`);
+    L.push(`更新锁:     ${s.lock ? `有 (pid ${s.lock.pid}, ${s.lock.at}${s.lock.stale ? ', 已陈旧' : ''})` : '无'}`);
+    L.push(`开关:       检查更新=${s.prefs.checkUpdates} (${s.prefs.sources.checkUpdates}) · 自动安装=${s.prefs.autoInstall} (${s.prefs.sources.autoInstall}) · 自动重启=${s.prefs.autoRestart} (${s.prefs.sources.autoRestart})`);
+    return L.join('\n');
+}
+// ── update 子命令 ───────────────────────────────────────────────────────────
+export async function runUpdateCommand(args = []) {
+    const home = resolveBolloonHome();
+    // 裸词优先 (bolloon update plan / status / history / now / wait / force / json),
+    // 同时兼容旧的 --plan / --status / ... 写法 (已有脚本不断裂)。
+    const has = (...f) => f.some((x) => args.includes(x));
+    const json = has('json', '--json');
+    // ── 状态 ──
+    if (has('status', '--status')) {
+        const s = await readUpdateStatus({ home });
+        if (json) {
+            out(JSON.stringify(s, null, 2));
+            return 0;
+        }
+        out(renderStatusReport(s));
+        return 0;
+    }
+    // ── 历史 ──
+    if (has('history', '--history')) {
+        const idx = args.findIndex((a) => a === 'history' || a === '--history');
+        const n = parseInt(args[idx + 1] || '10', 10);
+        const recs = await readHistory(Number.isFinite(n) && n > 0 ? n : 10, home);
+        if (json) {
+            out(JSON.stringify(recs, null, 2));
+            return 0;
+        }
+        out(renderHistory(recs));
+        return 0;
+    }
+    // ── 计划 ──
+    if (has('plan', '--plan')) {
+        const plan = await buildUpdatePlan({ home, force: true });
+        if (json) {
+            out(JSON.stringify(plan, null, 2));
+            return 0;
+        }
+        out(renderUpdatePlan(plan));
+        return 0;
+    }
+    // ── 执行 ──
+    if (has('now', '--now')) {
+        const wait = has('wait', '--wait');
+        const force = has('force', '--force', '-f');
+        const plan = await buildUpdatePlan({ home, force: true });
+        if (!json)
+            out(renderUpdatePlan(plan));
+        if (!plan.ok && plan.blockers.length > 0) {
+            if (json)
+                out(JSON.stringify({ stage: 'blocked', reason: plan.blockers.join('; ') }, null, 2));
+            err(`${RED}✗ 更新被阻塞${RESET}: ${plan.blockers.join('; ')}`);
+            return 1;
+        }
+        if (!plan.targetVersion) {
+            if (json)
+                out(JSON.stringify({ stage: 'succeeded', ok: true, reason: '已是最新', from: plan.currentVersion, to: plan.currentVersion }, null, 2));
+            out(`${GREEN}✓ 已是最新, 无需更新${RESET} (${plan.currentVersion})`);
+            return 0;
+        }
+        const res = await applyUpdate({
+            home,
+            strategy: wait ? 'wait' : 'now',
+            force,
+            onStage: json ? undefined : (stage, detail) => out(`  [${stage}] ${detail}`),
+        });
+        if (json) {
+            out(JSON.stringify(res, null, 2));
+            return res.ok ? 0 : 1;
+        }
+        if (res.ok) {
+            out(`${GREEN}✓ 更新成功${RESET}: ${res.from} → ${res.to} (${(res.durationMs / 1000).toFixed(1)}s)`);
+            out('  正在做更新后健康检查...');
+            const health = await runDoctor({ bolloonHome: home }).catch(() => null);
+            if (health) {
+                out(renderDoctor(health));
+            }
+            out(`${YELLOW}请重启 bolloon 以使用新版本${RESET}`);
+            return 0;
+        }
+        if (res.stage === 'blocked') {
+            err(`${YELLOW}! ${res.reason}${RESET}`);
+            return 1;
+        }
+        err(`${RED}✗ 更新失败${RESET} (${res.stage}): ${res.reason}`);
+        err(`  旧版本仍在: ${res.from} — 可继续使用; 详情: bolloon update status`);
+        if (res.stage === 'rolled_back')
+            err(`  已回滚到 ${res.from}`);
+        return 1;
+    }
+    // ── 默认: 只检查, 给清晰结论 (显式命令 = 忽略节流) ──
+    const r = await checkForUpdate({ home, force: true });
+    if (json) {
+        out(JSON.stringify(r, null, 2));
+        return r.status === 'offline' || r.status === 'registry_unavailable' || r.status === 'local_version_unknown' ? 2 : 0;
+    }
+    out(renderCheckResult(r));
+    if (r.status !== 'up_to_date' && r.status !== 'check_skipped') {
+        out('');
+        out(`${YELLOW}提示${RESET}: 本次只检查, 没有安装任何东西。`);
+    }
+    if (r.status === 'offline' || r.status === 'registry_unavailable' || r.status === 'local_version_unknown')
+        return 2;
+    if (r.status === 'update_available' && compareVersions(r.currentVersion, r.latestVersion || r.currentVersion) >= 0)
+        return 0;
+    return 0;
+}
+// ── doctor ──────────────────────────────────────────────────────────────────
+export async function runDoctorCommand(args = []) {
+    const home = resolveBolloonHome();
+    const json = args.includes('json') || args.includes('--json');
+    const skipNetwork = args.includes('offline') || args.includes('--offline');
+    const rep = await runDoctor({ bolloonHome: home, skipNetwork });
+    if (json) {
+        out(JSON.stringify(rep, null, 2));
+        return rep.grade === 'failed' ? 1 : 0;
+    }
+    out(renderDoctor(rep));
+    return rep.grade === 'failed' ? 1 : 0;
+}
+/**
+ * `bolloon runtime [check|install|report|json|dry-run|yes]`
+ *   check/report  —— 只看 (Phase 5 报告: 四个运行时 + 五项能力)
+ *   install       —— 真安装缺失的运行时 (需要 yes; 不偷偷 sudo)
+ *   dry-run       —— 只显示将执行的命令
+ *   json          —— 机器可读
+ * 也是 `bolloon setup repair-runtime` 的同一实现 (只有一份)。
+ */
+export async function runRuntimeCommand(args = []) {
+    const home = resolveBolloonHome();
+    const json = args.includes('json') || args.includes('--json');
+    const dryRun = args.includes('dry-run') || args.includes('--dry-run');
+    const yes = args.includes('yes') || args.includes('--yes') || args.includes('-y');
+    const verbose = args.includes('verbose') || args.includes('--verbose');
+    const install = args.includes('install') || args.includes('repair') || args.includes('repair-runtime');
+    const wantPlan = args.includes('plan') || dryRun;
+    if (args.includes('help') || args.includes('--help')) {
+        out(`${BOLD}bolloon runtime${RESET} — 运行时 (Node/npm/Git/Python) 检查与安装`);
+        out('');
+        for (const [id, v] of Object.entries(RUNTIME_MIN))
+            out(`  ${id.padEnd(7)} 最低 ${v.min.padEnd(8)} ${v.why}`);
+        out('');
+        out('  bolloon runtime              检查并给报告 (真执行验证)');
+        out('  bolloon runtime verbose      同上 + 路径/来源/验证时间');
+        out('  bolloon runtime plan         只看安装计划 (要装什么/用哪个包管理器/是否要管理员权限)');
+        out('  bolloon runtime install yes  真安装缺失项 (不偷偷 sudo; 需要管理员权限时会明确说)');
+        out('  bolloon runtime dry-run      只显示将执行的命令');
+        out('  bolloon runtime json         机器可读');
+        return 0;
+    }
+    if (wantPlan && !install) {
+        const before = await detectRuntimeReport({ home, deep: false });
+        const { planBootstrap } = await import('../utils/runtime-bootstrap.js');
+        const plan = planBootstrap(before.facts);
+        if (json) {
+            out(JSON.stringify({ report: before, plan }, null, 2));
+            return before.ok ? 0 : 1;
+        }
+        out(renderBootstrapPlan(plan));
+        return before.ok ? 0 : 1;
+    }
+    if (install && !json) {
+        // Phase 3: 真正改变系统之前先显示一次计划 (装什么/用什么装/要不要管理员权限/是否改 PATH)
+        const before = await detectRuntimeReport({ home, deep: false });
+        const { planBootstrap } = await import('../utils/runtime-bootstrap.js');
+        out(renderBootstrapPlan(planBootstrap(before.facts)));
+        out('');
+        if (install && !yes)
+            out(`${YELLOW}未带 yes: 只显示计划, 不执行安装${RESET} (加 yes 才真装)`);
+    }
+    // 只看 (check/report): 不经过安装流程, 免得打印"未获得同意"这种与本次目的无关的话
+    if (!install && !dryRun) {
+        const fresh = await detectRuntimeReport({ home, deep: true });
+        if (json) {
+            out(JSON.stringify(fresh, null, 2));
+            return fresh.ok ? 0 : 1;
+        }
+        out(renderRuntimeReport(fresh, { verbose }));
+        return fresh.ok ? 0 : 1;
+    }
+    const rep = await bootstrapRuntimes({
+        home,
+        dryRun,
+        yes: install ? yes : false,
+        onProgress: json ? undefined : (m) => out(`  ${m}`),
+    });
+    if (json) {
+        out(JSON.stringify(rep, null, 2));
+        return rep.ok ? 0 : 1;
+    }
+    out(renderRuntimeReport(rep, { verbose: true }));
+    if (!rep.ok) {
+        out('');
+        out(`${YELLOW}不宣布安装成功${RESET}: ${rep.missing.concat(rep.belowMinimum).join(', ') || '运行时未全部就绪'}`);
+        return 1;
+    }
+    return 0;
+}
+export const UPDATE_HELP = `
+${BOLD}版本与更新:${RESET} (子命令一律裸词, 不带 -- 前缀)
+  bolloon --version                  版本 + 安装方式/目录/入口/通道/上游/是否最新
+  bolloon --version verbose          诊断版 (构建时间/git/Node/npm/Python/配置目录/最近更新)
+  bolloon --version json             机器版 (同一份 VersionInfo, 给脚本与问题报告)
+  bolloon update                     只检查并给结论 (不安装任何东西)
+  bolloon update plan                更新计划: 要更新什么 / 不会动什么 / 风险检查
+  bolloon update status              更新状态: 最近检查/最近更新/失败/是否需重启/开关
+  bolloon update history [N]         最近 N 次更新 (时间 · 版本变化 · 结果 · 耗时 · 原因)
+  bolloon update now                 真正执行更新 (默认先看计划)
+  bolloon update now wait            等当前 Run 结束后再更新 (有长期任务时的默认建议)
+  bolloon doctor                     安装入口 + 版本事实 + 更新状态 + 运行时 是否自洽
+  bolloon doctor json                同上, 机器可读
+  bolloon runtime [plan|install|json] 运行时 (Node/npm/Git/Python) 检查与安装 (install 需显式 yes)
+
+${BOLD}开关 (config.json):${RESET}
+  checkUpdates (默认 true)   启动时后台检查
+  autoInstall  (默认 false)  自动安装 —— 默认关, 需显式打开
+  autoRestart  (默认 false)  装完自动重启
+${BOLD}环境变量 (临时覆盖, 不落盘):${RESET}
+  BOLLOON_SKIP_UPDATE=1      本次不检查
+  BOLLOON_AUTO_UPDATE=1      本次允许自动安装
+  BOLLOON_UPDATE_CHANNEL=stable|beta|dev
+
+${BOLD}退出码:${RESET} 0 正常 · 1 执行失败 · 2 检查不可用 (离线/registry 不可用/读不到本地版本)
+`;