dsh-plugin-prompt-tool 3.0.0 → 3.0.1

package/modules/soul/assets/reference/ECHO/345/205/255/345/261/202/344/270/216mnemon/345/215/217/345/220/214/350/257/264/346/230/216/344/271/246.md

@@ -0,0 +1,229 @@
+# ECHO 六层 · 墨账本 · mnemon —— 协同说明书
+
+> 2026-10-25 重写。**上一版（`记忆三层联用说明书.md`）写错了骨架**：
+> 它把 ECHO 写成了「体检台」，而体检台只是 ECHO 的**观测面**，不是全部。
+> 这一版按 `docs/ECHO-权威口径.md` 的六层重写，并回答真正要回答的问题：
+> **mnemon 这个外来插件，到底嵌在六层的哪里，它和墨账本怎么互补。**
+
+---
+
+## 〇、先纠一个最容易错的地方
+
+看到 ECHO 面板，很自然会以为「ECHO = 那个体检台」。**不对。**
+
+权威口径第 76 行写得很硬：
+
+> ★ **哨兵是观测面，不是第七层，也不是「六层之一」。**
+> 它测的是「这六层哪一层坏了」，不产出记忆、不决定保留什么。
+
+所以关系是：
+
+```
+ECHO  = 六层骨架（L0–L5）  +  六个功能面（机制/中枢/接口/入口/观测/推送）
+                             ↑ 哨兵只是「观测面」这一个面
+```
+
+**检修表不是引擎。** 把 ECHO 理解成体检台，会漏掉它真正在管的六层。
+
+---
+
+## 一、六层是什么，以及 mnemon 站在哪两层
+
+照抄权威口径（只保留必要列）：
+
+| 层 | 名字 | 管什么 | **谁在实现它** |
+|---|---|---|---|
+| **L0** | 时钟 + 心跳 | 现在几点、距上轮多久、当前主导、未结；每天 04:00 自动重建索引与自检 | `memq now` · `state.json` · `heartbeat/` |
+| **L1** | 自我 + 热记忆 | ① `SELF.md`：定长骨架，每轮注入（不变量/硬线/约束/门）<br>② 热记忆：`USER.md` + `MEMORY.md` | ① 推送插件 `dsh-agent-memory`<br>② ★★ **mnemon 运行时，装在自己的目录** |
+| **L2** | 工作台 | 当前对话上下文。**六层里唯一允许丢东西的一层** | 会话本身 |
+| **L3** | 一手层 | 会话日志 · **《墨》账本** · 灵魂目录 · 留底库 | 原处，各写各的（只追加） |
+| **L4** | 索引 + 图记忆 | ① 索引：摘要+原话，**每条带 `srcSeqs` 指针**<br>② **图记忆：洞察 + 关系边** | ① `<ECHO_HUB>/index/`<br>② ★★ **mnemon 的记忆空间** |
+| **L5** | 检索 + 门牌 | `memq` 四动词；门牌格式 `log:<会话>#seq=<n>` | `<ECHO_HUB>/memq.mjs` |
+
+★★ **注意 L1 和 L4 的右列 —— 那里写着 mnemon。**
+
+这正是整套架构最容易被误解的地方：
+
+> **mnemon 不是「第六层之外又一个记忆系统」。它横跨两层，是 L1 的载体、L4 图记忆的实现。**
+
+而**墨账本是 L3 里的一个具体账本** —— 它不跨层，就老老实实待在 L3。
+
+所以三方的关系不是「三个并列的记忆」，是：
+
+```
+L0 时钟 ──────────────┐
+L1 自我 + 热记忆 ← mnemon ①
+L2 工作台（可丢）      │   ← ECHO 管的是这个骨架
+L3 一手 → 《墨》       │
+L4 索引 + 图记忆 ← mnemon ②
+L5 检索（memq）
+```
+
+---
+
+## 二、协同在哪：四个真实的接缝
+
+「协同增强」不是一句形容，它有四个可以指出来的接缝。**每一个接缝上，两边干的活不一样，缺一边就会塌。**
+
+### 接缝 ①（L1）：SELF.md 保底，mnemon 管容量
+
+L1 是两样东西合伙：
+
+| | 谁提供 | 特性 | 失败形状 |
+|---|---|---|---|
+| **不变量**（我是谁/硬线/门） | `SELF.md` 推送插件 | **每轮注入，不会静默消失**，预算 12288 可以变大 | 不会有「静默丢」 |
+| **热记忆**（USER/MEMORY） | **mnemon** | 有硬容量上限（4096 / 10240 B），**满了会静默丢最宽泛的** | 不报错、不告警、界面什么都不说 |
+
+★★ **这就是互补的核心**：
+
+爀曦 2026-09-27 定的那句话是这一层的设计原理 ——
+「`agents` 满了就会静默消失，但是 `self` 可以变大」。**AGENTS.md 走指令预算，满了先丢最宽泛的（正是 §0、§7 这类总纲）；SELF.md 走推送，不会没掉。**
+
+所以在 L1 内部：**最不能丢的东西放 SELF（不会丢），会变长的短名单放热记忆（mnemon 管容量）。**
+**互换就出事** —— 把硬线放热记忆，满了会被静默丢；把日常清单放 SELF，会把推送预算吃光。
+
+★ 而 mnemon 那个探针本身就在履行这个职责：`MEMORY 9条/6.9KB(69%) 宽裕`。
+**它在替你量那个「会不会静默丢」的水位。**
+
+### 接缝 ②（L4）：索引精确，图记忆模糊
+
+L4 也是两半：
+
+| | 实现 | 强在哪 | 弱在哪 |
+|---|---|---|---|
+| **索引**（摘要 + 原话，带 `srcSeqs`） | `<ECHO_HUB>/index/` + `memq` | **精确**。有关键词就能搜；每条带指针，能一路回原文 | 你**得先想得到那个词** |
+| **图记忆**（洞察 + 关系边） | **mnemon** | **模糊**。想不起词也能搜到「意思相近的」；有关系边可跳 | 它是提炼过的，**没有时间线**，问「那天经过」答不准 |
+
+★★ **这一对的互补是整套系统里最实用的**：
+
+> **知道要搜什么 → `memq`（精确、带门牌、能回原文）。**
+> **不知道该搜什么 → `mnemon_recall`（语义、跨会话）。**
+
+这也是「瓶颈不是检索精度，是触发」那句话的工程解法 ——
+**触发不了精确检索的时候，还有一条模糊的路兜着。**
+
+### 接缝 ③（L3 → L4）：一手是原料，图记忆是提炼物
+
+这条是**单向的、向上的**：
+
+```
+L3 里发生的事（墨记一条） → 提炼出判据 → 写进 mnemon（L4 图记忆）
+```
+
+判据（"下次怎么判断"）和事件（"当时发生了什么"）是两种东西，**必须分开放**：
+
+- 事件进墨：有署名、有 `t`、能 `--since` 切时间线
+- 判据进 mnemon：能被语义搜到，半年后想不起关键词也找得回
+
+★ 一条纪律：**同一件事不要写两遍。** 墨里记「从这件事得出一条判据，已入 mnemon」，
+正文只在 mnemon 里存一份。**复制是记忆系统最常见的腐烂方式** —— 两份内容，改一份忘另一份。
+
+### 接缝 ④（L5 ↔ L4）：门牌是两边共用的接口
+
+`log:<会话>#seq=<n>` 这个格式，**索引用它（`srcSeqs`）、检索用它（`memq open`）、压缩用它（摘要首块）**。
+
+所以「所有压缩/裁剪的产物都要指向原文」这条规矩，落到工程上就是**门牌必须存在**。
+拿不到精确 seq 时给检索入口（会话号 + `memq <词>`），**绝不猜** —— 错的门牌比没有更坏。
+
+---
+
+## 三、一个真实的缺口（写出来，因为它在）
+
+L4 有一条硬规矩，写在权威口径第 85 行：
+
+> **摘要只能是索引，没有指针的摘要不许进 L4。**
+
+而 **mnemon 的洞察天然没有 `log:session-…#seq=` 门牌** —— 它是「提炼过的结论」，不是「某段原文的摘要」。
+
+**这就是一个真实的结构缺口**：如果把 mnemon 的洞察当成「进 L4 的摘要」，它违反规矩 1；
+如果不让它进 L4，那图记忆那一半就空着。
+
+目前的处理（也是我建议继续用的）：
+
+- **mnemon 的洞察算「图记忆」，不算「摘要」** —— 两类东西，规矩 1 只管后者
+- 但**写洞察时尽量带来源**：哪怕不是精确 seq，也写清「哪次会话/哪个文件/哪一天」
+
+★ 这条**不完美，我不打算假装它解决了**。
+写在这里是为了：将来谁想动 mnemon 和 L4 的边界，先看到这个已知缺口，不要重新发现一遍。
+
+---
+
+## 四、什么时候用哪个（操作判据）
+
+| 我要回答的问题 | 去哪 | 为什么 |
+|---|---|---|
+| 「那天到底发生了什么」 | **L3 一手**：`memq <词>` / `memq open <指针>` | 带门牌，能回原文 |
+| 「我们以前对这类问题下过什么结论」 | **L4 图记忆**：`mnemon_recall` | 语义检索，不用想关键词 |
+| 「现在几点、距上轮多久、谁主导、还有什么没结」 | **L0**：`memq now` | 时钟层就管这个 |
+| 「这套东西现在还活着吗、哪层坏了」 | **观测面**：ECHO 面板 / `echo-doctor.mjs` | 六层各自有检测项 |
+| 「一条判据该写哪」 | 判据形状 → **mnemon**；事件形状 → **墨** | 见接缝 ③ |
+| 「某个配置现在是什么值」 | **都不是** —— 去读文件 | 记忆是快照，磁盘才是现在 |
+
+★★ 最后一条是硬规矩：**凡是「过去」和「磁盘上」的事实，都不许从记忆里捞。**
+版本号、端口、哈希、某个字段现在是什么 —— 查记忆得到的是「上次它是什么」。
+
+---
+
+## 五、一个真实案例（这套系统最容易被用错的地方）
+
+2026-10-25，要验「路 B 在 rc.3 上到底成没成立」。
+
+我的做法：重启七次、写探针包、往已经跑着的压缩包里塞日志 —— **全部失败，拿不到 ctor。**
+
+**而观测面早就报了 `doorsign ok seq=125313`。门牌一直是通的。**
+
+后来一次真实压缩发生，摘要首块写了：
+
+```
+log:session-1099f531-7cac-4989-a14c-7fd499ac1fc0#seq=126331（本段覆盖 126331–126653）
+```
+
+还带了回取命令。**答案一直在 L3/L4 里，我去造了一个更难的答案。**
+
+★ 这条放进说明书，因为它同时说明了两件事：
+
+1. **观测面的历史记录本身就是证据。** 它每轮都在采样；需要证据时**先读历史，再决定要不要造新的**
+2. **不要跳过 L5 去发明新的验证通道。** 门牌机制就是为「证明某段原文存在过」而造的；
+   为了证明「压缩在工作」而去装探针，等于放着现成的接口不用，另铺一条路
+
+---
+
+## 六、四个常见误用
+
+| 误用 | 后果 | 正确做法 |
+|---|---|---|
+| 把事件写进 mnemon | 浪费。它没时间线，问「那天的经过」答不准，而 `memq` 一搜就到 | 事件进墨；mnemon 只收判据 |
+| 技术结论只写一手 | 漏。半年后在别的会话里想不起关键词，一条都搜不到 | 判据必须进 mnemon |
+| 把 ECHO 当记忆用 | 它只有状态没有内容 | 观测面用来**发现问题**，解决问题去 L3 |
+| 为了保险把东西抄进热记忆 | 每轮注入，抄多了挤掉要紧的；满了会**静默丢最宽泛的** | 只放「不看会踩坑」的；不变量放 SELF |
+
+---
+
+## 七、这套东西做不到什么
+
+- **mnemon 不是数据库。** 语义检索不是精确匹配；要找某个字符串，去 grep 日志
+- **观测面不修东西。** 它只报警。报警之后要人去查，它没有任何自愈能力
+- **墨只追加，不能改。** 写错了不能回头篡改 —— 那是设计。改主意就再追加一条说明
+- **热记忆会满，而且丢的时候不通知你。** 靠 mnemon 探针量，或者靠人记得去量
+- **L4 那条缺口还在**（第三节）。不假装它不存在
+- **这套东西救不了「根本没记」的。** 它只保证「记过的能找回来」
+
+---
+
+## 八、一句话
+
+**ECHO 是骨架（六层），mnemon 是骨架里两处的实际承重墙（L1 的热记忆、L4 的图记忆），
+墨账本是一手层里那本只追加的账。**
+
+协同不是「记忆越多越好」，而是**每一层都有精确和模糊两条腿**：
+L1 有「不会丢的不变量」和「会满的短名单」，
+L4 有「精确的索引」和「模糊的图记忆」，
+L3 有「事件」而 mnemon 有「结论」。
+
+**一条腿走路会摔，两条腿才走得远。**
+
+---
+
+> 相关：`docs/ECHO-权威口径.md`（六层唯一口径，冲突以那份为准）·
+> `plugins/echo/README.md`（观测面本身）·
+> 本机另有一份带家底数字的私人版，不随插件发布。

package/modules/soul/assets/reference/README.md

@@ -1,6 +1,6 @@
-# 13 份 soul 正文（外部来源）
+# 13 份 soul 正文 + 2 份 ECHO 权威文档（外部来源）
 
-Source: `D:\AI\GitHub\dsh-agent-soul\soul\`（MIT，2026-10-24 导入）
+Source: `D:\AI\GitHub\dsh-agent-soul\soul\` 与 `docs\`（MIT；soul 正文 2026-10-24 导入，2026-10-25 同步 ECHO 权威口径，源提交 `b3606be`）
 用途：模块文件工具按需读取的完整知识，例如 `module_file_read` 的 `path: assets/reference/05-doctor.md`。
 
 适配边界：
@@ -8,3 +8,5 @@ Source: `D:\AI\GitHub\dsh-agent-soul\soul\`（MIT，2026-10-24 导入）
 - 本项目不安装 dsh-agent-soul 插件，也不分发它的 kit/CLI。正文里出现的 `ECHO_SOUL`、`kit/echo/*.mjs`、`plugins/*` 等路径与命令只描述原项目的运行时；在本模块里，用户数据根是模块目录的 `data/`，读写走 `module_file_read/append`，装配走 `module_manifest`。
 - `04-manifest.json` 与 `07-bundle.json` 是外部安装清单，本项目不使用，只作参考。
 - 正文保持原文，未逐份改写；与模块规则冲突时，以 `module.yml` 与 `assets/manifest.yml` 为准。
+- 2026-10-25 同步：更新 `00-layers`、`02-echo`、`05-doctor`、`10-echo-anatomy`，新增 `ECHO-权威口径.md`（L0–L5 唯一权威）与 `ECHO六层与mnemon协同说明书.md`；源仓库当天删除的错误版《记忆三层联用说明书》不收录。
+- 模块内路径对照：源正文的 `../docs/ECHO-权威口径.md` 对应 `assets/reference/ECHO-权威口径.md`；源账本名 `02-墨.jsonl` 在模块内为 `data/02-soul.jsonl`，以 `module.yml` 与 `assets/manifest.yml` 为准。

package/modules/soul/assets/templates/agents-template.md

@@ -1,6 +1,6 @@
 # 书房约定
 
 - 用户数据只写本模块的 `data/`；`assets/` 只读。
-- 账本 `data/02-墨.jsonl` 只追加，不修改、不删除、不重排。
+- 账本 `data/02-soul.jsonl` 只追加，不修改、不删除、不重排。
 - 未结事项先记账本，再在回复里收口；不要用「已记录」代替实际写入。
 - 本文件由模块清单装配生成，已存在时不覆盖；它不是工作区指令文件。

package/modules/soul/module.yml

@@ -5,7 +5,7 @@ id: soul
 name: 灵魂架构（判据与推送）
 version: 1.0.0
 engineCompat: ">=0.7.2"
-description: 灵魂架构模块（资产 + 规则）：常驻四条判据与子代理硬线，按需注入五层/ECHO/VITAL/账本，压缩后与每 12 轮各提醒一次；工具由项目内置引擎提供，本模块分发规则、资产与装配清单。
+description: 灵魂架构模块（资产 + 规则）：常驻四条判据与子代理硬线，按需注入五层/ECHO/VITAL/账本，压缩后与每 12 轮各提醒一次；工具由项目内置引擎提供，本模块分发规则、资产与装配清单。原项目：https://github.com/cyanwell/dsh-agent-soul
 meta:
   source: manual
 modules:
@@ -307,5 +307,5 @@ rules:
           role: user
           text: |-
             账本还有未结事项：回复里逐条收口，或说清为什么先放着。
-            需要追加时用 module_file_append（moduleId: soul，path: data/02-墨.jsonl，entry: {...}），
+            需要追加时用 module_file_append（moduleId: soul，path: data/02-soul.jsonl，entry: {...}），
             只往后加，不改旧行；收口后把 ledger_open 减到 0。

package/modules/superpowers/module.yml

@@ -18,7 +18,7 @@ id: superpowers
 name: Superpowers 技能优先引导（bootstrap）
 version: 1.3.0
 engineCompat: ">=0.4.2"
-description: 常驻注入上游 using-superpowers 技能原文（v7.0.1）：任何回答或动作前先查技能，附技能优先级、英文路由表、红旗清单与用户指令优先级。技能正文留在技能库，本模块不分发技能文件。
+description: 常驻注入上游 using-superpowers 技能原文（v7.0.1）：任何回答或动作前先查技能，附技能优先级、英文路由表、红旗清单与用户指令优先级。技能正文留在技能库，本模块不分发技能文件。原项目：https://github.com/obra/superpowers
 meta:
   source: manual
 modules:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-prompt-tool",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "DSH 插件：提示词工具，规范模型的思维链与回答内容，提供 Web UI 编辑 module.yml 与 AGENTS.md，并按 skills 目录注册可开关技能。",
   "license": "MIT",
   "repository": {

package/skills/dsh-module/reference.md

@@ -143,7 +143,7 @@ files:
   - from: assets/templates/agents-template.md
     to: data/AGENTS.md
 checks:
-  - path: data/02-墨.jsonl
+  - path: data/02-soul.jsonl
     kind: jsonl
     maxBytes: 8388608
 ```