evolcore 0.0.33 → 0.0.34

package/dist/cli/daemon-commands.js

@@ -4,7 +4,7 @@ import os from 'os';
 import { spawn, execFile } from 'child_process';
 import { promisify } from 'util';
 import readline from 'readline';
-import { resolveRoot, resolvePaths, ensureDataDirs, getPackageRoot, agentMdPath } from '../paths.js';
+import { resolveRoot, resolvePaths, ensureDataDirs, getPackageRoot, agentMdPath, asModeOverridePath } from '../paths.js';
 import { loadDefaults, loadAllAgents, loadDaemonConfig, saveDaemonConfig } from '../config-store.js';
 import { resolveEffective } from '../config/config-manager.js';
 import { resolveAnthropicConfig } from '../agents/baseagent.js';
@@ -458,7 +458,73 @@ function resolveRunningDuration(pid, uptime) {
     const instance = scanInstances().mains.find(entry => entry.alive && entry.record.pid === pid);
     return instance ? formatRunningDuration(Date.now() - instance.record.startedAt) : '未知';
 }
-function printStartupInfo(opts = {}) {
+/**
+ * 渲染"运行模式"那一行。
+ *
+ * `daemonMode` 有值时用 daemon 实例记录里的模式（`ec status` 看的是正在跑的进程）；
+ * 没有时按当前进程判断（`ec start` 时就是这一份 CLI 即将拉起的模式）。
+ */
+/**
+ * CLI 侧按包路径判断模式。**不能用 isDevMode()**：它首次求值会读走并删除
+ * `--as-mode` 覆盖文件，那份文件只该由 daemon 消费。
+ */
+function packageIsDevMode() {
+    return !getPackageRoot().includes('node_modules');
+}
+export function describeRunMode(daemonMode, cliIsDevMode = packageIsDevMode()) {
+    const effective = daemonMode ?? (cliIsDevMode ? 'dev' : 'install');
+    const label = effective === 'install' ? '安装模式' : '开发模式';
+    const note = effective === 'install'
+        ? '（校验随包文件，篡改自动恢复）'
+        : '（不校验随包文件，可随意改动）';
+    return `运行模式:   ${label}${note}`;
+}
+/**
+ * 把本次 `--as-mode` 写进一次性覆盖文件，daemon 启动时读走并删除。
+ *
+ * 不走环境变量：环境变量会被 `ec restart` 全量继承，模式会在操作者不知情的
+ * 情况下被带到新进程。文件是一次性的，daemon 读过即删；若 daemon 最终没起来，
+ * 文件还留着，会在下一次启动时被读到——所以启动真实失败时此处清理。
+ */
+function writeAsModeOverride(asMode) {
+    const file = asModeOverridePath();
+    if (!asMode) {
+        // 没带 --as-mode：清掉上次失败启动可能残留的文件，保证这次按包路径判断
+        clearAsModeOverride(file);
+        return null;
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${asMode}\n`, 'utf-8');
+    return file;
+}
+function clearAsModeOverride(file) {
+    if (!file)
+        return;
+    try {
+        fs.rmSync(file, { force: true });
+    }
+    catch { /* ignore */ }
+}
+/** daemon 已在运行时 `--as-mode` 不会生效，明说，别让人以为切过去了。 */
+function warnAsModeNotApplied(asMode) {
+    if (!asMode)
+        return;
+    console.log(`  ⚠ --as-mode ${asMode} 未生效：daemon 已在运行，模式只在启动时确定。`);
+    console.log(`    需要切换请先 ec stop，再 ec start --as-mode ${asMode}。`);
+}
+function printAsModeNotice(asMode) {
+    if (!asMode)
+        return;
+    console.log('');
+    console.log(`🧪 本次运行模式已设为${asMode === 'install' ? '安装模式' : '开发模式'}（ec start --as-mode ${asMode}）`);
+    if (asMode === 'install') {
+        console.log('   随包发布的 kits/技能文件将按台账校验，带外改动会被自动恢复。');
+        console.log('   开发仓里请勿长期使用：本机 kits 文件会被登记进真实台账，');
+        console.log('   之后再按开发模式修改它们，会在下次以安装模式启动时被回滚。');
+    }
+    console.log('   只影响这一次启动；ec restart 不带该参数，会恢复按包路径判断。');
+}
+function printStartupInfo(opts = {}, asMode) {
     const pkgRoot = getPackageRoot();
     const isNpmInstall = pkgRoot.includes('node_modules');
     const cliRunsSource = !import.meta.url.includes('/dist/');
@@ -502,13 +568,18 @@ function printStartupInfo(opts = {}) {
     console.log(`${prefix}${version}${pidPart}${aunPart}`);
     console.log(`  包路径:     ${pkgRoot}`);
     console.log(`  安装类型:   ${isNpmInstall ? 'npm全局安装' : '开发仓(link)'}`);
+    // asMode 只是"本次请求"，是否生效要看 daemon 是否真的由这次启动拉起，标清楚别和实际模式混淆
+    const modeLine = describeRunMode(opts.runMode ?? asMode, !isNpmInstall);
+    console.log(`  ${asMode && !opts.runMode ? `${modeLine}（--as-mode 请求）` : modeLine}`);
     console.log(`  CLI执行:    ${cliRunsSource ? '源码(tsx)' : '编译产物(dist)'}`);
     console.log(`  Daemon执行: ${daemonRunsDist ? '编译产物(dist)' : '未知'}`);
     console.log(`  代码时间:   ${latestMtime ? formatLocalTime(latestMtime) : '?'}`);
 }
 export async function cmdStart(opts = {}) {
-    const cmdStartedAt = Date.now();
-    printStartupInfo();
+    // Measure from process start so the reported time includes CLI bootstrap
+    // (tsx compilation in a dev checkout), which is what the operator waits for.
+    const cmdStartedAt = Math.min(Date.now(), Math.round(performance.timeOrigin));
+    printStartupInfo(undefined, opts.asMode);
     const p = resolvePaths();
     const existingDaemon = await probeDaemon(p.socket);
     if (existingDaemon) {
@@ -521,6 +592,9 @@ export async function cmdStart(opts = {}) {
             return;
         }
         console.log(`  EvolCore is already running (PID: ${existingDaemon.pid}, IPC reachable)`);
+        const runningRecord = scanInstances().mains.find(m => m.alive && m.record.pid === existingDaemon.pid)?.record;
+        console.log(`  当前 daemon ${describeRunMode(runningRecord?.runMode)}`);
+        warnAsModeNotApplied(opts.asMode);
         console.log(`  已在运行；已运行时长: ${resolveRunningDuration(existingDaemon.pid, existingDaemon.uptime)}；部署/脚本可直接复用当前实例`);
         return;
     }
@@ -621,6 +695,8 @@ export async function cmdStart(opts = {}) {
         console.log(`  EvolCore is already running (PID: ${aliveMains.map(m => m.record.pid).join(', ')})`);
         console.log(`  启动于: ${new Date(first.record.startedAtIso).toLocaleString()}`);
         console.log(`  启动方式: ${first.record.launchedBy}`);
+        console.log(`  当前 daemon ${describeRunMode(first.record.runMode)}`);
+        warnAsModeNotApplied(opts.asMode);
         // 报告 AID 状态
         if (status.aidLastActivity.size > 0) {
             console.log('  AID 状态:');
@@ -647,7 +723,9 @@ export async function cmdStart(opts = {}) {
     // On Windows/macOS the process environment may be unavailable, so an
     // unregistered process from this package is conservatively treated as a
     // blocker when its HOME cannot be identified.
-    const orphans = findOrphanProcesses();
+    // No live main reached this point, so the registry snapshot above is still
+    // the authoritative "known PID" set; avoid a second scan.
+    const orphans = findOrphanProcesses(status);
     const blockingOrphans = orphans.filter(o => isRuntimeOrphan(o));
     if (blockingOrphans.length > 0) {
         console.error(`❌ 检测到未登记的 EvolCore 进程（PID: ${blockingOrphans.map(o => o.pid).join(', ')}），已停止启动以避免重复连接 AUN。`);
@@ -658,10 +736,13 @@ export async function cmdStart(opts = {}) {
     reportOrphans(orphans);
     if (versionInfo.some(result => result.hasUpdate)) {
         cleanEnv();
+        // 这条路由 restart-monitor 拉起 daemon，同样靠覆盖文件把 --as-mode 带过去
+        const overrideFile = writeAsModeOverride(opts.asMode);
         const launched = await launchPackageLifecycle('start', console.log, {
             prepared: true, foreground: opts.foreground, env: buildDaemonEnv(p, opts),
         });
         if (!launched.ok) {
+            clearAsModeOverride(overrideFile);
             console.error(`❌ 启动事务未能建立：${launched.reason}`);
             process.exitCode = 1;
         }
@@ -684,6 +765,7 @@ export async function cmdStart(opts = {}) {
     const appMain = path.join(getPackageRoot(), 'dist', 'index.js');
     const daemonEnv = buildDaemonEnv(p, opts);
     if (opts.foreground) {
+        const overrideFile = writeAsModeOverride(opts.asMode);
         const child = spawn('node', ['--no-warnings=ExperimentalWarning', appMain], {
             detached: false,
             stdio: 'inherit',
@@ -692,6 +774,7 @@ export async function cmdStart(opts = {}) {
         });
         const childPid = child.pid;
         if (!childPid) {
+            clearAsModeOverride(overrideFile);
             console.error('❌ Failed to start EvolCore (process creation failed)');
             process.exit(1);
             return;
@@ -710,16 +793,17 @@ export async function cmdStart(opts = {}) {
                 console.log('🔧 调试模式已启用（EVOLCORE_DEBUG_MODE=1）');
                 console.log('  在宿主终端以任意 session 身份执行命令：');
                 console.log('');
-                console.log('    ec msg send "消息内容" --as-session <sessionId>');
+                console.log(`    ec msg send '<消息内容>' --as-session <sessionId>`);
                 console.log('    ec trigger list --as-session <sessionId>');
                 console.log('    ec memory list --as-session <sessionId>');
                 console.log('');
                 console.log('  查看可用会话（运行后将在此处列出）：');
-                console.log('    ec msg send "test" --as-session   # 不带 sessionId 自动列出');
+                console.log(`    ec msg send 'test' --as-session   # 不带 sessionId 自动列出`);
                 console.log('');
                 console.log('  注意：重启 daemon（ec restart）会清除调试模式，');
                 console.log('        需重新执行 ec start --debug 才能恢复。');
             }
+            printAsModeNotice(opts.asMode);
             void waitForExistingEcweb(p).then((ecweb) => {
                 if (shouldPrintNoSelfAgentHints) {
                     printNoSelfAgentHints({ daemonConfig: loadDaemonConfig(), ecwebStarted: ecweb !== null, skipped });
@@ -766,6 +850,7 @@ export async function cmdStart(opts = {}) {
     const stdoutLog = path.join(p.logs, 'stdout.log');
     const out = fs.openSync(stdoutLog, 'a');
     const err = fs.openSync(stdoutLog, 'a');
+    const overrideFile = writeAsModeOverride(opts.asMode);
     const child = spawn('node', ['--no-warnings=ExperimentalWarning', appMain], {
         detached: true,
         stdio: ['ignore', out, err],
@@ -773,6 +858,12 @@ export async function cmdStart(opts = {}) {
         env: daemonEnv,
     });
     const childPid = child.pid;
+    // daemon 已在启动时读走该文件；若未能起来（pid 丢失/提前退出），清掉避免影响下次启动
+    child.once('error', () => clearAsModeOverride(overrideFile));
+    // Track liveness from the spawn handle instead of launching tasklist on
+    // every poll; the poll interval below is short enough that it matters.
+    let childExited = false;
+    child.once('exit', () => { childExited = true; });
     child.unref();
     // 等待 ready signal（最多 30 秒，AUN sidecar 超时 15s + 其他通道连接）
     const startTime = Date.now();
@@ -823,25 +914,27 @@ export async function cmdStart(opts = {}) {
                 printCodeStats(getPackageRoot(), p.logs);
             }
             console.log(`⏱ done in ${((Date.now() - cmdStartedAt) / 1000).toFixed(1)}s`);
+            printAsModeNotice(opts.asMode);
             if (opts.debug) {
                 console.log('');
                 console.log('🔧 调试模式已启用（EVOLCORE_DEBUG_MODE=1）');
                 console.log('  在宿主终端以任意 session 身份执行命令：');
                 console.log('');
-                console.log('    ec msg send "消息内容" --as-session <sessionId>');
+                console.log(`    ec msg send '<消息内容>' --as-session <sessionId>`);
                 console.log('    ec trigger list --as-session <sessionId>');
                 console.log('    ec memory list --as-session <sessionId>');
                 console.log('');
                 console.log('  查看可用会话（运行后将在此处列出）：');
-                console.log('    ec msg send "test" --as-session   # 不带 sessionId 自动列出');
+                console.log(`    ec msg send 'test' --as-session   # 不带 sessionId 自动列出`);
                 console.log('');
                 console.log('  注意：重启 daemon（ec restart）会清除调试模式，');
                 console.log('        需重新执行 ec start --debug 才能恢复。');
             }
-            // ECWeb lifecycle belongs to the daemon; the CLI only reports whether
-            // the supervised instance became healthy.
-            const ecwebStarted = await waitForExistingEcweb(p) !== null;
+            // ECWeb lifecycle belongs to the daemon; the CLI only needs its health
+            // for the no-agent hints. Waiting otherwise just holds the prompt for
+            // up to the probe timeout after the daemon is already ready.
             if (shouldPrintNoSelfAgentHints) {
+                const ecwebStarted = await waitForExistingEcweb(p) !== null;
                 printNoSelfAgentHints({ daemonConfig: loadDaemonConfig(), ecwebStarted, skipped });
             }
             return;
@@ -860,7 +953,7 @@ export async function cmdStart(opts = {}) {
             return;
         }
         // 进程已退出且无 ready signal
-        if (!platform.isProcessRunning(childPid)) {
+        if (childExited) {
             // 给进程一点时间写 ready signal（可能刚好在写入中）
             if (Date.now() - startTime > 3000) {
                 console.log('❌ Failed to start EvolCore');
@@ -875,9 +968,9 @@ export async function cmdStart(opts = {}) {
                 return;
             }
         }
-        setTimeout(checkReady, 500);
+        setTimeout(checkReady, 200);
     };
-    setTimeout(checkReady, 1000);
+    setTimeout(checkReady, 200);
 }
 function isPidReused(pid, expectedStartedAt) {
     if (expectedStartedAt === undefined)
@@ -890,7 +983,10 @@ function reportPidReused(pid) {
 }
 async function stopPid(pid, gracefulRequested = false, expectedStartedAt) {
     console.log(`🛑 Stopping EvolCore (PID: ${pid})...`);
-    if (isPidReused(pid, expectedStartedAt)) {
+    // A graceful request was accepted by the daemon that answered for this exact
+    // PID over IPC, so its identity is already proven; the start-time probe (a
+    // PowerShell launch on Windows) only guards the kill path.
+    if (!gracefulRequested && isPidReused(pid, expectedStartedAt)) {
         reportPidReused(pid);
         return true;
     }
@@ -939,7 +1035,7 @@ function isRuntimeOrphan(orphan, currentHome = resolveRoot()) {
 export async function cmdStop() {
     const status = scanInstances();
     const p = resolvePaths();
-    const initialOrphans = findOrphanProcesses();
+    const initialOrphans = findOrphanProcesses(status);
     const runtimeOrphans = initialOrphans.filter(orphan => isRuntimeOrphan(orphan, p.root));
     const ping = await probeDaemon(p.socket);
     if (ping && !hasVisibleDaemonPid(status, ping) && runtimeOrphans.length === 0) {
@@ -964,7 +1060,8 @@ export async function cmdStop() {
         process.exitCode = 1;
         return;
     }
-    await sleep(500);
+    // stopPid already observed every process leave the process table, so the
+    // records can be cleaned immediately (same reasoning as restart-monitor).
     cleanupInstances();
     if (aliveMains.length > 1) {
         console.log(`⚠ 停止了 ${aliveMains.length} 个 main 实例: ${aliveMains.map(m => m.record.pid).join(', ')}`);
@@ -973,6 +1070,9 @@ export async function cmdStop() {
 export async function cmdRestart(opts = {}) {
     const cmdStartedAt = Date.now();
     console.log('🔄 Restarting EvolCore...');
+    // 重启不带 --as-mode，模式按包路径重新判定；清掉可能残留的覆盖文件，并显示出来
+    writeAsModeOverride(undefined);
+    console.log(`  ${describeRunMode()}`);
     if (!await ensureCodexHookBeforeLifecycle())
         return;
     const initialStatus = scanInstances();
@@ -1186,7 +1286,8 @@ export async function cmdStatus() {
         console.log('');
     }
     if (pid) {
-        printStartupInfo({ pid, running: true });
+        const mainRecord = aliveMains.find(m => m.record.pid === pid)?.record;
+        printStartupInfo({ pid, running: true, runMode: mainRecord?.runMode });
         if (!ping) {
             console.log('⚠ 仅确认 daemon PID 存活，IPC 不可用，不能据此判断服务健康。');
             if (ipcFailure)

package/dist/cli/fs-command.js

@@ -56,7 +56,8 @@ Options:
   --content-type <mime>           上传时指定内容类型
   --public                        上传后公开可读（personal storage）
   --visibility <public|private>   chmod 可见性
-  --allow-roles <roles>           chmod 角色约束，逗号分隔
+  --allow-roles <roles>           chmod 角色约束，写法固定为单引号包住、逗号分隔，
+                                  如 --allow-roles 'owner,admin'
   -m aid:<aid>:<perms>            setfacl 新增/更新 ACL
   -x aid:<aid>                    setfacl 移除 ACL
   --source <AID>:<path>           mount 虚拟卷来源

package/dist/cli/index.js

@@ -78,7 +78,7 @@ AUN:
   EVENT_LOG         事件日志（默认: true）`;
 function printLifecycleHelp(command) {
     const help = {
-        start: `用法: ec start [--foreground] [--diagnose|-d]\n\n  --foreground   前台运行，适合 systemd 或容器直接管理\n  --diagnose, -d 以诊断模式启动 daemon`,
+        start: `用法: ec start [--foreground] [--diagnose|-d] [--debug] [--as-mode dev|install]\n\n  --foreground   前台运行，适合 systemd 或容器直接管理\n  --diagnose, -d 以诊断模式启动 daemon\n  --debug        调试模式：注册调试 IPC，可在宿主终端以任意 session 身份发命令\n  --as-mode      覆盖运行模式判定（仅本次启动生效，不写配置）：\n                   install = 按安装模式（校验随包文件完整性，篡改自动恢复）\n                   dev     = 按开发模式（不校验随包文件）`,
         stop: '用法: ec stop\n\n停止当前 EVOLCORE_HOME 下运行的 EvolCore 服务。',
         restart: `用法: ec restart [--clear] [--diagnose|-d]\n\n  --clear        同时清理跨 HOME 残留的 EvolCore 主进程\n  --diagnose, -d 以诊断模式启动新 daemon`,
         status: '用法: ec status\n\n查看 daemon、agent、渠道与会话运行状态。',
@@ -237,11 +237,20 @@ export async function main(args) {
                 printLifecycleHelp('start');
                 break;
             }
-            await cmdStart({
-                diagnose: strippedArgs.includes('--diagnose') || strippedArgs.includes('-d'),
-                foreground: strippedArgs.includes('--foreground'),
-                debug: strippedArgs.includes('--debug'),
-            });
+            {
+                const asModeRaw = getArgValue(strippedArgs, '--as-mode');
+                if (asModeRaw !== undefined && asModeRaw !== 'dev' && asModeRaw !== 'install') {
+                    console.error(`❌ --as-mode 只接受 dev 或 install，收到: ${asModeRaw}`);
+                    process.exitCode = 1;
+                    break;
+                }
+                await cmdStart({
+                    diagnose: strippedArgs.includes('--diagnose') || strippedArgs.includes('-d'),
+                    foreground: strippedArgs.includes('--foreground'),
+                    debug: strippedArgs.includes('--debug'),
+                    asMode: asModeRaw,
+                });
+            }
             break;
         case 'stop':
             if (wantsHelp(strippedArgs.slice(1))) {
@@ -339,6 +348,11 @@ export async function main(args) {
             await cmdNet(strippedArgs.slice(1));
             break;
         }
+        case 'integrity': {
+            const { cmdIntegrity } = await import('./integrity-command.js');
+            await cmdIntegrity(strippedArgs.slice(1));
+            break;
+        }
         case 'ctl':
             await cmdCtl(strippedArgs.slice(1));
             break;

package/dist/cli/integrity-command.js

@@ -0,0 +1,196 @@
+/**
+ * integrity-command.ts — `ec integrity` 子命令
+ *
+ * 子命令：
+ *   ec integrity check <path>    — 检查单个文件的台账状态（不修改，不恢复）
+ *   ec integrity seal <path>     — 把当前磁盘内容作为新基线登记（确认一次合法的带外修改）
+ *   ec integrity query <path>    — 打印台账记录（sha256、时间、登记方）
+ *   ec integrity list            — 列出所有已登记文件的状态摘要
+ *
+ * 所有操作都是本地 CLI，不经过 daemon IPC。
+ * 注意：ec integrity 不在 managed 白名单里，agent 会话内执行会被拒绝。
+ */
+import { createRequire } from 'module';
+import { checkFile, queryRecord, registerFile } from '../core/file-integrity/store.js';
+import { integrityDbPath, resolveRoot } from '../paths.js';
+import fs from 'fs';
+import path from 'path';
+const requireFromHere = createRequire(import.meta.url);
+const HELP = `用法: ec integrity <subcommand> [path]
+
+子命令:
+  check <path>    检查文件台账状态（不修改，不恢复文件）
+  seal <path>     把当前磁盘内容登记为新基线（确认合法的带外修改）
+  query <path>    查看台账记录（hash、时间、登记方）
+  list            列出所有已登记文件的摘要状态
+
+说明:
+  台账库位于 $EVOLCORE_HOME/data/integrity/file-integrity.db
+  "seal" 操作相当于手动确认一次合法修改，使其成为新的校验基线。
+  在开发模式下（非 node_modules 安装），系统文件不会自动校验，
+  但可以用 seal 主动建立基线，便于后续对比。
+`;
+function fmtTime(unix) {
+    if (!unix)
+        return '—';
+    return new Date(unix * 1000).toLocaleString('zh-CN', {
+        year: 'numeric', month: '2-digit', day: '2-digit',
+        hour: '2-digit', minute: '2-digit', second: '2-digit',
+        hour12: false,
+    });
+}
+function fmtHash(h) {
+    return h.slice(0, 16) + '…';
+}
+function resolveTarget(arg) {
+    return path.isAbsolute(arg) ? arg : path.resolve(process.cwd(), arg);
+}
+function cmdCheck(target) {
+    const result = checkFile(target);
+    const rel = path.relative(resolveRoot(), target) || path.basename(target);
+    switch (result.status) {
+        case 'missing':
+            console.log(`❓ 文件不存在: ${rel}`);
+            process.exitCode = 1;
+            break;
+        case 'unregistered':
+            console.log(`🆕 未登记（使用 seal 建立基线）: ${rel}`);
+            process.exitCode = 1;
+            break;
+        case 'verified':
+            console.log(`✅ 校验通过: ${rel}`);
+            console.log(`   sha256: ${fmtHash(result.actual)}`);
+            break;
+        case 'tampered':
+            console.log(`❌ 已被修改: ${rel}`);
+            console.log(`   预期: ${fmtHash(result.expected)}`);
+            console.log(`   实际: ${fmtHash(result.actual)}`);
+            console.log(`   可恢复: ${result.restorable ? '是（快照完好）' : '否（快照已损坏）'}`);
+            process.exitCode = 1;
+            break;
+    }
+}
+function cmdSeal(target) {
+    if (!fs.existsSync(target)) {
+        console.error(`❌ 文件不存在: ${target}`);
+        process.exitCode = 1;
+        return;
+    }
+    registerFile(target);
+    const rel = path.relative(resolveRoot(), target) || path.basename(target);
+    console.log(`✅ 已登记为新基线: ${rel}`);
+}
+function cmdQuery(target) {
+    const rec = queryRecord(target);
+    const rel = path.relative(resolveRoot(), target) || path.basename(target);
+    if (!rec) {
+        console.log(`🆕 台账无记录: ${rel}`);
+        return;
+    }
+    console.log(`文件: ${rel}`);
+    console.log(`  sha256:       ${rec.sha256}`);
+    console.log(`  登记时间:     ${fmtTime(rec.registered_at)}`);
+    console.log(`  最后校验:     ${fmtTime(rec.last_verified_at)}`);
+    console.log(`  登记方:       ${rec.registrar_aid ?? '（系统）'}`);
+}
+function cmdList() {
+    if (!fs.existsSync(integrityDbPath())) {
+        console.log('台账库尚未创建（还没有任何文件被登记过）');
+        return;
+    }
+    let DatabaseSync;
+    try {
+        ({ DatabaseSync } = requireFromHere('node:sqlite'));
+    }
+    catch {
+        console.error('❌ node:sqlite 不可用（需要 Node.js 22.5+）');
+        process.exitCode = 1;
+        return;
+    }
+    const db = new DatabaseSync(integrityDbPath(), { readonly: true });
+    const rows = db.prepare('SELECT file_path, sha256, registered_at, last_verified_at FROM file_integrity ORDER BY file_path').all();
+    if (rows.length === 0) {
+        console.log('台账为空');
+        return;
+    }
+    // 台账主键在 Windows 下是小写，root 也要按同样规则归一化才能前缀匹配
+    const rootSlash = resolveRoot().replace(/\\/g, '/');
+    const root = (process.platform === 'win32' ? rootSlash.toLowerCase() : rootSlash) + '/';
+    let ok = 0, tampered = 0, missing = 0;
+    console.log(`台账共 ${rows.length} 条记录（${integrityDbPath()}）\n`);
+    for (const row of rows) {
+        const rel = row.file_path.replace(/\\/g, '/').startsWith(root)
+            ? row.file_path.replace(/\\/g, '/').slice(root.length)
+            : row.file_path;
+        const chk = checkFile(row.file_path);
+        let icon;
+        switch (chk.status) {
+            case 'verified':
+                icon = '✅';
+                ok++;
+                break;
+            case 'tampered':
+                icon = '❌';
+                tampered++;
+                break;
+            case 'missing':
+                icon = '❓';
+                missing++;
+                break;
+            case 'unregistered':
+                icon = '🆕';
+                break;
+            default: icon = ' ';
+        }
+        console.log(`${icon} ${rel}`);
+        if (chk.status === 'tampered') {
+            console.log(`     预期: ${fmtHash(row.sha256)}  实际: ${fmtHash(chk.actual)}`);
+        }
+    }
+    console.log(`\n摘要：通过 ${ok}，已改 ${tampered}，不存在 ${missing}`);
+    if (tampered > 0 || missing > 0)
+        process.exitCode = 1;
+}
+export async function cmdIntegrity(args) {
+    const sub = args[0];
+    if (!sub || sub === '--help' || sub === '-h') {
+        console.log(HELP);
+        return;
+    }
+    switch (sub) {
+        case 'check': {
+            if (!args[1]) {
+                console.error('用法: ec integrity check <path>');
+                process.exitCode = 1;
+                return;
+            }
+            cmdCheck(resolveTarget(args[1]));
+            break;
+        }
+        case 'seal': {
+            if (!args[1]) {
+                console.error('用法: ec integrity seal <path>');
+                process.exitCode = 1;
+                return;
+            }
+            cmdSeal(resolveTarget(args[1]));
+            break;
+        }
+        case 'query': {
+            if (!args[1]) {
+                console.error('用法: ec integrity query <path>');
+                process.exitCode = 1;
+                return;
+            }
+            cmdQuery(resolveTarget(args[1]));
+            break;
+        }
+        case 'list':
+            cmdList();
+            break;
+        default:
+            console.error(`未知子命令: ${sub}`);
+            console.log(HELP);
+            process.exitCode = 1;
+    }
+}