evolcore 0.0.28 → 0.0.29-test.0

package/kits/docs/evolcore/ec-capabilities.md

@@ -0,0 +1,364 @@
+# EC Skill 系统
+
+EC 的技能系统：**一组可加载的能力单元**。每个技能是一个目录，里面放一个 `SKILL.md`。
+本文是整个机制的概要，面向使用者。
+
+> 写技能、装技能、调试技能没生效——看本文就够。开发设计细节见文末「开发设计文档」。
+
+---
+
+## 1. 技能是什么
+
+一个技能 = 一个目录 + 一个 `SKILL.md`：
+
+```
+<skill-name>/
+├── SKILL.md          # 必须。YAML frontmatter + Markdown 正文
+├── references/       # 可选。大块参考资料，按需读取，不进默认上下文
+├── scripts/          # 可选。确定性脚本
+└── assets/           # 可选。模板、样例数据
+```
+
+格式遵循 **Agent Skills 标准**，与 Claude Code / Codex / OpenClaw 一致——写技能的人不用学第二套规范，
+社区已有的技能可以直接拿来用。
+
+`<skill-name>` 用小写字母、数字、连字符（kebab-case），**且必须与 `SKILL.md` 里 `name` 字段一致**。
+
+### 与 Base Agent 技能的关系
+
+**不复用、不代理、不封装。** Claude Code / Codex / Gemini CLI 各自的技能由它们自己管理，
+EC 不在上面再套一层。EC 只管「EC 自身有哪些技能、哪些启用」。
+
+---
+
+## 2. 三级目录
+
+| 级别 | 位置 | 内容 | 生命周期 |
+|---|---|---|---|
+| **内置级** | `<包根>/kits/skills/` | `SKILL.md` + 开关 | 随包发布，用户不应直接改 |
+| **本机级** | `$EVOLCORE_HOME/skills/` | `SKILL.md` + 开关 | 本机安装，本机所有 agent 共享 |
+| **Agent 级** | `$EVOLCORE_AGENT_DIR/skills/` | **只有开关，没有 `SKILL.md`** | 按 agent 单独调整 |
+
+三条实际路径用 `ec skill where` 打印，不要凭记忆猜。
+
+**为什么叫「本机级」而不是「用户级」**：三家 base agent 的惯例叫 user-level，语义其实也是按机器共享。
+但 EC 里「用户」已经是关系层的角色概念（owner / admin / member / visitor），沿用会歧义。
+「主机级」也被否——`host` 在 ECK 中已是对端类型（daemon AID）。所以定为**本机级**：按机器划界。
+
+**关系级不参与**。技能启用与否不按对端区分，只到 Agent 级为止。
+
+---
+
+## 3. 开关机制
+
+### 开关文件
+
+开关**不是**每技能一个文件，而是**每级一个字典** `.switches.json`，放在各自的 skills 目录内：
+
+```
+内置级：<包根>/kits/skills/.switches.json
+本机级：$EVOLCORE_HOME/skills/.switches.json
+Agent 级：$EVOLCORE_AGENT_DIR/skills/.switches.json
+```
+
+```json
+{
+  "my-skill": { "enabled": true },
+  "core-guard": { "enabled": true, "locked": true }
+}
+```
+
+| 字段 | 含义 |
+|---|---|
+| `enabled` | 该级是否启用这个技能 |
+| `locked` | **仅内置级读取**。`true` = 拒绝被本机级 / Agent 级覆盖 |
+
+缺省语义：
+
+- 技能名**不在字典里 → 禁用**（开关字典是显式白名单）
+- 只有 `enabled: true` 算启用；字段缺失、写成其它值、文件损坏都按禁用处理
+- 文件不存在 = 空字典 = 所有技能禁用
+
+### `locked` 与 `enabled` 正交
+
+`locked` **只表达「不可覆盖」，不表达「强制开」**。两个字段是独立维度：
+
+| enabled | locked | 含义 |
+|---|---|---|
+| （无文件） | — | 禁用，可被下级覆盖 |
+| `true` | `false` | 开，可被下级覆盖 |
+| `false` | `false` | 关，可被下级覆盖 |
+| `true` | `true` | **强制可用，任何级别都关不掉** |
+| `false` | `true` | 关着，且任何级别都打不开 |
+
+典型用途是基础设施类技能——EC 自身运行依赖、不允许被误关。
+
+### 覆盖链
+
+```
+Agent 级  >  本机级  >  内置级
+```
+
+由近及远逐级覆盖。求值规则：
+
+```
+1. 若内置级存在且 locked: true
+     → 结论由内置级的 enabled 唯一决定，直接返回
+2. 否则，从 Agent 级往下找第一个有显式声明的层级
+     → 用它的 enabled 作为结论
+3. 三级都没有声明 → enabled 默认 false（禁用）
+```
+
+注意：内置级与本机级同名时，**不是简单的「内置优先」或「本机优先」**，而是按声明逐级求值。
+
+---
+
+## 4. 渐进式披露
+
+**技能正文不常驻上下文。** 常驻的只有每个技能的 `name` + `description`，写在这两个文件里：
+
+```
+$AGENT_DIR/skills/.index-builtin.md    内置技能索引
+$AGENT_DIR/skills/.index-local.md      本机技能索引
+```
+
+由 ECK manifest 注入（`order` 20.5 / 20.6，位于身份层之后、关系层之前）。技能属于
+「我有什么能力」的自我认知，与身份层同族，所以排在前面。
+
+模型的行为链：
+
+```
+① 读索引    → 看到「本 Agent 有这些技能」
+② 判断相关  → 按 description 比对当前任务
+③ 读全文    → Read <根目录>/<技能名>/SKILL.md
+④ 执行      → 按 SKILL.md 指令执行；需要时读 references/、跑 scripts/
+```
+
+**因此 `description` 是路由器，不是介绍文案。** 写得含糊，技能永远不会被选中。
+
+索引文件由监控器**自动重建**（约 2 秒防抖）：改 `.switches.json`、改 `SKILL.md`、增删技能目录
+都会触发。不需要手工刷新。
+
+**该组没有任何启用的技能时不生成索引文件**——manifest 按「文件是否存在」判断，不存在就跳过注入，
+上下文里不会出现「暂无技能」这类零信息量段落。
+
+---
+
+## 5. 路径：模型自己拼绝对路径
+
+EC **不会把 cwd 设到技能目录**（runner 拉起 base agent 时 cwd 固定为项目目录，且 Claude Code 的
+Bash 工具没有 cwd 参数），所以三家的「裸相对路径直接可用」在 EC 复现不了。
+
+EC 的解法：**索引里给根目录 + 拼路径规则，模型自己拼成绝对路径**。
+
+```
+路径规则:
+  根目录: <该组的真实绝对路径>
+  技能目录 = 根目录 + 路径分隔符 + 技能名
+  SKILL.md = 技能目录 + 路径分隔符 + "SKILL.md"
+  执行脚本时必须写完整绝对路径。
+```
+
+好处是**社区技能不用改**——正文里照写裸相对路径，模型知道技能目录在哪，自己就能拼。
+
+配套硬要求：**脚本内部必须用自身位置定位资源，不能依赖 cwd**。
+
+```js
+// 好：从脚本自身推
+const SKILL_DIR = path.resolve(import.meta.dirname, '..');
+
+// 差：cwd 不对就挂
+fs.readFileSync('assets/template.csv');
+```
+
+理由：即使模型把脚本路径拼对了，脚本自身的 cwd 仍是**模型调 Bash 时的 cwd**（项目目录）。
+
+---
+
+## 6. 编写规范
+
+### frontmatter
+
+必填两项：
+
+```yaml
+---
+name: my-skill                    # 必须与目录名一致，kebab-case
+description: >-                   # 最关键：写清做什么 + 触发场景 + 不适用场景
+  一句话说清能力。当用户要求……时使用。不适用于……
+---
+```
+
+可选字段（Agent Skills 标准）：
+
+| 字段 | 说明 |
+|---|---|
+| `license` | 许可协议标识（`MIT`、`Apache-2.0`）。分享型技能建议写 |
+| `compatibility` | 兼容性声明，标注依赖的运行时 / 平台 / 版本约束 |
+| `metadata` | 自由键值对（作者、版本、仓库地址）。各家都不解析，纯透传 |
+| `allowed-tools` | 工具白名单（`Read, Grep, Glob, Bash`）。不写则继承当前会话权限 |
+
+Claude Code 扩展字段（`disable-model-invocation`、`user-invocable`、`context: fork`、`agent`）
+EC **读取但不强依赖**——不认识就忽略，不报错。
+
+**未知字段一律忽略不报错**，这是向前兼容的前提。
+
+### `description` 怎么写
+
+官方文档明确指出模型有「触发不足」的倾向。有效写法：
+
+1. **先写做什么**：一句话说清能力
+2. **再列举触发场景**：用户可能说的原话、涉及的文件类型、典型任务
+3. **显式写不适用场景**：`不适用于……`，防止误触发
+4. **包含关键词**：用户真实会说的词，而不是术语
+
+```yaml
+# 差：模型不知道什么时候该用
+description: 处理 CSV 文件
+
+# 好：触发条件写死
+description: >-
+  清洗并规范化 CSV 文件。当用户要求清洗、去重、修正 CSV，或提到表头混乱、
+  列序不一致、编码问题时使用。不适用于 Excel 宏、PDF、图片数据。
+```
+
+建议控制在单行可读、总长约 **1536 字符**以内（三家共同的截断阈值）。**把最关键的用例放最前面**。
+
+### 正文结构
+
+建议：**目标 → 步骤（编号、祈使句）→ 输出契约 → 边界情况 → 参考资料指引**。
+控制在 **500 行**内，超出部分挪到 `references/`。
+
+### 脚本语言偏好
+
+| 优先级 | 语言 | 理由 |
+|---|---|---|
+| 1 | **Node.js** | EC 本身是 Node 项目，`node` 必然存在，零依赖问题 |
+| 2 | shell | Windows 上要看 Git Bash 是否可用 |
+| 3 | Python | 完全靠用户自装，最不可靠 |
+
+**随包发布的内置技能，脚本优先用 node 写**，否则用户装完 evolcore 会发现内置技能有一半跑不了。
+
+### 依赖声明
+
+技能可以在 `metadata.requires` 里声明运行时依赖：
+
+```yaml
+metadata:
+  requires:
+    bins: [python3]          # 每个都必须在 PATH 里存在
+    anyBins: [jq, python3]   # 至少有一个
+    env: [GROQ_API_KEY]      # 环境变量必须存在
+  os: [linux, darwin, win32] # 平台限制
+```
+
+检查在**索引生成阶段**执行：不满足的技能**从索引里排除**，不进模型上下文。
+技能本身没消失、开关也还是开着的，只是当前主机跑不了——这个状态在前端展示（提示缺什么）。
+
+**不自动安装依赖。** 自动装运行时是重大副作用，不该由技能系统发起。前端只负责说清楚缺什么。
+
+---
+
+## 7. 权限
+
+**技能不能成为提权手段。** 最终可用工具取交集：
+
+```
+最终可用工具 = 技能的 allowed-tools  ∩  当前会话权限
+```
+
+- 技能的 `allowed-tools` **只能收紧，不能放宽**。会话是 `readonly` 时，技能声明再多工具也没用
+- 会话放宽了、技能没收紧，按会话走
+- 技能没声明 `allowed-tools`，等同于不额外收紧
+
+技能的脚本执行与普通 Bash 调用走**同一道闸门**，不另开通道——权限判据只有一套，
+已有的审计、拒绝提示、审批流程自动生效。
+
+---
+
+## 8. 命令
+
+```bash
+ec skill list [--json]                  # 列出所有技能：名称、来源、最终状态
+ec skill info <name> [--json]           # 单技能详情：路径、描述、三级开关、生效依据
+ec skill create <name> [--desc "..."] [--enable]   # 新建技能骨架到本机级（默认禁用）
+ec skill install <源> [--force] [--enable]         # 安装技能（目录 / .zip / .md，默认禁用）
+ec skill remove <name>                  # 删除本机技能（内置技能不能删）
+ec skill enable <name> [--level agent|local]
+ec skill disable <name> [--level agent|local]
+ec skill validate <name|路径>           # 校验 SKILL.md 是否合规
+ec skill where                          # 打印三级根目录的实际路径
+```
+
+### 常见任务
+
+**装一个技能**：
+
+```bash
+ec skill install ./my-skill/            # 目录
+ec skill install ./my-skill.zip         # 压缩包
+ec skill install ./foo.md               # 单个 SKILL.md
+```
+
+安装前会**自动校验 `SKILL.md`**，不合规直接拒绝。已存在同名技能加 `--force` 覆盖。
+`.zip` 首次使用会自动装解压依赖（需要联网，之后离线可用）。
+
+**装完默认禁用**：`install`（连同 `create`）**不写开关文件**——字典里没有该技能就是禁用，
+技能不进索引、不会被模型选中。确认可用之后显式启用：
+
+```bash
+ec skill enable <name>
+```
+
+要装完即启用就加 `--enable`（此时才写入 `{"enabled": true}`）：
+`ec skill install ./my-skill/ --enable`。
+这是刻意设计——陌生技能在未经确认前不应自动生效。
+
+**查某个技能为什么没生效**：
+
+```bash
+ec skill info <name>
+```
+
+看 `生效依据` 那一行，它会指出是 Agent 级 / 本机级 / 内置级 / 默认值决定了当前状态。
+
+---
+
+## 9. 边界情况
+
+- **装完默认禁用**：`install` / `create` 不写开关文件，缺省即禁用，技能不进索引、
+  不被选中，等确认后再 `enable`；加 `--enable` 可装完即启用
+- **开关是显式白名单**：字典里没有该技能 = 关；要关一个已启用的技能写 `{"enabled": false}`
+  或直接删条目，效果相同
+- **内置技能不可删**：随包发布，`remove` 会拒绝。要停用请用 `disable`
+- **Agent 级不能装技能**：那一级只有 `.switches.json`。想让某技能只对单个 agent 生效，
+  先装到本机级，再对其他 agent `disable --level agent`
+- **`locked` 技能关不掉**：`enable` / `disable` 会拒绝并说明原因
+- **离线环境**：`install` 用目录方式不受影响；`.zip` 需要联网装一次解压依赖
+- **改动后约 2 秒生效**：索引重建有防抖，不用手工触发
+
+### 常见坑
+
+| 症状 | 原因 |
+|---|---|
+| 技能不出现 | 索引里没有 → 检查开关、`name` 与目录名是否一致、依赖是否满足 |
+| 装完立刻用但没反应 | 防抖 2 秒未到，稍等再看 `ec skill list` |
+| 脚本找不到文件 | 脚本内部依赖了 cwd。必须用自身位置定位资源 |
+| 改了 `SKILL.md` 但模型行为没变 | 模型已经读过旧正文，本轮上下文里不会自动刷新 |
+
+---
+
+## 10. 开发设计文档
+
+以下文档**只在源码仓库里**（`docs/skills/`），**不随 npm 包发布**——它们面向开发者，
+讲的是机制怎么设计的、为什么这么取舍：
+
+| 文档 | 内容 |
+|---|---|
+| `docs/skills/skill-md-spec-and-loading.md` | `SKILL.md` 规范、frontmatter 字段语义、渐进式披露、三家对照 |
+| `docs/skills/ec-skill-system-design.md` | 三级目录、开关模型、覆盖链、`locked` 正交语义、前端展示 |
+| `docs/skills/ec-skill-injection.md` | 索引怎么生成、防抖、文件格式、manifest 注入段位 |
+| `docs/skills/skill-script-execution.md` | 脚本执行机制、路径解析、依赖检查、权限闸门、隔离与 8 个待澄清问题 |
+
+读到本文（`ec-capabilities.md`）说明你拿到的是**随包发布**的那一份。若要深挖实现细节，
+先确认手上是否有源码仓库；没有就以本文为准。

package/kits/docs/evolcore/group.md

@@ -10,6 +10,8 @@
 
 ## 消息
 
+内联正文及文本选项（`--text`、`--transcript`、`--description`、`--question`、`--message`、`--answer`、`--reason`）遵循与私聊相同的单次 `\n` / `\r` / `\t` / `\\` 解码契约；真实换行也支持。PowerShell 中不要使用反引号换行转义，物理多行使用命令名而非显式批处理入口。文件、路径和 `--payload` JSON 不解码；名称和状态不是长文本。
+
 ```bash
 # 文本（含空格/换行/特殊字符时用引号包起来；纯短词可不包，但多空格会被压成一个）
 ec group send <from> <group-id> "<text>" --return none|required [--encrypt]
@@ -20,9 +22,8 @@ ec group send <from> <group-id> --file <path> --return none|required [--as <type
 # 自定义 payload
 ec group send <from> <group-id> --payload '<json>' --return none|required
 
-# 查询本地群历史（不调用 Gateway，不推进 group pull/ack 游标）
-ec group history <from> <group-id> --unread [--limit <N>] [--thread <id>] [--format json]
-ec group history <from> <group-id> --all [--limit <N>] [--thread <id>] [--format json]
+# 查询本地群历史（只读，不调用 Gateway，不推进 group pull/ack 游标）
+ec group history <from> <group-id> [--limit <N>] [--thread <main|all|id>] [--format json]
 
 # 拉取群消息（建议带 --app 独立消费通道，避免影响 daemon）
 ec group pull <from> <group-id> [--after-seq <N>] [--limit <N>] [--app <name>]
@@ -54,36 +55,35 @@ ec group send <from> <group-id> "通知" --mention alice.agentid.pub,bob.agentid
 
 ## 本地群历史
 
-`history` 读取本机的 `messages.jsonl`，不连接 Gateway，不改变 `group pull/ack` 游标。
-这里的自动已读只记录本地历史查询进度；`group pull` / `group ack` 仍是独立的 Gateway 消费游标命令，二者互不替代。
-查询必须显式指定 `--unread` 或 `--all`；首次没有日志时返回空结果，不创建模型会话。
+`history` 读取本机的 `messages.jsonl`，不连接 Gateway，不改变 `group pull/ack` 游标，也不维护本地已读游标。
+`group pull` / `group ack` 仍是独立的 Gateway 消费游标命令，二者互不替代。
+查询始终只读；首次没有日志时返回空结果，不创建模型会话。
 
 | 选项 | 含义 |
 |---|---|
-| `--unread` | 最早的未读群背景，按本地记录顺序输出，并自动记录本页已读 |
-| `--all` | 最近的群会话历史，包含没有未读标记的旧日志及出站消息 |
+| 默认 | 最近的群会话历史，包含入站和出站普通消息 |
 | `--limit N` | 默认 50，范围 1–500；单页另有 24 KiB 消息预算 |
 | `--thread main\|all\|id` | 无话题、整个群或指定话题；当前群任务默认继承当前话题，其他调用默认 all |
 | `--direction in\|out\|all` | 方向过滤，默认 all |
 | `--before/--after time` | 接收时间开区间，支持 epoch 毫秒和 ISO 时间 |
+| `--before-id/--after-id id` | 同一时间戳分页的 64 位游标 ID，需配合对应时间参数 |
+| `--before-id/--after-id id` | 同一时间戳分页时的消息 ID tie-break，需配合对应时间 |
 | `--format text\|json` | 默认 text |
-| `--message msg-id` | 配合 --all 查询指定消息正文，不改变已读状态 |
+| `--message msg-id` | 查询指定消息正文，不改变任何状态 |
 | `--offset bytes` | 配合 --message 从返回的 next_offset 继续读取长正文 |
 
-`--unread` 会把本次返回的消息自动记为已读，再次执行即可取得下一页，无需额外确认。
-查询期间新到的消息、未返回条目及其他筛选范围的消息不会被清除。`--all` 始终只浏览、不改变已读状态。
-`has_more` 表示本次还有匹配内容，普通 `--all` 可用时间/话题进一步缩小范围。
+`has_more` 表示本次还有匹配内容。按结果中的 `next_before` / `next_after` 原样传入时间和
+64 位游标 ID 获取相邻页，保证同一毫秒的多条消息也不会漏读或重复。
 
-长正文以 `content_truncated` 标识；预览返回后该消息也记为已读，需要完整内容时使用
-`--all --message <msg-id> --offset <next_offset>` 继续读取。偏移为 UTF-8 字节边界，每段最多 8 KiB。
-附件返回已有类型、名称或转写摘要，不自动下载。已读不会删除历史，随时可用 `--all` 回看。
+长正文以 `content_truncated` 标识，需要完整内容时使用
+`--message <msg-id> --offset <next_offset>` 继续读取。偏移为 UTF-8 字节边界，每段最多 8 KiB。
+附件返回已有类型、名称或转写摘要，不自动下载。
 
 受管执行通过 `group.op` 和 delegation 授权；member 限当前 Agent 的当前 AUN 群，
-owner/admin 按 Agent 管理范围查询其他群；visitor 默认拒绝。读取时的已读记录由服务内部维护。
+owner/admin 按 Agent 管理范围查询其他群；visitor 默认拒绝。
 不支持 `--app`、`--aun-path` 或自选历史文件路径。
 
-旧记录仍可用 `--all` 查询；精确未读统计从新增的本地过滤标记开始，不根据缺少 sessionId 猜测。
-已读状态独立存储，重启、renew、切模型不会清空；历史只包含本机收到并记录的会话内容。
+历史只包含本机收到并记录的会话内容；不根据缺少 sessionId 推断读取状态。
 
 ## 群管理
 
@@ -238,6 +238,22 @@ ec group member-statuses <from> <group-id>
 操作他人和查询屏蔽列表需要 Core owner/admin，随后仍由 Gateway 校验该 Agent 的群内权限。
 visitor 不开放这五个命令；托管调用不允许替换 `<from>`、`--app` 或 `--aun-path`。
 
+## @ 提及模式
+
+```bash
+# 查看当前群生效的提及模式及来源（本群覆盖 / Agent 全局 / AUN 服务端 / 默认配置）
+ec group mention <from> <group-id>
+
+# 设置本群覆盖；可选 mention-only（被 @ 才响应）/ disabled（全响应）/ auto（本地自动判断）
+ec group mention <from> <group-id> mention-only
+
+# 清除本群覆盖，回到跟随上级设置
+ec group mention <from> <group-id> --clear
+```
+
+`<mode>` 与 `--clear` 互斥。本命令只调整本群 relation 级覆盖，Agent 全局默认走 `/mention` slash 命令
+（私聊写 Agent 级）或 `ec config set mentionMode`。
+
 ## 入群与公告
 
 当前 CLI 封装了 `join` 和 `rules`。审批申请、邀请码、公告等高级管理能力第一批暂不提供单独命令。

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

@@ -0,0 +1,78 @@
+# 记忆系统概述
+
+记忆系统怎么运转：作用域、流水线、开关、目录结构。命令用法见 `$KITS_DOCS/evolcore/memory.md`；整理会话细节见 `$KITS_DOCS/evolcore/memory-consolidation.md`。
+
+## 流水线
+
+```
+主会话写 note  →  pending/  →  整理会话产生正式记忆  →  consolidated/  →  索引自动注入
+```
+
+- **note 是原料**：主会话写，不分类、不判断层级，不进索引、不签名。
+- **正式记忆只由整理会话产生**：读 note 或候选记忆，判断取舍，用 `create` / `update` / `archive` 写入。程序负责签名、重建索引、落日志。
+
+## 三个作用域
+
+| 作用域 | 位置 | 怎么产生 | 谁能看到 |
+|------|------|---------|---------|
+| relation | `$RELATIONS_DIR/<peerKey>/memory/` | `notes` / `profile` 模式 | 与该对端的会话 |
+| agent | `$PERSONAL_DIR/memory/` | `generalize` 模式（关系级 → agent 级） | 当前 agent 的所有会话 |
+| owner | `$EVOLCORE_HOME/memory/owner/<ownerAid>/` | `promote` 模式（关系级 → owner 级） | owner 名下所有 agent 的会话 |
+
+relation 是所有记忆的唯一出生地，agent 级和 owner 级都由它升格而来。
+
+## 整理什么时候启动
+
+| 触发 | 说明 |
+|------|------|
+| 上下文压缩前 | 自动。反馈回压缩时的会话和话题 |
+| renew / 新会话创建时 | 自动。反馈回发起时的会话和话题 |
+| 定时检查 | 自动。由 evolcore trigger 的 `script` 模式周期执行，检查 pending 堆积、待泛化 / 待提升 / 超期记忆 / 画像超期五类候选；**不反馈** |
+| 手动 | `ec memory consolidate [--mode ...]`。反馈回当前会话的当前话题 |
+
+所有触发路径都收口到统一入口 `launchConsolidation()`，它负责完整生命周期：启动前把 `pending/` 移入 `processing/` 加锁、序列化上下文、直接创建整理会话、会话结束后收尾（归档 note、写 checkpoint、定稿重建索引、反馈）。
+
+触发方分两层：**定时检查**由 trigger 的 `script` 模式承担，只做候选判断，不管理生命周期；**手动 / compact / renew / `/new`** 直接调用 `launchConsolidation()`。
+
+**并发与排队**：同一 agent 同时只能有一个整理会话；全局最多 5 个 agent 并发。超出的请求排队，前一个结束后自动启动下一个。
+
+## 召回
+
+各作用域的 `MEMORY.md` 索引由 manifest 注入 system prompt（主会话 order 36 / 37 / 38）。模型按索引里的描述和关键词判断哪条相关，再按需 Read 对应的 `consolidated/` 正文。
+
+索引上限 `memory.indexMaxBytes`（默认 5KB）。`important` / `urgent` / `profile` 必进且永不淘汰；`done` / `cancelled` 不进；其余按优先级和 mtime 排序，超限从末尾截断。没进索引的文件仍在磁盘上，只有 `archive` 才让它下线。
+
+## 规则从哪里来
+
+| 内容 | 位置 |
+|------|------|
+| 何时写、命令速查、召回（主会话）；三个写命令、模式权限、禁止事项（整理会话） | `$KITS_FRAGMENTS/memory.md`，两份 manifest 共用，按 `sessionType` 分支渲染 |
+| 整理流程：查重、取舍、收尾 | `$KITS_TEMPLATES/memory-consolidation/workflow.md` |
+| 各模式的具体做法 | `$KITS_TEMPLATES/memory-consolidation/<mode>.md` |
+
+会话原型到 manifest 的映射内置在代码里（`kit-renderer.ts` 的 `BUILTIN_SESSION_MANIFESTS`：`main` / `memory` / `auxiliary`），`config.sessionManifests` 只作可选覆盖。
+
+## 开关
+
+| 配置字段 | 控制范围 |
+|---------|---------|
+| `memory.enableRelation=false` | **总开关**。note 写不了、`[memory]` 段和索引不注入、所有整理模式和手动调用一并拒绝 |
+| `memory.enableAgent=false` | 关闭泛化模式与 agent 索引注入；notes / promote 照常 |
+| `memory.enableOwner=false` | 关闭提升模式与 owner 索引注入；notes / generalize 照常 |
+
+## 目录结构
+
+```
+$RELATIONS_DIR/<peerKey>/memory/     ← relation 作用域（note 唯一写入处）
+├── MEMORY.md                        # 索引（程序自动生成，manifest 注入）
+├── pending/                         # note 写入的临时记忆
+│   └── archive/                     # 被 drop 的 note
+├── processing/                      # 整理中的快照
+├── consolidated/                    # 正式记忆（已签名）
+└── archive/
+    ├── notes/                       # 整理完成的 pending 原件
+    └── invalid/                     # 验签失败或未签名的文件
+
+$PERSONAL_DIR/memory/                    ← agent 作用域（结构相同，由泛化产出）
+$EVOLCORE_HOME/memory/owner/<ownerAid>/  ← owner 作用域（结构相同，由提升产出）
+```

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

@@ -0,0 +1,133 @@
+# 记忆整理批次目录结构
+
+> 本文描述每次记忆整理产生的文件布局，以及整理进度标记文件的位置与格式。
+> 整理会话的触发机制与五种模式见 `memory-consolidation.md`；整理命令用法见 `memory.md`。
+
+---
+
+## 一、整理进度标记（Checkpoint）
+
+**路径**：`<chatDir>/consolidation-checkpoint.json`
+
+`chatDir` 与 `messages.jsonl` 同目录，即：
+
+```
+$EVOLCORE_HOME/agents/<selfAid>/sessions/<channelSessionKey>/
+  messages.jsonl                    ← 该关系所有消息流水
+  consolidation-checkpoint.json     ← 整理进度标记
+```
+
+**格式**：
+
+```json
+{
+  "lastConsolidatedAt": 1728021600000
+}
+```
+
+`lastConsolidatedAt` 是上一次整理完成时的毫秒时间戳。每次整理会话完成后由程序写入。
+
+**作用**：决定下次整理时从 `messages.jsonl` 里截取哪段历史。只取 `ts >= lastConsolidatedAt` 的行，避免把整个对端历史全量喂入整理会话。
+
+---
+
+## 二、整理批次目录（Consolidation Run Directory）
+
+每次触发一次整理，在以下位置建一个新目录：
+
+```
+$EVOLCORE_HOME/memory/consolidation-batches/
+  <prettyTs>-<selfAid>-<mode>/     ← 整理批次目录
+```
+
+`prettyTs` 格式为 `YYYYMMDDTHHmmss`（UTC），例如 `20261004T185900`。
+
+**示例**：
+
+```
+memory/consolidation-batches/
+  20261004T185900-toleiliang4.agentid.pub-notes/
+  20261005T100000-toleiliang4.agentid.pub-generalize/
+```
+
+---
+
+## 三、批次目录内的文件
+
+```
+<整理批次目录>/
+  context.md          ← 任务书
+  ops.jsonl           ← 操作流水
+  threads/            ← 话题快照目录
+    main.md           ← 主话题快照
+    <threadId>.md     ← 分话题快照（每个 thread 一个）
+  artifacts/          ← 产物目录（调试用）
+```
+
+### context.md — 任务书
+
+整理会话启动时读取的上下文文件，包含：
+
+- 整理模式、triggeredBy、允许写入的 scope
+- 作用域信息（selfAid、peerAid、processingDir、consolidatedDir、indexPath）
+- notes 模式：`threads/` 目录下各话题快照文件的路径列表
+- 其余模式：候选记忆列表（只有路径 + 描述，不塞全文）
+
+整理会话以此文件为起点，不依赖任何注入变量。
+
+### ops.jsonl — 操作流水
+
+整理会话执行的每条 `ec memory` 命令及其结果，每行一条 JSON：
+
+```json
+{"ts": "2026-10-04T18:59:30.000Z", "op": "create", "scope": "relation", "target": "commit-chinese", "tags": ["rule", "long-term"], "ok": true}
+{"ts": "2026-10-04T18:59:31.000Z", "op": "archive", "scope": "relation", "target": "consolidated/old-note.md", "ok": true}
+{"ts": "2026-10-04T18:59:32.000Z", "op": "summary", "created": 1, "updated": 0, "archived": 1, "errors": 0}
+```
+
+字段说明：`ts` 是 ISO 8601 字符串；`op` 取值 `create` / `update` / `archive` / `summary`；`target` 对 create 是 slug，对 update/archive 是目标路径；`ok` 是布尔值，失败时附 `error` 字段。最后一行 summary 由程序在会话结束时追加。
+
+### threads/ — 话题快照目录
+
+从 `messages.jsonl` 里截取本次整理范围内的消息（`ts >= lastConsolidatedAt`），按 threadId 分组，每个 thread 一个 Markdown 文件。没有 threadId 的消息归入 `main.md`。
+
+每个文件的格式：
+
+```
+# 话题快照：<threadId>
+
+> 时间范围：<firstMsgTime> — <lastMsgTime>
+> 消息行范围：L<start>–L<end>（对应 messages.jsonl 行号）
+
+L行号 时间 [用户 <peerAid>]: 内容
+L行号 时间 [助手]: 内容
+...
+```
+
+整理会话通过 `context.md` 里的路径列表逐一读取各话题快照，不需要自己去扫目录。
+
+### artifacts/ — 产物目录（调试用）
+
+整理会话 create / update 的记忆文件的符号链接或副本，便于一次性查看本次整理的全部产出。
+
+```
+artifacts/
+  consolidated/
+    <slug>.md     ← 指向 consolidated/ 下的实际文件
+```
+
+---
+
+## 四、目录命名速查
+
+| 名称 | 路径 | 说明 |
+|------|------|------|
+| 整理进度标记 | `<chatDir>/consolidation-checkpoint.json` | 记录上次整理到哪了 |
+| 整理批次根目录 | `$EVOLCORE_HOME/memory/consolidation-batches/` | 所有批次平铺在这里 |
+| 整理批次目录 | `consolidation-batches/<ts>-<selfAid>-<mode>/` | 一次整理对应一个目录 |
+| 任务书 | `<批次目录>/context.md` | 整理会话的起点文件 |
+| 操作流水 | `<批次目录>/ops.jsonl` | 所有 ec memory 调用记录 |
+| 话题快照目录 | `<批次目录>/threads/` | 按 threadId 切分的对话历史 |
+| 主话题快照 | `<批次目录>/threads/main.md` | 无 threadId 的消息 |
+| 分话题快照 | `<批次目录>/threads/<threadId>.md` | 某个 thread 的消息 |
+| 产物目录 | `<批次目录>/artifacts/` | 本次整理产出的记忆文件（调试用） |