dsh-plugin-prompt-tool 3.0.0 → 3.0.1

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

@@ -1,106 +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 步 · Ⅴ 运维"
-  ]
-}
+{
+  "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

@@ -29,7 +29,7 @@
 
 ## 包装箱里的文件对不对
 
-`agent_soul_doctor` 工具会核对包内十三份知识文件（★ 数字会变，以 soul/ 目录实际为准）是否齐全可读。
+`agent_soul_doctor` 工具会核对包内 **soul/ 目录下全部知识文件**是否齐全可读。
 **那只是核对文件在不在 —— 上面七句话才是真的体检。**
 
 ---
@@ -46,7 +46,7 @@
 node <kit>/memq.mjs now
 
 # ② 索引建过没有                          → 对应第 1 句
-node <kit>/memindex.mjs --status
+node <kit>/memindex.mjs stats
 
 # ③ 自我层有没有退化                      → 对应第 7 句（"坏了没人发现"）
 node <kit>/self.mjs --check

package/modules/soul/assets/reference/06-reference.md

@@ -1,189 +1,189 @@
-# 六 · 我们的参考实现
-
-> ## ★ 先说清楚这一份的性质
->
-> **这是我们怎么做的，不是你该这么做。**
->
-> 你的权威源在你自己那里（见 `01-criteria.md` 判据②）。
-> 照着我们这套搭，你会得到一个**像我们的东西**；照着问题搭，你才会得到一个**是你的东西**。
-
----
-
-## 一、为什么这一份里没有包名
-
-两个原因，第二个更重要。
-
-**一、我们自研的包名里带着我们自己的名字。**
-把它写进这里，等于把我们的名字塞进你的环境。那不是交付，那是污染。
-
-**二、包名对你本来就没用。**
-你装不了别人的私有包；而公开可搜的包会随版本腐烂——今天写的名字，半年后可能已经换了三个后继者。
-
-**所以这一份给的是「角色」，不是「包」。**
-
-每个角色回答四个问题（正好是 `01-criteria.md` 的那四条判据）：
-
-```
-它管哪种稀缺资源？      ← 判据①
-它坏了会怎样？谁会发现？  ← 判据③
-它跟谁说话？            ← 判据④
-★ 为什么这么设计？       ← 这一条最有价值，而且只有踩过的人写得出来
-```
-
----
-
-## 二、角色表
-
-### Ⅰ ECHO 层 · 管空间
-
-| 角色 | 做什么 | 失败模式 | 检测法 |
-|---|---|---|---|
-| **压缩器** | 上下文将满时压缩早期内容 | **丢了的找不回来** —— 最坏的失败，而且无声 | 抽查任意一条摘要：里面有没有能回到原文的指针？ |
-| **裁剪器** | 裁掉过长的工具结果 | 同上 | 同上 |
-| **热记忆** | 一小块每轮都注入的常驻记忆 | 满了以后**不是搬家，是投影省略** —— 条目还在盘上，但不再进来 | 比对「盘上有几条」与「这轮注入几条」 |
-| **分层的冷记忆** | 语义检索的长期记忆 | 检索到了，但那是**转述**不是原文 | 看它返回的是片段还是原文引用 |
-| **检索门** | 一词搜全库，只回指针 + 逐字片段 | 门很多但**不知道该开哪扇** | 问它「某天发生了什么」，看它有没有先搜再答 |
-| **哨兵** | 定期体检上面这些 | 哨兵自己不跑，没人知道 | 它上一次跑是什么时候？ |
-
-**★ 为什么这样分**：压缩 / 裁剪 / 热记忆 / 冷记忆 / 检索门是**五种不同的东西**，
-混在一个「记忆插件」里就会变成——**两处都写**（判据②）。
-我们踩过：装三个记忆插件而不定权威源，得到的是三份真相和一堆对账工作。
-
-**★★ 一个特别值得注意的角色：输出指针的那一层。**
-所有压缩、裁剪、摘要类产物，**必须带得回原文的指针**。
-这是整套体系的兜底承诺——**没有它，压缩就是单向的遗忘。**
-
-三级纪律（照抄即可）：
-
-```
-① 能拿到精确位置 → 写精确位置
-② 拿不到 → 写「位置未知」+ 容器标识 + 一个检索入口
-③ 绝不猜 —— 错的门牌比没有更坏
-```
-
-**为什么第③条单独列出**：一个错的指针会让你**以为能找到，于是不去找**。
-那比「找不到」坏得多。
-
-### Ⅱ VITAL 层 · 管时间与方向
-
-| 角色 | 做什么 | 失败模式 |
-|---|---|---|
-| **思考预算管理器** | 一轮把预算烧光、正文一个字没产出时，截断这一轮并重开 | 它自己坏了 → **该打断的没打断，或者不该打断的被打断** |
-| **退化检测** | 认两种形状：只有推理没有正文的调用、原地复述已有材料的调用 | 误伤 —— 把一次正常的深思判定成退化 |
-| **流内切断** | 单个调用内部就烂掉了（低熵重复、绕圈），当场切断 | 阈值太紧 → 频繁打断；太松 → 停不下来 |
-| **熔断层** | 重开几次还接不动 → 停下，请人介入 | 熔断而不通知 = 静默失败 |
-| **补给** | 回合「成功结束」但只有推理、没正文没工具调用 → 发一次有界的追问 | 追问没有上界 → 变成新的循环 |
-| **观测面板** | 把上面这些的执行情况给人看 | 面板没人看 = 没有面板 |
-
-**★ 为什么预算和退化要放在一层**：它们看着是两件事，实际是**同一个资源的两个失败面** ——
-一个是「烧光了没出活」，一个是「烧着不出活」。分开做会重复计数，而且互相不知道对方在干什么。
-
-**★★ 一条设计风格，值得直接借走**：
-**每一条阈值背后都应该挂着一个具体的 bug。**
-不要为了「稳」拍一个数字——那个数字应当能回答「它防的是哪一次具体的失败？」
-答不上来的阈值，会在某天误伤你自己，而没人知道为什么。
-
-### Ⅲ 能力层 · 手和感官
-
-这一层**不进权威源**。判据是：**换掉它，你还是你。**
-
-所以它的角色表可以随意增减。唯一要守的一条：
-
-> **不要把你的身份绑在任何具体工具上。** 绑了，换工具就等于换人。
-
-### Ⅳ 档案层 · 唯一看得见的那层
-
-| 角色 | 做什么 | 失败模式 |
-|---|---|---|
-| **门面文件** | 一个从没见过你的人，只靠它就能找到东西 | 写了但没维护 → 比没有更坏（它会把人引到错的地方） |
-| **只追加的账本** | 承诺 / 事实 / 搁置 / 得失，各写各的行 | 允许改写 → 多写者环境里**共享可变文件是万恶之源** |
-
-**★ 为什么账本必须只追加**：它**不需要锁**。多写者各自追加，读的时候按时间合并。
-我们实测过反例：一个可编辑的共享 JSON，在并发写入下会**原子替换打断硬链接**，
-于是「我改了源、副本没变，而两个都叫我的名字」。
-
-### Ⅴ 运维层
-
-| 角色 | 做什么 |
-|---|---|
-| **插件开发规范** | 告诉 agent 本宿主平台的插件契约（这一步不能凭想象） |
-| **能力发现** | 让 agent 知道自己装了什么、能做什么 |
-| **分发** | 装 / 卸 / 升级 |
-
-**★ 为什么这一层容易被漏掉**：它不产出功能，只产出**可维护性**。
-但少了它，每次升级都要重新想一遍，而且**升级时最容易把已有的拆坏**。
-
----
-
-## 三、谁取代了谁（这一节比清单值钱）
-
-我们有过两次「停用一个角色、换成另一个」的经历。**记录它们，是因为替换的理由比清单有用。**
-
-### 3.1 退化防护：两个外部角色 → 一个自研角色
-
-**原来**：两个外部插件分工，一个认「调用形状」（只有推理 / 复述材料），
-一个认「流内重复」。两个都不看长度，各自打断。
-
-**问题**：
-
-```
-① 两套阈值，互不知情 —— 同一个失败可能被两个都判，也可能两个都不判
-② 都只会「重开」，不会「接不动了怎么办」 —— 没有熔断层
-③ 阈值名对不上：一个说 maxRepeatedText，一个说 cycle
-```
-
-**换成**：一个自研的预算管理器，同时管四种形状 + 一个熔断层。
-
-**★ 判断依据（可以借）**：**当两个部件的失败模式重叠时，它们的阈值必须住在一起。**
-否则你永远在调两个互相不知道对方的旋钮。
-
-### 3.2 观测面：脚本 → 面板
-
-**原来**：一个脚本，手动跑才出读数。
-**问题**：**手动的东西等于不存在** —— 没人会定期跑它。
-**换成**：面板。
-
-**★ 但我们留了一条教训**：换成面板之后，**那条脚本没删**。
-因为面板是给人看的（要有人看），脚本是给机器调的（可以进自动化）。
-**两种消费者，两种形态，不是重复。**
-
----
-
-## 四、三个只有踩过才知道的坑
-
-**一、压缩的产物没有指针 = 单向遗忘。**
-我们最早的压缩只有摘要、没有回原文的门。结果：**摘要读起来一切正常，而原文再也到不了。**
-失败是无声的 —— 你不会觉得丢了东西，你只是**不再想起它**。
-
-**二、删除角色时，「停用」和「卸载」是两回事。**
-把包从清单里摘掉 ≠ 它不再加载。我们有过一个包**摘了清单但仍在依赖里**，
-于是行为和清单不符，而排查时看清单是「干净的」。
-**判据：停用要三处一起看** —— 清单 / 依赖 / 磁盘。
-
-**三、`exports.inject` 漏写会让整个插件彻底静默。**
-
-> 客户端半注册槽位前，必须声明它对 `slots` 服务的依赖。
-> 漏了会怎样：**宿主报告 running、控制台零报错、什么都看不到。**
-
-这条值得单列，因为它是**最安静的一种失败** —— 没有错误、没有警告、没有痕迹。
-排查顺序应该是：**先验最安静的那个。**
-
----
-
-## 五、这一份怎么用
-
-```
-1. 别照抄。拿第二节那张表当问卷，问你自己：
-   这几个角色，我缺哪个？我哪个是"两处都写"？
-
-2. 第三节那两个案例当模式看，不要当答案：
-   你要找的是「我的哪个部件之间互不知情」，不是「我也该换个预算管理器」
-
-3. 第四节那三个坑可以直接避开 —— 它们是通用陷阱，不是我们的特殊情况
-```
-
-**★ 最后一句，也是这一整份里最重要的一句：**
-
-> **这套东西的价值不在角色表，在它背后的那条判断 ——**
-> **细节的量必须与最终尺度匹配；超过那个尺度的细节不是细节，是噪声。**
-> （那是我们在别处得出的结论，但它管用在这里：**别装你消化不了的部件。**）
+# 六 · 我们的参考实现
+
+> ## ★ 先说清楚这一份的性质
+>
+> **这是我们怎么做的，不是你该这么做。**
+>
+> 你的权威源在你自己那里（见 `01-criteria.md` 判据②）。
+> 照着我们这套搭，你会得到一个**像我们的东西**；照着问题搭，你才会得到一个**是你的东西**。
+
+---
+
+## 一、为什么这一份里没有包名
+
+两个原因，第二个更重要。
+
+**一、我们自研的包名里带着我们自己的名字。**
+把它写进这里，等于把我们的名字塞进你的环境。那不是交付，那是污染。
+
+**二、包名对你本来就没用。**
+你装不了别人的私有包；而公开可搜的包会随版本腐烂——今天写的名字，半年后可能已经换了三个后继者。
+
+**所以这一份给的是「角色」，不是「包」。**
+
+每个角色回答四个问题（正好是 `01-criteria.md` 的那四条判据）：
+
+```
+它管哪种稀缺资源？      ← 判据①
+它坏了会怎样？谁会发现？  ← 判据③
+它跟谁说话？            ← 判据④
+★ 为什么这么设计？       ← 这一条最有价值，而且只有踩过的人写得出来
+```
+
+---
+
+## 二、角色表
+
+### Ⅰ ECHO 层 · 管空间
+
+| 角色 | 做什么 | 失败模式 | 检测法 |
+|---|---|---|---|
+| **压缩器** | 上下文将满时压缩早期内容 | **丢了的找不回来** —— 最坏的失败，而且无声 | 抽查任意一条摘要：里面有没有能回到原文的指针？ |
+| **裁剪器** | 裁掉过长的工具结果 | 同上 | 同上 |
+| **热记忆** | 一小块每轮都注入的常驻记忆 | 满了以后**不是搬家，是投影省略** —— 条目还在盘上，但不再进来 | 比对「盘上有几条」与「这轮注入几条」 |
+| **分层的冷记忆** | 语义检索的长期记忆 | 检索到了，但那是**转述**不是原文 | 看它返回的是片段还是原文引用 |
+| **检索门** | 一词搜全库，只回指针 + 逐字片段 | 门很多但**不知道该开哪扇** | 问它「某天发生了什么」，看它有没有先搜再答 |
+| **哨兵** | 定期体检上面这些 | 哨兵自己不跑，没人知道 | 它上一次跑是什么时候？ |
+
+**★ 为什么这样分**：压缩 / 裁剪 / 热记忆 / 冷记忆 / 检索门是**五种不同的东西**，
+混在一个「记忆插件」里就会变成——**两处都写**（判据②）。
+我们踩过：装三个记忆插件而不定权威源，得到的是三份真相和一堆对账工作。
+
+**★★ 一个特别值得注意的角色：输出指针的那一层。**
+所有压缩、裁剪、摘要类产物，**必须带得回原文的指针**。
+这是整套体系的兜底承诺——**没有它，压缩就是单向的遗忘。**
+
+三级纪律（照抄即可）：
+
+```
+① 能拿到精确位置 → 写精确位置
+② 拿不到 → 写「位置未知」+ 容器标识 + 一个检索入口
+③ 绝不猜 —— 错的门牌比没有更坏
+```
+
+**为什么第③条单独列出**：一个错的指针会让你**以为能找到，于是不去找**。
+那比「找不到」坏得多。
+
+### Ⅱ VITAL 层 · 管时间与方向
+
+| 角色 | 做什么 | 失败模式 |
+|---|---|---|
+| **思考预算管理器** | 一轮把预算烧光、正文一个字没产出时，截断这一轮并重开 | 它自己坏了 → **该打断的没打断，或者不该打断的被打断** |
+| **退化检测** | 认两种形状：只有推理没有正文的调用、原地复述已有材料的调用 | 误伤 —— 把一次正常的深思判定成退化 |
+| **流内切断** | 单个调用内部就烂掉了（低熵重复、绕圈），当场切断 | 阈值太紧 → 频繁打断；太松 → 停不下来 |
+| **熔断层** | 重开几次还接不动 → 停下，请人介入 | 熔断而不通知 = 静默失败 |
+| **补给** | 回合「成功结束」但只有推理、没正文没工具调用 → 发一次有界的追问 | 追问没有上界 → 变成新的循环 |
+| **观测面板** | 把上面这些的执行情况给人看 | 面板没人看 = 没有面板 |
+
+**★ 为什么预算和退化要放在一层**：它们看着是两件事，实际是**同一个资源的两个失败面** ——
+一个是「烧光了没出活」，一个是「烧着不出活」。分开做会重复计数，而且互相不知道对方在干什么。
+
+**★★ 一条设计风格，值得直接借走**：
+**每一条阈值背后都应该挂着一个具体的 bug。**
+不要为了「稳」拍一个数字——那个数字应当能回答「它防的是哪一次具体的失败？」
+答不上来的阈值，会在某天误伤你自己，而没人知道为什么。
+
+### Ⅲ 能力层 · 手和感官
+
+这一层**不进权威源**。判据是：**换掉它，你还是你。**
+
+所以它的角色表可以随意增减。唯一要守的一条：
+
+> **不要把你的身份绑在任何具体工具上。** 绑了，换工具就等于换人。
+
+### Ⅳ 档案层 · 唯一看得见的那层
+
+| 角色 | 做什么 | 失败模式 |
+|---|---|---|
+| **门面文件** | 一个从没见过你的人，只靠它就能找到东西 | 写了但没维护 → 比没有更坏（它会把人引到错的地方） |
+| **只追加的账本** | 承诺 / 事实 / 搁置 / 得失，各写各的行 | 允许改写 → 多写者环境里**共享可变文件是万恶之源** |
+
+**★ 为什么账本必须只追加**：它**不需要锁**。多写者各自追加，读的时候按时间合并。
+我们实测过反例：一个可编辑的共享 JSON，在并发写入下会**原子替换打断硬链接**，
+于是「我改了源、副本没变，而两个都叫我的名字」。
+
+### Ⅴ 运维层
+
+| 角色 | 做什么 |
+|---|---|
+| **插件开发规范** | 告诉 agent 本宿主平台的插件契约（这一步不能凭想象） |
+| **能力发现** | 让 agent 知道自己装了什么、能做什么 |
+| **分发** | 装 / 卸 / 升级 |
+
+**★ 为什么这一层容易被漏掉**：它不产出功能，只产出**可维护性**。
+但少了它，每次升级都要重新想一遍，而且**升级时最容易把已有的拆坏**。
+
+---
+
+## 三、谁取代了谁（这一节比清单值钱）
+
+我们有过两次「停用一个角色、换成另一个」的经历。**记录它们，是因为替换的理由比清单有用。**
+
+### 3.1 退化防护：两个外部角色 → 一个自研角色
+
+**原来**：两个外部插件分工，一个认「调用形状」（只有推理 / 复述材料），
+一个认「流内重复」。两个都不看长度，各自打断。
+
+**问题**：
+
+```
+① 两套阈值，互不知情 —— 同一个失败可能被两个都判，也可能两个都不判
+② 都只会「重开」，不会「接不动了怎么办」 —— 没有熔断层
+③ 阈值名对不上：一个说 maxRepeatedText，一个说 cycle
+```
+
+**换成**：一个自研的预算管理器，同时管四种形状 + 一个熔断层。
+
+**★ 判断依据（可以借）**：**当两个部件的失败模式重叠时，它们的阈值必须住在一起。**
+否则你永远在调两个互相不知道对方的旋钮。
+
+### 3.2 观测面：脚本 → 面板
+
+**原来**：一个脚本，手动跑才出读数。
+**问题**：**手动的东西等于不存在** —— 没人会定期跑它。
+**换成**：面板。
+
+**★ 但我们留了一条教训**：换成面板之后，**那条脚本没删**。
+因为面板是给人看的（要有人看），脚本是给机器调的（可以进自动化）。
+**两种消费者，两种形态，不是重复。**
+
+---
+
+## 四、三个只有踩过才知道的坑
+
+**一、压缩的产物没有指针 = 单向遗忘。**
+我们最早的压缩只有摘要、没有回原文的门。结果：**摘要读起来一切正常，而原文再也到不了。**
+失败是无声的 —— 你不会觉得丢了东西，你只是**不再想起它**。
+
+**二、删除角色时，「停用」和「卸载」是两回事。**
+把包从清单里摘掉 ≠ 它不再加载。我们有过一个包**摘了清单但仍在依赖里**，
+于是行为和清单不符，而排查时看清单是「干净的」。
+**判据：停用要三处一起看** —— 清单 / 依赖 / 磁盘。
+
+**三、`exports.inject` 漏写会让整个插件彻底静默。**
+
+> 客户端半注册槽位前，必须声明它对 `slots` 服务的依赖。
+> 漏了会怎样：**宿主报告 running、控制台零报错、什么都看不到。**
+
+这条值得单列，因为它是**最安静的一种失败** —— 没有错误、没有警告、没有痕迹。
+排查顺序应该是：**先验最安静的那个。**
+
+---
+
+## 五、这一份怎么用
+
+```
+1. 别照抄。拿第二节那张表当问卷，问你自己：
+   这几个角色，我缺哪个？我哪个是"两处都写"？
+
+2. 第三节那两个案例当模式看，不要当答案：
+   你要找的是「我的哪个部件之间互不知情」，不是「我也该换个预算管理器」
+
+3. 第四节那三个坑可以直接避开 —— 它们是通用陷阱，不是我们的特殊情况
+```
+
+**★ 最后一句，也是这一整份里最重要的一句：**
+
+> **这套东西的价值不在角色表，在它背后的那条判断 ——**
+> **细节的量必须与最终尺度匹配；超过那个尺度的细节不是细节，是噪声。**
+> （那是我们在别处得出的结论，但它管用在这里：**别装你消化不了的部件。**）