@bolloon/bolloon-agent 0.4.28 → 0.4.30

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';
@@ -42,6 +45,8 @@ export { TOOL_DEFINITIONS, } from './pi-sdk-types.js';
 export { PiSessionManager } from './pi-sdk-session-manager.js';
 import { PiSessionManager } from './pi-sdk-session-manager.js';
 import { registerBuiltinTools, registerWalletTools, setupInboxListener, IdempotencyCache, } from './pi-sdk-tools.js';
+import { registerContactTools } from './contacts/tools.js';
+import { ContactChain } from './contacts/chain.js';
 export { createAgentSession, getAgentSession, resetAgentSession, runSelfImproveLoop, } from './pi-sdk-session-factory.js';
 // Judgment 注入门 (P0): 在主对话 LLM 调起前自动拼入 Top 3 判断力
 // 失败静默, 不阻塞主对话
@@ -572,6 +577,14 @@ export class PiAgentSession {
             },
         };
         registerBuiltinTools(toolCtx);
+        // 2026-09-19: 联系方式工具 (手机/邮箱) —— Agent 拿不到明文, 只能给 contactId;
+        //   所有调用都要过 contacts/policy (首次联系/敏感内容需人工批准, 批量永远禁止)。
+        try {
+            registerContactTools(toolCtx, new ContactChain({ ownerDid: this.identity?.did || 'did:bolln:local' }));
+        }
+        catch (err) {
+            console.warn('[contacts] 注册联系工具失败 (非致命, 该能力不可用):', err?.message || err);
+        }
         registerWalletTools(toolCtx);
         setupInboxListener(toolCtx);
         // 镜像到 ToolRegistry (alias resolve 用)

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 不可用/读不到本地版本)
+`;

package/dist/cli-entry.js

@@ -20,6 +20,8 @@ import { fileURLToPath } from 'url';
 import { printBanner } from './cli/loading-tui.js';
 import { discoverEngines, delegateToEngine } from './external-engines/index.js';
 import { x402CheckBalance, x402Fetch } from './agents/x402/x402Pay.js';
+import { runVersionCommand, runUpdateCommand, runDoctorCommand, runRuntimeCommand, UPDATE_HELP } from './cli/update-commands.js';
+import { collectVersionInfo } from './utils/version-info.js';
 import { createRequire } from 'module';
 const _require = createRequire(import.meta.url);
 const isWindows = process.platform === 'win32';
@@ -31,18 +33,8 @@ const CYAN = _fg(0xc4, 0xd6, 0x40); // #c4d640
 const YELLOW = _fg(0xf5, 0x9e, 0x0b); // #f59e0b
 const GREEN = _fg(0x22, 0xc5, 0x5e); // #22c55e
 const MAGENTA = _fg(0xef, 0x44, 0x44); // #ef4444
-// 版本信息 — 2026-07-20 Bug 3: 从 package.json 读取, 不再硬编码
-const VERSION = (() => {
-    try {
-        const entryDir = path.dirname(fileURLToPath(import.meta.url));
-        const pkgPath = path.resolve(entryDir, '..', 'package.json');
-        const raw = fs.readFileSync(pkgPath, 'utf-8');
-        return JSON.parse(raw).version || '0.0.0';
-    }
-    catch {
-        return '0.0.0';
-    }
-})();
+// 版本信息 — 2026-09-19: 统一走 version-info 的**唯一版本解析** (不再各读一遍 package.json)
+const VERSION = collectVersionInfo({ light: true }).packageVersion;
 function log(msg, color = RESET) {
     console.log(`${color}${msg}${RESET}`);
 }
@@ -58,12 +50,14 @@ ${BOLD}选项:${RESET}
   --gui, -g           启动图形界面 (Electron)
   --web, -w           启动 Web UI (浏览器)
   --cli, -c           启动命令行界面
-  --version, -v       显示版本信息
+  --version, -v       显示版本 (bolloon --version verbose / bolloon --version json)
   --help, -h          显示帮助信息
 
 ${BOLD}命令:${RESET}
   bolloon setup                     初始化向导 (你的称呼 + 模型供应商 + API key + 连通性测试)
-  bolloon update [--now]            检查更新 / 立即更新 (bolloon update --now)
+  bolloon update [plan|status|history|now]   检查更新 / 计划 / 状态 / 历史 / 执行 (默认只检查)
+  bolloon doctor                    安装入口 + 版本事实 + 更新状态自洽性诊断
+  bolloon runtime [plan|install]    运行时 (Node/npm/Git/Python) 检查与安装
   bolloon model [name] [model]      列出 / 切换模型供应商 (如: bolloon model deepseek deepseek-v4-flash)
   bolloon model key <name>          配置某供应商的 API key (隐藏输入, 不回显)
   bolloon model test [name]         测试供应商连通性
@@ -80,9 +74,11 @@ ${BOLD}示例:${RESET}
   bolloon --web              # 启动 Web UI
   bolloon --cli              # 命令行模式
   bolloon model              # 查看当前模型供应商
-  bolloon model minimax      # 切换到 MiniMax
-  bolloon update             # 检查更新
-  bolloon update --now       # 立即更新
+  bolloon update             # 检查更新 (只读, 不改任何东西)
+  bolloon update plan        # 看更新计划与风险检查
+  bolloon update now         # 真正执行更新
+  bolloon doctor             # 我这台机器的 Bolloon 是否自洽
+${UPDATE_HELP}
 
 ${BOLD}环境变量:${RESET}
   MINIMAX_API_KEY           MiniMax API 密钥
@@ -134,7 +130,10 @@ function parseArgs() {
     switch (mode) {
         case '-v':
         case '--version':
-            return { mode: 'version', args: [] };
+            // 2026-09-19: --version 现在分三层 (普通/--verbose/--json), 参数必须往下传
+            return { mode: 'version', args: args.slice(1) };
+        case 'version':
+            return { mode: 'version', args: args.slice(1) };
         case '-h':
         case '--help':
             return { mode: 'help', args: [] };
@@ -154,6 +153,12 @@ function parseArgs() {
         // 2026-08-06: 子命令形式 (去掉 -- 前缀)
         case 'update':
             return { mode: 'update', args: args.slice(1) };
+        // 2026-09-19: 安装入口/版本事实/更新状态 自洽性诊断
+        case 'doctor':
+            return { mode: 'doctor', args: args.slice(1) };
+        // 2026-09-19: 运行时 (Node/npm/Git/Python) 检查与安装
+        case 'runtime':
+            return { mode: 'runtime', args: args.slice(1) };
         case 'model':
             return { mode: 'model', args: args.slice(1) };
         // 2026-09-18: 智能体工具执行轨迹 + 本机 P2P 连接信息 (递给名片/小工具用)
@@ -293,41 +298,8 @@ async function handleX402Command(x402Args) {
     console.error(`未知 x402 子命令: ${sub}`);
     process.exit(1);
 }
-/** update 子命令: 检查 / 执行更新 (bolloon update [--now|now] [packages]) */
-async function handleUpdateCommand(updateArgs) {
-    const { checkForUpdates, performUpdate } = await import('./utils/auto-update.js');
-    // bolloon update --now / bolloon update now [packages] — 立即更新
-    if (updateArgs[0] === '--now' || updateArgs[0] === 'now') {
-        const packages = updateArgs.slice(1).filter(a => !a.startsWith('-'));
-        console.log('🔄 正在检查并更新...');
-        const result = await performUpdate(packages.length > 0 ? packages : undefined);
-        if (result.success) {
-            console.log(`${GREEN}✅ 更新成功${result.updatedPackages ? `: ${result.updatedPackages.join(', ')}` : ''}${RESET}`);
-            if (result.updated)
-                console.log(`${YELLOW}  请重新启动应用以使用新版本${RESET}`);
-        }
-        else {
-            console.error(`${MAGENTA}❌ 更新失败: ${result.error}${RESET}`);
-            process.exit(1);
-        }
-        return;
-    }
-    // 默认: 检查更新
-    console.log('🔄 正在检查更新...');
-    const info = await checkForUpdates();
-    if (info && info.outdated) {
-        console.log(`${CYAN}📦 发现更新可用:${RESET}\n`);
-        console.log(`  当前版本: ${info.version}`);
-        console.log(`  最新版本: ${info.latest}\n`);
-        console.log(`  待更新包:`);
-        for (const p of info.packages)
-            console.log(`    - ${p.name}: ${p.current} → ${p.latest}`);
-        console.log(`\n  运行 ${GREEN}bolloon update --now${RESET} 执行更新`);
-    }
-    else {
-        console.log(`${GREEN}✅ 已是最新版本${RESET} (${info?.version || 'unknown'})`);
-    }
-}
+/** update 子命令: 2026-09-19 起统一走 src/cli/update-commands.ts 的 runUpdateCommand
+ *  (旧实现只有"检查/--now"两种行为, 且各自拼一套版本信息 —— 已删除, 避免两套事实) */
 /** model 子命令: 列出 / 切换模型供应商 (bolloon model [name] [model]) */
 /**
  * `bolloon trace [runId] [--json] [--last N]`
@@ -516,6 +488,11 @@ async function handleSetupCommand(setupArgs) {
         const i = setupArgs.indexOf(name);
         return i >= 0 && i + 1 < setupArgs.length ? setupArgs[i + 1] : undefined;
     };
+    if (setupArgs.includes('repair-runtime') || setupArgs.includes('--repair-runtime')) {
+        // Phase 7: 补装缺失运行时 (与 bolloon runtime install yes 同一实现)
+        console.log(`${BOLD}setup repair-runtime${RESET} — 检查并补装 Node/npm/Git/Python (不偷偷 sudo)`);
+        process.exit(await runRuntimeCommand(['install', 'yes']));
+    }
     if (setupArgs.includes('--help') || setupArgs.includes('-h')) {
         console.log(`${BOLD}bolloon setup${RESET} — 初始化 Bolloon (用户身份 + 模型供应商 + API key)`);
         console.log('');
@@ -525,6 +502,7 @@ async function handleSetupCommand(setupArgs) {
         console.log('  --model <名>      指定模型');
         console.log('  --name <称呼>     你的称呼 (写入 ~/.bolloon/identity/user.json)');
         console.log('  --no-test         跳过连通性测试');
+        console.log('  repair-runtime    检查并补装缺失运行时 (Node/npm/Git/Python)');
         return;
     }
     const apiKey = val('--api-key');
@@ -731,7 +709,8 @@ async function main() {
     const { mode, args } = parseArgs();
     switch (mode) {
         case 'version':
-            console.log(`Bolloon Agent v${VERSION}`);
+            // 2026-09-19: 三层版本输出 (普通/--verbose/--json) 全走同一个 VersionInfo
+            process.exit(await runVersionCommand(args));
             break;
         case 'help':
             printHelp();
@@ -755,7 +734,14 @@ async function main() {
             break;
         // 2026-08-06: 子命令 (bolloon update / bolloon model)
         case 'update':
-            await handleUpdateCommand(args);
+            process.exit(await runUpdateCommand(args));
+            break;
+        case 'doctor':
+            process.exit(await runDoctorCommand(args));
+            break;
+        // 2026-09-19: 运行时检查/安装 (与 install.sh / postinstall / doctor 同一实现)
+        case 'runtime':
+            process.exit(await runRuntimeCommand(args));
             break;
         case 'model':
             await handleModelCommand(args);