evolclaw 3.1.3 → 3.1.5

package/dist/cli/index.js

@@ -11,6 +11,7 @@ import { migrateProject } from '../config-store.js';
 import { cmdInit } from './init.js';
 import { ipcQuery } from '../ipc.js';
 import { cmdInitWechat, cmdInitFeishu, cmdInitDingtalk, cmdInitQQBot, cmdInitWecom } from './init-channel.js';
+import { isHelpFlag, wantsHelp } from './help.js';
 import * as platform from '../utils/cross-platform.js';
 import { EventBus } from '../core/event-bus.js';
 import { tryUpgrade, tryUpgradeAunSdk } from '../utils/npm-ops.js';
@@ -883,8 +884,8 @@ async function cmdStatus() {
                     const configChannelNames = new Set();
                     for (const cfg of agents) {
                         for (const inst of cfg.channels) {
-                            // effective key: <type>#<urlEncode(selfPeerId)>#<name>
-                            configChannelNames.add(`${inst.type}#${encodeURIComponent(cfg.aid)}#${inst.name}`);
+                            // effective key: <type>#<selfAID>#<name>
+                            configChannelNames.add(`${inst.type}#${cfg.aid}#${inst.name}`);
                         }
                     }
                     for (const s of allSessions) {
@@ -1013,7 +1014,7 @@ async function cmdStatus() {
     }
 }
 /**
- * 把 channel fingerprint 列表（`<type>#<selfPeerId>#<name>`）折叠成展示用摘要。
+ * 把 channel fingerprint 列表（`<type>#<selfAID>#<name>`）折叠成展示用摘要。
  *
  * 聚合规则：
  *   - 按 type 分组
@@ -1413,6 +1414,7 @@ async function cmdWatchMenu() {
         { key: 'log', label: 'log', desc: 'real-time log tail' },
         { key: 'aid', label: 'aid', desc: 'AID connection stats' },
         { key: 'msg', label: 'msg', desc: 'message inspector' },
+        { key: 'web', label: 'web', desc: 'browser dashboard (aid/msg/session)' },
     ];
     let index = 0;
     const useColor = !!process.stdout.isTTY;
@@ -1476,6 +1478,9 @@ async function cmdWatchMenu() {
                     const { cmdWatchMsg } = await import('./watch-msg.js');
                     await cmdWatchMsg();
                 }
+                else if (chosen === 'web') {
+                    await cmdWatchWeb();
+                }
                 resolve();
             }
         };
@@ -2097,6 +2102,97 @@ async function cmdWatchAid() {
     }
     platform.onShutdown(cleanup);
 }
+async function cmdWatchWeb() {
+    const p = resolvePaths();
+    fs.mkdirSync(p.instanceDir, { recursive: true });
+    const useColor = !!process.stdout.isTTY;
+    const RST = useColor ? '\x1b[0m' : '';
+    const DIM = useColor ? '\x1b[2m' : '';
+    const BOLD = useColor ? '\x1b[1m' : '';
+    const CYAN = useColor ? '\x1b[36m' : '';
+    const GREEN = useColor ? '\x1b[32m' : '';
+    const YELLOW = useColor ? '\x1b[33m' : '';
+    const logLine = (line) => {
+        const t = new Date();
+        const ts = `${String(t.getHours()).padStart(2, '0')}:${String(t.getMinutes()).padStart(2, '0')}:${String(t.getSeconds()).padStart(2, '0')}`;
+        process.stdout.write(`${DIM}${ts}${RST} ${line}\n`);
+    };
+    // 调试日志文件：每次运行 watch web 时清空，便于建立调试闭环
+    // 查看 sessions 调试日志 → 读这个文件
+    const logFile = path.join(p.logs, 'watch-web.log');
+    try {
+        fs.mkdirSync(p.logs, { recursive: true });
+        fs.writeFileSync(logFile, `# watch-web debug log\n# started ${new Date().toISOString()} pid=${process.pid}\n`);
+    }
+    catch { /* best effort */ }
+    const fileLog = (line) => {
+        const t = new Date();
+        const ts = `${String(t.getHours()).padStart(2, '0')}:${String(t.getMinutes()).padStart(2, '0')}:${String(t.getSeconds()).padStart(2, '0')}.${String(t.getMilliseconds()).padStart(3, '0')}`;
+        try {
+            fs.appendFileSync(logFile, `${ts} ${line.replace(/\x1b\[[0-9;]*m/g, '')}\n`);
+        }
+        catch { /* ignore */ }
+    };
+    // 同时输出到终端和日志文件
+    const log = (line) => { logLine(line); fileLog(line); };
+    const { startWatchWebServer } = await import('./watch-web/server.js');
+    let handle;
+    try {
+        handle = await startWatchWebServer({ log });
+    }
+    catch (e) {
+        console.error(`❌ 启动 Web 服务失败: ${e?.message || e}`);
+        process.exit(1);
+    }
+    // 注册 instance 文件
+    const instanceFile = path.join(p.instanceDir, `watch-web-${process.pid}.json`);
+    fs.writeFileSync(instanceFile, JSON.stringify({
+        pid: process.pid, startedAt: Date.now(), startedAtIso: new Date().toISOString(),
+        type: 'watch-web', port: handle.port,
+    }, null, 2));
+    // 列出本机访问地址
+    const os = await import('os');
+    const ifaces = os.networkInterfaces();
+    const lanIps = [];
+    for (const list of Object.values(ifaces)) {
+        for (const ni of list || []) {
+            if (ni.family === 'IPv4' && !ni.internal)
+                lanIps.push(ni.address);
+        }
+    }
+    process.stdout.write(`\n${BOLD}${CYAN}🔭 EvolClaw Watch Web${RST}\n\n`);
+    process.stdout.write(`  ${BOLD}配对码:${RST}  ${GREEN}${BOLD}${handle.pairingCode}${RST}  ${DIM}(5 分钟内有效，配对后 token 缓存 24h 自动续期)${RST}\n\n`);
+    process.stdout.write(`  ${BOLD}本机:${RST}    http://localhost:${handle.port}\n`);
+    for (const ip of lanIps) {
+        process.stdout.write(`  ${BOLD}局域网:${RST}  http://${ip}:${handle.port}\n`);
+    }
+    process.stdout.write(`\n  ${DIM}绑定 0.0.0.0，远程可访问。按任意键退出。${RST}\n`);
+    process.stdout.write(`  ${DIM}调试日志: ${logFile}${RST}\n\n`);
+    const cleanup = () => {
+        try {
+            fs.unlinkSync(instanceFile);
+        }
+        catch { }
+        handle.close().finally(() => process.exit(0));
+    };
+    process.on('exit', () => { try {
+        fs.unlinkSync(instanceFile);
+    }
+    catch { } });
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+    platform.onShutdown(cleanup);
+    // 按任意键退出
+    if (process.stdin.isTTY) {
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        process.stdin.on('data', (key) => {
+            logLine(`${YELLOW}收到退出指令，关闭服务…${RST}`);
+            cleanup();
+        });
+    }
+    await new Promise(() => { });
+}
 async function cmdRestartMonitor() {
     const p = resolvePaths();
     const restartLog = path.join(p.logs, 'restart.log');
@@ -2471,14 +2567,13 @@ function archiveSelfHealLog(p, log) {
  * Searches across all channel types (feishu, wechat, aun) for a matching instance.
  */
 function resolveInstanceConfig(instanceName) {
-    // 新结构：channel key 是 <type>#<selfPeerId>#<name>，解析后从对应 agent 的 channels[] 找
+    // 新结构：channel key 是 <type>#<selfAID>#<name>，解析后从对应 agent 的 channels[] 找
     const parts = instanceName.split('#');
     if (parts.length === 3) {
-        const [type, encodedSelfPeerId, name] = parts;
-        const selfPeerId = decodeURIComponent(encodedSelfPeerId);
+        const [type, selfAID, name] = parts;
         const { agents } = loadAllAgents();
-        // AUN channel 的 selfPeerId 就是 agent.aid
-        const agent = agents.find(a => a.aid === selfPeerId);
+        // AUN channel 的 selfAID 就是 agent.aid
+        const agent = agents.find(a => a.aid === selfAID);
         if (!agent)
             return null;
         const inst = agent.channels.find((c) => c.type === type && c.name === name);
@@ -2765,7 +2860,7 @@ Agent:
         process.exit(1);
     }
     // help 不需要连接服务，直接复用无参数时的帮助输出
-    if (args[0] === 'help') {
+    if (isHelpFlag(args[0])) {
         return cmdCtl([]);
     }
     const sessionId = process.env.EVOLCLAW_SESSION_ID;
@@ -2800,7 +2895,7 @@ Agent:
 async function cmdAgent(args) {
     const sub = args[0];
     const formatJson = args.includes('--format') && args[args.indexOf('--format') + 1] === 'json';
-    if (!sub || sub === 'help' || sub === '--help' || sub === '-h' || args.includes('--help') || args.includes('-h')) {
+    if (!sub || isHelpFlag(sub)) {
         console.log(`用法: evolclaw agent <command>
 
 Commands:
@@ -2818,6 +2913,7 @@ Commands:
 
 Options:
   --format json           输出 JSON 格式
+  --help, -h              各子命令均支持，查看详细用法
 
 示例:
   evolclaw agent list
@@ -2832,7 +2928,13 @@ Options:
     }
     const { agentList, agentShow, agentCreateInteractive, agentCreateNonInteractive, agentReload, agentEnable, agentDisable, agentGet, agentSet, agentDelete, agentRename, } = await import('./agent.js');
     // --- list ---
-    if (!sub || sub === 'list') {
+    if (sub === 'list') {
+        if (wantsHelp(args)) {
+            console.log(`用法: evolclaw agent list [--format json]
+
+列出所有 agent，显示名称、状态、渠道、项目、基座、最后活跃时间。`);
+            return;
+        }
         const result = await agentList();
         if (!result.ok) {
             if (formatJson) {
@@ -2893,6 +2995,24 @@ Options:
     }
     // --- new ---
     if (sub === 'new') {
+        if (wantsHelp(args)) {
+            console.log(`用法: evolclaw agent new [aid]                    交互式创建
+     evolclaw agent new <aid> --non-interactive [选项]
+
+非交互模式选项:
+  --baseagent <claude|codex|gemini>   默认: PATH 中第一个可用
+  --project <absolute path>           必填
+  --owner <aid>
+  --name <display-name>
+  --description <text>
+  --force                             覆盖已有 config.json
+  --format json                       输出 JSON
+
+示例:
+  evolclaw agent new mybot.agentid.pub
+  evolclaw agent new mybot.agentid.pub --non-interactive --project /abs/path --baseagent claude`);
+            return;
+        }
         const name = args[1];
         const nonInteractive = args.includes('--non-interactive');
         if (nonInteractive) {
@@ -2989,6 +3109,14 @@ Options:
     // }
     // --- reload ---
     if (sub === 'reload') {
+        if (wantsHelp(args)) {
+            console.log(`用法: evolclaw agent reload [aid] [--format json]
+
+热重载 agent 配置。
+  无参数      全量 resync（扫磁盘，新增上线、删除下线、修改热更新）
+  <aid>       仅热重载指定 agent`);
+            return;
+        }
         const target = args[1] && !args[1].startsWith('--') ? args[1] : undefined;
         const result = await agentReload(target);
         if (!result.ok) {
@@ -3016,6 +3144,12 @@ Options:
     }
     // --- enable ---
     if (sub === 'enable') {
+        if (wantsHelp(args)) {
+            console.log(`用法: evolclaw agent enable <aid> [--format json]
+
+启用 agent。若服务运行中会热重载，否则下次 evolclaw start 时生效。`);
+            return;
+        }
         const aid = args[1];
         if (!aid) {
             console.error('用法: evolclaw agent enable <aid>');
@@ -3041,6 +3175,12 @@ Options:
     }
     // --- disable ---
     if (sub === 'disable') {
+        if (wantsHelp(args)) {
+            console.log(`用法: evolclaw agent disable <aid> [--format json]
+
+停用 agent。若服务运行中会热重载离线，否则在配置中标记为禁用。`);
+            return;
+        }
         const aid = args[1];
         if (!aid) {
             console.error('用法: evolclaw agent disable <aid>');
@@ -3066,6 +3206,16 @@ Options:
     }
     // --- get ---
     if (sub === 'get') {
+        if (wantsHelp(args)) {
+            console.log(`用法: evolclaw agent get <aid> <key> [--format json]
+
+读取单个配置字段。key 支持点路径，如 "channels.aun.enabled"。
+
+示例:
+  evolclaw agent get mybot.agentid.pub active_baseagent
+  evolclaw agent get mybot.agentid.pub channels.aun.enabled`);
+            return;
+        }
         const aid = args[1];
         const key = args[2];
         if (!aid || !key) {
@@ -3093,6 +3243,16 @@ Options:
     }
     // --- set ---
     if (sub === 'set') {
+        if (wantsHelp(args)) {
+            console.log(`用法: evolclaw agent set <aid> <key> <value> [--format json]
+
+修改单个配置字段。key 支持点路径。修改后若服务运行中会自动热重载。
+
+示例:
+  evolclaw agent set mybot.agentid.pub active_baseagent codex
+  evolclaw agent set mybot.agentid.pub channels.aun.enabled true`);
+            return;
+        }
         const aid = args[1];
         const key = args[2];
         const val = args[3];
@@ -3120,6 +3280,15 @@ Options:
     }
     // --- rename ---
     if (sub === 'rename') {
+        if (wantsHelp(args)) {
+            console.log(`用法: evolclaw agent rename <aid> <name> [--format json]
+
+修改 agent 显示名称。同时更新本地 agent.md 并尝试重新上传。
+
+示例:
+  evolclaw agent rename mybot.agentid.pub "My Bot"`);
+            return;
+        }
         const aid = args[1];
         const newName = args[2];
         if (!aid || !newName) {
@@ -3146,6 +3315,14 @@ Options:
     }
     // --- delete ---
     if (sub === 'delete') {
+        if (wantsHelp(args)) {
+            console.log(`用法: evolclaw agent delete <aid> [--purge] [--format json]
+
+删除 agent 的配置。
+  --purge   同时清除该 agent 的会话、消息、日志等运行时数据
+  默认       仅删除 config.json，运行时数据保留`);
+            return;
+        }
         const aid = args[1];
         if (!aid) {
             console.error('用法: evolclaw agent delete <aid> [--purge]');
@@ -3172,6 +3349,12 @@ Options:
     }
     // --- show ---
     if (sub === 'show') {
+        if (wantsHelp(args)) {
+            console.log(`用法: evolclaw agent show <aid> [--format json]
+
+查看 agent 详情：身份、配置、连接状态、会话路径等。`);
+            return;
+        }
         const aid = args[1];
         if (!aid) {
             console.error('用法: evolclaw agent show <aid>');
@@ -3285,63 +3468,134 @@ function resolveAunPath(args) {
     return process.env.AUN_HOME || undefined;
 }
 async function cmdAid(args) {
-    const sub = args[0] || 'list';
+    const sub = args[0];
     const formatJson = args.includes('--format') && args[args.indexOf('--format') + 1] === 'json';
     const aunPath = resolveAunPath(args);
-    if (!sub || sub === 'help' || sub === '--help' || sub === '-h' || args.includes('--help') || args.includes('-h')) {
+    if (!sub || isHelpFlag(sub)) {
         console.log(`用法: evolclaw aid <command>
 
 Commands:
-  list              列出本地所有 AID
-  show <aid>        查看本地 AID 详情（证书有效期、私钥状态）
+  list              列出本地所有 AID（实测 sign+verify）
+  show <aid>        查看本地 AID 详情（证书、私钥、签名能力）
   new <aid>         创建新 AID 身份
-  delete <aid>      删除本地 AID（无网络注销）
+  delete <aid>      删除指定本地 AID（无网络注销）
+  delete --orphan         批量清理无私钥的外部 AID 缓存
+  delete --no-cert        批量清理无私钥也无公钥证书的孤儿目录
+  delete --unrecoverable  批量清理云端公钥已变更、本地不可恢复的 AID
+                          批量删除默认 dry-run，加 --yes 执行
   lookup <aid>      远程探测 AID（是否存在 + 网关 + agent.md）
   agentmd put <aid> 读本地 agent.md → 签名 → 上传
   agentmd get <aid> 下载 agent.md → 验签 → 本地持久化
 
 Options:
   --format json     输出 JSON 格式
+  --help, -h        各子命令均支持，查看详细用法
 
 示例:
   evolclaw aid list
   evolclaw aid show toleiliang2.agentid.pub
   evolclaw aid new reviewer.agentid.pub
+  evolclaw aid delete --help
   evolclaw aid delete old.agentid.pub
+  evolclaw aid delete --orphan
+  evolclaw aid delete --unrecoverable --yes
   evolclaw aid lookup someone.agentid.pub
   evolclaw aid agentmd put mybot.agentid.pub
   evolclaw aid agentmd get someone.agentid.pub`);
         return;
     }
-    const { aidList, aidCreate, aidShow, aidDelete, aidLookup, agentmdPut, agentmdGet, buildInitialAgentMd, isValidAid } = await import('../aun/aid/index.js');
+    const { aidList, aidListVerified, aidCreate, aidShow, aidDelete, aidLookup, agentmdPut, agentmdGet, buildInitialAgentMd, isValidAid } = await import('../aun/aid/index.js');
     if (sub === 'list') {
-        const aids = aidList(aunPath);
+        if (wantsHelp(args)) {
+            console.log(`用法: evolclaw aid list [筛选选项] [--no-verify] [--format json]
+
+列出本地 AID 并跑 sign+verify 自检。
+
+筛选选项（可组合，不指定 = 列出 mine + broken + peer-cert）:
+  --mine            仅本地可用身份（实测可签名+验签通过）
+  --broken          仅有私钥但不可用（公钥不匹配 / 证书过期 / sign 失败）
+  --peer-cert       仅对端 AID（无私钥，有公钥证书）
+  --no-cert         仅无私钥无证书的目录（默认隐藏，需用 aid delete --no-cert 清理）
+
+选项:
+  --no-verify       跳过 sign+verify 实测，仅静态扫描（更快，mine/broken 仅按静态判定近似）
+  --format json     JSON 格式输出
+
+输出图标:
+  🔑   有私钥
+  ✅   实测可签名/验签
+  ❌   不可签名（公钥不匹配 / sign 失败 / verify 失败等）
+  ⌛   证书过期
+  📜   有公钥证书
+  📄   有 agent.md
+
+示例:
+  evolclaw aid list                  列出 mine + broken + peer-cert
+  evolclaw aid list --mine           仅可用身份
+  evolclaw aid list --mine --broken  所有有私钥的 AID
+  evolclaw aid list --no-cert        仅无私钥无证书的孤儿目录
+  evolclaw aid list --no-verify      跳过实测，快速静态扫描`);
+            return;
+        }
+        const wantMine = args.includes('--mine');
+        const wantBroken = args.includes('--broken');
+        const wantPeerCert = args.includes('--peer-cert');
+        const wantNoCert = args.includes('--no-cert');
+        const noVerify = args.includes('--no-verify');
+        const anyFilter = wantMine || wantBroken || wantPeerCert || wantNoCert;
+        // 默认: mine + broken + peer-cert（隐藏 no-cert，需显式 --no-cert 才列）
+        const showMine = anyFilter ? wantMine : true;
+        const showBroken = anyFilter ? wantBroken : true;
+        const showPeerCert = anyFilter ? wantPeerCert : true;
+        const showNoCert = anyFilter ? wantNoCert : false;
+        const all = noVerify ? aidList(aunPath) : await aidListVerified(aunPath);
+        const aids = all.filter(a => (showMine && a.category === 'mine') ||
+            (showBroken && a.category === 'broken') ||
+            (showPeerCert && a.category === 'peer-cert') ||
+            (showNoCert && a.category === 'no-cert'));
         if (formatJson) {
             console.log(JSON.stringify(aids, null, 2));
             return;
         }
         if (aids.length === 0) {
-            console.log('本地无 AID');
+            console.log('无匹配 AID');
             return;
         }
-        console.log('本地 AID:');
+        console.log(`本地 AID${noVerify ? '（静态扫描，未实测）' : ''}（${aunPath ?? resolveRoot()}）:`);
         for (const a of aids) {
-            const icons = [
-                a.hasPrivateKey ? '🔑' : '  ',
-                a.hasAgentMd ? '📄' : '  ',
-            ].join('');
-            console.log(`  ${icons} ${a.aid}`);
-        }
-        console.log('\n🔑=私钥  📄=agent.md');
+            const keyIcon = a.hasPrivateKey ? '🔑' : '  ';
+            let signIcon = '  ';
+            // --no-verify 时 signVerified 始终为 null，用 canSign 作为静态近似
+            const effectiveOk = noVerify ? a.canSign : a.signVerified === true;
+            const effectiveFail = noVerify ? (a.hasPrivateKey && !a.canSign) : (a.hasPrivateKey && a.signVerified === false);
+            if (effectiveOk)
+                signIcon = '✅';
+            else if (a.hasPrivateKey && a.certExpired)
+                signIcon = '⌛';
+            else if (effectiveFail)
+                signIcon = '❌';
+            const certIcon = a.hasCert ? '📜' : '  ';
+            const mdIcon = a.hasAgentMd ? '📄' : '  ';
+            const tail = !noVerify && a.signVerified === false && a.signError && !(a.keyMatchesCert === false || a.certExpired || !a.hasPrivateKey || !a.hasCert)
+                ? `  (${a.signError})` : '';
+            console.log(`  ${keyIcon} ${signIcon} ${certIcon} ${mdIcon}  ${a.aid}${tail}`);
+        }
+        console.log('\n🔑=私钥  ✅=可签名/验签  ❌=不可签名  ⌛=证书过期  📜=公钥证书  📄=agent.md');
         return;
     }
     if (sub === 'show') {
+        if (wantsHelp(args)) {
+            console.log(`用法: evolclaw aid show <aid> [--format json]
+
+查看本地 AID 详情：私钥/证书/agent.md 状态、签名能力实测。`);
+            return;
+        }
         const aid = args[1];
         if (!aid) {
             console.error('用法: evolclaw aid show <aid>');
             process.exit(1);
         }
-        const info = aidShow(aid, { aunPath });
+        const info = await aidShow(aid, { aunPath });
         if (formatJson) {
             console.log(JSON.stringify(info, null, 2));
             return;
@@ -3349,58 +3603,246 @@ Options:
         console.log(`AID: ${info.aid}`);
         console.log(`  私钥: ${info.hasPrivateKey ? '有' : '无'}`);
         console.log(`  agent.md: ${info.hasAgentMd ? '有' : '无'}`);
-        console.log(`  证书到期: ${info.certExpiresAt ?? '无证书'}`);
+        if (info.hasAgentMd) {
+            const sigLabel = info.agentMdSignature === 'verified' ? '✓ 已验签'
+                : info.agentMdSignature === 'unsigned' ? '⚠ 未签名'
+                    : info.agentMdSignature === 'invalid' ? `✗ 签名无效${info.agentMdSignatureReason ? ': ' + info.agentMdSignatureReason : ''}`
+                        : '? 未知';
+            console.log(`  签名状态: ${sigLabel}`);
+        }
+        console.log(`  证书到期: ${info.certExpiresAt ?? '无证书'}${info.certExpired ? ' (已过期!)' : ''}`);
         if (info.certSubject)
             console.log(`  证书主体: ${info.certSubject}`);
+        if (info.keyMatchesCert === false)
+            console.log(`  密钥/证书: ✗ 公钥不匹配（cert.pem 与 key.json 公钥不一致）`);
+        else if (info.keyMatchesCert === true)
+            console.log(`  密钥/证书: ✓ 公钥一致`);
+        if (info.signVerified === true)
+            console.log(`  可签名/验签: ✓ 实测通过`);
+        else if (info.signVerified === false)
+            console.log(`  可签名/验签: ✗ 失败${info.signError ? `（${info.signError}）` : ''}`);
+        else
+            console.log(`  可签名/验签: ? 未知`);
         return;
     }
     if (sub === 'new') {
+        if (wantsHelp(args)) {
+            console.log(`用法: evolclaw aid new <完整AID> [--force]
+
+创建新 AID 身份：生成 ECDSA 密钥对、向 Issuer 申请证书、构建并上传初始 agent.md。
+
+选项:
+  --force    强制重新注册，覆盖已存在的身份（即使签名验证失败）
+
+例: evolclaw aid new reviewer.agentid.pub
+    evolclaw aid new reviewer.agentid.pub --force`);
+            return;
+        }
         const aid = args[1];
+        const force = args.includes('--force');
         if (!aid) {
-            console.error('用法: evolclaw aid new <完整AID>\n例: evolclaw aid new reviewer.agentid.pub');
+            console.error('用法: evolclaw aid new <完整AID> [--force]\n例: evolclaw aid new reviewer.agentid.pub');
             process.exit(1);
         }
         if (!isValidAid(aid)) {
             console.error(`❌ 无效 AID 格式: ${aid}`);
             process.exit(1);
         }
-        const result = await aidCreate(aid, { aunPath });
-        if (!result.alreadyExisted) {
-            const content = buildInitialAgentMd({ aid });
+        try {
+            const result = await aidCreate(aid, { aunPath, force });
+            if (!result.alreadyExisted) {
+                const content = buildInitialAgentMd({ aid });
+                try {
+                    await agentmdPut(content, { aid, aunPath });
+                    console.log('✓ agent.md 已发布');
+                }
+                catch (e) {
+                    console.warn(`⚠ agent.md 发布失败（首次连接将自动重试）: ${String(e.message || e).slice(0, 100)}`);
+                }
+            }
             try {
-                await agentmdPut(content, { aid, client: result.client, aunPath });
-                console.log('✓ agent.md 已发布');
+                await result.client.close();
             }
-            catch (e) {
-                console.warn(`⚠ agent.md 发布失败（首次连接将自动重试）: ${String(e.message || e).slice(0, 100)}`);
+            catch { }
+            try {
+                result.store?.close();
             }
+            catch { }
+            const verb = result.alreadyExisted ? '已存在且有效' : (force ? '已重新创建' : '已创建');
+            console.log(`✓ ${aid} ${verb}`);
+            console.log('  如需上线 AUN 通道，运行 evolclaw agent new ' + aid);
         }
-        try {
-            await result.client.close();
+        catch (e) {
+            if (e.code === 'AID_INVALID') {
+                console.error(`❌ ${e.message}`);
+                process.exit(1);
+            }
+            if (e.code === -32052 || e.constructor?.name === 'IdentityConflictError') {
+                console.error(`❌ AID ${aid} 已在服务端注册，但本地密钥无法匹配。\n` +
+                    `该 AID 可能由其他设备创建，无法在本地恢复。请选择其他名称。`);
+                process.exit(1);
+            }
+            throw e;
         }
-        catch { }
-        const verb = result.alreadyExisted ? '已存在' : '已创建';
-        console.log(`✓ ${aid} ${verb}`);
-        console.log('  如需上线 AUN 通道，运行 evolclaw agent new ' + aid);
         return;
     }
     if (sub === 'delete') {
-        const aid = args[1];
-        if (!aid) {
-            console.error('用法: evolclaw aid delete <aid>');
+        if (wantsHelp(args)) {
+            console.log(`用法: evolclaw aid delete <子命令>
+
+单个删除:
+  evolclaw aid delete <aid>           删除指定 AID 的本地数据（无网络注销）
+
+批量删除（默认 dry-run，加 --yes 才真删）:
+  evolclaw aid delete --orphan        删除所有"无私钥"的本地缓存（外部 AID）
+  evolclaw aid delete --no-cert       删除所有"无私钥也无公钥证书"的目录
+                                       条件：!hasPrivateKey && !hasCert
+                                       这些目录最多只剩 agent.md 或 SQLite 残留，
+                                       对验签和加密通信都没用，删除安全。
+  evolclaw aid delete --unrecoverable 删除所有不可恢复的 AID
+                                       条件：本地 sign+verify 实测失败
+                                       且 PKI 探测确认云端公钥也不等本地 key.json
+
+选项:
+  --yes              跳过 dry-run，立即执行
+  --skip-pki         --unrecoverable 时跳过 PKI 探测，仅依据本地 sign+verify 失败判断（危险，可能误删可恢复 AID）
+  --format json      输出 JSON 格式
+
+示例:
+  evolclaw aid delete old.agentid.pub
+  evolclaw aid delete --orphan                列出会被清理的孤儿
+  evolclaw aid delete --orphan --yes          实际清理
+  evolclaw aid delete --no-cert               列出无证书孤儿目录
+  evolclaw aid delete --no-cert --yes         实际清理
+  evolclaw aid delete --unrecoverable         联网探测后列出无救 AID
+  evolclaw aid delete --unrecoverable --yes`);
+            return;
+        }
+        const yes = args.includes('--yes');
+        const skipPki = args.includes('--skip-pki');
+        const orphan = args.includes('--orphan');
+        const noCert = args.includes('--no-cert');
+        const unrecoverable = args.includes('--unrecoverable');
+        const modes = [orphan, noCert, unrecoverable].filter(Boolean).length;
+        if (modes > 1) {
+            console.error('❌ --orphan / --no-cert / --unrecoverable 互斥，不能同时使用');
             process.exit(1);
         }
-        const deleted = aidDelete(aid, { aunPath });
-        if (deleted) {
-            console.log(`✓ ${aid} 已删除`);
+        // 单个 aid 删除：保留原有行为
+        if (modes === 0) {
+            const aid = args[1];
+            if (!aid) {
+                console.error('用法: evolclaw aid delete <aid>\n     evolclaw aid delete --orphan | --no-cert | --unrecoverable [--yes]\n     evolclaw aid delete --help   查看完整用法');
+                process.exit(1);
+            }
+            const deleted = aidDelete(aid, { aunPath });
+            if (deleted) {
+                console.log(`✓ ${aid} 已删除`);
+            }
+            else {
+                console.error(`❌ 本地不存在: ${aid}`);
+                process.exit(1);
+            }
+            return;
+        }
+        // 批量模式：先选出候选
+        const { probePkiRecoverability } = await import('../aun/aid/index.js');
+        const candidates = [];
+        if (orphan) {
+            const aids = aidList(aunPath);
+            for (const a of aids) {
+                if (!a.hasPrivateKey)
+                    candidates.push({ aid: a.aid, reason: 'no private key (external AID cache)' });
+            }
+        }
+        else if (noCert) {
+            const aids = aidList(aunPath);
+            for (const a of aids) {
+                if (!a.hasPrivateKey && !a.hasCert) {
+                    const traits = [a.hasAgentMd ? 'agent.md' : null].filter(Boolean).join(', ');
+                    candidates.push({ aid: a.aid, reason: `no private key, no cert${traits ? ` (only: ${traits})` : ''}` });
+                }
+            }
         }
         else {
-            console.error(`❌ 本地不存在: ${aid}`);
-            process.exit(1);
+            // unrecoverable: 必须先做 sign+verify 实测
+            if (!formatJson)
+                console.log('扫描中: 本地签名/验签实测...');
+            const aids = await aidListVerified(aunPath);
+            const localBroken = aids.filter(a => a.hasPrivateKey && a.signVerified === false);
+            if (skipPki) {
+                for (const a of localBroken) {
+                    candidates.push({ aid: a.aid, reason: `sign+verify failed (${a.signError ?? 'unknown'}) [--skip-pki: 未联网验证]` });
+                }
+            }
+            else {
+                if (!formatJson)
+                    console.log(`扫描中: 对 ${localBroken.length} 个本地损坏 AID 做 PKI 探测...`);
+                for (const a of localBroken) {
+                    const r = await probePkiRecoverability(a.aid, { aunPath });
+                    if (r.kind === 'unrecoverable') {
+                        candidates.push({ aid: a.aid, reason: `local broken; PKI: ${r.reason}`, pki: 'unrecoverable' });
+                    }
+                    else if (r.kind === 'no-server-record') {
+                        candidates.push({ aid: a.aid, reason: `local broken; PKI: ${r.reason}`, pki: 'no-server-record' });
+                    }
+                    else {
+                        // recoverable / no-key / unknown 一律保守不删
+                        if (!formatJson)
+                            console.log(`  · 跳过 ${a.aid}: PKI=${r.kind}${('reason' in r) ? ' — ' + r.reason : ''}`);
+                    }
+                }
+            }
         }
+        if (formatJson) {
+            console.log(JSON.stringify({
+                mode: orphan ? 'orphan' : noCert ? 'no-cert' : 'unrecoverable',
+                dryRun: !yes,
+                skipPki: unrecoverable ? skipPki : undefined,
+                candidates,
+            }, null, 2));
+            if (yes) {
+                for (const c of candidates)
+                    aidDelete(c.aid, { aunPath });
+            }
+            return;
+        }
+        if (candidates.length === 0) {
+            console.log(orphan ? '✓ 无孤儿 AID' : noCert ? '✓ 无无证书孤儿目录' : '✓ 无不可恢复 AID');
+            return;
+        }
+        console.log(`\n${yes ? '将删除' : '候选删除（dry-run）'}：${candidates.length} 个 AID`);
+        for (const c of candidates) {
+            console.log(`  - ${c.aid}`);
+            console.log(`      ${c.reason}`);
+        }
+        if (!yes) {
+            console.log('\n（dry-run，未真删除。加 --yes 执行真删。）');
+            return;
+        }
+        let ok = 0;
+        let fail = 0;
+        for (const c of candidates) {
+            const deleted = aidDelete(c.aid, { aunPath });
+            if (deleted) {
+                console.log(`  ✓ 删除 ${c.aid}`);
+                ok++;
+            }
+            else {
+                console.log(`  ✗ 失败 ${c.aid}（已不存在?）`);
+                fail++;
+            }
+        }
+        console.log(`\n完成：成功 ${ok}，失败 ${fail}`);
         return;
     }
     if (sub === 'lookup') {
+        if (wantsHelp(args)) {
+            console.log(`用法: evolclaw aid lookup <aid> [--format json]
+
+远程探测 AID：是否注册、所在网关、是否有 agent.md（不验签，仅获取）。`);
+            return;
+        }
         const aid = args[1];
         if (!aid) {
             console.error('用法: evolclaw aid lookup <aid>');
@@ -3438,6 +3880,13 @@ Options:
     if (sub === 'agentmd') {
         const verb = args[1];
         const aid = args[2];
+        if (!verb || isHelpFlag(verb) || wantsHelp(args)) {
+            console.log(`用法: evolclaw aid agentmd <put|get> <aid> [--format json]
+
+  put <aid>   读本地 agent.md → 用本地私钥签名 → 上传到 PKI
+  get <aid>   从 PKI 下载 agent.md → 验签 → 持久化到本地`);
+            return;
+        }
         if (verb === 'put') {
             if (!aid) {
                 console.error('用法: evolclaw aid agentmd put <aid>');
@@ -3509,7 +3958,7 @@ Options:
 }
 // ==================== RPC ====================
 async function cmdRpc(args) {
-    if (args[0] === 'help' || args.length === 0) {
+    if (args.length === 0 || isHelpFlag(args[0])) {
         console.log(`用法: evolclaw rpc --as <aid> --params <params>
 
 通用 AUN RPC 调用。
@@ -3588,7 +4037,7 @@ async function cmdStorage(args) {
     const sub = args[0];
     const aunPath = resolveAunPath(args);
     const formatJson = args.includes('--format') && args[args.indexOf('--format') + 1] === 'json';
-    if (!sub || sub === 'help') {
+    if (!sub || isHelpFlag(sub)) {
         console.log(`用法: evolclaw storage <command> <aid> [options]
 
 Commands:
@@ -3737,8 +4186,7 @@ async function cmdMsg(args) {
     const formatJson = args.includes('--format') && args[args.indexOf('--format') + 1] === 'json';
     const appIdx = args.indexOf('--app');
     const appSlot = appIdx >= 0 ? args[appIdx + 1] : undefined;
-    const asDaemon = args.includes('--as-daemon');
-    if (!sub || sub === 'help') {
+    if (!sub || isHelpFlag(sub)) {
         console.log(`用法: evolclaw msg <command> <from-aid> [args...] [options]
 
 Commands:
@@ -3747,13 +4195,12 @@ Commands:
   send <from> <to> --link <url> [--title T]            发送链接卡片
   send <from> <to> --payload <json>                    发送自定义 payload
   pull <from> [--after-seq N] [--limit N]              拉取收件箱
-  ack <from> <seq> --app <name>                        确认已读（必须传 --app）
+  ack <from> <seq> [--app <name>]                      确认已读
   recall <from> <message-id> [<message-id>...]         撤回消息
   online <from> <target-aid> [<target-aid>...]         查询在线状态
 
 Options:
-  --app <name>          指定应用 slot（隔离 ack 游标）
-  --as-daemon           ack 时显式以 daemon 身份（高危，会污染 daemon 游标）
+  --app <name>          指定应用 slot（独立消费通道，不影响 daemon）
   --format json         输出 JSON 格式
   --encrypt             启用端到端加密
   --thread <id>         指定话题 ID（用于多话题路由）
@@ -3879,7 +4326,7 @@ Options:
     }
     if (sub === 'pull') {
         if (!appSlot) {
-            console.error('⚠ 警告: 未传 --app，将使用 daemon 共享 slot（可能与 daemon 看到同一批消息）');
+            console.warn('⚠ 警告: 未传 --app，当前与 daemon 共享 evolclaw 消费通道。pull 会看到/影响 daemon 的消息消费；如需独立消费请用 --app <name>');
         }
         const afterSeqStr = getArgValue(args, '--after-seq');
         const limitStr = getArgValue(args, '--limit');
@@ -3921,7 +4368,7 @@ Options:
     if (sub === 'ack') {
         const seqStr = args[2];
         if (!seqStr) {
-            console.error('用法: evolclaw msg ack <from> <seq> --app <name>');
+            console.error('用法: evolclaw msg ack <from> <seq> [--app <name>]');
             process.exit(1);
         }
         const seq = Number(seqStr);
@@ -3929,10 +4376,8 @@ Options:
             console.error(`❌ seq 必须是数字: ${seqStr}`);
             process.exit(1);
         }
-        if (!appSlot && !asDaemon) {
-            console.error('❌ ack 必须传 --app <name>（或 --as-daemon 显式以 daemon 身份，高危）');
-            console.error('   理由: 不传 --app 会推进 daemon 共享的 ack 游标，导致 daemon 丢消息');
-            process.exit(1);
+        if (!appSlot) {
+            console.warn('⚠ 警告: 未传 --app，ack 将推进与 daemon 共享的 evolclaw 消费游标，可能影响 daemon 收消息；如需独立请用 --app <name>');
         }
         const result = await msgAck({ from, seq, ...commonOpts });
         if (!result.ok) {
@@ -4023,8 +4468,7 @@ async function cmdGroup(args) {
     const formatJson = args.includes('--format') && args[args.indexOf('--format') + 1] === 'json';
     const appIdx = args.indexOf('--app');
     const appSlot = appIdx >= 0 ? args[appIdx + 1] : undefined;
-    const asDaemon = args.includes('--as-daemon');
-    if (!sub || sub === 'help') {
+    if (!sub || isHelpFlag(sub)) {
         console.log(`用法: evolclaw group <command> <from-aid> [args...] [options]
 
 消息:
@@ -4032,7 +4476,7 @@ async function cmdGroup(args) {
   send <from> <group-id> --file <path> [--as <type>]   发送群文件
   send <from> <group-id> --payload <json>              发送自定义 payload
   pull <from> <group-id> [--after-seq N] [--limit N]   拉取群消息
-  ack <from> <group-id> <seq> --app <name>             确认已读（必须传 --app）
+  ack <from> <group-id> <seq> [--app <name>]           确认已读
 
 群管理:
   create <from> <name> [--visibility public|private] [--description D] [--join-mode M]  创建群
@@ -4050,8 +4494,7 @@ async function cmdGroup(args) {
   online <from> <group-id>                             查看在线成员
 
 Options:
-  --app <name>          指定应用 slot（隔离 ack 游标）
-  --as-daemon           ack 时显式以 daemon 身份（高危）
+  --app <name>          指定应用 slot（独立消费通道，不影响 daemon）
   --format json         输出 JSON 格式
   --mention <aid>       发送时 @ 某个成员（可多次）
   --mention-all         发送时 @ 所有人
@@ -4164,7 +4607,7 @@ Options:
     if (sub === 'pull') {
         const groupId = requireGroupId();
         if (!appSlot) {
-            console.error('⚠ 警告: 未传 --app，将使用 daemon 共享 slot');
+            console.warn('⚠ 警告: 未传 --app，当前与 daemon 共享 evolclaw 消费通道。pull 会看到/影响 daemon 的消息消费；如需独立消费请用 --app <name>');
         }
         const afterSeqStr = getArgValue(args, '--after-seq');
         const limitStr = getArgValue(args, '--limit');
@@ -4185,7 +4628,7 @@ Options:
         const groupId = requireGroupId();
         const seqStr = args[3];
         if (!seqStr) {
-            console.error('用法: evolclaw group ack <from> <group-id> <seq> --app <name>');
+            console.error('用法: evolclaw group ack <from> <group-id> <seq> [--app <name>]');
             process.exit(1);
         }
         const seq = Number(seqStr);
@@ -4193,9 +4636,8 @@ Options:
             console.error(`❌ seq 必须是数字: ${seqStr}`);
             process.exit(1);
         }
-        if (!appSlot && !asDaemon) {
-            console.error('❌ group ack 必须传 --app <name>（或 --as-daemon 显式以 daemon 身份，高危）');
-            process.exit(1);
+        if (!appSlot) {
+            console.warn('⚠ 警告: 未传 --app，ack 将推进与 daemon 共享的 evolclaw 消费游标，可能影响 daemon 收消息；如需独立请用 --app <name>');
         }
         const result = await groupAck({ from, groupId, seq, ...commonOpts });
         outputResult(result, () => {
@@ -4424,7 +4866,7 @@ export async function main(args) {
     }
     switch (cmd) {
         case 'init':
-            if (args[1] === 'help') {
+            if (isHelpFlag(args[1])) {
                 console.log(`用法: evolclaw init [渠道] [选项]
 
 仅初始化 defaults.json:
@@ -4500,7 +4942,7 @@ export async function main(args) {
                 await cmdWatchAid();
             }
             else if (args[1] === 'msg') {
-                if (args[2] === '--help' || args[2] === '-h' || args[2] === 'help') {
+                if (isHelpFlag(args[2])) {
                     console.log(`用法: evolclaw watch msg
 
 三面板交互式消息监控 TUI。
@@ -4525,6 +4967,9 @@ export async function main(args) {
             else if (args[1] === 'log') {
                 cmdWatch();
             }
+            else if (args[1] === 'web' || args[1] === 'session') {
+                await cmdWatchWeb();
+            }
             else if (!args[1]) {
                 await cmdWatchMenu();
             }
@@ -4588,6 +5033,11 @@ export async function main(args) {
             await cmdGroup(args.slice(1));
             break;
         }
+        case 'model': {
+            const { cmdModel } = await import('./model.js');
+            await cmdModel(args.slice(1));
+            break;
+        }
         case 'bench': {
             const { suppressSdkLogs } = await import('../aun/aid/index.js');
             suppressSdkLogs();
@@ -4638,14 +5088,25 @@ Commands:
                           --force                            (覆盖已有 config.json)
                   agent reload       全量 resync（扫磁盘，新增上线、删除下线、修改热更新）
                   agent reload <n>   热重载指定 agent 配置
+  model         模型管理（查看/切换，作用域：全局/agent/关系/会话）
+                  model list         列出可用模型，标注各作用域命中
+                  model current      显示实际生效的模型 + 来源
+                  model info <id>    查看单个模型详情（价格/上下文/模态等）
+                  model use <id>     切换模型（--self/--peer/--session 决定作用域）
+                  model effort <lv>  设置推理强度
+                  model reset        清除指定作用域设置，回落上一级
+                  model help         查看完整用法
   aid           AID 身份管理
                   aid list           列出本地所有 AID
                   aid show <aid>     查看本地 AID 详情（证书有效期、私钥状态）
                   aid new <aid>      创建新 AID 身份
-                  aid delete <aid>   删除本地 AID
                   aid lookup <aid>   远程探测 AID（是否存在 + 网关 + agent.md）
                   aid agentmd put <aid>  签名并上传 agent.md
                   aid agentmd get <aid>  下载并验签 agent.md
+                  aid delete <aid>             删除指定 AID
+                  aid delete --orphan          清理无私钥的外部 AID 缓存
+                  aid delete --unrecoverable   清理云端公钥已变更、不可恢复的 AID
+                                                 默认 dry-run，加 --yes 执行
   net           网络链路诊断
                   net check [<aid>]  10 步链路检测（DNS→Discovery→TCP→TLS→WSS→Auth→Ping→Echo）
                   net help           查看详细帮助