agent-purge 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZiChuanLan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# agent-purge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+一份系统提示词，喂给多个 coding agent。支持替换（replace）、追加（append）、清空（off）三种模式，可热切换，全程可逆。
+
+```
+agent-purge web          # 本地控制台 http://127.0.0.1:7788
+agent-purge codex        # 用当前 persona 启动 codex
+agent-purge pi --ask "…" # 一次性提问
+```
+
+## 它做什么
+
+每家 coding agent 读系统提示词的位置都不一样：有的认启动参数，有的认配置文件，有的只能靠插件改运行时对象。agent-purge 把这些入口统一成三件事：
+
+| 通道 | 机制 | 生效范围 |
+|---|---|---|
+| `install` | 写入该 harness 的托管配置块（Markdown / hooks / 插件） | 常驻，别人启动也生效 |
+| `shim` | 往 PATH 前置同名小壳，转发给 `agent-purge <h>` | 裸敲命令也接管 |
+| `slash` | 会话内 `/purge on\|off\|status` | 热切换，不动磁盘 |
+
+三层都写的是同一份 `personas/<id>.md` 的正文。`--mode off` 或 Web 总开关关掉时，全部撤回到原样——不留残渣。
+
+## 安装
+
+```bash
+npm i -g agent-purge     # 或 npx agent-purge web
+```
+
+要求 Node ≥ 20，零依赖。
+
+**数据独立存放**，升级不会被覆盖：默认 `~/.agent-purge/`（Windows `C:\Users\<你>\.agent-purge\`），里面是 `state.json` 和 `personas/`。想换位置就设环境变量：
+
+```bash
+export AGENT_PURGE_HOME=/path/to/your/data     # Windows: setx AGENT_PURGE_HOME D:\ap-data
+```
+
+旧版本（0.1.x）把数据放在包目录里，首次运行会自动搬到新家，原文件不动。
+
+## 人设
+
+`personas/<id>.md` = frontmatter（`id` / `name` / `description` / `harness` / `model`）+ 正文。正文就是会被写进系统提示词的那一段。
+
+```bash
+agent-purge ls                 # 列出全部 persona，标出当前匹配的
+agent-purge use <id>           # 切换当前 persona
+agent-purge pi --persona <id>  # 只这一轮用别的
+```
+
+首次运行会在 `personas/` 下生成 `neutral.md` 起步模板。
+
+## 支持情况
+
+`agent-purge ls` 和 Web 控制台显示的是**运行期真值**：每个 harness 有没有装、版本、注入层（SYS / USER）、三个通道各自可用性。`matrix.json` 里是静态能力表，两者冲突时以运行期为准。
+
+闭源桌面端（提示词在服务端或二进制里）只做原样启动，不做任何注入——`agent-purge <h>` 会明确打印原因，不会假装生效。
+
+## 目录
+
+```
+bin/         CLI 入口
+lib/         状态、persona、注入、通道、检测
+backends/    每个 harness 的启动参数与身份句处理
+web/         控制台（server.mjs + ui.html）
+bench/       注入成功率实测与裁判脚本（开发用，不参与运行）
+matrix.json  能力矩阵
+```
+
+## 边界
+
+- 只改提示词相关的位置，不碰二进制、不破解、不绕过任何授权。
+- 所有改动可逆：`agent-purge uninstall <h>` / `disarm` / `--mode off`。
+- 状态只存本机 `state.json`，不上传任何数据。
+
+## License
+
+MIT

package/backends/index.mjs

@@ -0,0 +1,181 @@
+// 每家的 build() 是纯函数：只描述"怎么启动"，不 spawn、不写盘。
+// setup/cleanup 由入口统一调用，保证能按哈希回滚。
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const inline = (text) => text.replace(/\s+$/, "");
+
+export const backends = {
+	// pi：命令行已试过 --system-prompt，但 pi.cmd 走 cmd.exe，10K 人设会撞 8191 上限（实测“命令行太长”）。
+	// 所以 pi 的注入靠扩展（sys 层、无长度限制、跟 state.json 走），这里只透传。
+	// 扩展由 launch() 在启动前自动确保安装。
+	pi: ({ args }) => ({ cmd: "pi", args }),
+
+	codex: ({ personaPath, personaText, mode, args }) => ({
+		cmd: "codex",
+		args:
+			mode === "off"
+				? [...args]
+				: mode === "append"
+					? ["-c", `developer_instructions=${inline(personaText)}`, ...args]
+					: ["-c", `model_instructions_file=${personaPath.replace(/\\/g, "/")}`, ...args],
+	}),
+
+// CodeBuddy（腾讯云，npm @tencent-ai/codebuddy-code）：原生整段替换，无残留
+	codebuddy: ({ personaPath, personaText, mode, args }) => ({
+		cmd: "codebuddy",
+		args:
+			mode === "off"
+				? [...args]
+				: mode === "append"
+					? ["--append-system-prompt", inline(personaText), ...args]
+					// replace 走文件：内联 9.6K 会把裸命令（.cmd 包装器）撞上 8191 上限
+					: ["--system-prompt-file", personaPath, ...args],
+	}),
+
+	claude: ({ personaPath, mode, args }) => ({
+		cmd: "claude",
+		args:
+			mode === "off"
+				? [...args]
+				: mode === "append"
+					? ["--append-system-prompt-file", personaPath, ...args]
+					: ["--system-prompt-file", personaPath, ...args],
+		residueHint: mode === "off" ? "" : "不补丁时残留 62 字身份句",
+	}),
+
+	grok: ({ personaText, mode, args }) => ({
+		cmd: "grok",
+		args:
+			mode === "off"
+				? [...args]
+				: mode === "append"
+					? ["--rules", inline(personaText), ...args]
+					: ["--system-prompt-override", inline(personaText), ...args],
+	}),
+
+	omp: ({ personaText, mode, args }) =>
+		mode === "off"
+			? { cmd: "omp", args: [...args] }
+			: {
+					cmd: "omp",
+					args: ["--system-prompt", inline(personaText), ...args],
+					residueHint: "MCP tool routes 仍会追加（10K 量级），关掉 MCP server 可缩",
+				},
+
+	// opencode 靠 cwd 下 .opencode/plugin/*.ts 发现插件，必须原地 splice
+	opencode: ({ personaText, mode, cwd, args }) => {
+		if (mode === "off") return { cmd: "opencode", args: [...args] };
+		const dir = join(cwd, ".opencode", "plugin");
+		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))});
+  },
+});
+`;
+		return {
+			cmd: "opencode",
+			note: "[plugin] .opencode/plugin/agent-purge.ts（原地 splice output.system）",
+			args,
+			setup: () => {
+				mkdirSync(dir, { recursive: true });
+				writeFileSync(file, src);
+			},
+			cleanup: () => rmSync(file, { force: true }),
+		};
+	},
+
+	// 需要落盘或调用方配合，CLI 不代劳，只给可复制的配方
+	zcode: () => ({
+		manual: [
+			"CLI 拿不到 customSystemPrompt（只有 app-server/SDK 能传）；CLI 只有 UserPromptSubmit hook 注入，且落在 user 角色。",
+			"注入配方: ~/.zcode/cli/config.json 里 hooks.enabled=true + UserPromptSubmit hook 返回 additionalContext。",
+			"归零配方: 等长替换 resources/glm/zcode.cjs 里的 IJs（42 字），但 cli_prefix 段仍留 42 字。",
+		],
+	}),
+
+	hermes: () => ({
+		manual: [
+			"hermes 从 $HERMES_HOME/SOUL.md 取身份段。",
+			"配方: 复制现有 HERMES_HOME 到 .sandbox/hermes-home，覆盖 SOUL.md，再 HERMES_HOME=<该目录> 启动。",
+			"必须加 --ignore-rules: Hermes 自带的 rules 层会把人设顶回去（实测不加时它自称 Hermes 并明说“这一条我不照办”，加了立刻完全采纳）。",
+			"注意首次启动会自装 Python 依赖（约 80 秒）。",
+		],
+	}),
+
+	antigravity: () => ({
+		manual: [
+			"prompt 在 resources/bin/language_server.exe（Go embed.FS）。",
+			"闭源 App 的身份句在二进制里，只能等长替换；改动会使签名失效、更新被覆盖，所以默认不做。",
+		],
+	}),
+
+	qoder: ({ reason }) => ({ unsupported: reason }),
+	workbuddy: ({ reason }) => ({ unsupported: reason }),
+};
+
+
+
+
+// 一次性问答（headless）规格：Web UI 与 `agent-purge <h> --ask` 共用。
+// 只收录实测过参数的 harness，没验过的不猜。
+export const oneshots = {
+	pi: ({ prompt }) => ({
+		cmd: "pi",
+		args: ["-p", prompt],
+		note: "注入靠扩展（sys 层）；人设走 state.json，不占命令行",
+	}),
+	claude: ({ prompt, personaPath, mode }) => ({
+		cmd: "claude",
+		args: ["-p", prompt, ...(mode === "off" ? [] : [mode === "append" ? "--append-system-prompt-file" : "--system-prompt-file", personaPath])],
+	}),
+	grok: ({ prompt, personaText, mode }) => ({
+		cmd: "grok",
+		args: ["-p", prompt, "--always-approve", ...(mode === "off" ? [] : [mode === "append" ? "--rules" : "--system-prompt-override", inline(personaText)])],
+	}),
+	omp: ({ prompt, personaText, mode }) => ({
+		cmd: "omp",
+		args: ["-p", ...(mode === "off" ? [] : ["--system-prompt", inline(personaText)]), prompt],
+	}),
+	codex: ({ prompt, personaPath, personaText, mode }) => ({
+		cmd: "codex",
+		args: [
+			...(mode === "off"
+				? []
+				: ["-c", mode === "append" ? `developer_instructions=${inline(personaText)}` : `model_instructions_file=${personaPath.replace(/\\/g, "/")}`]),
+			"exec",
+			prompt,
+		],
+	}),
+	opencode: ({ prompt, personaText, mode, cwd }) => {
+		if (mode === "off") return { cmd: "opencode", args: ["run", prompt] };
+		const b = backends.opencode({ personaText, cwd, args: ["run", prompt] });
+		return b;
+	},
+	zcode: ({ prompt }) => ({
+		cmd: "zcode",
+		args: ["--prompt", prompt, "--mode", "yolo", "--output-format", "stream-json", "--no-color"],
+		note: "persona 对 zcode CLI 不生效：customSystemPrompt 只有 app-server/SDK 能传",
+	}),
+	codebuddy: ({ prompt, personaPath, personaText, mode }) => ({
+		cmd: "codebuddy",
+		args: [
+			"-p",
+			prompt,
+			"--max-turns",
+			"5",
+			...(mode === "off"
+				? []
+				: mode === "append"
+					? ["--append-system-prompt", inline(personaText)]
+					: ["--system-prompt-file", personaPath]),
+		],
+	}),
+	hermes: ({ prompt, mode }) => ({
+		cmd: "hermes",
+		// --ignore-rules 是关键：不加时 Hermes 自带 rules 层会把人设顶回去（模型自称 Hermes、明说“不照办”）。
+		args: ["-z", prompt, ...(mode === "off" ? [] : ["--ignore-rules"])],
+		note: "身份段来自 $HERMES_HOME/SOUL.md；注入时必须带 --ignore-rules，关电源时不带",
+	}),
+};