pi-patch-keeper 1.2.7 → 1.2.9

package/README.md

@@ -9,6 +9,14 @@
 
 pi 配置守卫：codemode 一致性、force 顺序、环境指纹漂移、注入手册对齐。**不含 PiDeck 与第三方源码补丁。**
 
+## 快速事实
+
+| 项 | 说明 |
+| --- | --- |
+| 配置文件 | **无**（只读 settings.json / APPEND_SYSTEM.md） |
+| 命令行 | /patch-keeper [fix] |
+| 调用方式 | **全自动**：启动自检并自动修复 force 顺序；fix 手动重跑 |
+
 ## 安装
 
 ```bash
@@ -40,6 +48,8 @@ pi install npm:pi-patch-keeper
 - 写盘用临时文件 + rename；修复前备份。
 
 
+## 原理（专业）
+
 ```mermaid
 flowchart TD
     A[factory] --> B[读 settings.json 建指纹]
@@ -52,6 +62,22 @@ flowchart TD
     H -->|不一致| I[通知 + nextTurn 尾部消息<br/>以磁盘为准]
 ```
 
+## 原理（小白）
+
+像出门前的门卫，检查三件事：开关是否一致、排队顺序对不对、手里的说明书是不是最新版；能顺手修的直接修，修不了就提醒你。
+
+```mermaid
+flowchart LR
+    A[启动] --> B[门卫检查三件事]
+    B --> C{开关一致?}
+    B --> D{排队顺序对?}
+    B --> E{说明书最新?}
+    C -->|否| F[提醒]
+    D -->|否| G[直接调好]
+    E -->|否| H[提醒：以手上那份为准]
+```
+
+
 ## License
 
 MIT
@@ -64,6 +90,14 @@ MIT
 
 pi configuration guards: codemode consistency, force order, settings fingerprint drift, injected-manual alignment. **No PiDeck or third-party source patching.**
 
+## At a glance
+
+| Item | Description |
+| --- | --- |
+| Config file | **None** (reads settings.json / APPEND_SYSTEM.md only) |
+| Commands | /patch-keeper [fix] |
+| Automation | **Fully automatic**: self-checks at startup and repairs force order; fix re-runs it |
+
 ## Install
 
 ```bash
@@ -95,7 +129,33 @@ No config file (only reads `settings.json` and `APPEND_SYSTEM.md`); no environme
 - Writes are atomic (temp file + rename); a backup precedes any repair.
 
 
+## How it works (technical)
+
 ```mermaid
+flowchart TD
+    A[factory] --> B[read settings.json, build fingerprint]
+    B --> C[session_start]
+    C --> D{fingerprint changed?}
+    D -->|yes| E[notify: manuals may be stale]
+    C --> F{force order wrong?}
+    F -->|yes| G[backup + reorder packages]
+    C --> H[before_agent_start<br/>compare injected manual vs disk]
+    H -->|mismatch| I[notify + nextTurn message<br/>trust disk]
+
+## How it works (plain words)
+
+Like a doorman before you leave: checks three things — switches agree, queue order is right, the manual in hand is the latest version; fixes what it can and tells you the rest.
+
+```mermaid
+flowchart LR
+    A[startup] --> B[doorman checks three things]
+    B --> C{switches agree?}
+    B --> D{queue order right?}
+    B --> E{manual up to date?}
+    C -->|no| F[notify]
+    D -->|no| G[fix it directly]
+    E -->|no| H[notify: trust the copy in hand]
+```
 flowchart TD
     A[factory] --> B[read settings.json, build fingerprint]
     B --> C[session_start]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-patch-keeper",
-  "version": "1.2.7",
+  "version": "1.2.9",
   "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.)",
   "type": "module",
   "license": "MIT",