pi-patch-keeper 1.0.4 → 1.0.5

package/README.en.md

@@ -1,43 +1,45 @@
 # pi-patch-keeper — extension load-order guard (pi extension)
 
-Stops "force-type" extensions from silently dropping every later section.
+Prevents "force-typed" extensions from silently swallowing every section written after them.
 
-## Features
+## Why it exists
 
-- Checks `packages` order in `~/.pi/agent/settings.json` at startup.
-- Statically scans npm extension sources for unconditional `return { systemPrompt }` / `forceSystemPrompt`.
-- Moves known force-type packages to the end of `packages` (settings backed up first).
-- Speaks only when something is wrong; `/patch-keeper` reports, `/patch-keeper fix` repairs.
-- This release contains no machine-specific patch healing (source patches, PiDeck asar, etc.).
+`before_agent_start` runs extensions in order. An extension that returns `{ systemPrompt }` (or sets `forceSystemPrompt`) performs a **full replacement**, so every later extension's `sections` write is discarded — with no error. The symptom looks like "this extension is installed but has no effect".
 
-## Defaults
-
-| Item | Default | Note |
-| --- | --- | --- |
-| Force-type packages | `npm:pi-rtk-optimizer`, `npm:pi-cache-optimizer` | override via `forceTail` |
-| Auto repair | on | backup `settings.json.bak-force-order-*` |
-| Startup notice | only on issue | silent when clean |
-| Scope | `npm:` packages | local path packages are skipped |
+## What it does
 
-## Install
+- On startup, checks the order of `packages` in `~/.pi/agent/settings.json`: known force-typed extensions must sit at the end.
+- Statically scans installed npm extension entry files and separates:
+  - **unconditional force** (`return { systemPrompt }` / `forceSystemPrompt`) → must be last;
+  - **sections-first with legacy fallback** → report only, no move suggested.
+- Records a fingerprint of key settings fields and warns when it changes (earlier conclusions may be stale).
+- `codemode` single-point check: disabling `builtin:codemode` requires a replacement, and vice versa.
+- Silent when everything is fine.
 
-```bash
-pi install npm:pi-patch-keeper@1.0.0
-pi install ./pi-patch-keeper
-```
+## Commands
 
-## Config
+| Command | Effect |
+| --- | --- |
+| `/patch-keeper` | Show order, suspected force packages, fallback packages, codemode status |
+| `/patch-keeper fix` | Move known force-typed packages to the end (backup written first) |
 
-```json
-{ "forceTail": ["npm:pi-rtk-optimizer", "npm:pi-cache-optimizer"] }
-```
+## Defaults
 
-## How it works
+| Key | Default |
+| --- | --- |
+| `forceTail` | `npm:pi-rtk-optimizer`, `npm:pi-cache-optimizer` |
+| Auto-fix | on (order only, backup first) |
+| Notify | only on problems |
+| Scope | `npm:` packages |
 
-- Reads each npm package's `pi.extensions` entry and compares where sections and force appear: sections first means a compatibility fallback, not an unconditional force.
-- Reports when any package still follows a force-type package.
+Optional config: `~/.pi/patch-keeper-state.json`
 
 ## Limits
 
-- Only npm packages can be inspected.
-- Reorders loading; never edits package code.
+- Detects static forms only; dynamic `systemPrompt` construction is not detected.
+- Local-path packages are skipped.
+- Unknown force-typed extensions must be added to `forceTail` manually.
+
+## License
+
+MIT.

package/README.md

@@ -4,44 +4,50 @@
 
 ## 来源与借鉴
 
-原创，无上游实现。设计灵感来自本机长期维护 PiDeck / pi 补丁的实践：补丁会被升级覆盖，故需要启动时自检与自愈。
+原创，无上游实现。动机来自一个反复出现的症状：某个扩展明明装了、section 也写了，却没出现在 system prompt 里——根因是它前面有扩展 `return { systemPrompt }`，覆盖式替换把后续写入全丢了，而且不报错。
 
 ## 功能
 
-- 启动时检查 `~/.pi/agent/settings.json` 的 `packages` 顺序。
-- 静态扫描 npm 扩展源码，识别无条件 `return { systemPrompt }` / `forceSystemPrompt` 的包。
-- 已知 force 型包自动移到 `packages` 末尾（先备份 settings）。
-- 启动时只在发现问题时提示；`/patch-keeper` 随时查看状态，`/patch-keeper fix` 手动修复。
-- 发布版不含任何本机补丁自愈逻辑（源码补丁、PiDeck asar 等已剥离）。
+- 启动时检查 `~/.pi/agent/settings.json` 的 `packages` 顺序：已知 force 型必须在末尾。
+- 静态扫描已装 npm 扩展的入口源码，区分两类：
+  - **无条件 force**（`return { systemPrompt }` 或 `forceSystemPrompt`）→ 必须排在末尾；
+  - **section 优先 + 旧宿主兜底**（先写 sections，旧宿主才 force）→ 只提示，不建议移动。
+- 记录 settings 关键字段指纹（packages / defaultTools / enabledModels / extensions / codemode），变化时提示「此前的结论可能过期」。
+- codemode 单点检查：禁用 `builtin:codemode` 时必须有替代实现，反之亦然（双实现或单点断裂都会报）。
+- 只在发现问题时提示；命令随时查看状态。
+
+## 命令
+
+| 命令 | 作用 |
+| --- | --- |
+| `/patch-keeper` | 查看顺序、疑似 force 包、兜底包、codemode 单点状态 |
+| `/patch-keeper fix` | 把已知 force 型移到 `packages` 末尾（写前备份 `settings.json.bak-force-order-*`） |
 
 ## 默认配置
 
 | 项 | 默认 | 说明 |
 | --- | --- | --- |
-| force 型包 | `npm:pi-rtk-optimizer`, `npm:pi-cache-optimizer` | `~/.pi/patch-keeper.json` 的 `forceTail` 可覆盖 |
-| 自动修复顺序 | 开 | 写前备份 `settings.json.bak-force-order-*` |
-| 启动提示 | 仅异常时 | 无问题不打扰 |
+| `forceTail` | `npm:pi-rtk-optimizer`, `npm:pi-cache-optimizer` | 已知无条件 force 型；触发概率升序 |
+| 自动修复 | 开 | 仅调整顺序，写前备份 |
+| 提示时机 | 仅异常 | 无问题零输出 |
 | 检测范围 | `npm:` 包 | 本地路径包跳过 |
 
-## 安装
-
-```bash
-pi install npm:pi-patch-keeper
-pi install ./pi-patch-keeper
-```
-
-## 配置示例
+配置文件（可选）：`~/.pi/patch-keeper-state.json`
 
 ```json
 { "forceTail": ["npm:pi-rtk-optimizer", "npm:pi-cache-optimizer"] }
 ```
 
-## 机制
+## 机制（为什么放在启动时）
+
+pi 的 `before_agent_start` 依次调用各扩展；返回 `{ systemPrompt }` 等于 `forceSystemPrompt`——**覆盖式替换**，此后所有扩展对 sections 的修改都被丢弃。因此「谁在末尾」是有行为后果的，不是风格问题。本扩展只在 `session_start` 检查与提示，自身**绝不** return systemPrompt。
+
+## 局限
 
-- 读取每个 npm 包的 `pi.extensions` 入口，检查 `before_agent_start` 中 section 写入与 force 出现的先后：先 sections 后 force 视为兼容兜底，不计入疑似。
-- 判定「force 型包之后仍有其他包」即报问题。
+- 只识别静态形态（`return { systemPrompt }` / `forceSystemPrompt`）；动态拼接无法识别。
+- 只处理 `npm:` 前缀包；本地路径包（`path:` / 相对路径）不扫描。
+- 只能保证「已知 force 型在末尾」；未知的 force 型需要人工确认后加入 `forceTail`。
 
-## 限制
+## 许可证
 
-- 只能读 `npm:` 包；读不到源码的包跳过。
-- 不修包内代码，只调整加载顺序。
+MIT。

package/index.ts

@@ -1,429 +1,112 @@
 /**
- * patch-keeper —— 补丁自愈与状态检测（pi 扩展，外置 · 模块化 · 抗上游升级）
+ * patch-keeper —— 扩展加载顺序守护（pi 扩展）
  *
- * ## 为什么存在
- * 本机对「别人的东西」的全部改动登记在快照 `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 被锁）明确报出来。
+ * 问题：pi 的 system prompt 由各扩展的 section 写入拼装。若某扩展在
+ * `before_agent_start` 里 `return { systemPrompt }`（或设置 forceSystemPrompt），
+ * 它会**静默丢弃其后所有扩展的 section 写入**——没有任何报错，表现为
+ * 「某个扩展配了却没效果」。
  *
- * ## 为什么能修 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 到的就是打过补丁的内容 —— 当轮生效。
+ * 本扩展做三件事（全部只读，唯一的写是带备份修 settings）：
+ *  1. 检查 `settings.json` 的 packages 顺序：已知 force 型必须排在末尾。
+ *  2. 静态扫描已装 npm 扩展入口源码，区分「无条件 force」与「section 优先 + 旧宿主兜底」。
+ *  3. 记录 settings 关键字段指纹；变化时提示「环境已变，旧结论可能过期」。
  *
- * ## 边界（刻意的）
- * - PiDeck asar：**只检测不修**。PiDeck 正开着，文件被锁；且插件无权碰 Electron 主进程。
- *   检测到未打补丁 → 提示跑 `run-all.cmd` / `launch-pideck.cmd`（桌面 PI脚本补丁/ 不在时用快照副本 05-脚本补丁/）。
- * - 任何失败都只 notify，不抛错、不影响会话（纪律：不合法就跳过 + 记日志，绝不崩溃）。
+ * 纪律：绝不 return systemPrompt（否则自己就是问题）；任何失败只提示、不抛错。
  */
 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 { existsSync, readFileSync, writeFileSync, copyFileSync } from "node:fs";
 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");
-// 手册（注入对齐检测：本轮注入文本的版本行 vs 磁盘版）
-const MANUAL = path.join(HOME, ".pi", "agent", "APPEND_SYSTEM.md");
+const STATE = path.join(HOME, ".pi", "patch-keeper-state.json");
+const NPM_ROOT = path.join(HOME, ".pi", "agent", "npm", "node_modules");
 
-// 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";
-}
+/** 已知无条件 force 型包。触发概率升序：越靠后越应排在 packages 末尾。 */
+const DEFAULT_FORCE_TAIL = ["npm:pi-rtk-optimizer", "npm:pi-cache-optimizer"];
 
-/** 打/补 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 },
-];
+/** 静态扫描：入口源码里出现这两个形态即判为 force。 */
+const FORCE_RE = /return\s*\{\s*systemPrompt|forceSystemPrompt/;
+const SECTION_RE = /sections\s*(\[|\.)/;
 
-type Result = { ok: boolean; detail: string };
+export type Result = { ok: boolean; detail: string };
 
-/** 读文件；失败返回 null（永不抛）。 */
 function safeRead(p: string): string | null {
-  try { return readFileSync(p, "utf8"); } 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;
-}
-
-/** 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 };
-}
-
-/** 只在未打或半打时修补 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";
-}
-
-/** 第 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})`);
+    return readFileSync(p, "utf8");
+  } catch {
+    return null;
   }
-  if (!missing.length) asarOk = true; // 只在通过时缓存：缺失时每次都实测，便于打完补丁后立刻复检
-  return { ran: true, missing, detail: missing.length ? `未打补丁：${missing.join(" ")}` : "三个补丁都在" };
 }
 
-/** 汇总报告（给命令与启动提示共用）。 */
-// ── 环境指纹：settings 关键字段漂移 → 提示「手册 / 验证结论可能过期」
-function fingerprint(): Record<string, string[]> | null {
+function readSettings(): Record<string, unknown> | 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 JSON.parse(txt) as Record<string, unknown>;
+  } catch {
+    return null;
   }
-  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}）`); }
-    }
+/** 用户可在 ~/.pi/patch-keeper.json 用 forceTail 覆盖已知 force 型列表。 */
+function forceTail(): string[] {
+  const txt = safeRead(STATE);
+  if (!txt) return DEFAULT_FORCE_TAIL;
+  try {
+    const cfg = JSON.parse(txt) as { forceTail?: unknown };
+    return Array.isArray(cfg.forceTail) && cfg.forceTail.every((x) => typeof x === "string")
+      ? (cfg.forceTail as string[])
+      : DEFAULT_FORCE_TAIL;
+  } catch {
+    return DEFAULT_FORCE_TAIL;
   }
-  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[] {
+/** force 型必须整体位于末尾，且相对顺序按 tail 数组。 */
+export function forceOrderIssues(packages: string[], tail: string[] = DEFAULT_FORCE_TAIL): string[] {
   const out: string[] = [];
   const idx = (n: string) => packages.indexOf(n);
-  const present = FORCE_TAIL.filter((n) => idx(n) >= 0);
+  const present = 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（最可能触发者最后）");
+  const later = packages.slice(minForce + 1).filter((n) => !tail.includes(n));
+  if (later.length) {
+    out.push(
+      `force 型之后仍有 ${later.length} 个包（${later.slice(0, 2).join(" / ")}）—— 它们的 section 写入会被静默丢弃；把 ${tail.join(" / ")} 移到 packages 末尾`,
+    );
+  }
+  const ordered = present.every((n, i) => i === 0 || idx(present[i - 1]) < idx(n));
+  if (!ordered) out.push(`force 型相对顺序应与 ${tail.join(" → ")} 一致（最可能触发者最后）`);
   return out;
 }
-/** 把 FORCE_TAIL 成员移到末尾（其余相对顺序不变）；已正确时返回 null。 */
-export function normalizeForceOrder(packages: string[]): string[] | null {
-  const present = FORCE_TAIL.filter((n) => packages.includes(n));
+
+/** 把 force 型移到末尾（其余相对顺序不变）；已正确返回 null。 */
+export function normalizeForceOrder(packages: string[], tail: string[] = DEFAULT_FORCE_TAIL): string[] | null {
+  const present = tail.filter((n) => packages.includes(n));
   if (!present.length) return null;
-  const rest = packages.filter((n) => !FORCE_TAIL.includes(n));
+  const rest = packages.filter((n) => !tail.includes(n));
   const next = [...rest, ...present];
   return next.join("\n") === packages.join("\n") ? null : next;
 }
 
-/** 自动修复 settings.json 的 force 顺序；无变化返回 null。先备份再写。 */
-function fixForceOrder(): string | null {
-  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*(\[|\.)/;
-
-/** 分类：先写 section、只有旧宿主才 force 的算兼容兜底，不算疑似无条件 force。 */
-function classifyPackages(packages: string[]): { force: string[]; fallback: string[] } {
+/** 读扩展入口源码并分类：无条件 force / section 优先（旧宿主兜底）/ 无。 */
+function classifyPackages(packages: string[], tail: 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 (!name.startsWith("npm:") || tail.includes(name)) continue;
+    const dir = path.join(NPM_ROOT, 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; }
+    } catch {
+      continue;
+    }
     for (const rel of entries.slice(0, 3)) {
       const src = safeRead(path.join(dir, rel));
       if (src === null) continue;
@@ -433,179 +116,137 @@ function classifyPackages(packages: string[]): { force: string[]; fallback: stri
       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);
+      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;
+/** 疑似无条件 force（会吞掉其后 section）。 */
+export function scanForcePackages(packages: string[], tail: string[] = DEFAULT_FORCE_TAIL): string[] {
+  return classifyPackages(packages, tail).force;
 }
 
-/** 兼容兜底（section 优先，旧宿主才 force）。 */
-export function scanForceFallbacks(packages: string[]): string[] {
-  return classifyPackages(packages).fallback;
+/** 兼容兜底型（section 优先，仅旧宿主 force）。 */
+export function scanForceFallbacks(packages: string[], tail: string[] = DEFAULT_FORCE_TAIL): string[] {
+  return classifyPackages(packages, tail).fallback;
 }
 
-function report(): string[] {
-  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}`);
+/** codemode 单点检查：禁用 builtin:codemode 时必须有替代实现，反之亦然。 */
+export function consistencyCheck(extensions: string[], packages: string[]): string[] {
+  const disabled = extensions.includes("-builtin:codemode");
+  const guard = packages.includes("npm:pi-codemode-guard");
+  if (disabled && !guard) return ["codemode 单点断裂：已禁 builtin:codemode 但 packages 无替代实现 —— codemode 工具将不可用"];
+  if (!disabled && guard) return ["codemode 单点异常：替代实现已在，但 builtin:codemode 未禁用 —— 双实现风险"];
+  return [];
+}
+
+/** settings 关键字段指纹（顺序敏感）。 */
+function fingerprint(s: Record<string, unknown>): Record<string, string[]> {
+  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 ?? "?"],
+  };
+}
+
+/** 与上次指纹对比并写回；返回变化摘要（无变化为空）。 */
+function fingerprintDrift(cur: Record<string, string[]>): string[] {
+  let prev: Record<string, string[]> | null = null;
+  const raw = safeRead(STATE);
+  if (raw) {
+    try {
+      const j = JSON.parse(raw) as { fingerprint?: Record<string, string[]> };
+      prev = j.fingerprint ?? null;
+    } catch {
+      prev = null;
+    }
   }
-  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)}`);
+  try {
+    const cfg = raw ? (JSON.parse(raw) as Record<string, unknown>) : {};
+    writeFileSync(STATE, JSON.stringify({ ...cfg, fingerprint: cur }, null, 1), "utf8");
+  } catch {
+    /* 静默 */
   }
-  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;
+  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];
+    if (a.join("\n") !== b.join("\n")) out.push(k);
+  }
+  return out;
 }
 
-export default function (pi: ExtensionAPI) {
-  // 启动自愈：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}`; }
+/** 修 settings 的 force 顺序（写前备份）；无变化返回 null。 */
+function fixForceOrder(): string | null {
+  const s = readSettings();
+  if (!s) return null;
+  const tail = forceTail();
+  const packages = (s.packages as string[] | undefined) ?? [];
+  const next = normalizeForceOrder(packages, tail);
+  if (!next) return null;
   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}`; }
+    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 顺序已自动修复：${tail.filter((n) => next.includes(n)).join(" / ")} 移到 packages 末尾`;
+}
+
+/** 状态报告（命令与启动提示共用）。 */
+function report(): string[] {
+  const s = readSettings();
+  if (!s) return ["读不到 settings.json"];
+  const tail = forceTail();
+  const packages = (s.packages as string[]) ?? [];
+  const lines: string[] = [];
+  const fo = forceOrderIssues(packages, tail);
+  lines.push(`force顺序 : ${fo.length ? fo[0] : "OK"}`);
+  const fe = scanForcePackages(packages, tail);
+  lines.push(`疑似force: ${fe.length ? fe.join(" / ") : "无（静态扫描）"}`);
+  const fb = scanForceFallbacks(packages, tail);
+  lines.push(`兼容兜底 : ${fb.length ? fb.join(" / ") : "无"}`);
+  const cm = consistencyCheck((s.extensions as string[]) ?? [], packages);
+  lines.push(`codemode : ${cm.length ? cm[0] : "单点一致"}`);
+  return lines;
+}
+
+export default function patchKeeper(pi: ExtensionAPI): void {
+  pi.on("session_start", async (_event, ctx: ExtensionContext) => {
+    try {
+      const s = readSettings();
+      if (!s) return;
+      const msgs: string[] = [];
+      const fixed = fixForceOrder();
+      if (fixed) msgs.push(fixed);
+      else for (const x of forceOrderIssues((s.packages as string[]) ?? [], forceTail())) msgs.push(x);
+      const drift = fingerprintDrift(fingerprint(s));
+      if (drift.length) msgs.push(`环境指纹已变（${drift.join(" / ")}）—— 此前关于工具/模型的结论可能过期`);
+      const cm = consistencyCheck((s.extensions as string[]) ?? [], (s.packages as string[]) ?? []);
+      for (const x of cm) msgs.push(x);
+      for (const m of msgs) ctx.ui.notify("patch-keeper: " + m, "warning");
+    } catch {
+      /* 静默：检测不该影响会话 */
+    }
+  });
 
   pi.registerCommand("patch-keeper", {
-    description: "查看 / 自愈本机源码补丁状态（PiDeck asar ×3、pi-lens ×1、pi-memory ×1）",
+    description: "查看 / 修复扩展加载顺序（force 型必须在 packages 末尾）",
     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");
+        const r = fixForceOrder();
+        ctx.ui.notify(r ? `patch-keeper: ${r}` : "patch-keeper: force 顺序已正确，无需修复", r ? "info" : "info");
         return;
       }
-      const lines = report();
-      const tip = patchTip(lines);
-      ctx.ui.notify(`补丁状态\n${lines.join("\n")}${tip}`, "info");
+      ctx.ui.notify(`扩展加载顺序\n${report().join("\n")}`, "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,13 +1,16 @@
 {
   "name": "pi-patch-keeper",
-  "version": "1.0.4",
-  "description": "Guards extension load order so later sections are not silently dropped.",
+  "version": "1.0.5",
+  "description": "Detect and fix pi extension load-order hazards: force-typed extensions silently swallow later system-prompt sections.",
   "type": "module",
   "license": "MIT",
   "keywords": [
+    "load-order",
     "pi",
+    "pi-coding-agent",
     "pi-extension",
-    "pi-coding-agent"
+    "pi-package",
+    "system-prompt"
   ],
   "pi": {
     "extensions": [