agent-purge 0.2.8 → 0.2.10

package/README.md

@@ -32,6 +32,16 @@ npm i -g agent-purge     # 或 npx agent-purge web
 
 要求 Node ≥ 20，零依赖。
 
+**用 magpie 网关？** 插件不在 npm 包里，在仓库的 `magpie-plugin/` 子目录——不要指向仓库根（根 `package.json` 是 CLI，只有 `bin`，magpie 会拒绝）：
+
+```bash
+magpie plugin add /path/to/agent-purge/magpie-plugin
+```
+
+首次使用先跑一次 `agent-purge web`（打开 http://127.0.0.1:7788 的控制台，先看/选一个人设；不想开界面就用 `agent-purge ls`），它会生成 `~/.agent-purge/personas/`；再跑 `node magpie-plugin/gen-personas.mjs` 生成 Persona 页的人设清单。
+
+详见下文「magpie 网关插件（可选）」。
+
 **数据独立存放**，升级不会被覆盖：默认 `~/.agent-purge/`（Windows `C:\Users\<你>\.agent-purge\`），里面是 `state.json` 和 `personas/`。想换位置就设环境变量：
 
 ```bash
@@ -63,7 +73,7 @@ agent-purge pi --persona <id>  # 只这一轮用别的
 | `codex` | 启动参数 `-c model_instructions_file=` | 0.163.0 | 21,026 | 24 |
 | `claude` | `--system-prompt-file` + 二进制补丁清残留身份句 | 2.1.304 | 6,379 | 156 |
 | `grok` | `--system-prompt-override` | 1.0.62 | 5,146 | 21 |
-| `omp` | `--system-prompt` | 17.4.2 | 34,511 | 10,106 |
+| `omp` | 原生扩展：`before_agent_start` 改写 systemPrompt 数组，会话内 `/purge` 热切；`--ask` 仍走 `--system-prompt` | 17.4.2 | 34,511 | 10,106 |
 | `hermes` | 临时 HOME 里替换 `SOUL.md` | 0.21.5 | 8,139 | 7,554 |
 | `zcode` | UserPromptSubmit hook（user 角色）+ `customSystemPrompt` | 0.16.9 | 9,359 | 9,359 |
 | `opencode` | cwd 下 `.opencode/plugin/*.ts` 原地改 `output.system` | 1.19.3 | 19,332 | 112 |
@@ -89,6 +99,33 @@ agent-purge uninstall <h>    # 摘掉，按字节还原
 
 dsh 是唯一有多个形态的：desktop / web / headless 共用一套 cordis 插件，装在各自 profile 的 `node_modules/agent-purge/`，并在 `cordis.patch.yml` 里 `- insert` 挂上，不改 `app.asar`。装完重启一次，之后热生效；三个形态还能在 Web 面板分别勾选。
 
+### 三个通道与总电源（arm / disarm）
+
+一家 harness 有三条能注入的入口，`arm` 默认三条全开：
+
+| 通道 | 管什么 | 只想做这一项 |
+|---|---|---|
+| `shim` | PATH 最前放同名壳，**裸敲** `codex` / `dsh` 也经 agent-purge 启动 | `arm <h> --shim` |
+| `install` | 写 harness 自己的配置/插件，**别人启动的、GUI 里点开的**也生效 | `arm <h> --install` |
+| `slash` | 会话内 `/purge` 热切换（只有 pi / omp / dsh 有 sys 层热切） | `arm <h> --slash` |
+
+```bash
+agent-purge arm <h>            # 三条全开（= 注册）
+agent-purge disarm <h>         # 撤掉这一家的三条通道
+agent-purge arm --all          # 所有支持的 harness 全开 + 总电源打开
+agent-purge disarm --all       # 所有 harness 全撤 + 总电源关掉（"别管我"）
+```
+
+**`--all` 是总电源，不是"全部通道"。** 它改的是 `state.json` 里的 `default.mode`：
+
+- `default.mode = off` 时，**所有**入口都不注入——包括裸敲 `agent-purge`、`agent-purge <h>`、PATH 壳；
+- `disarm <h>` 只撤那家的三个通道，**不动总电源**，所以撤完 `agent-purge dsh` 仍然注入——
+  这就是"明明 disarm 了却还在改提示词"的来源；
+- 只想彻底关掉某一家：`agent-purge disarm dsh --all`（撤 dsh 三条通道 + 关总电源，别的 harness 不动）；
+  `arm` 会把上次的 mode 还回去。
+
+改完用 `agent-purge status` 复核：每家的 `shim / slash / install` 三个格子 + 当前 mode 一张表。
+
 ## magpie 网关插件（可选）
 
 [magpie](https://github.com/yetone/magpie) 把各家 agent 的请求收进本地网关。挂上这个插件后，**凡是经过网关的请求**（Claude Code、Codex、OpenCode、pi…）的 system 段都按 agent-purge 的当前人设改写——不用逐个 harness 装，换人设也不用重启 magpie。
@@ -115,7 +152,7 @@ magpie plugin list                                      # 应看到 async gatewa
 
 options 三键：`mode`、`persona`（人设 id）、`agents`（只对这些 magpie agent 生效，如 `["claude","codex"]`）。
 
-**边界**：改的是请求体里的文本，harness 在客户端就拼死的东西拦不住；`replace` 只删「一行里同时有自称和点名模型/厂商」的行，比 CLI 那套 per-harness 处理粗。插件页是沙箱（没有 fetch、读不到磁盘），人设清单由 `gen-personas.mjs` 按你本机的人设生成到本地（不进仓库），**装完先跑一次**，之后增删人设再跑：`node magpie-plugin/gen-personas.mjs`。自测不依赖 magpie：`npm test`（钩子 26 项断言：四种协议 × 四种模式；页面逻辑 18 项：搜索过滤、options 合并、失败回滚）。
+**边界**：改的是请求体里的文本，harness 在客户端就拼死的东西拦不住；`replace` 只删「一行里同时有自称和点名模型/厂商」的行，比 CLI 那套 per-harness 处理粗。插件页是沙箱（没有 fetch、读不到磁盘），人设清单由 `gen-personas.mjs` 按你本机的人设生成到本地（不进仓库），**装完先跑一次**，之后增删人设再跑：`node magpie-plugin/gen-personas.mjs`。前提是已经运行过 `agent-purge`（如 `agent-purge web` 或 `agent-purge ls`），`~/.agent-purge/personas/` 里有 persona；目录不存在时脚本会直接提示。自测不依赖 magpie：`npm test`（钩子 26 项断言：四种协议 × 四种模式；页面逻辑 18 项：搜索过滤、options 合并、失败回滚）。
 
 ## 目录
 

package/backends/index.mjs

@@ -72,13 +72,13 @@ export const backends = {
 		const file = join(dir, "agent-purge.ts");
 		const src = `export const AgentPurge = async () => ({
   "experimental.chat.system.transform": async (_input, output) => {
-    output.system.splice(0, output.system.length, ${JSON.stringify(inline(personaText))});
+    ${mode === "append" ? `output.system.push(${JSON.stringify(inline(personaText))});` : `output.system.splice(0, output.system.length, ${JSON.stringify(inline(personaText))});`}
   },
 });
 `;
 		return {
 			cmd: "opencode",
-			note: "[plugin] .opencode/plugin/agent-purge.ts（原地 splice output.system）",
+			note: `[plugin] .opencode/plugin/agent-purge.ts（${mode === "append" ? "push" : "原地 splice"} output.system）`,
 			args,
 			setup: () => {
 				mkdirSync(dir, { recursive: true });
@@ -203,7 +203,7 @@ export const oneshots = {
 	}),
 	opencode: ({ prompt, personaText, mode, cwd }) => {
 		if (mode === "off") return { cmd: "opencode", args: ["run", prompt] };
-		const b = backends.opencode({ personaText, cwd, args: ["run", prompt] });
+		const b = backends.opencode({ personaText, mode, cwd, args: ["run", prompt] });
 		return b;
 	},
 	opencode2: ({ prompt, personaText, mode }) => {

package/bin/agent-purge.mjs

@@ -28,6 +28,9 @@ const recovered = recover(); // 上次进程被杀时留下的半改配置，开
 if (recovered > 0) console.log(`[restore] 回滚了 ${recovered} 个上次残留的配置文件`);
 if (argv.includes("--help") || argv.includes("-h")) help(); // 永远优先于默认值
 const flag = (name, fallback) => {
+	// 支持 --mode=append 这种写法（以前只认空格分隔，等号形式会被静默忽略）
+	const inline = argv.find((a) => a.startsWith(name + "="));
+	if (inline !== undefined) return inline.slice(name.length + 1);
 	const i = argv.indexOf(name);
 	return i === -1 ? fallback : argv[i + 1];
 };
@@ -107,12 +110,13 @@ async function launch(name) {
 	const mode = explicitMode ?? state.default?.mode ?? "replace";
 
 	// 裸敲 pi 的持久位（写 state.json，扩展下一会话读它）
-	const autoFlag = name === "pi" ? flag("--auto", null) : null;
+	const autoFlag = name === "pi" || name === "omp" ? flag("--auto", null) : null;
 	if (autoFlag !== null) {
 		if (autoFlag !== "on" && autoFlag !== "off") die("--auto 只能是 on / off");
-		const { setPiAuto } = await import("../lib/state.mjs");
-		setPiAuto(DATA, autoFlag === "on");
-		console.log(`[auto] 裸敲 pi ${autoFlag === "on" ? "会" : "不会"}自动注入（已写入 state.json）`);
+		const { setPiAuto, setOmpAuto } = await import("../lib/state.mjs");
+		if (name === "pi") setPiAuto(DATA, autoFlag === "on");
+		else setOmpAuto(DATA, autoFlag === "on");
+		console.log(`[auto] 裸敲 ${name} ${autoFlag === "on" ? "会" : "不会"}自动注入（已写入 state.json）`);
 	}
 
 	// pi 的人设落在哪一层：sys（默认，真系统提示词）或 user（塞进用户消息，给忽略 system 的模型）
@@ -130,7 +134,8 @@ async function launch(name) {
 
 	// 实测策略：该 harness 的哪一层真的能注入（数据来自 matrix.json armor 段）
 	const { plan } = await import("../lib/armor.mjs");
-	const strategy = plan(matrix, name);	if (!strategy.error) {
+	const strategy = plan(matrix, name);
+	if (!strategy.error) {
 		if (strategy.requiresSeed) console.log(`[策略] ${name}：裸注入 sys 层实测 ${strategy.bare.sys}%，带人设词种子 ${strategy.persona.sys}% —— 需要 seed 层`);
 		const noSys = strategy.blocked.find((b) => b.layer === "sys");
 		if (noSys && mode !== "off") console.log(`[策略] ${name}：sys 层不可用（${noSys.reason}），本次只能靠 user 层`);
@@ -172,7 +177,7 @@ async function launch(name) {
 	if (dd !== -1) {
 		passthrough = argv.slice(dd + 1);
 	} else {
-		const ownWithValue = new Set(["--ask", "--mode", "--persona", "--cwd", "--auto"]);
+		const ownWithValue = new Set(["--ask", "--mode", "--persona", "--cwd", "--auto", "--layer"]);
 		const tail = argv.slice(1);
 		for (let i = 0; i < tail.length; i++) {
 			const t = tail[i];
@@ -185,10 +190,12 @@ async function launch(name) {
 		}
 	}
 
+	const askEq = argv.find((a) => a.startsWith("--ask="));
 	const askIdx = argv.indexOf("--ask");
+	const askPrompt = askEq !== undefined ? askEq.slice(6) : askIdx !== -1 ? argv[askIdx + 1] : null;
 	let built;
-	if (askIdx !== -1) {
-		const raw = argv[askIdx + 1];
+	if (askPrompt !== null) {
+		const raw = askPrompt;
 		if (!raw || raw.startsWith("--")) die('--ask 需要一个 prompt，例如: agent-purge codex --ask "解释这段代码"');
 		const prompt = raw.trim();
 		const one = oneshots[name];
@@ -210,6 +217,35 @@ async function launch(name) {
 
 	if (built.note) console.log(built.note);
 	if (built.residueHint) console.log(`[residue] ${built.residueHint}`);
+	const dryRun = argv.includes("--dry-run");
+	// 启动时把人设塞进扩展（omp / pi）：命令行走不通 10K 人设，扩展也没有长度上限。
+	// omp 交互式启动时把后端的 --system-prompt 摘掉，否则扩展和命令行会各注入一次。
+	// 但 --profile / --no-extensions 下默认扩展目录不会加载：这两个情况保留命令行注入。
+	const ompProfile = name === "omp" ? (flag("--profile", null) ?? process.env.OMP_PROFILE ?? null) : null;
+	const ompNoExtensions = name === "omp" && (argv.includes("--no-extensions") || argv.some((a) => a.startsWith("--no-extensions=")));
+	const useExtension = name !== "omp" || (askPrompt === null && !ompProfile && !ompNoExtensions);
+	let extFile = null;
+	if ((name === "pi" || name === "omp") && !built.unsupported && !built.manual) {
+		const isOmp = name === "omp";
+		if (mode === "off") {
+			// 不装、也不喊注入：扩展就算在盘上，也会因为 mode=off + 没 FORCE 而沉默
+			built.env = { ...built.env, AGENT_PURGE_MODE: "off" };
+		} else if (useExtension) {
+			if (isOmp && built.args[0] === "--system-prompt") built.args.splice(0, 2);
+			if (!dryRun) {
+				const { installSlash } = await import("../lib/slashes.mjs");
+				const r = installSlash(name, DATA, { personaId: picked.id, personaBody: personaText });
+				if (r.error) die(`${name}: ${r.error}`);
+				extFile = r.file;
+			}
+			built.env = { ...built.env, AGENT_PURGE_PERSONA: picked.id, AGENT_PURGE_MODE: mode, AGENT_PURGE_FORCE: "1" };
+		} else if (isOmp && askPrompt === null) {
+			console.log("[ext] --profile/--no-extensions：本次保留命令行注入，/purge 热切不可用");
+		} else if (isOmp) {
+			// --ask：命令行已经注入；扩展若在盘上且 ompAuto 开着会再注一遍，这里按 off 静音
+			built.env = { ...built.env, AGENT_PURGE_MODE: "off" };
+		}
+	}
 	// off 有两种来源：全局总电源关了，或者这一轮手动指定。措辞不能混，否则看日志的人会以为总开关坏了
 	if (mode === "off") {
 		const globalOff = (state.default?.mode ?? "") === "off";
@@ -220,32 +256,29 @@ async function launch(name) {
 		);
 	}
 	console.log(`[cmd] ${[built.cmd, ...built.args.map((a) => (a.includes(" ") ? JSON.stringify(a) : a))].join(" ")}`);
-	if (argv.includes("--dry-run")) process.exit(0);
-
-	// pi：注入活在扩展里（命令行装不下 10K 人设）。
-	//   mode ≠ off：确保扩展在位（没有就装、有就重写成人设最新版），并用 AGENT_PURGE_FORCE=1 明确告诉扩展“这次是启动器要注入”。
-	//   mode = off：不装、也不喊注入。扩展就算挂在盘上，也会因为 mode=off + 没 FORCE 而保持沉默（裸敲 pi 原样跑）。
-	if (name === "pi" && !built.unsupported && !built.manual) {
-		const { installSlash } = await import("../lib/slashes.mjs");
-		if (mode === "off") {
-			// 不装、不喊注入：扩展就算在盘上，也会因为 mode=off + 没 FORCE 而沉默
-			built.env = { ...built.env, AGENT_PURGE_MODE: "off" };
-		} else {
-			installSlash("pi", DATA, { personaId: picked.id, personaBody: personaText });
-			built.env = { ...built.env, AGENT_PURGE_PERSONA: picked.id, AGENT_PURGE_MODE: mode, AGENT_PURGE_FORCE: "1" };
-		}
-	}
+	if (extFile) console.log(`[ext] ${extFile}（/purge 热切换）`);
+	if (dryRun) process.exit(0);
 
 	if (!resolveBin(built.cmd)) {
 		die(`${name}: 找不到可执行文件 ${built.cmd}（PATH 里没有它；agent-purge doctor 可看本机探测结果）`);
 	}
 	built.setup?.();
+	// Ctrl-C 时也要清掉一次性插件：process.exit 会触发 exit 监听器，不依赖 child close
+	let cleaned = false;
+	const cleanup = () => {
+		if (cleaned) return;
+		cleaned = true;
+		try {
+			built.cleanup?.();
+		} catch {}
+	};
+	process.once("exit", cleanup);
 	// 一次性问答：stdin 直接给 NUL。否则 codex 这类会先“Reading additional input from stdin...”
 	// 并阻塞到 EOF（非 TTY 环境必现）；stdin 关了它就直接跑。
-	const stdio = askIdx !== -1 ? ["ignore", "inherit", "inherit"] : "inherit";
+	const stdio = askPrompt !== null ? ["ignore", "inherit", "inherit"] : "inherit";
 	const child = spawnBin(built.cmd, built.args, { cwd, stdio, env: { ...process.env, ...built.env } });
 	const finish = (code) => {
-		built.cleanup?.();
+		cleanup();
 		process.exit(code ?? 1);
 	};
 	child.on("error", (e) => {
@@ -346,21 +379,25 @@ async function armCmd(verb, rest) {
 
 	const supported = Object.keys(matrix.harnesses).filter((h) => matrix.harnesses[h].class !== "unsupported");
 	const namedTarget = rest.filter((x) => !x.startsWith("-"));
-	const targets = rest.includes("--all") || !namedTarget.length ? supported : namedTarget;
+	// 点了名的只动那家：`--all` 只管总电源，不再悄悄把别的 harness 一起撤（issue #5）
+	const targets = namedTarget.length ? namedTarget : supported;
 
 	// 全局 --all 就是总电源：撤的时候必须把 default.mode 置 off，
 	// 否则 `agent-purge <h>` 这条入口照样注入（实测：关了总开关还能接管，就是这里漏的）。
 	// 开的时候把上次的 mode 还回去。单家操作不动 mode。
+	// 没设过默认 harness 时也要能关：launch() 在 default 为空时会回落成 replace。
 	if (rest.includes("--all")) {
 		const { state: cur } = loadState(DATA);
-		const m = cur.default?.mode ?? "off";
-		if (verb === "disarm" && m !== "off" && cur.default?.harness) {
-			setDefault(DATA, { harness: cur.default.harness, mode: "off" });
-			patchState(DATA, { prevMode: m });
+		const m = cur.default?.mode ?? null; // null = 从没设过，launch() 会回落成 replace
+		const h = cur.default?.harness ?? null;
+		if (verb === "disarm" && m !== "off") {
+			patchState(DATA, { default: { harness: h, mode: "off" }, prevMode: m ?? "replace" });
+			console.log(`总电源：mode ${m ?? "(未设，实际按 replace)"} → off（裸敲 agent-purge / agent-purge <h> 都不再注入；arm --all 还回去）`);
 		}
-		if (verb === "arm" && m === "off" && cur.default?.harness) {
+		if (verb === "arm" && cur.default && m === "off") {
 			const back = MODES.includes(cur.prevMode) && cur.prevMode !== "off" ? cur.prevMode : "replace";
-			setDefault(DATA, { harness: cur.default.harness, mode: back });
+			patchState(DATA, { default: { harness: h, mode: back } });
+			console.log(`总电源：mode off → ${back}`);
 		}
 	}
 
@@ -507,7 +544,7 @@ async function statusCmd() {
 		const slashes = slashMod.slashStatus(DATA);
 
 		console.log(`persona  ${state.persona ?? "(未设置)"}`);
-		console.log(`default  ${state.default ? `${state.default.harness} · ${state.default.mode}` : "(未设置)"}   裸敲 agent-purge 用它`);
+		console.log(`default  ${state.default ? `${state.default.harness ?? "(未选默认)"} · ${state.default.mode}` : "(未设置)"}   裸敲 agent-purge 用它`);
 		console.log(`state    ${join(DATA, "state.json")}`);
 		console.log("");
 		console.log("harness     shim   slash  install   /purge层  常驻落点");
@@ -711,7 +748,11 @@ function help() {
    agent-purge arm <h> --shim               只做裸命令接管（写 PATH 最前）
    agent-purge arm <h> --install            只做配置文件常驻
    agent-purge arm <h> --slash              只做会话内 /purge
-   agent-purge disarm <h>|--all             以上全部撤掉
+   agent-purge disarm <h>|--all             以上全部撤掉；不带 <h> 就是所有 harness
+
+   注：--all 是总电源（state.json 的 default.mode）。带 <h> 时只撤那家，
+       但同样把总电源关掉——不然裸敲 agent-purge、agent-purge <h> 照样注入。
+       彻底别管我：agent-purge disarm --all
 
 ④ 看
    agent-purge status             一张表：每家的 shim / slash / install / 能做什么

package/lib/armed.mjs

@@ -20,12 +20,13 @@ export async function reconcileArmed(root) {
 			let alive = true;
 			if (ch === "shim") {
 				const bin = join(home, ".agent-purge", "bin");
-				alive = existsSync(join(bin, `${h}.cmd`)) || existsSync(join(bin, `${h}.ps1`));
+				alive = existsSync(join(bin, `${h}.cmd`)) || existsSync(join(bin, `${h}.ps1`)) || existsSync(join(bin, h));
 			} else if (ch === "install") {
 				alive = Boolean(installs.get(h));
 			} else if (ch === "slash") {
 				const s = resolveSlash(h, root);
-				alive = Boolean(s && s.offered !== false && existsSync(s.file));
+				// dsh 给 probe（看挂载块，不看固定路径）；其余家 slash 就是单个文件
+				alive = Boolean(s && s.offered !== false && (s.probe ? s.probe() : existsSync(s.file)));
 			}
 			if (!alive) {
 				setArmed(root, h, ch, false);

package/lib/caps.mjs

@@ -23,8 +23,8 @@ function readMatrix() {
 	}
 }
 
-/** 有 /purge 机制的 harness —— **只算能把内容写进系统提示词的**（pi 的扩展钩子、dsh 的 cordis 插件） */
-export const SLASH_IDS = new Set(["pi", "dsh"]);
+/** 有 /purge 机制的 harness —— **只算能把内容写进系统提示词的**（pi/omp 的扩展钩子、dsh 的 cordis 插件） */
+export const SLASH_IDS = new Set(["pi", "dsh", "omp"]);
 /** 有可写配置文件/插件的 harness（其余家只能点名启动或打补丁） */
 export const PERSIST_IDS = new Set(Object.keys(persistTargets));
 /** 能把内容真的送进 system 数组的层；user 层（上下文块/用户消息）一律不对外提供 */
@@ -63,6 +63,7 @@ const BLOCKED = { antigravity: "二进制补丁才能改它的系统提示，配
  */
 const HOT = {
 	pi: { kind: "command", needs: "slash", how: "扩展钩子 before_agent_start：/purge 或改设置，下一轮生效" },
+	omp: { kind: "command", needs: "slash", how: "扩展钩子 before_agent_start 改写 systemPrompt 数组：/purge 或改设置，下一轮生效" },
 	opencode: { kind: "state", needs: "install", how: "插件钩子 chat.system.transform 每轮读 state.json + active.md：改设置下一轮生效" },
 	dsh: { kind: "command", needs: "slash", how: "cordis 插件注册 /purge：改 state.json，下一句生效，不产生模型消息" },
 	opencode2: { kind: "state", needs: "install", how: "v2 插件 ctx.session.hook('context') 每轮读 state.json + active.md：改设置下一轮生效" },
@@ -73,7 +74,6 @@ const NOT_HOT = {
 	claude: "system 只在启动时拼一次；会话内只能往 user 消息里塞（实测 0/2）",
 	codex: "config.toml 启动时读；会话内没有能重拼 system 的钩子",
 	grok: "AGENTS.md 启动时读一次",
-	omp: "rules 启动时读一次",
 	hermes: "SOUL.md 虽然是每轮重读，但没有会话内命令面，只能改文件",
 	zcode: "桌面版闭源，没有插件与命令钩子",
 	codebuddy: "只有启动参数",
@@ -122,7 +122,7 @@ export function capsFor(id, ctx = {}) {
 	const slashWhy = blocked
 		? blocked
 		: !SLASH_IDS.has(id)
-			? `${id} 没有能改系统提示词的 /purge（/purge 展开成用户消息，实测无效；只有 pi 的扩展和 dsh 的 cordis 插件能做到）`
+			? `${id} 没有能改系统提示词的 /purge（/purge 展开成用户消息，实测无效；只有 pi/omp 的扩展和 dsh 的 cordis 插件能做到）`
 			: null;
 
 	return {

package/lib/dsh.mjs

@@ -15,11 +15,45 @@ export const DSH_PROFILES = ["desktop", "web", "headless"];
 export const RESIDENT = "agent-purge";
 export const SLASH_RESIDENT = "agent-purge-slash";
 export const SESSION = "agent-purge-session";
+/** 我们写过的三个块名：stash 用完即弃的判断用 */
+const ALL = [RESIDENT, SLASH_RESIDENT, SESSION];
 
 export const dshHome = () => process.env.DSH_HOME || join(homedir(), ".dsh");
 export const profileDir = (p) => join(dshHome(), "profiles", p);
 export const pluginDir = (p, name = RESIDENT) => join(profileDir(p), "node_modules", name);
 const patchFile = (p) => join(profileDir(p), "cordis.patch.yml");
+// 原始字节存 profile 级：插件目录会被删，多插件叠在一起时也要能一起还原（`[]` 空壳）
+const stashFile = (p) => join(profileDir(p), ".agent-purge.patch.before");
+const parseStash = (file) => {
+	try {
+		return JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		return null;
+	}
+};
+const rmStash = (p) => rmSync(stashFile(p), { force: true });
+
+/** 旧版前缀匹配会把 `-slash` 尾段留在 patch 里（issue #4）。只认第 0 列的裸行：块标量里的内容
+ * 必须缩进，子段更不可能出现在列 0，所以这个模式不会误删用户文本。 */
+const healStraySlash = (text) => text.replace(/^-slash[ \t]*\r?(?:\n|$)/gm, "");
+
+/** 剥孤儿行会改字节：换写前留一份原始字节，判断错了还有退路。
+ * 只在我们真棭行时写，且不覆盖已有备份（否则每次装/卸都会把真正的原文冲掉）。 */
+const healBackup = (p, raw) => {
+	const f = join(profileDir(p), ".agent-purge.patch.healed");
+	if (raw === null || healStraySlash(raw) === raw || existsSync(f)) return;
+	writeFileSync(f, raw);
+};
+
+/** dsh 的 patch 模板就是一个 `[]`：空 flow 数组后面再接 `- insert:` 是非法 YAML
+ * （真 dsh 报 `end of the stream or a document separator is expected`），文档根的 `[]` 先摊平。
+ * 只认文档根：手写的 flow 数组、缩进里的 `[]` 原样留着。 */
+const flattenEmptyArray = (text) => {
+	const lines = text.split("\n");
+	const i = lines.findIndex((l) => l.trim() && !/^\s*#/.test(l));
+	if (i < 0 || lines[i].trim() !== "[]") return text;
+	return [...lines.slice(0, i), ...lines.slice(i + 1)].join("\n");
+};
 
 /**
  * dsh 自己建过的 profile（带 package.json）。
@@ -32,6 +66,16 @@ export function liveProfiles() {
 }
 
 const mark = (name) => [`# >>> agent-purge:${name}`, `# <<< agent-purge:${name}`];
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+// marker 必须**整行**匹配：`agent-purge` 是 `agent-purge-slash` 的前缀，
+// 不锚行的话删常驻块会把 /purge 那段一起吃掉，留下 `-slash` 让 patch 变成非法 YAML（issue #4）。
+const blockRe = (name) => {
+	const [begin, end] = mark(name);
+	return new RegExp(`(?:^|\\r?\\n)${esc(begin)}[ \\t]*\\r?\\n[\\s\\S]*?(?:^|\\r?\\n)${esc(end)}[ \\t]*\\r?(?:\\n|$)`, "g");
+};
+const hasBlock = (text, name) => blockRe(name).test(text);
+/** 把我们的三段（以及旧版残留的孤儿行）都剥掉，得到“没有 agent-purge 的原样”。 */
+const stripOurs = (text) => ALL.reduce((t, n) => t.replace(blockRe(n), ""), healStraySlash(text));
 
 /** 这个 package.json 是 agent-purge 写的吗（别碰同名外来目录）。 */
 const isOurs = (meta) => existsSync(meta) && /"?agentPurge"?\s*:\s*true/.test(readFileSync(meta, "utf8"));
@@ -284,31 +328,47 @@ export function addPlugin(name, source) {
 			const dir = pluginDir(p, name);
 			const patch = patchFile(p);
 			const before = existsSync(patch) ? readFileSync(patch, "utf8") : null;
-			// 先登记再动手：下面任何一步抛错，这一轮的产物都能被回滚
-			touched.push({ dir, patch, before });
+			// 先登记再动手：下面任何一步抛错，这一轮的产物都能被回滚（stash 一并回滚）
+			touched.push({ dir, patch, before, existedDir: existsSync(dir), stashPath: stashFile(p), stash: existsSync(stashFile(p)) ? readFileSync(stashFile(p), "utf8") : null });
 			mkdirSync(dir, { recursive: true });
 			writeFileSync(join(dir, "package.json"), pkg);
 			writeFileSync(join(dir, "index.js"), source);
 			files.push(dir);
-			const old = before ?? "# agent-purge 新建的 patch 层\n";
-			if (old.includes(begin)) continue;
-			// `[]` 是合法空数组，后面接 `- insert:` 就是非法 YAML：整份换成我们的段
-			// 不存在也算“空”：走 stash 分支才能把“原本没有这个文件”记下来，卸载后才不会留个空壳
-			const empty = before === null || /^\s*(\[\s*\]\s*)?$/.test(old);
-			const next = empty ? block.slice(1) : old + block;
-			if (empty) {
-				// 整份替换会把原文端掉：原文 + 我们写出的成品都存下，卸载时对得上才整份还原
-				// （对不上 = 期间被人改过，那就只剔自己那段）
-				writeFileSync(join(dir, ".patch.before"), JSON.stringify({ before, after: next }));
+			// 旧版前缀匹配留下的孤儿 `-slash` 行会让整份 patch 不是合法 YAML：写入前剥掉
+			const stripped = healStraySlash(before ?? "");
+			const healed = flattenEmptyArray(stripped);
+			healBackup(p, before);
+			if (hasBlock(healed, name)) {
+				if (healed !== (before ?? "")) {
+					// 旧版装坏的 `[]` + 块：把自愈后的形态记成 stash.after，卸载才还原得回原文
+					const prev = parseStash(stashFile(p));
+					const keep = prev && prev.after === before ? prev.before : stripOurs(before ?? "");
+					writeFileSync(stashFile(p), JSON.stringify({ before: keep, after: healed }));
+					writeFileSync(patch, healed);
+				}
+				continue;
 			}
+			// 空文档（模板那个 `[]`）直接换成我们的段；stash 记剥孤儿后的原样，卸载还回 `[]`
+			const next = healed.trim() ? healed + block : block.slice(1);
+			const prev = parseStash(stashFile(p));
+			// 还原点只在文件还是我们上次写的样子时有效：被改过就按当前字节重新记，
+			// 否则旧 before 会把用户后来写的内容整份覆盖掉（或把文件误删）
+			let keep = null;
+			if (prev && prev.after === before) keep = prev.before;
+			// 旧版写坏的 patch（`[]` + 块）里也含我们的块：还原点得先剥掉自己，否则卸载后会回放旧块
+			else if (before !== null) keep = stripOurs(before);
+			writeFileSync(stashFile(p), JSON.stringify({ before: keep, after: next }));
 			writeFileSync(patch, next);
 		}
 	} catch (e) {
 		// 回滚：撤销本次已写的文件，宁可完全没装也不留半套
-		for (const { dir, patch, before } of touched.reverse()) {
-			rmSync(dir, { recursive: true, force: true });
+		for (const { dir, patch, before, existedDir, stashPath, stash } of touched.reverse()) {
+			// 只删这一轮新建的目录：重装时目录本来就在，删掉会让还原后的 patch 指向一个不存在的包
+			if (!existedDir) rmSync(dir, { recursive: true, force: true });
 			if (before === null) rmSync(patch, { force: true });
 			else writeFileSync(patch, before);
+			if (stash === null) rmSync(stashPath, { force: true });
+			else writeFileSync(stashPath, stash);
 		}
 		throw e;
 	}
@@ -317,45 +377,77 @@ export function addPlugin(name, source) {
 
 /** 只撤自己那一段：目录 + patch marker，别的配置原样。 */
 export function removePlugin(name) {
-	const [begin, end] = mark(name);
 	// 删 install 写入的那一段：前导 \n 可有可无（整份替换的形态没有），尾随 \n 一并吃掉
-	const re = new RegExp(`(?:^|\\n)${begin}[\\s\\S]*?${end}\\n?`, "g");
+	const re = blockRe(name);
 	for (const p of DSH_PROFILES) {
 		const dir = pluginDir(p, name);
 		const meta = join(dir, "package.json");
 		// 只删自己装的；同名但不是我们的目录留着（可能被用户或其他包占了）
 		const ours = isOurs(meta);
-		const stashFile = join(dir, ".patch.before");
-		// 当初整份替换过的：记录躲在插件目录里，先读出来，不然删目录就丢了
-		let stash = null;
-		if (ours && existsSync(stashFile)) {
-			try {
-				stash = JSON.parse(readFileSync(stashFile, "utf8"));
-			} catch {
-				stash = null;
-			}
-		}
+		// 当初整份替换过的：先读出来，不然删目录就丢了（新版在 profile 根，旧版在插件目录）
+		const stash = parseStash(stashFile(p)) ?? parseStash(join(dir, ".patch.before"));
 		if (ours) rmSync(dir, { recursive: true, force: true });
 		const patch = patchFile(p);
 		if (!existsSync(patch)) continue;
 		const text = readFileSync(patch, "utf8");
-		// 我们整份写的、且此后没人动过 → 整份还原（原本没这个文件就删掉它）
-		if (stash && text === stash.after) {
+		const healed = healStraySlash(text);
+		healBackup(p, text);
+		// 我们整份写的、且此后没人动过、且这是最后一个属于自己的块 → 整份还原（原本没这个文件就删掉它）
+		// 还有别的块（例如先装的 /purge）时不能整份还原，否则会连带把它抹掉
+		const siblings = ALL.filter((n) => n !== name && hasBlock(text, n));
+		if (stash && text === stash.after && siblings.length === 0) {
 			if (stash.before === null) rmSync(patch, { force: true });
 			else writeFileSync(patch, stash.before);
+			rmStash(p);
 			continue;
 		}
-		if (text.includes(begin)) writeFileSync(patch, text.replace(re, ""));
+		let next = healed;
+		if (hasBlock(next, name)) next = next.replace(re, "");
+		// 卸到没有我们的块了：剩下的只要等于“原文摊平 `[]` 后的样子”，就把原文逐字节还回去
+		// （多块先后装时，第一个块删完 text 就不再等于 stash.after，但剩下的仍然是原文）
+		if (stash && !ALL.some((n) => hasBlock(next, n))) {
+			const base = stash.before === null ? "" : stash.before;
+			const baseFlat = flattenEmptyArray(healStraySlash(base));
+			// 只认两种“等于原文”：逐字节相等，或两边都只剩空白（原文是那个 `[]` 空壳）
+			if (next === baseFlat || (next.trim() === "" && baseFlat.trim() === "")) {
+				if (stash.before === null) rmSync(patch, { force: true });
+				else writeFileSync(patch, stash.before);
+				rmStash(p);
+				continue;
+			}
+		}
+		if (next !== text) writeFileSync(patch, next);
+		// 我们三个块都不在了 → 这份 stash 用完即弃
+		if (!ALL.some((n) => hasBlock(next, n))) rmStash(p);
+	}
+}
+
+/** 盘上真有那份插件文件的位置：status / armed 对账用。
+ * 不能拿没装过的 desktop 路径当真相：web/headless 装了、desktop 没建过时，
+ * 读那个路径就是 ENOENT（issue #3）。 */
+export function pluginFileOnDisk(name) {
+	for (const p of liveProfiles()) {
+		const f = join(pluginDir(p, name), "index.js");
+		if (existsSync(f)) return f;
 	}
+	return join(pluginDir("desktop", name), "index.js");
+}
+
+/** 任一份 profile 挂着就算能用：/purge 是会话内的，后来新建的 profile 不影响已有会话。 */
+export function hasPluginAny(name) {
+	const targets = liveProfiles();
+	return targets.length > 0 && targets.some((p) => {
+		const patch = patchFile(p);
+		return existsSync(join(pluginDir(p, name), "index.js")) && existsSync(patch) && hasBlock(readFileSync(patch, "utf8"), name);
+	});
 }
 
 /** patch 里还挂着这个名字吗（status 用；不许在有其他 insert 时谎报干净）。 */
 export function hasPlugin(name) {
-	const [begin] = mark(name);
 	const targets = liveProfiles();
 	if (targets.length === 0) return false;
 	return targets.every((p) => {
 		const patch = patchFile(p);
-		return existsSync(join(pluginDir(p, name), "index.js")) && existsSync(patch) && readFileSync(patch, "utf8").includes(begin);
+		return existsSync(join(pluginDir(p, name), "index.js")) && existsSync(patch) && hasBlock(readFileSync(patch, "utf8"), name);
 	});
 }