evolcore 0.0.27 → 0.0.29-test.0

package/kits/docs/AUTHORING.md

@@ -0,0 +1,314 @@
+# ECK 文档写作与维护指南
+
+> **读者：人与 Agent 两类。** ECK 由人机共同维护——人做设计判断，Agent 做具体增改。
+> 因此本文的规则要同时满足两个要求：人看得懂判据，Agent 能按判据执行。
+>
+> 相关文档：查阅文档见 `GUIDE.md`；manifest 注入机制见 `context-assembly.md`；路径与索引机制见 `$KITS_RULES/02-navigation.md`。
+
+---
+
+## 零、原则总览
+
+| 原则 | 防什么 | 可自动排查 |
+|------|--------|:---------:|
+| §一 文件位置 | 放错目录破坏机器约定 | ❌ |
+| §二 正交性 | 同一概念多处定义、随时间漂移 | 部分（grep） |
+| §三 注入成本 | `rules/` 膨胀，每轮白烧 token | ❌ |
+| §四 命名与路径 | 引用无法解析 | 部分 |
+| §五 可发现性 | 文档存在但找不到 | ❌ |
+| §六 引用完整性 | 悬空链接 / 语义失效 | 仅悬空可查 |
+| §七 粒度阈值 | 无意义碎片化 | ❌ |
+| §八 权威裁决 | 代码改了文档没改，不知信谁 | ❌ |
+| §九 示例一致性 | 照抄示例失败 | ❌ |
+
+**真正能自动排查的只有"悬空引用"一项**，其余全靠流程纪律——这是检查清单（§十）比看起来更重要的原因。
+
+---
+
+## 一、文件放哪里
+
+`kits/` 下的目录有明确分工，放错位置会破坏约定或让文档失去可发现性：
+
+| 目录 | 内容性质 | 谁读 | 能否放文档 |
+|------|---------|------|-----------|
+| `rules/` | 自动注入的机制骨架（01-06） | 每次会话自动加载 | ❌ 只放这 6 个 |
+| `docs/` | 按需 Read 的知识文档 | Agent 按需 | ✅ **人读的文档都放这里** |
+| `schemas/` | 代码消费的 schema 数据 | `schema-registry.ts` 扫描 | ❌ 只放 `*.schema.*.json` + `_meta.json` |
+| `templates/` | prompt 组装模板 | 渲染引擎 | ❌ 只放模板 |
+| `migrations/` | 迁移数据 | 迁移逻辑 | 仅 README 例外 |
+
+**判据**：`schemas/`、`templates/` 是**机器读的数据目录**，命名和格式有程序依赖。人类阅读的说明文档一律放 `docs/` 下对应子目录。在数据目录里放 `.md` 会破坏命名约定，也让后来者误判目录职责。
+
+`migrations/README.md` 是唯一被接受的反例——README 与其描述的数据同放是通用惯例，且它在子目录内，不污染顶层命名空间。
+
+### `templates/` 下的子目录
+
+模板按**被注入的会话类型**分子目录，不要平铺：
+
+| 子目录 | 用途 | 谁引用 |
+|------|------|--------|
+| `system-fragments/` | 主会话的系统提示词片段（identity / session / commands 等）；`memory.md` 例外，主会话与整理会话共用 | `eck_manifest.json`（`memory.md` 另被 `eck_manifest.memory.json` 引用） |
+| `message-fragments/` | 消息信封渲染片段 | `eck_message_manifest.json` |
+| `memory-consolidation/` | 整理会话（`sessionType=memory`）的 prompt | `eck_manifest.memory.json` |
+
+**`memory-consolidation/` 的结构**：`workflow.md`（整理流程）+ 五份模式手册（`notes.md` / `generalize.md` / `promote.md` / `profile.md` / `forget.md`）。命令、权限、禁止事项不在这里，而在主会话与整理会话共用的 `$KITS_FRAGMENTS/memory.md`（按 `sessionType` 分支渲染）。manifest 里**逐个文件列段**，不能用目录段——`pattern` 不支持变量插值（`manifest-engine.ts` 的 `matchGlob` 只做 `*` → `.*`），目录段会把六份文件一次性全灌进去。
+
+**这些文件不进 `docs/`**：它们是**每轮注入**的 prompt，不是按需 Read 的知识文档。放 `docs/` 会让人误以为可以惰性加载，改了却发现要么不生效、要么被重复注入。人读的机制说明在 `kits/docs/evolcore/memory-consolidation.md`。
+
+---
+
+## 二、正交：一个概念只有一个事实源
+
+这是本套文档体系最核心的规则（`00-导读.md` 已声明"每个概念只有一个唯一事实源"），执行时按下面的方法落地。
+
+### 先分类，再动笔
+
+写或改文档前，先判定它在讲哪一类内容：
+
+| 类别 | 内容 | 举例 |
+|------|------|------|
+| **格式/机制** | 数据结构、字段定义、协议语义、权限模型 | `protected_headers` 有哪些字段 |
+| **工具用法** | CLI 语法、参数、退出码、连接行为 | `ec menu-client --request-file` 怎么用 |
+| **具体任务** | 某个入口/场景的完整操作步骤 | 通过 menu exec 取某个 schema |
+
+**格式类只能有一个定义处**，其余文档引用它。工具类文档**不得重复定义格式**，只能写"格式见 XX"。
+
+### 判定重叠的实际做法
+
+遇到两份文档疑似重复时，逐条列出两边的章节，标出讲同一件事的部分：
+
+```
+内容项                        A 文档   B 文档   处置
+消息类型定义                  ✅ 完整  ✅ 部分   归 A，B 删掉改引用
+CLI 参数语义                  ✅ 完整  ❌        归 B
+鉴权机制                      ❌       ✅ 完整   归 A
+```
+
+只有**明确归属给某一方**的部分才能保留，另一方改为一句引用。做不到这一条，两份文档就会随时间继续漂移。
+
+### 常见的重叠陷阱
+
+- 两份文档都写"默认值/缺省行为" → 归格式方
+- 两份文档都举 JSON 示例 → 归格式方，工具方最多留最简的可复制样例
+- 两份文档都写权限要求 → 归格式方（协议层），工具方只写"入口的 token/owner 校验"
+
+---
+
+## 三、注入成本：内容默认放 docs/
+
+ECK 的 manifest 机制决定了**不同位置的内容有不同的成本量级**。机制完整说明见 `context-assembly.md`（唯一事实源，本文不重复定义），这里只给由此得出的写作判据。
+
+### 成本模型
+
+| 位置 | 何时消耗 token | 成本量级 |
+|------|--------------|---------|
+| `rules/` | **每次对话都注入**（当前 6 文件约 18KB） | 每轮都付 |
+| `docs/` | 仅被 agent Read 时 | 按需付，多数对话为零 |
+
+### 判据
+
+> **内容默认放 `docs/`。只有"每个会话、每轮都需要，不注入就会做错事"的内容才升到 `rules/`。**
+
+写入 `rules/` 前自问：**这条信息如果不注入，agent 会在多少比例的对话里做错事？**
+
+- 每轮都需要（如"不得调用 `ec restart`"）→ 进 `rules/`
+- 偶发场景才需要（如"Menu 消息有哪些字段"）→ 留 `docs/`，靠 `INDEX.md` 触发词按需命中
+
+答不上来就别进 `rules/`。最常见的隐性浪费是把偶发查阅的内容塞进规则文件，之后每轮对话都在白烧 token。
+
+### 硬阈值
+
+来自 `context-assembly.md` 的限额机制：
+
+- 单目录段：40KB（`$KITS_RULES` 当前约 18KB，**剩余约一半**）
+- 总闸：50 文件 / 100KB（跨所有段累计）
+
+逼近阈值会触发截断——**后面的 section 直接不加载**，且只注入一行截断说明。这是静默降级，出错时不报错，只表现为"某段上下文莫名其妙没出现"。
+
+### 升到 rules/ 的代价
+
+`rules/` 段是 `directory` 类型，加载**整个目录**。所以往 `rules/` 加一份文件不只是加了那份文件的成本，而是抬高了该目录的总字节数，逼近 40KB 上限。加规则文件前先确认现有占用（渲染报告里的 `manifest-*.md` 或直接量目录大小）。
+
+---
+
+## 四、命名与路径写法
+
+### 文件名
+
+与源码对应关系优先于名字的绝对准确。例如 `menu-protocol.md` 对应 `src/core/command/menu-protocol.ts`——保持同名比改成 `menu-app-protocol.md` 更有价值，因为读者能靠文件名在代码里定位实现。
+
+### 文档内引用路径
+
+三种写法，按场景选，**同一份文档内保持一致**：
+
+| 场景 | 写法 | 示例 |
+|------|------|------|
+| 引用同目录文档 | 裸文件名 | `menu-protocol.md` |
+| 引用别名内路径（`$KITS_*` / `$AGENT_DIR` 等） | `$别名/子路径` | `$KITS_DOCS/evolcore/foo.md` |
+| 引用别名外路径 | 全限定 + 说明 | `$KITS/schemas/bar.md`（注明不在别名解析范围） |
+
+**不要用 `../` 相对路径**跨目录引用。`$KITS_DOCS` = `kits/docs`，`../schemas/` 会跑出别名体系，读者（尤其是 agent）无法用路径规则解析。
+
+**只有 `$KITS` / `$KITS_DOCS` / `$KITS_RULES` / `$KITS_TEMPLATES` / `$KITS_FRAGMENTS` / `$AGENT_DIR` / `$PERSONAL_DIR` / `$RELATIONS_DIR` / `$VENUES_DIR` 等注册别名可用于引用**。完整清单见 `$KITS_DOCS/path-registry.md`。写 `$ECK` / `$PEER_DIR` 这类未注册名，在 manifest 里会**导致整段被静默丢弃**。
+
+### 术语唯一
+
+同一个概念在整套文档里只能有一个名字。理由是**检索靠字符串匹配**——同一概念存在两种叫法，等于把一半可发现性让出去。
+
+裁决标准：**优先对齐代码里的标识符**。源码中的类型名、函数名、文件名是全系统唯一不会歧义的名字。例如"授权凭证"这种业务术语，如果有对应的源码类型名，以源码为准。
+
+---
+
+## 五、可发现性：新文档必须接进链路
+
+一份文档写完不等于能被找到。ECK 的检索链路是**单入口 + 多级 lazy Read**：
+
+```
+【自动注入】$KITS_RULES/06-channel.md
+   "遇到明确触发词 → 优先查 $KITS_DOCS/evolcore/INDEX.md"
+        │
+        ▼
+【按需 Read】INDEX.md（命令表 / 协议与集成表）
+        │
+        ▼
+【按需 Read】目标文档
+        │
+        └── 文档内回链到相邻文档（双向可达）
+```
+
+### 接入清单（新文档必做）
+
+1. **在 `INDEX.md` 注册**，选对表：
+   - 对应某个 `ec` 子命令 → 「命令表」，填**触发词列**（关键，agent 靠它命中）
+   - 描述机制/格式，无对应命令 → 「协议与集成文档」表
+2. **补触发词**。触发词要写用户/agent 可能说出的自然语言，不是文档标题的复述。对照现有条目：
+   - ✅ `远程诊断/远程 daemon 操作/daemon 日志/跨主机`
+   - ❌ `Menu 客户端命令文档`
+3. **双向回链**。相邻文档之间互相引用——A 提到 B 的地方链过去，B 的相关处链回来。
+4. **检查上游触发词**。`rules/06-channel.md` 里那句示例触发词列表如果不覆盖新话题，补上。
+
+### 反模式
+
+- **双入口**：`commands` fragment（自动注入的能力卡）只列常用命令，不必把新命令加进去。加了会造成"能力卡一份、INDEX 一份"的双份维护，且 fragment 是精简卡片，不适合承载完整清单。
+- **只加文档不加索引**：文档存在但没有任何自动注入的锚点指向它，agent 无从知晓。
+
+---
+
+## 六、引用完整性
+
+**原则：任何引用都必须在任何时刻可解析。**
+
+失效分两种，性质完全不同：
+
+| 类型 | 表现 | 可否自动排查 |
+|------|------|:-----------:|
+| **结构失效（悬空）** | 目标文件不存在、锚点不存在 | ✅ 可 |
+| **语义失效** | 目标文件存在、链接有效，但**内容已经不对了** | ❌ 不可 |
+
+### 悬空排查
+
+```bash
+# 列出所有 markdown 内链目标，逐个确认存在
+git grep -h -o '\[.*\](\./[^)]*\.md)' -- kits/docs | sort -u
+```
+
+### 语义失效的预防
+
+改了某个概念，所有引用它的文档**必须列入同一次变更**。做法：
+
+1. 改动前先查清"谁引用了它"——`git grep -n "<概念关键字>" -- kits`
+2. 把命中的文档全部纳入本次改动范围，逐一核对
+3. 查不清的（概念名在正文里以同义词出现），至少在提交信息里记录未核对的文档
+
+这是唯一能防语义失效的手段。**不要指望后来者发现**——语义失效不会报错，只会在某次对话里表现为"agent 引用了过时的说法"。
+
+---
+
+## 七、粒度阈值
+
+正交讲"该分就分"，但同样要防"不该分的分了"。
+
+> **两半内容的发现触发词不同 → 拆；触发词相同、读者相同 → 合。**
+
+判据是**触发词**，不是篇幅。举例：
+
+- `menu-client.md`（工具用法）与 `menu-protocol.md`（格式定义）**该拆**——用户说"远程看日志"和说"auth_method 是什么"是两类完全不同的需求，触发词不重叠
+- 反之，如果两份文档都靠"menu 怎么工作"这个触发词命中，拆开就是纯粹的碎片化，只让读者多跳一次
+
+篇幅长不是拆分的理由。一份 500 行的单主题文档，比三份各 150 行、读者要在其间跳转的文档更容易维护。
+
+---
+
+## 八、权威裁决：冲突时以谁为准
+
+正交管"一个概念只有一个事实源"，但没回答**冲突时以谁为准**。实际维护中这立刻会遇到：代码改了、文档没改，读者该信谁？
+
+| 冲突类型 | 以谁为准 | 说明 |
+|---------|---------|------|
+| 行为、字段、参数、错误码等**实现事实** | **代码为准** | 文档跟随代码；文档中给出源码指针，让读者可自行核对 |
+| 设计意图、取舍理由、"为什么这样" | **文档为准** | 代码是实现手段，意图只存在于文档 |
+
+### 文档之间冲突
+
+**不要简单地"以后者为准"。** 回到 §二 正交：判定该概念归属哪一份，另一份删掉改引用。只在引用处保留一句指向。
+
+简单往后覆盖文档，会让两份继续各自漂移——下次改其中一份，冲突再次出现。
+
+---
+
+## 九、示例代码必须与实现一致
+
+文档里的示例会被直接照抄执行，写错比不写更糟。
+
+**规则**：写或改示例前，**读一遍对应的源码**确认形态。特别是：
+
+- **参数类型**（对象 vs `JSON.stringify` 字符串）
+- **必填但易漏的字段**（如 Menu 消息的 `ttl: 60`）
+- **签名/字段名**（`protected_headers` 字段的大小写与拼写）
+
+本次维护中发现的典型错误：示例写成 `payload: JSON.stringify({...})`，而实现是 `payload: {...}` 对象直传（`transport.ts` 直接读 `params.payload?.type`）——照抄会直接失败。
+
+**示例后附依据**：在示例下方注明对应的源文件与行为，方便后续核对：
+
+```markdown
+- `ttl: 60` 是 Menu 消息的固定约定（`src/aun/menu/transport.ts` 的 `MENU_MESSAGE_TTL_SECONDS`）。
+```
+
+---
+
+## 十、改动前后的检查清单
+
+### 改前
+
+- [ ] 确认改动内容属于哪一类（格式 / 工具 / 具体任务）
+- [ ] 搜索该内容是否已在别处定义（`git grep -n "<关键字段名>" -- kits`）
+- [ ] 若已定义，判断归哪一方，另一方改为引用
+- [ ] 若改的是概念定义，查清所有引用方并纳入本次变更（防语义失效，见 §六）
+- [ ] 若往 `rules/` 加内容，先确认该目录当前占用（防注入成本失控，见 §三）
+
+### 改后
+
+- [ ] 无 `../` 相对路径引用
+- [ ] 无未注册别名（`$ECK` / `$PEER_DIR` / `$AGENT_INDEX` 等）
+- [ ] 所有引用的目标文件**确实存在**（悬空引用排查，见 §六）
+- [ ] 章节编号连续、锚点链接有效
+- [ ] 示例代码与源码形态一致（见 §九）
+- [ ] 新文档已注册进 `INDEX.md` 且带触发词
+- [ ] 被改动文档的相邻文档有回链
+- [ ] 改了 `ec memory` 的命令语法：`$KITS_FRAGMENTS/memory.md`、`$KITS_DOCS/evolcore/memory.md`、`src/cli/memory-command.ts` 的 `MEMORY_HELP` / `USAGE` 三处同步
+
+---
+
+## 十一、本次维护的案例（供参考）
+
+以下几处改动可作为规则的实际样本：
+
+| 问题 | 违反的规则 | 处置 |
+|------|-----------|------|
+| `menu-client.md` 与 `menu-protocol.md` 都定义消息类型 | §二 正交 | client 收敛为工具手册，格式引用 protocol |
+| `menu-protocol-cli-exec-frontend.md` 被引用但不存在 | §六 结构失效 | 改指向 `menu-protocol.md` |
+| `schemas/menu-exec-schema-commands.md` 放在数据目录 | §一 文件位置 | `git mv` 到 `docs/evolcore/` |
+| `INDEX.md` 用 `../schemas/...` | §四 路径写法 | 改为同目录裸文件名 |
+| 章节顺序 `0,1,2,3,4,6,5` | §十 编号连续 | 交换 §5/§6 并修锚点 |
+| 示例用 `JSON.stringify(payload)` | §九 示例一致性 | 改为对象直传 + 补 `ttl` |
+| `menu-protocol.md` 无触发词入口 | §五 可发现性 | 新建「协议与集成文档」表并填触发词 |

package/kits/docs/GUIDE.md

@@ -1,5 +1,7 @@
 # 文档查阅指南
 
+> 本文面向**查阅**文档的人。要**新增或修改** `kits/` 下的文档，见 `AUTHORING.md`。
+
 ## 查阅流程
 
 1. 先看 `$KITS_RULES`（自动加载的 6 个规则文件 01-06）了解机制骨架

package/kits/docs/INDEX.md

@@ -7,6 +7,7 @@
 | 文档 | 路径 | 说明 |
 |------|------|------|
 | 查阅指南 | `GUIDE.md` | 文档查阅流程 |
+| 写作与维护指南 | `AUTHORING.md` | 增改 ECK 文档时的规则：放哪、怎么正交、如何接入可发现链路、示例一致性、检查清单 |
 | 路径定义 | `path-registry.md` | 所有预定义路径及派生规则 |
 | 上下文组装机制 | `context-assembly.md` | manifest 装配机制：when 条件/合并覆盖/模板渲染/运行时变量/调试输出 |
 
@@ -15,6 +16,7 @@
 | 文档 | 路径 | 说明 |
 |------|------|------|
 | 速查表 | `aun/CHEATSHEET.md` | AUN 协议命名空间与常用操作速查 |
+| SDK 文档指引 | `aun/SDK.md` | AUN SDK 文档位置（`$AUN_SDK_DOCS`）、结构与常用入口；四语言版本共用同一份协议文档 |
 | 同步协议 | `aun/SYNC_PROTOCOL.md` | 上游协议同步 SOP |
 
 ## EvolCore 命令

package/kits/docs/aun/CHEATSHEET.md

@@ -17,3 +17,7 @@
 ## Group 使用入口
 
 日常群操作使用 `ec group`，详见 `evolcore/group.md`。群文件使用 `ec fs`，详见 `evolcore/fs.md`。
+
+## AUN SDK 完整文档
+
+详见 `aun/SDK.md`。

package/kits/docs/aun/SDK.md

@@ -0,0 +1,60 @@
+# AUN SDK 文档指引
+
+AUN SDK 有四个语言版本：TypeScript、Python、Go、JavaScript。协议文档是四个版本共用的，
+统一打包在 `@agentunion/fastaun`（TypeScript SDK）的 `_packed_docs/` 目录下。
+
+## 文档位置
+
+文档位于 `$AUN_SDK_DOCS`，即 `$AUN_SDK/_packed_docs`。
+
+`$AUN_SDK` 是 npm 包 `@agentunion/fastaun` 的安装目录，在 evolcore 项目中作为本地依赖安装，
+通常路径为 `$PACKAGE_ROOT/node_modules/@agentunion/fastaun`。路径别名定义见
+`$KITS_DOCS/path-registry.md`。
+
+该目录不存在时，说明当前环境未安装此包，不要凭记忆推断协议细节。
+
+## 文档结构
+
+找到 `$AUN_SDK_DOCS` 后，内容按三个维度组织：
+
+### 协议规范（`protocol/` 目录）
+
+| 文件 | 内容 |
+|------|------|
+| `00-总览与分层.md` | 协议目标、四层架构、三种连接模式（gateway/peer/relay）、文档导航 |
+| `00A-设计原则-为Agent而生.md` | 元原则：Agent 优先、主体对等、自主至上 |
+| `01-身份与凭证协议-auth.md` | auth.* 方法、AID/证书/私钥/token 关系 |
+| `02-证书与信任体系.md` | AID 体系、四级证书链、信任模型、吊销机制 |
+| `03-Gateway-连接模式.md` | Gateway 连接流程、auth.connect、心跳重连 |
+| `06-服务协议.md` | 业务层方法：group/message/storage/meta/search 等服务的 RPC 定义 |
+| `08-AUN-E2EE-Group.md` | 群端到端加密 |
+| `10-Group-子协议.md` | group.* 完整协议规范 |
+| `11-Storage-子协议.md` | storage.* 完整协议规范 |
+| `13-Agent行为规范.md` | Agent 自主模式行为规范、收发方义务 |
+| `附录A-术语表.md` | 协议术语定义 |
+
+### SDK 使用手册（`sdk/` 目录）
+
+| 文件 | 内容 |
+|------|------|
+| `INDEX.md` | SDK 手册总索引 |
+| `04-连接与认证.md` | 连接建立、access token getter |
+| `06-API手册.md` | SDK API 完整手册 |
+| `09-group-rpc-manual.md` | group RPC 手册 |
+| `09-message-rpc-manual.md` | message RPC 手册 |
+| `09-storage-rpc-manual.md` | storage RPC 手册 |
+| `09-stream-rpc-manual.md` | stream RPC 手册 |
+| `09-proxy-rpc-manual.md` | proxy RPC 手册 |
+| `09-payload-reference.md` | payload 类型参考 |
+| `E2EE_V2消息通信时序图.md` | E2EE V2 主链路时序 |
+| `Notify通知方案.md` | client.notify() 在线轻量通知 |
+
+### agent.md 名片规范
+
+| 文件 | 内容 |
+|------|------|
+| `agent.md/SCHEMA.md` | agent.md 名片完整字段规范 |
+
+### 总索引
+
+`INDEX.md`（文档根目录下）是完整的三层索引，覆盖所有设计文档、测试指南、架构方案等。

package/kits/docs/channels/aun.md

@@ -55,6 +55,14 @@ AUN keystore seed 由 EvolCore 使用固定应用值管理，不再提供配置
 - **群 @ 处理策略**：`mention_mode=disabled|mention-only` 是群级配置，只决定哪些群消息进入 Agent LLM 上下文，不影响 AUN 协议层投递；被过滤消息仍应本地存档。
 - **身份体系**：对端以 AID 标识，关系层 peerKey 形如 `aun#alice.aid.pub`。
 
+### 私聊最终回复标题
+
+AUN 私聊中，`result.text` 的 `isFinal=true` 会在 `payload.text` 正文前添加 `✅ 最终回复:`。AUN 文本客户端按正文展示，标题随 outbox 上下文持久化，断线恢复发送时仍保留。群聊、中间文本、命令回执及错误消息不自动添加该标题。
+
+Interactive 私聊的最终正文保留到本轮结束后统一发送，避免定时 flush 提前当作中间文本发出。Codex 明确标记的 commentary 可按原定时窗口发送；没有阶段标记的正文等到下一文本块、工具调用或本轮结束后确定发送方式。标题和正文之间留一个空行，正文已经以同一标题开头时不重复添加，也不额外发送 `payload.title`。
+
+标题仅表示最终回复的展示信息，任务完成或失败仍由 `task.status` 表达。
+
 ### 出站关注状态
 
 AUN runner 状态和 action card 可携带顶层 `attention`，值只能是以下四种之一：

package/kits/docs/context-assembly.md

@@ -31,9 +31,10 @@ evolcore 收到消息 → 构造一份 **vars**（运行时变量，见下）→
 |------|------|------|
 | `main`（默认） | `eck_manifest.json` | 主会话，完整上下文 |
 | `auxiliary` | `eck_manifest.auxiliary.json` | 辅助会话（双会话模式），精简上下文 |
+| `memory` | `eck_manifest.memory.json` | 记忆整理会话（由触发器拉起） |
 | 未来：`approval` / `goal` / ... | `eck_manifest.<type>.json` | 权限审批 / 目标管理等专用会话 |
 
-**映射由 agent config 的 `sessionManifests` 字段定义**（走 config 分级覆盖：关系/环境/agent 级）：
+**上表映射内置在代码里**（`src/eck/kit-renderer.ts` 的 `BUILTIN_SESSION_MANIFESTS`），不依赖任何 config。agent config 的 `sessionManifests` 字段只作**可选覆盖**（走 config 分级覆盖：关系/环境/agent 级）：
 
 ```jsonc
 // $AGENT_DIR/config.json
@@ -45,7 +46,7 @@ evolcore 收到消息 → 构造一份 **vars**（运行时变量，见下）→
 }
 ```
 
-渲染时按 `session.sessionType`（缺省 `'main'`）查 `sessionManifests`，取不到则回退 `eck_manifest.json`。
+渲染时按 `session.sessionType`（缺省 `'main'`）依次查：`sessionManifests` 覆盖 → 内置映射 → `eck_manifest.json`（`resolveSessionManifest`）。bootstrapping 阶段固定用 `eck_manifest.json`。
 **每个 manifest 文件各自两级合并**（`$KITS/<file>` + `$ECK/<file>`），互不干扰。
 
 ## section 字段
@@ -256,7 +257,7 @@ vars 由 evolcore 在 `message-processor.ts` 按当前会话构造。分两类
 | 变量 | 含义 |
 |------|------|
 | `selfAid` / `selfName` | 当前 agent 身份 |
-| `hasPersona` / `hasWorkingMemory` | 是否有人格 / 当前关注 |
+| `hasPersona` | 是否有人格 |
 | `peerId` / `peerKey` / `peerName` | 对端原生 ID / 跨渠道键 / 显示名 |
 | `peerRole` / `peerType` | 对端角色（owner/admin/member/visitor/自定义角色/none）/ 类型（human/agent） |
 | `groupId` | 群 ID（群聊时） |
@@ -295,10 +296,11 @@ coding 场景（无 channel/无身份）下，`chatType`、`channel`、`selfAid`
 | 20 | identity-layer | fragment | active 且 chatType≠null | ✓ |
 | 21 | persona | `$PERSONAL_DIR/persona.md` | active 且 chatType≠null | ✗ |
 | 21.5 | personal-profile | `$PERSONAL_DIR/personal.md` | active 且 chatType≠null | ✗ |
-| 22 | working-memory | `$PERSONAL_DIR/memory/working.md` | active 且 chatType≠null | ✗ |
-| 23 | preferences | `$PERSONAL_DIR/preferences/active-preferences.md` | active 且 chatType=private | ✗ |
 | 30 | relation-layer | fragment | active 且 chatType∈{private,group} | ✓ |
-| 35 | peer-profile | `$RELATIONS_DIR/{{peerKey}}/profile.md` | active 且 peerKey≠null | ✗ |
+| 35 | memory | `$KITS_FRAGMENTS/memory.md` | active 且 memoryEnableRelation≠false | ✓ |
+| 36 | agent-memory | `$PERSONAL_DIR/memory/MEMORY.md` | active 且 memoryEnableAgent≠false | ✗ |
+| 37 | owner-memory | `$EVOLCORE_HOME/memory/owner/{{ownerAid}}/MEMORY.md` | active 且 ownerAid≠null 且 memoryEnableOwner≠false | ✗ |
+| 38 | relation-memory | `$RELATIONS_DIR/{{peerKey}}/memory/MEMORY.md` | active 且 peerKey≠null | ✗ |
 | 40 | venue-fragment | fragment | active 且 chatType≠null | ✓ |
 | 41 | venue-chattype | `$KITS_DOCS/venues/{{chatType}}.md` | active 且 chatType≠null | ✗ |
 | 42 | venue-channel-chattype | `$KITS_DOCS/venues/{{channel}}-{{chatType}}.md` | active 且 chatType≠null | ✗ |
@@ -314,6 +316,8 @@ Bootstrap 只加载引导与有渠道时的最小通信上下文 `[reply]`，不
 `[reply]` 展示 selfAid、peerId、peerType、channel、chatType、chatMode；未知身份显示 unknown，回复方式只取运行时已解析的 chatMode，不从身份或私聊场景重新推断。命令经当前会话 delegated sender / daemon IPC 发送，遵守现有身份、目标、话题与加密约束。
 `needsInjection` 仅是是否进行模板渲染的布尔开关，不是变量白名单；上述变量原本已存在于运行时 vars。
 
+> **v3 移除的段**：`order 22` working-memory、`23` preferences、`34` relation-working-memory、`35` peer-profile、`36.5` owner-working-memory 已从 manifest 删除。这些内容分别由 `memory-tags.md` 里的状态标签与 `profile` 标签的记忆取代。详见 `docs/memory/memory-system-v3.md`。
+
 `session` 与 `baseagent` 不依赖 chatType，因此 active 的 coding 场景仍命中 rules + session + baseagent；无渠道时不加载共用回复段。
 生命周期缺失兼容 active；created 与显式非法生命周期不命中主 manifest 的引导、回复或常规段。
 

package/kits/docs/evolcore/INDEX.md

@@ -33,7 +33,7 @@ Windows 上 Codex 托管任务出现 `helper_sandbox_lock_failed`、`SetNamedSec
 | 命令集 | 用途 | 触发词 | 适用场景 | 文档 |
 |--------|------|--------|----------|------|
 | `ec msg` | 私聊收发消息 | 回复/发消息/拉取/撤回/查在线 | 有对端（peerId） | `msg.md` |
-| `ec group` | 群聊收发与群管理 | 群发/建群/本地群历史/邀请/踢人/退群/群成员/角色/封禁/屏蔽/成员状态/规则/协作 | 群聊（groupId） | `group.md`；完整协作流程见 `group-collaboration.md` |
+| `ec group` | 群聊收发与群管理 | 群发/建群/本地群历史/邀请/踢人/退群/群成员/角色/封禁/屏蔽/成员状态/规则/@提及模式/协作 | 群聊（groupId） | `group.md`；完整协作流程见 `group-collaboration.md` |
 | `/invites` / `ec group invites` | 收到群邀请、Owner 卡片审核与恢复 | 入群邀请/接受邀请/拒绝邀请/审核卡片/待处理邀请 | 当前 Agent Owner 的 AUN 私聊 | `group.md` |
 | `ec group rules` | 群规则文件发布与上下文注入 | 群规则/工作流程/职责分工/rules.md/发布规则 | AUN 群聊（groupId） | `group-rules.md` |
 | `ec aid` | AID 身份管理 | 身份/证书/名片/探测对端 | 任意有渠道场景 | `aid.md` |
@@ -43,13 +43,14 @@ Windows 上 Codex 托管任务出现 `helper_sandbox_lock_failed`、`SetNamedSec
 | `ec agent` | EvolAgent 生命周期 | 创建/启停/热重载/改配置 | 管理员（owner/admin） | `agent.md`；完整创建与 Bootstrap 见 `agent-create.md` |
 | `ec contact` | Contact Book 与访问控制 | 申请添加、拉黑/解除拉黑、查拉黑 | Agent 当前私聊可申请添加；管理写操作按角色限制 | `contact.md` |
 | `ec rpc` | 底层 AUN RPC（逃生通道） | 直接调协议方法 | 高级/兜底 | `rpc.md` |
-| `ec menu-client` | 远程 Daemon Menu 请求 | 远程诊断/daemon 日志/监控/原始配置 | 运维主机或具备 `ec.menu.request` 权限的托管 Agent | `menu-client.md` |
+| `ec menu-client` | 远程 Daemon Menu 请求 | 远程诊断/远程 daemon 操作/daemon 日志/监控/原始配置/跨主机 | 运维主机或具备 `ec.menu.request` 权限的托管 Agent | `menu-client.md` |
 
 ## 会话自管理类（不连 AUN，操作当前会话）
 
 | 命令集 | 用途 | 触发词 | 文档 |
 |--------|------|--------|------|
 | `ec ctl` | 当前会话工具 | 主动发消息/文件、重命名、队列、项目路径、会话状态 | `ctl.md` |
+| `ec memory` | 记忆写入与整理 | 记住/记一下/mark it/这很重要/保存/记忆/memory/整理记忆 | `memory.md` |
 
 ## 本地工具类（不连 AUN，操作本地配置）
 
@@ -62,6 +63,7 @@ Windows 上 Codex 托管任务出现 `helper_sandbox_lock_failed`、`SetNamedSec
 | `ec trigger` | 定时与事件触发器管理（创建用 `create`，`set` 为兼容别名） | 触发器/定时任务/cron/提醒/定时检查/自动执行/巡检/禁用 trigger/删除 trigger | `trigger.md` |
 | `ec trigger event` | EventBus 事件目录 | 事件触发/事件目录/EventBus/source.type=event/filter.match | `event.md` |
 | `ec task` | 恢复暂停或异常中断的会话任务 | 任务恢复/异常中断/继续任务/resume | `task.md` |
+| `ec skill` | EC 技能管理（新建/安装/删除/启用/禁用/校验/查路径） | 创建技能/新建 skill/安装技能/装个 skill/删除技能/禁用技能/启用技能/看看有哪些技能/技能为什么没生效 | `ec-capabilities.md` |
 
 ## 开发者工具（非 agent 会话能力）
 
@@ -69,8 +71,20 @@ Windows 上 Codex 托管任务出现 `helper_sandbox_lock_failed`、`SetNamedSec
 |------|------|------|
 | `ec bench` | AUN 消息系统性能基准测试 | CLI 工具，agent 一般不主动调用；`ec bench --help` 查看用法 |
 
+## 协议与集成文档（非命令集）
+
+按需 Read。这些文档描述机制与格式，不对应某个 `ec` 子命令。
+
+| 文档 | 用途 | 触发词 |
+|------|------|--------|
+| `menu-protocol.md` | Menu Protocol 规范（消息类型 / protected_headers / name→operation 映射 / 鉴权机制） | menu 消息格式/为什么被拒/服务端怎么读 menu/auth_method/凭证怎么带/Evol App 怎么调 daemon |
+| `menu-exec-schema-commands.md` | 通过 `menu.action name=cli action=exec` 取配置 schema 的命令手册 | 配置 schema 版本/schema 内容/远程取 schema |
+| `ec-capabilities.md` | EC Skill 系统机制概要（三级目录、开关覆盖链、渐进式披露、编写规范、权限） | 技能系统怎么工作/技能放在哪里/SKILL.md 怎么写/技能为什么没生效/description 怎么写 |
+
 ## 其他
 
 | 文档 | 说明 |
 |------|------|
-| `self-summary.md` | 自我总结流程指南 |
+| `self-summary.md` | 自我总结流程指南（**早期设计稿，源码未实现，可删除**；记忆以 `memory-architecture.md` 为准） |
+| `memory-architecture.md` | 记忆系统概述（作用域、流水线、开关、目录） |
+| `memory-consolidation-batches.md` | 整理批次目录结构（整理批次目录、checkpoint、话题快照、产物目录） |

package/kits/docs/evolcore/agent-create.md

@@ -37,6 +37,7 @@ ec agent new helper.agentid.pub --initialize \
   --owner owner.agentid.pub --name "Helper" \
   --description "协助处理项目开发任务" \
   --tags '["coding","maintenance","typescript"]' \
+  --avatar-file /home/user/helper-project/avatar.jpg \
   --persona-file /home/user/helper-project/persona.md
 ```
 
@@ -44,6 +45,21 @@ ec agent new helper.agentid.pub --initialize \
 
 初始化期间不处理目标 Agent 的普通入站消息。初始化失败或 daemon 重启后，使用 `ec agent initialize <aid> --resume` 恢复原操作；不要重复 `new` 或使用 `--force` 覆盖。`ec agent show <aid>` 会显示初始化阶段、错误和下一步，但不会暴露 persona 正文。
 
+创建时可直接使用 `--avatar-file <path>` 或 `--avatar-url <HTTPS URL>` 提供头像。普通托管非交互创建还可将当前对端已经收到的图片附件写成 `--avatar-file 'attachment:<id>'`，由 daemon 在当前关系目录中解析；不要先把附件复制到项目目录或 `$TMPDIR`。两种来源互斥，并沿用 `ec aid avatar` 的公共头像处理管线；创建流程只负责把参数传给同一公共能力。
+
+### 创建阶段的可选头像
+
+头像是可选项，不提供不会阻塞创建或 Bootstrap。创建者应在执行普通非交互式 `ec agent new` 前询问 Owner 是否提供头像；若 Owner 已发送图片附件，直接把附件 ID 作为 `--avatar-file 'attachment:<id>'` 传给创建命令，不要读取、复制或改写附件路径。也可以传本地图片路径或 HTTPS 地址：
+
+```bash
+ec agent new helper.agentid.pub --non-interactive \
+  --project /home/user/helper-project --baseagent codex \
+  --owner owner.agentid.pub \
+  --avatar-file 'attachment:<id>'
+# 或使用本地文件：--avatar-file '/home/user/helper-project/avatar.jpg'
+# 或使用 HTTPS：--avatar-url 'https://example.com/avatar.jpg'
+```
+
 没有得到创建者明确最终字段时，继续使用下方的普通非交互式创建，让目标 Agent 自己完成 Bootstrap。
 
 多个 Agent 必须串行创建和观察。不要并行启动多个 `ec agent new`：证书、热加载和 Bootstrap 会竞争连接与资源，容易造成超时、锁等待或把失败误判为未创建。
@@ -61,6 +77,7 @@ ec agent new helper.agentid.pub --non-interactive \
   --project /home/user/helper-project \
   --baseagent codex \
   --owners '["helper-creator.agentid.pub","owner.agentid.pub"]' \
+  --avatar-file 'attachment:<id>' \
   --name "Helper" \
   --description "协助处理项目开发任务" \
   --tags '["coding","diagnostics","logs"]' \
@@ -132,6 +149,8 @@ ec agent show helper.agentid.pub
 
 新 Agent 应回显这三个最终值并等待确认。Owner 再明确回复“确认”后，才能修改和发布名片。
 
+如果创建命令已提供头像，创建流程会在初始 `agent.md` 发布成功后自动处理；Bootstrap 不重复询问或执行头像命令。头像支持 PNG、JPEG、WebP，创建流程会保持完整画面、补白边、缩放到头像尺寸并压缩到 500 KiB 内；原图不会被覆盖。若无法解码或规范化，创建会返回具体的可恢复错误。Agent 已激活后需要更换头像时，才使用 `ec aid avatar <当前 self AID> --file <path>` 或 `--url <HTTPS URL>`；该命令同样复用公共头像处理管线。
+
 Bootstrap 完成前，新 Agent 不处理普通任务，也不执行与本流程无关的工具或命令。如果 Owner 要求跳过、先工作或同时交办普通任务，新 Agent 应说明必须先完成首次设定，并继续确认缺失字段。
 
 ## 4. 新 Agent 修改自己的 agent.md
@@ -162,6 +181,8 @@ ec aid agentmd put helper.agentid.pub
 只有命令明确成功后才能继续。发布失败时保留已经确认的 welcome，修正发布问题后续做，不重复生成。
 多 Owner 共用该模板；需要称呼时保留 `{{ownerName}}` / `{{ownerAid}}` 供逐人渲染。投递文本不再追加未确认内容。
 
+如果头像是在创建命令中提供的，创建流程会在初始 `agent.md` 发布成功后自动上传并更新头像；不要在 Bootstrap 中再次执行 `ec aid avatar` 或 `agentmd put`。头像未提供时跳过；创建时已明确提供但规范化或上传失败时，按创建命令返回的可恢复错误处理。
+
 ## 6. 新 Agent 完成 Bootstrap
 
 发布成功后，新 Agent 执行整个 Bootstrap 的最后一个操作：
@@ -196,11 +217,14 @@ Bootstrap 首条消息只发送给 `owners[0]`；`ready` 成功后，正式欢
 
 使用 `--handoff` 代办创建时，创建 Agent 在与新 Agent 的会话中完成验收后，执行 `ec handoff return --content '<验收结果>'`，将结果回流至自己与原需求 Owner 的会话；该步骤不由新 Agent 执行。
 
+代办交接的内联返回正文也支持单次 `\n` / `\r` / `\t` / `\\` 解码；从 `--text-from-file` 读取的文件字节保持原样。不要使用 PowerShell 反引号换行转义。
+
 验收标准：
 
 - `lifecycle` 为 `active`；`ec agent show` 的 `lifecycle` 字段也必须为 `active`。
 - `agent.md` 已成功签名发布。
 - 本地与远端 `agent.md` 的 `name`、`description`、`tags` 与 Owner 确认值一致；创建流程 skill 必须在发布后复读核验，不以初始上传响应代替。
+- 如果 Owner 选择提供头像，远端 `agent.md` 的 `avatar` 已更新并发布；未提供时跳过，已明确提供但规范化或上传失败时创建进入可恢复失败状态。
 - `personal/welcome.md` 是当前 Bootstrap 对话最后展示并经 Owner 确认的全文，未确认文案没有另存草稿。
 - 系统已创建新的主会话并发送正式欢迎消息。
 - 新 Agent 能在新主会话中处理普通任务。

package/kits/docs/evolcore/agent.md

@@ -65,6 +65,8 @@ ec agent delete <aid> [--purge]
 
 ## 非交互创建必填项
 
+`welcome --text`、`persona --text`、创建时的 `--description` / `--persona-text` / `--handoff` 按一次 `\n` / `\r` / `\t` / `\\` 解码；已传入的物理换行保留。不要使用 PowerShell 反引号换行转义；Windows PowerShell 中直接使用命令名，不要用批处理入口传物理多行。文件、路径、`--tags` JSON 不解码；`--name` / `rename` 名称不允许换行。
+
 `ec agent new <aid> --non-interactive` 时，只有 `<aid>` 必填：
 - `--project` 缺省为当前目录，并自动转为绝对路径。
 - `--baseagent` 优先使用 `agents/defaults.json`，否则检测本机可用基座。
@@ -73,13 +75,14 @@ ec agent delete <aid> [--purge]
 - `--dry-run` 只输出最终创建计划，不注册 AID、不写配置、不上传 `agent.md`。
 - `--force` 覆盖已有 `config.json`；AID 密钥保留。
 - `--tags` 接受 3 到 6 个标签的 JSON 数组；每个标签只允许 Unicode 字母、数字和连字符（`-`），最长 50 字符。
+- `ec agent new` 支持 `--avatar-file <path>`（托管当前对端附件可用 `attachment:<id>`）或 `--avatar-url <https-url>`；创建流程沿用 `ec aid avatar` 的公共头像管线。未提供头像时跳过；已明确提供但无法规范化或上传时，创建返回可恢复错误。
 - `--initialize` 要求显式提供 `--name`、`--description`、`--tags` 和 Owner；它不从项目元数据推断名片，成功条件是目标 Agent 已进入 `active`。`--initialize` 自动包含 `--non-interactive`，不需要同时填写后者。
 - `--persona-file` / `--persona-text` 可选；两者互斥。初始化失败可用 `ec agent initialize <aid> --resume` 按原计划恢复，不能用普通 `new --force` 覆盖。
 - `ec agent persona show` 读取当前 Agent 的 `$PERSONAL_DIR/persona.md`；`--text` 或 `--file <path>` 可由当前 Agent 的 owner 写入。文件内容限制为 UTF-8 文本，`--file` 仅接受 `.md`/`.txt`。
 - `ec agent welcome --text <text>` 只用于 Bootstrap 中 Owner 已明确确认的完整文案；命令固定写入当前 Agent 的 `$PERSONAL_DIR/welcome.md`，不接受自定义路径，也不保存未确认草稿。`welcome show` 读取该文件。
 - welcome 托管写入要求当前 Agent 私聊 Owner；admin 仅可读。模板上限 4 KiB，渲染上限 8 KiB；变量为 `agentName`、`agentDescription`、`agentAid`、`agentTags`、`agentTagsText`、`ownerName`、`ownerAid`、`channel`，支持标签循环和真值条件。写入保留原始文本，投递不附加额外文案。
 - `agent show <target-aid>` 与 `agent get <target-aid> <key>` 的跨 Agent 读取对 owner/admin 开放，但普通 Agent 角色只获得安全摘要；敏感配置值和物理路径仅对 DaemonOwner 返回原值。跨 Agent 写入、启停、删除和 reload 仍遵循各自的目标与 DaemonOwner 权限边界。
-- Agent 配置可包含 `fullaccess.enabled`（默认关闭），仅可通过已认证的 EC Web Agent 设置修改。该开关受 `daemon.json.fullaccess.enabled` 总开关约束；daemon 关闭时 EC Web 隐藏该设置项。实际运行时，只有同时属于该 AgentOwner 和当前 daemonOwner 的直接私聊任务才会按调用使用宿主级 fullaccess；群聊、普通 Owner、跨 Agent 和 Trigger 不会因该开关自动提权。daemon 总开关也控制 `/fa`、`/fullaccess` 和 Fullaccess Trigger。
+- Agent 配置可包含 `fullaccess.enabled`（默认关闭），仅可通过已认证的 EC Web Agent 设置修改。实际运行时，只有同时属于该 Agent Owner 和当前 daemon Owner 的直接私聊任务才会按调用使用宿主级 fullaccess；群聊、普通 Owner、跨 Agent 和 Trigger 不会因该开关自动提权。`/fa`、`/fullaccess` 和 Fullaccess Trigger 是内置能力，仍分别要求经过认证的 daemon Owner / 持久授权来源。
 
 ## 创建 Agent
 
@@ -119,7 +122,7 @@ ec agent delete <aid> [--purge]
 约束：
 - 规范入口使用 `args.data`（data URL）或 `args.url`（HTTPS URL）二选一；控制面可用顶层 `agent` 或 `args.aid` 选择目标，Agent channel 只能修改当前 self AID。
 - 新客户端使用 `name=aid action=avatar`。兼容旧版 App 的 `name=agent action=update` + `args.patch.avatar=<data URL>`：头像必须单独提交，复用相同图片校验、上传和名片发布流程，不写入 config.json，成功后同样发布头像更新事件。`patch.avatar_url` 仍不支持。
-- 支持真实 MIME 为 PNG/JPEG/WebP 的图片；大小不超过 500KB，分辨率为 128–2048 像素，宽高比为 0.8–1.25。
+- 支持真实 MIME 为 PNG/JPEG/WebP 的图片；源文件不超过 10 MiB。若大小、尺寸或宽高比不符合最终头像规范，公共 avatar 管线会保持完整画面、补边、缩放并压缩到 500KB 内；无法规范化时返回具体原因。
 - 成功后头像上传到该 agent 自己的 AUN storage，`agent.md` frontmatter 写入 AID 风格 URL，并重新签名发布。
 - 托管会话中的 CLI 形式为 `ec aid avatar <当前 self AID> (--file <path> | --url <https-url>)`；仅允许 owner 在 `request`/`bypass` 模式下执行。`--file` 只能从项目目录或当前会话 `$TMPDIR` 读取，`--url` 由 daemon 下载并做 SSRF、重定向和大小校验。
 - 成功响应包含 `sha256`、`mime`、`width`、`height` 和 `aspectRatio`，便于调用方核对实际上传内容。