
agent-purge 是一款专为本地 Coding Agent 设计的系统提示词管理工具。它解决了不同 AI 编程助手读取系统提示词路径不一的问题,提供统一的注入、热切换与还原机制,确保提示词配置全程可控且可逆。
核心机制:三层注入与四模式切换
不同 Coding Agent 读取系统提示词的方式各异,有的依赖启动参数,有的依赖配置文件,有的需通过插件修改运行时对象。agent-purge 将复杂的适配工作统一为三个通道:
- install(常驻配置):将提示词写入目标 Agent 的托管配置块(如 Markdown 文件、hooks 或插件),对后续所有启动均生效。
- shim(命令拦截):在系统 PATH 环境变量前置同名小壳程序,将裸敲的命令转发给
agent-purge处理,实现无感接管。 - slash(会话热切换):在会话内通过
/purge on|off|status指令动态调整,不修改任何磁盘文件。
所有通道均调用同一份 personas/<id>.md 文件的内容。当执行 --mode off 或通过 Web 控制台关闭总开关时,系统会按字节还原至初始状态,不留任何配置残渣。
工具支持四种工作模式,以适应不同场景的需求:
- off:不干预请求,保持宿主 Agent 原有行为。
- strict:将 system 提示词整段替换为人设内容(宿主原有工具说明等会被清除,可能导致 Agent 基础能力受限)。
- append:将人设内容追加在宿主 system 提示词的最前方,保留宿主原有设定。
- replace:将人设内容置于前方,并尝试删除宿主 system 中明确提及模型名称或厂商的自称语句,以获得更干净的上下文。
人设管理与数据隔离
人设文件采用 frontmatter + 正文 的 Markdown 格式。正文即为注入系统提示词的实际内容;frontmatter 中的 description 字段用于在 Web 列表和命令行中显示说明,同时支持 order(排序)、harness 和 model 等可选匹配键。
- 数据独立存储:配置与状态默认保存在
~/.agent-purge/(Windows 下为C:\Users\<你>\.agent-purge\),包含state.json和personas/目录。 - 环境变量支持:可通过设置
AGENT_PURGE_HOME环境变量自定义数据存储路径,升级工具时不会覆盖现有数据。 - 便捷管理命令:提供
agent-purge ls(列出并高亮当前匹配的人设)、agent-purge use <id>(切换全局人设)以及agent-purge pi --persona <id>(仅在当前轮次使用特定人设)。
兼容性矩阵与实测数据
工具对主流 Coding Agent 的注入效果均经过本地真实请求体抓包实测,而非理论估算。以下是部分核心支持情况(展示默认 SYSTEM 长度与注入后长度的对比):
- codex (v0.163.0):通过启动参数注入,长度由 21,026 压缩至 24。
- claude (v2.1.304):通过
--system-prompt-file及二进制补丁清理残留,长度由 6,379 压缩至 156。 - grok (v1.0.62):通过
--system-prompt-override注入,长度由 5,146 压缩至 21。 - opencode (v1.19.3):原地修改 cwd 下插件的
output.system,长度由 19,332 压缩至 112。 - dsh (v0.2.1-rc.2):作为 cordis 插件注入各 profile,长度由 5,713 压缩至 68。
注:对于提示词固化在服务端或二进制文件中的闭源桌面端(如 qoder、workbuddy),工具仅做原样启动,不进行任何注入操作,并会明确打印原因,避免虚假生效。
进阶用法:Magpie 网关插件集成
若使用 magpie 本地网关统一管理各家 Agent 的请求,可安装 agent-purge 提供的可选网关插件。该插件直接在网关层改写请求体中的 system 段,无需逐个配置本地 harness,且切换人设无需重启服务。
- 安装方式:由于插件未发布至 npm,需通过本地路径安装:
magpie plugin add /path/to/agent-purge/magpie-plugin。 - 运行机制:插件读取本地的
~/.agent-purge/目录。在 magpie 的 Persona 页面点击切换后,下一个经过网关的请求即会应用新人设。 - 沙箱限制:插件运行在沙箱环境中,无网络请求与磁盘读取权限。人设清单需通过运行
node magpie-plugin/gen-personas.mjs脚本在本地生成。
安全边界与合规声明
agent-purge 在设计上严格遵循本地化与可逆性原则,明确划定了操作边界:
- 仅限提示词层面:只修改提示词相关的位置,不触碰二进制文件,不进行破解,不绕过任何软件授权机制。
- 全流程可逆:通过
uninstall、disarm或--mode off指令,可确保系统状态按字节还原。 - 数据不出本机:状态仅存储于本地的
state.json,不向任何外部服务器上传数据。 - 合规使用限定:本项目为非营利开源工具,仅供学习与研究。所有操作必须限制在用户有权管理的本机官方 harness 或合规实验室受控环境中,严禁用于任何未授权的网络探测、攻击或违法违规用途。
相关导航


Siftly

Hallmark

同事.skill

Web Clone · 网站复刻方法论

STE80 Humanizer

Miaoda App Builder Skill







