agent-purge 教程：统一管理 Coding Agent 系统提示词与 Persona

agent-purge 是什么

agent-purge 是一套面向多个 Coding Agent 的系统提示词管理工具。不同 Agent 可能通过启动参数、配置文件、Hook 或插件读取提示词，而 agent-purge 将这些差异封装起来，让用户围绕同一份 Persona 内容完成注入、切换和撤回。

项目支持三种模式：

• replace：使用 Persona 正文替换目标系统提示词。
• append：将 Persona 正文追加到现有提示词。
• off：关闭注入并撤回改动。

模式可以热切换。关闭 Web 总开关或使用 --mode off 后，工具会将相关改动恢复到原样，不留下托管注入残渣。

核心机制与功能

三种统一通道

agent-purge 使用三个通道适配不同 Harness。三层通道最终使用的都是当前 personas/<id>.md 文件正文。

• install：向目标 Harness 写入托管配置块，可能采用 Markdown、Hooks 或插件机制。它属于常驻配置，其他人直接启动对应 Harness 时也会生效。
• shim：在 PATH 前面放置同名命令壳，再把调用转发给 agent-purge <h>，从而接管直接输入的原始命令。
• slash：在会话中通过 /purge on、/purge off 或 /purge status 热切换，不修改磁盘配置。

本地化与可逆性

项目只修改与提示词有关的位置，不修改二进制文件，也不破解或绕过授权。状态保存在本机的 state.json 中，不会上传。可以通过卸载、解除接管或关闭模式恢复原始状态。

agent-purge uninstall <h>
agent-purge disarm
agent-purge <h> --mode off

具体 Harness 支持哪些通道，应以本机运行时检测结果为准。

安装前提

运行 agent-purge 需要 Node.js 20 或更高版本。项目本身零依赖，可通过 npm 全局安装，也可以使用 npx 直接打开 Web 控制台。

安装与首次运行

方式一：全局安装

npm i -g agent-purge

安装完成后，可以直接运行：

agent-purge web

本地控制台默认地址为 http://127.0.0.1:7788。在浏览器中打开该地址，即可查看和管理 Persona、Harness 状态及总开关。

方式二：通过 npx 启动

如果不想先进行全局安装，可以直接运行：

npx agent-purge web

数据目录

配置与 Persona 不放在 npm 包目录中，因此升级软件包不会覆盖用户数据。默认位置如下：

• Linux 与 macOS：~/.agent-purge/
• Windows：C:\Users\<你>\.agent-purge\

目录中主要包含 state.json 和 personas/。首次运行时，工具会在 Persona 目录中生成 neutral.md 起步模板。

如果曾使用 0.1.x 版本，首次运行新版时会自动迁移原先位于包目录中的数据，同时保留原文件。

自定义数据存储位置

可以通过 AGENT_PURGE_HOME 环境变量指定独立数据目录。这适合需要备份 Persona、区分工作环境或将配置放到其他磁盘的场景。

Linux 或 macOS

export AGENT_PURGE_HOME=/path/to/your/data

Windows

setx AGENT_PURGE_HOME D:\ap-data

设置后，应在新的终端会话中运行 agent-purge，以确保环境变量已经生效。

理解与管理 Persona

每个人设对应一个 personas/<id>.md 文件。文件由 Frontmatter 和正文组成，其中正文是实际写入系统提示词的内容。

Frontmatter 支持以下字段：

• description：Persona 说明，会显示在 Web 列表和 agent-purge ls 输出中。
• desc：旧版说明字段，仍然兼容。
• order：可选的排序信息。
• harness：可选的 Harness 匹配信息。
• model：可选的模型匹配信息。

在 Web 控制台中只修改名称和说明时，其他 Frontmatter 键会被保留，不会整段覆盖。

列出 Persona

agent-purge ls

该命令会列出全部 Persona，并标记当前匹配项。同时，它还会展示运行期检测到的 Harness 安装情况、版本、注入层以及各通道的可用性。

切换当前 Persona

agent-purge use <id>

这里的 <id> 对应 personas/ 目录中 Persona 文件的名称标识。切换后，后续受管调用将使用该 Persona。

仅为一次调用指定 Persona

如果不想改变当前全局选择，可以只在本轮调用中指定另一个 Persona：

agent-purge pi --persona <id>

这种方式适合临时测试不同提示词效果，调用结束后不会把该 Persona 当作后续调用的默认选择。

基本使用示例

启动 Web 控制台

agent-purge web

随后访问 http://127.0.0.1:7788。控制台可用于查看运行状态以及操作总开关。关闭总开关时，注入会被撤回。

使用当前 Persona 启动 Codex

agent-purge codex

agent-purge 会根据对应 Backend 和本机运行环境处理启动，并尝试通过该 Harness 实际可用的机制应用当前 Persona。

向 pi 发起一次性提问

agent-purge pi --ask "请检查这个项目的错误处理逻辑"

该命令使用当前 Persona 启动一次调用，并将 --ask 后面的内容作为本轮问题。

会话内热切换

对于支持 Slash 通道的 Harness，可以在会话内使用：

/purge on
/purge status
/purge off

• /purge on：启用 Persona 注入。
• /purge status：查看当前状态。
• /purge off：关闭注入，同时不修改磁盘配置。

如何确认注入是否真的生效

matrix.json 保存的是静态能力矩阵，但静态声明不一定等同于当前机器上的真实状态。版本差异、安装方式和 Harness 自身变化都可能影响通道可用性。

因此，应优先查看 agent-purge ls 或 Web 控制台给出的运行期信息。它们会反映：

• Harness 是否已经安装。
• 检测到的 Harness 版本。
• 提示词位于 SYS 还是 USER 注入层。
• install、shim 和 slash 三个通道是否可用。

当静态能力表与运行期检测结果冲突时，以运行期结果为准。

高级使用技巧

为不同任务准备多个 Persona

可以在 personas/ 下维护多个 Markdown 文件，例如分别用于代码审查、重构建议或日常开发协作。使用 description 写清用途，并通过 order 调整显示顺序；需要限定匹配范围时，可使用 harness 或 model 字段。

切换前先运行：

agent-purge ls

确认目标 Persona 后再执行：

agent-purge use <id>

区分长期配置与临时实验

• 需要常驻生效时，使用目标 Harness 支持的 install 通道。
• 希望直接输入原命令也由 agent-purge 接管时，使用 shim 通道。
• 只想在当前会话测试时，优先使用 slash 通道或单次 --persona 参数。

是否可使用某种通道，仍需以运行期检测结果为准。

修改前保留恢复路径

虽然项目会保存状态并提供可逆操作，实际使用时仍建议先确认当前 Persona、目标 Harness 和启用模式。测试完成后，可以使用以下方式撤回：

agent-purge uninstall <h>
agent-purge disarm

也可以切换到 --mode off，或在 Web 控制台中关闭总开关。

不要把原样启动误认为注入成功

对于系统提示词位于服务端或封闭二进制中的闭源桌面端，agent-purge 只会原样启动，不会执行提示词注入。运行 agent-purge <h> 时，工具会明确输出无法注入的原因，而不会伪装成已经生效。

项目结构速览

• bin/：CLI 入口。
• lib/：状态、Persona、注入、通道和检测逻辑。
• backends/：各 Harness 的启动参数与身份句处理。
• web/：本地控制台，包括 server.mjs 和 ui.html。
• bench/：注入成功率实测与裁判脚本，仅用于开发，不参与正常运行。
• matrix.json：静态能力矩阵。

安全、隐私与合规边界

agent-purge 定位于用户有权管理的本机官方 Harness，用于提示词工程与鲁棒性评测。它不修改二进制文件，不绕过授权，不向外上传本地状态，也不应被用于未经授权的系统。

• 仅在本人有权控制的设备、软件和合规实验环境中使用。
• 不得用于未授权攻击、漏洞利用、数据窃取、非法侵入或恶意载荷传播。
• 不得违反适用法律法规、模型服务条款与滥用政策。
• 项目按 MIT 许可证“按现状”提供，使用者应对自己的输入、输出和使用行为负责。
• 借用项目名称、思路、代码或提示词时，应按仓库声明进行署名并标明来源。

README 还对特定地区服务器和网站的访问作出了严格限制。实际使用前，应完整阅读仓库中的免责与合规声明，并确保操作范围符合其要求。

总结

agent-purge 将多个 Coding Agent 不一致的提示词入口统一为 Persona、install、shim 和 slash 等概念，并提供 Web 控制台、运行期检测与可逆撤回能力。入门时可以先安装工具、打开 Web 控制台、运行 agent-purge ls 检查支持情况，再选择 Persona 启动目标 Harness。对于临时实验，优先使用单次 Persona 或会话热切换；对于长期配置，则应在确认运行期能力和合规边界后再启用常驻通道。