evolcore 0.0.1 → 0.0.3

package/kits/docs/channels/aun.md

@@ -0,0 +1,65 @@
+# AUN 渠道
+
+> 知识性文档：AUN 渠道的配置、参数与特有机制。**不依赖当前会话渠道**——任意会话都可按需 Read。
+> 运行时"怎么发消息"由注入的 `[channel]` 段决定（aun 渠道用 `ec msg send` / `ec group send`），不在本文。
+> 群聊使用 `evolcore/group.md`；群文件使用 `evolcore/fs.md`。
+
+## 概述
+
+AUN 渠道把 agent 接入 AUN（Agent Union Network），对端以 **AID** 为身份标识（既是身份也是地址）。evolcore 通过 AUN SDK（`@agentunion/fastaun`）维护到 Gateway 的 WebSocket 长连接，支持私聊、群聊、文件、E2EE 加密。
+
+## 配置
+
+AUN 渠道是**隐式**的——它不写在 `channels[]` 数组里，而是从 agent 自身的 AID 自动创建。一个 agent 就是一个 AID，启动时 evolcore 用顶层 `aid` 字段隐式构造唯一的 aun 实例（`channel-loader.ts`）。所以真实的 agent config.json 里 `channels` 数组通常是空的（飞书等非 aun 渠道才往里加）。
+
+### agent 配置（`agents/<aid>/config.json`）
+
+```json
+{
+  "$schema_version": 1,
+  "aid": "myagent.agentid.pub",
+  "enabled": true,
+  "owners": ["owner.agentid.pub"],
+  "channels": [],
+  "active_baseagent": "claude"
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `aid` | agent 的 AID，**即 aun 渠道身份**（隐式创建，无需在 channels[] 声明） |
+| `enabled` | agent 是否启用 |
+| `owners` | owner 的 **AID** 列表（最高权限）；首个 owner 用于首次连接发欢迎消息 |
+| `admins` | admin 的 AID 列表 |
+| `channels` | 非 aun 渠道（飞书等）的实例数组；aun 不在此 |
+
+> `owners`/`admins` 用 **AID**，不是渠道原生 ID。
+
+### 进程级配置（`$EVOLCORE_HOME/config.json`）
+
+E2EE 加密种子是**进程级**的，所有 agent 共享，不在 agent config 里：
+
+```json
+{
+  "aun": {
+    "encryptionSeed": "<seed>"
+  }
+}
+```
+
+留空时 SDK 依次回退 `AUN_ENCRYPTION_SEED` 环境变量 → 默认 `'evol'`。
+
+> Gateway 不在配置里手填：连接时从 AID 自动发现（见下）。Keystore 默认落在 `$EVOLCORE_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 天内不重复探测）。缓存落在 **`$EVOLCORE_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），由 evolcore 从 agent.md 提取，不是 agent.md 本体。
+- **E2EE 加密**：可选端到端加密，回复默认跟随对端消息加密状态（密文回密文，明文回明文）；种子由进程级 `aun.encryptionSeed` 提供。
+- **断线重连**：SDK 内置退避策略自动重连。实时连接状态用 `ec watch aid` 查看（`ec aid` 是身份/证书管理，不显示连接状态）。
+- **群 ID 格式**：当前协议规范使用 `g-{slug}.issuer-domain` canonical 形式，输入也可接受本域简写 `g-{slug}` 或兼容形式 `g-{slug}@issuer-domain`。历史会话里可能仍出现 `group.{issuer}/{group_no}` 一类旧格式，运行时需兼容读取。
+- **群分发模式**：`dispatch_mode=broadcast|mention` 是群级配置，只决定哪些群消息进入 Agent LLM 上下文，不影响 AUN 协议层投递；被过滤消息仍应本地存档。
+- **身份体系**：对端以 AID 标识，关系层 peerKey 形如 `aun#alice.aid.pub`。

package/kits/docs/channels/feishu.md

@@ -0,0 +1,56 @@
+# 飞书渠道
+
+> 知识性文档：飞书渠道的配置、参数与特有机制。**不依赖当前会话渠道**——任意会话都可按需 Read（在 aun 会话里也可查飞书）。
+> 运行时"怎么发消息"由注入的 `[channel]` 段决定（飞书是 evolcore 自动回复，agent 不调 CLI），不在本文。
+
+## 概述
+
+飞书渠道通过 evolcore 的 feishu channel 插件接入，对端以飞书 `user_id`（如 `ou_xxx`）为身份标识。支持单聊/群聊收发、合并转发解析、富文本卡片、文件/图片/视频消息。
+
+## 配置
+
+飞书渠道按 **per-agent** 配置，写在 `agents/<aid>/config.json` 的 `channels` 数组里。每个元素是一个独立实例，靠 `name` 区分；同一 agent 可配多个飞书实例。
+
+```json
+{
+  "aid": "myagent.aid.pub",
+  "channels": [
+    {
+      "type": "feishu",
+      "name": "main",
+      "enabled": true,
+      "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`：已废弃，仅为旧配置兼容保留；飞书继续按 Markdown/post 消息发送。
+
+## 特有机制
+
+- **合并转发解析**：飞书的 `merge_forward` 消息会被自动展开为文本注入上下文（含"以下是引用的原消息"包裹）。
+- **交互卡片**：命令和交互请求可使用飞书卡片发送；卡片按钮**仅发起者可操作**，他人点击返回提示。
+- **身份体系**：对端以 `user_id` 标识，关系层 peerKey 形如 `feishu#ou_xxx`。
+- **自动回复**：飞书是非 aun 渠道，回复由 evolcore 自动完成，agent 无需调用 `ec msg send`。

package/kits/docs/context-assembly.md

@@ -0,0 +1,366 @@
+# 上下文组装机制（manifest）
+
+ECK 把"每条消息该给 base agent 看哪些上下文"这件事，交给一份 **manifest** 声明式描述，由 `renderKitSections`（`src/agents/kit-renderer.ts`）在每次处理消息时执行。本文是这套机制的完整参考。
+
+> 本文是按需载入文档。日常对话不需要读它——只有在排查"为什么某段上下文没出现/出现了"、要改 manifest、或要看实际渲染结果时才 Read。
+
+## 三个阶段
+
+evolcore 收到消息 → 构造一份 **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 只加载一次并缓存。
+
+## 多 manifest：按会话原型（sessionType）选清单
+
+不同**会话原型**加载不同的 manifest 文件，各自走同一引擎、同一两级覆盖机制：
+
+| 会话原型（`session.sessionType`） | manifest 文件 | 用途 |
+|------|------|------|
+| `main`（默认） | `eck_manifest.json` | 主会话，完整上下文 |
+| `auxiliary` | `eck_manifest.auxiliary.json` | 辅助会话（双会话模式），精简上下文 |
+| 未来：`approval` / `goal` / ... | `eck_manifest.<type>.json` | 权限审批 / 目标管理等专用会话 |
+
+**映射由 agent config 的 `sessionManifests` 字段定义**（走 config 分级覆盖：关系/环境/agent 级）：
+
+```jsonc
+// $AGENT_DIR/config.json
+{
+  "sessionManifests": {
+    "main": "eck_manifest.json",              // 缺省可省略，兜底就是它
+    "auxiliary": "eck_manifest.auxiliary.json"
+  }
+}
+```
+
+渲染时按 `session.sessionType`（缺省 `'main'`）查 `sessionManifests`，取不到则回退 `eck_manifest.json`。
+**每个 manifest 文件各自两级合并**（`$KITS/<file>` + `$ECK/<file>`），互不干扰。
+
+## section 字段
+
+manifest 是 `{ "$schema_version": 1, "sections": [...] }`。每个 section：
+
+| 字段 | 必填 | 含义 |
+|------|------|------|
+| `id` | ✓ | 唯一标识，覆盖合并的键 |
+| `type` | ✓ | `file`（单文件）或 `directory`（整目录） |
+| `file` | type=file | 文件路径，可含 `$NAME` / `{{key}}` |
+| `path` | type=directory | 目录路径 |
+| `pattern` | | 目录匹配 glob，默认 `*.md`（支持 `*` 和 `{a,b}`） |
+| `maxFiles` | | type=directory：最多加载文件数，默认 20。超出停止加载并注入截断说明 |
+| `maxBytes` | | type=directory：最多加载总字节，默认 40960（40KB）。超出停止加载并注入截断说明（至少保留 1 个文件） |
+| `order` | ✓ | 排序，**升序**决定上下文中出现的先后 |
+| `needsInjection` | ✓ | `true`=按模板渲染（解析 `{{}}` 条件与变量）；`false`=原样读入 |
+| `when` | ✓ | 加载条件，`"always"` 或条件对象（见下） |
+| `enabled` | | `false` 时整段跳过 |
+| `loop` | | 三段式循环：`{ forEach, childFile, separator? }`。有 loop 时 file 作 wrapper，见"三段式循环" |
+| `description` | | 调试输出里的人类可读标签 |
+
+### 三段式循环（wrapper + forEach + child）
+
+批量数据（如一批消息）用 `loop` 字段做"包裹层 + 循环体"渲染，避免手写重复模板：
+
+```jsonc
+{
+  "id": "batch-messages",
+  "type": "file",
+  "file": "$KITS_.../batch-wrapper.md",   // ① wrapper：包裹模板，含 {{@loop}} 占位
+  "loop": {
+    "forEach": "items",                    // ② 循环 vars 里的数组变量
+    "childFile": "$KITS_.../batch-item.md", // ③ 每元素渲染的子模板
+    "separator": "\n"                      // 元素间分隔符，默认 "\n"
+  },
+  "needsInjection": true,
+  "order": 5,
+  "when": "always"
+}
+```
+
+**wrapper 模板**（`{{@loop}}` 处填入循环结果）：
+```
+【批次 剩余{{remainingInQueue}}条 | 主队列{{pendingCount}}】
+{{@loop}}
+【批次结束】
+```
+
+**childFile 模板**（每个元素，可访问元素字段 + 外层 vars + `{{@index}}`）：
+```
+[{{@index}}] {{peerName}}: {{content}}
+```
+
+**渲染规则**：
+- 对 `vars[forEach]` 数组每个元素渲染 childFile（对象元素 → 字段可用 `{{field}}`；标量 → `{{.}}`），以 `separator` 连接
+- wrapper 单独渲染（其变量如 `remainingInQueue` 来自 vars），`{{@loop}}` 位置**字面量填入**循环结果 → 循环结果不被二次解析
+- childFile 内可再嵌套 `{{#each}}` 或另一个占位，支持多层
+- 空数组 / 非数组 → 循环结果为空串
+- wrapper 不含 `{{@loop}}` → 循环结果追加到 wrapper 末尾（容错）
+
+> **消息渲染层的 loop**：`eck_message_manifest.json` 里的 loop 段是**批次包裹层**——
+> child 由 message-renderer 的逐条渲染（`renderOneItem`，自带 content 哨兵）产出，
+> 用户消息文本里的 `{{}}` 不会被二次解析。批次 vars（remainingInQueue 等）从 sessionVars 透传。
+> 详见 `prompt-loading-architecture.md`。
+
+### 清单顶层字段
+
+除 `sections` 外，manifest 顶层还支持全局限额（总闸，跨所有段累计）：
+
+| 字段 | 默认 | 含义 |
+|------|------|------|
+| `$schema_version` | — | 版本号 |
+| `mode` | patch | `patch`（合并）/ `replace`（完全替换），见"合并与覆盖" |
+| `totalMaxFiles` | 50 | 整个清单渲染最多文件数。达到后停止加载后续所有段 |
+| `totalMaxBytes` | 102400（100KB） | 整个清单渲染最多总字节。达到后停止加载后续所有段 |
+
+## 目录加载限额（安全保护）
+
+`type: directory` 段加载整个目录，若目录内容失控会撑爆提示词。两层限额保护：
+
+- **单目录限额**（`maxFiles` 20 / `maxBytes` 40KB）：单个目录段最多加载多少。超出时停止加载该目录后续文件，并在该段末尾注入一行截断说明：
+  `[注意] 目录 $KITS_RULES 未完整加载：N 个文件未加载（达文件数上限 20 个）。`
+- **总闸限额**（`totalMaxFiles` 50 / `totalMaxBytes` 100KB）：整个清单所有段加起来的上限。达到后停止加载后续所有命中段，末尾注入总截断说明，**带上未加载的 section id 集合**：
+  `[注意] 上下文清单总量超限（>50 文件 / >100KB），以下 section 未加载：goal-fragment, extra-docs。`
+
+> **注**：字节按文件原始内容（`rawContent`）计，不含渲染后变化，也不含截断说明行本身。
+> 单目录"至少保留 1 个文件"——避免单个超大文件导致整段为空。
+> 截断信息同时写入调试输出（`manifest-*.md`），便于排查。
+
+> **现状**：当前唯一目录段 `$KITS_RULES` = 6 文件 / ~18KB，远低于默认限额，不受影响。
+> 新增规则文档时注意别让该目录逼近 40KB。
+
+## 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。
+
+### 覆盖示例
+
+禁用某段：
+
+```json
+{ "sections": [ { "id": "venue-client", "enabled": false } ] }
+```
+
+改加载条件（仅 owner/admin 才载入对端档案）：
+
+```json
+{ "sections": [ { "id": "peer-profile", "when": { "var": "peerRole", "in": ["owner", "admin"] } } ] }
+```
+
+新增自定义段：
+
+```json
+{
+  "sections": [
+    {
+      "id": "my-custom-context",
+      "type": "file",
+      "file": "$AGENT_DIR/custom/my-rules.md",
+      "order": 25,
+      "needsInjection": false,
+      "when": "always",
+      "description": "我的自定义规则"
+    }
+  ]
+}
+```
+
+完全替换（忽略基础 manifest）：
+
+```json
+{ "$schema_version": 1, "mode": "replace", "sections": [ ... ] }
+```
+
+## 路径与模板渲染
+
+### 路径占位符（所有 section 的 file/path）
+
+- `$NAME`（大写）→ 从 vars 取真值，如 `$KITS_DOCS` → 包内文档目录。
+- `{{key}}` → 从 vars 取真值，如 `{{chatType}}` → `private`，`{{peerKey}}` → `aun#alice.aid.pub`。
+
+manifest 中常用路径变量的展开值：
+
+| 变量 | 展开为 |
+|------|--------|
+| `$PACKAGE_ROOT` | evolcore 包根 |
+| `$EVOLCORE_HOME` | 用户数据根（默认 `~/.evolcore`） |
+| `$KITS` | `$PACKAGE_ROOT/kits` |
+| `$KITS_RULES` | `$KITS/rules` |
+| `$KITS_DOCS` | `$KITS/docs` |
+| `$KITS_TEMPLATES` | `$KITS/templates` |
+| `$KITS_FRAGMENTS` | `$KITS_TEMPLATES/system-fragments` |
+| `$ECK` | `$EVOLCORE_HOME/eck` |
+| `$AGENT_DIR` | `$EVOLCORE_HOME/agents/<selfAid>` |
+| `$PERSONAL_DIR` | `$AGENT_DIR/personal` |
+| `$RELATIONS_DIR` | `$AGENT_DIR/relations` |
+| `$VENUES_DIR` | `$AGENT_DIR/venues` |
+
+任一占位符解析为空 → 该 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 由 evolcore 在 `message-processor.ts` 按当前会话构造。分两类：
+
+**路径类**（供占位符展开成真实路径）：
+`EVOLCORE_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/member/visitor/自定义角色/none）/ 类型（human/agent） |
+| `groupId` | 群 ID（群聊时） |
+| `chatType` | `private` / `group` / `null`(coding) |
+| `channel` | 渠道类型（aun/feishu/...）|
+| `mentionMode` | 群 @ 处理模式（mention-only/disabled） |
+| `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 | `when: "always"` | rules/ 核心规则、session 参数 |
+| **按条件自动加载** | manifest | `when` 条件 + 路径存在性 | 身份层（chatType 非空时）、对端档案（peerKey 非空时） |
+| **按需加载** | agent 自主 | agent 在对话中主动 Read 文件 | 查阅 `$KITS_DOCS/` 下的详细参考文档 |
+
+前两种由 manifest 控制，第三种由 agent 根据各层文档中的"按需加载指引"自主决定。
+
+## 默认 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 | relation-group-profile | `$RELATIONS_DIR/{{peerKey}}/profile.md` | groupId≠null | ✗ |
+| 44 | venue-client | `$KITS_DOCS/venues/client-{{clientType}}.md` | clientType≠null | ✗ |
+| 50 | channel-layer | fragment | channel≠null | ✓ |
+| 55 | commands | 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 为空而落选）。
+
+## 环境层文档目录结构
+
+venue-* 段从随包发布的通用文档（只读）取文件：
+
+```
+$KITS_DOCS/venues/                  通用环境文档（随包发布，只读）
+├── private.md                      单聊场景通用指引
+├── group.md                        群聊场景通用指引
+├── aun-private.md                  AUN 单聊特有
+├── aun-group.md                    AUN 群聊特有
+├── feishu-private.md               飞书单聊特有
+├── feishu-group.md                 飞书群聊特有
+├── client-desktop.md               桌面端环境
+├── client-mobile.md                移动端环境
+└── ...
+```
+
+> **注意**：具体群/私聊实例的 profile 数据落**关系层** `$RELATIONS_DIR/<peerKey>/profile.md`，
+> 由 `relation-group-profile` 段注入，不在 venues 目录。
+
+## 输出结构
+
+所有命中 section 的文件内容拼成一个块，注入 system prompt：
+
+```
+<system-reminder>
+EvolCore 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` 调试文件（见下）。
+
+## 调试机制（看实际渲染结果）
+
+每次渲染都把结果落盘到 **`$EVOLCORE_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/eck_templates/GUIDE.template.md

@@ -0,0 +1,22 @@
+# Agent 查阅指南
+
+本文件是 {{SELF_AID}} 的个人查阅指南。
+
+## 查阅优先级
+
+1. `$KITS_RULES`（自动加载）— ECK 机制骨架
+2. `$AGENT_INDEX/INDEX.md`（本目录）— 个人索引
+3. `$KITS_DOCS/INDEX.md` — evolcore 级文档索引
+4. 按索引中的路径 Read 具体文档
+
+## 路径解析
+
+遇到 `$名称` 时：
+1. 查 `$ECK/path-registry.md` 获取实际路径
+2. 如果实例文件中没有，查 `$KITS_DOCS/path-registry.md` 了解派生规则
+
+## 索引维护
+
+当以下范围内有文档变动时，更新本索引：
+- `{{CURRENT_PROJECT}}`
+- `{{AGENT_DIR}}`

package/kits/docs/eck_templates/INDEX.template.md

@@ -0,0 +1,28 @@
+# Agent 索引
+
+本文件是 {{SELF_AID}} 的 agent 级文档索引。
+
+## 项目文档
+
+| 文档 | 路径 | 说明 | 最后更新 |
+|------|------|------|----------|
+| — | — | （初始化后由 agent 维护） | — |
+
+## 个人档案
+
+| 文档 | 路径 | 说明 | 最后更新 |
+|------|------|------|----------|
+| 人格档案 | `$SELF_DIR/persona.md` | 行为规范与人格定义 | {{CREATED_AT}} |
+| 工作记忆 | `$SELF_DIR/memory/working.md` | 短期关注点 | {{CREATED_AT}} |
+
+## 关系档案
+
+| 对端 AID | 路径 | 最后交互 |
+|----------|------|----------|
+| — | — | — |
+
+## 场所档案
+
+| 场所 | 路径 | 说明 |
+|------|------|------|
+| — | — | — |

package/kits/docs/eck_templates/path-registry.template.md

@@ -0,0 +1,33 @@
+# 路径注册表实例
+
+本文件记录运行时解析出的实际路径值。由 evolcore 初始化时生成。
+
+## 基础路径
+
+| 名称 | 实际路径 |
+|------|----------|
+| `$EVOLCORE_HOME` | {{EVOLCORE_HOME}} |
+| `$PACKAGE_ROOT` | {{PACKAGE_ROOT}} |
+| `$CURRENT_PROJECT` | {{CURRENT_PROJECT}} |
+
+## 派生路径
+
+| 名称 | 实际路径 |
+|------|----------|
+| `$KITS` | {{KITS}} |
+| `$KITS_RULES` | {{KITS_RULES}} |
+| `$KITS_DOCS` | {{KITS_DOCS}} |
+| `$KITS_TEMPLATES` | {{KITS_TEMPLATES}} |
+| `$ECK` | {{ECK}} |
+| `$AGENT_DIR` | {{AGENT_DIR}} |
+| `$SELF_DIR` | {{SELF_DIR}} |
+| `$RELATIONS_DIR` | {{RELATIONS_DIR}} |
+| `$VENUES_DIR` | {{VENUES_DIR}} |
+| `$AGENT_INDEX` | {{AGENT_INDEX}} |
+
+## 外部依赖
+
+| 名称 | 实际路径 | 状态 |
+|------|----------|------|
+| `$KITE` | {{KITE}} | {{KITE_STATUS}} |
+| `$AUN_SDK_CORE` | {{AUN_SDK_CORE}} | {{AUN_SDK_STATUS}} |

package/kits/docs/eck_templates/runtime.template.md

@@ -0,0 +1,19 @@
+# 运行时配置
+
+## 基本信息
+
+- AID: {{SELF_AID}}
+- 名称: {{AGENT_NAME}}
+- 创建时间: {{CREATED_AT}}
+
+## 运行时参数
+
+- 模型: {{MODEL_ID}}
+- 推理强度: {{EFFORT_LEVEL}}
+- 权限模式: {{PERMISSION_MODE}}
+
+## 行为配置
+
+- 自我总结: {{SELF_SUMMARY_ENABLED}}
+- 空闲总结间隔: {{IDLE_SUMMARY_MINUTES}} 分钟
+- 每日总结 token 预算: {{DAILY_SUMMARY_BUDGET}}

package/kits/docs/evolcore/INDEX.md

@@ -0,0 +1,68 @@
+# EvolCore 命令集目录
+
+所有 `ec` 命令集的专属索引：用途、触发词、适用场景、详细文档。
+运行时 evolcore 会通过 `commands` fragment 按当前场景（有无 peer/group、对端角色）
+注入一张精简能力卡，指向本目录下对应文档；需要完整用法时 Read 对应文档。
+
+> 对外通信命令以自己的 AID 为发送者；当前渠道是否需要 CLI 回复，以运行时注入的
+> `channel` 规则为准。参数不是全局通用的：`--format json` 仅用于对应帮助中明确支持的命令，
+> `--app <name>` 仅用于消息 pull/ack、消费类 RPC 和明确支持 app slot 的文件操作。
+
+## 如何使用本索引
+
+1. **遇到触发词**（用户提到"费用/用量/创建/查群/上传文件"等）→ Ctrl+F 本文档找触发词 → 定位命令集 → Read 对应文档
+2. **不确定有没有命令**时，直接 `ec <猜测的子命令> --help` 试一下（如 `ec stats --help`）
+3. **已知场景需求**（如"要给对端发消息"）→ 看下方分类表 → 定位到对应命令集
+
+## 服务运维类（本地，无需 AUN）
+
+| 命令 | 用途 | 触发词 |
+|------|------|--------|
+| `ec --version` / `-v` / `-V` | 查看版本号 | 版本 |
+| `ec restart` | 重启服务（含自动升级检查） | 重启 |
+| `ec status` | 查看运行状态、进程、会话、渠道连接 | 状态/查看状态 |
+| `ec logs` | 查看日志（`--level` `--module` `--raw` `--no-color`） | 日志/查看日志 |
+| `ec diagnose` | 诊断启动环境 | 诊断/环境诊断 |
+
+## 对外通信 / 网络类（连 AUN，以 AID 为发送者）
+
+| 命令集 | 用途 | 触发词 | 适用场景 | 文档 |
+|--------|------|--------|----------|------|
+| `ec msg` | 私聊收发消息 | 回复/发消息/拉取/撤回/查在线 | 有对端（peerId） | `msg.md` |
+| `ec group` | 群聊收发与群管理 | 群发/建群/邀请/踢人/退群/群成员/角色/封禁/规则 | 群聊（groupId） | `group.md` |
+| `ec group rules` | 群规则文件发布与上下文注入 | 群规则/工作流程/职责分工/rules.md/发布规则 | AUN 群聊（groupId） | `group-rules.md` |
+| `ec aid` | AID 身份管理 | 身份/证书/名片/探测对端 | 任意有渠道场景 | `aid.md` |
+| `ec fs` | AUN 文件系统统一入口 | 上传/下载/看文件/列目录/删文件/配额/群空间 | 任意有渠道场景 | `fs.md` |
+| `ec storage` | 文件存储底层调试入口 | storage 调试/旧命令/底层上传下载 | 任意有渠道场景 | `storage.md` |
+| `ec agent` | EvolAgent 生命周期 | 创建/启停/热重载/改配置 | 管理员（owner/admin） | `agent.md` |
+| `ec contact` | Contact Book 与访问控制 | 拉黑/解除拉黑/查拉黑 | Agent owner/admin | `contact.md` |
+| `ec rpc` | 底层 AUN RPC（逃生通道） | 直接调协议方法 | 高级/兜底 | `rpc.md` |
+
+## 会话自管理类（不连 AUN，操作当前会话）
+
+| 命令集 | 用途 | 触发词 | 文档 |
+|--------|------|--------|------|
+| `ec ctl` | 当前会话工具 | 主动发消息/文件、重命名、队列、项目路径、会话状态 | `ctl.md` |
+
+## 本地工具类（不连 AUN，操作本地配置）
+
+| 命令集 | 用途 | 触发词 | 文档 |
+|--------|------|--------|------|
+| `ec model` | 模型与推理强度管理（按作用域持久化） | 切模型/列模型/当前模型/模型详情/改强度/诊断网关 | `model.md` |
+| `ec response` | 响应模式管理（按作用域持久化） | 切换响应模式/列响应模式/看当前模式/改响应配置 | `response.md` |
+| `ec config` | 配置体系底层入口（读写/快照/回滚） | 看配置/改配置/查字段/查schema/校验/快照/回滚/历史/启动记录 | `config.md` |
+| `ec stats` | Token 用量与费用统计 | 用量/费用/统计/预算/token/cost | `stats.md` |
+| `ec trigger` | 定时与事件触发器管理（创建用 `create`，`set` 为兼容别名） | 触发器/定时任务/cron/提醒/定时检查/自动执行/巡检/禁用 trigger/删除 trigger | `trigger.md` |
+| `ec trigger event` | EventBus 事件目录 | 事件触发/事件目录/EventBus/source.type=event/filter.match | `event.md` |
+
+## 开发者工具（非 agent 会话能力）
+
+| 命令 | 用途 | 说明 |
+|------|------|------|
+| `ec bench` | AUN 消息系统性能基准测试 | CLI 工具，agent 一般不主动调用；`ec bench --help` 查看用法 |
+
+## 其他
+
+| 文档 | 说明 |
+|------|------|
+| `self-summary.md` | 自我总结流程指南 |