evolclaw 3.1.11 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## v3.2.0 (2026-06-05)
+
+### New Features
+
+- **控制 AID（control AID）** — 进程级控制身份，启动时以 `pureIdentity` 模式连接 AUN（跳过 evolagent onboarding）。生成采用 `ec+5位数字` 候选 + PKI 权威查重 + fail-fast；缺失时进入 init（TTY 守卫，headless 仅告警）。`evolclaw status` 新增控制 AID 连接状态展示
+- **Menu 协议 / agent 控制面** — `/system`、`/agent` 迁移到 owners 鉴权；trigger 接入菜单协议（直连 manager/scheduler，无文本拼装）；agent 创建支持 accepted-return + 构建进度（`create-status.json` + `onPhase` 回调 + model/chatmode）；新增 agent query/options 与 project 兜底
+- **进程级 owners 配置层** — 新增 `evolclaw.json` 进程级配置，`config.json` 合并入 `evolclaw.json`（弃用 `ProcessConfig`）；process-level owners 从 `defaults.json` 迁移到 `evolclaw.json`；新增 `isProcessLevelOwner` 鉴权辅助
+- **Observer 模式重构** — AUN owner 间消息互转发；`evolclaw init aun` 简化为 owner-only 配置；`mergeForAgent` 输出补全 `dispatch`/`observable`
+
+### Improvements
+
+- **统一 FileCache** — 新增 mtime-gated 统一文件缓存，迁移 relation prefs、manifest+fragment、persona/working 读取与 model-scope 缓存；新增 Cache watch 视图监控缓存命中
+- **消息信封渲染补全** — @AID 列表与群名补全，修复 proximity 信息丢失
+- **Idle 监控解耦** — idle notify/warn 改为事件总线发布（`runner:idle-notify`/`runner:idle-warn`，携带 idleSec/事件数/工具名），与通道发送解耦；超时诊断信息下沉到事件 payload
+
+### Bug Fixes
+
+- **多 agent 群广播去重** — 消息队列改按 `sessionKey:messageId` 去重，允许同一消息广播给多个 agent
+- **AUN owner 入站转发** — owner 来源的入站消息正确转发给其它 owners
+- **单 agent reload 缓存失效** — reload 时失效 identity 层缓存
+- **CLI /slist 过滤** — 过滤掉程序化 SDK session，不在 `/slist` 显示
+- **控制 AID 查重走 GET** — 改用 `store.resolve`（GET）替代 `store.exists`（HEAD），规避部分 Gateway 对 HEAD 空响应断连导致的误判
+- **启动门控修复** — gate 直接调 `initTail` 而非完整 `cmdInit`；AID 生成失败时跳过 owners 提示；抑制控制 AID gate 路径的 SDK keystore 日志
+
 ## v3.1.11 (2026-06-04)
 
 ### Improvements

package/README.md

@@ -267,6 +267,32 @@ evolclaw/
 - `/restart` - 重启服务（自愈机制）
 - `/repair` - 检查并修复会话
 
+### ⚠️ 进程级 menu 操作鉴权（v3.2 Breaking）
+
+进程级 menu 操作（`/system restart/upgrade`、`/agent` agent 生命周期管理）的鉴权已迁移到
+`evolclaw.json` 顶层 `owners` 字段（v3.2 起，不再读 `agents/defaults.json`）。
+升级后**必须**在 `evolclaw.json` 配置 `owners`，否则这些操作一律返回 `FORBIDDEN`（daemon 启动时也会 warn 提示）。
+
+```json
+{
+  "owners": ["eleans-2022.agentid.pub"]
+}
+```
+
+`evolclaw init` 交互流程会在生成控制 AID 后提示录入 owners（可跳过后手动编辑）。
+
+- **`owners`**：进程级管理者 AID 名单。可执行 `/system`（重启/升级）与 `/agent`
+  （create / delete / enable / disable / list / show）。
+- 关系级的 `/trigger`（set / cancel / update / list）仍走 channel 角色（owner/admin）+ scoped 鉴权，**不**受 `owners` 影响。
+- `/agent create` 为「受理即返回」：立即回 `{ accepted: true, aid }`，后台跑完整创建流程并把各
+  环节写入 `agents/<aid>/create-status.json`；客户端用 `menu.query name=agent args={aid}` 轮询
+  `createProgress.status` 直到 `ready` / `failed`。
+
+### 控制 AID（control AID）
+
+v3.2 新增进程级身份标识。启动时自动生成 `ec+5位数字.agentid.pub` 格式的控制 AID，以
+`pureIdentity` 模式接入 AUN 网络（跳过 evolagent onboarding）。`evolclaw status` 可查看控制 AID 连接状态。
+
 ## 技术栈
 
 - **运行时**：Node.js >= 22 + TypeScript（ES modules）

package/dist/agents/kit-renderer.js

@@ -61,7 +61,11 @@ export function renderKitSections(ctx) {
         }
         const files = loadSectionFiles(section, ctx.vars, sessionCache);
         diag.fileCount = files.length;
+        // 路径解析成功但读出 0 文件 → 文件/目录不存在（存在性不再单独 syscall，
+        // 由内容读取顺带得到；详见 manifest-engine.resolvePathWithDiag）。
         if (files.length === 0) {
+            if (diag.resolveStatus === 'ok')
+                diag.resolveStatus = 'not-exist';
             diagnostics.push(diag);
             continue;
         }
@@ -125,7 +129,7 @@ const PARAM_DESCRIPTIONS = {
     peerName: '对端显示名',
     peerRole: '对端角色（owner/admin/guest/anonymous）',
     peerType: '对端类型（human/agent）',
-    sameDevice: '对端与本端同一物理设备（E2EE 消息 proximity，仅加密消息有值）',
+    sameDevice: '对端与本端同一物理设备（SDK 0.4.9 起明文/密文消息均可携带，具体字段以网关下发为准）',
     sameNetwork: '对端与本端在同一网络内',
     sameEgressIp: '对端与本端共享同一出口 IP',
     groupId: '群组 ID（群聊时）',

package/dist/agents/manifest-engine.js

@@ -5,24 +5,25 @@ import fs from 'fs';
 import path from 'path';
 import { kitsDir, resolveRoot, getPackageRoot } from '../paths.js';
 import { logger } from '../utils/logger.js';
-// ── Manifest loading / cache (keyed by filename) ──
-const _manifestCache = new Map();
-/** 清空所有 manifest 缓存（manifest 结构变更后调用）。 */
+import { fileCache } from '../core/cache/file-cache.js';
+// ── Manifest loading / cache ──
+// manifest 定义随包发布、运行期靠 reload/重启刷新 → on-reload（group 'kits'）。
+// base + eck override 合成结果以 base 文件路径为键缓存；loader 内读两个文件。
+/** 清空所有 manifest 缓存（manifest 结构变更后调用，由 invalidateKitCache 串联）。 */
 export function invalidateManifestCache() {
-    _manifestCache.clear();
+    fileCache.invalidateGroup('kits');
 }
 /**
  * 加载并合并 manifest。基础文件在 $KITS/<filename>，
  * 覆盖文件在 $EVOLCLAW_HOME/eck/<filename>（可选）。结果按 order 升序缓存。
  */
 export function loadManifest(filename) {
-    const cached = _manifestCache.get(filename);
-    if (cached)
-        return cached;
-    const sections = loadAndMergeManifest(filename);
-    _manifestCache.set(filename, sections);
-    logger.info(`[ManifestEngine] Loaded ${filename}: ${sections.length} sections`);
-    return sections;
+    const kitsPath = path.join(kitsDir(), filename);
+    return fileCache.get(kitsPath, () => {
+        const sections = loadAndMergeManifest(filename);
+        logger.info(`[ManifestEngine] Loaded ${filename}: ${sections.length} sections`);
+        return sections;
+    }, { policy: 'on-reload', group: 'kits' });
 }
 function loadAndMergeManifest(filename) {
     const kitsPath = path.join(kitsDir(), filename);
@@ -86,9 +87,72 @@ export function evaluateWhen(when, vars) {
     return true;
 }
 export function isTruthy(val) {
+    if (Array.isArray(val))
+        return val.length > 0; // 空数组视为假，使 {{?arr}} / {{#each}} 落空
     return val !== undefined && val !== null && val !== false && val !== '' && val !== 0;
 }
 // ── Template rendering ──
+/**
+ * 展开 {{#each KEY}}BODY{{/each}} 循环块（在条件/变量替换之前跑）。
+ * - vars[KEY] 为非空数组才展开；每个元素构造子作用域：
+ *     对象元素 → { ...vars, ...el }（字段可用 {{field}} 访问）
+ *     标量元素 → { ...vars, '.': el }（{{.}} 访问当前元素）
+ *   另注入 {{@index}}（0 基序号）。
+ * - body 经完整 renderTemplate 递归渲染，天然支持嵌套 each / 条件。
+ * - 非数组或空数组 → 整块渲染为空串。
+ * 用深度扫描定位**最外层** each 块（正则无法平衡嵌套），从外向内展开。
+ */
+function resolveEach(template, vars, stripBlankLines) {
+    const OPEN = /\{\{#each\s+([A-Za-z_]\w*)\}\}/g;
+    let result = '';
+    let cursor = 0;
+    OPEN.lastIndex = 0;
+    let m;
+    while ((m = OPEN.exec(template)) !== null) {
+        const blockStart = m.index;
+        const key = m[1];
+        const bodyStart = OPEN.lastIndex;
+        // 从 bodyStart 起按深度找配对的 {{/each}}
+        const TOKEN = /\{\{#each\s+[A-Za-z_]\w*\}\}|\{\{\/each\}\}/g;
+        TOKEN.lastIndex = bodyStart;
+        let depth = 1;
+        let bodyEnd = -1;
+        let blockEnd = -1;
+        let t;
+        while ((t = TOKEN.exec(template)) !== null) {
+            if (t[0].startsWith('{{#each'))
+                depth++;
+            else {
+                depth--;
+                if (depth === 0) {
+                    bodyEnd = t.index;
+                    blockEnd = TOKEN.lastIndex;
+                    break;
+                }
+            }
+        }
+        if (bodyEnd === -1)
+            break; // 无配对，剩余原样输出
+        // 输出块前的原文
+        result += template.slice(cursor, blockStart);
+        const body = template.slice(bodyStart, bodyEnd);
+        const arr = vars[key];
+        if (Array.isArray(arr)) {
+            for (let i = 0; i < arr.length; i++) {
+                const el = arr[i];
+                const scope = (el && typeof el === 'object' && !Array.isArray(el))
+                    ? { ...vars, ...el, '@index': i }
+                    : { ...vars, '.': el, '@index': i };
+                result += renderTemplate(body, scope, stripBlankLines);
+            }
+        }
+        // 数组以外（含 undefined / 非数组）→ 整块跳过（不输出）
+        cursor = blockEnd;
+        OPEN.lastIndex = blockEnd;
+    }
+    result += template.slice(cursor);
+    return result;
+}
 function resolveConditions(template, vars) {
     // 只匹配**最内层** {{?...}}...{{/}} 块（逐字符负向前瞻排除嵌套），do/while 由内向外消解。
     const inner = /\{\{\?(\w+)(?:(!=|=)([^}]*))?\}\}((?:(?!\{\{\?)[^])*?)\{\{\/\}\}/;
@@ -111,11 +175,15 @@ function resolveConditions(template, vars) {
  * 紧凑）；false 时保留空行（消息正文用，正文多段结构不能被压扁）。
  */
 export function renderTemplate(template, vars, stripBlankLines = true) {
-    let result = resolveConditions(template, vars);
-    result = result.replace(/\{\{(\w+)\}\}/g, (_match, key) => {
+    let result = resolveEach(template, vars, stripBlankLines);
+    result = resolveConditions(result, vars);
+    // 变量替换：支持普通名、当前元素 {{.}}、循环序号 {{@index}}。
+    result = result.replace(/\{\{(\.|@index|\w+)\}\}/g, (_match, key) => {
         const val = vars[key];
-        if (!isTruthy(val))
-            return '';
+        if (!isTruthy(val) && val !== 0)
+            return ''; // 0 是有效序号/值，保留
+        if (val === 0)
+            return '0';
         return String(val);
     });
     if (stripBlankLines)
@@ -146,11 +214,10 @@ export function resolvePathWithDiag(rawPath, vars) {
     if (unresolved.length > 0) {
         return { resolved, status: 'unresolved-vars', unresolvedTokens: unresolved };
     }
-    // 路径规范化：模板里 ../ 等相对片段折叠成真实路径
+    // 路径规范化：模板里 ../ 等相对片段折叠成真实路径。
+    // 不再在此 existsSync——存在性由随后经 fileCache 的内容读取顺带得到（file
+    // section 读出 null 即不存在），避免每 section 每消息一次 syscall。
     resolved = path.normalize(resolved);
-    if (!fs.existsSync(resolved)) {
-        return { resolved, status: 'not-exist', unresolvedTokens: unresolved };
-    }
     return { resolved, status: 'ok', unresolvedTokens: unresolved };
 }
 function resolvePath(rawPath, vars) {
@@ -174,29 +241,35 @@ export function loadSectionFiles(section, vars, sessionCache) {
     return [];
 }
 function loadFileSection(filePath, vars, sessionCache) {
+    void sessionCache; // 内容跨 session 共享，改走全局 fileCache（on-reload）
     const resolved = resolvePath(filePath, vars);
     if (!resolved)
         return null;
-    if (sessionCache.has(resolved))
-        return [resolved, sessionCache.get(resolved)];
-    try {
-        const content = fs.readFileSync(resolved, 'utf-8');
-        sessionCache.set(resolved, content);
-        return [resolved, content];
-    }
-    catch {
-        return null;
-    }
+    // 内容跨 session 共享：用全局 fileCache（on-reload，reload/重启时失效），
+    // 不再按 session 重复缓存同一文件内容。
+    const content = fileCache.getText(resolved, { policy: 'on-reload', group: 'kits' });
+    return content === null ? null : [resolved, content];
 }
 function readDirectoryFiles(dirPath, pattern) {
     const glob = pattern || '*.md';
-    try {
-        const files = fs.readdirSync(dirPath).filter(f => matchGlob(f, glob)).sort();
-        return files.map(f => [f, fs.readFileSync(path.join(dirPath, f), 'utf-8')]);
-    }
-    catch {
-        return [];
+    // 目录列表 + 各文件内容均走 fileCache（on-reload）。目录列表以 "<dir>|<glob>"
+    // 为键缓存文件名数组；各文件内容走 fileCache.getText 共享。
+    const names = fileCache.get(`${dirPath} ${glob}`, () => {
+        try {
+            return fs.readdirSync(dirPath).filter(f => matchGlob(f, glob)).sort();
+        }
+        catch {
+            return [];
+        }
+    }, { policy: 'on-reload', group: 'kits' });
+    const out = [];
+    for (const f of names) {
+        const fp = path.join(dirPath, f);
+        const content = fileCache.getText(fp, { policy: 'on-reload', group: 'kits' });
+        if (content !== null)
+            out.push([f, content]);
     }
+    return out;
 }
 function matchGlob(filename, pattern) {
     const regex = pattern

package/dist/agents/message-renderer.js

@@ -44,6 +44,8 @@ function renderOneItem(item, sessionVars, sessionCache, contentSentinel) {
         sameDevice: item.sameDevice ?? sessionVars.sameDevice,
         sameNetwork: item.sameNetwork ?? sessionVars.sameNetwork,
         sameEgressIp: item.sameEgressIp ?? sessionVars.sameEgressIp,
+        // 模板引擎不支持数组循环：被 @ 的 AID 预先 join 成串，空则 undefined 使 {{?mentionAids}} 落空。
+        mentionAids: (item.mentionAids && item.mentionAids.length > 0) ? item.mentionAids.join(',') : undefined,
         now: formatLocalTime(item.timestamp ?? Date.now(), sessionVars.timezone ? String(sessionVars.timezone) : undefined),
         // content held as a per-call random sentinel, swapped back post-render.
         // Using a UUID means no real message can collide with it.

package/dist/aun/aid/control-aid.js

@@ -0,0 +1,67 @@
+import crypto from 'crypto';
+import { aidCreate } from './index.js';
+import { getAidStore, SLOT } from './store.js';
+import { logger } from '../../utils/logger.js';
+const MAX_ATTEMPTS = 5;
+/** 生成候选控制 AID：ec + 5位随机数字 + .agentid.pub */
+export function candidateAid() {
+    const n = crypto.randomInt(10000, 100000); // 5 位：10000-99999
+    return `ec${n}.agentid.pub`;
+}
+/**
+ * 候选 AID 是否已在 PKI 注册。
+ *
+ * 不用 store.exists（它走 HTTP HEAD /pki/cert/<aid>）——部分 Gateway 实现
+ * （Python websockets HTTP 处理）对 HEAD 直接空响应断连（curl 52 / socket hang up），
+ * 导致 exists 误报"网关不可达"。改用 store.resolve（走 GET），语义等价且 GET 正常返回：
+ *   - resolve ok            → 证书存在（HTTP 200）→ 已注册
+ *   - CERT_NOT_FOUND        → 404 → 未注册
+ *   - 其它 error            → 真·网络错误，向上抛出供 fail-fast
+ * skipAgentMd:true 避免多拉一次 agent.md（控制 AID 本就不传 agent.md）。
+ */
+async function candidateExists(store, candidate) {
+    const r = await store.resolve(candidate, { skipAgentMd: true });
+    if (r.ok)
+        return true;
+    if (r.error?.code === 'CERT_NOT_FOUND')
+        return false;
+    throw new Error(`Gateway 不可达，无法查重控制 AID：${r.error?.message ?? 'unknown'}`);
+}
+/**
+ * 生成控制 AID：循环候选 → candidateExists 查重（权威 PKI 判据）→ 不冲突则 aidCreate。
+ * - 查重走 GET 证书（见 candidateExists；不拉 agent.md，控制 AID 本就不传 agent.md）
+ * - fail-fast：查重探测失败（网关不可达）立即抛错，不掩盖成"均冲突"
+ * - agent.md 不上传：aidCreate 仅注册身份 + 写私钥，不调 agentmdPut
+ */
+export async function generateControlAid() {
+    const store = await getAidStore({ slotId: SLOT.cli });
+    try {
+        for (let i = 0; i < MAX_ATTEMPTS; i++) {
+            const candidate = candidateAid();
+            if (await candidateExists(store, candidate)) {
+                logger.info(`[control-aid] ${candidate} 已注册，重试 (${i + 1}/${MAX_ATTEMPTS})`);
+                continue;
+            }
+            const created = await aidCreate(candidate);
+            // 清理 aidCreate 内部另开的 client/store——关闭失败不可丢弃已注册的 AID（否则下次 init
+            // 会把它当冲突，白白消耗一次重试）。close 异常降级为 warn。
+            try {
+                await created.client?.close?.();
+            }
+            catch (e) {
+                logger.warn(`[control-aid] client.close() 失败（非致命）: ${e}`);
+            }
+            try {
+                await created.store?.close?.();
+            }
+            catch (e) {
+                logger.warn(`[control-aid] store.close() 失败（非致命）: ${e}`);
+            }
+            return { aid: created.aid, gateway: created.gateway };
+        }
+        throw new Error(`无法生成控制 AID：连续 ${MAX_ATTEMPTS} 次候选均冲突`);
+    }
+    finally {
+        store.close();
+    }
+}

package/dist/aun/aid/identity.js

@@ -443,6 +443,7 @@ export async function probePkiRecoverability(aid, opts) {
 }
 // ==================== Lookup ====================
 export async function aidLookup(aid) {
+    // gateway：well-known 探测（保留，供 aid lookup 命令展示）
     let gateway = '';
     try {
         const gwResp = await fetch(`https://${aid}/.well-known/aun-gateway`, { redirect: 'follow' });
@@ -464,16 +465,28 @@ export async function aidLookup(aid) {
         }
     }
     catch { /* ignore */ }
+    const { agentmdGet } = await import('./agentmd.js');
+    const store = await getAidStore({ slotId: SLOT.cli });
     try {
-        const resp = await fetch(`https://${aid}/agent.md`, { redirect: 'follow' });
-        if (resp.ok) {
-            const content = await resp.text();
-            return { exists: true, aid, gateway, content };
+        // 权威注册判据：PKI 证书 HEAD（与 agent.md 无关）
+        const existsResult = await store.exists(aid);
+        if (!existsResult.ok) {
+            return { exists: false, aid, gateway, error: existsResult.error?.message ?? 'exists check failed' };
         }
-        return { exists: false, aid, gateway, error: `agent_md_not_found` };
+        const exists = existsResult.data.exists;
+        if (!exists) {
+            return { exists: false, aid, gateway };
+        }
+        // 已注册：尽力拉 agent.md content（无 agent.md 不影响 exists）
+        let content;
+        try {
+            content = await agentmdGet(aid, { store });
+        }
+        catch { /* registered but no agent.md — content stays undefined */ }
+        return { exists, aid, gateway, content };
     }
-    catch (e) {
-        return { exists: false, aid, gateway, error: String(e.message || e) };
+    finally {
+        store.close();
     }
 }
 function lifecycleLogPath(aid) {

package/dist/aun/aid/store.js

@@ -39,10 +39,10 @@ export class AidLoadError extends Error {
  */
 export async function getAidStore(opts) {
     const { aunPath: defaultAunPath } = await import('../../paths.js');
-    const { loadProcessConfig } = await import('../../config-store.js');
+    const { loadEvolclawConfig } = await import('../../evolclaw-config.js');
     const { AIDStore } = await import('@agentunion/fastaun');
     const aunPath = opts.aunPath ?? defaultAunPath();
-    const encryptionSeed = loadProcessConfig().aun?.encryptionSeed
+    const encryptionSeed = loadEvolclawConfig().aun?.encryptionSeed
         ?? process.env.AUN_ENCRYPTION_SEED
         ?? 'evol';
     const caCertPath = path.join(aunPath, 'CA', 'root', 'root.crt');