agent-purge

3周前更新 45 00

agent-purge 解决了多编程Agent人设不统一、切换繁琐、注入入口分散的痛点:一份人设全局生效,命令行+网页+会话三端可控,四种模式随时切换,并且做到修改无痕、一键还原。适合批量调试多Agent提示词、做对照实验,大幅减少反复修改配置文件的操作成本。

所在地:
ZiChuanLan
收录时间:
2026-10-29
agent-purgeagent-purge

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 控制台关闭总开关时,系统会按字节还原至初始状态,不留任何配置残渣。

工具支持四种工作模式,以适应不同场景的需求:

  1. off:不干预请求,保持宿主 Agent 原有行为。
  2. strict:将 system 提示词整段替换为人设内容(宿主原有工具说明等会被清除,可能导致 Agent 基础能力受限)。
  3. append:将人设内容追加在宿主 system 提示词的最前方,保留宿主原有设定。
  4. 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 或合规实验室受控环境中,严禁用于任何未授权的网络探测、攻击或违法违规用途。

相关导航