evolcore 0.0.24 → 0.0.25

package/dist/cli/aun-commands.js

@@ -116,7 +116,7 @@ async function runManagedAid(args, formatJson) {
     if (!parsed.ok)
         failManagedAid(formatJson, parsed.code, parsed.reason);
     const runtime = await readBestTaskRuntimeContext();
-    const requiresSelfAid = parsed.command.kind === 'show' || parsed.command.kind === 'agentmd.put';
+    const requiresSelfAid = parsed.command.kind === 'show' || parsed.command.kind === 'agentmd.put' || parsed.command.kind === 'avatar';
     if (requiresSelfAid && runtime?.selfAid && parsed.command.aid !== runtime.selfAid.replace(/^@/, '')) {
         failManagedAid(formatJson, 'SCOPE_MISMATCH', `托管任务只能操作当前 self AID：${runtime.selfAid}`);
     }
@@ -155,6 +155,22 @@ async function runManagedAid(args, formatJson) {
                 console.log(JSON.stringify({ ok: true, aid: response.result.aid, path: response.result.path }, null, 2));
             else
                 console.log('✓ agent.md 已发布');
+            return;
+        case 'avatar':
+            if (formatJson)
+                console.log(JSON.stringify({
+                    ok: true,
+                    aid: response.result.aid,
+                    avatar: response.result.avatar,
+                    objectKey: response.result.objectKey,
+                    sha256: response.result.sha256,
+                    mime: response.result.mime,
+                    width: response.result.width,
+                    height: response.result.height,
+                    aspectRatio: response.result.aspectRatio,
+                }, null, 2));
+            else
+                console.log(`✓ 头像已更新${response.result.avatar ? `: ${response.result.avatar}` : ''}${response.result.sha256 ? ` (sha256: ${response.result.sha256})` : ''}`);
     }
 }
 function failManagedGroup(formatJson, code, error) {
@@ -332,36 +348,37 @@ export async function cmdAid(args) {
     const formatJson = getArgValue(args, '--format') === 'json';
     const aunPath = resolveAunPath(args);
     if (!sub || isHelpFlag(sub)) {
-        console.log(`用法: ec aid <command>
-
-Commands:
-  list              列出本地所有 AID（实测 sign+verify）
-  show <aid>        查看本地 AID 详情（证书、私钥、签名能力）
-  new <aid>         创建新 AID 身份
-  delete <aid>      删除指定本地 AID（无网络注销）
-  delete --orphan         批量清理无私钥的外部 AID 缓存
-  delete --no-cert        批量清理无私钥也无公钥证书的孤儿目录
-  delete --unrecoverable  批量清理云端公钥已变更、本地不可恢复的 AID
-                          批量删除默认 dry-run，加 --yes 执行
-  lookup <aid>      远程探测 AID（是否存在 + 网关 + agent.md）
+        console.log(`用法: ec aid <command>
+
+Commands:
+  list              列出本地所有 AID（实测 sign+verify）
+  show <aid>        查看本地 AID 详情（证书、私钥、签名能力）
+  new <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 格式
-  --aun-path <path> 指定 AUN keystore 根（默认 EVOLCORE_HOME，可由 AUN_HOME 设置）
-  --help, -h        各子命令均支持，查看详细用法
-
-示例:
-  ec aid list
-  ec aid show toleiliang2.agentid.pub
-  ec aid new reviewer.agentid.pub
-  ec aid delete --help
-  ec aid delete old.agentid.pub
-  ec aid delete --orphan
-  ec aid delete --unrecoverable --yes
-  ec aid lookup someone.agentid.pub
-  ec aid agentmd put mybot.agentid.pub
+  avatar <aid> --file <path> | --url <https-url>  上传头像并更新 agent.md
+
+Options:
+  --format json     输出 JSON 格式
+  --aun-path <path> 指定 AUN keystore 根（默认 EVOLCORE_HOME，可由 AUN_HOME 设置）
+  --help, -h        各子命令均支持，查看详细用法
+
+示例:
+  ec aid list
+  ec aid show toleiliang2.agentid.pub
+  ec aid new reviewer.agentid.pub
+  ec aid delete --help
+  ec aid delete old.agentid.pub
+  ec aid delete --orphan
+  ec aid delete --unrecoverable --yes
+  ec aid lookup someone.agentid.pub
+  ec aid agentmd put mybot.agentid.pub
   ec aid agentmd get someone.agentid.pub`);
         return;
     }
@@ -372,33 +389,33 @@ Options:
     const { aidList, aidListVerified, aidCreate, aidShow, aidDelete, aidLookup, agentmdPut, agentmdGet, buildInitialAgentMd, isValidAid } = await import('../aun/aid/index.js');
     if (sub === 'list') {
         if (wantsHelp(args)) {
-            console.log(`用法: ec 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
-
-示例:
-  ec aid list                  列出 mine + broken + peer-cert
-  ec aid list --mine           仅可用身份
-  ec aid list --mine --broken  所有有私钥的 AID
-  ec aid list --no-cert        仅无私钥无证书的孤儿目录
+            console.log(`用法: ec 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
+
+示例:
+  ec aid list                  列出 mine + broken + peer-cert
+  ec aid list --mine           仅可用身份
+  ec aid list --mine --broken  所有有私钥的 AID
+  ec aid list --no-cert        仅无私钥无证书的孤儿目录
   ec aid list --no-verify      跳过实测，快速静态扫描`);
             return;
         }
@@ -450,8 +467,8 @@ Options:
     }
     if (sub === 'show') {
         if (wantsHelp(args)) {
-            console.log(`用法: ec aid show <aid> [--format json]
-
+            console.log(`用法: ec aid show <aid> [--format json]
+
 查看本地 AID 详情：私钥/证书/agent.md 状态、签名能力实测。`);
             return;
         }
@@ -466,16 +483,16 @@ Options:
     }
     if (sub === 'new') {
         if (wantsHelp(args)) {
-            console.log(`用法: ec aid new <完整AID> [--force] [--format json]
-
-创建新 AID 身份：生成 ECDSA 密钥对、向 Issuer 申请证书、构建并上传初始 agent.md。
-
-选项:
-  --force    强制重新注册，覆盖已存在的身份（即使签名验证失败）
-  --format json      输出 JSON
-  --aun-path <path>  指定 AUN keystore 根
-
-例: ec aid new reviewer.agentid.pub
+            console.log(`用法: ec aid new <完整AID> [--force] [--format json]
+
+创建新 AID 身份：生成 ECDSA 密钥对、向 Issuer 申请证书、构建并上传初始 agent.md。
+
+选项:
+  --force    强制重新注册，覆盖已存在的身份（即使签名验证失败）
+  --format json      输出 JSON
+  --aun-path <path>  指定 AUN keystore 根
+
+例: ec aid new reviewer.agentid.pub
     ec aid new reviewer.agentid.pub --force`);
             return;
         }
@@ -558,34 +575,34 @@ Options:
     }
     if (sub === 'delete') {
         if (wantsHelp(args)) {
-            console.log(`用法: ec aid delete <子命令>
-
-单个删除:
-  ec aid delete <aid>           删除指定 AID 的本地数据（无网络注销）
-
-批量删除（默认 dry-run，加 --yes 才真删）:
-  ec aid delete --orphan        删除所有"无私钥"的本地缓存（外部 AID）
-  ec aid delete --no-cert       删除所有"无私钥也无公钥证书"的目录
-                                       条件：!hasPrivateKey && !hasCert
-                                       这些目录最多只剩 agent.md 或 SQLite 残留，
-                                       对验签和加密通信都没用，删除安全。
-  ec aid delete --unrecoverable 删除所有不可恢复的 AID
-                                       条件：本地 sign+verify 实测失败
-                                       且 PKI 探测确认云端公钥也不等本地 key.json
-
-选项:
-  --yes              跳过 dry-run，立即执行
-  --skip-pki         --unrecoverable 时跳过 PKI 探测，仅依据本地 sign+verify 失败判断（危险，可能误删可恢复 AID）
-  --format json      输出 JSON 格式
-  --aun-path <path>  指定 AUN keystore 根
-
-示例:
-  ec aid delete old.agentid.pub
-  ec aid delete --orphan                列出会被清理的孤儿
-  ec aid delete --orphan --yes          实际清理
-  ec aid delete --no-cert               列出无证书孤儿目录
-  ec aid delete --no-cert --yes         实际清理
-  ec aid delete --unrecoverable         联网探测后列出无救 AID
+            console.log(`用法: ec aid delete <子命令>
+
+单个删除:
+  ec aid delete <aid>           删除指定 AID 的本地数据（无网络注销）
+
+批量删除（默认 dry-run，加 --yes 才真删）:
+  ec aid delete --orphan        删除所有"无私钥"的本地缓存（外部 AID）
+  ec aid delete --no-cert       删除所有"无私钥也无公钥证书"的目录
+                                       条件：!hasPrivateKey && !hasCert
+                                       这些目录最多只剩 agent.md 或 SQLite 残留，
+                                       对验签和加密通信都没用，删除安全。
+  ec aid delete --unrecoverable 删除所有不可恢复的 AID
+                                       条件：本地 sign+verify 实测失败
+                                       且 PKI 探测确认云端公钥也不等本地 key.json
+
+选项:
+  --yes              跳过 dry-run，立即执行
+  --skip-pki         --unrecoverable 时跳过 PKI 探测，仅依据本地 sign+verify 失败判断（危险，可能误删可恢复 AID）
+  --format json      输出 JSON 格式
+  --aun-path <path>  指定 AUN keystore 根
+
+示例:
+  ec aid delete old.agentid.pub
+  ec aid delete --orphan                列出会被清理的孤儿
+  ec aid delete --orphan --yes          实际清理
+  ec aid delete --no-cert               列出无证书孤儿目录
+  ec aid delete --no-cert --yes         实际清理
+  ec aid delete --unrecoverable         联网探测后列出无救 AID
   ec aid delete --unrecoverable --yes`);
             return;
         }
@@ -715,8 +732,8 @@ Options:
     }
     if (sub === 'lookup') {
         if (wantsHelp(args)) {
-            console.log(`用法: ec aid lookup <aid> [--format json]
-
+            console.log(`用法: ec aid lookup <aid> [--format json]
+
 远程探测 AID：是否注册、所在网关、是否有 agent.md（不验签，仅获取）。`);
             return;
         }
@@ -737,9 +754,9 @@ Options:
         const verb = args[1];
         const aid = args[2];
         if (!verb || isHelpFlag(verb) || wantsHelp(args)) {
-            console.log(`用法: ec aid agentmd <put|get> <aid> [--format json]
-
-  put <aid>   读本地 agent.md → 用本地私钥签名 → 上传到 PKI
+            console.log(`用法: ec aid agentmd <put|get> <aid> [--format json]
+
+  put <aid>   读本地 agent.md → 用本地私钥签名 → 上传到 PKI
   get <aid>   从 PKI 下载 agent.md → 验签 → 持久化到本地`);
             return;
         }
@@ -795,30 +812,79 @@ Options:
         console.error(`未知子命令: aid agentmd ${verb ?? ''}\n用法: ec aid agentmd [put|get] <aid>`);
         process.exit(1);
     }
-    console.error(`未知子命令: ${sub}\n用法: ec aid [list|show|new|delete|lookup|agentmd] <aid>`);
+    if (sub === 'avatar') {
+        const aid = args[1];
+        const fileIndex = args.indexOf('--file');
+        const urlIndex = args.indexOf('--url');
+        const filePath = fileIndex >= 0 ? args[fileIndex + 1] : undefined;
+        const url = urlIndex >= 0 ? args[urlIndex + 1] : undefined;
+        if (wantsHelp(args)) {
+            console.log('用法: ec aid avatar <aid> (--file <path> | --url <https-url>) [--format json]');
+            return;
+        }
+        const sourceCount = (fileIndex >= 0 ? 1 : 0) + (urlIndex >= 0 ? 1 : 0);
+        if (!aid || sourceCount !== 1 || (fileIndex >= 0 && (!filePath || filePath.startsWith('-')))
+            || (urlIndex >= 0 && (!url || url.startsWith('-'))) || (fileIndex >= 0 && fileIndex !== 2) || (urlIndex >= 0 && urlIndex !== 2)
+            || args.filter(value => value === '--file').length > 1 || args.filter(value => value === '--url').length > 1 || !isValidAid(aid)
+            || (args.includes('--format') && !formatJson) || (args.includes('--format') && args.filter(value => value === '--format').length !== 1)) {
+            const usage = '用法: ec aid avatar <aid> (--file <path> | --url <https-url>) [--format json]';
+            if (formatJson)
+                console.log(JSON.stringify({ ok: false, code: 'INVALID_ARGUMENT', error: usage }, null, 2));
+            else
+                console.error(usage);
+            process.exit(1);
+        }
+        const { uploadAvatarFile, uploadAvatarUrl } = await import('../utils/avatar-upload.js');
+        const result = filePath
+            ? await uploadAvatarFile(aid, filePath, { aunPath })
+            : await uploadAvatarUrl(aid, url, { aunPath });
+        if (!result.ok) {
+            if (formatJson)
+                console.log(JSON.stringify({ ok: false, code: result.code, error: result.error }, null, 2));
+            else
+                console.error(`❌ 头像上传失败: ${result.error}`);
+            process.exit(1);
+        }
+        if (formatJson)
+            console.log(JSON.stringify({
+                ok: true,
+                aid,
+                avatar: result.publicUrl,
+                objectKey: result.objectKey,
+                sha256: result.sha256,
+                mime: result.mime,
+                width: result.width,
+                height: result.height,
+                aspectRatio: result.aspectRatio,
+            }, null, 2));
+        else
+            console.log(`✓ 头像已更新${result.publicUrl ? `: ${result.publicUrl}` : ''}${result.sha256 ? ` (sha256: ${result.sha256})` : ''}`);
+        return;
+    }
+    console.error(`未知子命令: ${sub}\n用法: ec aid [list|show|new|delete|lookup|agentmd|avatar] <aid>`);
     process.exit(1);
 }
 // ==================== RPC ====================
 export async function cmdRpc(args) {
     if (args.length === 0 || wantsHelp(args)) {
-        console.log(`用法: ec rpc --as <aid> --params <params>
-
-通用 AUN RPC 调用。
-
---params 自动判断输入形式:
-  单行 JSON (以 { 开头)     → 单次调用
-  多行 JSONL                → 逐行执行，失败即停
-  文件路径 (文件存在)        → 读取文件内容作为 JSONL
-
-每行 JSON 格式: {"method":"<namespace.method>","params":{...}}
-
-Options:
-  --app <name>   指定应用 slot（独立消费通道）。仅对 message.pull / group.pull
-                 等消费类方法有意义——隔离 seq 游标与消息过滤；默认与 daemon 共享通道。
-  --aun-path <path> 指定 AUN keystore 根
-
-示例:
-  ec rpc --as alice.agentid.pub --params '{"method":"message.send","params":{"to":"bob.agentid.pub","payload":{"type":"text","text":"hello"}}}'
+        console.log(`用法: ec rpc --as <aid> --params <params>
+
+通用 AUN RPC 调用。
+
+--params 自动判断输入形式:
+  单行 JSON (以 { 开头)     → 单次调用
+  多行 JSONL                → 逐行执行，失败即停
+  文件路径 (文件存在)        → 读取文件内容作为 JSONL
+
+每行 JSON 格式: {"method":"<namespace.method>","params":{...}}
+
+Options:
+  --app <name>   指定应用 slot（独立消费通道）。仅对 message.pull / group.pull
+                 等消费类方法有意义——隔离 seq 游标与消息过滤；默认与 daemon 共享通道。
+  --aun-path <path> 指定 AUN keystore 根
+
+示例:
+  ec rpc --as alice.agentid.pub --params '{"method":"message.send","params":{"to":"bob.agentid.pub","payload":{"type":"text","text":"hello"}}}'
   ec rpc --as alice.agentid.pub --params calls.jsonl`);
         return;
     }
@@ -886,29 +952,29 @@ export async function cmdStorage(args) {
     const aunPath = resolveAunPath(args);
     const formatJson = getArgValue(args, '--format') === 'json';
     if (!sub || wantsHelp(args)) {
-        console.log(`用法: ec storage <command> <aid> [options]
-
-Commands:
-  upload <aid> <local-file> <remote-path> [--public]   上传文件（默认私有）
-  download <aid> <url> [local-path]                    下载文件
-  ls <aid> [prefix]                                    列文件
-  rm <aid> <remote-path>                               删文件
-  quota <aid>                                          查配额
-
-<url> 格式: [https://]<owner-aid>/<path>
-
-Options:
-  --public          上传后公开可读（仅 upload）
-  --format json     输出 JSON
-  --aun-path <path> 指定 AUN keystore 根
-
-示例:
-  ec storage upload myaid.agentid.pub ./doc.txt notes/doc.txt
-  ec storage upload myaid.agentid.pub ./pic.png images/pic.png --public
-  ec storage download myaid.agentid.pub myaid.agentid.pub/notes/doc.txt ./doc.txt
-  ec storage download myaid.agentid.pub bob.agentid.pub/public/file.pdf ./file.pdf
-  ec storage ls myaid.agentid.pub notes/
-  ec storage rm myaid.agentid.pub notes/doc.txt
+        console.log(`用法: ec storage <command> <aid> [options]
+
+Commands:
+  upload <aid> <local-file> <remote-path> [--public]   上传文件（默认私有）
+  download <aid> <url> [local-path]                    下载文件
+  ls <aid> [prefix]                                    列文件
+  rm <aid> <remote-path>                               删文件
+  quota <aid>                                          查配额
+
+<url> 格式: [https://]<owner-aid>/<path>
+
+Options:
+  --public          上传后公开可读（仅 upload）
+  --format json     输出 JSON
+  --aun-path <path> 指定 AUN keystore 根
+
+示例:
+  ec storage upload myaid.agentid.pub ./doc.txt notes/doc.txt
+  ec storage upload myaid.agentid.pub ./pic.png images/pic.png --public
+  ec storage download myaid.agentid.pub myaid.agentid.pub/notes/doc.txt ./doc.txt
+  ec storage download myaid.agentid.pub bob.agentid.pub/public/file.pdf ./file.pdf
+  ec storage ls myaid.agentid.pub notes/
+  ec storage rm myaid.agentid.pub notes/doc.txt
   ec storage quota myaid.agentid.pub`);
         return;
     }
@@ -1063,83 +1129,83 @@ export async function cmdMsg(args) {
     const formatJson = getArgValue(args, '--format') === 'json';
     const appSlot = getArgValue(args, '--app');
     if (!sub || isHelpFlag(sub) || (wantsHelp(args) && sub !== 'history')) {
-        console.log(`用法: ec msg <command> <from-aid> [args...] [options]
-
-Commands:
-  send <from> <to> <text> --return <none|required>     发送文本（跨会话时 --return 必填）
-  send <from> <to> --text-from-file <path>             从文件读取文本内容
-  send <from> <to> --file <path> [--as <type>]         发送文件（image|video|voice|file）
-  send <from> <to> --link <url> [--title T]            发送链接卡片
-  send <from> <to> --payload <json>                    发送自定义 payload
+        console.log(`用法: ec msg <command> <from-aid> [args...] [options]
+
+Commands:
+  send <from> <to> <text> --return <none|required>     发送文本（跨会话时 --return 必填）
+  send <from> <to> --text-from-file <path>             从文件读取文本内容
+  send <from> <to> --file <path> [--as <type>]         发送文件（image|video|voice|file）
+  send <from> <to> --link <url> [--title T]            发送链接卡片
+  send <from> <to> --payload <json>                    发送自定义 payload
   pull <from> [--after-seq N] [--limit N] --app <name> 拉取收件箱（必须使用独立 slot）
-  ack <from> <seq> [--app <name>]                      确认已读
-  recall <from> <message-id> [<message-id>...]         撤回消息
-  online <from> <target-aid> [<target-aid>...]         查询在线状态
-  history <from> [<target-aid>|selector] [筛选选项]    查询本地消息历史
-
-Options:
-  --text-from-file <path>  从文件读取文本（UTF-8），用于超长消息或避免 Shell 转义
-  --app <name>          指定应用 slot（独立消费通道，不影响 daemon）
-  --aun-path <path>     指定 AUN keystore 根
-  --format json         输出 JSON 格式
-  --encrypt             强制端到端加密（未指定时使用 daemon 默认值）
-  --no-encrypt          强制明文发送（优先于 --encrypt）
-  --thread <id>         指定话题 ID（用于多话题路由）
-  --session <latest|all|id> 按 EvolCore 逻辑会话过滤历史（默认 latest）
-  --before <time>       只返回该时间之前的历史
-  --after <time>        只返回该时间之后的历史
-  --direction <value>   历史方向：in|out|all
-  --channel <type>      历史渠道：aun|feishu|wechat|dingtalk|qqbot|wecom
-  --channel-name <name> 历史渠道实例名（非 AUN 渠道必须匹配 Agent 配置）
-  --channel-key <key>   非 AUN 已落盘渠道的完整实例键（与 --peer-id 成对）
-  --peer-id <id>        非 AUN 渠道的原生对端 ID（与 --channel-key 成对）
-  --return <none|required> 跨会话发送必填：none=仅补充目标上下文，required=回答回流来源
-  --content-type <mime> 显式覆盖 MIME（仅 --file 模式）
-  --as <type>           附件类型：image|video|voice|file（仅 --file 模式）
-  --text <说明>          附件说明文字（仅 --file 模式）
-  --transcript <text>   语音转写（仅 --as voice）
-  --title <text>        链接标题（仅 --link 模式）
-  --description <text>  链接描述（仅 --link 模式）
-  --                    end-of-options：其后所有参数按正文处理
-                        （用于发送恰好等于某 flag 的文本，如 send a b -- --encrypt）
-
-示例:
-  ec msg send alice.agentid.pub bob.agentid.pub "hello" --return none
-  ec msg send alice.agentid.pub bob.agentid.pub --text-from-file long-message.txt --return none
-  ec msg send alice.agentid.pub bob.agentid.pub "讨论项目A" --thread "project-A" --return required
-  ec msg send alice.agentid.pub bob.agentid.pub --file ./pic.png --return none
-  ec msg send alice.agentid.pub bob.agentid.pub --file ./demo.mp4 --as video --return none
-  ec msg send alice.agentid.pub bob.agentid.pub --link https://example.com --title "AUN" --return none
-  ec msg pull alice.agentid.pub --app my-bot
-  ec msg ack alice.agentid.pub 42 --app my-bot
-  ec msg recall alice.agentid.pub msg-uuid-1 msg-uuid-2
-  ec msg online alice.agentid.pub bob.agentid.pub carol.agentid.pub
-  ec msg history alice.agentid.pub bob.agentid.pub --session latest --limit 50
+  ack <from> <seq> [--app <name>]                      确认已读
+  recall <from> <message-id> [<message-id>...]         撤回消息
+  online <from> <target-aid> [<target-aid>...]         查询在线状态
+  history <from> [<target-aid>|selector] [筛选选项]    查询本地消息历史
+
+Options:
+  --text-from-file <path>  从文件读取文本（UTF-8），用于超长消息或避免 Shell 转义
+  --app <name>          指定应用 slot（独立消费通道，不影响 daemon）
+  --aun-path <path>     指定 AUN keystore 根
+  --format json         输出 JSON 格式
+  --encrypt             强制端到端加密（未指定时使用 daemon 默认值）
+  --no-encrypt          强制明文发送（优先于 --encrypt）
+  --thread <id>         指定话题 ID（用于多话题路由）
+  --session <latest|all|id> 按 EvolCore 逻辑会话过滤历史（默认 latest）
+  --before <time>       只返回该时间之前的历史
+  --after <time>        只返回该时间之后的历史
+  --direction <value>   历史方向：in|out|all
+  --channel <type>      历史渠道：aun|feishu|wechat|dingtalk|qqbot|wecom
+  --channel-name <name> 历史渠道实例名（非 AUN 渠道必须匹配 Agent 配置）
+  --channel-key <key>   非 AUN 已落盘渠道的完整实例键（与 --peer-id 成对）
+  --peer-id <id>        非 AUN 渠道的原生对端 ID（与 --channel-key 成对）
+  --return <none|required> 跨会话发送必填：none=仅补充目标上下文，required=回答回流来源
+  --content-type <mime> 显式覆盖 MIME（仅 --file 模式）
+  --as <type>           附件类型：image|video|voice|file（仅 --file 模式）
+  --text <说明>          附件说明文字（仅 --file 模式）
+  --transcript <text>   语音转写（仅 --as voice）
+  --title <text>        链接标题（仅 --link 模式）
+  --description <text>  链接描述（仅 --link 模式）
+  --                    end-of-options：其后所有参数按正文处理
+                        （用于发送恰好等于某 flag 的文本，如 send a b -- --encrypt）
+
+示例:
+  ec msg send alice.agentid.pub bob.agentid.pub "hello" --return none
+  ec msg send alice.agentid.pub bob.agentid.pub --text-from-file long-message.txt --return none
+  ec msg send alice.agentid.pub bob.agentid.pub "讨论项目A" --thread "project-A" --return required
+  ec msg send alice.agentid.pub bob.agentid.pub --file ./pic.png --return none
+  ec msg send alice.agentid.pub bob.agentid.pub --file ./demo.mp4 --as video --return none
+  ec msg send alice.agentid.pub bob.agentid.pub --link https://example.com --title "AUN" --return none
+  ec msg pull alice.agentid.pub --app my-bot
+  ec msg ack alice.agentid.pub 42 --app my-bot
+  ec msg recall alice.agentid.pub msg-uuid-1 msg-uuid-2
+  ec msg online alice.agentid.pub bob.agentid.pub carol.agentid.pub
+  ec msg history alice.agentid.pub bob.agentid.pub --session latest --limit 50
   ec msg history alice.agentid.pub --channel-key feishu#alice.agentid.pub#main --peer-id ou_xxx --session all --format json`);
         return;
     }
     if (sub === 'history' && wantsHelp(args)) {
-        console.log(`用法: ec msg history <self-aid> [<target-aid> | --channel-key <key> --peer-id <id>] [options]
-
-查询指定会话对的本地历史，不调用 message.pull，也不影响收件箱游标。非 AUN selector 按已落盘的 session metadata、完整 channelKey 与原生 peer ID 精确读取，不能传入文件路径。
-
-托管会话限制：普通会话只能使用当前 self AID 和当前 AUN 私聊对端；可信 daemon Trigger 可用精确的 --channel-key/--peer-id selector 读取已落盘的非 AUN 私聊历史。托管任务不支持 --channel、--channel-name、--aun-path 或 --app。
-
-Options:
-  --session <latest|all|id> 默认 latest；all 查询全部；也可指定会话 ID
-  --limit <N>             返回最新 N 条（默认 50，最大 500）
-  --before <time>         开区间；epoch 毫秒或 ISO 时间
-  --after <time>          开区间；epoch 毫秒或 ISO 时间
-  --direction <value>     in|out|all（默认 all）
-  --channel-key <key>     非 AUN 已落盘渠道完整键；必须与 --peer-id 同时给出
-  --peer-id <id>          原生私聊对端 ID；必须与 --channel-key 同时给出
-  --format <text|json>    输出格式（默认 text）
-
-示例:
-  ec msg history alice.agentid.pub bob.agentid.pub
-  ec msg history alice.agentid.pub bob.agentid.pub --session latest
-  ec msg history alice.agentid.pub bob.agentid.pub --session all
-  ec msg history alice.agentid.pub bob.agentid.pub --session meta_20260713_1783920000000 --format json
+        console.log(`用法: ec msg history <self-aid> [<target-aid> | --channel-key <key> --peer-id <id>] [options]
+
+查询指定会话对的本地历史，不调用 message.pull，也不影响收件箱游标。非 AUN selector 按已落盘的 session metadata、完整 channelKey 与原生 peer ID 精确读取，不能传入文件路径。
+
+托管会话限制：普通会话只能使用当前 self AID 和当前 AUN 私聊对端；可信 daemon Trigger 可用精确的 --channel-key/--peer-id selector 读取已落盘的非 AUN 私聊历史。托管任务不支持 --channel、--channel-name、--aun-path 或 --app。
+
+Options:
+  --session <latest|all|id> 默认 latest；all 查询全部；也可指定会话 ID
+  --limit <N>             返回最新 N 条（默认 50，最大 500）
+  --before <time>         开区间；epoch 毫秒或 ISO 时间
+  --after <time>          开区间；epoch 毫秒或 ISO 时间
+  --direction <value>     in|out|all（默认 all）
+  --channel-key <key>     非 AUN 已落盘渠道完整键；必须与 --peer-id 同时给出
+  --peer-id <id>          原生私聊对端 ID；必须与 --channel-key 同时给出
+  --format <text|json>    输出格式（默认 text）
+
+示例:
+  ec msg history alice.agentid.pub bob.agentid.pub
+  ec msg history alice.agentid.pub bob.agentid.pub --session latest
+  ec msg history alice.agentid.pub bob.agentid.pub --session all
+  ec msg history alice.agentid.pub bob.agentid.pub --session meta_20260713_1783920000000 --format json
   ec msg history alice.agentid.pub --channel-key feishu#alice.agentid.pub#main --peer-id ou_xxx --session all --format json`);
         return;
     }
@@ -1568,74 +1634,74 @@ export async function cmdGroup(args) {
     const appSlot = getArgValue(args, '--app');
     const rulesActionHelp = sub === 'rules' && isHelpFlag(args[3]);
     if (!sub || isHelpFlag(sub) || (wantsHelp(args) && !rulesActionHelp)) {
-        console.log(`用法: ec group <command> <from-aid> [args...] [options]
-
-消息:
-  send <from> <group-id> <text> --return <none|required> 发送群文本（跨会话时 --return 必填）
-  send <from> <group-id> --file <path> [--as <type>]   发送群文件
-  send <from> <group-id> --payload <json>              发送自定义 payload
+        console.log(`用法: ec group <command> <from-aid> [args...] [options]
+
+消息:
+  send <from> <group-id> <text> --return <none|required> 发送群文本（跨会话时 --return 必填）
+  send <from> <group-id> --file <path> [--as <type>]   发送群文件
+  send <from> <group-id> --payload <json>              发送自定义 payload
   pull <from> <group-id> [--after-seq N] [--limit N] --app <name>   拉取群消息（必须使用独立 slot）
-  ack <from> <group-id> <seq> [--app <name>]           确认已读
-
-群管理:
-  create <from> <name> [--visibility public|private] [--description D]
-                       [--join-mode open|approval|invite_only|closed]  创建群
-  list <from> [--size N]                                列出我加入的群
-  info <from> <group-id>                                查看群详情
-  update <from> <group-id> [--name N] [--description D] 修改群信息
-  dissolve <from> <group-id>                            解散群
-  suspend <from> <group-id>                             暂停群
-  resume <from> <group-id>                              恢复群
-  rules <from> <group-id> get                          读取已发布群规则文件 /rules.md
-  rules <from> <group-id> set <file>                   上传并发布群规则文件
-  rules <from> <group-id> publish                      发布当前群空间 /rules.md
-  rules <from> <group-id> [--mode M] [--question Q] [--max-pending N]  查看/更新入群规则
-
-成员:
-  join <from> <group-id> [--message M] [--answer A]    申请加入
-  leave <from> <group-id>                              退出群
-  invite <from> <group-id> <member-aid> [<member-aid>...]   创建定向邀请
-  invites <from> [--page N] [--size N]                    查看收到的邀请
-  accept-invite <from> <invite-id>                         接受邀请
-  reject-invite <from> <invite-id>                         拒绝邀请
-  revoke-invite <from> <invite-id>                         撤回邀请
-  kick <from> <group-id> <member-aid>                  踢出成员
-  members <from> <group-id> [--page N] [--size N]      列出群成员
-  online <from> <group-id>                             查看在线成员
-  role <from> <group-id> <member-aid> <admin|member>   设置成员角色
-  owner <from> <group-id> <new-owner-aid>               转让群主
-  ban <from> <group-id> [<member-aid>] [--duration N]   封禁成员；不带 member-aid 时列出封禁
-  unban <from> <group-id> <member-aid>                  解封成员
-
-Options:
-  --app <name>          指定应用 slot（独立消费通道，不影响 daemon）
-  --aun-path <path>     指定 AUN keystore 根
-  --format json         输出 JSON 格式
-  --encrypt             强制端到端加密（未指定时使用 daemon 默认值；仅 send）
-  --no-encrypt          强制明文发送（优先于 --encrypt；仅 send）
-  --thread <id>         指定话题 ID（仅 send）
-  --return <none|required> 跨会话发送必填（仅 send；Trigger 只能使用 none）
-  --mention <aid>       发送时 @ 某个成员（可多次，或用逗号分隔多个 aid）
-  --mention-all         发送时 @ 所有人
-  --content-type <mime> 显式覆盖 MIME（仅 --file 模式）
-  --as <type>           附件类型：image|video|voice|file（仅 --file 模式）
-  --text <说明>          附件说明文字（仅 --file 模式）
-  --transcript <text>   语音转写（仅 --as voice）
-  --group-id <aid>      指定自定义群 AID（仅 create）
-  --member-type <type>  定向邀请成员类型：human|ai（仅 invite）
-  --                    end-of-options：其后所有参数按正文处理
-                        （用于发送恰好等于某 flag 的文本，如 send a g -- --encrypt）
-
-格式示例（.example.invalid 是保留的虚构域，以下 AID 均不是真实地址）:
-  ec group create sender.example.invalid "Dev Team" --visibility private
-  ec group send sender.example.invalid 12345.example.invalid "hello team" --return none
-  ec group send sender.example.invalid 12345.example.invalid "@member 看下 PR" --mention member.example.invalid
-  ec group send sender.example.invalid 12345.example.invalid --file ./arch.png
-  ec group rules sender.example.invalid 12345.example.invalid set ./rules.md
-  ec group invite sender.example.invalid 12345.example.invalid member.example.invalid
-  ec group members sender.example.invalid 12345.example.invalid
-
-查询真实群 AID:
+  ack <from> <group-id> <seq> [--app <name>]           确认已读
+
+群管理:
+  create <from> <name> [--visibility public|private] [--description D]
+                       [--join-mode open|approval|invite_only|closed]  创建群
+  list <from> [--size N]                                列出我加入的群
+  info <from> <group-id>                                查看群详情
+  update <from> <group-id> [--name N] [--description D] 修改群信息
+  dissolve <from> <group-id>                            解散群
+  suspend <from> <group-id>                             暂停群
+  resume <from> <group-id>                              恢复群
+  rules <from> <group-id> get                          读取已发布群规则文件 /rules.md
+  rules <from> <group-id> set <file>                   上传并发布群规则文件
+  rules <from> <group-id> publish                      发布当前群空间 /rules.md
+  rules <from> <group-id> [--mode M] [--question Q] [--max-pending N]  查看/更新入群规则
+
+成员:
+  join <from> <group-id> [--message M] [--answer A]    申请加入
+  leave <from> <group-id>                              退出群
+  invite <from> <group-id> <member-aid> [<member-aid>...]   创建定向邀请
+  invites <from> [--page N] [--size N]                    查看收到的邀请
+  accept-invite <from> <invite-id>                         接受邀请
+  reject-invite <from> <invite-id>                         拒绝邀请
+  revoke-invite <from> <invite-id>                         撤回邀请
+  kick <from> <group-id> <member-aid>                  踢出成员
+  members <from> <group-id> [--page N] [--size N]      列出群成员
+  online <from> <group-id>                             查看在线成员
+  role <from> <group-id> <member-aid> <admin|member>   设置成员角色
+  owner <from> <group-id> <new-owner-aid>               转让群主
+  ban <from> <group-id> [<member-aid>] [--duration N]   封禁成员；不带 member-aid 时列出封禁
+  unban <from> <group-id> <member-aid>                  解封成员
+
+Options:
+  --app <name>          指定应用 slot（独立消费通道，不影响 daemon）
+  --aun-path <path>     指定 AUN keystore 根
+  --format json         输出 JSON 格式
+  --encrypt             强制端到端加密（未指定时使用 daemon 默认值；仅 send）
+  --no-encrypt          强制明文发送（优先于 --encrypt；仅 send）
+  --thread <id>         指定话题 ID（仅 send）
+  --return <none|required> 跨会话发送必填（仅 send；Trigger 只能使用 none）
+  --mention <aid>       发送时 @ 某个成员（可多次，或用逗号分隔多个 aid）
+  --mention-all         发送时 @ 所有人
+  --content-type <mime> 显式覆盖 MIME（仅 --file 模式）
+  --as <type>           附件类型：image|video|voice|file（仅 --file 模式）
+  --text <说明>          附件说明文字（仅 --file 模式）
+  --transcript <text>   语音转写（仅 --as voice）
+  --group-id <aid>      指定自定义群 AID（仅 create）
+  --member-type <type>  定向邀请成员类型：human|ai（仅 invite）
+  --                    end-of-options：其后所有参数按正文处理
+                        （用于发送恰好等于某 flag 的文本，如 send a g -- --encrypt）
+
+格式示例（.example.invalid 是保留的虚构域，以下 AID 均不是真实地址）:
+  ec group create sender.example.invalid "Dev Team" --visibility private
+  ec group send sender.example.invalid 12345.example.invalid "hello team" --return none
+  ec group send sender.example.invalid 12345.example.invalid "@member 看下 PR" --mention member.example.invalid
+  ec group send sender.example.invalid 12345.example.invalid --file ./arch.png
+  ec group rules sender.example.invalid 12345.example.invalid set ./rules.md
+  ec group invite sender.example.invalid 12345.example.invalid member.example.invalid
+  ec group members sender.example.invalid 12345.example.invalid
+
+查询真实群 AID:
   ec group list <发送方AID>`);
         return;
     }
@@ -2067,18 +2133,18 @@ Options:
         const groupId = requireGroupId();
         const action = args[3];
         const printRulesFileUsage = () => {
-            console.log(`用法:
-  ec group rules <from> <group-id> get
-  ec group rules <from> <group-id> set <file>
-  ec group rules <from> <group-id> publish
-  ec group rules <from> <group-id> [--mode open|approval|invite_only|closed] [--question Q] [--max-pending N]
-
-说明:
-  get      读取当前已发布的群规则文件 /rules.md
-  set      上传本地文件到群空间 /rules.md，发布 rules.content 元数据，并发送 group.rules.updated 通知
-  publish  不上传文件，仅发布当前群空间 /rules.md 的元数据并发送通知
-
-兼容:
+            console.log(`用法:
+  ec group rules <from> <group-id> get
+  ec group rules <from> <group-id> set <file>
+  ec group rules <from> <group-id> publish
+  ec group rules <from> <group-id> [--mode open|approval|invite_only|closed] [--question Q] [--max-pending N]
+
+说明:
+  get      读取当前已发布的群规则文件 /rules.md
+  set      上传本地文件到群空间 /rules.md，发布 rules.content 元数据，并发送 group.rules.updated 通知
+  publish  不上传文件，仅发布当前群空间 /rules.md 的元数据并发送通知
+
+兼容:
   不带 get/set/publish 时仍使用旧的入群规则接口。`);
         };
         const printRulesFileState = (result, verb) => {