evolcore 0.0.23 → 0.0.25

package/dist/cli/bench.js

@@ -381,26 +381,26 @@ async function cliAuth(aid, slotId) {
 // ==================== Main Command ====================
 export async function cmdBench(args) {
     if (isHelpFlag(args[0]) || wantsHelp(args)) {
-        console.log(`用法: ec bench [options]
-
-AUN 消息系统性能基准测试。使用多个本地 AID 并发互发消息，
-测量吞吐量、延迟、丢失率，以及认证性能和账号切换性能。
-
-Options:
-  --aids N          使用的 AID 数量 (默认 3, 范围 2-10)
-  --rounds N        每个 AID 发送的消息轮数 (默认 20)
-  --concurrency N   最大并发发送数 (默认 5)
-  --wait N          发送后等待传播的秒数 (默认 3)
-  --encrypt         发送加密消息（E2EE）
-  --file            文件传输验证模式（压缩 evolcore 目录，拆片发送，接收后 MD5 校验+解压）
-  --cli             使用 CLI 子进程调用（测试完整命令行链路，含进程启动开销）
-  --aun-path <path> 自定义 AUN 目录
-  --format json     以 JSON 输出结果
-
-示例:
-  ec bench --aids 5 --rounds 10
-  ec bench --file --rounds 50
-  ec bench --encrypt --aids 5 --rounds 20
+        console.log(`用法: ec bench [options]
+
+AUN 消息系统性能基准测试。使用多个本地 AID 并发互发消息，
+测量吞吐量、延迟、丢失率，以及认证性能和账号切换性能。
+
+Options:
+  --aids N          使用的 AID 数量 (默认 3, 范围 2-10)
+  --rounds N        每个 AID 发送的消息轮数 (默认 20)
+  --concurrency N   最大并发发送数 (默认 5)
+  --wait N          发送后等待传播的秒数 (默认 3)
+  --encrypt         发送加密消息（E2EE）
+  --file            文件传输验证模式（压缩 evolcore 目录，拆片发送，接收后 MD5 校验+解压）
+  --cli             使用 CLI 子进程调用（测试完整命令行链路，含进程启动开销）
+  --aun-path <path> 自定义 AUN 目录
+  --format json     以 JSON 输出结果
+
+示例:
+  ec bench --aids 5 --rounds 10
+  ec bench --file --rounds 50
+  ec bench --encrypt --aids 5 --rounds 20
   ec bench --cli --aids 3 --rounds 5`);
         return;
     }

package/dist/cli/config.js

@@ -196,26 +196,26 @@ async function runManagedBatchGet(fields, rest, formatJson) {
     }
     renderConfigExecution(response.result, formatJson);
 }
-const HELP = `Usage: ec config <command> [options]
-
-Fields:
-  get <field> [<field> ...]     one or more fields (batch)
-  set <field> <value>
-  unset <field>
-
-Scoped commands:
-  show | effective | fields [field] | validate | init
-
-Global commands:
-  list | snapshot | prune | history | diff | restore | current | boots
-  schema                        overview of all schemas
-  schema <name> [<version>]     view a schema definition
-  schema <name> --list          list a schema's versions
-
-Selectors:
-  --self <aid> [--peer <peerKey>] | --default | --process
-
-Output:
+const HELP = `Usage: ec config <command> [options]
+
+Fields:
+  get <field> [<field> ...]     one or more fields (batch)
+  set <field> <value>
+  unset <field>
+
+Scoped commands:
+  show | effective | fields [field] | validate | init
+
+Global commands:
+  list | snapshot | prune | history | diff | restore | current | boots
+  schema                        overview of all schemas
+  schema <name> [<version>]     view a schema definition
+  schema <name> --list          list a schema's versions
+
+Selectors:
+  --self <aid> [--peer <peerKey>] | --default | --process
+
+Output:
   --format json`;
 export async function cmdConfig(args) {
     const subcommand = args[0];

package/dist/cli/contact.js

@@ -58,15 +58,15 @@ function fail(message, code = 'INVALID_ARGUMENT', data) {
     throw error;
 }
 function printHelp() {
-    console.log(`Usage:
-  ec contact add <primaryId> --self <agent-aid>
-  ec contact block <primaryId> --self <agent-aid>
-  ec contact unblock <primaryId> --self <agent-aid>
-  ec contact list --blocked --self <agent-aid>
-
-Options:
-  --self <agent-aid>  必填，本端 agent AID
-  --blocked           list 必填，仅列出已拉黑联系人
-  --format json       输出 JSON
+    console.log(`Usage:
+  ec contact add <primaryId> --self <agent-aid>
+  ec contact block <primaryId> --self <agent-aid>
+  ec contact unblock <primaryId> --self <agent-aid>
+  ec contact list --blocked --self <agent-aid>
+
+Options:
+  --self <agent-aid>  必填，本端 agent AID
+  --blocked           list 必填，仅列出已拉黑联系人
+  --format json       输出 JSON
   --help, -h          显示帮助`);
 }

package/dist/cli/ctl-command.js

@@ -3,26 +3,28 @@ import { ipcQuery } from '../ipc.js';
 import { isHelpFlag, wantsHelp } from './help.js';
 import { AGENT_DELEGATION_TOKEN_ENV } from '../core/auth/agent-delegation.js';
 // ==================== Ctl ====================
-const CTL_HELP = `用法: ec ctl <command> [args...]
-
-查询:
-  status                    查看会话状态
-  pwd                       显示当前项目路径
-  help                      显示帮助
-
-会话:
-  name <名称>               重命名当前会话
-
-消息:
-  send <消息内容>           主动发送文本消息（proactive 模式）
-  file [channel] <path>     发送项目内文件
-  queue [--after <time>] [--before <time>]  查看/管理会话消息队列
-
-示例:
-  ec ctl status
-  ec ctl name "新会话名称"
-  ec ctl send "任务已完成"
-  ec ctl file report.md
+const CTL_HELP = `用法: ec ctl <command> [args...]
+
+查询:
+  status                    查看会话状态
+  status --format json      查看当前任务的结构化运行上下文
+  pwd                       显示当前项目路径
+  help                      显示帮助
+
+会话:
+  name <名称>               重命名当前会话
+
+消息:
+  send <消息内容>           主动发送文本消息（proactive 模式）
+  file [channel] <path>     发送项目内文件
+  queue [--after <time>] [--before <time>]  查看/管理会话消息队列
+
+示例:
+  ec ctl status
+  ec ctl status --format json
+  ec ctl name "新会话名称"
+  ec ctl send "任务已完成"
+  ec ctl file report.md
   ec ctl queue --full`;
 export async function cmdCtl(args) {
     if (args.length === 0) {

package/dist/cli/daemon-commands.js

@@ -30,8 +30,50 @@ import { inspectDataMigrationRequirement } from '../core/data-migration.js';
 import { isInitCancelledError, printInitCancelHint } from './init-cancel.js';
 import { listCodexAppServerProcesses, unregisterCodexAppServerProcess } from '../agents/codex/app-server-registry.js';
 import { DEFAULT_ECWEB_PORT, ecwebService, setEcwebEnabled } from '../config/daemon-services.js';
-import { checkCodexProjectPath, inspectCodexManagedHook } from '../agents/codex/diagnostics.js';
+import { checkCodexProjectPath, inspectCodexManagedHook, ensureCodexManagedHook, runCodexHookLaunchDiagnostic, } from '../agents/codex/diagnostics.js';
 const execFileAsync = promisify(execFile);
+/** Run before launch, and before restart stops any existing daemon. */
+export function ensureCodexHookBeforeLifecycle(onRepaired) {
+    if (!platform.isWindows)
+        return true;
+    try {
+        const usesCodex = loadDefaults()?.active_baseagent === 'codex'
+            || loadAllAgents().agents.some(agent => {
+                try {
+                    return resolveEffective({ self: agent.aid }).active_baseagent === 'codex';
+                }
+                catch (error) {
+                    console.warn(`⚠ Agent ${agent.aid} 配置解析失败：${error instanceof Error ? error.message : String(error)}`);
+                    return false;
+                }
+            });
+        if (!usesCodex)
+            return true;
+        const result = ensureCodexManagedHook({
+            packageRoot: getPackageRoot(),
+            onInstallRequired: () => console.log('🔧 Codex 运行组件缺失，正在自动安装；Windows 提示管理员授权时请选择“是”。'),
+        });
+        if (result.status === 'installed') {
+            if (result.repaired) {
+                console.log('✅ Codex Windows managed hook 已自动安装并验证');
+                onRepaired?.();
+            }
+            return true;
+        }
+        console.error(`❌ Codex Windows managed hook 未就绪：${result.error || result.reason || result.status}`);
+        if (result.status === 'missing') {
+            console.error('  本次操作已停止。下次启动或重启会再次自动尝试安装，需要允许 Windows 管理员授权。');
+        }
+        else {
+            console.error('  本次操作已停止。现有 Codex 策略或文件访问异常，需要管理员核对；自动安装不会覆盖异常策略。');
+        }
+    }
+    catch (error) {
+        console.error(`❌ Codex 启动检查失败：${error instanceof Error ? error.message : String(error)}`);
+    }
+    process.exitCode = 1;
+    return false;
+}
 async function runAutomaticInit(action) {
     try {
         return await action();
@@ -66,8 +108,8 @@ function printNoSelfAgentHints(options) {
 // taskkill, even though the daemon is healthy and able to shut down gracefully.
 const DAEMON_PROBE_TIMEOUT_MS = platform.isWindows ? 5_000 : 1_000;
 export const DAEMON_SHUTDOWN_TIMEOUT_MS = platform.isWindows ? 10_000 : 3_000;
-async function probeDaemon(socketPath, timeoutMs = DAEMON_PROBE_TIMEOUT_MS) {
-    const response = await ipcQuery(socketPath, { type: 'ping' }, timeoutMs);
+async function probeDaemon(socketPath, timeoutMs = DAEMON_PROBE_TIMEOUT_MS, throwOnError = false) {
+    const response = await ipcQuery(socketPath, { type: 'ping' }, timeoutMs, { throwOnError });
     if (response?.pong !== true || !Number.isInteger(response.pid) || response.pid <= 0)
         return null;
     return response;
@@ -205,19 +247,39 @@ function runSourceBuild() {
         });
     });
 }
+/**
+ * Spawn the restart monitor and confirm it actually reached its own code.
+ *
+ * The daemon is already stopped at this point, so a monitor that dies on
+ * startup leaves nothing running and nobody watching — the exact silent
+ * failure this mechanism exists to prevent.
+ */
+async function spawnRestartMonitorAndConfirm(monitorEntry, reportLine) {
+    const result = await platform.launchMonitorAndConfirm([...monitorEntry.args, 'restart-monitor'], { EVOLCORE_HOME: resolvePaths().root, ...(monitorEntry.env ?? {}) }, pid => scanInstances().restartMonitors.some(m => m.alive && m.record.pid === pid), pid => scanInstances().restartMonitors.some(m => m.alive && m.record.pid !== pid));
+    if (result.ok)
+        return { ok: true };
+    for (const line of (result.stderrTail ?? '').split(/\r?\n/).filter(Boolean).slice(-8)) {
+        reportLine(`  | ${line}`);
+    }
+    return { ok: false, reason: result.reason ?? 'unknown' };
+}
 async function requireFreshSourceBuild() {
     if (!sourceBuildNeedsRefresh())
         return true;
     return await runSourceBuild();
 }
-function requireCompletedDataMigration(root) {
+function requireCompletedDataMigration(root, action = 'start') {
     const requirement = inspectDataMigrationRequirement(root);
     if (!requirement.required)
         return true;
-    console.error(`❌ 检测到 ${requirement.operationCount} 项待确认的用户数据迁移，服务未启动。`);
+    console.error(action === 'restart'
+        ? `❌ 检测到 ${requirement.operationCount} 项待确认的用户数据迁移，本次不停止当前服务。`
+        : `❌ 检测到 ${requirement.operationCount} 项待确认的用户数据迁移，服务未启动。`);
     console.error('  先执行: ec data migrate --dry-run');
     console.error('  确认后: ec data migrate --apply');
     console.error('  迁移成功并校验后，再执行 ec start 或 ec restart。');
+    if (action === 'restart')
+        console.error('  本次 ec restart 仅完成只读检查，未停止当前服务。');
     process.exitCode = 2;
     return false;
 }
@@ -386,6 +448,14 @@ export async function cmdStart(opts = {}) {
     const p = resolvePaths();
     const existingDaemon = await probeDaemon(p.socket);
     if (existingDaemon) {
+        let hookRepaired = false;
+        if (!ensureCodexHookBeforeLifecycle(() => { hookRepaired = true; }))
+            return;
+        if (hookRepaired) {
+            console.log('🔄 Codex 运行组件已补齐，正在自动重启服务以加载策略...');
+            await cmdRestart({ diagnose: opts.diagnose });
+            return;
+        }
         console.log(`  EvolCore is already running (PID: ${existingDaemon.pid}, IPC reachable)`);
         console.log(`  已在运行；已运行时长: ${resolveRunningDuration(existingDaemon.pid, existingDaemon.uptime)}；部署/脚本可直接复用当前实例`);
         return;
@@ -424,6 +494,11 @@ export async function cmdStart(opts = {}) {
             console.log('\n初始化完成，开始启动 EvolCore ....');
         }
     }
+    // The initialization path can create the first Codex agent, so perform the
+    // machine-hook check after config migration/auto-init and before any daemon
+    // process is launched.
+    if (!ensureCodexHookBeforeLifecycle())
+        return;
     // 控制 AID 门禁：缺 aid 且交互式 → 只补全控制 AID + owners（不重走 baseagent 向导）。
     // 非 TTY（restart-monitor/systemd/管道）不补全（无法交互），只提示后继续启动，daemon 侧 warn 兜底。
     const daemonCfgStart = loadDaemonConfig();
@@ -758,6 +833,8 @@ export async function cmdStop() {
 export async function cmdRestart(opts = {}) {
     const cmdStartedAt = Date.now();
     console.log('🔄 Restarting EvolCore...');
+    if (!ensureCodexHookBeforeLifecycle())
+        return;
     const initialStatus = scanInstances();
     const initialOrphans = findOrphanProcesses();
     const initialRuntimeOrphans = initialOrphans.filter(orphan => isRuntimeOrphan(orphan));
@@ -769,12 +846,12 @@ export async function cmdRestart(opts = {}) {
         if (initialRuntimeOrphans.length === 0 && rejectPidIsolatedLifecycle('restart', initialStatus, ping))
             return;
     }
-    if (!await requireFreshSourceBuild())
-        return;
+    // 构建交给 restart-monitor：它在 daemon 停止之后才编译，dist/ 不会被活进程
+    // 占用，失败还能回滚到上一份产物。这里再编译一次会落在事务保护之外。
     // Keep restart behavior identical to startup: both paths use one upgrade
     // check implementation and continue when an upgrade is unavailable.
     await runUpgradeChecks();
-    if (!requireCompletedDataMigration(resolveRoot()))
+    if (!requireCompletedDataMigration(resolveRoot(), 'restart'))
         return;
     // 停止所有活 main 进程（可能不止一个）
     const status = scanInstances();
@@ -854,11 +931,30 @@ export async function cmdRestart(opts = {}) {
         }
     }
     console.log(`⏱ restart prep done in ${((Date.now() - cmdStartedAt) / 1000).toFixed(1)}s, starting...`);
-    // 通过 restart-monitor 启动，避免在 agent 内调用时自杀
-    const appCli = path.join(getPackageRoot(), 'dist', 'cli', 'index.js');
-    platform.spawnDetachedNode([appCli, 'restart-monitor'], {
-        EVOLCORE_HOME: resolvePaths().root,
-    });
+    // 通过 restart-monitor 启动，避免在 agent 内调用时自杀。
+    // 开发仓下 monitor 从源码跑；安装包下先复制到 stage 目录，两种情况都让看门狗
+    // 不住在会被替换的产物里。
+    const monitorEntry = platform.resolveMonitorLaunch(getPackageRoot(), path.join(resolvePaths().root, 'data', 'monitor-stage'));
+    if (monitorEntry.note)
+        console.log(`ℹ ${monitorEntry.note}`);
+    if (!fs.existsSync(monitorEntry.entry)) {
+        console.error(`❌ 重启中止：找不到 restart-monitor 入口 ${monitorEntry.entry}`);
+        console.error('  请先执行 npm run build 重建产物');
+        process.exitCode = 1;
+        return;
+    }
+    const monitorStarted = await spawnRestartMonitorAndConfirm(monitorEntry, log => console.error(log));
+    if (!monitorStarted.ok) {
+        if (monitorEntry.stageDir)
+            platform.cleanupMonitorStage(monitorEntry.stageDir);
+        console.error(`❌ 重启中止：restart-monitor 未能启动（${monitorStarted.reason}）`);
+        if (fs.existsSync(path.join(getPackageRoot(), 'src', 'cli', 'index.ts'))) {
+            console.error('  源码可能存在语法错误导致 tsx 无法加载。请执行 npx tsc --noEmit 检查。');
+        }
+        console.error('  服务已停止，请修复后执行 ec start。');
+        process.exitCode = 1;
+        return;
+    }
     console.log('🔄 Restart monitor started, waiting for service to come back online...');
     await sleep(2000);
     // 代码统计（开发环境）
@@ -1032,7 +1128,11 @@ export async function cmdStatus() {
     // Start all read-only daemon queries together. On a busy Windows host each
     // query can otherwise wait behind the same IPC/event-loop delay and make the
     // total `ec status` time the sum of several individual timeouts.
-    const pingPromise = probeDaemon(p.socket).catch(() => null);
+    let ipcFailure;
+    const pingPromise = probeDaemon(p.socket, DAEMON_PROBE_TIMEOUT_MS, true).catch(error => {
+        ipcFailure = error;
+        return null;
+    });
     const statusPromise = ipcQuery(p.socket, { type: 'status' }).catch(() => null);
     const aidsPromise = ipcQuery(p.socket, { type: 'aun-aids' }).catch(() => null);
     const agentsPromise = ipcQuery(p.socket, { type: 'evolagent.list' }).catch(() => null);
@@ -1049,6 +1149,11 @@ export async function cmdStatus() {
     }
     if (pid) {
         printStartupInfo({ pid, running: true });
+        if (!ping) {
+            console.log('⚠ 仅确认 daemon PID 存活，IPC 不可用，不能据此判断服务健康。');
+            if (ipcFailure)
+                console.log(`  ${ipcFailure instanceof Error ? ipcFailure.message : String(ipcFailure)}`);
+        }
         console.log('');
         console.log('📊 Process Info:');
         if (processVisible) {
@@ -1159,7 +1264,9 @@ export async function cmdStatus() {
         }
     }
     else {
-        console.log('⚠ EvolCore is not running');
+        console.log(ipcFailure ? '⚠ 无法确认 EvolCore 运行状态：IPC 不可用，且没有可见的存活 PID。' : '⚠ EvolCore is not running');
+        if (ipcFailure)
+            console.log(`  ${ipcFailure instanceof Error ? ipcFailure.message : String(ipcFailure)}`);
     }
     // Session & Project statistics (从文件系统读)
     if (fs.existsSync(p.sessionsDir)) {
@@ -2905,7 +3012,12 @@ async function cmdWatchWeb() {
     const cfg = loadDaemonConfig();
     const currentService = ecwebService(cfg.services);
     const port = currentService?.port ?? DEFAULT_ECWEB_PORT;
-    saveDaemonConfig({ ...cfg, services: setEcwebEnabled(cfg.services, true, port) });
+    // Avoid rewriting daemon.json on every invocation once ECWeb is already
+    // enabled on the requested port. The persisted config is the daemon's
+    // lifecycle source of truth, but an unchanged desired state needs no write.
+    if (currentService?.enabled !== true || currentService.port !== port) {
+        saveDaemonConfig({ ...cfg, services: setEcwebEnabled(cfg.services, true, port) });
+    }
     const ok = await startEcwebIfEnabled(p, { forceRestart: true });
     if (!ok)
         process.exit(1); // 失败原因已由 startEcwebIfEnabled 打印
@@ -2944,9 +3056,10 @@ export async function cmdMv(oldDir, newDir) {
     }
 }
 // ==================== Diagnose ====================
-export async function cmdDiagnose() {
+export async function cmdDiagnose(args = []) {
     const p = resolvePaths();
     let hasError = false;
+    const runHookLaunchProbe = args.includes('--codex-hook');
     // 1. 检查数据目录
     console.log(`[diagnose] EVOLCORE_HOME = ${p.root}`);
     if (!fs.existsSync(p.root)) {
@@ -3010,6 +3123,24 @@ export async function cmdDiagnose() {
             const hook = inspectCodexManagedHook({ packageRoot: getPackageRoot() });
             if (hook.status === 'installed') {
                 console.log(`[diagnose] ✓ Codex managed hook 已安装: ${hook.hookPath}`);
+                if (runHookLaunchProbe) {
+                    try {
+                        const launch = runCodexHookLaunchDiagnostic({ packageRoot: getPackageRoot() });
+                        if (launch.status === 'ok') {
+                            console.log('[diagnose] ✓ Codex managed hook 启动探针报告: ' + launch.output);
+                            for (const result of launch.results) {
+                                console.log('[diagnose]   ' + result.label + ': exit=' + result.exitCode + ' pid=' + (result.pid ?? 'unknown'));
+                            }
+                        }
+                        else {
+                            console.log('[diagnose] - Codex managed hook 启动探针: 跳过（' + (launch.reason || 'not applicable') + '）');
+                        }
+                    }
+                    catch (error) {
+                        console.error('[diagnose] ❌ Codex managed hook 启动探针失败: ' + (error instanceof Error ? error.message : String(error)));
+                        hasError = true;
+                    }
+                }
             }
             else if (hook.status === 'skipped') {
                 console.log(`[diagnose] - Codex managed hook: 跳过（${hook.reason}）`);
@@ -3129,21 +3260,21 @@ export async function cmdWatchCommand(args) {
     }
     else if (args[0] === 'msg') {
         if (isHelpFlag(args[1])) {
-            console.log(`用法: ec watch msg
-
-三面板交互式消息监控 TUI。
-
-面板:
-  左 (Scope)     本地 AID 列表，显示收发统计和对端数量
-  中 (Stats)     选中 AID 的对端列表（默认 All），显示 per-peer 收发数
-  右 (Messages)  消息流，带滚动条
-
-操作:
-  ↑↓             当前面板内导航
-  ←→ / Tab       切换面板
-  Enter          选中 AID / 选中对端
-  Backspace      返回上一级
-  Page Up/Down   消息滚动
+            console.log(`用法: ec watch msg
+
+三面板交互式消息监控 TUI。
+
+面板:
+  左 (Scope)     本地 AID 列表，显示收发统计和对端数量
+  中 (Stats)     选中 AID 的对端列表（默认 All），显示 per-peer 收发数
+  右 (Messages)  消息流，带滚动条
+
+操作:
+  ↑↓             当前面板内导航
+  ←→ / Tab       切换面板
+  Enter          选中 AID / 选中对端
+  Backspace      返回上一级
+  Page Up/Down   消息滚动
   ESC            退出`);
             return;
         }

package/dist/cli/fs-command.js

@@ -19,73 +19,73 @@ class FsCliError extends Error {
         this.details = details;
     }
 }
-const HELP = `用法: ec fs <command> [args...] [options]
-
-Commands:
-  ls <AID>:<path>                 列目录
-  stat [-L] <AID>:<path>          查看节点元数据（默认不跟随软链；-L 跟随）
-  lstat <AID>:<path>              查看节点本身（不跟随末级软链）
-  cat <AID>:<path>                输出文本文件内容；二进制/大文件返回头部摘要
-  cp <local> <AID>:<path>         上传本地文件
-  cp <AID>:<path> <local>         下载远程文件
-  cp <AID>:<path> <AID>:<path>    远程复制（同后端）
-  mv <AID>:<path> <AID>:<path>    移动/改名（同后端）
-  rm [-r] <AID>:<path>            删除文件或目录
-  mkdir [-p] <AID>:<path>         创建目录
-  ln -s <target> <AID>:<path>     创建软链（personal storage）
-  chmod [mode] <AID>:<path>       切换公开/私有（personal storage）
-  setfacl <AID>:<path> -m|-x ...   设置/移除 ACL（群路径使用 role:member|role:admin）
-  getfacl <AID>:<path>            查看 ACL
-  token issue|revoke|ls <path>    管理访问 token（personal storage）
-  find <AID>:<path> [filters]     查找节点
-  df <AID>:                       查看容量/配额
-  mount <target> --volume <id>    挂载实体卷
-  mount <target> --source <src>   挂载远程子树
-  approve <AID>:<path>            批准待审挂载（personal storage）
-  reject <AID>:<path>             拒绝待审挂载（personal storage）
-  umount <AID>:<path>             卸载挂载点
-
-Options:
-  --as <aid>                      操作者 AID；也可由 EVOLCORE_SELF_AID 注入
-  --format json                   输出 JSON
-  --overwrite, --force            覆盖目标（用于 cp/mv/ln）或强制删除（用于 rm）
-  -r, --recursive                 递归（用于 rm/cp）
-  -p, --parents                   自动创建父目录（用于 mkdir/group 上传）
-  -L, --follow                    stat 跟随末级软链
-  --token <token>                 读取时携带访问 token（personal storage）
-  --content-type <mime>           上传时指定内容类型
-  --public                        上传后公开可读（personal storage）
-  --visibility <public|private>   chmod 可见性
-  --allow-roles <roles>           chmod 角色约束，逗号分隔
-  -m aid:<aid>:<perms>            setfacl 新增/更新 ACL
-  -x aid:<aid>                    setfacl 移除 ACL
-  --source <AID>:<path>           mount 虚拟卷来源
-  --volume <id>                   mount 实体卷 ID
-  --require-approval              mount 需要来源 owner 审批
-  --expires <time>                mount/token/ACL 过期时间，Unix 秒或 ISO 日期
-  --max-uses <n>                  ACL 最大使用次数
-  --max-reads <n>                 token 最大读取次数
-  --readonly, --readwrite         mount 只读/读写
-  --name <glob>                   find 名称过滤
-  --type <f|d|l>                  find 类型过滤
-  --size <expr>                   find 大小过滤，如 +1M
-  --mtime <expr>                  find 修改时间过滤
-  --head-bytes <n>                cat 二进制头部字节数，默认 256
-  --max-bytes <n>                 cat 最大直接输出字节数，默认 1048576
-  --aun-path <path>               指定 AUN keystore 根
-  --app <name>                    指定 AUN app slot
-
-示例:
-  ec fs ls alice.agentid.pub:/private/
-  ec fs cp ./report.md alice.agentid.pub:/private/report.md --as alice.agentid.pub
-  ec fs cp alice.agentid.pub:/private/report.md ./report.md --as alice.agentid.pub
-  ec fs cp alice.agentid.pub:/private/a.md bob.agentid.pub:/inbox/a.md --as alice.agentid.pub
-  ec fs cat alice.agentid.pub:/private/report.md --as alice.agentid.pub
-  ec fs ln -s alice.agentid.pub:/private/report.md alice.agentid.pub:/public/report.md --as alice.agentid.pub
-  ec fs chmod +r alice.agentid.pub:/public/report.md --as alice.agentid.pub
-  ec fs setfacl alice.agentid.pub:/private/report.md -m aid:bob.agentid.pub:r --as alice.agentid.pub
-  ec fs token issue alice.agentid.pub:/public/report.md --expires 2026-12-31 --as alice.agentid.pub
-  ec fs find alice.agentid.pub:/private/ --name "*.md" --as alice.agentid.pub
+const HELP = `用法: ec fs <command> [args...] [options]
+
+Commands:
+  ls <AID>:<path>                 列目录
+  stat [-L] <AID>:<path>          查看节点元数据（默认不跟随软链；-L 跟随）
+  lstat <AID>:<path>              查看节点本身（不跟随末级软链）
+  cat <AID>:<path>                输出文本文件内容；二进制/大文件返回头部摘要
+  cp <local> <AID>:<path>         上传本地文件
+  cp <AID>:<path> <local>         下载远程文件
+  cp <AID>:<path> <AID>:<path>    远程复制（同后端）
+  mv <AID>:<path> <AID>:<path>    移动/改名（同后端）
+  rm [-r] <AID>:<path>            删除文件或目录
+  mkdir [-p] <AID>:<path>         创建目录
+  ln -s <target> <AID>:<path>     创建软链（personal storage）
+  chmod [mode] <AID>:<path>       切换公开/私有（personal storage）
+  setfacl <AID>:<path> -m|-x ...   设置/移除 ACL（群路径使用 role:member|role:admin）
+  getfacl <AID>:<path>            查看 ACL
+  token issue|revoke|ls <path>    管理访问 token（personal storage）
+  find <AID>:<path> [filters]     查找节点
+  df <AID>:                       查看容量/配额
+  mount <target> --volume <id>    挂载实体卷
+  mount <target> --source <src>   挂载远程子树
+  approve <AID>:<path>            批准待审挂载（personal storage）
+  reject <AID>:<path>             拒绝待审挂载（personal storage）
+  umount <AID>:<path>             卸载挂载点
+
+Options:
+  --as <aid>                      操作者 AID；也可由 EVOLCORE_SELF_AID 注入
+  --format json                   输出 JSON
+  --overwrite, --force            覆盖目标（用于 cp/mv/ln）或强制删除（用于 rm）
+  -r, --recursive                 递归（用于 rm/cp）
+  -p, --parents                   自动创建父目录（用于 mkdir/group 上传）
+  -L, --follow                    stat 跟随末级软链
+  --token <token>                 读取时携带访问 token（personal storage）
+  --content-type <mime>           上传时指定内容类型
+  --public                        上传后公开可读（personal storage）
+  --visibility <public|private>   chmod 可见性
+  --allow-roles <roles>           chmod 角色约束，逗号分隔
+  -m aid:<aid>:<perms>            setfacl 新增/更新 ACL
+  -x aid:<aid>                    setfacl 移除 ACL
+  --source <AID>:<path>           mount 虚拟卷来源
+  --volume <id>                   mount 实体卷 ID
+  --require-approval              mount 需要来源 owner 审批
+  --expires <time>                mount/token/ACL 过期时间，Unix 秒或 ISO 日期
+  --max-uses <n>                  ACL 最大使用次数
+  --max-reads <n>                 token 最大读取次数
+  --readonly, --readwrite         mount 只读/读写
+  --name <glob>                   find 名称过滤
+  --type <f|d|l>                  find 类型过滤
+  --size <expr>                   find 大小过滤，如 +1M
+  --mtime <expr>                  find 修改时间过滤
+  --head-bytes <n>                cat 二进制头部字节数，默认 256
+  --max-bytes <n>                 cat 最大直接输出字节数，默认 1048576
+  --aun-path <path>               指定 AUN keystore 根
+  --app <name>                    指定 AUN app slot
+
+示例:
+  ec fs ls alice.agentid.pub:/private/
+  ec fs cp ./report.md alice.agentid.pub:/private/report.md --as alice.agentid.pub
+  ec fs cp alice.agentid.pub:/private/report.md ./report.md --as alice.agentid.pub
+  ec fs cp alice.agentid.pub:/private/a.md bob.agentid.pub:/inbox/a.md --as alice.agentid.pub
+  ec fs cat alice.agentid.pub:/private/report.md --as alice.agentid.pub
+  ec fs ln -s alice.agentid.pub:/private/report.md alice.agentid.pub:/public/report.md --as alice.agentid.pub
+  ec fs chmod +r alice.agentid.pub:/public/report.md --as alice.agentid.pub
+  ec fs setfacl alice.agentid.pub:/private/report.md -m aid:bob.agentid.pub:r --as alice.agentid.pub
+  ec fs token issue alice.agentid.pub:/public/report.md --expires 2026-12-31 --as alice.agentid.pub
+  ec fs find alice.agentid.pub:/private/ --name "*.md" --as alice.agentid.pub
   ec fs df alice.agentid.pub: --as alice.agentid.pub`;
 const VALUE_FLAGS = new Set([
     '--as',

package/dist/cli/handoff-command.js

@@ -153,13 +153,13 @@ function formatTimestamp(value) {
 export async function cmdHandoff(args) {
     const sub = args[0];
     if (!sub || isHelpFlag(sub) || wantsHelp(args)) {
-        console.log(`用法: ec handoff <command> [args]
-
-Commands:
-  return [handoff-id] [content]       确认完成；required 策略需提供回流内容
-  return [handoff-id] --text-from-file <path>
-  status <handoff-id>                查询 handoff 状态
-  list [--state <state>] [--session <id>] [--limit <n>] [--agent <aid>]
+        console.log(`用法: ec handoff <command> [args]
+
+Commands:
+  return [handoff-id] [content]       确认完成；required 策略需提供回流内容
+  return [handoff-id] --text-from-file <path>
+  status <handoff-id>                查询 handoff 状态
+  list [--state <state>] [--session <id>] [--limit <n>] [--agent <aid>]
   trace <handoff-id> [--limit <n>] [--agent <aid>]`);
         return;
     }