evolcore 0.0.2 → 0.0.4

package/dist/cli/agent-command.js

@@ -25,7 +25,8 @@ function formatBytes(bytes) {
 export async function cmdAgent(args) {
     const sub = args[0];
     const formatJson = getArgValue(args, '--format') === 'json';
-    if (!sub || isHelpFlag(sub)) {
+    const commands = new Set(['list', 'show', 'new', 'enable', 'disable', 'get', 'set', 'rename', 'ready', 'reload', 'delete']);
+    if (!sub || isHelpFlag(sub) || (wantsHelp(args) && !commands.has(sub))) {
         console.log(`用法: ec agent <command>
 
 Commands:

package/dist/cli/aun-commands.js

@@ -31,6 +31,7 @@ Commands:
 
 Options:
   --format json     输出 JSON 格式
+  --aun-path <path> 指定 AUN keystore 根（默认 EVOLCORE_HOME，可由 AUN_HOME 设置）
   --help, -h        各子命令均支持，查看详细用法
 
 示例:
@@ -169,12 +170,14 @@ Options:
     }
     if (sub === 'new') {
         if (wantsHelp(args)) {
-            console.log(`用法: ec aid new <完整AID> [--force]
+            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`);
@@ -183,23 +186,35 @@ Options:
         const aid = args[1];
         const force = args.includes('--force');
         if (!aid) {
-            console.error('用法: ec aid new <完整AID> [--force]\n例: ec aid new reviewer.agentid.pub');
+            if (formatJson)
+                console.log(JSON.stringify({ ok: false, code: 'MISSING_AID', error: 'missing AID' }));
+            else
+                console.error('用法: ec aid new <完整AID> [--force]\n例: ec aid new reviewer.agentid.pub');
             process.exit(1);
         }
         if (!isValidAid(aid)) {
-            console.error(`❌ 无效 AID 格式: ${aid}`);
+            if (formatJson)
+                console.log(JSON.stringify({ ok: false, code: 'INVALID_AID', error: `invalid AID: ${aid}` }));
+            else
+                console.error(`❌ 无效 AID 格式: ${aid}`);
             process.exit(1);
         }
         try {
             const result = await aidCreate(aid, { aunPath, force });
+            let agentmdUploaded = result.alreadyExisted;
+            let agentmdError;
             if (!result.alreadyExisted) {
                 const content = buildInitialAgentMd({ aid });
                 try {
                     await agentmdPut(content, { aid, aunPath });
-                    console.log('✓ agent.md 已发布');
+                    agentmdUploaded = true;
+                    if (!formatJson)
+                        console.log('✓ agent.md 已发布');
                 }
                 catch (e) {
-                    console.warn(`⚠ agent.md 发布失败（首次连接将自动重试）: ${String(e.message || e).slice(0, 100)}`);
+                    agentmdError = String(e.message || e).slice(0, 100);
+                    if (!formatJson)
+                        console.warn(`⚠ agent.md 发布失败（首次连接将自动重试）: ${agentmdError}`);
                 }
             }
             try {
@@ -211,17 +226,34 @@ Options:
             }
             catch { }
             const verb = result.alreadyExisted ? '已存在且有效' : (force ? '已重新创建' : '已创建');
-            console.log(`✓ ${aid} ${verb}`);
-            console.log('  如需上线 AUN 通道，运行 ec agent new ' + aid);
+            if (formatJson) {
+                console.log(JSON.stringify({
+                    ok: true,
+                    aid,
+                    alreadyExisted: result.alreadyExisted,
+                    agentmdUploaded,
+                    ...(agentmdError ? { agentmdError } : {}),
+                }, null, 2));
+            }
+            else {
+                console.log(`✓ ${aid} ${verb}`);
+                console.log('  如需上线 AUN 通道，运行 ec agent new ' + aid);
+            }
         }
         catch (e) {
             if (e.code === 'AID_INVALID') {
-                console.error(`❌ ${e.message}`);
+                if (formatJson)
+                    console.log(JSON.stringify({ ok: false, code: 'AID_INVALID', error: e.message }));
+                else
+                    console.error(`❌ ${e.message}`);
                 process.exit(1);
             }
             if (e.code === -32052 || e.constructor?.name === 'IdentityConflictError') {
-                console.error(`❌ AID ${aid} 已在服务端注册，但本地密钥无法匹配。\n` +
-                    `该 AID 可能由其他设备创建，无法在本地恢复。请选择其他名称。`);
+                const error = `AID ${aid} 已在服务端注册，但本地密钥无法匹配；该 AID 可能由其他设备创建，无法在本地恢复`;
+                if (formatJson)
+                    console.log(JSON.stringify({ ok: false, code: 'IDENTITY_CONFLICT', error }));
+                else
+                    console.error(`❌ ${error}。请选择其他名称。`);
                 process.exit(1);
             }
             throw e;
@@ -249,6 +281,7 @@ Options:
   --yes              跳过 dry-run，立即执行
   --skip-pki         --unrecoverable 时跳过 PKI 探测，仅依据本地 sign+verify 失败判断（危险，可能误删可恢复 AID）
   --format json      输出 JSON 格式
+  --aun-path <path>  指定 AUN keystore 根
 
 示例:
   ec aid delete old.agentid.pub
@@ -279,10 +312,16 @@ Options:
             }
             const deleted = aidDelete(aid, { aunPath });
             if (deleted) {
-                console.log(`✓ ${aid} 已删除`);
+                if (formatJson)
+                    console.log(JSON.stringify({ ok: true, aid, deleted: true }, null, 2));
+                else
+                    console.log(`✓ ${aid} 已删除`);
             }
             else {
-                console.error(`❌ 本地不存在: ${aid}`);
+                if (formatJson)
+                    console.log(JSON.stringify({ ok: false, aid, deleted: false, error: 'not found' }, null, 2));
+                else
+                    console.error(`❌ 本地不存在: ${aid}`);
                 process.exit(1);
             }
             return;
@@ -505,7 +544,7 @@ Options:
 }
 // ==================== RPC ====================
 export async function cmdRpc(args) {
-    if (args.length === 0 || isHelpFlag(args[0])) {
+    if (args.length === 0 || wantsHelp(args)) {
         console.log(`用法: ec rpc --as <aid> --params <params>
 
 通用 AUN RPC 调用。
@@ -520,6 +559,7 @@ export async function cmdRpc(args) {
 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"}}}'
@@ -589,7 +629,7 @@ export async function cmdStorage(args) {
     const sub = args[0];
     const aunPath = resolveAunPath(args);
     const formatJson = getArgValue(args, '--format') === 'json';
-    if (!sub || isHelpFlag(sub)) {
+    if (!sub || wantsHelp(args)) {
         console.log(`用法: ec storage <command> <aid> [options]
 
 Commands:
@@ -601,6 +641,11 @@ Commands:
 
 <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
@@ -741,13 +786,12 @@ export async function cmdMsg(args) {
     const sub = args[0];
     const aunPath = resolveAunPath(args);
     const formatJson = getArgValue(args, '--format') === 'json';
-    const appIdx = args.indexOf('--app');
-    const appSlot = appIdx >= 0 ? args[appIdx + 1] : undefined;
-    if (!sub || isHelpFlag(sub)) {
+    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>                              发送文本
+  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]            发送链接卡片
@@ -761,6 +805,7 @@ Commands:
 Options:
   --text-from-file <path>  从文件读取文本（UTF-8），用于超长消息或避免 Shell 转义
   --app <name>          指定应用 slot（独立消费通道，不影响 daemon）
+  --aun-path <path>     指定 AUN keystore 根
   --format json         输出 JSON 格式
   --encrypt             启用端到端加密（密文发送）
   --no-encrypt          强制明文发送（优先于 --encrypt）
@@ -769,20 +814,23 @@ Options:
   --before <time>       只返回该时间之前的历史
   --after <time>        只返回该时间之后的历史
   --direction <value>   历史方向：in|out|all
-  --return <required|none> 跨会话回流策略（一期仅支持 required；跨会话默认 required）
+  --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"
-  ec msg send alice.agentid.pub bob.agentid.pub --text-from-file long-message.txt
-  ec msg send alice.agentid.pub bob.agentid.pub "讨论项目A" --thread "project-A"
-  ec msg send alice.agentid.pub bob.agentid.pub --file ./pic.png
-  ec msg send alice.agentid.pub bob.agentid.pub --file ./demo.mp4 --as video
-  ec msg send alice.agentid.pub bob.agentid.pub --link https://example.com --title "AUN"
+  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
@@ -1180,20 +1228,21 @@ export async function cmdGroup(args) {
     const sub = args[0];
     const aunPath = resolveAunPath(args);
     const formatJson = getArgValue(args, '--format') === 'json';
-    const appIdx = args.indexOf('--app');
-    const appSlot = appIdx >= 0 ? args[appIdx + 1] : undefined;
-    if (!sub || isHelpFlag(sub) || (args.length === 2 && isHelpFlag(args[1]))) {
+    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>                        发送群文本
+  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]   拉取群消息
   ack <from> <group-id> <seq> [--app <name>]           确认已读
 
 群管理:
-  create <from> <name> [--visibility public|private] [--description D] [--join-mode M]  创建群
+  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] 修改群信息
@@ -1219,19 +1268,25 @@ export async function cmdGroup(args) {
 
 Options:
   --app <name>          指定应用 slot（独立消费通道，不影响 daemon）
+  --aun-path <path>     指定 AUN keystore 根
   --format json         输出 JSON 格式
   --encrypt             启用端到端加密（仅 send）
   --no-encrypt          强制明文发送（优先于 --encrypt；仅 send）
   --thread <id>         指定话题 ID（仅 send）
-  --return <required|none> 跨会话回流策略（仅 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）
   --                    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"
+  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
@@ -1426,10 +1481,8 @@ Options:
         if (!appSlot) {
             console.warn('⚠ 警告: 未传 --app，当前与 daemon 共享 evolcore 消费通道。pull 会看到/影响 daemon 的消息消费；如需独立消费请用 --app <name>');
         }
-        const afterSeqStr = getArgValue(args, '--after-seq');
-        const limitStr = getArgValue(args, '--limit');
-        const afterSeq = afterSeqStr !== undefined ? Number(afterSeqStr) : undefined;
-        const limit = limitStr !== undefined ? Number(limitStr) : undefined;
+        const afterSeq = parseNumberFlag('--after-seq', '--after-seq');
+        const limit = parseNumberFlag('--limit', '--limit');
         const result = await groupPull({ from, groupId, afterSeq, limit, ...commonOpts });
         outputResult(result, () => {
             const r = result;
@@ -1475,12 +1528,17 @@ Options:
             console.error(`❌ --visibility 必须是 public 或 private`);
             process.exit(1);
         }
+        const joinMode = getArgValue(args, '--join-mode');
+        if (joinMode && !['open', 'approval', 'invite_only', 'closed'].includes(joinMode)) {
+            console.error('❌ --join-mode 必须是 open|approval|invite_only|closed');
+            process.exit(1);
+        }
         const result = await groupCreate({
             from,
             name,
             visibility,
             description: getArgValue(args, '--description'),
-            joinMode: getArgValue(args, '--join-mode'),
+            joinMode: joinMode,
             groupId: getArgValue(args, '--group-id'),
             ...commonOpts,
         });
@@ -1493,8 +1551,7 @@ Options:
         return;
     }
     if (sub === 'list') {
-        const sizeStr = getArgValue(args, '--size');
-        const size = sizeStr !== undefined ? Number(sizeStr) : undefined;
+        const size = parseNumberFlag('--size', '--size');
         const result = await groupList({ from, size, ...commonOpts });
         outputResult(result, () => {
             const r = result;
@@ -1755,12 +1812,10 @@ Options:
     }
     if (sub === 'members') {
         const groupId = requireGroupId();
-        const pageStr = getArgValue(args, '--page');
-        const sizeStr = getArgValue(args, '--size');
         const result = await groupMembers({
             from, groupId,
-            page: pageStr !== undefined ? Number(pageStr) : undefined,
-            size: sizeStr !== undefined ? Number(sizeStr) : undefined,
+            page: parseNumberFlag('--page', '--page'),
+            size: parseNumberFlag('--size', '--size'),
             ...commonOpts,
         });
         outputResult(result, () => {

package/dist/cli/bench.js

@@ -9,7 +9,7 @@ import { resolveControlIssuer } from '../aun/aid/control-aid.js';
 import { msgSend, msgPull } from '../aun/msg/index.js';
 import { getPackageRoot, aunPath as defaultAunPath } from '../paths.js';
 import { getAidStore, loadClient, SLOT } from '../aun/aid/store.js';
-import { isHelpFlag, getArgValue } from './help.js';
+import { isHelpFlag, wantsHelp, getArgValue } from './help.js';
 const execFileAsync = promisify(execFile);
 // ==================== ANSI ====================
 const GREEN = '\x1b[32m';
@@ -370,7 +370,7 @@ async function cliAuth(aid, slotId) {
 }
 // ==================== Main Command ====================
 export async function cmdBench(args) {
-    if (isHelpFlag(args[0])) {
+    if (isHelpFlag(args[0]) || wantsHelp(args)) {
         console.log(`用法: ec bench [options]
 
 AUN 消息系统性能基准测试。使用多个本地 AID 并发互发消息，

package/dist/cli/contact.js

@@ -0,0 +1,71 @@
+import { resolvePaths } from '../paths.js';
+import { executeResolvedContactCommand, resolveContactCommand, } from '../config/contact-operation-service.js';
+import { ipcQuery } from '../ipc.js';
+import { AGENT_DELEGATION_TOKEN_ENV } from '../core/auth/agent-delegation.js';
+import { getArgValue, isHelpFlag, wantsHelp } from './help.js';
+export async function cmdContact(args) {
+    if (args.length === 0 || isHelpFlag(args[0]) || wantsHelp(args)) {
+        printHelp();
+        return;
+    }
+    const json = getArgValue(args, '--format') === 'json';
+    if (process.env.EVOLCORE_SESSION_ID) {
+        const result = await runManaged(args, json);
+        output(result, json);
+        return;
+    }
+    const resolved = resolveContactCommand(args);
+    if (!resolved.ok)
+        fail(resolved.reason, resolved.code);
+    const result = await executeResolvedContactCommand(resolved.command);
+    if (!result.ok)
+        fail(result.error, result.code, result.data);
+    output(result, json);
+}
+function output(value, json) {
+    if (json)
+        console.log(JSON.stringify(value));
+    else
+        console.log(JSON.stringify(value, null, 2));
+}
+async function runManaged(args, json) {
+    const sessionId = process.env.EVOLCORE_SESSION_ID;
+    const delegationToken = process.env[AGENT_DELEGATION_TOKEN_ENV];
+    if (!delegationToken)
+        fail(`${AGENT_DELEGATION_TOKEN_ENV} is not set for the active task`, 'DELEGATION_REQUIRED');
+    let response = null;
+    try {
+        response = await ipcQuery(resolvePaths().socket, {
+            type: 'contact.op',
+            argv: ['contact', ...args],
+            sessionId,
+            delegationToken,
+        }, 10_000);
+    }
+    catch { }
+    if (!response)
+        fail('Unable to connect to the evolcore daemon', 'DAEMON_UNAVAILABLE');
+    if (!response.ok || !response.result) {
+        fail(response.error || 'contact operation failed', response.code || 'CONTACT_AUTH_FAILED', response.data);
+    }
+    return response.result;
+}
+function fail(message, code = 'INVALID_ARGUMENT', data) {
+    const error = new Error(message);
+    error.code = code;
+    if (data !== undefined)
+        error.data = data;
+    throw error;
+}
+function printHelp() {
+    console.log(`Usage:
+  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

@@ -1,6 +1,6 @@
 import { resolvePaths } from '../paths.js';
 import { ipcQuery } from '../ipc.js';
-import { isHelpFlag } from './help.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...]
@@ -30,7 +30,7 @@ export async function cmdCtl(args) {
         process.exit(1);
     }
     // help 不需要连接服务。
-    if (isHelpFlag(args[0])) {
+    if (isHelpFlag(args[0]) || wantsHelp(args)) {
         console.log(CTL_HELP);
         return;
     }