pi-patch-keeper 1.1.1 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.en.md +69 -27
  2. package/README.md +60 -37
  3. package/package.json +2 -2
package/README.en.md CHANGED
@@ -1,44 +1,86 @@
1
- # pi-patch-keeper — patch self-healing and status checks (pi extension)
1
+ # pi-patch-keeper — pi configuration guards (pi extension)
2
2
 
3
- Turns "patches to other people's packages must be re-applied after every upgrade" into startup self-healing with an explicit report.
3
+ > Requires pi >= 0.74 · Node >= 20 · MIT · no runtime dependencies · no PiDeck or third-party patching
4
4
 
5
- ## What it heals
5
+ ## What it solves
6
6
 
7
- | Target | Action |
8
- | --- | --- |
9
- | pi-lens wordindex patch (symbol_search stuck on "building") | fixes in place at startup; stops when upstream ships the fix (warm_cache_adopted) |
10
- | pi-memory exit summary / section precedence | fixes in place, backup first |
11
- | pi-tactician section precedence | fixes in place, backup first |
12
- | PiDeck builtin extensions (5, dual copies) | restores from the snapshot copy when a release overwrites them |
13
- | PiDeck app.asar (3 patches) | detect only (file locked while PiDeck runs) |
14
- | force-typed extension order | auto-moves known force-typed packages to the end, backup first |
15
- | manual version vs injected version | warns once per mismatch pair |
7
+ Three configuration failures happen silently: the codemode switch disagreeing with the installed guard, a force-type extension sitting mid-list (dropping every later section), and an injected manual that is older than the one on disk. None of them error — behaviour just drifts. This extension checks at startup and fixes what it can.
8
+
9
+ ## Features
10
+
11
+ - **codemode single-source check**: disabling `builtin:codemode` and installing `pi-codemode-guard` must agree.
12
+ - **force-order guard**: force-type extensions must sit last in `packages`; wrong order is fixed automatically (with a backup).
13
+ - **Environment fingerprint drift**: notifies when key `settings.json` fields change, since manuals or prior verification may be stale.
14
+ - **Injection alignment**: compares injected `APPEND_SYSTEM.md` version with disk and tells the model to trust disk.
15
+ - Commands `/patch-keeper` and `/patch-keeper fix`.
16
16
 
17
17
  ## Install
18
18
 
19
- pi install npm:pi-patch-keeper
20
- pi install ./pi-patch-keeper
19
+ ```bash
20
+ pi install npm:pi-patch-keeper
21
+ pi install ./pi-patch-keeper
22
+ ```
23
+
24
+ ## Configuration
25
+
26
+ ### 1 · Config file
21
27
 
22
- Reload or restart the session after installing.
28
+ **None** — it only reads `settings.json` and the manual.
23
29
 
24
- ## Commands
30
+ ### 2 · Environment
25
31
 
26
- | Command | Effect |
32
+ None.
33
+
34
+ ### 3 · Commands
35
+
36
+ | Command | Purpose |
27
37
  | --- | --- |
28
- | /patch-keeper | status of every patch face |
29
- | /patch-keeper fix | heal what can be healed now |
38
+ | `/patch-keeper` | codemode / force / fingerprint / injection-alignment status |
39
+ | `/patch-keeper fix` | Repair force order in `packages` (with backup) |
40
+
41
+ ### 4 · State files (self-maintained)
42
+
43
+ | Item | Path | Description |
44
+ | --- | --- | --- |
45
+ | Fingerprint | `~/.pi/patch-keeper.json` | Settings snapshot for drift detection |
46
+ | Manual sentinel | `~/.pi/patch-keeper-manual.json` | Manual version / content signature |
47
+ | Fix backup | `~/.pi/agent/settings.json.bak-force-order-*` | Backup before repair |
48
+
49
+ ### 5 · Not included (local module)
50
+
51
+ PiDeck builtin patch restore, read-only asar checks, pi-lens / pi-memory / pi-tactician source patches, local snapshot restore — all depend on the PiDeck install directory, third-party internals or local paths, so they are **not shipped**; a local module `patch-keeper-local` provides them (`/patch-keeper-local`).
52
+
53
+ ## Where it acts (prompt and config paths)
54
+
55
+ | Stage | Does |
56
+ | --- | --- |
57
+ | factory (startup) | Fingerprint compare, force self-check and auto-repair; failures only notify |
58
+ | `session_start` | Summarises drift / order / manual drift in one notification |
59
+ | `before_agent_start` | Compares injected manual version with disk (**read-only**, never rewrites the prompt) |
60
+
61
+ It never touches thinking or tool calls: it acts on the **system prompt and configuration state**.
62
+
63
+ ## Feedback path
64
+
65
+ | Item | Path | Why |
66
+ | --- | --- | --- |
67
+ | Injection-alignment hint | User notification + trailing message `nextTurn`, `display:false` | The user already knows; the model must too, otherwise "use the disk version" stops at the user side |
68
+ | Alignment text | "injected vX != disk vY -> injected is not evidence; action: read disk and continue" | Gives both criterion and action |
69
+ | Never returns systemPrompt | Only its own section / message | Returning it replaces the whole prompt (`forceSystemPrompt`) and silently drops every later section |
70
+ | Drift / force problems | Notification only (once per `session_start`) | Low-frequency information |
30
71
 
31
- ## Discipline
72
+ ## How it works
32
73
 
33
- - Never returns systemPrompt; only notifies.
34
- - Any failure is reported as a hint, never thrown.
35
- - All paths derive from the home directory, so it survives machine, username and drive changes.
74
+ - All writes are atomic (temp file + rename); a backup precedes any repair.
75
+ - Force repair moves known force-type packages to the end, preserving the rest.
76
+ - Manual drift uses version + content signature, so unversioned content edits are caught.
36
77
 
37
- ## Limits
78
+ ## Limitations
38
79
 
39
- - asar patches cannot be applied while PiDeck is running; the extension only reports them.
40
- - Upstream patches are detected by marker strings; a substantially rewritten upstream file is reported as unknown instead of being patched.
80
+ - Covers pi's own configuration only.
81
+ - Force repair relies on a built-in known-force list.
82
+ - Drift reports what changed, not whether the new value is right.
41
83
 
42
84
  ## License
43
85
 
44
- MIT.
86
+ MIT
package/README.md CHANGED
@@ -1,63 +1,86 @@
1
- # pi-patch-keeper —— 补丁自愈与状态检测（pi 扩展）
1
+ # pi-patch-keeper —— pi 配置守卫（pi 扩展）
2
2
 
3
- ## 安装
3
+ > 适用 pi ≥ 0.74 · Node ≥ 20 · MIT · 无运行时依赖 · 不含 PiDeck / 第三方补丁
4
+
5
+ ## 它解决什么问题
6
+
7
+ pi 的配置有三类静默失效：codemode 开关与插件不一致、force 型扩展排在中途导致其后 section 被丢弃、注入的手册与磁盘版本不同步。它们都不会报错，只会让行为悄悄偏离。本扩展在启动时检查并在能修时自动修。
8
+
9
+ ## 功能
4
10
 
5
- npm 发布版：`pi install npm:pi-patch-keeper`
11
+ - **codemode 单点一致性**：禁 `builtin:codemode` 与安装 `pi-codemode-guard` 必须同时成立。
12
+ - **force 顺序守卫**：force 型扩展必须排在 `packages` 末尾，乱序自动修复（先备份）。
13
+ - **环境指纹漂移**：`settings.json` 的关键字段变化时提示「手册或验证结论可能过期」。
14
+ - **注入对齐**：比对注入的 `APPEND_SYSTEM.md` 版本与磁盘版本，不一致时按磁盘版执行。
15
+ - 命令 `/patch-keeper` / `/patch-keeper fix`。
6
16
 
7
- 本地目录：`pi install <path/to/patch-keeper>`
17
+ ## 安装
18
+
19
+ ```bash
20
+ pi install npm:pi-patch-keeper
21
+ pi install ./pi-patch-keeper
22
+ ```
8
23
 
9
- 安装后 `/reload` 或重启会话生效（扩展源码改动需重启）。
24
+ ## 配置
10
25
 
11
- **是什么**：把「对别人的东西」的改动（**12 个面**：PiDeck builtin ×5 双份 · npm 包 ×4 · app.asar ×3）从「升级后手工重跑」变成**启动自愈 + 明确报告**——外置、模块化、抗上游升级。全量清单由本机补丁登记表维护（PATCH-REGISTRY，随快照包分发）。
26
+ ### 1 · 配置文件
12
27
 
13
- ## 来源与借鉴
28
+ **无配置文件**：本包只读 `settings.json` 与手册，不引入自己的键。
14
29
 
15
- 原创，无上游实现。设计灵感来自本机长期维护 PiDeck / pi 补丁的实践：补丁会被升级覆盖，故需要启动时自检与自愈。
30
+ ### 2 · 环境变量
16
31
 
17
- ## 机制（源码级）
32
+ 无。
18
33
 
19
- 1. **session_start 自检**（每次 pi 启动）：
20
- - **pi-lens wordindex 补丁：能修的直接修**——本扩展是 user 扩展（加载 rank 2），先于 pi-lens 的 package rank 4；factory 内同步改 `dist/index.js`，pi-lens 随后 import 到的即打过补丁的内容（**当轮生效**）；半打状态先还原再重打（幂等）。**上游发版后停手**：dist 出现 `warm_cache_adopted`（#4583 / PR #4586）即视为 A 已修复——跳过 A、只补 B（B 上游未修），`/patch-keeper` 显示「上游已修复 #4583」。
21
- - **pi-memory exit summary 空行规范化：能修的直接修**——改 npm pi-memory 的 `index.ts`（render 侧规范块级空行；幂等；写前留 `.bak-exitsummary-<stamp>` 备份）。
22
- - **PiDeck asar 三补丁：只检测不修**——PiDeck 运行中文件被锁、插件无权碰 Electron 主进程；检测到未打补丁时提示跑 `launch-pideck.cmd`（启动前自动重打）或快照 `05-脚本补丁/` 下脚本。
23
- 2. **before_agent_start 注入对齐检测**：比对「本轮注入的手册版本」vs「磁盘版」——不一致提示**一次**（同 pair 去重）；方向不限（注入滞后 / 磁盘回滚都可能）。
24
- 3. **环境漂移指纹**：`~/.pi/patch-keeper.json` 记录 settings 关键字段（packages / defaultTools 等）——支撑漂移检测。
25
- 4. **force 顺序守卫（自动修复）**：packages 中条件 force 型（pi-rtk-optimizer / pi-cache-optimizer）须在末尾——启动与 /patch-keeper fix 时自动移到末尾（先备份 settings.json.bak-force-order-*），修复幂等；其后 section 写入不会被静默丢弃。
26
- 5. **force 型扩展扫描（疑似）**：扫描 packages 入口源码中的 return { systemPrompt } / forceSystemPrompt，报告疑似无条件 force 的包（会覆盖 system、使其后 section 静默丢失）；位于中间者启动时提示。先写 section、只有旧宿主才 force 的归为「兼容兜底」，不计入疑似。
34
+ ### 3 · 命令
27
35
 
28
- ## 自我回灌（条件触发型）
36
+ | 命令 | 作用 |
37
+ | --- | --- |
38
+ | `/patch-keeper` | codemode / force / 指纹 / 注入对齐状态 |
39
+ | `/patch-keeper fix` | 修复 `packages` 的 force 顺序（带备份） |
29
40
 
30
- 与 caveman / ptc-meter / think-anchor 的「每轮回灌」不同：**常态零注入**，只在异常时出声一次——
41
+ ### 4 · 状态文件（自动维护）
31
42
 
32
- - 每轮 before_agent_start 比对「本轮实际注入的手册版本」vs「磁盘版本」；
33
- - 不一致（注入滞后 / 磁盘回滚均可能）→ 一次 notify 提示「以磁盘为准、先读回全文」（同 pair 去重，不重复打扰）；
34
- - notify 用户 + 回灌模型（nextTurn，四律②：用户侧收到后模型也须知道，否则「以磁盘为准」停在用户侧）；检测失败静默。
43
+ | 项 | 路径 | 说明 |
44
+ | --- | --- | --- |
45
+ | 环境指纹 | `~/.pi/patch-keeper.json` | 上次启动的配置快照，用于漂移对比 |
46
+ | 手册哨兵 | `~/.pi/patch-keeper-manual.json` | 手册版本 / 内容签名，抓「改了内容没升版本」 |
47
+ | 修复备份 | `~/.pi/agent/settings.json.bak-force-order-*` | 修复前备份 |
35
48
 
36
- ## 纪律（回灌四律实践）
49
+ ### 5 · 不包含（本机模块）
37
50
 
38
- - **绝不返回 systemPrompt**——只 notify；任何失败静默（检测不该影响会话，绝不抛错）。
39
- - 路径全部从 home / `%LOCALAPPDATA%` 推导——换机、换用户名、复刻包到别机均可用。
51
+ PiDeck builtin 补丁双份恢复、asar 只读检测、pi-lens / pi-memory / pi-tactician 源码补丁、本机快照恢复 —— 依赖 PiDeck 安装目录、第三方包内部实现与本机路径，**不随本包发布**；由本机模块 `patch-keeper-local` 提供（`/patch-keeper-local`）。
40
52
 
41
- ## 配置与命令
53
+ ## 作用点（配置与提示通路）
42
54
 
43
- | 项 | 值 |
55
+ | 阶段 | 做什么 |
44
56
  | --- | --- |
45
- | 指纹文件 | `~/.pi/patch-keeper.json`（随 settings 变化同步） |
46
- | 命令 | `/patch-keeper`（状态）· `/patch-keeper fix`（能修的立即修） |
57
+ | factory（启动） | 指纹对比、force 自检与自动修复；失败只提示 |
58
+ | `session_start` | 汇总漂移 / 顺序 / 手册漂移，一次通知 |
59
+ | `before_agent_start` | 比对注入手册版本与磁盘版本（**只读**，不改 prompt） |
60
+
61
+ 它不碰 thinking，也不碰工具调用：作用的是**系统提示与配置状态**。
47
62
 
48
- ## 生效与回滚
63
+ ## 回灌（反馈回到模型的通路）
49
64
 
50
- - 生效：装上即用（每次会话启动自检）；代码改动 `/reload` 或重启。
51
- - 回滚：删本目录；已打补丁保持原样（回退用 `05-脚本补丁/` 下脚本各自的 rollback）。
65
+ | 项 | 通路 | 设计理由 |
66
+ | --- | --- | --- |
67
+ | 注入对齐提示 | 通知用户 + 尾部消息 `nextTurn`、`display:false` | 用户已收到通知，模型也必须知道，否则「以磁盘版执行」只停在用户侧 |
68
+ | 注入对齐文本 | 「注入 vX ≠ 磁盘 vY → 注入版不可作判断依据；动作：读回全文后执行」 | 给出判据与动作，而不是只报事实 |
69
+ | 绝不返回 systemPrompt | 只写自己的 section / 消息 | 返回即 forceSystemPrompt **覆盖式替换**，会静默丢弃其后所有 section 的修改 |
70
+ | 指纹漂移 / force 问题 | 仅通知（`session_start` 一次） | 低频信息，不需要每轮打扰 |
52
71
 
53
- ## 测试
72
+ ## 机制
54
73
 
55
- 源码仓库内的隔离自测覆盖：force 顺序三例、命令注册、版本不一致告警一次的 pair 去重、一致静默、空 event 不抛、session_start 失败静默、自建扩展被覆盖后从快照恢复、上游已修标记（A 停打 / 仅补 B）。
74
+ - 所有写盘走「临时文件 + rename」原子写；修复前留备份。
75
+ - force 顺序修复只移动已知 force 型包到末尾，其余相对顺序不变。
76
+ - 手册漂移用「版本号 + 内容签名」双判据，避免只看版本号漏掉未登记的正文改动。
56
77
 
57
- ## 环境依赖与降级
78
+ ## 限制
58
79
 
59
- 补丁目标（npm 包与 PiDeck builtin）不存在时对应项跳过并只报状态，不报错；本机快照目录（备份与恢复来源）缺失时，恢复类动作跳过，自愈仍然工作。适配任意用户名与安装路径。
80
+ - 只覆盖 pi 自身配置，不检查第三方插件行为。
81
+ - force 修复依赖内置的 known-force 列表（随版本更新）。
82
+ - 指纹只报「变了什么」，不判断新值是否正确。
60
83
 
61
84
  ## License
62
85
 
63
- MIT.
86
+ MIT
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pi-patch-keeper",
3
- "version": "1.1.1",
4
- "description": "Startup self-healing for pi/pi-lens/pi-memory/PiDeck patches, plus force-typed extension order guard and status report.",
3
+ "version": "1.2.1",
4
+ "description": "pi config guards: codemode single-source check, force-order guard (auto-fix), settings fingerprint drift, injected-manual alignment. (PiDeck / third-party source patches are a local-only module, not bundled.)",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "keywords": [