evolcore 0.0.28 → 0.0.29

package/kits/docs/evolcore/memory-consolidation.md

@@ -0,0 +1,263 @@
+# ec memory 整理会话 — 机制说明
+
+> 本文说明**整理会话**（`sessionType=memory`）的工作机制：它是什么、有哪几种模式、各自怎么干活、产出什么。
+> 整理会话自己读的规范是注入的 `[memory]` fragment 与模板（`kits/templates/memory-consolidation/`），本文供人排查问题时阅读。
+>
+> 主会话的命令用法见 `$KITS_DOCS/evolcore/memory.md`；标签取值见 `$KITS_DOCS/evolcore/memory-tags.md`。
+
+---
+
+## 一、整理会话是什么
+
+一个**临时的、跑完即删的**独立会话，不在对端对话里，也不在会话列表里留痕。
+
+```
+主会话         launchConsolidation()        整理会话（模型）          程序
+  │                    │                         │                    │
+  ├─ note ─────────────────────────────────────► pending/
+  │                    │                         │                    │
+  ├─ consolidate ─────►│                         │                    │
+  │              pending/ → processing/          │                    │
+  │              序列化上下文文件                │                    │
+  │                    ├── 拉起会话 ────────────►│                    │
+  │                    │                         ├─ 读上下文文件       │
+  │                    │                         ├─ 读候选记忆         │
+  │                    │                         ├─ create/update/archive
+  │                    │                         │                    ├─ 签名
+  │                    │                         │                    ├─ 日志落盘
+  │                    │◄──── 会话结束 ───────────┤                    │
+  │              onConsolidationComplete()       │                    │
+  │              processing/ 归位               │                    │
+  │              writeCheckpoint                │                    │
+  │              重建索引（收尾时一次性）        │                    │
+  │              feedback → 发起时的会话和话题   │                    │
+```
+
+**它是唯一能产生正式记忆的地方。** 主会话只能写 note（原料），正式记忆的增删改全部由整理会话完成。
+
+**统一入口 `launchConsolidation()`**：所有触发路径——手动调用、定时检查、上下文压缩、renew / `/new`——都收口到这一个函数。它负责整理的完整生命周期：启动前把 `pending/` 加锁移入 `processing/`，序列化上下文文件，**直接创建整理会话**，会话结束后通过 `onConsolidationComplete` 处理收尾（归位、checkpoint、定稿索引、反馈）。
+
+**触发方分两个层次**：
+- **定时检查**：由 evolcore trigger 的 `script` 模式每小时执行一次，检查五类候选（notes / generalize / promote / profile / forget），符合条件就拉起整理会话。检查器只做判断，不承载生命周期。
+- **手动 / compact / renew / `/new`**：直接调用 `launchConsolidation()`，不经检查器。
+
+**并发与排队**：同一 agent 同时只能有一个整理会话在跑；全局最多 5 个 agent 并发。超出的请求排队，前一个结束后自动启动下一个。
+
+---
+
+## 二、五种模式
+
+| 模式 | 输入 | 产出 | 判断依据 | 检查 owner |
+|---|---|---|---|---|
+| `notes` | 当前关系的 `pending/` + 会话历史 | relation 正式记忆 | 值不值得长期留下 | 否 |
+| `generalize` | 关系级里带 `to-generalize` 的记忆 | agent 正式记忆 | **普遍性**：换成别的对端也成立 | 否 |
+| `promote` | 关系级里带 `to-promote` 的记忆 | owner 正式记忆 | **权威性**：owner 定下、对所有 agent 有效 | **是** |
+| `profile` | 该关系索引里的全部记忆 | 一条带 `profile` 标签的 relation 记忆 | 归纳对端这个主体 | 否 |
+| `forget` | mtime 超过 `forgetAfterDays` 的记忆 | 无新结论，只做续期 / 合并 / 归档 | 这条还成立吗 | 否 |
+
+**每种模式各自起独立的整理会话**，一个会话只对应一种模式。候选集和允许写的 scope 都不一样，不能合成一次会话跑固定流程。
+
+**会话怎么知道自己是什么模式**：`launchConsolidation()` 建会话时带 `memoryMode`，经 `session.metadata` → `kitCtx.vars` → manifest 的 `when` 条件选出对应的模式手册。只有 `[memory]` 段、`workflow.md` 和自己那一份模式手册会被加载。
+
+---
+
+## 三、三个写命令
+
+整理会话只能用这三个命令写正式记忆。**不允许用 Write / Edit 直接写文件**——那会绕过签名和索引。
+
+### create — 新建
+
+```bash
+ec memory create --scope <relation|agent|owner> --slug <slug> --desc "一句话描述" \
+  --tags <tag1,tag2,...> [--keywords <kw1,kw2,...>] [--replaces <路径,...>] "<正文>"
+```
+
+- 程序负责签名、写入 `consolidated/`、重建索引。
+- `--replaces` 指定的旧文件会被自动归档——**合并、纠正内容、升格作用域都走这条路径**，一次调用完成，不会出现「新的写了、旧的没归档」的重复记忆。
+- **目标 slug 已存在且未在 `--replaces` 里列出 → 拒绝**，报错回传已有文件路径。这是防止漏用 `--replaces` 导致静默覆盖的闸门。
+- **正文上限 10KB**，超出报 `MEMORY_TOO_LARGE`。这不是技术限制（底层签名接口本身无上限），而是记忆的性质决定的：一条记忆应当是**一句话能说清的结论**。内容确实那么多时，拆成多条分别 `create`，或把细节留在归档文件里、记忆只记结论。
+
+### update — 只改标签
+
+```bash
+ec memory update <路径> --tags <tag1,tag2,...>     # 整体替换标签
+ec memory update <路径> --touch                   # 刷新 mtime 与 updatedAt，用于续期
+```
+
+**update 不能改正文。** 内容一变，描述和关键词都得跟着变，那就应该 create 一条新的。它剩下的场景都是正文不变、只有状态变的：
+
+| 场景 | 改法 |
+|---|---|
+| 任务推进 | `in-progress` → `blocked` → `done` / `cancelled` |
+| 紧急解除 | 去掉 `urgent` |
+| 推断被确认 | `inferred` → `verified` |
+| 判定长期有效或重要 | 补 `long-term` / `important` |
+| 评估后不该升级 | 去掉 `to-generalize` / `to-promote` |
+
+### archive — 归档
+
+```bash
+ec memory archive <路径...>
+```
+
+**没有删除，只有归档。** 文件移入 `archive/`，可人工回捞。用于：合并后多出来的旧文件、已经过时的记忆。
+
+---
+
+## 四、权限校验
+
+daemon 按整理会话的模式校验 `--scope`：
+
+| 会话模式 | 允许的 `--scope` |
+|---|---|
+| `notes` | `relation` |
+| `generalize` | `agent` |
+| `promote` | `owner`，且 `--replaces` 的来源必须包含 owner 关系的记忆 |
+| `profile` | `relation` |
+| `forget` | `relation`（合并产出；续期与归档不限作用域） |
+
+**这是唯一真正生效的一道闸。** 触发器提示词里写的模式、上下文文件里写的模式、daemon 的校验，三层一致——前两层是引导，第三层是保证。模型理解错了模式，越权的写入也会被拒。
+
+**其他写入限制**：
+
+- `profile` 标签的记忆，一个关系只能有一条。重新生成必须用 `--replaces` 指定旧的那条。
+- `to-promote` 只能打在对端是 owner 的关系上。群聊关系额外检查发言人身份，owner 本人说的话可以打。
+- 全局总开关是 `memory.enableRelation`。它关闭时，五种模式和手动调用全部拒绝。
+  - `enableAgent=false` 关闭泛化模式与 agent 索引注入，notes / promote 照常。
+  - `enableOwner=false` 关闭提升模式与 owner 索引注入，notes / generalize 照常。
+
+---
+
+## 五、候选怎么筛
+
+主会话每一轮判断「压缩或新会话后会丢、且有影响」就写一条 note，所以 `pending/` 里是**未经分类的原料**：可能重复、可能矛盾、可能有错。
+
+**`notes` 模式**的输入是：
+
+- `pending/` 里的全部 note
+- 会话历史（`triggeredBy` 为 `compress` / `session-new` / `manual` 时可用；`periodic-trigger` 触发的补漏整理没有会话历史，只能凭 note 本身判断）
+- 现有的 `MEMORY.md` 索引（查重用）
+
+**`launchConsolidation()` 在拉起整理会话之前会把 `pending/` 整体 rename 到 `processing/`**，相当于加锁声明认领。整理过程中主会话新写的 note 落在 `pending/`，不会被这次整理误伤，也不会被误删。
+
+**`profile` 和 `forget` 模式**的候选清单**只给路径 + 描述**，会话按需读正文：
+
+- `profile`：先读该关系的索引（每条描述即一句话结论），归纳画像主要靠这些；某条太简、拿不准时再读那一条。
+- `forget`：候选只给路径和描述，只有拿不准是不是还成立的那几条才读全文。
+
+一个关系可能有几百条记忆，全读正文既慢又没必要。
+
+---
+
+## 六、收尾
+
+| 结果 | 处理 |
+|---|---|
+| 成功（含 `[[NOOP]]`） | `processing/` 里的 note 移入 `archive/notes/`，留底便于追查整理质量；写 checkpoint |
+| 失败 / 中断 | `processing/` 里的 note 移回 `pending/`，下次重新整理；不写 checkpoint |
+
+`processing/` 里的非 note 条目（如 `pending/archive/` 的 drop 留底）无论成败都原样还回 `pending/`。归位时与已有文件重名不覆盖，改名加时间戳后缀。
+
+**这个收尾由程序做（`onConsolidationComplete`），不让模型自己挪文件。**
+
+同时程序会在批次目录 `$EVOLCORE_HOME/memory/consolidation-batches/<YYYYMMDDTHHmmss>-<selfAid>-<mode>/` 下：
+
+- 往 `ops.jsonl` 追加一行 `summary`（created / updated / archived / errors 计数）。
+- 导出整理会话历史到 `history.jsonl`。
+
+索引 `MEMORY.md` 在每次 `create` / `update` / `archive` 后已即时重建，收尾不再重复。
+
+上一批的 `processing/` 还在时（会话未结束，或 daemon 中途重启丢了收尾），新一轮 notes 整理不迁移 `pending/`，避免两批混在一起。
+
+---
+
+## 七、整理会话里能做什么、不能做什么
+
+**能**：
+
+- 用 Read / Glob / Grep 读上下文文件、`processing/`、`consolidated/`、`MEMORY.md`、批次目录。
+- 用 Bash 执行**单条** `ec memory create` / `update` / `archive` 写正式记忆。
+
+**不能**（程序拦截，提示「整理会话不允许执行此命令」）：
+
+- Write / Edit / MultiEdit / NotebookEdit（Codex 的文件变更同理）——直接写文件绕过签名和索引。
+- 子代理（Agent / Task）、PowerShell——能绕开本策略。
+- Bash 里的其他任何命令，包括 `ls`、`cat`、`npm`、`git`，以及 `ec memory note` / `ec memory consolidate`
+  （note 是主会话入口，用了会把结果变回原料；consolidate 会形成循环）。
+- 在放行命令后拼接其他命令（`;`、`&&`、`|`、`$()`、反引号）。正文含特殊字符时用单引号包住。
+
+**不能**（daemon 校验拒绝）：
+
+- 处理模式之外的 `--scope`。
+
+**不该做**：
+
+- 逐一读取所有 consolidated 文件查重。先查 `MEMORY.md` 索引，只在发现高度相似的描述时才读那一条确认。
+
+实现：`src/core/memory/memory-session-policy.ts`，由 response-engine 在 `sessionType=memory` 的会话上挂为 policyHook，Claude / Codex / ecagent 三个 runner 共用。整理 trigger 不带 `permissionMode`，不会进入 fullaccess，策略不会被跳过。
+
+---
+
+## 八、索引与目录
+
+```
+<memory>/
+├── MEMORY.md           # 索引，程序自动重建
+├── pending/            # note 写入；整理前整体移到 processing/
+│   └── archive/        # 被 drop 的 note
+├── processing/         # 整理中快照
+├── consolidated/       # 正式记忆（已签名），文件名即 <slug>.md
+└── archive/
+    ├── notes/          # 整理完成的 pending 原件
+    └── invalid/        # 验签失败或未签名的文件
+```
+
+**索引**：每个作用域一份，上限 `memory.indexMaxBytes`（默认 5KB）。重建时**逐份验签，只认 `verified`**——`invalid` 和 `unsigned` 都移入 `archive/invalid/`，都不进索引。筛选顺序：
+
+1. `important`、`urgent`、`profile` 必进，**永不淘汰**
+2. `in-progress`、`pending`、`blocked`
+3. `long-term`
+4. 其余按文件 mtime 从新到旧
+5. `done`、`cancelled` **不进索引**
+6. 超过上限从末尾截断
+
+**时间有两处来源**：文件 mtime 给程序用（排序、超期判断），frontmatter 的 `updatedAt` 给人读。程序在每次写操作时同步写入。
+
+**「候选」与「索引」是两回事**：候选是本次遗忘会话要审查的那份清单（mtime 超 `forgetAfterDays` 的记忆）；索引是 `MEMORY.md`，决定召回时能否看到。**续期只是让它在 `forgetAfterDays` 天内不再进候选，完全不影响索引**——那条记忆一直可被召回。只有归档才会把它从索引里移除。**续期可逆，归档不可逆。**
+
+**索引行格式**：`- [描述](consolidated/<slug>.md) #keyword1 #keyword2`
+
+没进索引的文件仍留在磁盘上，可以搜到；只有 `archive` 才让它下线。
+
+**整理批次**：`$EVOLCORE_HOME/memory/consolidation-batches/`，每次整理建一个批次目录，命名为 `YYYYMMDDTHHmmss-<selfAid>-<mode>/`，目录内含 `context.md`（任务书）、`ops.jsonl`（操作流水）、`threads/`（话题快照）。不自动清理，由人工维护。详细结构见 `memory-consolidation-batches.md`。
+
+---
+
+## 九、整理会话的 manifest
+
+整理会话的 manifest（`kits/eck_manifest.memory.json`，14 段）不是主会话的减配版，而是独立的一份。会话原型 `memory` 由代码内置映射到这份 manifest（`kit-renderer.ts` 的 `BUILTIN_SESSION_MANIFESTS`），不依赖 agent config；`config.sessionManifests` 只作可选覆盖。
+
+| order | 段 | 用途 |
+|---|---|---|
+| 12 | `memory` | 与主会话共用的 `$KITS_FRAGMENTS/memory.md`，按 `sessionType=memory` 渲染整理分支：三个写命令、模式权限、禁止事项 |
+| 20 | `memory-workflow` | 整理流程：读上下文、查重、取舍、update 与 create --replaces 的选择、收尾 |
+| 25 | `persona` | 当前 agent 的人格 |
+| 26 | `personal-profile` | 当前 agent 的个人资料与工作背景 |
+| 27 | `peer-profile` | **当前对端画像**（`profile` 标签的记忆） |
+| 31 | `memory-mode-*` | 五份模式手册，按 `memoryMode` 五选一 |
+| 36/37/38 | 三份记忆索引 | agent / owner / relation |
+| 60 | `session` | 会话实例状态 |
+
+**为什么注入人格、个人资料和对端画像**：判断一条记忆值不值得留下、该归到哪个作用域时，需要知道「我是谁」（人格与自身定位）和「对方是谁」（画像）。三者都在模式手册之前加载（order 25–27 < 31），确保判断依据先于操作指令到位。
+
+**相对 v2 去掉的段**：`rules` 目录段（原本会把 `04-relation.md` / `05-venue.md` / `06-channel.md` 一并注入，对整理会话是噪声甚至误导）、`identity-layer`。整理会话不跟对端说话、不进群、不发消息。
+
+---
+
+## 十、session.md 的注入
+
+整理会话也加载 `$KITS_FRAGMENTS/session.md`，但其中的 proactive 行为约束（群聊要不要响应、首次调用工具前先发言、每 N 次调用汇报进展、`ec group send` / `ec msg send` 语法速查、跨会话 `--return` 规则）**不会渲染**。
+
+原因：整理会话由触发器创建，`peerType` 是 `system`、`chatType` 是 `private`。`resolveChatModeForPeer` 对 system 对端有硬约束，返回 `interactive`，而 proactive 那段的条件是 `{{?chatMode=proactive}}`，所以整块跳过。已实测确认。
+
+**因此 `session.md` 不需要为整理会话做任何改动。** 要保留的字段是 `permissionMode`（决定能否调三个写命令）、`timezone` / `tzOffset` / `localDate`（遗忘判断算天数，时区错会误判超期）、`sessionId` / `project`（诊断）。

package/kits/docs/evolcore/memory-tags.md

@@ -0,0 +1,63 @@
+# memory-tags — 记忆标签说明
+
+记忆系统的标签值全集。写入记忆时从本表选值，同一条记忆可以贴多个标签。
+
+标签值直接放在 frontmatter 的 `tags` 数组里：
+
+```yaml
+tags: [important, long-term, rule, verified]
+
+```
+
+---
+
+## 标签表
+
+| 标签值 | 说明 | 判断条件 | 例子 |
+| --- | --- | --- | --- |
+| important | 重要标记（保证进索引，不参与淘汰） | 忘了会直接影响工作质量或引发冲突 | owner 要求 commit 必须用中文；不要直接删文件 |
+| urgent | 紧急标记（保证进索引，不参与淘汰） | 当前任务中需要立即用到 | 今天必须完成的约定 |
+| long-term | 长期有效标记 | 预期较长时间内都会成立，不随当前任务结束而过期 | 项目使用 vitest |
+| verified | 已验证标记 | 对端明确确认过，或多次一致表现 | 对方说「对，就是这样」 |
+| inferred | 推断标记 | 从行为或上下文推断，对端未明确说过 | 对方总用列表回复，推断偏好列表格式 |
+| preference | 偏好类记忆 | 对端表达了稳定的偏好、风格或习惯 | 偏好简洁回复；不喜欢表格 |
+| rule | 规则类记忆 | 关于工作方式的正向约定 | commit 消息必须用中文；改代码前先读文件 |
+| prohibition | 禁令类记忆 | 明确说了不要做某件事 | 不要直接删文件 |
+| fact | 事实类记忆 | 关于项目、环境、技术的客观事实 | 项目用 vitest 跑测试 |
+| profile | 画像类记忆（保证进索引，不参与淘汰；一个关系只能有一条） | 关于对端这个主体的综合性描述 | 风格直接，不喜欢来回确认 |
+| feedback | 反馈类记忆 | 对端对我的工作给出了明确的纠正或评价 | 「你上次列了一堆选项，我不需要，直接给结论就行」 |
+| decision | 决策类记忆 | 一个方向性结论被确立，来自澄清或拍板均算 | memory.md 改名为 memory-consolidation.md |
+| context | 背景类记忆 | 项目或阶段的辅助背景，不属于其他类型 | 当前处于记忆系统 v2 设计阶段；上周完成 T17 |
+| to-generalize | 待泛化标记 | 这条关系级记忆换成别的对端大概率也成立 | 构建前要先清 dist；改代码前先读文件 |
+| to-promote | 待提升标记 | owner 明确定下、要求名下所有 agent 都遵守的规矩 | owner 说以后谁都不许自己提交 |
+| in-progress | 任务进行中 | 任务正在执行 | — |
+| pending | 任务等待中 | 等待条件或确认才能继续 | — |
+| blocked | 任务被阻塞 | 被外部因素卡住，无法推进 | — |
+| cancelled | 任务已取消 | 任务被放弃，不再推进 | — |
+| done | 任务已完成 | 任务结束，整理时从索引移除 | — |
+
+---
+
+## 规则
+
+1.  同一条记忆可以贴多个标签
+2.  `in-progress / pending / blocked / cancelled / done` 描述同一件事的状态，同一条记忆只选其中一个
+3.  `verified` 和 `inferred` 不同时贴
+
+---
+
+## 两个升级标记的用法
+
+`to-generalize` 和 `to-promote` 不是给记忆定性的，而是给整理会话留的**待办**：
+
+- 打上 `to-generalize` → 下次泛化模式会扫到它，评估能否升到 agent 级。
+- 打上 `to-promote` → 下次提升模式会扫到它，评估能否升到 owner 级。
+
+**打标的只有整理会话**（`create --tags`，事后可用 `update` 补）。主会话写的 note 不带标签。
+
+**清标的两种方式**：
+
+- 升级成功 —— 源文件被 `--replaces` 归档，标签随文件一起消失。
+- 评估后认为不该升级 —— 用 `update` 去掉标签，否则每次定时检查都会重新扫到它。
+
+**限制**：`to-promote` 只能打在对端是 owner 的关系上。其他对端打这个标签会被拒绝——否则它会永远挂在磁盘上没人处理。群聊关系下额外检查发言人身份，owner 本人说的话可以打。

package/kits/docs/evolcore/memory.md

@@ -0,0 +1,110 @@
+# ec memory — 记忆写入与整理
+
+写入、修改、撤销当前关系的临时记忆（note），以及手动触发整理。触发词：记住/记一下/mark it/这很重要/别忘了/泛化一下/提升一下/整理记忆。
+
+何时该写、每轮自检、召回方式见系统提示词的 `[memory]` 段；本页只讲命令用法。系统怎么运转见 `$KITS_DOCS/evolcore/memory-architecture.md`。
+
+## 边界
+
+- 仅在 evolcore 托管会话中可用（通过 daemon IPC 执行，依赖 `EVOLCORE_SESSION_ID`）。
+- `note` 写入当前关系，**必须有对端**（peerKey）；没有对端的会话不要调用。
+- `memory.enableRelation=false` 时整个命令族被拒绝。
+- **不要用 Write / Edit 直接写记忆文件，也不要用 baseagent 的原生记忆工具**：绕过签名和索引，整理会话不感知。
+- `create` / `update` / `archive` 只在整理会话（`sessionType=memory`）里可用，主会话调用会被拒绝。
+
+## note 写入
+
+```bash
+ec memory note --slug <slug> [--tags <tag1,tag2,...>] [--speakers <id1,id2,...>] "<正文>"
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--slug` | **必填**。字母/数字/连字符，1-64 字符，当前关系内唯一，后续 update / drop 靠它定位 |
+| `--tags` | 可选。逗号分隔，取值见 `$KITS_DOCS/evolcore/memory-tags.md` |
+| `--speakers` | 可选，**群聊专用**。逗号分隔，填本条 note 涉及的发言人 AID 或渠道原生 ID（如 `alice.agentid.pub,bob.agentid.pub`）。整理会话会据此把发言人相关信息分流写入各发言人自己的 relation 记忆，而不是只落在群的 relation 下。私聊场景无需填写。 |
+| 正文 | 必填。写清事实本身即可，不用组织成索引描述 |
+
+```bash
+ec memory note --slug commit-chinese --tags "rule,long-term" \
+  "对端要求：commit message 必须用中文，并列出所有功能改动点。"
+```
+
+note 是原料：不进索引、不签名，由整理会话读取后决定留下什么。
+
+## note 修改
+
+```bash
+ec memory note update <slug> [--slug <新slug>] [--tags <...>] ["<新正文>"]
+```
+
+不传的字段保持不变；至少提供一项。判据：**还是在说同一件事 → update；不是 → 新建。**
+
+```bash
+ec memory note update commit-chinese --tags "rule,long-term" \
+  "commit 消息必须用中文；代码注释可以是英文"
+```
+
+## note 撤销
+
+```bash
+ec memory note drop <slug>
+```
+
+文件移入 `pending/archive/`，不会真删。drop 后 slug 空出，可同名重建。
+
+## note 查看
+
+```bash
+ec memory note list
+```
+
+列出当前关系 `pending/` 里的 note（slug + 标签 + 首行）。长会话里忘了写过什么就先查一下，避免重复新建。
+
+## 触发整理
+
+```bash
+ec memory consolidate [--mode <notes|generalize|promote|profile|forget>]
+```
+
+| 模式 | 做什么 | 什么时候用 |
+|------|--------|-----------|
+| `notes`（默认） | pending → 关系级正式记忆 | 想立刻固化刚才聊到的东西 |
+| `generalize` | 关系级 → agent 级 | 对端说「不管跟谁聊你都要记得这个」 |
+| `promote` | 关系级 → owner 级 | owner 说「让我所有 Agent 都记住这个」 |
+| `profile` | 生成/重建当前对端画像 | owner 说「重新生成一下画像」 |
+| `forget` | 评估超期记忆续期或归档 | 一般不手动，由定时检查发起 |
+
+**命令是异步的**：`launchConsolidation()` 在拿到整理会话的 base agent 会话 ID 后命令即退出，不等整理会话完成。输出示例：
+
+```
+整理会话已启动（notes 模式）
+agentSessionId: d6c2835e-3ccb-494b-b391-9725c5578043
+context:        C:\...\consolidation-batches\20261005T103000-toleiliang4.agentid.pub-notes\context.md
+```
+
+`agentSessionId` 用于调试，可以在 base agent 的会话目录里找到对应的日志。整理完成后，结果会以消息形式反馈到**当前会话的当前话题**。
+
+反馈规则：手动、上下文压缩、renew、`/new` 四种触发路径都会把整理结果反馈回**发起时的会话和话题**（用发起时抓取的 channelId / peerId / threadId 直接投递，不依赖会话 ID 是否变化）。只有定时触发不发反馈——结果只记录在整理批次目录的 `ops.jsonl` 里，供事后审计。
+
+反馈内容优先取整理会话调用 `ec memory feedback` 写入的文本；未调用时回退到默认模板（模式、触发方式、耗时、新建/更新/归档条数等统计）。
+
+没有 `--scope`，作用域由模式唯一决定。
+
+## 常见报错
+
+| 报错 | 原因与处理 |
+|------|-----------|
+| `必须提供 --slug` | 写入漏了 `--slug`，补上：`ec memory note --slug <slug> "<正文>"` |
+| `必须提供记忆内容（content）` | 正文缺失或被 shell 吞掉，正文整体加引号 |
+| `SLUG_EXISTS: 该 slug 已存在同名 note: <路径>` | 撞名。补充同一件事 → `note update <slug>`；确实是新事 → 换 slug |
+| `至少提供一项要改的内容` | `note update` 只给了 slug，补 `--slug` / `--tags` / 正文之一 |
+| `未知参数: --xxx` | 参数拼错，未识别的参数一律报错 |
+| `--scope 已废弃` | 改用 `--mode` |
+| `<op> 只能由整理会话（sessionType=memory）调用` | 主会话调用了 `create` / `update` / `archive`，改用 `ec memory note` |
+
+## 相关文档
+
+- 系统概述（作用域、流水线、开关、目录） → `$KITS_DOCS/evolcore/memory-architecture.md`
+- 标签取值全集 → `$KITS_DOCS/evolcore/memory-tags.md`
+- 整理会话工作机制 → `$KITS_DOCS/evolcore/memory-consolidation.md`

package/kits/docs/evolcore/menu-client.md

@@ -2,11 +2,8 @@
 
 向另一台主机的 EvolCore Control AID 发送标准 `menu.*` 请求。独立终端使用 AUN 短连接完成发送、拉取、匹配和 ACK；EvolCore 托管 Agent 自动通过当前 daemon 的委托入口与现有 AUN 连接完成调用。
 
-## 托管会话边界
-
-托管调用必须使用当前 self AID，并拥有 `ec.menu.request` 的 relation 权限。daemon 校验当前 session、委托和角色，按目标 AID 与 request ID 匹配加密响应；普通角色的聊天权限不自动授予远程 Menu 调用能力。
-
-托管模式不接受 `--app`、`--aun-path`、`--no-encrypt`，也不创建独立连接或清理 daemon 的消息。`--request-file` 由 daemon 校验后读取，须为当前项目或本会话 `$TMPDIR` 内不受保护的普通文件，最大 128 KiB；也可用 `--request-json`。目标是否允许具体操作，仍由远端 Control Menu 的 Token/Owner 鉴权决定。
+> **本文只讲工具用法**（CLI 语法、参数、连接与输出行为）。
+> Menu 消息的格式、`protected_headers`、鉴权机制见 `menu-protocol.md`；通过 menu exec 取配置 schema 见 `menu-exec-schema-commands.md`。
 
 ## 用法
 
@@ -18,21 +15,40 @@ ec menu-client request <from-aid> <daemon-aid> \
   --format json
 ```
 
-- `--request-file` 与 `--request-json` 二选一，内容是现有 Menu request；缺少 `id` 时自动生成 UUID。
+- `--request-file` 与 `--request-json` 二选一，内容是**现有 Menu request**（结构见 `menu-protocol.md §三`）；缺少 `id` 时自动生成 UUID。
+- 请求与响应的 `ttl`、volatile 游标、`to_device_id` 定向回复等传输细节由 CLI 与 daemon 自动处理，调用方无需关心。
 - 默认使用 E2EE，并发送 `client_name=ec-menu-client` 和本机 EvolCore `client_version`。
 - 独立终端默认 slot 是 `evolcore-menu-client`；`--app <slot>` 可覆盖，但会切换消费游标，调用方须自行串行化。托管模式使用 daemon 的现有连接和 ACK 路径。
+- `menu.query` / `menu.options` 等待响应超时时自动重发一次相同 request id；写操作不自动重试。
+
+## 鉴权入口
+
 - 默认授权是远端 `daemon.json.owners` 对发送 AID 的校验。
 - `--remote-token <token>` 使用 daemon 签发的远程访问 token，权限与 daemon-owner 一致。CLI 审计日志不会记录 token 明文。
+- `--ecweb-token <token>` 是 `--remote-token` 的兼容别名。
 - `system/paircode` 例外：仅接受加密的 daemon-owner 请求，已有 remote token 不能换取新配对码。
+
+> 具体的权限判定层次（哪些 operation 需要 daemon-owner、哪些走 agent 角色）见 `menu-protocol.md §五`。
+
+## 托管会话边界
+
+托管调用必须使用当前 self AID，并拥有 `ec.menu.request` 的 relation 权限。daemon 校验当前 session、委托和角色，按目标 AID 与 request ID 匹配加密响应；普通角色的聊天权限不自动授予远程 Menu 调用能力。
+
+托管模式不接受 `--app`、`--aun-path`、`--no-encrypt`，也不创建独立连接或清理 daemon 的消息。`--request-file` 由 daemon 校验后读取，须为当前项目或本会话 `$TMPDIR` 内不受保护的普通文件，最大 128 KiB；也可用 `--request-json`。目标是否允许具体操作，仍由远端 Control Menu 的 Token/Owner 鉴权决定。
+
+## 配对码与 token 生命周期
+
 - 配对码有效期为 10 分钟，成功兑换一次即失效；并发兑换最多一次成功。再次获取会生成新码，已签发 token 不受影响。
 - 未消费的码由各入口共享，重复获取不延长有效期。发放来源记录在运行时 `data/instance/control-access-tokens.json` 的 `pairingIssuances`：`host-cli` 为宿主机 CLI，`pair` 为 `/pair`，`menu` 为 AUN Menu，`ecweb-local` 为本地 ECWeb。`pair` / `menu` 同时记录已认证 daemon owner 的 `authorizedBy` AID；同一码经多个入口发放时保留全部不同来源与 owner，而不覆盖旧记录。
 - 发放记录包含 `pairingId`、发放/到期时间、`issuers` 和成功兑换时间 `redeemedAt`，保留 30 天；不保存配对码或其哈希。成功兑换的 token 同时保存 `pairingId` / `pairingIssuers`，后续续期与 daemon 重启不丢失来源。旧 token 缺少来源时不补造历史。
-- `--ecweb-token <token>` 是 `--remote-token` 的兼容别名。
-- Menu 请求和响应使用 `message.send` 顶层 `ttl: 60`，接收响应时应支持 volatile 游标和无持久 `seq`；响应若带 `sender_device_id`，服务端会用 `to_device_id` 定向回原设备。
-- `menu.query` / `menu.options` 等待响应超时时自动重发一次相同 request id；写操作不自动重试。
+
+## 输出与退出码
+
 - 成功时 stdout 是完整 `menu.response` JSON。远端业务错误仍在响应的 `error` 字段中；本地传输/超时错误退出码非 0。独立终端的 ACK 错误也以非零退出码返回；托管模式由 daemon 的正常消费路径处理 ACK。
 
-## 常用请求
+## 常用请求示例
+
+请求体的完整字段定义见 `menu-protocol.md §三`。以下是可直接填入 `--request-json` 的样例：
 
 ```json
 {"type":"menu.query","id":"status-1","name":"system","args":{"view":"status"}}
@@ -54,5 +70,5 @@ ec menu-client request <from-aid> <daemon-aid> \
 
 子任务示例需发往目标 Agent 的会话；话题可用 `name=topic args={"target":"<threadId>","view":"subtasks"}`。
 返回 `{ scope: "retained-history", tasks: [...] }`。普通 session/topic 状态另带 `subtasks`、`subtasksScope`；
-`/status` 单列“已记录子任务数”，不把它加到主会话轮数中。历史来自现有 `events*.log`，
+`/status` 单列"已记录子任务数"，不把它加到主会话轮数中。历史来自现有 `events*.log`，
 受 `EVENT_LOG` 开关和日志保留期限制（当前归档保留 48 小时）；无记录不能据此推断从未执行过子任务。

package/kits/{schemas → docs/evolcore}/menu-exec-schema-commands.md

@@ -1,7 +1,7 @@
 # 通过 menu action exec 获取 Schema 的命令手册
 
 > 面向前端（App / Web / Bot）通过 `menu.action name=cli action=exec` 远程执行 CLI，取回配置 schema 的**版本**与**内容**。
-> 传输层、`menu.response` 配对、错误处理等通用机制见 [menu-protocol-cli-exec-frontend.md](./menu-protocol-cli-exec-frontend.md)。
+> 传输层、`menu.response` 配对、错误处理等通用机制见 `$KITS_DOCS/evolcore/menu-protocol.md`。
 
 对应代码：`src/cli/config.ts` · `src/config/config-operation-service.ts`（`executeSchema`）· `src/config/schema-registry.ts`
 
@@ -27,7 +27,7 @@
   - `exitCode === 0` 才算命令成功；`--format json` 时对 `stdout` 直接 `JSON.parse`。
 - 失败（透传层拒绝，命令没跑）：`error = { code, message }`。
 
-> 逻辑 schema 名（`<name>`）：`daemon` / `defaults` / `agent-config` / `relation-config` / `contact-book` / `single-session`。各名对应哪份配置见 [§6 配置 ↔ Schema 对应表](#6-配置--schema-对应表)。
+> 逻辑 schema 名（`<name>`）：`daemon` / `defaults` / `agent-config` / `relation-config` / `contact-book` / `single-session`。各名对应哪份配置见 [§5 配置 ↔ Schema 对应表](#5-配置--schema-对应表)。
 
 ---
 
@@ -149,7 +149,7 @@
 
 ---
 
-## 6. 配置 ↔ Schema 对应表
+## 5. 配置 ↔ Schema 对应表
 
 每份配置文件由 `ConfigTarget` 路由到唯一的 schema（`src/config/config-manager.ts` 的 `TARGET_SCHEMA`）。查某份配置有哪些字段、类型/枚举/默认，就用 §2 拉对应 `<name>` 的内容。
 
@@ -188,21 +188,27 @@
 
 ---
 
-## 5. 完整发送样例（AUN）
+## 6. 完整发送样例（AUN）
 
 ```typescript
 await client.call('message.send', {
   to: targetAid,
-  payload: JSON.stringify({
+  payload: {
     type: 'menu.action',
     id: 'c-schema-1',
     name: 'cli',
     action: 'exec',
     args: { argv: ['config', 'schema', 'agent-config', '--format', 'json'] },
-  }),
+  },
   encrypt: true,
+  ttl: 60,                        // MENU_MESSAGE_TTL_SECONDS
+  protected_headers: { client_name: 'Evol App' },
 });
 // 响应在 onMessage 里按 parsed.id 配对：
 //   parsed.data.exitCode === 0 → JSON.parse(parsed.data.stdout).content
 //   parsed.error → 透传层拒绝
 ```
+
+- `payload` 传**对象**（不是 `JSON.stringify` 后的字符串）；`message.send` 的协议层要求 payload 是 JSON 对象。
+- `ttl: 60` 是 Menu 消息的固定约定（`src/aun/menu/transport.ts` 的 `MENU_MESSAGE_TTL_SECONDS`），缺失时不会被自动补上。
+- `protected_headers` 承载客户端标识与鉴权方式，字段定义见 `menu-protocol.md §二`。