evolclaw 3.1.4 → 3.1.5

package/dist/core/session/session-mapper.js

@@ -1,4 +1,5 @@
 import { formatTimestamp } from './session-fs-store.js';
+import { formatSessionKey, DEFAULT_THREAD_ID } from './session-key.js';
 export function sessionToFile(session) {
     const metadata = {};
     if (session.metadata) {
@@ -15,19 +16,22 @@ export function sessionToFile(session) {
         if (session.metadata.resumeAt)
             metadata.resumeAt = session.metadata.resumeAt;
         for (const [k, v] of Object.entries(session.metadata)) {
-            if (['isActive', 'channelName', 'permissionMode', 'peerId', 'peerName', 'groupId', 'replyContext', 'agentSessions', 'resumeAt'].includes(k))
+            if (['isActive', 'channelKey', 'channelName', 'permissionMode', 'peerId', 'peerName', 'groupId', 'replyContext', 'agentSessions', 'resumeAt'].includes(k))
                 continue;
             if (v !== undefined)
                 metadata[k] = v;
         }
     }
     const now = session.updatedAt || Date.now();
+    const channelType = session.channelType || session.channel;
+    const threadId = session.threadId || DEFAULT_THREAD_ID;
     return {
         id: session.id,
         channel: session.channel,
-        channelType: session.channelType || session.channel,
+        channelType,
         channelId: session.channelId,
-        selfId: session.selfId ?? null,
+        sessionKey: formatSessionKey(channelType, session.channelId, threadId),
+        selfAID: session.selfAID,
         agentType: session.agentId || 'claude',
         threadId: session.threadId || '',
         chatType: session.chatType || 'private',
@@ -71,7 +75,8 @@ export function fileToSession(file) {
         channel: file.channel,
         channelType: file.channelType,
         channelId: file.channelId,
-        selfId: file.selfId ?? undefined,
+        sessionKey: file.sessionKey || formatSessionKey(file.channelType, file.channelId, file.threadId || DEFAULT_THREAD_ID),
+        selfAID: file.selfAID,
         agentId: file.agentType,
         threadId: file.threadId,
         chatType: file.chatType,

package/dist/core/trigger/manager.js

@@ -23,7 +23,7 @@ export class TriggerManager {
             const raw = fs.readFileSync(this.triggersPath, 'utf8');
             const data = JSON.parse(raw);
             this.triggers = new Map(Object.entries(data.triggers ?? {}));
-            // Migrate old channel key format: "selfPeerId#type#name" → "type#selfPeerId#name"
+            // Migrate old channel key format: "selfAID#type#name" → "type#selfAID#name"
             let migrated = false;
             for (const trigger of this.triggers.values()) {
                 const fixed = this.migrateChannelKey(trigger.targetChannel);
@@ -52,7 +52,7 @@ export class TriggerManager {
         }
     }
     /**
-     * Detect and fix old format "selfPeerId#type#name" → current "type#selfPeerId#name".
+     * Detect and fix old format "selfAID#type#name" → current "type#selfAID#name".
      * Old format: first segment contains '.' (AID like "evolai.agentid.pub").
      */
     migrateChannelKey(key) {
@@ -63,7 +63,7 @@ export class TriggerManager {
             return key;
         const [first, second, third] = parts;
         if (first.includes('.') && !second.includes('.')) {
-            return formatChannelKey({ type: second, selfPeerId: first, name: third });
+            return formatChannelKey({ type: second, selfAID: first, name: third });
         }
         return key;
     }

package/dist/core/trigger/scheduler.js

@@ -211,8 +211,9 @@ export class TriggerScheduler {
     buildSyntheticMessage(trigger, messageId) {
         return {
             channel: trigger.targetChannel,
+            channelType: trigger.targetChannelType,
             channelId: trigger.targetChannelId,
-            selfId: this.aid,
+            selfAID: this.aid,
             threadId: trigger.targetThreadId ?? '',
             agentId: trigger.agentId,
             chatType: 'private',

package/dist/index.js

@@ -26,7 +26,7 @@ import { StatsCollector } from './utils/stats.js';
 import { AidStatsCollector } from './utils/stats.js';
 import { PermissionGateway } from './core/permission.js';
 import { InteractionRouter } from './core/interaction-router.js';
-import { ChannelLoader } from './core/channel-loader.js';
+import { ChannelLoader, tryParseChannelKey } from './core/channel-loader.js';
 import { AgentLoader } from './core/baseagent-loader.js';
 import { EvolAgentRegistry } from './core/evolagent-registry.js';
 import { buildReloadHooks } from './core/channel-loader.js';
@@ -553,7 +553,8 @@ async function main() {
                 const owningAgent = agentRegistry.resolveByChannel(inst.adapter.channelKey);
                 const effectiveDefault = owningAgent?.projectPath
                     ?? primaryAgent.projectPath;
-                const session = await sessionManager.getOrCreateSession(inst.adapter.channelKey, channelId, effectiveDefault, undefined, undefined, undefined, undefined);
+                const parsedKey = tryParseChannelKey(inst.adapter.channelKey);
+                const session = await sessionManager.getOrCreateSession(inst.adapter.channelKey, channelId, effectiveDefault, undefined, undefined, undefined, undefined, undefined, undefined, parsedKey?.selfAID, parsedKey?.type);
                 return path.isAbsolute(session.projectPath)
                     ? session.projectPath
                     : path.resolve(process.cwd(), session.projectPath);
@@ -866,6 +867,9 @@ async function main() {
         queued: messageQueue.getQueueLengthByAgent(agentName),
     }));
     ipcServer.setAunAidStatsProvider(() => aidStatsCollector.getAllSnapshots());
+    ipcServer.setAunAidStatsRecorder((params) => {
+        aidStatsCollector.recordOutbound(params.aid, params.toPeer, Buffer.byteLength(params.text || '', 'utf-8'), params.text, false, params.encrypt, params.chatmode);
+    });
     // ── Reload hooks: enable agentRegistry.reload() to drain/disconnect/restart channels ──
     const reloadHooks = buildReloadHooks({
         channelLoader,

package/dist/ipc.js

@@ -11,6 +11,7 @@ export class IpcServer {
     agentRegistry;
     aunAidProvider;
     aunAidStatsProvider;
+    aunAidStatsRecorder;
     constructor(socketPath, getStatus, commandExecutor) {
         this.socketPath = socketPath;
         this.getStatus = getStatus;
@@ -28,6 +29,10 @@ export class IpcServer {
     setAunAidStatsProvider(provider) {
         this.aunAidStatsProvider = provider;
     }
+    /** Inject AUN AID stats recorder for aun-aid-stats-record-outbound IPC handler */
+    setAunAidStatsRecorder(recorder) {
+        this.aunAidStatsRecorder = recorder;
+    }
     start() {
         // Remove stale socket file (Unix only — named pipes auto-cleanup on process exit)
         if (!isNamedPipe(this.socketPath)) {
@@ -97,6 +102,23 @@ export class IpcServer {
                 const stats = this.aunAidStatsProvider ? this.aunAidStatsProvider() : [];
                 return { ok: true, stats };
             }
+            case 'aun-aid-stats-record-outbound': {
+                if (!this.aunAidStatsRecorder)
+                    return { ok: false, error: 'recorder not configured' };
+                try {
+                    this.aunAidStatsRecorder({
+                        aid: cmd.aid,
+                        toPeer: cmd.toPeer,
+                        text: cmd.text ?? '',
+                        encrypt: cmd.encrypt,
+                        chatmode: cmd.chatmode,
+                    });
+                    return { ok: true };
+                }
+                catch (e) {
+                    return { ok: false, error: String(e?.message || e) };
+                }
+            }
             case 'ctl': {
                 if (!this.commandExecutor)
                     return { ok: false, error: 'ctl not configured' };

package/kits/docs/GUIDE.md

@@ -2,14 +2,14 @@
 
 ## 查阅流程
 
-1. 先看 `$KITS_RULES`（自动加载的 8 个规则文件）了解机制骨架
+1. 先看 `$KITS_RULES`（自动加载的 6 个规则文件 01-06）了解机制骨架
 2. 需要详细信息时，按 `INDEX.md` 找到对应文档路径
 3. Read 对应文档
 
 ## 路径解析
 
 文档中用 `$名称` 引用路径。解析步骤：
-1. 查 `$KITS_RULES/01-entry.md` 的路径体系速查表
+1. 查 `$KITS_RULES/02-navigation.md` 的路径体系速查表
 2. 如需完整定义，Read `$KITS_DOCS/path-registry.md`
 3. 如需运行时实际值，Read `$ECK/path-registry.md`
 

package/kits/docs/INDEX.md

@@ -8,6 +8,7 @@
 |------|------|------|
 | 查阅指南 | `GUIDE.md` | 文档查阅流程 |
 | 路径定义 | `path-registry.md` | 所有预定义路径及派生规则 |
+| 上下文组装机制 | `context-assembly.md` | manifest 装配机制：when 条件/合并覆盖/模板渲染/运行时变量/调试输出 |
 
 ## AUN 协议
 
@@ -20,11 +21,14 @@
 
 | 文档 | 路径 | 说明 |
 |------|------|------|
-| Agent 命令 | `evolclaw/AGENT_CMD.md` | agent 全生命周期管理命令 |
-| 运行时工具 | `evolclaw/tools.md` | ctl 命令集 |
+| 私聊消息 | `evolclaw/msg.md` | `ec msg` 私聊收发消息 |
+| 群聊消息 | `evolclaw/group.md` | `ec group` 群聊收发与群管理 |
+| Agent 生命周期 | `evolclaw/agent.md` | `ec agent` 创建/启停/配置/热重载 |
+| AID 身份 | `evolclaw/aid.md` | `ec aid` 身份/证书/名片/探测对端 |
+| 文件存储 | `evolclaw/storage.md` | `ec storage` 上传/下载/配额 |
+| 运行时自管理 | `evolclaw/ctl.md` | `ec ctl` 切模型/推理强度/压缩/重启 |
+| 底层 RPC | `evolclaw/rpc.md` | `ec rpc` 直接调 AUN 协议方法 |
 | 自我总结 | `evolclaw/self-summary.md` | 自我总结流程指南 |
-| 私聊消息 | `evolclaw/MSG_PRIVATE.md` | 私聊消息命令 |
-| 群聊消息 | `evolclaw/MSG_GROUP.md` | 群聊消息命令 |
 
 ## 身份
 
@@ -35,12 +39,12 @@
 | AID 档案规范 | `identity/AID_PROFILE_SPEC.md` | AID 档案格式规范 |
 | 路径运维 | `identity/PATH_OPS.md` | 路径运维操作 |
 
-## 渠道
+## 渠道（知识文档·按需加载，不依赖当前渠道）
 
 | 文档 | 路径 | 说明 |
 |------|------|------|
-| AUN 渠道 | `channels/aun.md` | AUN 通信约定 |
-| 飞书渠道 | `channels/feishu.md` | 飞书渠道接入 |
+| AUN 渠道 | `channels/aun.md` | AUN 渠道配置、参数与特有机制（网关发现/E2EE/群 ID/证书链） |
+| 飞书渠道 | `channels/feishu.md` | 飞书渠道配置、参数与特有机制（appId/合并转发/卡片/user_id） |
 
 ## ECK 模板
 

package/kits/docs/channels/aun.md

@@ -1,25 +1,64 @@
-# AUN 通信约定
+# AUN 渠道
 
-## 消息收发
+> 知识性文档：AUN 渠道的配置、参数与特有机制。**不依赖当前会话渠道**——任意会话都可按需 Read。
+> 运行时"怎么发消息"由注入的 `[channel]` 段决定（aun 渠道用 `ec msg send` / `ec group send`），不在本文。
+> 底层协议方法与 RPC 逃生通道见 `evolclaw/rpc.md`。
 
-- 私聊：`message.send` / `message.receive`
-- 群聊：`group.message.send` / `group.message.receive`
-- 消息格式：纯文本 / Markdown / 文件引用
+## 概述
 
-## 身份识别
+AUN 渠道把 agent 接入 AUN（Agent Union Network），对端以 **AID** 为身份标识（既是身份也是地址）。evolclaw 通过 AUN SDK（`@agentunion/fastaun`）维护到 Gateway 的 WebSocket 长连接，支持私聊、群聊、文件、E2EE 加密。
 
-- 每条入站消息携带发送者 AID
-- 通过 `https://<aid>/agent.md` 获取对端名片
-- 名片包含：名称、能力声明、联系方式
+## 配置
 
-## 连接管理
+AUN 渠道是**隐式**的——它不写在 `channels[]` 数组里，而是从 agent 自身的 AID 自动创建。一个 agent 就是一个 AID，启动时 evolclaw 用顶层 `aid` 字段隐式构造唯一的 aun 实例（`channel-loader.ts`）。所以真实的 agent config.json 里 `channels` 数组通常是空的（飞书等非 aun 渠道才往里加）。
 
-- evolclaw 自动维护 WebSocket 长连接
-- 断线自动重连（SDK 内置退避策略）
-- 连接状态可通过 `evolclaw ctl aid` 查看
+### agent 配置（`agents/<aid>/config.json`）
 
-## 群聊
+```json
+{
+  "$schema_version": 1,
+  "aid": "myagent.agentid.pub",
+  "enabled": true,
+  "owners": ["owner.agentid.pub"],
+  "channels": [],
+  "active_baseagent": "claude"
+}
+```
 
-- 群 ID 格式：`<issuer>/<group-name>`
-- 被 @ 时才默认响应（可通过 venue policy 配置）
-- 群消息按窗口批量推送（batch_window_seconds）
+| 字段 | 说明 |
+|------|------|
+| `aid` | agent 的 AID，**即 aun 渠道身份**（隐式创建，无需在 channels[] 声明） |
+| `enabled` | agent 是否启用 |
+| `owners` | owner 的 **AID** 列表（最高权限）；首个 owner 用于首次连接发欢迎消息 |
+| `admins` | admin 的 AID 列表 |
+| `channels` | 非 aun 渠道（飞书等）的实例数组；aun 不在此 |
+
+> `owners`/`admins` 用 **AID**，不是渠道原生 ID。
+
+### 进程级配置（`$EVOLCLAW_HOME/config.json`）
+
+E2EE 加密种子是**进程级**的，所有 agent 共享，不在 agent config 里：
+
+```json
+{
+  "aun": {
+    "encryptionSeed": "<seed>"
+  }
+}
+```
+
+留空时 SDK 依次回退 `AUN_ENCRYPTION_SEED` 环境变量 → 默认 `'evol'`。
+
+> Gateway 不在配置里手填：连接时从 AID 自动发现（见下）。Keystore 默认落在 `$EVOLCLAW_HOME`。
+
+## 特有机制
+
+- **隐式创建**：aun 渠道由顶层 `aid` 派生，无独立配置实例；这是它与飞书等渠道最大的不同。
+- **网关发现**：连接前查询 `https://<aid>/.well-known/aun-gateway` 获取网关地址（AID 本身即域名）；per-agent 流程不提供手填 gateway 的入口，发现失败即连接失败。
+- **身份与信任**：每条入站消息携带发送者 AID，经四级 X.509 证书链（Root CA → Registry CA → Issuer CA → Agent）验签。
+- **agent.md 缓存**：对端名片 `https://<aid>/agent.md` 由 **AUN SDK 自动拉取并缓存**（`AgentMdManager`，带 ETag/TTL，默认 1 天内不重复探测）。缓存落在 **`$EVOLCLAW_HOME/AIDs/<aid>/`**，每个 AID 两个文件：`agent.md`（带签名正文）+ `agentmd.json`（元数据：etag/last_modified/checked_at/verify_status）。本端与对端的 agent.md 都缓存于此。
+  - 关系层另存一份**派生**的精简身份 `relations/<peerKey>/peer-identity.json`（type/isAgent/name），由 evolclaw 从 agent.md 提取，不是 agent.md 本体。
+- **E2EE 加密**：可选端到端加密，回复默认跟随对端消息加密状态（密文回密文，明文回明文）；种子由进程级 `aun.encryptionSeed` 提供。
+- **断线重连**：SDK 内置退避策略自动重连。实时连接状态用 `ec watch aid` 查看（`ec aid` 是身份/证书管理，不显示连接状态）。
+- **群 ID 格式**：`group.{issuer}/{group_name}`（新格式）或 `{group_no}.{issuer}`（数字群号，如 `11117.agentid.pub`）。
+- **身份体系**：对端以 AID 标识，关系层 peerKey 形如 `aun#alice.aid.pub`。

package/kits/docs/channels/feishu.md

@@ -1,27 +1,56 @@
 # 飞书渠道
 
-<!-- TODO: 填充飞书渠道接入文档 -->
+> 知识性文档：飞书渠道的配置、参数与特有机制。**不依赖当前会话渠道**——任意会话都可按需 Read（在 aun 会话里也可查飞书）。
+> 运行时"怎么发消息"由注入的 `[channel]` 段决定（飞书是 evolclaw 自动回复，agent 不调 CLI），不在本文。
 
 ## 概述
 
-飞书渠道通过 evolclaw 的 feishu channel 实现，支持：
-- 单聊消息收发
-- 群聊消息收发
-- 合并转发消息解析
-- 文件/图片/视频消息
+飞书渠道通过 evolclaw 的 feishu channel 插件接入，对端以飞书 `user_id`（如 `ou_xxx`）为身份标识。支持单聊/群聊收发、合并转发解析、富文本卡片、文件/图片/视频消息。
 
 ## 配置
 
-在 evolclaw 配置中启用飞书渠道：
+飞书渠道按 **per-agent** 配置，写在 `agents/<aid>/config.json` 的 `channels` 数组里。每个元素是一个独立实例，靠 `name` 区分；同一 agent 可配多个飞书实例。
 
 ```json
 {
-  "channels": {
-    "feishu": {
+  "aid": "myagent.aid.pub",
+  "channels": [
+    {
+      "type": "feishu",
+      "name": "main",
       "enabled": true,
-      "appId": "<app-id>",
-      "appSecret": "<app-secret>"
+      "appId": "cli_xxx",
+      "appSecret": "<app-secret>",
+      "owners": ["ou_owner_user_id"],
+      "admins": ["ou_admin_user_id"]
     }
-  }
+  ]
 }
 ```
+
+### 实例字段
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `type` | 是 | 固定 `"feishu"` |
+| `name` | 是（数组形式） | 该 agent 内飞书实例的本地标识，不含 `#` |
+| `enabled` | 否 | 默认启用；`false` 关闭该实例 |
+| `appId` | 是 | 飞书自建应用 App ID |
+| `appSecret` | 是 | 飞书自建应用 App Secret |
+| `owners` | 否 | owner 的飞书 `user_id` 列表（最高权限） |
+| `admins` | 否 | admin 的飞书 `user_id` 列表 |
+| `flushDelay` | 否 | flush 间隔（秒），覆盖全局值 |
+| `debounce` | 否 | 入站消息去抖间隔（秒），覆盖全局值 |
+| `showActivities` | 否 | 思考过程展示范围：`all` / `dm-only` / `owner-dm-only` / `none` |
+
+> `owners`/`admins` 用飞书原生 `user_id`，**不是 AID**。
+
+agent 级（config.json 顶层）相关开关：
+- `enable_rich_content`：启用富文本卡片渲染，默认关闭。
+
+## 特有机制
+
+- **合并转发解析**：飞书的 `merge_forward` 消息会被自动展开为文本注入上下文（含"以下是引用的原消息"包裹）。
+- **交互卡片**：富内容开启时，部分回复以飞书卡片形式发送；卡片按钮**仅发起者可操作**，他人点击返回提示。
+- **身份体系**：对端以 `user_id` 标识，关系层 peerKey 形如 `feishu#ou_xxx`。
+- **自动回复**：飞书是非 aun 渠道，回复由 evolclaw 自动完成，agent 无需调用 `ec msg send`。

package/kits/docs/context-assembly.md

@@ -0,0 +1,181 @@
+# 上下文组装机制（manifest）
+
+ECK 把"每条消息该给 base agent 看哪些上下文"这件事，交给一份 **manifest** 声明式描述，由 `renderKitSections`（`src/agents/kit-renderer.ts`）在每次处理消息时执行。本文是这套机制的完整参考。
+
+> 本文是按需载入文档。日常对话不需要读它——只有在排查"为什么某段上下文没出现/出现了"、要改 manifest、或要看实际渲染结果时才 Read。
+
+## 三个阶段
+
+evolclaw 收到消息 → 构造一份 **vars**（运行时变量，见下）→ `renderKitSections`：
+
+1. **选段**：按 manifest 顺序遍历每个 section，用它的 `when` 条件 + 当前 vars 判断是否加载。
+2. **渲染**：解析 section 路径里的 `$NAME` / `{{key}}` 占位符定位文件；`needsInjection:true` 的文件再跑一遍模板渲染（条件块 + 变量替换）。
+3. **拼装**：所有命中的文件内容包进一个 `<system-reminder>` 块，作为 system prompt 的一部分注入。
+
+整个过程对每次消息执行一次，结果同时落盘到调试目录（见"调试机制"）。
+
+## manifest 文件位置
+
+| 文件 | 角色 | 性质 |
+|------|------|------|
+| `$KITS/eck_manifest.json` | 基础 manifest（开发时维护） | 只读 |
+| `$ECK/eck_manifest.json` | 用户覆盖（可选，默认不存在） | 可写 |
+
+加载时合并两者（见"合并与覆盖"）。manifest 只加载一次并缓存。
+
+## section 字段
+
+manifest 是 `{ "$schema_version": 1, "sections": [...] }`。每个 section：
+
+| 字段 | 必填 | 含义 |
+|------|------|------|
+| `id` | ✓ | 唯一标识，覆盖合并的键 |
+| `type` | ✓ | `file`（单文件）或 `directory`（整目录） |
+| `file` | type=file | 文件路径，可含 `$NAME` / `{{key}}` |
+| `path` | type=directory | 目录路径 |
+| `pattern` | | 目录匹配 glob，默认 `*.md`（支持 `*` 和 `{a,b}`） |
+| `order` | ✓ | 排序，**升序**决定上下文中出现的先后 |
+| `needsInjection` | ✓ | `true`=按模板渲染（解析 `{{}}` 条件与变量）；`false`=原样读入 |
+| `when` | ✓ | 加载条件，`"always"` 或条件对象（见下） |
+| `enabled` | | `false` 时整段跳过 |
+| `description` | | 调试输出里的人类可读标签 |
+
+## when 条件求值
+
+`when` 是 `"always"` 或一个对象。求值规则（`evaluateWhen`）：
+
+| 写法 | 含义 |
+|------|------|
+| `"always"` | 恒为真 |
+| `{ "var": "X", "eq": V }` | `vars.X === V`；`eq:null` 匹配"未注入"（null/undefined） |
+| `{ "var": "X", "neq": V }` | `vars.X !== V`；`neq:null` 匹配"已注入" |
+| `{ "var": "X", "in": [...] }` | `vars.X` 在数组内 |
+| `{ "var": "X", "nin": [...] }` | `vars.X` 不在数组内 |
+| `{ "any": ["A","B"] }` | A、B 任一为真值 |
+| `{ "all": ["A","B"] }` | A、B 全为真值 |
+
+"真值"判定：非 `undefined`/`null`/`false`/`""`/`0`。
+
+典型用法：`{ "var": "chatType", "neq": null }` = "非 coding 场景才加载"；`{ "var": "groupId", "neq": null }` = "群聊才加载"。
+
+## 合并与覆盖
+
+无 `$ECK/eck_manifest.json` 时，直接用基础 manifest。存在时：
+
+- 覆盖文件含 `"mode": "replace"` → **完全替换**，只用覆盖文件的 sections。
+- 否则 **patch 合并**：以 `id` 为键，覆盖文件里同 id 的字段浅合并进基础 section（`{...base, ...override}`），新 id 追加。
+
+合并后统一按 `order` 升序排序。改某段行为（如关掉某层、调顺序、换条件）优先用覆盖文件，不动基础 manifest。
+
+## 路径与模板渲染
+
+### 路径占位符（所有 section 的 file/path）
+
+- `$NAME`（大写）→ 从 vars 取真值，如 `$KITS_DOCS` → 包内文档目录。
+- `{{key}}` → 从 vars 取真值，如 `{{chatType}}` → `private`，`{{peerKey}}` → `aun#alice.aid.pub`。
+
+任一占位符解析为空 → 该 section 视为"未解析"，跳过（调试输出标 `unresolved-vars`）。文件不存在 → 标 `not-exist`，也跳过。这是**正常机制**：很多 section 靠"路径解析不出来"自然落选（如 coding 场景没有 `$PERSONAL_DIR`）。
+
+### 模板渲染（仅 needsInjection:true 的文件）
+
+读入跑三遍：
+
+1. **条件块**（内层优先，可嵌套）：
+   - `{{?key}}...{{/}}` — key 为真值才保留
+   - `{{?key=value}}...{{/}}` — `String(vars.key)===value` 才保留
+   - `{{?key!=value}}...{{/}}` — 不等才保留
+2. **变量替换**：`{{key}}` 替换为值，非真值替换为空串。
+3. **清理**：删掉空行。
+
+`needsInjection:false` 的文件原样读入，不做任何替换（如 rules 目录、persona.md、各 venue 文档）。
+
+## 运行时变量（vars）目录
+
+vars 由 evolclaw 在 `message-processor.ts` 按当前会话构造。分两类：
+
+**路径类**（供占位符展开成真实路径）：
+`EVOLCLAW_HOME`、`PACKAGE_ROOT`、`CURRENT_PROJECT`、`KITS`、`KITS_RULES`、`KITS_DOCS`、`KITS_TEMPLATES`、`KITS_FRAGMENTS`、`PERSONAL_DIR`、`RELATIONS_DIR`、`VENUES_DIR`。
+
+**内容/场景类**（供 when 判断与模板替换）：
+
+| 变量 | 含义 |
+|------|------|
+| `selfAid` / `selfName` | 当前 agent 身份 |
+| `hasPersona` / `hasWorkingMemory` | 是否有人格 / 当前关注 |
+| `peerId` / `peerKey` / `peerName` | 对端原生 ID / 跨渠道键 / 显示名 |
+| `peerRole` / `peerType` | 对端角色（owner/admin/guest/...）/ 类型（human/agent） |
+| `groupId` | 群 ID（群聊时） |
+| `chatType` | `private` / `group` / `null`(coding) |
+| `channel` | 渠道类型（aun/feishu/...）|
+| `dispatch` | 群分发模式（mention/broadcast） |
+| `clientType` | 客户端类型（desktop/web/mobile） |
+| `permissionMode` / `readonly` | 权限模式 / 是否只读 |
+| `capabilities` | 当前渠道能力（图片输入/输出、文件发送） |
+| `project` / `CURRENT_PROJECT` | 项目目录名 / 完整路径 |
+| `sessionId` / `sessionName` / `sessionKey` / `sessionCreatedAt` / `threadId` | 会话标识与元信息 |
+| `chatMode` | `interactive` / `proactive` |
+| `baseAgent` / `baseAgentName` / `baseAgentModel` / `agentSessionId` | base agent 信息 |
+
+coding 场景（无 channel/无身份）下，`chatType`、`channel`、`selfAid`、`peer*` 等均为空——这正是身份/关系/环境/渠道层落选的原因。
+
+## 默认 manifest 的段（按 order）
+
+| order | id | 类型 | 加载条件（when） | inject |
+|-------|----|----|------------------|--------|
+| 10 | rules | 目录 `$KITS_RULES` | always | ✗ |
+| 20 | identity-layer | fragment | chatType≠null | ✓ |
+| 21 | persona | `$PERSONAL_DIR/persona.md` | chatType≠null | ✗ |
+| 22 | working-memory | `$PERSONAL_DIR/memory/working.md` | chatType≠null | ✗ |
+| 30 | relation-layer | fragment | chatType∈{private,group} | ✓ |
+| 35 | peer-profile | `$RELATIONS_DIR/{{peerKey}}/profile.md` | peerKey≠null | ✗ |
+| 40 | venue-fragment | fragment | chatType≠null | ✓ |
+| 41 | venue-chattype | `$KITS_DOCS/venues/{{chatType}}.md` | chatType≠null | ✗ |
+| 42 | venue-channel-chattype | `$KITS_DOCS/venues/{{channel}}-{{chatType}}.md` | chatType≠null | ✗ |
+| 43 | venue-group-profile | `$VENUES_DIR/{{channel}}#{{groupId}}/profile.md` | groupId≠null | ✗ |
+| 44 | venue-client | `$KITS_DOCS/venues/client-{{clientType}}.md` | clientType≠null | ✗ |
+| 50 | channel-layer | fragment | channel≠null | ✓ |
+| 60 | session | fragment | always | ✓ |
+| 70 | baseagent | fragment | baseAgent≠null | ✓ |
+
+> 注意：`session`(60) 是 `always`，`baseagent`(70) 只看 `baseAgent` 是否注入——这两段**与 chatType 无关**，coding 场景也会加载。所谓"coding 仅 rules"是近似说法：精确地说 coding 场景命中的是 rules + session + baseagent（其余因 chatType/channel 为空而落选）。
+
+## 输出结构
+
+所有命中 section 的文件内容拼成一个块，注入 system prompt：
+
+```
+<system-reminder>
+EvolClaw Context Kit documents are shown below.
+
+Contenu de <展示路径> (<id — description>):
+
+<文件内容>
+
+...（每个文件一段，按 order）
+
+IMPORTANT: Use this context when it affects the current interaction.
+</system-reminder>
+```
+
+展示路径会把绝对路径回缩成 `$KITS_RULES`/`$AGENT_DIR` 等别名。`needsInjection:true` 的段额外单独汇总到 `fragments-*.md` 调试文件（见下）。
+
+## 调试机制（看实际渲染结果）
+
+每次渲染都把结果落盘到 **`$EVOLCLAW_HOME/data/eck-debug/`**，文件名带时间戳（`<字段>-YYYY-MM-DD-HH-MM-SS`）：
+
+| 文件 | 内容 |
+|------|------|
+| `vars-<ts>.json` | 本次注入的全部 vars 真值 + 每个变量的中文说明 |
+| `context-<ts>.md` | 最终注入 base agent 的完整 `<system-reminder>` 块（即上面"输出结构"的实际产物） |
+| `fragments-<ts>.md` | 仅经过模板渲染（needsInjection）的段，单独汇总，便于核对 `{{}}` 替换是否正确 |
+| `manifest-<ts>.md` | **诊断报告**：每个 section 的 when 是否通过、路径解析状态（ok/unresolved-vars/not-exist/skipped）、是否被用上、是否注入；含未解析占位符清单 |
+
+排查"某段为什么没出现"：看 `manifest-<ts>.md` 里该 section 的 `status` 和 `unresolved tokens`。看"实际给 agent 的全文"：读 `context-<ts>.md`。
+
+调试文件保留 24 小时，`cleanEckDebug` 自动清理过期的。
+
+## 缓存与热加载
+
+- **manifest 缓存**：`_manifestCache`，进程内只加载一次。改了 manifest 需触发 `invalidateKitCache()`（或重启）才生效。
+- **文件内容缓存**：`_sessionPathCache` 按 `sessionId` 缓存已读文件内容；`invalidateSessionCache(sessionId)` 清单个会话。
+- rules / fragments / docs 这些 `kits/` 下的文件，改完一般随会话重建生效（缓存按会话隔离）；manifest 本身的结构改动需要 invalidate。

package/kits/docs/evolclaw/agent.md

@@ -0,0 +1,49 @@
+# ec agent — EvolAgent 生命周期管理
+
+管理本机托管的 EvolAgent（创建、启停、配置、热重载）。触发词：创建/新建/列出/查看/启用/禁用/删除/热重载/改配置。
+
+## 子命令
+
+```bash
+# 列出所有 agent
+ec agent list
+
+# 查看 agent 详情（身份 + 配置 + 连接 + 会话 + 路径）
+ec agent show <aid>
+
+# 创建 agent（交互式）
+ec agent new [aid]
+
+# 创建 agent（非交互式，自动化场景）
+ec agent new <aid> --non-interactive --project <绝对路径> \
+  [--baseagent claude|codex|gemini] [--owner <aid>] \
+  [--name "<显示名>"] [--description "<text>"] [--force]
+
+# 启用 / 停用
+ec agent enable <aid>
+ec agent disable <aid>
+
+# 读 / 改单个配置字段（支持点路径，如 active_baseagent）
+ec agent get <aid> <key>
+ec agent set <aid> <key> <val>
+
+# 改 agent 名称（更新 agent.md 并重新上传）
+ec agent rename <aid> "<name>"
+
+# 热重载配置（无参数 = 全量 resync：扫磁盘，新增上线/删除下线/修改热更新）
+ec agent reload [aid]
+
+# 删除 agent（--purge 连数据一并清除）
+ec agent delete <aid> [--purge]
+```
+
+## 非交互创建必填项
+
+`ec agent new <aid> --non-interactive` 时：
+- 必填：`--project <absolute path>`
+- 可选：`--baseagent`（默认 PATH 中第一个可用项）、`--owner`、`--name`、`--description`、`--force`（覆盖已有 config.json）
+
+## 通用约定
+
+- `--format json` — 输出 JSON
+- `--help` / `-h` — 各子命令均支持，查看详细用法

package/kits/docs/evolclaw/aid.md

@@ -0,0 +1,49 @@
+# ec aid — AID 身份管理
+
+管理本地 AID 身份（证书、私钥、agent.md 名片），以及远程探测对端 AID。触发词：身份/证书/名片/探测对端/创建身份。
+
+## 子命令
+
+```bash
+# 列出本地所有 AID（实测 sign+verify）
+ec aid list [筛选选项] [--no-verify]
+
+# 查看本地 AID 详情（证书有效期、私钥状态、签名能力）
+ec aid show <aid>
+
+# 创建新 AID 身份
+ec aid new <aid>
+
+# 远程探测 AID（是否存在 + 网关 + agent.md）
+ec aid lookup <aid>
+
+# agent.md 名片：签名上传 / 下载验签
+ec aid agentmd put <aid>
+ec aid agentmd get <aid>
+
+# 删除指定本地 AID（无网络注销）
+ec aid delete <aid>
+```
+
+## list 筛选选项
+
+不指定 = 列出 mine + broken + peer-cert（隐藏 no-cert）。可组合：
+- `--mine` — 仅本地可用身份（实测可签名+验签通过）
+- `--broken` — 仅有私钥但不可用（公钥不匹配 / 证书过期 / sign 失败）
+- `--peer-cert` — 仅对端 AID（无私钥，有公钥证书）
+- `--no-cert` — 仅无私钥无证书的孤儿目录
+- `--no-verify` — 跳过 sign+verify 实测，仅静态扫描（更快）
+
+输出图标：`🔑` 有私钥 · `✅` 实测可签名/验签 · `❌` 不可签名 · `⌛` 证书过期 · `📜` 有公钥证书 · `📄` 有 agent.md
+
+## delete 批量清理
+
+批量删除**默认 dry-run，加 `--yes` 才真正执行**：
+- `ec aid delete --orphan` — 清理无私钥的外部 AID 缓存
+- `ec aid delete --no-cert` — 清理无私钥也无公钥证书的孤儿目录
+- `ec aid delete --unrecoverable` — 清理云端公钥已变更、本地不可恢复的 AID
+
+## 通用约定
+
+- `--format json` — 输出 JSON
+- `--help` / `-h` — 各子命令均支持