@bolloon/bolloon-agent 0.5.1 → 0.5.3

package/dist/cli/identity-command.js

@@ -17,10 +17,13 @@
  */
 import * as fs from 'fs/promises';
 import * as os from 'os';
+import * as path from 'path';
 import * as crypto from 'crypto';
-import { okEnvelope, failEnvelope, line, title, hint, plain, has, } from './protocol-envelope.js';
+import { okEnvelope, failEnvelope, line, title, hint, plain, has, opt, } from './protocol-envelope.js';
 import { getLocalIdentityFile, initLocalIdentity } from './setup-wizard.js';
 import { AUDIT_FORBIDDEN_KEYS } from '../agents/task-contract.js';
+import { KeyManager } from '@diap/sdk';
+import { ADDRESS_BINDING_PROTOCOL, BINDING_INDEX_FILENAME, DEFAULT_BINDING_CHAIN_ID, BINDING_ADDRESS_RE, bindingsDir, bindingIndexPath, newBindingNonce, createAddressBinding, verifyAddressBinding, payerIdentityOf, writeBindingRecord, readBindingRecord, readBindingIndex, rebuildBindingIndex, loadPayerIdentityIndex, buildPublicBindingProjection, didShort, } from '../agents/identity/address-binding.js';
 export const IDENTITY_USAGE = `
 ${title('bolloon identity')}
   bolloon identity init [--force] [--json]
@@ -31,6 +34,25 @@ ${title('bolloon identity')}
       **绝不打印私钥** (输出只有 did / 文件路径 / 文件权限)
   bolloon identity show [--json]
       看本机身份: did · 公钥指纹(sha256 前 16 位) · 文件权限 · 创建时间 (不含私钥)
+  bolloon identity bind-address --address 0x…全小写 --address-key-file <path> [--label <名>]
+                              [--did-key-file <path>] [--chain-id 8453] [--expires-at <ISO8601>]
+                              [--bindings-dir <dir>] [--json]
+      登记「地址 ↔ DID」绑定 (**链下登记, 可离线验签**): 同一份声明正文被**两侧**签名 ——
+        · sig_did  = DID 私钥 (Ed25519, ~/.bolloon/identity.json) 对 canonical 正文签名
+        · sig_addr = 该以太地址私钥 (EIP-191 personal_sign) 对**同一份**正文签名
+      验证 = 两侧都过才算数 (少一侧 = 拒, 不降级)。落盘前**自验不通过就整条失败** (不留半成品)。
+      红线: **没有默认钱包路径** (--address-key-file 必填, 以免手滑拿主钱包签); 私钥不进任何输出。
+      名字短写: --label 会被清洗成 [A-Za-z0-9._-] + 中日文 (≤24 字符), 另有一枚 label_sig 覆盖它。
+  bolloon identity bindings list   [--bindings-dir <dir>] [--json]
+      列本机绑定库 (~/.bolloon/bindings): id · 名字短写 · DID 短写 · 地址(仅本机) · 链 · 签发时间
+      **重验**: 每条都当场验一遍, 不通过的如实列出 (它们不会进快照)
+  bolloon identity bindings show   <file> [--json]
+      看一条绑定的正文/签名/判据 (地址与 DID 全文只在本机命令里出; 页面上只出短写)
+  bolloon identity bindings verify <file> [--bindings-dir <dir>] [--json]
+      离线复验一条绑定: 逐条列判据 (双侧签名 · 正文 canonical · did↔公钥自洽 · 时效 · nonce 一次性);
+      **不过 = 非零退出码**
+  bolloon identity bindings publish --out <path> [--bindings-dir <dir>] [--json]
+      写出**对外投影** (显式路径): 只有短写 (name_short / did_short) + 地址哈希; 地址与完整 DID 不出
 
 选项: --json · --quiet · --force (只对 init 有效)
 说明: 只建 identity.json; 供应商/API key 仍走 bolloon setup (或 bolloon setup --provider … --api-key …);
@@ -170,8 +192,311 @@ export async function identityCommand(flags) {
         return identityInit(flags);
     if (sub === 'show' || sub === 'status')
         return identityShow(flags);
+    if (sub === 'bind-address')
+        return identityBindAddress(flags);
+    if (sub === 'bindings')
+        return identityBindings(flags);
     return {
-        envelope: failEnvelope('INVALID_ARGUMENT', sub ? `未知 identity 子命令: ${sub}` : '缺少 identity 子命令 (init | show)', { usage: plain(IDENTITY_USAGE.trim()), accepted: ['bolloon identity init', 'bolloon identity show'] }, [], 'needs_human'),
+        envelope: failEnvelope('INVALID_ARGUMENT', sub ? `未知 identity 子命令: ${sub}` : '缺少 identity 子命令 (init | show | bind-address | bindings)', { usage: plain(IDENTITY_USAGE.trim()), accepted: ['bolloon identity init', 'bolloon identity show', 'bolloon identity bind-address --address 0x… --address-key-file <path>', 'bolloon identity bindings list|show|verify|publish'] }, [], 'needs_human'),
         human: IDENTITY_USAGE,
     };
 }
+// ═══════════════════════════════════════════════════════════════════════════
+// 地址 ↔ DID 绑定登记 (`diap-address-binding/1`) —— 2026-09-29
+//   让网关能把链上付款行里的**付款方地址**翻成**智能体身份**。
+//   红线 (逐条都在这段代码里落实):
+//     · **不默认任何钱包路径** —— `--address-key-file` 必填, 免得手滑拿主钱包签名;
+//     · 私钥只在进程内用一次, **不进 stdout / 不进绑定文件 / 不进日志** (只打印地址);
+//     · 绑定库的 `nonce` 一次性: 生成时先查索引, 撞了就换;
+//     · 落盘前必须**自验通过**(双侧签名), 否则整条命令失败, 不留半成品。
+// ═══════════════════════════════════════════════════════════════════════════
+/** 读一个"以太地址私钥"文件: 认 JSON 的 `privateKey` 字段, 也认纯文本 (0x + 64 hex) */
+async function readAddressKeyFile(file) {
+    const raw = (await fs.readFile(file, 'utf-8')).trim();
+    let pk = '';
+    if (raw.startsWith('{')) {
+        const j = JSON.parse(raw);
+        pk = String(j?.privateKey ?? j?.private_key ?? j?.key ?? '');
+    }
+    else {
+        pk = raw.split(/\s+/)[0];
+    }
+    pk = pk.trim();
+    if (!/^(0x)?[0-9a-fA-F]{64}$/.test(pk)) {
+        throw new Error(`地址私钥文件里没找到 32 字节私钥 (JSON 的 privateKey 字段或纯文本 0x+64 hex): ${file}`);
+    }
+    return pk.startsWith('0x') ? pk : `0x${pk}`;
+}
+/** `bolloon identity bind-address --address 0x… --address-key-file <path> [--label …]` */
+async function identityBindAddress(flags) {
+    const head = 'bolloon identity bind-address';
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    const address = String(opt(flags, '--address') || '').trim().toLowerCase();
+    const keyFile = opt(flags, '--address-key-file');
+    const didFile = opt(flags, '--did-key-file') || getLocalIdentityFile(home);
+    const dir = opt(flags, '--bindings-dir') || bindingsDir(home);
+    const label = opt(flags, '--label');
+    const chainIdRaw = opt(flags, '--chain-id');
+    const expiresAt = opt(flags, '--expires-at') || null;
+    const bad = (code, msg, data = {}) => ({
+        envelope: failEnvelope(code, msg, { ...data, keyMaterialInOutput: false }, [], 'needs_human'),
+        human: `${title(head)}\n  原因: ${msg}\n\n${hint(IDENTITY_USAGE.trim())}`,
+    });
+    if (!address || !BINDING_ADDRESS_RE.test(address)) {
+        return bad('INVALID_ARGUMENT', `--address 必须是**全小写** 0x + 40 位十六进制 (实得 ${JSON.stringify(opt(flags, '--address') ?? '')})`, { address: address || null });
+    }
+    if (!keyFile) {
+        return bad('INVALID_ARGUMENT', '必须显式给 --address-key-file <path> —— 本命令**没有默认钱包**: 不替你在任何目录里找一个私钥来签 (以免拿主钱包误签)', { address, needs: '--address-key-file' });
+    }
+    const chainId = chainIdRaw ? Number(chainIdRaw) : DEFAULT_BINDING_CHAIN_ID;
+    if (!Number.isInteger(chainId) || chainId <= 0)
+        return bad('INVALID_ARGUMENT', `--chain-id 必须是正整数 (实得 ${JSON.stringify(chainIdRaw)})`, { chainId: chainIdRaw ?? null });
+    if (expiresAt && !Number.isFinite(Date.parse(expiresAt)))
+        return bad('INVALID_ARGUMENT', `--expires-at 必须是 ISO8601 时间串 (实得 ${expiresAt})`, { expiresAt });
+    // 地址私钥 (只读一次, 不进任何输出)
+    let addressKey = '';
+    try {
+        addressKey = await readAddressKeyFile(keyFile);
+    }
+    catch (e) {
+        return bad('NOT_FOUND', `读地址私钥失败: ${String(e?.message || e).slice(0, 160)}`, { addressKeyFile: keyFile });
+    }
+    // DID 身份 (与 `agent-identity.ts` / 卖方签名同源: KeyManager)
+    let did = '';
+    let didPrivateKeyHex = '';
+    let didPublicKeyHex = '';
+    try {
+        const kp = await KeyManager.fromFile(didFile);
+        did = String(kp?.did || '');
+        didPrivateKeyHex = Buffer.from(kp.privateKey).toString('hex');
+        didPublicKeyHex = Buffer.from(kp.publicKey).toString('hex');
+    }
+    catch (e) {
+        return bad('NOT_FOUND', `读本机 DID 身份失败 (${didFile}): ${String(e?.message || e).slice(0, 160)} —— 没有身份先跑 bolloon identity init`, { didKeyFile: didFile });
+    }
+    // nonce 一次性: 生成前先看本机索引里有没有撞 (撞了就换一枚)
+    let index = readBindingIndex({ dir });
+    if (!index) {
+        try {
+            index = await rebuildBindingIndex({ dir });
+        }
+        catch {
+            index = null;
+        }
+    }
+    const used = new Set(Object.keys(index?.nonces || {}));
+    let nonce = newBindingNonce();
+    for (let i = 0; i < 8 && used.has(nonce); i++)
+        nonce = newBindingNonce();
+    let rec;
+    try {
+        rec = await createAddressBinding({ did, didPrivateKeyHex, didPublicKeyHex, addressPrivateKeyHex: addressKey, address, chainId, expiresAt, nonce, label, createdBy: 'bolloon identity bind-address' });
+    }
+    catch (e) {
+        return bad('POLICY_DENIED', `造绑定失败 (未落盘): ${String(e?.message || e).slice(0, 200)}`, { address, chainId, didShort: didShort(did) });
+    }
+    finally {
+        addressKey = ''; // 用完即弃 (不留到后面任何一行)
+    }
+    let file = '';
+    try {
+        const w = await writeBindingRecord(rec, { dir });
+        file = w.file;
+    }
+    catch (e) {
+        return bad('DUPLICATE_REQUEST', `绑定落盘失败: ${String(e?.message || e).slice(0, 160)}`, { id: rec.id, dir });
+    }
+    const ident = payerIdentityOf(rec);
+    const payload = {
+        action: 'bound',
+        id: rec.id,
+        protocol: ADDRESS_BINDING_PROTOCOL,
+        address,
+        did,
+        didShort: ident.did_short,
+        nameShort: ident.name_short,
+        label: rec.label ?? null,
+        chainId: rec.statement.chainId,
+        issuedAt: rec.statement.issuedAt,
+        expiresAt: rec.statement.expiresAt,
+        nonce: rec.statement.nonce,
+        statementJson: rec.statement_json,
+        sigDidAlg: 'ed25519',
+        sigAddrAlg: 'eip-191-personal-sign',
+        verified: true,
+        verifiedChecks: rec.verified_checks ?? [],
+        file,
+        bindingsDir: dir,
+        didKeyFile: didFile,
+        addressKeyFile: keyFile,
+        keyMaterialInOutput: false,
+        semantics: '链下登记(可离线验签) —— 不是链上事实',
+    };
+    return {
+        envelope: okEnvelope('OK', `已登记地址↔DID 绑定 (${rec.id} · 双侧签名自验通过)`, payload, [
+            `off-chain signed statement: ${rec.statement_json}`,
+        ], null),
+        human: [
+            title(head),
+            line('绑定 id', rec.id),
+            line('协议', ADDRESS_BINDING_PROTOCOL),
+            line('地址', address),
+            line('DID', did),
+            line('DID 短写', ident.did_short),
+            line('智能体名', ident.name_short),
+            line('chainId', rec.statement.chainId),
+            line('issuedAt', rec.statement.issuedAt),
+            line('expiresAt', rec.statement.expiresAt ?? '(不过期)'),
+            line('绑定文件', file),
+            line('自验判据', (rec.verified_checks || []).join(' · ')),
+            '',
+            `  ${hint('口径: 「链下登记(可离线验签)」—— 这是签名声明, 不是链上事实')}`,
+            '  私钥没进任何输出; 地址私钥只在本进程内用了一瞬',
+            `  复核: bolloon identity bindings verify ${file}`,
+        ].join('\n'),
+    };
+}
+/** `bolloon identity bindings list|show|verify|publish` */
+async function identityBindings(flags) {
+    const head = 'bolloon identity bindings';
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    const dir = opt(flags, '--bindings-dir') || bindingsDir(home);
+    const sub = String(flags.positionals[1] ?? '').trim().toLowerCase();
+    const rest = flags.positionals.slice(2).filter((p) => p && p !== 'true');
+    const fail = (code, msg, data = {}) => ({
+        envelope: failEnvelope(code, msg, { ...data, bindingsDir: dir, keyMaterialInOutput: false }, [], 'needs_human'),
+        human: `${title(head)}\n  原因: ${msg}\n\n${hint('用法: bindings list [--bindings-dir <dir>] · bindings show <file> · bindings verify <file> [--bindings-dir <dir>] · bindings publish --out <path>')}`,
+    });
+    if (sub === 'list' || sub === '') {
+        let index = readBindingIndex({ dir });
+        let rebuilt = false;
+        if (!index) {
+            index = await rebuildBindingIndex({ dir });
+            rebuilt = true;
+        }
+        const rows = index.bindings.map((b) => ({
+            id: b.id, address: b.address, name_short: b.name_short, did_short: b.did_short,
+            chainId: b.chainId, issuedAt: b.issuedAt, expiresAt: b.expiresAt, verified_at: b.verified_at, file: b.file,
+        }));
+        const loaded = await loadPayerIdentityIndex({ dir, now: Date.now() });
+        return {
+            envelope: okEnvelope('OK', `${rows.length} 条绑定 (重验通过 ${loaded.verified}${loaded.rejected.length ? ` · 拒 ${loaded.rejected.length}` : ''})`, {
+                action: 'list', bindingsDir: dir, indexFile: bindingIndexPath(home) === path.join(dir, BINDING_INDEX_FILENAME) ? bindingIndexPath(home) : path.join(dir, BINDING_INDEX_FILENAME),
+                rebuilt, count: rows.length, verified: loaded.verified, rejected: loaded.rejected, reason: loaded.reason,
+                bindings: rows, keyMaterialInOutput: false,
+                semantics: '链下登记(可离线验签) —— 每行是签名声明, 不是链上事实; address 只在本机索引里',
+            }, [], null),
+            human: [
+                title(head + ' list'),
+                line('绑定库', dir),
+                line('条数', rows.length),
+                line('重验', loaded.reason),
+                ...(rows.length
+                    ? ['', ...rows.map((r) => `  ${r.id}  ${r.name_short.padEnd(20)} ${r.did_short}  ${r.address}  chain=${r.chainId}  ${r.issuedAt}`)]
+                    : ['', '  (空 —— 还没有地址↔DID 登记; 地址不出公开面, 名字来自链下签名声明)']),
+                ...(loaded.rejected.length ? ['', `  ⚠ 有 ${loaded.rejected.length} 条重验不过 (不进快照): ${loaded.rejected.map((r) => `${r.id}:${r.reasons.join(',')}`).join(' | ').slice(0, 200)}`] : []),
+            ].join('\n'),
+        };
+    }
+    if (sub === 'show' || sub === 'verify') {
+        const file = rest[0] ? path.resolve(rest[0]) : '';
+        if (!file)
+            return fail('INVALID_ARGUMENT', `bindings ${sub} 需要文件路径: <file>`);
+        let rec;
+        try {
+            rec = readBindingRecord(file);
+        }
+        catch (e) {
+            return fail('NOT_FOUND', `读绑定文件失败: ${String(e?.message || e).slice(0, 160)}`, { file });
+        }
+        const index = readBindingIndex({ dir });
+        const verdict = await verifyAddressBinding(rec, { now: Date.now(), ...(index ? { nonces: index.nonces } : {}) });
+        if (sub === 'show') {
+            const ident = verdict.ok ? payerIdentityOf(rec) : null;
+            return {
+                envelope: okEnvelope('OK', `绑定 ${rec.id} (验签 ${verdict.ok ? '通过' : '不通过'})`, {
+                    action: 'show', file, id: rec.id, protocol: rec.protocol,
+                    statement: rec.statement, statementJson: rec.statement_json,
+                    didPublicKey: rec.did_public_key, label: rec.label ?? null, labelCovered: verdict.label_covered,
+                    sigDid: rec.sig_did, sigAddr: rec.sig_addr,
+                    verified: verdict.ok, verifyReasons: verdict.reasons, checks: verdict.checks,
+                    nameShort: ident ? ident.name_short : null, didShort: ident ? ident.did_short : null,
+                    verified_at: rec.verified_at ?? null, created_by: rec.created_by ?? null,
+                    keyMaterialInOutput: false,
+                    semantics: '链下登记(可离线验签) —— 不是链上事实',
+                }, [], null),
+                human: [
+                    title(head + ' show'),
+                    line('文件', file),
+                    line('id', rec.id),
+                    line('正文 (canonical)', rec.statement_json),
+                    line('DID', rec.statement.did),
+                    line('地址', rec.statement.address),
+                    line('chainId', rec.statement.chainId),
+                    line('label', rec.label ?? '(无)'),
+                    line('名字覆盖', verdict.label_covered === null ? '(无 label)' : (verdict.label_covered ? 'label_sig 有效' : 'label_sig 无效')),
+                    line('sig_did', `${String(rec.sig_did || '').slice(0, 24)}… (ed25519, ${verdict.sig_did_ok ? '通过' : '不通过'})`),
+                    line('sig_addr', `${String(rec.sig_addr || '').slice(0, 20)}… (eip-191, ${verdict.sig_addr_ok ? '通过' : '不通过'})`),
+                    line('验签结论', verdict.ok ? '✅ 通过 (两侧)' : `❌ 拒: ${verdict.reasons.join(' | ')}`),
+                    '',
+                    `  ${hint('名字与短写只在**验签通过**时才算数; 未通过一律不出名字/不出 DID')}`,
+                ].join('\n'),
+            };
+        }
+        // verify: 判据逐条列出; 不过 = 非零退出码
+        const humanLines = [
+            title(head + ' verify'),
+            line('文件', file),
+            line('id', rec.id),
+            `  结论: ${verdict.ok ? '✅ 通过 (双侧签名 + 正文 canonical + 时效/nonce)' : `❌ 拒 (${verdict.reasons.join(' | ')})`}`,
+            '',
+            ...verdict.checks.map((c) => `  ${c.ok ? '✔' : '✘'} ${c.name.padEnd(24)} ${String(c.detail).slice(0, 120)}`),
+        ];
+        const payload = {
+            action: 'verify', file, id: rec.id, ok: verdict.ok, reasons: verdict.reasons,
+            checks: verdict.checks, sigDidOk: verdict.sig_did_ok, sigAddrOk: verdict.sig_addr_ok,
+            labelCovered: verdict.label_covered, address: verdict.address, did: verdict.did,
+            nonceChecked: !!index, keyMaterialInOutput: false,
+            semantics: '链下登记(可离线验签) —— 不是链上事实',
+        };
+        return verdict.ok
+            ? { envelope: okEnvelope('OK', `验签通过: ${rec.id}`, payload, [], null), human: humanLines.join('\n') }
+            : {
+                envelope: failEnvelope('SIGNATURE_INVALID', `验签不通过: ${rec.id} —— ${verdict.reasons.join(' | ')}`, payload, [], 'needs_human'),
+                human: humanLines.join('\n'),
+            };
+    }
+    if (sub === 'publish') {
+        const out = opt(flags, '--out');
+        if (!out)
+            return fail('INVALID_ARGUMENT', '缺少 --out <path> (显式路径, 不写死目录)');
+        const proj = await buildPublicBindingProjection({ dir });
+        const target = path.resolve(out);
+        try {
+            await fs.mkdir(path.dirname(target), { recursive: true });
+            await fs.writeFile(target, JSON.stringify(proj, null, 2), 'utf-8');
+        }
+        catch (e) {
+            return fail('INTERNAL_ERROR', `写投影失败 (${target}): ${String(e?.message || e).slice(0, 160)}`);
+        }
+        return {
+            envelope: okEnvelope('OK', `已写出对外投影 ${proj.count} 条 → ${target}`, {
+                action: 'publish', out: target, count: proj.count, protocol: proj.protocol, kind: proj.kind,
+                // 对外面只出短写: 地址只以 sha256 前 16 位出现
+                rows: proj.bindings.map((b) => ({ id: b.id, address_hash: b.address_hash, name_short: b.name_short, did_short: b.did_short })),
+                keyMaterialInOutput: false,
+                semantics: '链下登记(可离线验签) —— 对外只出短写; 地址不出 (只有哈希)',
+            }, [], null),
+            human: [
+                title(head + ' publish'),
+                line('写入', target),
+                line('条数', proj.count),
+                line('协议', proj.protocol),
+                ...proj.bindings.map((b) => `  ${b.id}  ${b.name_short.padEnd(20)} ${b.did_short}  ${b.address_hash}`),
+                '',
+                `  ${hint('对外面里没有完整地址、没有完整 DID —— 网关是**本机**按地址匹配的')}`,
+            ].join('\n'),
+        };
+    }
+    return fail('INVALID_ARGUMENT', `未知 bindings 子命令: ${sub || '(空)'} (list | show | verify | publish)`);
+}

package/dist/cli/protocol-envelope.js

@@ -75,6 +75,10 @@ const OPTIONS_WITH_VALUE = new Set([
     '--announcement-id',
     // 2026-09-23 (C7): 群聊通道 `bolloon task announce|trail|post` 的群链接/groupId + 极短事实字段
     '--group', '--round', '--criteria', '--kind', '--hash', '--bytes', '--checks', '--verdict', '--limit', '--from',
+    // 2026-09-29: `bolloon identity bind-address|bindings` 的显式路径与声明字段
+    //   (名字先查过全仓: `--address/--label/--out/--chain-id/--bindings-dir/--address-key-file/--did-key-file/--expires-at`
+    //    在其他 cli-entry 命令里都没有被当布尔开关用过 ⇒ 加进"带值选项"不会改变既有解析)
+    '--address', '--label', '--out', '--chain-id', '--bindings-dir', '--address-key-file', '--did-key-file', '--expires-at',
 ]);
 export function parseFlags(args) {
     const flags = { json: false, quiet: false, positionals: [], options: new Map(), raw: args };

package/dist/cli/update-commands.js

@@ -14,7 +14,7 @@
  */
 import { resolveBolloonHome } from '../setup/setup-store.js';
 import { collectVersionInfo, renderVersionText, renderVersionJson, DEV_CHANNEL_WARNING, DEV_BACK_TO_STABLE_HINT, channelKindOf, isDevIdentity, } from '../utils/version-info.js';
-import { checkForUpdate, buildUpdatePlan, renderUpdatePlan, applyUpdate, readUpdateStatus, readHistory, renderHistory, updateSummaryFor, compareVersions, checkExitCode, REFUSED_STATUSES, } from '../utils/update-manager.js';
+import { checkForUpdate, buildUpdatePlan, renderUpdatePlan, applyUpdate, readUpdateStatus, readHistory, renderHistory, updateSummaryFor, compareVersions, REFUSED_STATUSES, } from '../utils/update-manager.js';
 import { renderGithubReportLine } from '../utils/dual-source.js';
 import { runDoctor, renderDoctor } from '../utils/update-health.js';
 import { detectRuntimeReport, bootstrapRuntimes, renderRuntimeReport, renderBootstrapPlan, RUNTIME_MIN, readRuntimeConfigWithFallback, } from '../utils/runtime-bootstrap.js';
@@ -148,7 +148,7 @@ export function renderCheckResult(r) {
         L.push(`说明: ${r.reason}`);
     L.push('');
     if (r.status === 'update_available') {
-        L.push(`下一步: ${BOLD}bolloon update plan --channel ${r.channel}${RESET} 看计划, ${BOLD}bolloon update now --channel ${r.channel}${RESET} 执行更新`);
+        L.push(`下一步: ${BOLD}bolloon update --channel ${r.channel}${RESET} 直接更新 (会先打印计划与风险检查); 只想看计划不动任何东西: ${BOLD}bolloon update --dry-run${RESET}`);
         if (dev)
             L.push(DEV_CHANNEL_WARNING), L.push(DEV_BACK_TO_STABLE_HINT);
     }
@@ -183,7 +183,7 @@ export function renderStatusReport(s) {
         : 'stable (npm registry)'}`);
     L.push(`身份标识:   ${dev ? `commit ${s.installedDevSha || '未知'}` : s.currentVersion}`);
     L.push(`能切回:     ${s.switchableTo
-        ? `${s.switchableTo.channel} (${s.switchableTo.source}${s.switchableTo.target ? ` @ ${s.switchableTo.target}` : ''}) — 一键切: bolloon update now --channel ${s.switchableTo.channel}`
+        ? `${s.switchableTo.channel} (${s.switchableTo.source}${s.switchableTo.target ? ` @ ${s.switchableTo.target}` : ''}) — 一键切: bolloon update --channel ${s.switchableTo.channel}`
         : '无 (未知来源)'}`);
     if (s.lastDevSha && !dev)
         L.push(`上次 dev:   commit ${s.lastDevSha}${s.devCheckedAt ? ` @ ${s.devCheckedAt}` : ''} (已切回 stable)`);
@@ -218,7 +218,7 @@ export function renderStatusReport(s) {
 // ── update 子命令 ───────────────────────────────────────────────────────────
 export async function runUpdateCommand(args = []) {
     const home = resolveBolloonHome();
-    // 裸词优先 (bolloon update plan / status / history / now / wait / force / json / --channel dev),
+    // 裸词优先 (bolloon update / status / history / wait / force / dry-run / json / --channel dev),
     // 同时兼容旧的 --plan / --status / ... 写法 (已有脚本不断裂)。
     const has = (...f) => f.some((x) => args.includes(x));
     const json = has('json', '--json');
@@ -228,6 +228,28 @@ export async function runUpdateCommand(args = []) {
         return 2;
     }
     const channel = ch.channel;
+    // `update --help` 必须是**只读**的 (三合一后默认会真装, 这条不拦就会「看帮助反而装了东西」)
+    if (has('help', '-h', '--help')) {
+        out(UPDATE_HELP.trim());
+        return 0;
+    }
+    /**
+     * 防误触 (2026-09-28, 与三合一同时加的): `update` 现在**默认就执行更新** ——
+     * 于是打错一个词 (如 `bolloon update plna`) 会直接装东西, 这是不可接受的。
+     * 白名单之外、又不是数字、又不是 --channel 的取值的裸词 ⇒ 拒绝执行并打用法。
+     */
+    {
+        const KNOWN_BARE = new Set(['status', 'history', 'wait', 'force', 'dry-run', 'plan', 'json', 'now']);
+        const valIdx = new Set();
+        args.forEach((a, i) => { if (a === '--channel' || a === 'channel')
+            valIdx.add(i + 1); });
+        const unknown = args.filter((a, i) => !a.startsWith('-') && !KNOWN_BARE.has(a) && !/^\d+$/.test(a) && !valIdx.has(i));
+        if (unknown.length > 0) {
+            err(`${RED}✗ 不认识 ${BOLD}update ${unknown[0]}${RESET} —— 已拒绝执行 (什么都没装)`);
+            err(`  用法: bolloon update [wait|force] [--dry-run|status|history [N]] [--channel stable|dev]`);
+            return 2;
+        }
+    }
     // ── 状态 ──
     if (has('status', '--status')) {
         const s = await readUpdateStatus({ home, channel });
@@ -250,8 +272,9 @@ export async function runUpdateCommand(args = []) {
         out(renderHistory(recs));
         return 0;
     }
-    // ── 计划 ──
-    if (has('plan', '--plan')) {
+    // ── 只读: --dry-run (2026-09-28 leo: `update` 三个动作合成一个, 默认直接执行;
+    //    只读位改由 `--dry-run` 承接 —— 旧写法 `plan`/`--plan` 等价于它, **只打印、不装任何东西**) ──
+    if (has('dry-run', '--dry-run', 'plan', '--plan')) {
         const plan = await buildUpdatePlan({ home, force: true, channel });
         if (json) {
             out(JSON.stringify(plan, null, 2));
@@ -260,10 +283,15 @@ export async function runUpdateCommand(args = []) {
         out(renderUpdatePlan(plan));
         if (plan.channelKind === 'git-ref')
             printDevNotice();
+        out('');
+        out(`${YELLOW}本次只打印计划, 没有安装任何东西${RESET} —— 要真更新就运行 ${BOLD}bolloon update${RESET}`);
         return 0;
     }
-    // ── 执行 ──
-    if (has('now', '--now')) {
+    // ── 默认动作 (三合一): 计划 + 风险检查 + 直接执行 ──
+    {
+        if (has('now', '--now')) {
+            out(`${YELLOW}提示${RESET}: \`now\` 已去掉 —— \`bolloon update\` 现在直接执行更新 (本条按新行为继续)。`);
+        }
         const wait = has('wait', '--wait');
         const force = has('force', '--force', '-f');
         const plan = await buildUpdatePlan({ home, force: true, channel });
@@ -332,18 +360,6 @@ export async function runUpdateCommand(args = []) {
             err(`  已回滚到 ${res.from}`);
         return 1;
     }
-    // ── 默认: 只检查, 给清晰结论 (显式命令 = 忽略节流) ──
-    const r = await checkForUpdate({ home, force: true, channel });
-    if (json) {
-        out(JSON.stringify(r, null, 2));
-        return checkExitCode(r.status);
-    }
-    out(renderCheckResult(r));
-    if (r.status !== 'up_to_date' && r.status !== 'check_skipped') {
-        out('');
-        out(`${YELLOW}提示${RESET}: 本次只检查, 没有安装任何东西。`);
-    }
-    return checkExitCode(r.status);
 }
 // ── doctor ──────────────────────────────────────────────────────────────────
 export async function runDoctorCommand(args = []) {
@@ -441,12 +457,12 @@ ${BOLD}版本与更新:${RESET} (子命令一律裸词, 不带 -- 前缀)
   bolloon --version                  版本 + 安装方式/目录/入口/通道/来源身份/上游/是否最新
   bolloon --version verbose          诊断版 (构建时间/git/Node/npm/Python/配置目录/最近更新)
   bolloon --version json             机器版 (同一份 VersionInfo, 给脚本与问题报告)
-  bolloon update                     只检查并给结论 (不安装任何东西)
-  bolloon update plan                更新计划: 要更新什么 / 不会动什么 / 风险检查
+  bolloon update                     直接执行更新 (先打印计划与风险检查, 再真装; 不写 plan/now)
+  bolloon update --dry-run           只看计划与风险检查, 一个字节都不动 (旧 update plan 等价于它)
+  bolloon update wait                等当前 Run 结束后再更新 (有长期任务时的默认建议)
+  bolloon update force               忽略"有长期任务在跑"的提醒 (阻塞项仍然阻塞)
   bolloon update status              更新状态: 装的哪个源+版本/commit+能切回哪/最近检查/失败/开关
   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)
@@ -456,7 +472,7 @@ ${BOLD}双源 (--channel):${RESET}
                            比较语义 = semver (npm 的 latest ↔ GitHub 同名 tag)
   --channel dev     GitHub master HEAD 是唯一源; 比较语义 = git ref + commit sha (不用 semver);
                            身份 = <版本>+dev.<sha7>; 未走发布门, 会打印警告并记录 sha
-  一键回稳定版:     bolloon update now --channel stable
+  一键回稳定版:     bolloon update --channel stable
   --channel 只覆盖本次进程, 不落盘 (config 里的 updateChannel 仍是默认值)
   源不可达 / 版本不存在 → 拒绝并说清 (退出码 2), 不会静默装回旧版