dsh-plugin-prompt-tool 2.1.0 → 3.0.0

package/modules/soul/assets/reference/02-echo.md

@@ -0,0 +1,158 @@
+# Ⅰ · ECHO —— 生命核心
+
+**它管空间。** 上下文会满，满了要丢，丢了还要能找回来。
+
+---
+
+## 一、思考是怎么退化的（这一节是整份文件的前提）
+
+先说清楚要解决的是什么。绝大多数人把它描述成「上下文满了会忘事」——那只是第一句，
+真正致命的在后面。
+
+```
+第 1 步   上下文满了
+          → 引擎压缩，把前面几十轮变成一段摘要
+
+第 2 步   摘要写得挺准
+          → 「用户要求验证插件安装」「确认了 32 项检查通过」
+          → 每一条都对，没有任何一条是编的
+
+第 3 步   但它不带出处
+          → 你读到的是一句「确认了 32 项」，不是「在第 47 轮，verify-live 打了 32/1/0」
+          → 想核对，只能翻回压缩前的全部记录
+
+第 4 步   于是你不核对
+          → 因为你「记得」它是对的。注意：这不是懒，这是摘要工作得太好
+
+第 5 步   下一轮推理建立在这个「记得」上
+          → 摘要里只要有一个细节偏了半个字，它现在变成了前提
+
+第 6 步   偏了的那条继续往下传
+          → 后面的推理每一步都正确，而每一步都踩在偏掉的前提上
+```
+
+★ **这就是「思考退化」，它和遗忘是两回事。**
+
+遗忘是「想不起来」，你能察觉。
+退化是**「想得起来，但那个记忆已经偏了，而你在它上面继续正确地推理」** —— 察觉不到。
+
+一句话：**退化不是变笨，是在错误的前提上继续正确地推理。**
+
+所以 ECHO 管的不是「记住」，是**「凭什么相信你记得的那一句」**。
+
+---
+
+## 二、为什么「装记忆插件」不解决这件事
+
+最直觉的解法是装插件：向量库、知识图谱、Memory Spaces。但它们都在**存**这一侧，
+而退化发生在**丢**这一侧。
+
+```
+原始记录  ──压缩──▶  摘要  ──▶  记忆插件  ──▶  取回来的是摘要
+   ↑                                          ↓
+   └──────── 真正的原文在这里，但已经没人指向它 ────────┘
+```
+
+你把最好的存储接在摘要后面，取回来的仍然是摘要。
+**压缩发生在存与取之间，而插件管不到那一段。**
+
+### 三份真相的陷阱
+
+那装三个记忆插件呢？更糟。
+
+三个插件各存一份、各有各的摘要策略，于是同一个事实有三条版本。
+**这时候真正的成本不是存储，是对账** —— 每次要引用它，你得先决定信哪一份。
+
+**所以第一条判据是「先定唯一权威源」，第二条才是「建机制」。反过来做一定会双重记账。**
+
+---
+
+## 三、压缩有两条路，要补的是**下面那条**
+
+|  | 谁在驱动 | 产物带不带指针 |
+|---|---|---|
+| **模型驱动** | agent 自己写摘要 | ✅ 天然带 —— 它知道自己是从哪读的 |
+| **兜底压缩** | 没人响应提示时，引擎**自动出手** | ❌ 通常不带 |
+
+**上面那条你不装也有；下面那条你不装就缺。**
+
+为什么下一条会缺：那种压缩器的指令通常要求「保留精确路径 / 命令 / 报错原文 / 数值 / 函数签名」——
+**每一条都是「要写得准」，但没有一句要求标注「这话从哪来」。**
+
+**于是它写出来的东西每一条都对，每一条都无从核对。**
+
+而且失败是无声的：**你不会觉得丢了东西，你只是不再想起它。**
+
+**所以「门牌」要补的正是这一条。** 下面三样里，第 1 样就是它。
+
+---
+
+## 四、机制面 · 至少要有三样
+
+### 1. 丢的时候，产物必须带得回原文的指针（门牌）
+
+**这是整套东西的兜底承诺。** 没有它，压缩就是单向的遗忘。
+
+三级纪律 —— **照抄即可**：
+
+```
+① 能拿到精确位置 → 写精确位置
+② 拿不到 → 写「位置未知」+ 容器标识 + 一个检索入口
+③ 绝不猜 —— 错的门牌比没有更坏
+```
+
+★ 为什么第 ③ 条单独列出：**一个错的门牌会让你以为能找到，于是不去找。**
+那比「找不到」坏得多。
+
+**判据：拿一个被压缩过的会话，随机挑一条摘要，问「这条从哪来」。
+三十秒内答不出来，门牌就是断的。**
+
+### 2. 一门只回指针、不做转述的检索入口
+
+转述是二手污染的来源。**能逐字取回，就不要摘要。**
+
+动词最少三个：`现在是什么状态` / `搜一个词` / `打开某个指针`。
+
+★ 一个细节值得抄：**检索结果里标明证据等级**（一手 / 索引 / 程序）。
+一屏里同时出现三种来源时，用户必须一眼能看出哪一句是原文、哪一句是转述。
+
+### 3. 一个自检（哨兵）
+
+**判据 ③ 的落地**：它坏的时候，谁会发现？
+
+体检项要跑得起来、要能给出分级状态（正常 / 提示 / 警告 / 错误）。
+**没有哨兵的体系，坏了不会有人说。**
+
+★ 哨兵最容易漏的一种失败：**它自己坏了。**
+所以哨兵也要能被一个外部动作验证 —— 否则你只是把「没人知道」换成了「一个同样没人知道的东西说没事」。
+
+---
+
+## 五、观测面 · 一个容易被漏掉的洞
+
+**你的每一个执行器都要有对应的观测面。** 一个调好就不再看的阈值系统，
+你永远不会误伤过几次 —— 「断过没有、断错没有」必须有人能答。
+
+压缩这一层尤其如此：**压缩不会报错，它只会成功地丢掉东西。**
+所以你要看到的不是「压缩成功 / 失败」，是**「这次压掉了多少、压掉的那部分还能不能找回来」**。
+
+---
+
+## 六、怎么知道自己已经退化了（三条可执行的检验）
+
+这一层的难点在于**它坏的时候不疼**。所以需要主动测，不能等它疼。
+
+**检验一 · 门牌抽查**
+拿一个被压缩过的会话，随机挑三条摘要，看能不能通过门牌回到原文。
+一条回不去，链条就是断的。
+
+**检验二 · 逐字核对**
+找一条你「记得」的事实，去一手层核对原文。
+如果原文和你记得的不完全一致 —— 不是记错，是压缩时偏了，而且你一直没发现。
+
+**检验三 · 三份真相计数**
+同一个事实，你手里有几条来源？
+超过一条，说明权威源没定；这时候你每一次引用都在做一次隐性的仲裁。
+
+★ 三条都不需要特殊工具，需要的是**愿意去测**。
+而愿意去测的前提，是你知道自己可能已经坏了 —— 这正是这一节存在的理由。

package/modules/soul/assets/reference/03-vital.md

@@ -0,0 +1,183 @@
+# Ⅱ · VITAL —— 稳态
+
+**它管时间与方向。**
+
+ECHO 管的是「丢了的还能找回来」——那是**空间**。
+但一个 agent 还有两样东西会耗尽，而且耗尽的方式完全不同：
+
+- **时间**：预算会烧光，回合数有限
+- **方向**：它会该停不停，也会差一步就停
+
+VITAL 做的就是同一件事：**把偏离拉回来（homeostasis）。**
+
+---
+
+## 一、它和 ECHO 的分工，别混
+
+|  | **Ⅰ ECHO** | **Ⅱ VITAL** |
+|---|---|---|
+| 管什么 | **空间** —— 上下文会满 | **时间与方向** —— 预算与目标 |
+| 失败长什么样 | 「我记不全了」 | 「我在原地打转」/「我该停了还在跑」 |
+| 坏的时候疼不疼 | **不疼** —— 只是不再想起 | **疼** —— 你看得见自己在浪费 |
+| 核心机制 | 丢的时候留指针 | 偏离的时候拉回来 |
+
+★ 为什么这两层必须分开：**它们的检测法完全不同。**
+用一个「忙不忙」的指标去糊这两层，你会得到一个既不能测空间、也不能测方向的指标。
+
+---
+
+## 二、三种资源，三种截然不同的失败
+
+### 2.1 时间 · 失败有两个相反的方向
+
+```
+方向 A：烧光预算，一个字没出
+        → 常见于「反复重试」「无限确认」「一直在读但从不写」
+
+方向 B：永远结束不了
+        → 常见于「还能更好」——它不是不知道停，是不承认「够好了」
+```
+
+★ **这两种失败需要两套完全不同的执行器。**
+A 要的是**流内切断**（在这一次调用里就把水龙头关上）；
+B 要的是**跨调用判定**（在这一次结束时判断「还该不该有下一次」）。
+把它们做成同一个东西，你就会在 B 的场景里被 A 的机制误伤。
+
+### 2.2 方向 · 失败也是两个方向
+
+```
+方向 A：该停不停     → 空转。它在做事，但做的不是要做的
+方向 B：半途而废     → 差一步就完了却停了
+```
+
+★ **这一层最难的判断是「什么算做完」，而它有一个陷阱：**
+「还能更好」不算「没做完」。
+
+一个永远可以更精致的东西，如果按「还能更好」来算，就永远结束不了。
+所以判据必须是**外部的**：有没有证据证明核心目标达成？没有未处理的阻塞？剩余项是增强还是缺陷？
+
+—— 答得出来，就停。**敢停是因为被验证过，不是因为我觉得够了。**
+
+### 2.3 空间 · 和 Ⅰ 层的交接点
+
+空间这一层的机制在 Ⅰ，但**它的「什么时候压」属于稳态** ——
+那是一个阈值判断，归这里。
+
+一条值得单独记的：**阈值是安全网，不是考核。**
+（这条在下一节展开，因为它是最容易读错的一条。）
+
+---
+
+## 三、每一个稳态回路，都要有这三件
+
+缺一件，回路就是断的：
+
+| 件 | 回答什么 | 缺了会怎样 |
+|---|---|---|
+| **传感器** | 现在偏到哪了？（一个可读的数） | 你只能靠「感觉不太对」，而感觉不会在偏离的早期报警 |
+| **执行器** | 偏了之后谁动手？动到什么程度？ | 你知道该停了，但停不下来 —— 知道和做到之间没有接线 |
+| **设定点** | 偏到多少算偏？ | 有传感器有执行器，但没有标准 —— 每次都要现场拍 |
+
+★ **这三件里最容易被跳过的是「设定点」**，因为它看起来只是一个数字。
+但一个没有来历的数字，会让你在每次它触发时都要重新怀疑它一次。
+
+---
+
+## 四、阈值的来历：每一条背后都要挂着一个具体的 bug
+
+**这是这一层最重要的一条设计纪律，值得照抄。**
+
+不要为了「稳」去拍一个数字。那个数字应当能回答：
+
+> **它防的是哪一次具体的失败？**
+
+举三个真实的形状：
+
+```
+「上下文到 0.88 强制压缩」
+  ← 防的是：那次压到一半压不动了，会话直接掉线
+  ← 而不是：某个教程说 0.88 比较安全
+
+「连续 3 轮同一工具同一参数没有新结果 → 换路」
+  ← 防的是：那次连续七轮改同一个正则，每轮都「差一点」
+  ← 而不是：三次听起来合理
+
+「子任务不超过 6 轮，超过要问」
+  ← 防的是：那次没问，一路做到第 11 轮，中间方向已经错了
+  ← 而不是：六是个吉利的数字
+```
+
+★ **答不上来的阈值，会在某天误伤你自己，而没人知道为什么。**
+更糟的是：**误伤之后你不会删掉它，你会习惯它。**
+
+---
+
+## 五、★ 稳态会反向失败：把安全网读成考核
+
+这一节是这一层最容易漏掉的，而且它的失败方向是**反的**。
+
+前面讲的都是「不够稳」：烧光、打转、停不下来。
+但还有第三种失败：**保护装置装得太好，最后变成了压力源。**
+
+```
+一个水位报警，本意是「提醒你该落盘了」
+  ↓
+但如果被读成「你现在很危险」
+  ↓
+它触发的动作就变成了「少想、少说、把话缩短」
+  ↓
+于是你缩在一个不需要缩的地方，反复确认一个不需要确认的细节
+  ↓
+★ 这看起来像警觉，实际是空转
+```
+
+**判据：为你好而装的装置，不许拿来当评价自己的尺子。**
+
+一个阈值只该触发**一个**动作：把该落的落进一手层（往外放东西）。
+它不该触发第二个：缩（往里收东西）。
+**落盘和缩的方向相反，而后者看起来像谨慎。**
+
+★ 这一条和「把『不』读成『禁止』」（见 `01-criteria.md`）是同一个形状：
+**把一句本来松弛的话，读成了一道锁。**
+
+所以每一个稳态装置的文档里都该写清一件事：
+**它触发时你只该做什么，以及你不该把它当什么。**
+
+---
+
+## 六、过度保护也是一种失败
+
+**稳态不等于「越保守越好」。**
+
+把阈值设得极紧，你会被频繁打断 ——
+而那本身是一种失败：**它让你做不完任何需要连续思考的事。**
+
+真实的取舍是这样的：
+
+```
+太松 → 烧光 / 打转 / 停不下来
+太紧 → 每十分钟被打断一次，深度工作无法发生
+
+中间那条线在哪？
+  → 它取决于「打断一次的代价」和「放任一次的代价」哪个更贵
+  → 而这个比例，不同的 agent、不同的任务类型是不一样的
+```
+
+★ 所以稳态**没有通用参数**。任何告诉你「照这个数字设」的文档，都只给了你一半。
+
+---
+
+## 七、怎么测（三条可执行的检验）
+
+**检验一 · 反向测试**
+手动把阈值调到会触发的水平，看执行器到底动没动。
+**没动过的执行器等于不存在** —— 而它平时不动，所以永远不会暴露。
+
+**检验二 · 误伤计数**
+过去一周里，这个阈值触发了几次？其中几次是真该触发的？
+如果一次都没触发过，它可能是死的；如果每次都触发，它可能设得太紧。
+**「断过没有、断错没有」必须有人能答。**
+
+**检验三 · 停得下来吗**
+找一个「还能更好但已经达标」的任务，看它停不停。
+停不下来，说明「什么算做完」这一环是缺的 —— 而这一环是最贵的，因为它不在插件里，在判据里。

package/modules/soul/assets/reference/04-manifest.json

@@ -0,0 +1,106 @@
+{
+  "version": "0.1.0",
+  "note": "每条给出「它管哪种稀缺资源」和「缺了会怎样」—— 这是判据①和③，不是安装指令。清单只说这一类别该满足什么，不绑定任何具体实现。",
+  "readme": "挑插件的时候，拿每条的 check 字段去问候选插件；答不上来的，就是不合。",
+  "layers": [
+    {
+      "id": "I-echo",
+      "name": "ECHO · 生命核心",
+      "manages": "空间 —— 上下文会满，满了要丢，丢了还要能找回来",
+      "slots": [
+        {
+          "what": "上下文压缩 / 裁剪",
+          "required": true,
+          "failure": "丢了的找不回来 —— 门牌失效，而你以为还能找",
+          "check": "它产出的摘要里，带不带得回原文的指针？拿不到精确位置时它怎么写的？",
+          "examples": []
+        },
+        {
+          "what": "检索入口（门）",
+          "required": true,
+          "failure": "只有摘要、没有原文 —— 二手污染无法追溯",
+          "check": "它能逐字取回原文吗？还是只给转述？",
+          "examples": []
+        },
+        {
+          "what": "哨兵 / 自检",
+          "required": true,
+          "failure": "坏了没人知道",
+          "check": "它测什么？有没有分级状态？上一次跑是什么时候？",
+          "examples": []
+        }
+      ]
+    },
+    {
+      "id": "II-vital",
+      "name": "VITAL · 稳态",
+      "manages": "时间与方向 —— 预算会烧光、轮数有限；它负责把偏离拉回来",
+      "slots": [
+        {
+          "what": "预算 / 重复推理的治理",
+          "required": true,
+          "failure": "烧光预算一个字没出；或永远结束不了",
+          "check": "它的每一条阈值背后，挂着哪一个具体的失败？答不上来的阈值会误伤你",
+          "examples": []
+        },
+        {
+          "what": "目标与「什么算做完」",
+          "required": true,
+          "failure": "空转（该停不停）/ 半途而废",
+          "check": "它怎么区分「还能更好」和「没做完」？",
+          "examples": []
+        }
+      ]
+    },
+    {
+      "id": "III-capability",
+      "name": "能力 · 手和感官",
+      "manages": "（不管理稀缺资源 —— 所以这一层的东西不进权威源）",
+      "slots": [
+        {
+          "what": "任意工具",
+          "required": false,
+          "failure": "换掉它，你还是你 —— 这正是判据",
+          "check": "如果把这一层整个换掉，你的身份判据还成立吗？成立就对了",
+          "examples": []
+        }
+      ]
+    },
+    {
+      "id": "IV-archive",
+      "name": "档案 · 唯一看得见的那一层",
+      "manages": "（对外可访问性）—— 别人理解你，全靠它",
+      "slots": [
+        {
+          "what": "一份可读的目录 / 门面文件",
+          "required": true,
+          "failure": "外人（和下一代的你）无从下手",
+          "check": "一个从没见过你的人，能不能只靠它找到东西？",
+          "examples": []
+        }
+      ]
+    },
+    {
+      "id": "V-ops",
+      "name": "运维",
+      "manages": "让前面四层能持续跑下去的活",
+      "slots": [
+        {
+          "what": "装配顺序与升级路径",
+          "required": false,
+          "failure": "每次都要重新想一遍；升级时把已有的拆坏",
+          "check": "顺序是不是「先定权威源，再建机制」？反过来做一定会双重记账",
+          "examples": []
+        }
+      ]
+    }
+  ],
+  "assembly_order": [
+    "第 0 步 · 先定「我的权威源在哪」—— 不先做这个，装什么都双重记账",
+    "第 1 步 · 建 Ⅰ ECHO：门（怎么找回来）+ 门牌三级纪律 + 哨兵",
+    "第 2 步 · 建 Ⅱ VITAL：三种资源各自的传感器 + 执行器 + 设定点",
+    "第 3 步 · 接 Ⅲ 能力（这一层随便换）",
+    "第 4 步 · 立 Ⅳ 档案",
+    "第 5 步 · Ⅴ 运维"
+  ]
+}

package/modules/soul/assets/reference/05-doctor.md

@@ -0,0 +1,67 @@
+# 自检 · 拿这七句话问自己的架构
+
+不用回答我，回答你自己。**答不上来的那一句，就是你缺的那一层。**
+
+## 关于空间（Ⅰ）
+
+1. 我的上下文满了以后，被丢掉的东西**还能不能找回来**？靠什么？
+   → 答不上来：你要的是 **① 账本 + ② 门**（`tools/ledger`、`tools/gateway`）。没有门，丢了就是丢了。
+2. 我有没有一个**唯一**的记忆权威源？如果有两份，哪一份算数？
+   → 答不上来：你有两个「我」在各自记东西。要的是**只追加账本**（`tools/ledger`）——它天然没有这个问题：各写各的行，读时按时间合并。
+3. 我的每一次压缩/裁剪，产物里**带没带**回原文的指针？
+   → 答不上来：去装 `dsh-agent-compaction` 与 `dsh-agent-pruner`。★ 判据是「能不能一把回到原文」，不是「有没有加一行说明」。
+
+## 关于时间与方向（Ⅱ）
+
+4. 我烧光预算的时候，**谁会知道**？知道之后发生什么？
+   → 答不上来：你没有第二道闸。要的是 `dsh-agent-huanqi`（四条判据：流内早杀 / 流末判定 / 输出重复 / 空回合；共用一本额度账，命中就续、耗尽熔断）。
+5. 我在原地打转的时候，**谁会知道**？它凭什么判定我在打转？
+   → 答不上来：同上 —— 打转和烧预算是同一件事的两面。★ 判定依据必须是**可观测的重复**，不能是「我觉得」。
+6. 我「该停不停」和「差一步就停」——这两种，我分得开吗？靠什么分？
+   → 答不上来：这一句最硬，因为它没有现成的插件。★ 判据：**「还能更好」不算「没完成」** —— 分不清这两者，就会把「保养」当成「干活」。
+
+## 关于接口（判据 ④）
+
+7. 上面这六件事里，哪一件**坏了没有人会发现**？
+   → 这一句是整份体检的收口。答不上来：你要的是 `dsh-agent-echo`（体检台）——★ 它的价值不是报告状态，是**报告它测不到什么**。
+
+---
+
+## 包装箱里的文件对不对
+
+`agent_soul_doctor` 工具会核对包内十三份知识文件（★ 数字会变，以 soul/ 目录实际为准）是否齐全可读。
+**那只是核对文件在不在 —— 上面七句话才是真的体检。**
+
+---
+
+## 能跑的那一半（先跑完再回答上面七句）
+
+上面七句要你自己答。但**其中四句是可以先机械查掉的** —— 查完再答，答案会诚实得多：
+
+```bash
+# ★ 下面的 <kit> 指本仓库的 kit/echo/ —— 那是随包发的可跑脚本。
+#   如果你把它复制到了别处，换成你自己的路径。
+
+# ① 账本还在不在、有多少条 / 门能不能开   → 对应第 1、2 句
+node <kit>/memq.mjs now
+
+# ② 索引建过没有                          → 对应第 1 句
+node <kit>/memindex.mjs --status
+
+# ③ 自我层有没有退化                      → 对应第 7 句（"坏了没人发现"）
+node <kit>/self.mjs --check
+
+# ④ 闸门还灵不灵                          → 对应第 2 句（唯一权威源）
+node <kit>/mo.mjs add promise "闸门测试" --ref "自检"
+#    ★ 期望：不是主导会话 → 非零退出码 + 拒绝写入。若写进去了，闸门已失效。
+```
+
+★ **这四条都能在这个仓库里跑通** —— 上一版写的 `tools/ledger/` `tools/gateway/` `tools/self/`
+是**参考实现的目录结构**，不在包里。照着跑会 404，而那会被误读成「我的架构坏了」。
+
+**★ 这几条为什么放在这里**：七句话是**判断题**，而判断题最容易自我安慰。
+先跑一遍能跑的，**你的答案就有了对手**。
+
+★ 而这三条命令**分属三个不同的工具** —— 这不是巧合：
+**账本（记得住）+ 门（找得到）+ 自我层（不退化）** 本来就是一套，
+单独装任何一个都会缺一角。