pi-patch-keeper 1.2.11 → 1.3.1

package/README.md

@@ -13,7 +13,7 @@ pi 配置守卫：codemode 一致性、force 顺序、环境指纹漂移、注
 
 | 项 | 说明 |
 | --- | --- |
-| 配置文件 | **无**（只读 settings.json / APPEND_SYSTEM.md） |
+| 配置文件 | `~/.pi/patch-keeper.json`（可省略；`forceTail` 数组） |
 | 命令行 | /patch-keeper [fix] |
 | 调用方式 | **全自动**：启动自检并自动修复 force 顺序；fix 手动重跑 |
 
@@ -25,11 +25,23 @@ pi install npm:pi-patch-keeper
 
 ## 配置
 
-无配置文件（只读 `settings.json` 与 `APPEND_SYSTEM.md`）；无环境变量。
+配置文件 `~/.pi/patch-keeper.json`（可省略）；无环境变量。
+
+| 键 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `forceTail` | string[] | `["npm:pi-rtk-optimizer", "npm:pi-cache-optimizer"]` | 视为 force 型的包名（须排在 packages 末尾）；配了非空数组则完全覆盖默认 |
+
+完整配置：
+
+```json
+{
+  "forceTail": ["npm:pi-rtk-optimizer", "npm:pi-cache-optimizer"]
+}
+```
 
 | 状态文件 | 说明 |
 | --- | --- |
-| `~/.pi/patch-keeper.json` | 上次启动的配置指纹（漂移对比） |
+| `~/.pi/patch-keeper-state.json` | 上次启动的配置指纹（漂移对比） |
 | `~/.pi/patch-keeper-manual.json` | 手册版本 + 内容签名 |
 | `~/.pi/agent/settings.json.bak-force-order-*` | force 顺序修复前的备份 |
 
@@ -51,14 +63,11 @@ pi install npm:pi-patch-keeper
 
 ```mermaid
 flowchart TD
-    A[factory] --> B[读 settings.json 建指纹]
-    B --> C[session_start]
-    C --> D{指纹变化?}
-    D -->|是| E[通知：手册/结论可能过期]
-    C --> F{force 顺序错?}
-    F -->|是| G[备份 + 重排 packages]
-    C --> H[before_agent_start<br/>比对注入手册版本与磁盘]
-    H -->|不一致| I[通知 + nextTurn 尾部消息<br/>以磁盘为准]
+    A[factory：读 settings.json 建指纹] --> B[session_start]
+    A --> C[before_agent_start]
+    B -->|指纹变化| D[通知：手册 / 结论可能过期]
+    B -->|force 顺序错| E[备份 + 重排 packages]
+    C -->|注入版本 vs 磁盘不一致| F[通知 + nextTurn 尾部消息<br/>以磁盘为准]
 ```
 
 ## 原理（小白）
@@ -92,7 +101,7 @@ pi configuration guards: codemode consistency, force order, settings fingerprint
 
 | Item | Description |
 | --- | --- |
-| Config file | **None** (reads settings.json / APPEND_SYSTEM.md only) |
+| Config file | `~/.pi/patch-keeper.json` (optional; `forceTail` array) |
 | Commands | /patch-keeper [fix] |
 | Automation | **Fully automatic**: self-checks at startup and repairs force order; fix re-runs it |
 
@@ -104,11 +113,15 @@ pi install npm:pi-patch-keeper
 
 ## Configuration
 
-No config file (only reads `settings.json` and `APPEND_SYSTEM.md`); no environment variables.
+Config file `~/.pi/patch-keeper.json` (optional); no environment variables.
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `forceTail` | string[] | `["npm:pi-rtk-optimizer", "npm:pi-cache-optimizer"]` | Packages treated as force-type (must sit last in packages); a non-empty array replaces the default |
 
 | State file | Description |
 | --- | --- |
-| `~/.pi/patch-keeper.json` | Settings fingerprint from the previous start (drift compare) |
+| `~/.pi/patch-keeper-state.json` | Settings fingerprint from the previous start (drift compare) |
 | `~/.pi/patch-keeper-manual.json` | Manual version + content signature |
 | `~/.pi/agent/settings.json.bak-force-order-*` | Backup before a force-order repair |
 
@@ -130,15 +143,11 @@ No config file (only reads `settings.json` and `APPEND_SYSTEM.md`); no environme
 
 ```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]
-
+    A[factory: build fingerprint from settings.json] --> B[session_start]
+    A --> C[before_agent_start]
+    B -->|fingerprint changed| D[notify: manuals may be stale]
+    B -->|force order wrong| E[backup + reorder packages]
+    C -->|injected vs disk mismatch| F[notify + nextTurn message<br/>trust disk]
 ```
 
 ## How it works (plain words)

package/index.ts

@@ -15,7 +15,8 @@ import * as path from "node:path";
 
 const HOME = os.homedir();
 
-const FINGERPRINT = path.join(HOME, ".pi", "patch-keeper.json");
+const CONFIG = path.join(HOME, ".pi", "patch-keeper.json");      // 用户配置（可编辑）
+const FINGERPRINT = path.join(HOME, ".pi", "patch-keeper-state.json"); // 指纹状态（自动维护）
 
 const SETTINGS = path.join(HOME, ".pi", "agent", "settings.json");
 // 手册（注入对齐检测：本轮注入文本的版本行 vs 磁盘版）
@@ -121,25 +122,42 @@ function manualDrift(): string | null {
   return null;
 }
 // 已知盲区：caveman-think-zh 是 user 扩展（不在 packages 数组），它在检测到原版英文段时
-// 也会 force；FORCE_TAIL 覆盖不到，触发时本扩展看不到。
+// 也会 force；forceTail 覆盖不到，触发时本扩展看不到。
 /** force/条件 force 型必须排在 packages 末尾（其后 section 写入会被静默丢弃）。触发概率升序：rtk → cache-optimizer。 */
-const FORCE_TAIL = ["npm:pi-rtk-optimizer", "npm:pi-cache-optimizer"];
+const DEFAULT_FORCE_TAIL = ["npm:pi-rtk-optimizer", "npm:pi-cache-optimizer"];
+
+/** 用户配置（~/.pi/patch-keeper.json，可省略）：forceTail 决定哪些包被视为 force 型。 */
+export type PkConfig = { forceTail?: string[] };
+export function loadConfig(): PkConfig {
+  const raw = safeRead(CONFIG);
+  if (raw === null) return {};
+  try { const j = JSON.parse(raw) as PkConfig; return j && typeof j === "object" ? j : {}; } catch { return {}; }
+}
+/** force 型包列表（配置优先，缺省用内置两项）。 */
+export function forceTail(): string[] {
+  const c = loadConfig();
+  const list = Array.isArray(c.forceTail) ? c.forceTail.filter((x): x is string => typeof x === "string" && x.length > 0) : [];
+  return list.length ? list : DEFAULT_FORCE_TAIL;
+}
 export function forceOrderIssues(packages: string[]): string[] {
   const out: string[] = [];
+  const FT = forceTail();
   const idx = (n: string) => packages.indexOf(n);
-  const present = FORCE_TAIL.filter((n) => idx(n) >= 0);
+  const present = FT.filter((n) => idx(n) >= 0);
   if (!present.length) return out;
   const minForce = Math.min(...present.map(idx));
-  const later = packages.slice(minForce + 1).filter((n) => !FORCE_TAIL.includes(n));
-  if (later.length) out.push(`force 型之后仍有 ${later.length} 个包（${later.slice(0, 2).join(" / ")}）—— 它们的 section 写入会被丢弃；把 ${FORCE_TAIL.join(" / ")} 移到末尾`);
-  if (idx(FORCE_TAIL[0]) >= 0 && idx(FORCE_TAIL[1]) >= 0 && idx(FORCE_TAIL[0]) > idx(FORCE_TAIL[1])) out.push("force 顺序应为 rtk → cache-optimizer（最可能触发者最后）");
+  const later = packages.slice(minForce + 1).filter((n) => !FT.includes(n));
+  if (later.length) out.push(`force 型之后仍有 ${later.length} 个包（${later.slice(0, 2).join(" / ")}）—— 它们的 section 写入会被丢弃；把 ${FT.join(" / ")} 移到末尾`);
+  const actual = present.slice().sort((a, b) => idx(a) - idx(b));
+  if (actual.join("|") !== present.join("|")) out.push("force 顺序应为 " + FT.join(" → ") + "（最可能触发者最后）");
   return out;
 }
-/** 把 FORCE_TAIL 成员移到末尾（其余相对顺序不变）；已正确时返回 null。 */
+/** 把 forceTail 成员移到末尾（其余相对顺序不变）；已正确时返回 null。 */
 export function normalizeForceOrder(packages: string[]): string[] | null {
-  const present = FORCE_TAIL.filter((n) => packages.includes(n));
+  const FT = forceTail();
+  const present = FT.filter((n) => packages.includes(n));
   if (!present.length) return null;
-  const rest = packages.filter((n) => !FORCE_TAIL.includes(n));
+  const rest = packages.filter((n) => !FT.includes(n));
   const next = [...rest, ...present];
   return next.join("\n") === packages.join("\n") ? null : next;
 }
@@ -158,7 +176,7 @@ function fixForceOrder(): string | null {
     s.packages = next;
     writeAtomic(SETTINGS, JSON.stringify(s, null, 2));
   } catch (e) { return `force 顺序自动修复失败：${(e as Error).message}`; }
-  return `force 顺序已自动修复：${FORCE_TAIL.filter((n) => next.includes(n)).join(" / ")} 移到 packages 末尾`;
+  return `force 顺序已自动修复：${forceTail().filter((n) => next.includes(n)).join(" / ")} 移到 packages 末尾`;
 }
 /** 静态扫描：packages 中疑似 force 型扩展（入口源码含 return { systemPrompt } / forceSystemPrompt）。 */
 const FORCE_RE = /return\s*\{\s*systemPrompt|forceSystemPrompt/;
@@ -169,7 +187,7 @@ function classifyPackages(packages: string[]): { force: string[]; fallback: stri
   const force: string[] = [];
   const fallback: string[] = [];
   for (const name of packages) {
-    if (!name.startsWith("npm:") || FORCE_TAIL.includes(name)) continue;
+    if (!name.startsWith("npm:") || forceTail().includes(name)) continue;
     const dir = path.join(HOME, ".pi", "agent", "npm", "node_modules", name.slice(4));
     if (!existsSync(dir)) continue;
     let entries: string[] = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-patch-keeper",
-  "version": "1.2.11",
+  "version": "1.3.1",
   "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",