agent-purge 0.2.8 → 0.2.9

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 |
@@ -115,7 +125,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) => {

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);
 	});
 }

package/lib/persist.mjs

@@ -3,7 +3,7 @@
 // 不动二进制——这里只做可逆的配置改动。
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { RESIDENT as DSH_RESIDENT, SESSION as DSH_SESSION, addPlugin, hasPlugin, pluginDir, residentSource, removePlugin } from "./dsh.mjs";
+import { RESIDENT as DSH_RESIDENT, SESSION as DSH_SESSION, addPlugin, hasPlugin, pluginFileOnDisk, residentSource, removePlugin } from "./dsh.mjs";
 
 const BEGIN = "# >>> agent-purge";
 const END = "# <<< agent-purge";
@@ -64,6 +64,8 @@ export const targets = {
 	codex: {
 		file: () => join(home, ".codex", "config.toml"),
 		kind: "block",
+		// TOML 顶层键必须写在第一个 [table] 之前：追加到文件尾会被解析成上一个表里的键
+		position: "top",
 		layer: "sys",
 		note: "model_instructions_file 直接换掉它的指令文件（连 GUI/子进程启动都生效）",
 		body: (active) => `model_instructions_file = "${active.replace(/\\/g, "/")}"`,
@@ -108,20 +110,20 @@ export const AgentPurge = async () => ({
 	},
 	dsh: {
 		// cordis 插件挂 systemPrompt 层；三个 profile 各一份（desktop 由 Electron 独占，装完要重启一次）
-		file: () => join(pluginDir("desktop"), "index.js"),
+		file: () => pluginFileOnDisk(DSH_RESIDENT),
 		kind: "file",
 		layer: "sys",
 		note: "cordis 插件包；运行时每轮读 state.json，开关 / 切模式 / 换人设都即时生效；只有首次安装要重启一次",
 		probe: () => hasPlugin(DSH_RESIDENT),
 		install: ({ root, active }) => {
 			const r = addPlugin(DSH_RESIDENT, residentSource(root, active));
-			return { file: join(pluginDir("desktop"), "index.js"), note: `三个 profile：${r.profiles.join("/")}；重启一次 DeepSeek Harness 后插件开始工作（之后热切换）` };
+			return { file: pluginFileOnDisk(DSH_RESIDENT), note: `三个 profile：${r.profiles.join("/")}；重启一次 DeepSeek Harness 后插件开始工作（之后热切换）` };
 		},
 		uninstall: () => {
 			removePlugin(DSH_RESIDENT);
 			// 一次性插件被 SIGKILL 时不会自己清，一并扫掉
 			removePlugin(DSH_SESSION);
-			return { file: join(pluginDir("desktop"), "index.js") };
+			return { file: pluginFileOnDisk(DSH_RESIDENT) };
 		},
 	},
 	opencode2: {
@@ -183,7 +185,7 @@ export function status(_root) {
 
 export function install(name, { root, active }) {
 	const t = targets[name];
-	if (!t) return { error: `${name} 没有持久化后端（见 notes：grok/omp 只有 CLI 开关，claude/zcode/antigravity 要打补丁）` };
+	if (!t) return { error: `${name} 没有持久化后端（可用: ${Object.keys(targets).join(", ")}）` };
 	// 多文件/自定义布局的 harness 自带安装函数（dsh 三个 profile、opencode2 v2 插件）
 	// 它们的失败信号是异常（同名外来目录拒绝覆盖等），这里转成调用方约好的 {error}
 	if (t.install) {
@@ -200,7 +202,7 @@ export function install(name, { root, active }) {
 		return { file, action: "wrote-whole-file" };
 	}
 	const old = existsSync(file) ? readFileSync(file, "utf8") : "";
-	const next = upsertBlock(old, t.body(active));
+	const next = upsertBlock(old, t.body(active), t.position);
 	writeFileSync(file, next);
 	return { file, action: old.includes(BEGIN) ? "replaced-block" : "appended-block" };
 }
@@ -237,15 +239,34 @@ export function uninstall(name) {
 	return { file, action: "removed-block" };
 }
 
-// 按标记替换或追加，幂等
-function upsertBlock(text, body) {
+// 按标记替换或追加，幂等。position="top" 用于 TOML：块必须落在第一个 [table] 之前。
+export function upsertBlock(text, body, position = "bottom") {
+	const eol = text.includes("\r\n") ? "\r\n" : "\n";
 	const block = `${BEGIN}\n${body}\n${END}`;
-	if (text.includes(BEGIN)) return text.replace(new RegExp(`${escapeRe(BEGIN)}[\\s\\S]*?${escapeRe(END)}`), block);
-	return `${text.replace(/\s*$/, "")}\n\n${block}\n`;
+	const stripped = text.includes(BEGIN) ? stripBlock(text) : text;
+	if (position === "top") {
+		let lines = stripped.split(/\r?\n/);
+		const firstTable = lines.findIndex((l) => /^\s*\[/.test(l));
+		const end = firstTable === -1 ? lines.length : firstTable;
+		// 已有的顶层同名键先删掉，否则 TOML 会报 duplicate key
+		const key = body.split("=")[0].trim();
+		const keyRe = key ? new RegExp(`^\\s*${escapeRe(key)}\\s*=`) : null;
+		if (keyRe) lines = lines.filter((l, i) => !(i < end && keyRe.test(l)));
+		// 插在开头连续的注释/空行之后：顶层键必须早于第一个 [table]，但不该淹没 #:schema 这类头注释
+		let at = 0;
+		while (at < lines.length && (/^\s*#/.test(lines[at]) || lines[at].trim() === "")) at++;
+		lines.splice(at, 0, ...block.split("\n"));
+		return lines.join(eol).replace(/\s*$/, eol);
+	}
+	return `${stripped.replace(/\s*$/, "")}${eol}${eol}${block.split("\n").join(eol)}${eol}`;
 }
 
-function stripBlock(text) {
-	return text.replace(/\n*# >>> agent-purge[\s\S]*?# <<< agent-purge\n*/, "\n").replace(/\s*$/, "\n");
+export function stripBlock(text) {
+	const eol = text.includes("\r\n") ? "\r\n" : "\n";
+	return text
+		.replace(/\r?\n*# >>> agent-purge[\s\S]*?# <<< agent-purge\r?\n*/, eol + eol)
+		.replace(/^(?:\r?\n)+/, "")
+		.replace(/\s*$/, eol);
 }
 
 function escapeRe(s) {

package/lib/personas.mjs

@@ -29,6 +29,7 @@ export function createStore(root) {
 		(existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith(".md") && !f.startsWith(".") && f !== "active.md") : []);
 
 	function read(id) {
+		if (!isValidId(id)) return null;
 		const file = join(dir, `${id}.md`);
 		if (!existsSync(file)) return null;
 		const raw = readFileSync(file, "utf8");
@@ -45,12 +46,14 @@ export function createStore(root) {
 
 	function save(id, { meta = {}, body }) {
 		if (isReservedId(id)) throw new Error(`${id} 是保留名（active 指针专用），换个 id`);
+		if (!isValidId(id)) throw new Error(`非法 persona id: ${id}（不能含路径分隔符或 ..，最长 64 字符）`);
 		const file = join(dir, `${id}.md`);
 		writeFileSync(file, serialize({ id, meta, body }));
 		return read(id);
 	}
 
 	function remove(id) {
+		if (!isValidId(id)) return false;
 		rmSync(join(dir, `${id}.md`), { force: true });
 		rmSync(join(build, `${id}.md`), { force: true });
 		// 删的就是 active 时必须改道：否则下次无参启动直接 “没有 persona”。
@@ -61,6 +64,7 @@ export function createStore(root) {
 			if (next) setActive(next.id);
 			else writeFileSync(join(dir, ACTIVE_BODY), "You are a helpful coding assistant.\n");
 		}
+		return true;
 	}
 
 	// 把正文落到 .build，给需要文件路径的 harness 用（frontmatter 绝不能进 prompt）
@@ -120,6 +124,12 @@ export function isReservedId(id) {
 	return RESERVED_IDS.has(String(id || ""));
 }
 
+/** persona id 会直接拼进文件名：挡掉路径分隔符与 ..，避免读/删到数据目录之外 */
+export function isValidId(id) {
+	const s = String(id ?? "").trim();
+	return Boolean(s) && s.length <= 64 && !s.includes("..") && !/[\\/:*?"<>|\0]/.test(s) && !isReservedId(s);
+}
+
 function parse(raw) {
 	if (!raw.startsWith("---")) return { meta: {}, body: raw };
 	const end = raw.indexOf("\n---", 3);