pi-patch-keeper 1.0.3 → 1.0.4

package/index.ts

@@ -1,161 +1,611 @@
-/** 
- * pi-patch-keeper — extension load-order guard for the pi coding agent.
+/**
+ * patch-keeper —— 补丁自愈与状态检测（pi 扩展，外置 · 模块化 · 抗上游升级）
  *
- * Force-type extensions (those returning { systemPrompt } / forceSystemPrompt)
- * replace the whole system prompt, silently dropping every section written by
- * handlers that run after them. This extension keeps known force-type packages
- * at the tail of settings.json "packages" and reports packages that still follow
- * one of them.
+ * ## 为什么存在
+ * 本机对「别人的东西」的全部改动登记在快照 `05-脚本补丁/PATCH-REGISTRY.md`（唯一权威清单）：
+ * PiDeck app.asar ×3（只检测）、npm 包 ×2（pi-lens / pi-memory，自愈）、PiDeck builtin ×5（双份自愈）、
+ * npm 包注入通道 ×2（pi-memory / tactician 改 section）。
+ * 上游一升级就覆盖，得重跑桌面上的补丁脚本 —— 容易忘。这个扩展把它变成自愈：
+ * 每次 pi 启动时检查一遍，能修的直接修，不能修的（PiDeck 正开着，asar 被锁）明确报出来。
  *
- * Release edition: no machine-specific patch healing (source patches, PiDeck
- * asar, memory fixes) is included.
+ * ## 为什么能修 pi-lens
+ * pi 的资源加载有优先级（dist/core/package-manager.js resourcePrecedenceRank）：
+ *   0/1 project · 2/3 user（本扩展）· 4 package（pi-lens）· 5 builtin
+ * 本扩展是「user 扩展」= rank 2，pi-lens 是「package 扩展」= rank 4，**先加载**。
+ * 所以在 factory 里同步改 dist/index.js，pi-lens 随后 import 到的就是打过补丁的内容 —— 当轮生效。
+ *
+ * ## 边界（刻意的）
+ * - PiDeck asar：**只检测不修**。PiDeck 正开着，文件被锁；且插件无权碰 Electron 主进程。
+ *   检测到未打补丁 → 提示跑 `run-all.cmd` / `launch-pideck.cmd`（桌面 PI脚本补丁/ 不在时用快照副本 05-脚本补丁/）。
+ * - 任何失败都只 notify，不抛错、不影响会话（纪律：不合法就跳过 + 记日志，绝不崩溃）。
  */
-import { existsSync, readFileSync, writeFileSync, copyFileSync } from "node:fs";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { existsSync, readFileSync, writeFileSync, copyFileSync, readdirSync } from "node:fs";
+import { createHash } from "node:crypto";
 import * as os from "node:os";
 import * as path from "node:path";
 
+// 路径从 home / %LOCALAPPDATA% 推导（不写死用户名：换机 / 换用户名 / 复刻包到别的机器仍可用）
 const HOME = os.homedir();
+const LOCALAPPDATA = process.env.LOCALAPPDATA ?? path.join(HOME, "AppData", "Local");
+const PI_LENS = path.join(HOME, ".pi", "agent", "npm", "node_modules", "pi-lens", "dist", "index.js");
+const PI_MEMORY = path.join(HOME, ".pi", "agent", "npm", "node_modules", "pi-memory", "index.ts");
+const ASAR = path.join(LOCALAPPDATA, "Programs", "PiDeck", "resources", "app.asar");
+// 唯一处置入口：快照 05-脚本补丁/（桌面旧目录 PI脚本补丁/ 已不存在，2026-10-15 核实）
+const SNAPSHOT_PATCH_DIR = path.join(HOME, "Desktop", "pi-env-snapshot", "05-脚本补丁");
+// 环境指纹文件（settings 关键字段，用于漂移检测）
+const FINGERPRINT = path.join(HOME, ".pi", "patch-keeper.json");
 const SETTINGS = path.join(HOME, ".pi", "agent", "settings.json");
-const CONFIG = path.join(HOME, ".pi", "patch-keeper.json");
-const NPM_DIR = path.join(HOME, ".pi", "agent", "npm", "node_modules");
-const DEFAULT_TAIL = ["npm:pi-rtk-optimizer", "npm:pi-cache-optimizer"];
+// 手册（注入对齐检测：本轮注入文本的版本行 vs 磁盘版）
+const MANUAL = path.join(HOME, ".pi", "agent", "APPEND_SYSTEM.md");
+
+// PiDeck 内置扩展补丁（本机修改；升级会覆盖，缺失时提示从快照恢复）
+const PIDECK_BUILTIN = path.join(HOME, "AppData", "Roaming", "PiDeck", "builtin-extensions");
+const PIDECK_INSTALL = path.join(process.env.LOCALAPPDATA ?? path.join(HOME, "AppData", "Local"), "Programs", "PiDeck", "resources", "extensions");
+// needle = 本机修复特征串（不是 section 名）：命中即视为已打；升级覆盖后从快照恢复。
+const BUILTIN_PATCHES: Array<{ file: string; install: string; needle: string; name: string }> = [
+  { file: path.join(PIDECK_BUILTIN, "pi-deck-security-gate.ts"), install: path.join(PIDECK_INSTALL, "pi-deck-security-gate.ts"), needle: "越界操作先说明理由", name: "security-gate" },
+  { file: path.join(PIDECK_BUILTIN, "pi-deck-plan-mode.ts"), install: path.join(PIDECK_INSTALL, "pi-deck-plan-mode.ts"), needle: "keepThirdParty", name: "plan-mode" },
+  { file: path.join(PIDECK_BUILTIN, "pi-deck-goal-mode.ts"), install: path.join(PIDECK_INSTALL, "pi-deck-goal-mode.ts"), needle: "roundLine", name: "goal-mode" },
+  { file: path.join(PIDECK_BUILTIN, "pi-deck-trash-guard.ts"), install: path.join(PIDECK_INSTALL, "pi-deck-trash-guard.ts"), needle: "deleteFlagStyle", name: "trash-guard" },
+  { file: path.join(PIDECK_BUILTIN, "pi-deck-session-title.ts"), install: path.join(PIDECK_INSTALL, "pi-deck-session-title.ts"), needle: "TITLE_SOURCE_MARKER_HEAD", name: "session-title" },
+];
+const SNAPSHOT_BUILTIN = path.join(HOME, "Desktop", "pi-env-snapshot", "03-PiDeck", "builtin-extensions");
+const MANUAL_STATE = path.join(HOME, ".pi", "patch-keeper-manual.json");
+/**
+ * 从手册文本里取版本号（标题「自主工作手册」后 200 字符内的第一个 vNN.NN）。
+ * 取不到返回 null（注入文本若不含标题即静默跳过，绝不猜）。
+ */
+function manualVer(text: string): string | null {
+  const i = text.indexOf("自主工作手册");
+  if (i < 0) return null;
+  const m = text.slice(i, i + 200).match(/v(\d+\.\d+)/);
+  return m ? m[1] : null;
+}
+
+// ── pi-lens word index 补丁：两处替换（与 patches/pi-lens-wordindex-patch.js 同源）
+const A1_FROM = "    warmWordIndexes.set(key4, entry);\n  }\n  entry.leases++;";
+const A1_MARK = "if (entry && !entry.index) {";
+const A1_TO = "    warmWordIndexes.set(key4, entry);\n  }\n  if (entry && !entry.index) {\n    const late = deserializeWordIndex(loadProjectSnapshot(key4)?.wordIndex) ?? void 0;\n    if (late?.forward) entry.index = late;\n  }\n  entry.leases++;";
+const A2_FROM = "if (!snapshot.wordIndex && existing.wordIndex && existing.seq === snapshot.seq && (snapshot.incomplete || !existing.incomplete)) {";
+const A2_MARK = "existing.wordIndex && (snapshot.incomplete";
+const A2_TO = "if (!snapshot.wordIndex && existing.wordIndex && (snapshot.incomplete || !existing.incomplete)) {";
+
+
+// ── pi-memory exit summary 空行规范化补丁（幂等；与 pi-memory/index.ts 内已打状态一致）
+const ME_MARK = "normalizeExitSummaryMarkdown";
+const ME_FROM_FN = "function formatExitSummaryEntry(";
+const ME_FROM_RET = 'header, "", summary.trim()].join("\\n");';
+const ME_TO_RET = 'header, "", normalizeExitSummaryMarkdown(summary.trim())].join("\\n");';
+const ME_FN = ['/**', ' * 规范 exit summary 的块级空行（MD022 / MD032：标题 / 列表前后须空行）；代码围栏内不动。', ' */', 'function normalizeExitSummaryMarkdown(text: string): string {', '\tconst lines = text.split(/\\r?\\n/);', '\tconst out: string[] = [];', '\tconst isFence = (l: string) => /^\\s*(\\x60{3,}|~{3,})/.test(l);', '\tconst isHeading = (l: string) => /^#{1,6}\\s/.test(l);', '\tconst isList = (l: string) => /^\\s*(?:[-*+]|\\d+\\.)\\s/.test(l);', '\tlet inFence = false;', '\tfor (const line of lines) {', '\t\tconst fenceLine = isFence(line);', '\t\tif (fenceLine) inFence = !inFence;', '\t\tconst prev = out.length ? out[out.length - 1] : "";', '\t\tif (!fenceLine && !inFence && prev !== "") {', '\t\t\tconst startsBlock = (isHeading(line) || isList(line)) && !(isList(line) && isList(prev));', '\t\t\tconst afterBlock = isHeading(prev) || (isList(prev) && !isList(line));', '\t\t\tif (startsBlock || afterBlock) out.push("");', '\t\t}', '\t\tout.push(line);', '\t}', '\treturn out.join("\\n");', '}'].join("\n");
+const MEM_SECTION_MARK = 'sections["pi_memory"]';
+const MEM_SECTION_ANCHOR = [
+	"\t\treturn {",
+	"\t\t\tsystemPrompt: event.systemPrompt + headerLines.join(\"\\n\"),",
+	"\t\t};",
+].join("\n");
+const MEM_SECTION_BLOCK = [
+	"\t\t// R7：有 sections 的宿主优先写 section —— 返回 systemPrompt 是 force 覆盖，",
+	"\t\t// 会丢弃其后（builtin 组）goal / plan / security 的 section 写入",
+	"\t\t// （2026-10-17 实证：goal 的 Objective 与 Rules 从 system 消失，只剩 Round 消息）。",
+	"\t\tconst sections = (event as { systemPromptOptions?: { sections?: Record<string, string> } }).systemPromptOptions?.sections;",
+	"\t\tif (sections) {",
+	"\t\t\tsections[\"pi_memory\"] = headerLines.join(\"\\n\").replace(/^\\n+/, \"\");",
+	"\t\t\treturn;",
+	"\t\t}",
+	"\t\treturn {",
+	"\t\t\tsystemPrompt: event.systemPrompt + headerLines.join(\"\\n\"),",
+	"\t\t};",
+].join("\n");
+const TACT = path.join(HOME, ".pi", "agent", "npm", "node_modules", "@khanhicetea", "pi-tactician", "src", "index.ts");
+const TACT_MARK = 'sections["tactician"]';
+const TACT_ANCHOR = [
+	"\t\tif (event.systemPrompt.includes(GUIDANCE_MARKER)) return;",
+	"\t\treturn { systemPrompt: `${event.systemPrompt}\\n\\n${TACTICIAN_GUIDANCE}` };",
+].join("\n");
+const TACT_BLOCK = [
+	"\t\t// R7b：有 sections 的宿主写 section（不 force）——force 会让其后 builtin 组",
+	"\t\t// （goal / plan / security）的 section 写入被整组丢弃（2026-10-17 实证）。",
+	"\t\tconst sections = (event as { systemPromptOptions?: { sections?: Record<string, string> } }).systemPromptOptions?.sections;",
+	"\t\tif (sections) {",
+	"\t\t\tsections[\"tactician\"] = TACTICIAN_GUIDANCE;",
+	"\t\t\treturn;",
+	"\t\t}",
+	"\t\tif (event.systemPrompt.includes(GUIDANCE_MARKER)) return;",
+	"\t\treturn { systemPrompt: `${event.systemPrompt}\\n\\n${TACTICIAN_GUIDANCE}` };",
+].join("\n");
+
+/** pi-memory 状态：done / none。 */
+function piMemoryState(src: string): "done" | "none" {
+  return src.includes(ME_MARK) ? "done" : "none";
+}
+
+/** 打/补 pi-memory exit summary 规范化（幂等）。 */
+function healPiMemory(): Result {
+  if (!existsSync(PI_MEMORY)) return { ok: false, detail: "pi-memory/index.ts 不存在（未安装？）" };
+  const src = safeRead(PI_MEMORY);
+  if (src === null) return { ok: false, detail: "读取失败" };
+  if (piMemoryState(src) === "done") return { ok: true, detail: "已是最新（无需动作）" };
+  if (!src.includes(ME_FROM_FN) || !src.includes(ME_FROM_RET)) return { ok: false, detail: "锚点未找到（版本变化？）—— 需人工确认" };
+  let next = src.replace(ME_FROM_RET, ME_TO_RET);
+  next = next.replace(ME_FROM_FN, ME_FN + "\n\n" + ME_FROM_FN);
+  if (!next.includes(ME_MARK) || next === src) return { ok: false, detail: "打补丁失败（结果校验不通过）" };
+  try {
+    const stamp = new Date().toISOString().slice(0, 10).replace(/-/g, "");
+    const bak = `${PI_MEMORY}.bak-exitsummary-${stamp}`;
+    if (!existsSync(bak)) copyFileSync(PI_MEMORY, bak);
+    writeFileSync(PI_MEMORY, next, "utf8");
+  } catch (e) { return { ok: false, detail: `写入失败：${(e as Error).message}` }; }
+  return { ok: true, detail: "已自动修补（exit summary 空行规范化）—— 本轮即生效" };
+}
+/** R7：memory 段改 section（防 force 吞掉其后 builtin 组的 section）。 */
+function healMemorySection(): Result {
+  if (!existsSync(PI_MEMORY)) return { ok: false, detail: "pi-memory/index.ts 不存在（未安装？）" };
+  const src = safeRead(PI_MEMORY);
+  if (src === null) return { ok: false, detail: "读取失败" };
+  if (src.includes(MEM_SECTION_MARK)) return { ok: true, detail: "已是最新（无需动作）" };
+  if (!src.includes(MEM_SECTION_ANCHOR)) return { ok: false, detail: "锚点未找到（版本变化？）—— 需人工确认" };
+  const next = src.replace(MEM_SECTION_ANCHOR, MEM_SECTION_BLOCK);
+  if (!next.includes(MEM_SECTION_MARK) || next === src) return { ok: false, detail: "打补丁失败（结果校验不通过）" };
+  try {
+    const stamp = new Date().toISOString().slice(0, 10).replace(/-/g, "");
+    const bak = `${PI_MEMORY}.bak-memsec-${stamp}`;
+    if (!existsSync(bak)) copyFileSync(PI_MEMORY, bak);
+    writeFileSync(PI_MEMORY, next, "utf8");
+  } catch (e) { return { ok: false, detail: `写入失败：${(e as Error).message}` }; }
+  return { ok: true, detail: "已自动修补（memory 段改 section）—— 重启后生效" };
+}
+/** R7b：tactician 改 section（防 force 吞掉其后 builtin 组的 section）。 */
+function healTactician(): Result {
+  if (!existsSync(TACT)) return { ok: false, detail: "pi-tactician/src/index.ts 不存在（未安装？）" };
+  const src = safeRead(TACT);
+  if (src === null) return { ok: false, detail: "读取失败" };
+  if (src.includes(TACT_MARK)) return { ok: true, detail: "已是最新（无需动作）" };
+  if (!src.includes(TACT_ANCHOR)) return { ok: false, detail: "锚点未找到（版本变化？）—— 需人工确认" };
+  const next = src.replace(TACT_ANCHOR, TACT_BLOCK);
+  if (!next.includes(TACT_MARK) || next === src) return { ok: false, detail: "打补丁失败（结果校验不通过）" };
+  try {
+    const stamp = new Date().toISOString().slice(0, 10).replace(/-/g, "");
+    const bak = `${TACT}.bak-tactician-${stamp}`;
+    if (!existsSync(bak)) copyFileSync(TACT, bak);
+    writeFileSync(TACT, next, "utf8");
+  } catch (e) { return { ok: false, detail: `写入失败：${(e as Error).message}` }; }
+  return { ok: true, detail: "已自动修补（tactician 改 section）—— 重启后生效" };
+}
+// ── PiDeck asar 补丁：只读检测（needle 出现次数）
+const ASAR_CHECKS: Array<{ name: string; needle: string; expected: number }> = [
+  { name: "history-race", needle: "runtime.tab.runtimeGeneration !== runtimeGeneration", expected: 8 },
+  { name: "katex", needle: "singleDollarTextMath: !0", expected: 0 },
+  { name: "noise", needle: "appLogger.warn(\"app\", \"Main window renderer console error\"", expected: 0 },
+];
+
+type Result = { ok: boolean; detail: string };
 
+/** 读文件；失败返回 null（永不抛）。 */
 function safeRead(p: string): string | null {
-	try { return readFileSync(p, "utf8"); } catch { return null; }
+  try { return readFileSync(p, "utf8"); } catch { return null; }
 }
 
-function readJson(p: string): Record<string, unknown> | null {
-	const t = safeRead(p);
-	if (t === null) return null;
-	try { return JSON.parse(t) as Record<string, unknown>; } catch { return null; }
+/** 统计 needle 在原串里的出现次数。 */
+function count(hay: string, needle: string): number {
+  let n = 0, i = 0;
+  while ((i = hay.indexOf(needle, i)) >= 0) { n += 1; i += needle.length; }
+  return n;
 }
 
-function forceTail(): string[] {
-	const c = readJson(CONFIG);
-	const t = c?.forceTail;
-	const list = Array.isArray(t) ? t.filter((x): x is string => typeof x === "string") : DEFAULT_TAIL;
-	return list.length ? list : DEFAULT_TAIL;
+/** pi-lens 状态：both / partial / none / missing。 */
+function piLensState(src: string): { state: "both" | "partial" | "none"; a1: boolean; a2: boolean } {
+  const a1 = src.includes(A1_MARK);
+  const a2 = !src.includes(A2_FROM) && src.includes(A2_MARK);
+  let state: "both" | "partial" | "none" = "none";
+  if (a1 && a2) state = "both";
+  else if (a1 || a2) state = "partial";
+  return { state, a1, a2 };
 }
 
-function packagesOf(): string[] | null {
-	const s = readJson(SETTINGS);
-	const p = s?.packages;
-	return Array.isArray(p) ? p.filter((x): x is string => typeof x === "string") : null;
+/** 只在未打或半打时修补 pi-lens（幂等）。 */
+function healPiLens(): Result {
+  if (!existsSync(PI_LENS)) return { ok: false, detail: "pi-lens dist 不存在（未安装？）" };
+  const src = safeRead(PI_LENS);
+  if (src === null) return { ok: false, detail: "读取失败" };
+  const { state, a1, a2 } = piLensState(src);
+  if (state === "both") return { ok: true, detail: "已是最新（无需动作）" };
+  let next = src;
+  // 半打状态先还原，再整体重打（避免只打一半造成新的不一致）
+  if (a2 && !a1) next = next.replace(A2_TO, A2_FROM); // 半打：先把 B 还原，再由下面两步整体重打
+  if (!next.includes(A1_MARK)) next = next.replace(A1_FROM, A1_TO);
+  if (next.includes(A2_FROM)) next = next.replace(A2_FROM, A2_TO);
+  const after = piLensState(next);
+  if (after.state !== "both") return { ok: false, detail: `打补丁失败（结果 ${after.state}，锚点可能已随版本变化）` };
+  try {
+    const stamp = new Date().toISOString().slice(0, 10).replace(/-/g, "");
+    const bak = `${PI_LENS}.bak-wordindex-${stamp}`;
+    if (!existsSync(bak)) copyFileSync(PI_LENS, bak);
+    writeFileSync(PI_LENS, next, "utf8");
+  } catch (e) { return { ok: false, detail: `写入失败：${(e as Error).message}` }; }
+  return { ok: true, detail: `已自动修补（原状态 ${state}）—— 本轮即生效` };
+}
+
+
+/** 记忆文件格式规范化（压连续空行 + 单尾换行；围栏内不动）。 */
+function normMd(txt: string): string {
+  const lines = txt.split(/\r?\n/);
+  const out: string[] = [];
+  let inFence = false;
+  for (const line of lines) {
+    const isF = /^\s*(?:`{3,}|~{3,})/.test(line);
+    if (isF) inFence = !inFence;
+    if (!inFence && line.trim() === "" && out.length > 0 && out[out.length - 1].trim() === "") continue;
+    out.push(line);
+  }
+  while (out.length > 0 && out[out.length - 1].trim() === "") out.pop();
+  return out.join("\n") + "\n";
 }
 
-/** Problems in the current load order (empty = OK). */
+/** 第 3 处自愈：memory_write 每次写入都会引入 MD012/MD047（同日复发 3 次后机制化）——启动即规范。 */
+function healMemoryFormat(): Result {
+  try {
+    const dir = path.join(HOME, ".pi", "agent", "memory");
+    if (!existsSync(dir)) return { ok: true, detail: "memory 目录不存在（跳过）" };
+    let fixed = 0;
+    const walk = (d: string): void => {
+      for (const e of readdirSync(d, { withFileTypes: true })) {
+        const p = path.join(d, e.name);
+        if (e.isDirectory()) { if (e.name !== ".git") walk(p); continue; }
+        if (!e.name.endsWith(".md")) continue;
+        const txt = safeRead(p);
+        if (txt === null) continue;
+        const norm = normMd(txt);
+        if (norm !== txt) { try { writeFileSync(p, norm, "utf8"); fixed += 1; } catch { /* 静默 */ } }
+      }
+    };
+    walk(dir);
+    return { ok: true, detail: fixed > 0 ? `已规范化 ${fixed} 个记忆文件（空行 / 尾换行）` : "记忆格式无需动作" };
+  } catch (e) { return { ok: false, detail: (e as Error).message }; }
+}
+/** PiDeck asar：只读检测，返回未打补丁的项名。 */
+let asarOk = false;
+/** 未打补丁时的处置提示（纯函数，便于单测）。 */
+function patchTip(lines: string[]): string {
+  if (!lines.some((l) => l.includes("未打") || l.includes("半打"))) return "";
+  const dir = existsSync(SNAPSHOT_PATCH_DIR) ? SNAPSHOT_PATCH_DIR : "pi-env-snapshot/05-脚本补丁/（也未找到）";
+  return ` → PiDeck 补丁需退出 PiDeck 后重跑补丁脚本（快照副本：${dir}；或用其中的 launch-pideck.cmd 启动 PiDeck 时自动重打）`;
+}
+
+
+function checkAsar(): { ran: boolean; missing: string[]; detail: string } {
+  if (asarOk) return { ran: true, missing: [], detail: "三个补丁都在" };
+  if (!existsSync(ASAR)) return { ran: false, missing: [], detail: "app.asar 不存在" };
+  let buf: Buffer;
+  try { buf = readFileSync(ASAR); } catch (e) { return { ran: false, missing: [], detail: `读取失败：${(e as NodeJS.ErrnoException).code ?? (e as Error).message}` }; }
+  const txt = buf.toString("utf8");
+  const missing: string[] = [];
+  for (const c of ASAR_CHECKS) {
+    const n = count(txt, c.needle);
+    if (n !== c.expected) missing.push(`${c.name}(=${n}, 期望 ${c.expected})`);
+  }
+  if (!missing.length) asarOk = true; // 只在通过时缓存：缺失时每次都实测，便于打完补丁后立刻复检
+  return { ran: true, missing, detail: missing.length ? `未打补丁：${missing.join(" ")}` : "三个补丁都在" };
+}
+
+/** 汇总报告（给命令与启动提示共用）。 */
+// ── 环境指纹：settings 关键字段漂移 → 提示「手册 / 验证结论可能过期」
+function fingerprint(): Record<string, string[]> | null {
+  const txt = safeRead(SETTINGS);
+  if (txt === null) return null;
+  try {
+    const s = JSON.parse(txt) as Record<string, unknown>;
+    return {
+      packages: (s.packages as string[]) ?? [],
+      defaultTools: (s.defaultTools as string[]) ?? [],
+      enabledModels: (s.enabledModels as string[]) ?? [],
+      extensions: (s.extensions as string[]) ?? [],
+      codemode: [(s.codemode as { mode?: string })?.mode ?? "?"],
+    };
+  } catch { return null; }
+}
+/** 与上次指纹对比；变化摘要数组（无变化为空）。对比后写回新指纹。 */
+function fingerprintDrift(): string[] {
+  const cur = fingerprint();
+  if (cur === null) return [];
+  let prev: Record<string, string[]> | null = null;
+  const prevRaw = safeRead(FINGERPRINT);
+  if (prevRaw) { try { prev = JSON.parse(prevRaw) as Record<string, string[]>; } catch { prev = null; } }
+  try { writeFileSync(FINGERPRINT, JSON.stringify(cur, null, 1), "utf8"); } catch { /* 静默 */ }
+  if (prev === null) return [];
+  const out: string[] = [];
+  for (const k of ["packages", "defaultTools", "enabledModels", "extensions", "codemode"] as const) {
+    const a = prev[k] ?? [];
+    const b = cur[k];
+    const added = b.filter((x) => !a.includes(x)).length;
+    const removed = a.filter((x) => !b.includes(x)).length;
+    if (added || removed) out.push(`${k} ${a.length}→${b.length}${added ? ` +${added}` : ""}${removed ? ` -${removed}` : ""}`);
+  }
+  return out;
+}
+
+/** codemode 单点一致性：禁 builtin:codemode ⟺ packages 含 pi-codemode-guard（启动检查 / /patch-keeper 共用）。 */
+export function consistencyCheck(exts: string[], pkgs: string[]): string[] {
+  const disabled = (exts ?? []).includes("-builtin:codemode");
+  const guard = (pkgs ?? []).includes("npm:pi-codemode-guard");
+  if (disabled && !guard) return ["codemode 单点断裂：已禁 builtin:codemode 但 packages 无 pi-codemode-guard —— codemode 工具将不可用"];
+  if (!disabled && guard) return ["codemode 单点异常：pi-codemode-guard 在但未禁 builtin:codemode —— 双实现风险"];
+  return [];
+}
+
+
+function restoreBuiltinPatches(): string | null {
+  const out: string[] = [];
+  for (const bp of BUILTIN_PATCHES) {
+    for (const target of [bp.install, bp.file]) {
+      if (!existsSync(target)) continue; // 未装 PiDeck / 路径不同：跳过，不算缺失
+      const cur = safeRead(target);
+      if (cur !== null && cur.includes(bp.needle)) continue;
+      const snap = path.join(SNAPSHOT_BUILTIN, path.basename(target));
+      if (!existsSync(snap)) { out.push(`${bp.name}: 缺补丁且快照无副本`); continue; }
+      try {
+        if (cur !== null) copyFileSync(target, `${target}.bak-restore-${Date.now()}`);
+        copyFileSync(snap, target);
+        out.push(`${bp.name}（${target === bp.install ? "安装目录" : "用户层"}）: 已从快照恢复`);
+      } catch (e) { out.push(`${bp.name}: 恢复失败（${(e as Error).message}）`); }
+    }
+  }
+  return out.length ? out.join("；") : null;
+}
+
+/** 手册内容漂移：版本号未变但正文变了（只比版本号会漏）。 */
+function manualDrift(): string | null {
+  const disk = safeRead(MANUAL);
+  if (disk === null) return null;
+  const ver = manualVer(disk) ?? "";
+  const sig = createHash("sha256").update(disk).digest("hex").slice(0, 12);
+  let prev: { ver?: string; sig?: string } | null = null;
+  const raw = safeRead(MANUAL_STATE);
+  if (raw) { try { prev = JSON.parse(raw); } catch { prev = null; } }
+  try { writeFileSync(MANUAL_STATE, JSON.stringify({ ver, sig })); } catch { /* ignore */ }
+  if (prev && prev.ver === ver && prev.sig !== sig) return `手册内容已变但版本号未升（${ver}）—— bump-manual 或撤销未登记改动`;
+  return null;
+}
+// 已知盲区：caveman-think-zh 是 user 扩展（不在 packages 数组），它在检测到原版英文段时
+// 也会 force；FORCE_TAIL 覆盖不到，触发时本扩展看不到。
+/** force/条件 force 型必须排在 packages 末尾（其后 section 写入会被静默丢弃）。触发概率升序：rtk → cache-optimizer。 */
+const FORCE_TAIL = ["npm:pi-rtk-optimizer", "npm:pi-cache-optimizer"];
 export function forceOrderIssues(packages: string[]): string[] {
-	const out: string[] = [];
-	const tail = forceTail();
-	const present = tail.filter((n) => packages.includes(n));
-	if (!present.length) return out;
-	const minForce = Math.min(...present.map((n) => packages.indexOf(n)));
-	const later = packages.slice(minForce + 1).filter((n) => !tail.includes(n));
-	if (later.length) out.push(
-		"force-type package is followed by " + later.length + " package(s) (" + later.slice(0, 2).join(" / ") +
-		") — their sections are dropped; move " + tail.join(" / ") + " to the end");
-	if (tail.every((n) => packages.includes(n)) && packages.indexOf(tail[0]) > packages.indexOf(tail[1]))
-		out.push("force order should be " + tail.join(" -> ") + " (the most likely trigger goes last)");
-	return out;
-}
-
-/** Reordered packages, or null when already correct. */
+  const out: string[] = [];
+  const idx = (n: string) => packages.indexOf(n);
+  const present = FORCE_TAIL.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（最可能触发者最后）");
+  return out;
+}
+/** 把 FORCE_TAIL 成员移到末尾（其余相对顺序不变）；已正确时返回 null。 */
 export function normalizeForceOrder(packages: string[]): string[] | null {
-	const tail = forceTail();
-	const present = tail.filter((n) => packages.includes(n));
-	if (!present.length) return null;
-	const next = [...packages.filter((n) => !tail.includes(n)), ...present];
-	return next.join("\n") === packages.join("\n") ? null : next;
+  const present = FORCE_TAIL.filter((n) => packages.includes(n));
+  if (!present.length) return null;
+  const rest = packages.filter((n) => !FORCE_TAIL.includes(n));
+  const next = [...rest, ...present];
+  return next.join("\n") === packages.join("\n") ? null : next;
 }
 
-/** Repair settings.json order; backs up first. Returns a message or null. */
+/** 自动修复 settings.json 的 force 顺序；无变化返回 null。先备份再写。 */
 function fixForceOrder(): string | null {
-	const s = readJson(SETTINGS);
-	if (!s) return null;
-	const packages = Array.isArray(s.packages) ? (s.packages as string[]) : [];
-	const next = normalizeForceOrder(packages);
-	if (!next) return null;
-	try {
-		copyFileSync(SETTINGS, SETTINGS + ".bak-force-order-" + Date.now());
-		s.packages = next;
-		writeFileSync(SETTINGS, JSON.stringify(s, null, 2), "utf8");
-	} catch (e) { return "force order repair failed: " + (e as Error).message; }
-	return "force order repaired: " + forceTail().filter((n) => next.includes(n)).join(" / ") + " moved to the end";
+  const txt = safeRead(SETTINGS);
+  if (txt === null) return null;
+  let s: Record<string, unknown>;
+  try { s = JSON.parse(txt) as Record<string, unknown>; } catch { return "force 顺序自动修复失败：settings.json 解析失败"; }
+  const packages = (s.packages as string[] | undefined) ?? [];
+  const next = normalizeForceOrder(packages);
+  if (!next) return null;
+  try {
+    copyFileSync(SETTINGS, `${SETTINGS}.bak-force-order-${Date.now()}`);
+    s.packages = next;
+    writeFileSync(SETTINGS, JSON.stringify(s, null, 2), "utf8");
+  } catch (e) { return `force 顺序自动修复失败：${(e as Error).message}`; }
+  return `force 顺序已自动修复：${FORCE_TAIL.filter((n) => next.includes(n)).join(" / ")} 移到 packages 末尾`;
 }
-
+/** 静态扫描：packages 中疑似 force 型扩展（入口源码含 return { systemPrompt } / forceSystemPrompt）。 */
 const FORCE_RE = /return\s*\{\s*systemPrompt|forceSystemPrompt/;
 const SECTION_RE = /sections\s*(\[|\.)/;
 
-/** Classify static force candidates: sections-first means a legacy-host fallback. */
-function classify(packages: string[]): { force: string[]; fallback: string[] } {
-	const force: string[] = [];
-	const fallback: string[] = [];
-	const tail = forceTail();
-	for (const name of packages) {
-		if (!name.startsWith("npm:") || tail.includes(name)) continue;
-		const dir = path.join(NPM_DIR, name.slice(4));
-		if (!existsSync(dir)) continue;
-		let entries: string[] = [];
-		const pj = readJson(path.join(dir, "package.json")) as { pi?: { extensions?: unknown } } | null;
-		const ex = pj?.pi?.extensions;
-		entries = Array.isArray(ex) ? ex.filter((x): x is string => typeof x === "string") : [];
-		for (const rel of entries.slice(0, 3)) {
-			const src = safeRead(path.join(dir, rel));
-			if (src === null) continue;
-			const i = src.indexOf("before_agent_start");
-			if (i < 0) continue;
-			const body = src.slice(i, i + 4000);
-			const fi = body.search(FORCE_RE);
-			if (fi < 0) continue;
-			const si = body.search(SECTION_RE);
-			if (si >= 0 && si < fi) fallback.push(name); else force.push(name);
-			break;
-		}
-	}
-	return { force, fallback };
+/** 分类：先写 section、只有旧宿主才 force 的算兼容兜底，不算疑似无条件 force。 */
+function classifyPackages(packages: string[]): { force: string[]; fallback: string[] } {
+  const force: string[] = [];
+  const fallback: string[] = [];
+  for (const name of packages) {
+    if (!name.startsWith("npm:") || FORCE_TAIL.includes(name)) continue;
+    const dir = path.join(HOME, ".pi", "agent", "npm", "node_modules", name.slice(4));
+    if (!existsSync(dir)) continue;
+    let entries: string[] = [];
+    try {
+      const pj = JSON.parse(safeRead(path.join(dir, "package.json")) ?? "{}") as { pi?: { extensions?: unknown } };
+      const ex = pj.pi?.extensions;
+      entries = Array.isArray(ex) ? ex.filter((x): x is string => typeof x === "string") : [];
+    } catch { continue; }
+    for (const rel of entries.slice(0, 3)) {
+      const src = safeRead(path.join(dir, rel));
+      if (src === null) continue;
+      const i = src.indexOf("before_agent_start");
+      if (i < 0) continue;
+      const body = src.slice(i, i + 4000);
+      const fi = body.search(FORCE_RE);
+      if (fi < 0) continue;
+      const si = body.search(SECTION_RE);
+      if (si >= 0 && si < fi) fallback.push(name); else force.push(name);
+      break;
+    }
+  }
+  return { force, fallback };
+}
+
+/** 疑似无条件 force（会静默吞掉其后 section）。 */
+export function scanForcePackages(packages: string[]): string[] {
+  return classifyPackages(packages).force;
+}
+
+/** 兼容兜底（section 优先，旧宿主才 force）。 */
+export function scanForceFallbacks(packages: string[]): string[] {
+  return classifyPackages(packages).fallback;
 }
 
 function report(): string[] {
-	const lines: string[] = [];
-	const pk = packagesOf();
-	if (!pk) { lines.push("settings: cannot read " + SETTINGS); return lines; }
-	const issues = forceOrderIssues(pk);
-	lines.push("force order: " + (issues.length ? issues[0] : "OK"));
-	const tail = forceTail();
-	lines.push("force packages: " + tail.filter((n) => pk.includes(n)).join(" / ") + (tail.some((n) => !pk.includes(n)) ? " (partial)" : ""));
-	const { force, fallback } = classify(pk);
-	lines.push("static scan: " + (force.length ? "force-like " + force.join(" / ") : "none"));
-	lines.push("fallbacks: " + (fallback.length ? fallback.join(" / ") : "none"));
-	return lines;
+  const lines: string[] = [];
+  const lensSrc = safeRead(PI_LENS);
+  if (lensSrc === null) lines.push("pi-lens : 读不到 dist/index.js");
+  else {
+    const st = piLensState(lensSrc);
+    let label = `半打（A=${st.a1} B=${st.a2}）`;
+    if (st.state === "both") label = "已打（A+B）";
+    else if (st.state === "none") label = "未打";
+    lines.push(`pi-lens : ${label}`);
+  }
+  const memSrc = safeRead(PI_MEMORY);
+  if (memSrc === null) lines.push("pi-memory: 读不到 index.ts");
+  else lines.push(`pi-memory: ${memSrc.includes(ME_MARK) ? "已打（exit summary 空行规范化）" : "未打"} · ${memSrc.includes(MEM_SECTION_MARK) ? "已打（section 优先）" : "未打（section 优先）"}`);
+  const tactSrc = safeRead(TACT);
+  lines.push(`tactician: ${tactSrc === null ? "读不到" : tactSrc.includes(TACT_MARK) ? "已打（section 优先）" : "未打（section 优先）"}`);
+  const asar = checkAsar();
+  lines.push(`PiDeck  : ${asar.detail}`);
+  for (const bp of BUILTIN_PATCHES) {
+    const st = (p: string): string => { const src = safeRead(p); return src === null ? "无" : src.includes(bp.needle) ? "已打" : "未打"; };
+    lines.push(`builtin  : ${bp.name} 生效版=${st(bp.install)} 用户层=${st(bp.file)}`);
+  }
+  const fp = fingerprint();
+  const cm = fp ? consistencyCheck(fp.extensions, fp.packages) : [];
+  let cmLabel = "读不到 settings";
+  if (fp) cmLabel = cm.length ? cm[0] : "单点一致";
+  lines.push(`codemode : ${cmLabel}`);
+  const fo = fp ? forceOrderIssues(fp.packages) : [];
+  lines.push(`force序  : ${fp ? (fo.length ? fo[0] : "OK") : "读不到 settings"}`);
+  const fe = fp ? scanForcePackages(fp.packages) : [];
+  lines.push(`forceExt: ${fp ? (fe.length ? "疑似 " + fe.join(" / ") : "无（静态扫描）") : "读不到 settings"}`);
+  const fb = fp ? scanForceFallbacks(fp.packages) : [];
+  lines.push(`force兜底: ${fp ? (fb.length ? fb.join(" / ") : "无") : "读不到 settings"}`);
+  return lines;
 }
 
 export default function (pi: ExtensionAPI) {
-	pi.registerCommand("patch-keeper", {
-		description: "Show / repair extension load order (force-type packages must load last)",
-		handler: async (args: string, ctx: ExtensionContext) => {
-			const arg = (args || "").trim().toLowerCase();
-			if (arg === "fix") {
-				const r = fixForceOrder();
-				ctx.ui.notify(r ?? "patch-keeper: load order already correct", "info");
-				return;
-			}
-			ctx.ui.notify("patch-keeper\n" + report().join("\n"), "info");
-		},
-	});
-
-	pi.on("session_start", async (_event, ctx: ExtensionContext) => {
-		try {
-			const pk = packagesOf();
-			if (!pk) return;
-			const msgs: string[] = [];
-			for (const x of forceOrderIssues(pk)) msgs.push("patch-keeper: " + x);
-			const fixed = fixForceOrder();
-			if (fixed) msgs.push("patch-keeper: " + fixed);
-			const { force } = classify(pk);
-			const tail = forceTail();
-			const mid = force.filter((n) => pk.indexOf(n) < pk.length - 1 && !tail.includes(n));
-			if (mid.length) msgs.push("patch-keeper: force-like package not last: " + mid.join(" / ") + " — move it to the end of packages");
-			for (const m of msgs) ctx.ui.notify(m, "warning");
-		} catch { /* detection must never break the session */ }
-	});
-}
+  // 启动自愈：factory 是同步上下文，此时 pi-lens（rank 4）尚未加载。
+  let healNote: string | null = null;
+  try {
+    const r = healPiLens();
+    if (!r.ok) healNote = `patch-keeper: pi-lens 自愈失败 —— ${r.detail}`;
+  } catch (e) { healNote = `patch-keeper: pi-lens 自愈异常 —— ${(e as Error).message}`; }
+  try {
+    const r = healPiMemory();
+    if (!r.ok) healNote = (healNote ? healNote + "\n" : "") + `patch-keeper: pi-memory 自愈失败 —— ${r.detail}`;
+  } catch (e) { healNote = (healNote ? healNote + "\n" : "") + `patch-keeper: pi-memory 自愈异常 —— ${(e as Error).message}`; }
+  try {
+    const r = healMemorySection();
+    if (!r.ok) healNote = (healNote ? healNote + "\n" : "") + `patch-keeper: pi-memory section 自愈失败 —— ${r.detail}`;
+  } catch (e) { healNote = (healNote ? healNote + "\n" : "") + `patch-keeper: pi-memory section 自愈异常 —— ${(e as Error).message}`; }
+  try {
+    const rt = healTactician();
+    if (!rt.ok) healNote = (healNote ? healNote + "\n" : "") + `patch-keeper: tactician section 自愈失败 —— ${rt.detail}`;
+  } catch (e) { healNote = (healNote ? healNote + "\n" : "") + `patch-keeper: tactician section 自愈异常 —— ${(e as Error).message}`; }
+  try {
+    const r = healMemoryFormat();
+    if (!r.ok) healNote = (healNote ? healNote + "\n" : "") + `patch-keeper: 记忆格式自愈失败 —— ${r.detail}`;
+  } catch (e) { healNote = (healNote ? healNote + "\n" : "") + `patch-keeper: 记忆格式自愈异常 —— ${(e as Error).message}`; }
+
+  pi.registerCommand("patch-keeper", {
+    description: "查看 / 自愈本机源码补丁状态（PiDeck asar ×3、pi-lens ×1、pi-memory ×1）",
+    handler: async (args: string, ctx: ExtensionContext) => {
+      const arg = (args || "").trim().toLowerCase();
+      if (arg === "fix") {
+        const r = healPiLens();
+        ctx.ui.notify(`pi-lens: ${r.detail}`, r.ok ? "info" : "error");
+
+        const r2 = healPiMemory();
+        ctx.ui.notify(`pi-memory: ${r2.detail}`, r2.ok ? "info" : "error");
+        const r3 = healMemorySection();
+        ctx.ui.notify(`pi-memory section: ${r3.detail}`, r3.ok ? "info" : "error");
+        const r4 = healTactician();
+        ctx.ui.notify(`tactician section: ${r4.detail}`, r4.ok ? "info" : "error");
+        const rForce = fixForceOrder();
+        if (rForce) ctx.ui.notify(`patch-keeper: ${rForce}`, "info");
+        const rb = restoreBuiltinPatches();
+        if (rb) ctx.ui.notify(`patch-keeper: ${rb}`, "warning");
+        return;
+      }
+      const lines = report();
+      const tip = patchTip(lines);
+      ctx.ui.notify(`补丁状态\n${lines.join("\n")}${tip}`, "info");
+    },
+  });
+
+  // 启动提示：只在「PiDeck 补丁缺失」时出声（pi-lens 已自动修好，不打扰）
+  pi.on("session_start", async (_event, ctx: ExtensionContext) => {
+    try {
+      const asar = checkAsar();
+      const msgs: string[] = [];
+      const drift = fingerprintDrift();
+      const forceFix = fixForceOrder();
+      const fp = fingerprint();
+      const cm = fp ? consistencyCheck(fp.extensions, fp.packages) : [];
+      for (const x of cm) msgs.push("patch-keeper: " + x);
+      if (forceFix) msgs.push("patch-keeper: " + forceFix);
+      else if (fp) for (const x of forceOrderIssues(fp.packages)) msgs.push("patch-keeper: " + x);
+      if (fp) {
+        const fe = scanForcePackages(fp.packages);
+        const mid = fe.filter((n) => fp.packages.indexOf(n) < fp.packages.length - 1);
+        if (mid.length) msgs.push("patch-keeper: 疑似 force 型扩展不在末尾（其后的 section 可能被静默丢弃）：" + mid.join(" / ") + " —— 核源码后移到 packages 末尾");
+      }
+      if (drift.length) msgs.push(`patch-keeper: 环境指纹已变（${drift.join("；")}）—— 手册 / 上轮验证结论可能过期，按 08-台账核对纪律逐项重验`);
+      if (asar.ran && asar.missing.length) {
+        msgs.push(`patch-keeper: PiDeck 补丁缺失 —— ${asar.detail}`);
+        msgs.push(`关闭 PiDeck 后重跑补丁脚本（快照 ${SNAPSHOT_PATCH_DIR}；或用其中的 launch-pideck.cmd 启动 PiDeck 时自动重打）`);
+      }
+      for (const bp of BUILTIN_PATCHES) {
+        const missing = [bp.install, bp.file].filter((p: string) => { const src = safeRead(p); return src !== null && !src.includes(bp.needle); });
+        if (missing.length) {
+          const where = missing.length === 2 ? "两处" : missing[0] === bp.install ? "安装目录（生效版）" : "用户层";
+          msgs.push(`patch-keeper: PiDeck 内置扩展补丁缺失（${bp.name}，${where}）—— 升级覆盖？从快照 03-PiDeck/builtin-extensions 恢复`);
+        }
+      }
+      {
+        const memSrc2 = safeRead(PI_MEMORY);
+        if (memSrc2 !== null && !memSrc2.includes(MEM_SECTION_MARK)) msgs.push("patch-keeper: pi-memory 未打 section 优先补丁 —— goal / plan / security 的 section 会被 force 吞掉，建议 /patch-keeper fix");
+      }
+      {
+        const tactSrc2 = safeRead(TACT);
+        if (tactSrc2 !== null && !tactSrc2.includes(TACT_MARK)) msgs.push("patch-keeper: tactician 未打 section 优先补丁 —— 会 force 吞掉其后的 section（goal / plan / security），建议 /patch-keeper fix");
+      }
+      const md = manualDrift();
+      if (md) msgs.push(`patch-keeper: ${md}`);
+      if (healNote) msgs.push(healNote);
+      for (const m of msgs) ctx.ui.notify(m, "warning");
+    } catch { /* 静默：检测不该影响会话 */ }
+  });
+
+  // 注入对齐（手册 §2 纪律区）：注入的是宿主上次读取的文本，可能与磁盘版不同步。每轮比对一次，不一致时提示一次。
+  // 纪律：**绝不返回 systemPrompt** —— 返回即 forceSystemPrompt 覆盖式替换，会静默丢弃其后所有 section 的修改。
+  let lastPair = "";
+  pi.on("before_agent_start", async (event, ctx: ExtensionContext) => {
+    try {
+      const injected = String((event as { systemPrompt?: string } | undefined)?.systemPrompt ?? "");
+      const vi = manualVer(injected);
+      const disk = safeRead(MANUAL);
+      const vd = disk === null ? null : manualVer(disk);
+      if (!vi || !vd) return undefined;
+      const pair = vi + "|" + vd;
+      if (vi === vd || pair === lastPair) return undefined;
+      lastPair = pair;
+      ctx.ui.notify(`注入对齐：注入 v${vi} ≠ 磁盘 v${vd}（观察者 = 磁盘版）→ 判据：注入版不可作判断依据；动作：读回全文执行，重启后自愈`, "warning");
+      // 回灌四律②：用户已收到通知；模型也需要知道，否则「以磁盘版执行」停在用户侧。
+      try {
+        (pi as unknown as { sendMessage?: (m: unknown, o?: unknown) => void }).sendMessage?.(
+          {
+            customType: "patch-keeper",
+            content: `注入对齐：注入 v${vi} ≠ 磁盘 v${vd}（观察者 = 磁盘版）→ 注入版不可作判断依据；动作：读回 APPEND_SYSTEM.md 全文后执行，重启后自愈。`,
+            display: false,
+          },
+          { deliverAs: "nextTurn" },
+        );
+      } catch { /* 静默：回灌失败不影响会话 */ }
+    } catch { /* 静默：检测不该影响会话 */ }
+    return undefined;
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-patch-keeper",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Guards extension load order so later sections are not silently dropped.",
   "type": "module",
   "license": "MIT",
@@ -22,5 +22,6 @@
   ],
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"
-  }
+  },
+  "author": "15066212pp"
 }