agent-purge 0.2.9 → 0.2.11

package/lib/templates/personas/neutral.md

@@ -1,30 +1,30 @@
----
-id: neutral
-name: 中性模板
-description: 起步用的最小 persona：只约定语言、风格和协作方式。正文就是会被写进系统提示词的那一段，改这里就是改 agent 的行为。
-harness: ["*"]
-model: ["*"]
-order: 1
----
-
-# 系统提示词 · 起步模板
-
-## 语言与格式
-
-简体中文；先给结论，再给依据。命令、路径、标识符保持原样不翻译。
-
-## 工作方式
-
-- 先读再改：动文件前先看一眼现状，别凭印象改。
-- 最小改动：只动与目标相关的地方，不顺手重构无关代码。
-- 有证据再下结论：跑过的命令、读到的行号、真实报错，都可以引；没验证过的判断标 `[INFERENCE]`。
-- 卡住时给下一步需要的具体信息，不要只说“无法完成”。
-
-## 边界
-
-技术细节、代码、配置该给就给；不确定的事实说不确定，不编造。
-
----
-
-> 这份文件是模板：复制成 `<你的 id>.md` 再改，`agent-purge use <id>` 切过去。
-> 正文之后的任何内容都会原样进入系统提示词（`install` / 裸命令接管 / `/purge` 都读它）。
+---
+id: neutral
+name: 中性模板
+description: 起步用的最小 persona：只约定语言、风格和协作方式。正文就是会被写进系统提示词的那一段，改这里就是改 agent 的行为。
+harness: ["*"]
+model: ["*"]
+order: 1
+---
+
+# 系统提示词 · 起步模板
+
+## 语言与格式
+
+简体中文；先给结论，再给依据。命令、路径、标识符保持原样不翻译。
+
+## 工作方式
+
+- 先读再改：动文件前先看一眼现状，别凭印象改。
+- 最小改动：只动与目标相关的地方，不顺手重构无关代码。
+- 有证据再下结论：跑过的命令、读到的行号、真实报错，都可以引；没验证过的判断标 `[INFERENCE]`。
+- 卡住时给下一步需要的具体信息，不要只说“无法完成”。
+
+## 边界
+
+技术细节、代码、配置该给就给；不确定的事实说不确定，不编造。
+
+---
+
+> 这份文件是模板：复制成 `<你的 id>.md` 再改，`agent-purge use <id>` 切过去。
+> 正文之后的任何内容都会原样进入系统提示词（`install` / 裸命令接管 / `/purge` 都读它）。

package/lib/update.mjs

@@ -0,0 +1,137 @@
+// Release 检查与受限流式下载；只有确证的编译产品可以自替换，共享 node.exe 始终保持原样。
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, copyFileSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, readSync, writeSync, constants } from "node:fs";
+import { basename, dirname } from "node:path";
+import { readResource, isCompiled } from "./root.mjs";
+import { atomicControlJSON } from "./control.mjs";
+
+export const GITHUB_REPO = "ZiChuanLan/agent-purge";
+export const RELEASES_API = `https://api.github.com/repos/${GITHUB_REPO}/releases/latest`;
+export const RELEASES_PAGE = `https://github.com/${GITHUB_REPO}/releases/latest`;
+export function currentVersion() {
+	try { return JSON.parse(readResource("package.json").toString("utf8")).version || "0.0.0"; }
+	catch { return "0.0.0"; }
+}
+// 当前 Release 仅有 Windows EXE，不能用它覆盖 Linux/macOS 的编译产物。
+export const canReplaceSelf = () => process.platform === 'win32' && isCompiled() && !/^(?:node|bun)(?:\.exe)?$/i.test(basename(process.execPath));
+
+export function compareSemver(a, b) {
+	const parse = value => String(value).replace(/^v/, "").split("+")[0].split(/-(.*)/s);
+	const [am, ap] = parse(a), [bm, bp] = parse(b);
+	const aa = am.split(".").map(Number), bb = bm.split(".").map(Number);
+	for (let i = 0; i < 3; i++) { const delta = (bb[i] || 0) - (aa[i] || 0); if (delta) return delta; }
+	if (ap === bp) return 0;
+	if (ap === undefined) return -1;
+	if (bp === undefined) return 1;
+	const ax = ap.split("."), bx = bp.split(".");
+	for (let i = 0; i < Math.max(ax.length, bx.length); i++) {
+		if (ax[i] === bx[i]) continue;
+		if (ax[i] === undefined) return 1;
+		if (bx[i] === undefined) return -1;
+		const an = /^\d+$/.test(ax[i]), bn = /^\d+$/.test(bx[i]);
+		if (an && bn) return Number(bx[i]) - Number(ax[i]);
+		if (an !== bn) return an ? 1 : -1;
+		return bx[i] > ax[i] ? 1 : -1;
+	}
+	return 0;
+}
+export async function checkForUpdate({ timeout = 5000, cacheFile, force = false } = {}) {
+	const current = currentVersion();
+	if (!force && cacheFile) {
+		try {
+			const cached = JSON.parse(readFileSync(cacheFile, "utf8"));
+			if (cached.ok === true && typeof cached.latest === "string" && Date.now() - cached.at >= 0 && Date.now() - cached.at < 86400000)
+				return { ...cached, current, hasUpdate: compareSemver(current, cached.latest) > 0, fromCache: true };
+		} catch {}
+	}
+	const controller = new AbortController(), timer = setTimeout(() => controller.abort(), timeout);
+	try {
+		const response = await fetch(RELEASES_API, { signal: controller.signal, headers: { Accept: "application/vnd.github.v3+json", "User-Agent": `agent-purge/${current}` } });
+		if (response.status === 404) return { current, ok: true, published: false, latest: current, hasUpdate: false, body: "尚无公开 Release。", htmlUrl: RELEASES_PAGE, assets: [], at: Date.now() };
+		if (!response.ok) throw new Error(`GitHub API 响应 ${response.status}: ${response.statusText}`);
+		const data = await abortable(response.json(), controller.signal);
+		const latest = String(data.tag_name ?? "").replace(/^v/, "");
+		if (!/^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/.test(latest)) throw new Error("Release 版本字段无效");
+		const assets = (Array.isArray(data.assets) ? data.assets : []).filter(a => typeof a.name === "string" && /^https:\/\//.test(a.browser_download_url ?? ""))
+			.map(a => ({ name: a.name, size: a.size, downloadUrl: a.browser_download_url, digest: a.digest ?? null }));
+		const result = { ok: true, current, latest, hasUpdate: compareSemver(current, latest) > 0, tagName: data.tag_name,
+			name: data.name || data.tag_name, body: String(data.body ?? ""), publishedAt: data.published_at, htmlUrl: data.html_url || RELEASES_PAGE, assets, at: Date.now() };
+		if (cacheFile) { try { mkdirSync(dirname(cacheFile), { recursive: true }); atomicControlJSON(cacheFile, result); } catch {} }
+		return result;
+	} catch (error) { return { ok: false, current, latest: current, hasUpdate: false, error: controller.signal.aborted ? "请求超时" : error.message }; }
+	finally { clearTimeout(timer); }
+}
+function abortable(promise, signal) {
+	return new Promise((resolve, reject) => {
+		const abort = () => reject(new DOMException("请求超时", "AbortError"));
+		if (signal.aborted) { abort(); return; }
+		signal.addEventListener("abort", abort, { once: true });
+		Promise.resolve(promise).then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+	});
+}
+
+/** 下载到同目录临时文件，长度/摘要通过后才发布；中断时保留原 destPath。 */
+export async function downloadFile(url, destPath, onProgress, { timeout = 60000, maxBytes = 512 * 1024 * 1024, expectedSize, digest } = {}) {
+	if (!/^https?:\/\//i.test(url)) throw new Error("下载 URL 必须是 HTTP(S)");
+	if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || (expectedSize !== undefined && (!Number.isSafeInteger(expectedSize) || expectedSize < 1))) throw new Error("下载长度参数无效");
+	const controller = new AbortController(), timer = setTimeout(() => controller.abort(), timeout);
+	const temporary = `${destPath}.part-${randomUUID()}`;
+	let fd, reader;
+	try {
+		const response = await fetch(url, { signal: controller.signal, redirect: "follow", headers: { "User-Agent": `agent-purge/${currentVersion()}` } });
+		if (!response.ok || !response.body) throw new Error(`下载失败 HTTP ${response.status}`);
+		const total = Number(response.headers.get("content-length") || 0);
+		if (!Number.isSafeInteger(total) || total < 0 || total > maxBytes || (expectedSize !== undefined && expectedSize > maxBytes)) throw new Error("下载长度超出限制");
+		mkdirSync(dirname(destPath), { recursive: true });
+		fd = openSync(temporary, "wx", 0o600);
+		reader = response.body.getReader();
+		let received = 0;
+		const hash = createHash("sha256");
+		while (true) {
+			const { done, value } = await abortable(reader.read(), controller.signal);
+			if (done) break;
+			received += value.byteLength;
+			if (received > maxBytes) throw new Error("下载长度超出限制");
+			hash.update(value);
+			let offset = 0;
+			while (offset < value.byteLength) offset += writeSync(fd, value, offset, value.byteLength - offset);
+			onProgress?.(received, total);
+		}
+		if (!received || (total && received !== total) || (expectedSize !== undefined && received !== expectedSize)) throw new Error("下载不完整：长度不符");
+		const sha256 = hash.digest("hex");
+		if (digest && digest !== `sha256:${sha256}`) throw new Error("下载摘要不符");
+		fsyncSync(fd); closeSync(fd); fd = undefined;
+		renameSync(temporary, destPath);
+		return { path: destPath, size: received, sha256 };
+	} finally {
+		clearTimeout(timer);
+		if (fd !== undefined) closeSync(fd);
+		controller.abort();
+		if (reader) reader.cancel().catch(() => {});
+		rmSync(temporary, { force: true });
+	}
+}
+
+/** 独立文件事务供夹具测试；先 copy 到目标同卷，旧二进制保留为可回滚副本。 */
+export function replaceExecutable(currentExe, downloadedNewExePath) {
+	if (/^(?:node|bun)(?:\.exe)?$/i.test(basename(currentExe))) throw new Error("共享运行时保持原样，请使用包管理器更新");
+	const fd = openSync(downloadedNewExePath, "r"), header = Buffer.alloc(2);
+	try {
+		if (statSync(downloadedNewExePath).size < 64 || readSync(fd, header, 0, 2, 0) !== 2 || header.toString() !== "MZ") throw new Error("更新文件不是 Windows 可执行文件");
+	} finally { closeSync(fd); }
+	const staged = `${currentExe}.new-${randomUUID()}`, oldExePath = `${currentExe}.old-${randomUUID()}`;
+	copyFileSync(downloadedNewExePath, staged, constants.COPYFILE_EXCL);
+	let moved = false;
+	try {
+		renameSync(currentExe, oldExePath); moved = true;
+		renameSync(staged, currentExe);
+		return { ok: true, currentExe, oldExePath };
+	} catch (error) {
+		if (moved) { try { renameSync(oldExePath, currentExe); } catch (rollback) { throw new Error(`更新失败：${error.message}；还原失败：${rollback.message}；旧版保留于 ${oldExePath}`, { cause: error }); } }
+		throw error;
+	} finally { rmSync(staged, { force: true }); }
+}
+export function replaceSelfExecutable(downloadedNewExePath) {
+	if (!canReplaceSelf()) throw new Error(`当前为 Node/脚本安装，请使用 npm 或安装器更新：${process.execPath}`);
+	return replaceExecutable(process.execPath, downloadedNewExePath);
+}

package/lib/verification.mjs

@@ -0,0 +1,23 @@
+// 读回「实测证据」：谁真的被证明把人设发进了特权角色层。
+// 只认本机抓包写下的 verification/latest.json，不认 matrix.json 的常量表，也不认配置写入成功。
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { verificationEvidence } from "./evidence.mjs";
+export { sysHit } from "./evidence.mjs";
+
+export function verificationFile(root) {
+	return join(root, "verification", "latest.json");
+}
+
+/** harness 名 → true（有实测且命中 sys 层）。没有报告 = 空集合，调用方按「未实测」处理。 */
+export function verifiedHarnesses(root) {
+	const ok = new Set();
+	let raw;
+	try {
+		raw = JSON.parse(readFileSync(verificationFile(root), "utf8"));
+	} catch {
+		return ok;
+	}
+	for (const r of Array.isArray(raw?.results) ? raw.results : []) if (verificationEvidence(r).state === "verified") ok.add(r.harness);
+	return ok;
+}

package/lib/window.mjs

@@ -0,0 +1,58 @@
+// 桌面原生独立窗口启动器：优先使用 Edge/Chrome 的 App 模式（无地址栏、无标签页的原生软件窗口体验）
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+
+const BROWSER_PATHS = [
+	"C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe",
+	"C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe",
+	"C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+	"C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+];
+
+/**
+ * 寻找本机安装的 Chromium 内核浏览器（Edge / Chrome）
+ */
+export function findChromiumAppBrowser() {
+	if (process.platform !== "win32") return null;
+	for (const p of BROWSER_PATHS) {
+		if (existsSync(p)) return p;
+	}
+	return null;
+}
+
+/**
+ * 以原生应用窗口（独立窗口、无地址栏、无标签页）打开指定 URL
+ * @param {string} url
+ * @param {{ width?: number, height?: number }} [opts]
+ */
+export function openAppWindow(url, { width = 1260, height = 860, spawnProcess = spawn,
+	onError = error => console.error(`[web] 无法自动打开浏览器：${error.message}；服务仍在运行，请手动访问 ${url}`) } = {}) {
+	const launch = (command, args) => {
+		try {
+			const child = spawnProcess(command, args, { detached: true, stdio: "ignore", windowsHide: true });
+			child.once("error", onError);
+			child.unref();
+			return child;
+		} catch (error) { onError(error); return null; }
+	};
+	const browser = findChromiumAppBrowser();
+	if (browser) {
+		// --app 模式：启动独立应用窗口，体验与原生桌面客户端完全一致
+		const child = launch(
+			browser,
+			[`--app=${url}`, `--window-size=${width},${height}`],
+		);
+		return { mode: child ? "app" : "manual", browser, pid: child?.pid };
+	}
+
+	// 兜底回退：系统默认浏览器打开
+	let child;
+	if (process.platform === "win32") {
+		child = launch("cmd.exe", ["/d", "/c", "start", "", url]);
+	} else if (process.platform === "darwin") {
+		child = launch("open", [url]);
+	} else {
+		child = launch("xdg-open", [url]);
+	}
+	return { mode: child ? "browser" : "manual", browser: "default", pid: child?.pid };
+}

package/lib/wrappers.mjs

@@ -0,0 +1,49 @@
+// 已核对的完整模板；只归一换行，未知 wrapper 不授予临时宿主身份。
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+export const MANAGED_PI_BATCH = "@ECHO off\nSETLOCAL\nSET \"node=node\"\n\"%node%\" \"%~dp0pi-launcher.js\" %*\nSET \"pi_exit_code=%ERRORLEVEL%\"\nIF \"%pi_exit_code%\"==\"9009\" (\n  IF \"%node%\"==\"node\" (\n    \"%SystemRoot%\\System32\\where.exe\" /Q node\n    IF ERRORLEVEL 1 GOTO node_missing\n  ) ELSE IF NOT EXIST \"%node%\" GOTO node_missing\n)\nEXIT /B %pi_exit_code%\n:node_missing\nECHO Pi could not find Node.js. Install Node.js 22.19.0 or newer, or rerun the installer at https://pi.dev. 1>&2\nEXIT /B %pi_exit_code%\r\n";
+export const MANAGED_PI_JS = "const fs = require(\"node:fs\");\nconst path = require(\"node:path\");\nconst { spawnSync } = require(\"node:child_process\");\n\nconst packageName = \"@earendil-works/pi-coding-agent\";\nconst commandName = \"pi\";\nconst agentDir = path.dirname(__dirname);\nconst installRoot = path.join(agentDir, \"install\");\nconst currentFile = path.join(installRoot, \"current-version\");\nconst currentVersion = fs.readFileSync(currentFile, \"utf8\").trim();\nif (!currentVersion || currentVersion === \".\" || currentVersion === \"..\" || !/^[0-9A-Za-z._+-]+$/.test(currentVersion)) {\n\tthrow new Error(`Managed Pi version file is invalid: ${currentFile}`);\n}\n\nconst releaseDir = path.join(installRoot, \"releases\", currentVersion);\nconst packageDir = path.join(releaseDir, \"node_modules\", ...packageName.split(\"/\"));\nconst packageJson = JSON.parse(fs.readFileSync(path.join(packageDir, \"package.json\"), \"utf8\"));\nconst binPath = typeof packageJson.bin === \"string\" ? packageJson.bin : packageJson.bin?.[commandName];\nif (!binPath) {\n\tthrow new Error(`${packageName} does not declare a ${commandName} bin`);\n}\nconst cliPath = path.resolve(packageDir, binPath);\nconst cliRelative = path.relative(packageDir, cliPath);\nif (cliRelative.startsWith(\"..\") || path.isAbsolute(cliRelative) || !fs.statSync(cliPath).isFile()) {\n\tthrow new Error(`Managed Pi executable is invalid: ${cliPath}`);\n}\n\nconst result = spawnSync(process.execPath, [cliPath, ...process.argv.slice(2)], {\n\tstdio: \"inherit\",\n\tenv: { ...process.env, PI_MANAGED_INSTALL_ROOT: installRoot },\n});\nif (result.error) throw result.error;\nprocess.exit(result.status ?? 1);\r\n";
+export const MANAGED_PI_POWERSHELL = `#!/usr/bin/env pwsh
+$basedir=Split-Path $MyInvocation.MyCommand.Definition -Parent
+$launcher=Join-Path $basedir "pi-launcher.js"
+$node="node"
+try {
+  if ($MyInvocation.ExpectingInput) {
+    $input | & $node $launcher $args
+  } else {
+    & $node $launcher $args
+  }
+} catch [System.Management.Automation.CommandNotFoundException] {
+  [Console]::Error.WriteLine("Pi could not find Node.js. Install Node.js 22.19.0 or newer, or rerun the installer at https://pi.dev.")
+  exit 127
+}
+exit $LASTEXITCODE
+`;
+const normalize = source => source.replace(/\r\n?/g, "\n").replace(/\n$/, "");
+const same = (source, expected) => normalize(source) === normalize(expected);
+export function knownWrapper(file, env, findNode) {
+ let source;
+ try { source = readFileSync(file, "utf8"); } catch { return null; }
+ const dir = dirname(file);
+ if ((basename(file).toLowerCase() === "pi.cmd" && same(source, MANAGED_PI_BATCH)) || (basename(file).toLowerCase() === "pi.ps1" && same(source, MANAGED_PI_POWERSHELL))) {
+  try {
+   if (!same(readFileSync(join(dir, "pi-launcher.js"), "utf8"), MANAGED_PI_JS)) return null;
+   const installRoot = join(dirname(dir), "install"), version = readFileSync(join(installRoot, "current-version"), "utf8").trim();
+   if (!/^[0-9A-Za-z._+-]+$/.test(version) || [".", ".."].includes(version)) return null;
+   const pkg = realpathSync(join(installRoot, "releases", version, "node_modules", "@earendil-works", "pi-coding-agent"));
+   const manifest = JSON.parse(readFileSync(join(pkg, "package.json"), "utf8"));
+   const bin = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.pi;
+   if (manifest.name !== "@earendil-works/pi-coding-agent" || typeof bin !== "string") return null;
+   const entry = realpathSync(resolve(pkg, bin)), inside = relative(pkg, entry);
+   if (inside.startsWith("..") || isAbsolute(inside) || !statSync(entry).isFile()) return null;
+   const node = findNode(env); if (!node) return null;
+   return { cmd: node, args: [entry], env: { PI_MANAGED_INSTALL_ROOT: installRoot }, hostDirect: true };
+  } catch { return null; }
+ }
+ const v1 = join(dir, "node_modules", "opencode-ai", "bin", "opencode.exe");
+ const template = '@ECHO off\nGOTO start\n:find_dp0\nSET dp0=%~dp0\nEXIT /b\n:start\nSETLOCAL\nCALL :find_dp0\n"%dp0%\\node_modules\\opencode-ai\\bin\\opencode.exe"   %*';
+ if (same(source, template) && existsSync(v1)) return { cmd: v1, args: [], hostDirect: true };
+ const v2 = join(dir, "node_modules", "@opencode", "cli", "bin", "opencode.exe");
+ if (same(source, '@echo off\n"' + v2 + '" %*') && existsSync(v2)) return { cmd: v2, args: [], hostDirect: true };
+ return null;
+}

package/magpie-plugin/README.md

@@ -0,0 +1,44 @@
+# magpie 网关插件
+
+可选集成：改写经过 magpie 网关的请求提示词，读取与 CLI 相同的人设和模式。
+
+**插件入口是本目录，不是仓库根目录。** 根 `package.json` 是 CLI；插件不在 agent-purge 的 npm 包里。
+
+## 安装
+
+```bash
+git clone https://github.com/ZiChuanLan/agent-purge
+agent-purge ls
+node /path/to/agent-purge/magpie-plugin/gen-personas.mjs
+magpie plugin add /path/to/agent-purge/magpie-plugin
+magpie plugin list
+```
+
+先运行一次 agent-purge 以初始化人设。增删人设后重新运行 `gen-personas.mjs`；生成的 `page/personas.js` 只属于本地，不提交。
+
+插件读取 `~/.agent-purge/`，也支持 `AGENT_PURGE_HOME`。切换 CLI 人设后，下一个经过网关的请求读取新设置。插件页设置会写入 magpie options。
+
+## 配置
+
+```bash
+magpie plugin options magpie-plugin '{"mode":"append"}'
+```
+
+上述插件名按安装目录名 `magpie-plugin` 使用。
+
+| 字段 | 用途 |
+|---|---|
+| `mode` | `off` / `strict` / `replace` / `append` |
+| `persona` | 人设标识 |
+| `agents` | 限定执行器，例如 `["claude","codex"]` |
+
+`off` 不改请求；`strict` 替换可控 system 文本；`replace` 近似删除身份行后放入人设；`append` 将人设置于宿主文本**之前**，与 CLI 的后置位置不同。
+
+## 边界与测试
+
+- 只处理经过网关的请求，不能修改客户端已经固定的行为或未经过网关的流量。
+- strict 会移除原 system 中的工具说明文本；不等于清空独立的结构化工具定义。
+- 插件页不能直接读取本地文件，人设列表由生成脚本提供。
+- `npm test` 包含钩子与页面逻辑回归，不依赖 magpie；这些测试不等于所有 magpie 版本的真实安装验收。
+
+[主项目](../README.md) · [使用指南](../docs/usage.md)