pi-patch-keeper 1.0.5 → 1.0.7

package/README.md

@@ -1,53 +1,57 @@
 # pi-patch-keeper — 扩展加载顺序守护（pi 扩展）
 
-防止「force 型扩展」静默吞掉其后所有 section 的 system 注入。
+防止「force 型扩展」静默吞掉其后的 system 注入。
 
-## 来源与借鉴
+## 为什么需要
 
-原创，无上游实现。动机来自一个反复出现的症状：某个扩展明明装了、section 也写了，却没出现在 system prompt 里——根因是它前面有扩展 `return { systemPrompt }`，覆盖式替换把后续写入全丢了，而且不报错。
+pi 的 system prompt 由各扩展写入的 section 拼装。若某扩展在 `before_agent_start` 里
+`return { systemPrompt }`（或设置 `forceSystemPrompt`），宿主会用返回值**整段替换**，
+其后所有扩展的 section 写入被静默丢弃——没有报错，表现为「配了却不起效」。
 
 ## 功能
 
-- 启动时检查 `~/.pi/agent/settings.json` 的 `packages` 顺序：已知 force 型必须在末尾。
-- 静态扫描已装 npm 扩展的入口源码，区分两类：
-  - **无条件 force**（`return { systemPrompt }` 或 `forceSystemPrompt`）→ 必须排在末尾；
-  - **section 优先 + 旧宿主兜底**（先写 sections，旧宿主才 force）→ 只提示，不建议移动。
-- 记录 settings 关键字段指纹（packages / defaultTools / enabledModels / extensions / codemode），变化时提示「此前的结论可能过期」。
-- codemode 单点检查：禁用 `builtin:codemode` 时必须有替代实现，反之亦然（双实现或单点断裂都会报）。
-- 只在发现问题时提示；命令随时查看状态。
+- **启动检查** `settings.json` 的 `packages` 顺序：已知 force 型必须整体位于末尾。
+- **静态扫描**已装 npm 扩展的入口源码，区分两类：
+  - 「无条件 force」——从不写 section，只 return systemPrompt（会吞掉其后一切）
+  - 「兼容兜底」——先写 section，只在旧宿主才 force（安全）
+- **自动修复**：把已知 force 型移到末尾（写前备份 `settings.json.bak-force-order-*`）。
+- **指纹提示**：记录 `packages / defaultTools / enabledModels / extensions / codemode` 指纹，
+  变化时提示「环境已变，旧结论可能过期」。
+- **codemode 单点检查**：禁用 `builtin:codemode` 必须有替代实现，反之亦然。
 
 ## 命令
 
 | 命令 | 作用 |
 | --- | --- |
-| `/patch-keeper` | 查看顺序、疑似 force 包、兜底包、codemode 单点状态 |
-| `/patch-keeper fix` | 把已知 force 型移到 `packages` 末尾（写前备份 `settings.json.bak-force-order-*`） |
+| `/patch-keeper` | 查看顺序 / 疑似 force / 兼容兜底 / codemode 单点 |
+| `/patch-keeper fix` | 修 force 顺序（写前备份） |
 
-## 默认配置
+## 配置
 
-| 项 | 默认 | 说明 |
-| --- | --- | --- |
-| `forceTail` | `npm:pi-rtk-optimizer`, `npm:pi-cache-optimizer` | 已知无条件 force 型；触发概率升序 |
-| 自动修复 | 开 | 仅调整顺序，写前备份 |
-| 提示时机 | 仅异常 | 无问题零输出 |
-| 检测范围 | `npm:` 包 | 本地路径包跳过 |
-
-配置文件（可选）：`~/.pi/patch-keeper-state.json`
+`~/.pi/patch-keeper.json`（可选）：
 
 ```json
 { "forceTail": ["npm:pi-rtk-optimizer", "npm:pi-cache-optimizer"] }
 ```
 
-## 机制（为什么放在启动时）
+`forceTail` 覆盖默认的「已知 force 型」列表；数组顺序即期望顺序（最可能触发者最后）。
+指纹状态写入同文件的 `fingerprint` 字段。
+
+## 纪律
 
-pi 的 `before_agent_start` 依次调用各扩展；返回 `{ systemPrompt }` 等于 `forceSystemPrompt`——**覆盖式替换**，此后所有扩展对 sections 的修改都被丢弃。因此「谁在末尾」是有行为后果的，不是风格问题。本扩展只在 `session_start` 检查与提示，自身**绝不** return systemPrompt。
+- **绝不** `return { systemPrompt }` —— 否则自己就是它要防的问题。
+- 唯一的写操作是修 `settings.json` 的 `packages`，且写前备份。
+- 任何异常只提示、不抛错；无问题不打扰。
 
-## 局限
+## 安装
 
-- 只识别静态形态（`return { systemPrompt }` / `forceSystemPrompt`）；动态拼接无法识别。
-- 只处理 `npm:` 前缀包；本地路径包（`path:` / 相对路径）不扫描。
-- 只能保证「已知 force 型在末尾」；未知的 force 型需要人工确认后加入 `forceTail`。
+```bash
+pi install npm:pi-patch-keeper
+pi install ./pi-patch-keeper
+```
 
-## 许可证
+## 限制
 
-MIT。
+- 静态扫描只看扩展入口前 4000 字符内 `before_agent_start` 附近的写法，动态构造的 force 检测不到。
+- user 扩展（不在 `packages` 数组里）不在扫描范围。
+- 只处理顺序问题；不修改任何第三方扩展的源码。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-patch-keeper",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Detect and fix pi extension load-order hazards: force-typed extensions silently swallow later system-prompt sections.",
   "type": "module",
   "license": "MIT",