evolclaw 3.1.3 → 3.1.5

package/kits/eck_manifest.json

@@ -4,92 +4,128 @@
     {
       "id": "rules",
       "type": "directory",
-      "path": "$PACKAGE_ROOT/kits/rules",
+      "path": "$KITS_RULES",
       "order": 10,
       "needsInjection": false,
       "when": "always",
-      "description": "ECK 核心规则（自动载入）"
+      "description": "ECK 核心规则（自动加载）"
     },
     {
       "id": "identity-layer",
       "type": "file",
-      "file": "$PACKAGE_ROOT/kits/templates/system-fragments/identity.md",
+      "file": "$KITS_FRAGMENTS/identity.md",
       "order": 20,
       "needsInjection": true,
-      "when": {
-        "var": "scene",
-        "neq": "coding"
-      },
+      "when": { "var": "chatType", "neq": null },
       "description": "身份层：我是谁"
     },
+    {
+      "id": "persona",
+      "type": "file",
+      "file": "$PERSONAL_DIR/persona.md",
+      "order": 21,
+      "needsInjection": false,
+      "when": { "var": "chatType", "neq": null },
+      "description": "人格档案（persona.md）"
+    },
+    {
+      "id": "working-memory",
+      "type": "file",
+      "file": "$PERSONAL_DIR/memory/working.md",
+      "order": 22,
+      "needsInjection": false,
+      "when": { "var": "chatType", "neq": null },
+      "description": "当前关注（working memory）"
+    },
     {
       "id": "relation-layer",
       "type": "file",
-      "file": "$PACKAGE_ROOT/kits/templates/system-fragments/relation.md",
+      "file": "$KITS_FRAGMENTS/relation.md",
       "order": 30,
       "needsInjection": true,
-      "when": {
-        "var": "scene",
-        "in": ["private", "group"]
-      },
+      "when": { "var": "chatType", "in": ["private", "group"] },
       "description": "关系层：跟我聊天的是谁"
     },
     {
       "id": "peer-profile",
       "type": "file",
-      "file": "$EVOLCLAW_HOME/agents/{{selfAid}}/relations/{{peerKey}}/profile.md",
+      "file": "$RELATIONS_DIR/{{peerKey}}/profile.md",
       "order": 35,
       "needsInjection": false,
-      "when": {
-        "var": "peerKey",
-        "neq": null
-      },
+      "when": { "var": "peerKey", "neq": null },
       "description": "当前对端的关系档案"
     },
     {
-      "id": "venue-layer",
+      "id": "venue-fragment",
       "type": "file",
-      "file": "$PACKAGE_ROOT/kits/templates/system-fragments/venue.md",
+      "file": "$KITS_FRAGMENTS/venue.md",
       "order": 40,
       "needsInjection": true,
-      "when": {
-        "var": "chatType",
-        "neq": null
-      },
-      "description": "环境层：我在什么场景下"
+      "when": { "var": "chatType", "neq": null },
+      "description": "环境层模板（基础参数）"
+    },
+    {
+      "id": "venue-chattype",
+      "type": "file",
+      "file": "$KITS_DOCS/venues/{{chatType}}.md",
+      "order": 41,
+      "needsInjection": false,
+      "when": { "var": "chatType", "neq": null },
+      "description": "场景通用文档（private/group）"
+    },
+    {
+      "id": "venue-channel-chattype",
+      "type": "file",
+      "file": "$KITS_DOCS/venues/{{channel}}-{{chatType}}.md",
+      "order": 42,
+      "needsInjection": false,
+      "when": { "var": "chatType", "neq": null },
+      "description": "渠道+场景文档（如 feishu-group）"
+    },
+    {
+      "id": "venue-group-profile",
+      "type": "file",
+      "file": "$VENUES_DIR/{{channel}}#{{groupId}}/profile.md",
+      "order": 43,
+      "needsInjection": false,
+      "when": { "var": "groupId", "neq": null },
+      "description": "具体群环境文档"
+    },
+    {
+      "id": "venue-client",
+      "type": "file",
+      "file": "$KITS_DOCS/venues/client-{{clientType}}.md",
+      "order": 44,
+      "needsInjection": false,
+      "when": { "var": "clientType", "neq": null },
+      "description": "客户端环境文档"
     },
     {
       "id": "channel-layer",
       "type": "file",
-      "file": "$PACKAGE_ROOT/kits/templates/system-fragments/channel.md",
+      "file": "$KITS_FRAGMENTS/channel.md",
       "order": 50,
       "needsInjection": true,
-      "when": {
-        "var": "channel",
-        "neq": null
-      },
-      "description": "渠道层：我通过什么通信"
+      "when": { "var": "channel", "neq": null },
+      "description": "渠道层：通信渠道及能力"
     },
     {
-      "id": "eckruntime",
+      "id": "session",
       "type": "file",
-      "file": "$PACKAGE_ROOT/kits/templates/system-fragments/eckruntime.md",
+      "file": "$KITS_FRAGMENTS/session.md",
       "order": 60,
       "needsInjection": true,
       "when": "always",
-      "description": "运行时参数"
+      "description": "会话层：当前会话实例状态"
     },
     {
       "id": "baseagent",
       "type": "file",
-      "file": "$PACKAGE_ROOT/kits/templates/system-fragments/baseagent.md",
+      "file": "$KITS_FRAGMENTS/baseagent.md",
       "order": 70,
       "needsInjection": true,
-      "when": {
-        "var": "baseAgent",
-        "neq": null
-      },
+      "when": { "var": "baseAgent", "neq": null },
       "description": "Base Agent 特定配置"
     }
   ]
-}
+}

package/kits/rules/01-overview.md

@@ -57,7 +57,7 @@ AUN 把 agent 当网络主体（具备社会人属性:身份/通信/自主），
            │                  │
      Evol 前端            EvolClaw
   (App/Web/Desktop)        Channel 适配层（AUN/飞书/微信/...）
-   或其它 AUN 客户端       关系层 / 环境层 / 个人数据层 / 上下文注入
+   或其它 AUN 客户端       身份层 / 关系层 / 环境层 /  渠道层 / 会话层
                            Base Agent（Claude Code / Codex / Gemini/...）
 
 ```
@@ -69,7 +69,7 @@ EvolClaw 是一个 Node.js 项目，通过 `npm install -g evolclaw@latest` 安
 
 ### Evol
 
-Evol 是 AUN 原生的消息应用（App / Web / Desktop）——人和 agent 都是其中的主体。用户通过 Evol 与 agent 和其他人对话。
+Evol 是 AUN 原生的消息应用（App / Web / Desktop）——人和 agent 都是其中的主体。用户通过 Evol 与 agent以及其他人对话。
 
 ### Channel
 
@@ -102,13 +102,24 @@ ECK（EvolClaw Context Kit）是 EvolClaw 的上下文组装系统。你正在
 
 ### 上下文组装流程
 
-evolclaw 收到消息后，按场景决定加载哪些层：
+evolclaw 收到每条消息时，由一份**声明式 manifest** 决定加载哪些上下文段——不是写死的分支。
+每个 section 带 `when` 条件，evolclaw 按当前会话构造一组运行时变量（`chatType`、`channel`、
+`selfAid`、`peerKey` 等）逐段求值，命中的才按顺序拼进 system prompt（`needsInjection` 的段还会先做模板渲染）。
 
-| 场景 | 加载的层 |
-|------|----------|
-| coding | 仅 rules（不加载身份层、关系层） |
-| private | rules + 身份层 + 关系层（对端）+ 环境层 + 渠道层 |
-| group | rules + 身份层 + 关系层（群）+ 环境层 + 渠道层 |
+按场景，命中的段大致是：
+
+| 场景 | 命中的层/段 |
+|------|------------|
+| coding（无渠道） | rules + 会话层 + baseagent（身份/关系/环境/渠道层因无 channel、无身份而落选） |
+| private（私聊） | rules + 身份层 + 关系层（对端）+ 环境层 + 渠道层 + 会话层 + baseagent |
+| group（群聊） | rules + 身份层 + 关系层（群）+ 环境层 + 渠道层 + 会话层 + baseagent |
+
+> 会话层（session fragment）是 `when:always`、baseagent 段只要注入了 base agent 信息就加载——
+> 二者与 chatType 无关，每个场景都在；所以 coding 并非"仅 rules"。
+
+manifest schema、when 条件、合并覆盖、模板渲染、运行时变量目录，以及**实际渲染结果的调试输出**
+（`$EVOLCLAW_HOME/data/eck-debug/` 下的 vars / context / fragments / manifest 四个文件）：
+详见 `$KITS_DOCS/context-assembly.md`。
 
 ## 术语
 
@@ -116,5 +127,4 @@ evolclaw 收到消息后，按场景决定加载哪些层：
 - **对端**：和你通信的主体
 - **本端（self）**：你自己
 - **用户**：对端中的人类一方
-- **环境（Venue）**：渠道 + 场景（私聊/群聊）构成的交互空间
-
+- **环境（Venue）**：渠道 + 场景（私聊/群聊）构成的交互空间

package/kits/rules/05-venue.md

@@ -1,6 +1,6 @@
-# 环境层：我在什么场景下
+# 环境层：当前对话场景
 
-环境层决定当前会话加载哪些信息。动态注入的 `scene` 标识当前场景类型，`venueKey`（`<channel>#<urlEncode(venueId)>`）是 venue 在所有渠道中的稳定标识。
+环境层决定当前会话加载哪些信息。动态注入的 `chatType` 标识当前聊天类型（private/group/null），`venueUid` 是场所唯一标识（预留）。
 
 ## 场景判定
 

package/kits/rules/06-channel.md

@@ -6,45 +6,41 @@
 
 | 位置 | 内容 |
 |------|------|
-| `$KITS_DOCS/channels/` | 各渠道的使用手册（只读，按需加载） |
+| `$KITS_DOCS/channels/` | 各渠道的**知识文档**：配置、参数、特有机制（只读，按需加载） |
 | `$AGENT_DIR/channels/` | 各渠道的运行时数据（可写） |
 
-## 通信规则
-
-与其他主体通信时，**必须调用 CLI 命令**发消息，不要把输出当成发送给对方的内容。
+> 运行时"当前渠道怎么发消息"由动态注入的 `[channel]` 段决定（见下方通信规则）；
+> `$KITS_DOCS/channels/` 是**不依赖当前渠道**的知识库，任意会话都可按需 Read 任意渠道文档。
 
-当前渠道的发消息命令已在上下文中注入（见 `[aun]` 或对应渠道块）。
+## 通信规则
 
-### 仅在无法获取 self-aid 时才用 `ec ctl send`
+与其他主体通信**必须调用 CLI 命令**（首选 `ec msg send <self-aid> <peer-id> "<text>"`），
+不要把模型输出当成发送给对方的内容。当前渠道的发消息命令已在上下文中注入（见 `[aun]` 或对应渠道块）。
 
-```bash
-ec ctl send "<text>"
-ec ctl send --encrypt "<text>"
-```
+> proactive 模式尤其注意：你直接输出的普通文本会被投影成"思考过程"实时展示给用户，
+> 它可见、但不入消息历史、也不是发给对端的回复。只有显式调用 `ec msg send` 对端才真正收到。
+> 拿不到 self-aid 时才退回 `ec ctl send "<text>"`（自动继承当前会话的 AID 和对端）。
 
 ### 命令返回值
 
 - 成功：`ok` 或包含 `✓ 已发送 ...` 的输出（exit 0）
 - 失败：`✗ ...` 错误信息（exit 非零）
 
-发送成功后**继续后续处理**。一次任务可能发 0 到多条消息，不要因为看到"已发送"就反复发送同一条消息。
-
-## Agent 管理命令
+发送成功后**继续后续处理**。一次任务可能发 0 到多条消息不要因为看到"已发送"就反复发送同一条消息。
 
-`evolclaw agent` — agent 全生命周期管理。
+## 命令集
 
-触发词：创建/新建/初始化、列出/查看、启用/禁用/删除、热重载、修改配置。
+所有命令以 `ec` 为前缀，以自己的 AID 为发送者。详细用法按需 Read 对应文档。
 
-详细参考：Read `$KITS_DOCS/evolclaw/AGENT_CMD.md`
-
-## 消息命令
-
-`evolclaw msg` / `evolclaw group` — 通信 CLI。
-
-| 聊天类型 | 详细文档 |
-|----------|----------|
-| private | `$KITS_DOCS/evolclaw/MSG_PRIVATE.md` |
-| group | `$KITS_DOCS/evolclaw/MSG_GROUP.md` |
+| 命令集 | 用途 | 触发词 | 详细文档 |
+|--------|------|--------|----------|
+| `ec msg` | 私聊收发消息 | 回复/发消息/拉取/撤回 | `$KITS_DOCS/evolclaw/msg.md` |
+| `ec group` | 群聊收发与群管理 | 群发/建群/邀请/踢人 | `$KITS_DOCS/evolclaw/group.md` |
+| `ec agent` | EvolAgent 生命周期 | 创建/启用禁用/热重载/改配置 | `$KITS_DOCS/evolclaw/agent.md` |
+| `ec aid` | AID 身份管理 | 身份/证书/名片/探测对端 | `$KITS_DOCS/evolclaw/aid.md` |
+| `ec storage` | 文件存储 | 上传/下载/配额 | `$KITS_DOCS/evolclaw/storage.md` |
+| `ec ctl` | 会话运行时自管理 | 切模型/推理强度/压缩/重启 | `$KITS_DOCS/evolclaw/ctl.md` |
+| `ec rpc` | 底层 AUN RPC（逃生通道） | 直接调协议方法 | `$KITS_DOCS/evolclaw/rpc.md` |
 
 共同约定：
 - 以自己的 AID 为发送者
@@ -52,6 +48,13 @@ ec ctl send --encrypt "<text>"
 - `--format json` 所有命令通用
 - `--app <name>` 指定应用 slot
 
-## 各渠道文档
+## 各渠道知识文档（按需加载）
+
+`$KITS_DOCS/channels/` 下每个渠道一份知识文档，内容是该渠道的**配置、参数、特有机制**——
+属于知识性内容，**不依赖**当前注入的渠道类型。需要了解某渠道怎么配置、有哪些参数、
+有哪些特别机制时，按需 Read 对应文档（在 aun 会话里也可查飞书，反之亦然）。
 
-不同渠道的详细通信规则和命令工具使用方式：Read `$KITS_DOCS/channels/` 中的对应文档。
+| 渠道 | 文档 | 触发词 |
+|------|------|--------|
+| AUN | `$KITS_DOCS/channels/aun.md` | aun 怎么配置/网关/E2EE/群 ID 格式/证书链 |
+| 飞书 | `$KITS_DOCS/channels/feishu.md` | 飞书怎么配置/appId/合并转发/卡片/user_id |

package/kits/templates/system-fragments/baseagent.md

@@ -1,2 +1,8 @@
 [baseagent]
-base-agent: {{baseAgentName}}
+baseAgentName: {{baseAgentName}} # 底层推理引擎（Claude Code / Codex / Gemini CLI）
+{{?baseAgentModel}}
+baseAgentModel: {{baseAgentModel}}
+{{/}}
+{{?agentSessionId}}
+agentSessionId: {{agentSessionId}} # 底层引擎的会话 ID（区别于 evolclaw sessionId）
+{{/}}

package/kits/templates/system-fragments/channel.md

@@ -1,5 +1,8 @@
 [channel]
-channel: {{channel}}
+channel: {{channel}} # 渠道类型：aun|feishu|wechat|dingtalk|qqbot|wecom
+{{?capabilities}}
+capabilities: {{capabilities}} # 当前渠道支持的能力
+{{/}}
 {{?peerId}}
 {{?channel=aun}}
 ec msg send {{selfAid}} {{peerId}} "<text>" [--encrypt] [--file <path> --as image|video|voice|file] [--link <url> --title "<title>"] [--payload '<json>']

package/kits/templates/system-fragments/identity.md

@@ -1,11 +1,11 @@
 [identity]
 {{?selfAid}}
-self-name: {{selfName}}
-self-aid: {{selfAid}}
+selfName: {{selfName}}
+selfAid: {{selfAid}}
 {{/}}
 {{?hasPersona}}
-persona: loaded
+hasPersona: active
 {{/}}
 {{?hasWorkingMemory}}
-working-memory: loaded
+hasWorkingMemory: active
 {{/}}

package/kits/templates/system-fragments/relation.md

@@ -1,11 +1,14 @@
 {{?peerKey}}
 [relation]
-peer-name: {{peerName}}
-peer-aid: {{peerId}}
-peer-role: {{peerRole}}
-peer-key: {{peerKey}}
+peerName: {{peerName}}
+peerId: {{peerId}} # 对端在当前渠道内的原生 ID
+peerRole: {{peerRole}} # owner|admin|guest|anonymous
+{{?peerType}}
+peerType: {{peerType}} # human 或 agent
+{{/}}
+peerKey: {{peerKey}} # 跨渠道唯一标识，格式 channel#urlEncode(peerId)
 {{/}}
 {{?groupId}}
 [relation]
-group-id: {{groupId}}
+groupId: {{groupId}}
 {{/}}

package/kits/templates/system-fragments/session.md

@@ -0,0 +1,27 @@
+[session]
+project: {{project}} # 项目目录名
+CURRENT_PROJECT: {{CURRENT_PROJECT}} # 项目完整路径
+sessionId: {{sessionId}} # evolclaw 会话 ID
+{{?sessionKey}}
+sessionKey: {{sessionKey}} # 会话路由键（channelType#urlEncode(channelId)#urlEncode(threadId)）
+{{/}}
+{{?sessionName}}
+sessionName: {{sessionName}}
+{{/}}
+sessionCreatedAt: {{sessionCreatedAt}}
+chatMode: {{chatMode}} # interactive=同步对话 / proactive=主动推送（输出静默）
+{{?permissionMode}}
+permissionMode: {{permissionMode}} # auto / bypass / request / edit / plan / noask / readonly
+{{/}}
+{{?threadId}}
+threadId: {{threadId}} # 同一会话内的子话题 ID（多话题路由时）
+{{/}}
+{{?readonly}}
+readonly: true — 禁止修改项目文件，如需生成文件请写入 .evolclaw/tmp/
+{{/}}
+{{?chatMode=proactive}}
+# proactive 模式：你的普通文本会作为"思考过程"实时展示给用户（可见，但不入消息历史、不是回复）。
+# 要正式回复对端，必须显式调用发送命令（命令集见 06-channel）。
+proactive-send: ec msg send {{selfAid}} {{peerId}} "<text>"   # 拿不到 self-aid 时退回 ec ctl send "<text>"
+proactive-file: ec msg send {{selfAid}} {{peerId}} --file <path> --as <image|video|voice|file>
+{{/}}

package/kits/templates/system-fragments/venue.md

@@ -1,4 +1,16 @@
 [venue]
+chatType: {{chatType}} # private|group
+EVOLCLAW_HOME: {{EVOLCLAW_HOME}} # 用户数据根目录（agents/sessions/logs）
+PACKAGE_ROOT: {{PACKAGE_ROOT}} # evolclaw 安装目录（kits/rules/docs）
 {{?venueUid}}
-venue-id: {{venueUid}}
+venueUid: {{venueUid}}
+{{/}}
+{{?dispatch}}
+dispatch: {{dispatch}} # 群分发模式：mention(被@才响应) / broadcast(所有消息都响应)
+{{/}}
+{{?clientType}}
+clientType: {{clientType}} # 客户端类型：desktop / web / mobile
+{{/}}
+{{?groupId}}
+groupId: {{groupId}}
 {{/}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolclaw",
-  "version": "3.1.3",
+  "version": "3.1.5",
   "description": "Lightweight AI Agent gateway connecting Claude Agent SDK to messaging channels (Feishu, ACP) with multi-project session management",
   "type": "module",
   "main": "dist/index.js",
@@ -11,6 +11,7 @@
   "files": [
     "dist/",
     "bin/",
+    "assets/",
     "!dist/experimental/",
     "kits/",
     "!kits/.kits-version",
@@ -21,19 +22,24 @@
   ],
   "scripts": {
     "dev": "tsx watch src/index.ts",
-    "build": "tsc && node -e \"const f='dist/cli/index.js',c=require('fs').readFileSync(f,'utf8');if(!c.startsWith('#!'))require('fs').writeFileSync(f,'#!/usr/bin/env node\\n'+c)\" && node -e \"try{require('child_process').execFileSync('chmod',['+x','dist/cli/index.js'])}catch{}\" && node -e \"require('fs').mkdirSync('dist/data',{recursive:true});require('fs').copyFileSync('src/data/error-dict.json','dist/data/error-dict.json')\"",
+    "build": "tsc && node -e \"const f='dist/cli/index.js',c=require('fs').readFileSync(f,'utf8');if(!c.startsWith('#!'))require('fs').writeFileSync(f,'#!/usr/bin/env node\\n'+c)\" && node -e \"try{require('child_process').execFileSync('chmod',['+x','dist/cli/index.js'])}catch{}\" && node -e \"require('fs').mkdirSync('dist/data',{recursive:true});require('fs').copyFileSync('src/data/error-dict.json','dist/data/error-dict.json')\" && node -e \"require('fs').cpSync('src/cli/watch-web/static','dist/cli/watch-web/static',{recursive:true})\"",
     "start": "node dist/index.js",
-    "test": "flock --nonblock /tmp/evolclaw-test.lock vitest run || { echo '\\n[ERROR] Another vitest instance is already running. Wait or kill it first.' >&2; exit 1; }",
+    "test": "vitest run",
     "test:watch": "vitest",
     "test:hooks": "tsx test-sdk-hooks.ts",
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
-    "@agentunion/fastaun": "^0.3.2",
-    "@anthropic-ai/claude-agent-sdk": "^0.2.100",
+    "@agentunion/fastaun": "^0.4.7",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.156",
+    "@anthropic-ai/sdk": "^0.100.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "cron-parser": "^5.5.0",
+    "dotenv": "^17.4.2",
     "image-type": "^6.0.0",
-    "qrcode-terminal": "^0.12.0"
+    "qrcode-terminal": "^0.12.0",
+    "ws": "^8.21.0",
+    "zod": "^4.0.0"
   },
   "optionalDependencies": {
     "@larksuiteoapi/node-sdk": "^1.59.0",
@@ -47,6 +53,7 @@
     "@types/form-data": "^2.2.1",
     "@types/node": "^25.5.0",
     "@types/qrcode-terminal": "^0.12.2",
+    "@types/ws": "^8.18.1",
     "@vitest/coverage-v8": "^4.1.0",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",

package/dist/aun/aid/lifecycle-log.js

@@ -1,33 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-import { resolvePaths } from '../../paths.js';
-function ensureDir(dir) {
-    fs.mkdirSync(dir, { recursive: true });
-}
-function logPath(aid) {
-    const aidName = aid.startsWith('@') ? aid.slice(1) : aid;
-    return path.join(resolvePaths().aidLogsDir, `${aidName}.jsonl`);
-}
-export function appendAidLifecycle(event) {
-    const filePath = logPath(event.aid);
-    ensureDir(path.dirname(filePath));
-    fs.appendFileSync(filePath, JSON.stringify(event) + '\n');
-}
-export function readAidLifecycle(aid, lastN = 50) {
-    const filePath = logPath(aid);
-    try {
-        const content = fs.readFileSync(filePath, 'utf-8');
-        const lines = content.trim().split('\n').filter(Boolean);
-        const events = [];
-        for (const line of lines.slice(-lastN)) {
-            try {
-                events.push(JSON.parse(line));
-            }
-            catch { }
-        }
-        return events;
-    }
-    catch {
-        return [];
-    }
-}