一份人设，统一接管本机多个 coding agent。
agent-purge 是一个本地提示词与人设编排控制台，为 Pi、Codex、Claude Code、OpenCode、Gemini CLI、Qwen Code、Kiro CLI 等执行器提供统一的人设管理入口。你可以在浏览器控制台中点击切换，也可以直接用命令行启动；每个宿主仍完整保留自己的模型、工具与工作流。
- 一份人设，多端入口：CLI 与 Web 共用同一份人设库与账本，支持单次启动、常驻配置、会话内
/purge热切与按目录写入项目规则。 - 能力诚实、分家自治：默认跟随全局人设与改写力度，也可按工具单独覆写；界面严格按各家实测支持度展示可用通道与力度，不摆假开关。
- 支持热切，也明示边界：Pi / omp / OpenCode / dsh 等具备每轮回调的动态通道下一轮即生效；静态配置或启动参数入口明示需新开会话。
- 文件共享与原子可逆：项目规则按
AGENTS.md/CLAUDE.md/GEMINI.md/QWEN.md文件共享托管，支持写入前 diff 预览与 SHA 冲突检测；每次写入均保留原字节stash快照，随时可逐位撤回。 - 零生产依赖、本地优先：无外部后端、不上传配置，数据保存在独立目录（默认
~/.agent-purge/），升级不覆盖用户人设。
需要 Node.js 20+，并先在本机安装你要管理的 coding agent。
npm install -g agent-purge
agent-purge web也可以直接运行 npx agent-purge web，无需全局安装。
- 在 「人设库」 编辑起步模板或新建人设（支持从 GitHub 仓库或本地目录批量拉取）。
- 回到 「控制台」 选择人设与默认力度、保存设置，打开目标工具开关或点开右侧详情工作区调优通道。
- 在 「规则文件」 为指定项目目录或全局配置目录追加规则块（默认在原文件末尾 append，随时可无损移除）。
控制台默认监听 http://127.0.0.1:7788；若端口被系统保留或占用，会自动顺延至 7890–7909 空闲端口并打开独立桌面窗口。首次启动不会自动接管任何工具。
系统提示词接管在 「控制台」；项目目录及各家全局规则文件（AGENTS.md / CLAUDE.md / GEMINI.md / QWEN.md / CRUSH.md / .clinerules / .roorules）统一在 「规则文件」 页按作用范围与指定人设写入。
其他安装方式：Windows 安装器、便携包与无桌面环境
| 形式 | 运行要求 | 适用场景 |
|---|---|---|
| npm | Node.js 20+ | 用 npm 安装与升级 |
agent-purge-<版本>-setup.exe |
Windows，外部 Node.js 20+ | 图形安装和卸载 |
agent-purge-<版本>.zip |
Windows，外部 Node.js 20+ | 解压后使用 |
agent-purge.exe |
Windows x64，自带运行时 | 无需另装 Node 的独立便携版 |
agent-purge-<版本>-darwin-arm64.dmg / x64.dmg |
macOS 12+（Apple Silicon / Intel，自带运行时） | 未签名 .app 磁盘镜像，拖入 /Applications 后首次需右键「打开」或 xattr -cr 放行 |
agent-purge-<版本>-linux-x64 / -linux-arm64 |
主流 Linux 发行版（自带运行时） | 单文件二进制，chmod +x 后直接运行 |
agent-purge-<版本>-linux-<架构>.tar.gz |
主流 Linux 发行版 | 便携包，含 .desktop、图标与免 root 的 install.sh |
agent-purge-<版本>-linux-<架构>.deb |
Debian / Ubuntu 及衍生版 | sudo apt install ./*.deb，注册 /usr/bin/agent-purge 与桌面入口 |
agent-purge-<版本>-linux-<架构>.AppImage |
主流 Linux 发行版（存在时才有） | 双击或用 --appimage-extract-and-run 直接启动控制台 |
下载附件以实际 GitHub Releases 为准；未发布的版本没有附件。请核对 SHA-256 和签名状态，未签名程序可能出现系统提示。ZIP 中的 EXE 是薄启动器，不是自带运行时的独立版。
SSH / WSL 等无桌面环境使用 agent-purge web --no-open。Web 仅监听本机；Linux 可用 npm / 源码入口或 Release 里的二进制、.tar.gz、.deb（AppImage 随 runner 能力可选生成），macOS 可用 npm / 源码或 .dmg 镜像（.dmg 未经 Apple 签名与公证）。平台验证范围见兼容性说明。
控制台右上角的版本角标点开就是升级入口，按安装形态自动选路：独立 EXE 下载并就地热替换、npm 全局安装调 npm install -g、源码检出（git clone 后直接 node bin/agent-purge.mjs）在安装目录执行 git pull --ff-only，不下载任何发布产物。源码检出的「有没有更新」按上游提交算，版本号没变也会提示；工作区有未提交改动、处于游离 HEAD 或分支没有上游时一律拒绝并说明原因。
人设正文决定要提供给执行器的提示词；名称和说明只用于管理。首次运行会生成 neutral 起步模板，你可以在 Web 中直接编辑，也可以创建自己的 Markdown 文件。
agent-purge ls # 查看人设
agent-purge use <id> # 切换并同步已选范围
agent-purge mode append # 修改全局模式
agent-purge use <id> --for codex # 只给 Codex 指定人设
agent-purge use follow --for codex # 恢复跟随全局| 模式 | 行为 | 注意 |
|---|---|---|
replace（默认） |
优先替换宿主身份行，尽量保留其他说明 | 身份识别是近似处理；无法读取宿主文本的启动入口按 strict 执行 |
strict |
用人设替换可控入口中的宿主文本 | 该入口原有说明也会移除；宿主仍可能添加额外文本 |
append |
保留宿主说明，另加一份人设 | 不替换原身份，需注意规则冲突 |
off |
停止相应入口注入 | 全局暂停与单次启动参数的作用范围不同 |
strict 不等于“模型只收到人设”。 实际角色可能是 system、developer 或项目上下文，取决于宿主和通道。希望保留宿主说明时，可先试 append。
手写人设示例与存储位置
将以下内容保存为 ~/.agent-purge/personas/concise.md，然后执行 agent-purge use concise：
---
id: concise
name: 简洁协作
description: 中文、先结论、修改前先读代码
---
用简体中文协作。先给结论，再给依据。
修改代码前先阅读现有实现；不确定时明确说明。只有正文进入提示词。description 用于列表说明，旧键 desc 仍兼容；Web 编辑会保留未涉及的元数据。高级匹配、排序与数据目录配置见使用指南。
也可参考维护者的 some-magic 人设仓库。
只想临时使用，可以通过 agent-purge 启动一次，不必登记常驻通道：
agent-purge codex --mode append
agent-purge pi --ask "解释这段代码"
agent-purge codex -- --help # -- 后的参数交给宿主要让其他启动入口也读取配置，再按需选择以下通道：
| 通道 | 做什么 | 生效时机 |
|---|---|---|
install |
写入宿主的托管配置或插件 | 静态配置需新会话；已加载动态插件下一轮读取 |
shim |
通过 PATH 中的同名命令转发启动 | 下一次从该命令启动 |
slash |
安装会话内 /purge 扩展 |
取决于宿主扩展和启用状态 |
project |
写入指定目录的项目规则文件 | 对应目录的新会话 |
agent-purge install codex
agent-purge arm pi --slash
agent-purge project on pi --dir /path/to/project
agent-purge statusarm <h> 会尝试开启该执行器可用的常驻、命令和 slash 通道，结果逐项报告；项目通道需单独选择。同一人设经多个入口提供时可能重复，建议只开启需要的范围。
使用 magpie 网关？ 可选插件位于 magpie-plugin/，不是仓库根目录。安装方法和网关改写边界见 magpie 插件说明。
以下为支持范围与当前验证程度；请求级验证只覆盖表中明确说明的宿主，不是对所有版本的兼容承诺。
| 执行器 / 宿主 | 已验证版本 | 主要接管通道 | 同会话热切 | 验证状态与实测说明 |
|---|---|---|---|---|
| pi / omp | 1.4.0 / 18.14.1 | 会话扩展 / 插件 | 支持（/purge 热切） |
动态扩展已实测；四模式抓包通过 |
| OpenCode 1.x / 2.x | 1.19.5 / 2.2.5 | 插件机制 | 支持（同会话注入） | 插件挂载已实测 |
| DSH (DeepSeek Harness) | 0.2.1-rc.5 | 配置 / SDK / 插件 | 支持（SDK 同会话） | headless/web/desktop 三形态四模式已抓包 |
| Codex | 0.166.0 | 启动参数 / 规则文件 | 需新会话 | 启动入口已验证；固定替换身份 |
| Claude Code | 2.1.316 | 启动参数 / 规则文件 | 需新会话 | 启动入口与 CLAUDE.md 规则已验证；支持替换与追加 |
| CodeBuddy / Grok | 2.179.0 / 1.0.73 | 启动入口 / 规则文件 | 需新会话 | 启动参数与配置文件已验证 |
| Qwen Code | 0.27.2 | 启动参数 (--system-prompt / --append-system-prompt) |
需新会话 | 启动参数已验证，支持整段覆盖与末尾追加；长人设受命令行长度限制 |
| Gemini CLI | 0.68.0 | 环境变量 (GEMINI_SYSTEM_MD) |
需新会话 | 真实包 PromptProvider 替换 core system prompt 已验证 |
| Crush | v0.100.0 | 全局规则 (CRUSH.md) / AGENTS.md |
需新会话 | 真实 Windows release 实测；追加系统上下文，写托管块原子可逆 |
| Continue CLI | 1.5.47 | 启动参数 (--rule) |
需新会话 | 真实安装 @continuedev/cli；--rule 追加规则/上下文 |
| Qoder CLI | 1.1.87 | 启动参数 (--system-prompt / --append-system-prompt) |
需新会话 | 真实安装 @qoder-ai/qodercli；两个参数入口已验证，支持替换与追加 |
| Kimi Code | 2.5.3 | 启动参数 (--agent-file) |
需新会话 | 真实安装 @moonshot-ai/kimi-code；Markdown 正文作为 system prompt 替换 |
| Auggie CLI | 0.37.1 | 启动参数 (--rules) |
需新会话 | 真实安装 @augmentcode/auggie；--rules 追加规则/上下文 |
| Goose | 1.59.0 | 启动参数 (session/run --system) |
需新会话 | 真实 release 实测；--system 追加系统指令，BYOK 跑通 |
| Kiro CLI | 3.2.0 | 启动参数 (--agent) / Custom Agent |
需新会话 | --agent 参数与自定义 agent prompt 字段替换已实测 |
| Kilo Code | @kilocode/cli 7.8.18 | 配置覆盖 (code.md) / AGENTS.md |
需新会话 | off/strict/replace/append 四模式真实抓包；system 层 marker=1 |
| Antigravity (agy) | CLI 1.5.3 / 语言服务 1.23.x | 全局规则 (~/.gemini/config/AGENTS.md) |
需新会话 | 四模式真实抓包；落 system 层 <user_rules>，规则段优先级压住 |
| WorkBuddy / WorkBuddy AI | 5.9.3 / 5.9.4 | 配置文件写入 (app-config.json) |
需新会话 | 国际版与国内版上下文写入已实测 |
| PI-Desktop | 0.21.0（便携版） | 常驻配置 (SYSTEM.md) / 导入插件 |
支持（插件同会话下一轮生效） | 常驻配置写入与 imported 插件热切已实测 |
Cursor、Devin CLI、Copilot CLI、Amp、Cline、Roo Code、Gemini CLI、Qwen Code、Crush 的规则文件已接入「规则文件」页；其中 Cursor / Devin / Copilot / Amp / Cline / Roo 只写规则，不替换主 agent 的 system prompt。Muse Code 目前没有可安装的 CLI，暂不接入。
首次安装或更新插件代码后，仍需重新加载宿主。配置写入、历史测试通过、当前会话实际生效，是不同状态。
Windows 与 WSL/Linux 已执行回归，macOS 尚待实机验证。Hermes、zcode 未计为本轮通过。请求角色、宿主残留、浏览器覆盖与已知安装问题统一记录在兼容性与限制，不以模型自称身份作为验收依据。
| 目的 | 命令 | 用户人设 |
|---|---|---|
| 临时暂停 / 恢复原范围 | agent-purge pause / agent-purge resume |
保留 |
| 仅撤销一家常驻配置 | agent-purge uninstall dsh |
保留，其他通道不变 |
| 撤销一家全部已选通道 | agent-purge disarm dsh |
保留 |
| 撤销所有登记的接管 | agent-purge clean |
保留 |
卸载 npm 程序时，先撤销接管，再移除程序：
agent-purge clean
npm uninstall -g agent-purgeWindows 安装器卸载也会先撤销接管并保留人设。发生恢复冲突时，保留报错指出的文件和凭据，先比较修改再处理；不要直接删除备份。历史会话中已经发送的内容无法撤回。
需要永久删除数据时，先备份，再按完整卸载说明操作；self-uninstall --yes 与普通卸载不同。
- 本机管理：默认数据目录为
~/.agent-purge/；Windows 对应C:\Users\<用户>\.agent-purge\。可通过AGENT_PURGE_HOME调整，程序升级不会覆盖这份目录。 - 模型请求仍会联网：启用后，人设会随宿主请求发送给其配置的模型服务；本地管理不等于离线运行。更新检查也会访问 GitHub。
- 不直接修改宿主权限：项目管理提示词和配置入口，不破解宿主、不绕过授权；不保证改写后的模型行为。
- 只在有权管理的环境使用：Web 仅监听
127.0.0.1，不要直接暴露到公网。完整要求见下方声明。
npm ci --ignore-scripts
npm run check:repo
npm test| 文档 | 内容 |
|---|---|
| 使用指南 | 人设文件、分家配置、通道、项目规则、恢复与常见问题 |
| 兼容性与限制 | 实测版本、平台范围、请求证据与已知问题 |
| 参与开发 | 目录结构、测试命令与提交规范 |
| 架构约定 | 模块边界、配置语义和界面规范 |
| 发布流程 | 构建、安装验收与发行检查 |
回归测试保留在 test/，临时日志与构建产物不进入源码仓库。
Warning
- 本项目仅为本地多宿主配置管理与开发调试工具，旨在帮助开发者统一管理合法工作人设。
- 软件本身不提供、不分发任何用于越狱、对抗安全审查或侵犯第三方权益的提示词载荷。
- 使用者须自行对其使用的提示词内容及操作后果负责，严禁将本项目用于未经授权的系统访问、安全对抗或违反模型服务商使用协议的活动。
- 作者不对任何滥用、数据丢失、服务中断或违法违规行为承担法律责任。
- 合法、授权使用：请遵守适用法律、宿主及模型服务条款，不用于未经授权的访问、攻击、数据窃取或其他违法活动。
- 使用前评估风险：提示词改写可能影响模型行为。请先备份配置、在隔离环境测试，并审核重要操作与输出。
- 按现状提供：软件的许可、保证排除与责任限制以 MIT LICENSE 为准；本说明不附加与其冲突的授权限制。
展开完整声明：许可、使用责任、数据隐私与第三方关系
agent-purge 用于在使用者有权管理的 coding agent 中配置人设和提示词入口。项目采用 MIT License；本说明用于解释用途、风险和使用责任，不替代 LICENSE，也不对 MIT 授权范围附加额外限制。复制、修改或分发软件时，请按 LICENSE 保留必要的版权和许可声明。
本项目仅为本地多宿主配置管理与开发调试工具，旨在帮助开发者统一管理合法工作人设。软件本身不提供、不分发任何用于越狱、对抗安全审查或侵犯第三方权益的提示词载荷。
使用者应遵守适用法律法规、宿主软件与模型服务的条款，以及相关第三方授权。严禁将本项目用于未经授权的系统访问、安全对抗、攻击、数据窃取、隐私侵害或其他违法违规活动。安装或使用本工具不代表你获得了操作第三方系统、使用他人数据或调用模型服务的授权，使用者须自行对其使用的提示词内容及操作后果承担全部责任。
提示词改写可能改变模型输出、工具调用倾向和原有工作流程；严格替换也可能移除可控入口中的原有说明。本项目不保证模型输出正确、安全、合法或适合特定用途，也不替代宿主的权限控制、沙箱、人工审核和安全策略。
用于重要项目之前，请备份配置并在隔离环境测试。执行敏感操作前应自行审核模型输出；恢复遇到冲突时，保留原文件和恢复凭据，不要直接删除备份。
人设和配置默认保存在本机，但启用后会随宿主请求发送给其配置的模型服务。更新检查、软件安装和宿主运行可能访问外部网络。请勿在人设中放入不应发送给服务提供方的密钥、个人信息或机密数据；本工具不提供完整的网络隔离或数据防泄漏保障。
软件按 LICENSE 约定以“按现状”方式提供，不作其中所列的明示或默示保证。使用者应评估自身使用场景、保管凭据并审核产生的结果。在适用法律允许的范围内，作者与贡献者的保证排除及责任限制以 LICENSE 为准；本说明不排除法律规定不得排除的责任。
本项目是独立开发的工具，与所支持的 coding agent、模型提供商及其关联主体不存在默认的隶属、授权、合作或背书关系。文中的产品名称和标识归相应权利人所有，兼容性说明不代表第三方对本项目作出认可或担保。
完整声明也可在 docs/LEGAL.md 单独阅读。
许可文件：MIT LICENSE。使用声明见上节及 docs/LEGAL.md。
感谢 LINUX DO 社区，以及所有报告问题、补充适配和参与改进的使用者。