evolclaw 3.1.2 → 3.1.4

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## v3.1.4 (2026-05-27)
+
+### New Features
+
+- **CLI help 系统重构 + ECK 注入** — 全新 help 子命令体系，ECK（EvolClaw Kit）注入机制重构，AID identity 管理命令
+- **Menu 协议五动词拆分** — menu 协议拆分为 list/query/options/update/action 五个动词，命令收敛至 baseagent/session
+
+### Improvements
+
+- **npm-ops 去 CLI 依赖** — checkLatestVersion 改用 HTTP fetch 直接查 registry API，去除对 npm CLI 的运行时依赖
+- **agent.md 适配 SDK 0.3.3** — 统一 aun_path 到 EVOLCLAW_HOME，适配最新 SDK 版本
+
+### Bug Fixes
+
+- **Session channelType 缺失修复** — 修复 channelType 缺失导致 chat dir 无法解析 + isBackgroundSession 同步化
+- **SessionManager 查询路径 NPE** — 修复缺失 channelType 时的空指针异常
+
+## v3.1.3 (2026-05-26)
+
+### New Features
+
+- **Menu 协议拆分为 5 动词** — `menu.list` / `menu.query` / `menu.options` / `menu.update` / `menu.action`，response 统一 `error.code` 透传（`NO_ACTIVE_SESSION` / `MISSING_VALUE` / ...），`name → cmd` 由 bridge 内部映射，AUN 白名单接纳全部 `menu.*` 类型
+- **xhigh effort 档位** — Claude/Codex 新增 `xhigh` 推理强度档位，Codex 通过 `codex debug models` 动态拉取模型目录与各模型支持的 effort 列表
+- **结构化 menu options 字段** — session 子菜单返回 `preview`（首条消息预览）/ `lastActive` / `agentSessionId` / `turns` 扩展字段，所有可选项菜单返回 `selected` 标记当前值
+
+### Improvements
+
+- **命令收敛** — 移除 `/plist` `/project` `/bind` `/agentmd` `/p` 别名；`/agent` 改为 EvolAgent 管理命令；baseagent 切换统一为 `/baseagent`（别名 `/base`）；`/aid` `/rpc` `/storage` `/evolagent` 改为 ctl 专属
+- **execMenu 拆分** — `command-handler` 拆出 `execMenuQuery` / `execMenuUpdate` / `execMenuAction` 三入口，无活跃会话时多项 fallback 到 evolagent config（`/pwd` / `/chatmode` / `/dispatch` 等）
+- **EvolAgent 持久化方法** — 新增 `setActiveBaseagent` / `setChatmodePrivate` / `setDispatch`，配置变更直接落盘
+- **Codex 实例每次重建** — 通过 env 注入 `EVOLCLAW_SESSION_ID`，仅首轮拼接 `systemPromptAppend`，避免 resume 时重复污染历史
+- **Agent plugin 启用判定** — `isEnabled` 改为按 `baseagents.<name>` 配置启用，Codex 额外检测 `@openai/codex-sdk` 是否可用，`init` / `agent new` CLI 同步该判定
+- **context-too-long 提示文案** — 按 agent 是否支持 compact 区分提示，retry 后仍超长时清理 renderer 中混入的错误文本（新增 `IMRenderer.stripContextError`）
+
+### Bug Fixes
+
+- **Codex resume 历史污染** — systemPromptAppend 在 resume 轮次重复拼接到 prompt 头部，导致系统提示被反复写入对话历史
+
 ## v3.1.2 (2026-05-25)
 
 ### Improvements

package/README.md

@@ -243,14 +243,11 @@ evolclaw/
 
 ### 管理员级命令（Admin+ 可用）
 
-**项目管理**：
+**项目**：
 - `/pwd` - 显示当前项目路径
-- `/plist` - 列出所有项目（显示会话空闲时间）
-- `/p <name|path>` - 切换项目（保留会话历史）
-- `/bind <path>` - 绑定新项目目录
 
 **Agent 与模型**：
-- `/agent [name]` - 查看或切换 Agent 后端（claude / codex / gemini）
+- `/baseagent [name]` - 查看或切换 Agent 后端（claude / codex / gemini）（别名 `/base`）
 - `/model [model]` - 查看或切换模型
 - `/effort [level]` - 查看或切换推理强度（low / medium / high / max / auto）
 - `/perm [mode]` - 查看或切换权限模式（auto / edit / default / readonly）
@@ -272,7 +269,6 @@ evolclaw/
 - `/file <文件路径>` - 发送文件给用户
 - `/restart` - 重启服务（自愈机制）
 - `/repair` - 检查并修复会话
-- `/agentmd [put|set]` - 管理 AUN agent.md（仅 AUN 渠道）
 
 ## 技术栈
 

package/assets/.env.template

@@ -0,0 +1,4 @@
+# AUN 环境变量
+# 取消注释并填入值即可生效（进程已有的同名变量不会被覆盖）
+
+# AUN_ENCRYPTION_SEED=your-seed-here

package/assets/config.json.template

@@ -0,0 +1,6 @@
+{
+  "$schema_version": 1,
+  "aun": {
+    "encryptionSeed": null
+  }
+}

package/dist/agents/claude-runner.js

@@ -1094,7 +1094,7 @@ export class AgentRunner {
 export class ClaudeAgentPlugin {
     name = 'claude';
     isEnabled(agent) {
-        return agent.baseagent === 'claude';
+        return !!agent.config.baseagents?.claude;
     }
     createAgent(agent, callbacks) {
         const override = agent.config.baseagents?.claude;

package/dist/agents/codex-runner.js

@@ -7,6 +7,7 @@
  */
 import { resolveOpenaiConfig } from './resolve.js';
 import { logger } from '../utils/logger.js';
+import { execFileSync } from 'child_process';
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
@@ -17,13 +18,58 @@ const MIME_EXT = {
     'image/gif': '.gif',
     'image/webp': '.webp',
 };
-// ── Codex 模型列表 ──
-const CODEX_MODELS = ['gpt-5.3-codex', 'gpt-5.2-codex', 'gpt-5-codex', 'gpt-5.2', 'gpt-5.4'];
+const CODEX_CATALOG_FALLBACK = [
+    { slug: 'gpt-5.5', efforts: ['low', 'medium', 'high', 'xhigh'] },
+    { slug: 'gpt-5.4', efforts: ['low', 'medium', 'high', 'xhigh'] },
+    { slug: 'gpt-5.4-mini', efforts: ['low', 'medium', 'high', 'xhigh'] },
+    { slug: 'gpt-5.3-codex', efforts: ['low', 'medium', 'high', 'xhigh'] },
+    { slug: 'gpt-5.2', efforts: ['low', 'medium', 'high', 'xhigh'] },
+];
+let codexCatalogCache = null;
+export function isCodexSdkAvailable() {
+    try {
+        import.meta.resolve('@openai/codex-sdk');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function fetchCodexCatalog() {
+    if (codexCatalogCache)
+        return codexCatalogCache;
+    try {
+        const output = execFileSync('codex', ['debug', 'models'], {
+            encoding: 'utf-8',
+            timeout: 5000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const catalog = JSON.parse(output);
+        const models = catalog.models
+            .filter(m => m.visibility === 'list')
+            .map(m => ({
+            slug: m.slug,
+            efforts: (m.supported_reasoning_levels || []).map(l => l.effort),
+        }));
+        if (models.length > 0) {
+            codexCatalogCache = models;
+            return models;
+        }
+    }
+    catch (e) {
+        logger.debug(`[CodexRunner] Failed to fetch model catalog, using fallback: ${e}`);
+    }
+    return CODEX_CATALOG_FALLBACK;
+}
+export function getCodexEfforts(model) {
+    const catalog = fetchCodexCatalog();
+    const entry = catalog.find(m => m.slug === model);
+    return entry?.efforts ?? catalog[0]?.efforts ?? ['low', 'medium', 'high'];
+}
 // ── Codex Runner ──
 export class CodexRunner {
     name = 'codex';
     capabilities = { clear: false, compact: false, fork: false };
-    codex = null;
     codexModule = null;
     model;
     effort;
@@ -39,21 +85,25 @@ export class CodexRunner {
             this.effort = this.resolvedConfig.effort;
         this.onSessionIdUpdate = callbacks.onSessionIdUpdate;
     }
-    async ensureCodex() {
-        if (!this.codex || !this.codexModule) {
+    async ensureCodex(sessionId) {
+        if (!this.codexModule) {
             const { requireOptional } = await import('../utils/npm-ops.js');
             this.codexModule = await requireOptional('@openai/codex-sdk');
-            this.codex = new this.codexModule.Codex({
-                apiKey: this.resolvedConfig.apiKey,
-                baseUrl: this.resolvedConfig.baseUrl,
-            });
         }
-        return { codex: this.codex, mod: this.codexModule };
+        const codex = new this.codexModule.Codex({
+            apiKey: this.resolvedConfig.apiKey,
+            baseUrl: this.resolvedConfig.baseUrl,
+            env: {
+                ...process.env,
+                EVOLCLAW_SESSION_ID: sessionId,
+            },
+        });
+        return { codex, mod: this.codexModule };
     }
     // ── ModelSwitcher ──
     setModel(model) { this.model = model; }
     getModel() { return this.model; }
-    listModels() { return CODEX_MODELS; }
+    listModels() { return fetchCodexCatalog().map(m => m.slug); }
     // ── Effort ──
     setEffort(effort) { this.effort = effort; }
     getEffort() { return this.effort; }
@@ -94,10 +144,14 @@ export class CodexRunner {
     }
     // ── Core: runQuery ──
     async runQuery(sessionId, prompt, projectPath, initialAgentSessionId, images, systemPromptAppend, sessionManager) {
-        // Agent ctl: 注入 EVOLCLAW_SESSION_ID 供子进程使用
-        process.env.EVOLCLAW_SESSION_ID = sessionId;
-        const { codex } = await this.ensureCodex();
+        const { codex } = await this.ensureCodex(sessionId);
         let agentSessionId = initialAgentSessionId || this.activeSessions.get(sessionId);
+        let fullPrompt = prompt;
+        // Only inject system context on the first turn; resumed Codex threads already
+        // have that context in history and repeating it will pollute the conversation.
+        if (systemPromptAppend && !agentSessionId) {
+            fullPrompt = prompt + '\n\n--- [SYSTEM_PROMPT_END] ---\n' + systemPromptAppend;
+        }
         const threadOptions = {
             workingDirectory: projectPath,
             model: this.model,
@@ -116,7 +170,7 @@ export class CodexRunner {
         let input;
         if (images?.length) {
             const tmpDir = os.tmpdir();
-            const parts = [{ type: 'text', text: prompt }];
+            const parts = [{ type: 'text', text: fullPrompt }];
             for (let i = 0; i < images.length; i++) {
                 const img = images[i];
                 const ext = MIME_EXT[img.mimeType || ''] || '.jpg';
@@ -129,7 +183,7 @@ export class CodexRunner {
             logger.info(`[CodexRunner] Attached ${images.length} image(s) as local_image`);
         }
         else {
-            input = prompt;
+            input = fullPrompt;
         }
         const { events } = await thread.runStreamed(input, { signal: controller.signal });
         // 包装为 AgentEvent 流
@@ -302,10 +356,10 @@ export class CodexRunner {
 export class CodexAgentPlugin {
     name = 'codex';
     isEnabled(agent) {
-        if (agent.baseagent !== 'codex')
-            return false;
         if (!agent.config.baseagents?.codex)
             return false;
+        if (!isCodexSdkAvailable())
+            return false;
         try {
             const override = agent.config.baseagents.codex;
             const syntheticConfig = { agents: { codex: override } };
@@ -317,8 +371,10 @@ export class CodexAgentPlugin {
         }
     }
     createAgent(agent, callbacks) {
+        if (!isCodexSdkAvailable()) {
+            throw new Error('Missing optional dependency @openai/codex-sdk');
+        }
         const override = agent.config.baseagents?.codex;
-        const syntheticConfig = { agents: { codex: override } };
         const merged = {
             agents: { codex: { ...(override || {}) } },
         };

package/dist/agents/gemini-runner.js

@@ -407,8 +407,6 @@ export class GeminiRunner {
 export class GeminiAgentPlugin {
     name = 'gemini';
     isEnabled(agent) {
-        if (agent.baseagent !== 'gemini')
-            return false;
         const geminiCfg = agent.config.baseagents?.gemini;
         if (!geminiCfg)
             return false;

package/dist/agents/kit-renderer.js

@@ -1,6 +1,6 @@
 import fs from 'fs';
 import path from 'path';
-import { kitsDir, eckDebugDir, resolveRoot } from '../paths.js';
+import { kitsDir, eckDebugDir, resolveRoot, getPackageRoot } from '../paths.js';
 import { logger } from '../utils/logger.js';
 // ── Param descriptions (for debug output) ──
 const PARAM_DESCRIPTIONS = {
@@ -14,21 +14,60 @@ const PARAM_DESCRIPTIONS = {
     peerId: '对端在该渠道的原生 ID',
     peerKey: '对端跨渠道唯一标识（channel#urlEncode(peerId)）',
     peerName: '对端显示名',
-    peerRole: '对端角色',
+    peerRole: '对端角色（owner/admin/guest/anonymous）',
+    peerType: '对端类型（human/agent）',
     groupId: '群组 ID（群聊时）',
-    scene: '场景类型',
-    chatType: '聊天类型',
-    channel: '当前渠道',
-    venueUid: 'venue 唯一标识',
-    project: '当前项目目录名（由 CURRENT_PROJECT 派生）',
+    chatType: '聊天类型（private=私聊 / group=群聊 / null=本地开发）',
+    channel: '渠道类型（aun/feishu/wechat/dingtalk/qqbot/wecom）',
+    venueUid: '场所唯一标识（预留）',
+    capabilities: '当前渠道支持的能力列表',
+    project: '当前项目目录名',
+    sessionId: 'evolclaw 会话 ID',
     sessionName: '会话名称',
-    sessionMode: '会话模式',
+    sessionCreatedAt: '会话创建时间（ISO）',
+    threadId: '话题 ID（多话题路由时）',
+    chatMode: '会话模式（interactive=同步交互 / proactive=主动推送）',
     readonly: '是否只读模式',
-    canSendFile: '当前渠道是否支持发文件',
-    capabilities: '渠道能力列表',
-    baseAgent: '当前 base agent 规范值（claude/codex/gemini/hermes）',
-    baseAgentName: '当前 base agent 显示名',
+    baseAgent: 'base agent 规范值（claude/codex/gemini/hermes）',
+    baseAgentName: 'base agent 显示名',
+    baseAgentModel: 'base agent 使用的模型',
+    agentSessionId: 'base agent 会话 ID',
 };
+function buildPathMappings(vars) {
+    const pkgRoot = getPackageRoot();
+    const evolHome = String(vars['EVOLCLAW_HOME'] || resolveRoot());
+    const selfAid = vars['selfAid'] ? String(vars['selfAid']) : '';
+    const currentProject = vars['CURRENT_PROJECT'] ? String(vars['CURRENT_PROJECT']) : '';
+    const mappings = [
+        { prefix: path.join(pkgRoot, 'kits', 'rules'), alias: '$KITS_RULES' },
+        { prefix: path.join(pkgRoot, 'kits', 'templates', 'system-fragments'), alias: '$KITS_FRAGMENTS' },
+        { prefix: path.join(pkgRoot, 'kits', 'templates'), alias: '$KITS_TEMPLATES' },
+        { prefix: path.join(pkgRoot, 'kits', 'docs'), alias: '$KITS_DOCS' },
+        { prefix: path.join(pkgRoot, 'kits'), alias: '$KITS' },
+        { prefix: pkgRoot, alias: '$PACKAGE_ROOT' },
+    ];
+    if (selfAid) {
+        mappings.push({ prefix: path.join(evolHome, 'agents', selfAid), alias: '$AGENT_DIR' });
+    }
+    mappings.push({ prefix: evolHome, alias: '$EVOLCLAW_HOME' });
+    if (currentProject) {
+        mappings.push({ prefix: currentProject, alias: '$CURRENT_PROJECT' });
+    }
+    // Sort by prefix length descending so longer (more specific) paths match first
+    mappings.sort((a, b) => b.prefix.length - a.prefix.length);
+    return mappings;
+}
+function shortenPath(filePath, mappings) {
+    const normalized = filePath.replace(/\\/g, '/');
+    for (const { prefix, alias } of mappings) {
+        const normalizedPrefix = prefix.replace(/\\/g, '/');
+        if (normalized.startsWith(normalizedPrefix)) {
+            const rest = normalized.slice(normalizedPrefix.length);
+            return alias + rest;
+        }
+    }
+    return filePath;
+}
 // ── Cache ──
 let _manifestCache = null;
 const _sessionPathCache = new Map();
@@ -49,6 +88,8 @@ export function renderKitSections(ctx) {
         loadKitManifest();
     const sections = _manifestCache;
     const fileParts = [];
+    const fragmentParts = [];
+    const pathMappings = buildPathMappings(ctx.vars);
     for (const section of sections) {
         if (section.enabled === false)
             continue;
@@ -62,14 +103,20 @@ export function renderKitSections(ctx) {
             if (!content.trim())
                 continue;
             const label = section.description ? `${section.id} — ${section.description}` : section.id;
-            fileParts.push(`Contenu de ${filePath} (${label}):\n\n${content.trimEnd()}`);
+            const displayPath = shortenPath(filePath, pathMappings);
+            const part = `Contenu de ${displayPath} (${label}):\n\n${content.trimEnd()}`;
+            fileParts.push(part);
+            if (section.needsInjection) {
+                fragmentParts.push(part);
+            }
         }
     }
     if (fileParts.length === 0)
         return '';
     const body = fileParts.join('\n\n');
     const output = `<system-reminder>\nEvolClaw Context Kit documents are shown below.\n\n${body}\n\nIMPORTANT: Use this context when it affects the current interaction.\n</system-reminder>`;
-    writeDebugFiles(ctx, output);
+    const fragmentsOutput = fragmentParts.length > 0 ? fragmentParts.join('\n\n') : '';
+    writeDebugFiles(ctx, output, fragmentsOutput);
     return output;
 }
 export function cleanEckDebug() {
@@ -233,14 +280,27 @@ function isTruthy(val) {
 }
 // CHUNK_CONTINUE_6
 // ── Template rendering ──
+function resolveConditions(template, vars) {
+    // Find innermost {{?...}}...{{/}} block (no nested {{? inside) and resolve it.
+    // Repeat until no blocks remain.
+    const inner = /\{\{\?(\w+)(?:(!=|=)([^}]*))?\}\}([^]*?)\{\{\/\}\}/;
+    let result = template;
+    let prev;
+    do {
+        prev = result;
+        result = result.replace(inner, (_match, key, op, value, body) => {
+            if (op === '=')
+                return String(vars[key]) === value ? body : '';
+            if (op === '!=')
+                return String(vars[key]) !== value ? body : '';
+            return isTruthy(vars[key]) ? body : '';
+        });
+    } while (result !== prev);
+    return result;
+}
 function renderTemplate(template, vars) {
-    // Pass 1: conditional sections {{?key=value}}...{{/}} and {{?key}}...{{/}}
-    let result = template.replace(/\{\{\?(\w+)(?:=([^}]*))?\}\}([\s\S]*?)\{\{\/\}\}/g, (_match, key, value, body) => {
-        if (value !== undefined) {
-            return String(vars[key]) === value ? body : '';
-        }
-        return isTruthy(vars[key]) ? body : '';
-    });
+    // Pass 1: resolve nested conditionals inside-out
+    let result = resolveConditions(template, vars);
     // Pass 2: variable substitution {{key}}
     result = result.replace(/\{\{(\w+)\}\}/g, (_match, key) => {
         const val = vars[key];
@@ -261,7 +321,7 @@ function getSessionCache(sessionId) {
     return cache;
 }
 // ── Debug output ──
-function writeDebugFiles(ctx, output) {
+function writeDebugFiles(ctx, output, fragmentsOutput) {
     const now = new Date();
     const ts = now.toISOString().replace(/[T:.]/g, '-').slice(0, 19);
     const dir = eckDebugDir();
@@ -278,4 +338,7 @@ function writeDebugFiles(ctx, output) {
     };
     fs.writeFile(path.join(dir, `vars-${ts}.json`), JSON.stringify(varsData, null, 2), () => { });
     fs.writeFile(path.join(dir, `context-${ts}.md`), output, () => { });
+    if (fragmentsOutput) {
+        fs.writeFile(path.join(dir, `fragments-${ts}.md`), fragmentsOutput, () => { });
+    }
 }

package/dist/aun/aid/agentmd.js

@@ -1,8 +1,7 @@
 import fs from 'fs';
 import path from 'path';
-import os from 'os';
-import { getAunClient } from './client.js';
-import { agentMdPath, aidLocalDir } from '../../paths.js';
+import { getAunClient, createAunClient } from './client.js';
+import { agentMdPath, aidLocalDir, resolveRoot } from '../../paths.js';
 export function buildInitialAgentMd(opts) {
     const agentName = opts.aid.split('.')[0];
     const agentType = opts.type || 'ai';
@@ -83,71 +82,37 @@ async function verifyContent(content, aid, certPem, client) {
  * Create a bare AUNClient (no createAid) for read-only operations.
  */
 async function createBareClient(aunPath) {
-    const { AUNClient } = await import('@agentunion/fastaun');
-    const caCertPath = path.join(aunPath, 'CA', 'root', 'root.crt');
-    const clientOpts = { aun_path: aunPath, debug: false };
-    if (fs.existsSync(caCertPath))
-        clientOpts.root_ca_path = caCertPath;
-    return new AUNClient(clientOpts);
+    return createAunClient({ aunPath });
 }
 export async function agentmdGet(aid, opts) {
-    const aunPath = opts?.aunPath ?? path.join(os.homedir(), '.aun');
-    const localPath = agentMdPath(aid);
-    // === Path A: local agent.md exists ===
-    if (fs.existsSync(localPath)) {
-        const content = fs.readFileSync(localPath, 'utf-8');
-        if (!opts?.withVerification)
-            return content;
-        // Verify local content
-        const client = opts?.client ?? await createBareClient(aunPath);
-        const ownClient = !opts?.client;
-        try {
-            const certPem = await obtainCertPem(aid, aunPath, client);
-            const verification = await verifyContent(content, aid, certPem, client);
-            if (verification.status !== 'invalid') {
-                return { content, verification };
-            }
-            // Fallback: local invalid → try remote
-            try {
-                const remote = await client.auth.downloadAgentMd(aid);
-                if (remote) {
-                    const remoteVerification = await verifyContent(remote, aid, certPem, client);
-                    if (remoteVerification.status === 'verified') {
-                        fs.writeFileSync(localPath, remote, 'utf-8');
-                        return { content: remote, verification: remoteVerification };
-                    }
-                }
-            }
-            catch { /* remote fetch failed, return local invalid result */ }
-            return { content, verification };
-        }
-        finally {
-            if (ownClient)
-                try {
-                    await client.close();
-                }
-                catch { /* ignore */ }
-        }
-    }
-    // === Path B: no local agent.md → download from remote ===
+    const aunPath = opts?.aunPath ?? resolveRoot();
     const client = opts?.client ?? await createBareClient(aunPath);
     const ownClient = !opts?.client;
+    const localPath = agentMdPath(aid);
     try {
-        const raw = await client.auth.downloadAgentMd(aid);
-        if (!opts?.withVerification) {
-            // Persist without verification
-            const aidDir = aidLocalDir(aid);
-            fs.mkdirSync(aidDir, { recursive: true });
-            fs.writeFileSync(path.join(aidDir, 'agent.md'), raw, 'utf-8');
-            return raw;
+        // Try SDK fetch (auto-saves locally + verifies signature)
+        let content;
+        let verification;
+        try {
+            const info = await client.fetchAgentMd(aid);
+            content = info.content;
+            const sig = info.signature ?? {};
+            const status = sig.status === 'verified' ? 'verified' : sig.status === 'unsigned' ? 'unsigned' : 'invalid';
+            verification = { status, ...(sig.reason ? { reason: String(sig.reason) } : {}) };
+        }
+        catch (err) {
+            // Network failed — fall back to local file (verify signature via SDK if requested)
+            if (!fs.existsSync(localPath))
+                throw err;
+            content = fs.readFileSync(localPath, 'utf-8');
+            if (opts?.withVerification) {
+                const certPem = await obtainCertPem(aid, aunPath, client);
+                verification = await verifyContent(content, aid, certPem, client);
+            }
         }
-        const certPem = await obtainCertPem(aid, aunPath, client);
-        const verification = await verifyContent(raw, aid, certPem, client);
-        // Persist to local
-        const aidDir = aidLocalDir(aid);
-        fs.mkdirSync(aidDir, { recursive: true });
-        fs.writeFileSync(path.join(aidDir, 'agent.md'), raw, 'utf-8');
-        return { content: raw, verification };
+        if (!opts?.withVerification)
+            return content;
+        return { content: content, verification: verification ?? { status: 'unsigned' } };
     }
     finally {
         if (ownClient)
@@ -158,24 +123,52 @@ export async function agentmdGet(aid, opts) {
     }
 }
 /**
- * Upload agent.md: auto-sign + upload + sync to local file.
+ * Upload agent.md: write to local file → publishAgentMd (auto-sign + upload).
  */
 export async function agentmdPut(content, opts) {
-    const aunPath = opts.aunPath ?? path.join(os.homedir(), '.aun');
+    const aunPath = opts.aunPath ?? resolveRoot();
     const client = opts.client ?? await getAunClient(opts.aid, { aunPath });
     const ownClient = !opts.client;
+    const dir = aidLocalDir(opts.aid);
+    const filePath = path.join(dir, 'agent.md');
+    const existed = fs.existsSync(filePath);
     try {
-        let signed;
-        try {
-            signed = await client.auth.signAgentMd(content);
-        }
-        catch {
-            signed = content;
-        }
-        await client.auth.uploadAgentMd(signed);
-        const dir = aidLocalDir(opts.aid);
         fs.mkdirSync(dir, { recursive: true });
-        fs.writeFileSync(path.join(dir, 'agent.md'), signed, 'utf-8');
+        fs.writeFileSync(filePath, content, 'utf-8');
+        await client.publishAgentMd();
+    }
+    catch (e) {
+        if (!existed)
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch { /* ignore */ }
+        throw e;
+    }
+    finally {
+        if (ownClient)
+            try {
+                await client.close();
+            }
+            catch { /* ignore */ }
+    }
+}
+/**
+ * Check if agent.md is up-to-date (30-day cache), fetch if changed.
+ * Returns changed=true + content when a new version was downloaded.
+ */
+export async function agentmdSync(aid, opts) {
+    const client = opts?.client ?? await createBareClient();
+    const ownClient = !opts?.client;
+    try {
+        const state = await client.checkAgentMd(aid, 30);
+        if (!state.in_sync || !state.local_found) {
+            const info = await client.fetchAgentMd(aid);
+            return { changed: true, content: info.content };
+        }
+        const localPath = agentMdPath(aid);
+        const content = fs.existsSync(localPath) ? fs.readFileSync(localPath, 'utf-8') : undefined;
+        return { changed: false, content };
     }
     finally {
         if (ownClient)

package/dist/aun/aid/client.js

@@ -1,6 +1,5 @@
 import fs from 'fs';
 import path from 'path';
-import os from 'os';
 import { fileURLToPath } from 'url';
 import { execFileSync } from 'child_process';
 import { isWindows } from '../../utils/cross-platform.js';
@@ -25,7 +24,7 @@ export function suppressSdkLogs() {
         return; process.stderr.write(args.map(String).join(' ') + '\n'); };
 }
 // ==================== Constants ====================
-export const MIN_AUN_CORE_SDK = [0, 2, 17];
+export const MIN_AUN_CORE_SDK = [0, 3, 3];
 export const AUN_CORE_SDK_PKG = '@agentunion/fastaun';
 // ==================== SDK & Environment ====================
 function compareVersion(a, min) {
@@ -114,15 +113,31 @@ export async function downloadCaRoot(aunPath, gatewayUrl, indent = '') {
         return false;
     }
 }
-// ==================== AUNClient Factory ====================
-export async function getAunClient(aid, opts) {
-    const aunPath = opts?.aunPath ?? path.join(os.homedir(), '.aun');
+/**
+ * 统一构造 AUNClient：自动绑 root_ca_path + setAgentMdPath(aidsDir())。
+ * 不做 createAid / authenticate / connect，调用方按需续作。
+ *
+ * 所有 new AUNClient 调用都应走此工厂，避免 SDK 默认把 agent.md 写到
+ * {aun_path}/AgentMDs（默认目录）。
+ */
+export async function createAunClient(opts = {}) {
+    const { aunPath: defaultAunPath, aidsDir } = await import('../../paths.js');
+    const aunPath = opts.aunPath ?? defaultAunPath();
     const caCertPath = path.join(aunPath, 'CA', 'root', 'root.crt');
     const { AUNClient } = await import('@agentunion/fastaun');
-    const clientOpts = { aun_path: aunPath, debug: false };
+    const clientOpts = { aun_path: aunPath, debug: opts.debug ?? false };
     if (fs.existsSync(caCertPath))
         clientOpts.root_ca_path = caCertPath;
-    const client = new AUNClient(clientOpts);
+    if (opts.encryptionSeed)
+        clientOpts.encryption_seed = opts.encryptionSeed;
+    const client = opts.aunSdkLog !== undefined
+        ? new AUNClient(clientOpts, opts.aunSdkLog)
+        : new AUNClient(clientOpts);
+    client.setAgentMdPath(aidsDir());
+    return client;
+}
+export async function getAunClient(aid, opts) {
+    const client = await createAunClient({ aunPath: opts?.aunPath });
     await client.auth.createAid({ aid });
     return client;
 }