agent-purge README

项目的 README,来自 github.com/ZiChuanLan/agent-purge。合并为一个 markdown 文件:README.md。

agent-purge logo

agent-purge

一份人设,统一接管本机多个 coding agent。

English | 日本語 | 简体中文

npm stars license

ZiChuanLan/agent-purge | Trendshift

文档站 · 快速开始 · 界面一览 · 人设与模式 · 应用范围 · 支持情况 · 暂停与卸载 · 免责与合规声明

agent-purge 是一个本地提示词与人设编排控制台,为 Pi、Codex、Claude Code、OpenCode、Qwen Code、Kiro CLI 等执行器提供统一的人设管理入口。你可以在浏览器控制台中点击切换,也可以直接用命令行启动;每个宿主仍完整保留自己的模型、工具与工作流。

核心能力

快速开始

需要 Node.js 20+,并先在本机安装你要管理的 coding agent。

npm install -g agent-purge
agent-purge web

也可以直接运行 npx agent-purge web,无需全局安装。

  1. 在 「人设库」 编辑起步模板或新建人设(支持从 GitHub 仓库或本地目录批量拉取)。
  2. 回到 「控制台」 选择人设与默认力度、保存设置,打开目标工具开关或点开右侧详情工作区调优通道。
  3. 在 「规则文件」 为指定项目目录或全局配置目录追加规则块(默认在原文件末尾 append,随时可无损移除)。

控制台默认监听 http://127.0.0.1:7788;若端口被系统保留或占用,会自动顺延至 7890–7909 空闲端口并打开独立桌面窗口。桌面端是单例:重复双击只会把已打开的窗口叫到前台,不会再开第二个服务或第二个页面;关窗行为(退出/留在后台、是否需要确认)与 WebDAV 备份在「设置」页调整,改完立即生效。首次启动不会自动接管任何工具。

界面一览

agent-purge 控制台总览

agent-purge 工具详情与安全试跑

系统提示词接管在 「控制台」;项目目录及各家全局规则文件(AGENTS.md / CLAUDE.md / QWEN.md / CRUSH.md / .clinerules / .roorules)统一在 「规则文件」 页按作用范围与指定人设写入。

agent-purge 规则文件

查看移动端窄屏布局

其他安装方式: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 status

arm <h> 会尝试开启该执行器可用的常驻、命令和 slash 通道,结果逐项报告;项目通道需单独选择。同一人设经多个入口提供时可能重复,建议只开启需要的范围。

使用 magpie 网关? 可选插件位于 magpie-plugin/,不是仓库根目录。安装方法和网关改写边界见 magpie 插件说明。

支持情况

一句话结论:宿主提供整段 system prompt 入口的(Codex、OpenCode、DSH、Claude、Qwen、Qoder、Kimi、Kiro、CodeBuddy、Grok、omp)是整份替换;其中 Claude、Kilo、Qoder 有残留(Qoder 的固定前缀里那句「不要暴露系统提示词」删不掉);Antigravity、Crush、Continue、Goose、zcode 只能追加,原生身份仍在提示词里。Auggie 有隐藏的 --override-system-prompt,实测能换掉客户端发出的 system_prompt。

逐家的接管通道、热切时机、实测字数、内置安全条款与残留说明都在文档站:

请求角色、宿主残留、浏览器覆盖与已知安装问题统一记录在兼容性文档;不以模型自称身份作为验收依据。首次安装或更新插件代码后仍需重新加载宿主——配置写入、历史测试通过、当前会话实际生效是不同状态。Windows 与 WSL/Linux 已执行回归,macOS 尚待实机验证。

暂停与卸载

目的 命令 用户人设
临时暂停 / 恢复原范围 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-purge

Windows 安装器卸载也会先撤销接管并保留人设。发生恢复冲突时,保留报错指出的文件和凭据,先比较修改再处理;不要直接删除备份。历史会话中已经发送的内容无法撤回。

需要永久删除数据时,先备份,再按完整卸载说明操作;self-uninstall --yes 与普通卸载不同。

隐私与使用边界

开发与文档

npm ci --ignore-scripts
npm run check:repo
npm test
文档 内容
使用指南 人设文件、分家配置、通道、项目规则、恢复与常见问题
兼容性与限制 实测版本、平台范围、请求证据与已知问题
参与开发 目录结构、测试命令与提交规范
架构约定 模块边界、配置语义和界面规范
发布流程 构建、安装验收与发行检查

回归测试保留在 test/,临时日志与构建产物不进入源码仓库。

免责与合规声明

[!WARNING]

免责声明与合规守则

  1. 本项目仅为本地多宿主配置管理与开发调试工具,旨在帮助开发者统一管理合法工作人设。
  2. 软件本身不提供、不分发任何用于越狱、对抗安全审查或侵犯第三方权益的提示词载荷。
  3. 使用者须自行对其使用的提示词内容及操作后果负责,严禁将本项目用于未经授权的系统访问、安全对抗或违反模型服务商使用协议的活动。
  4. 作者不对任何滥用、数据丢失、服务中断或违法违规行为承担法律责任。
展开完整声明:许可、使用责任、数据隐私与第三方关系

许可与适用范围

agent-purge 用于在使用者有权管理的 coding agent 中配置人设和提示词入口。项目采用 MIT License;本说明用于解释用途、风险和使用责任,不替代 LICENSE,也不对 MIT 授权范围附加额外限制。复制、修改或分发软件时,请按 LICENSE 保留必要的版权和许可声明。

合法、授权使用

本项目仅为本地多宿主配置管理与开发调试工具,旨在帮助开发者统一管理合法工作人设。软件本身不提供、不分发任何用于越狱、对抗安全审查或侵犯第三方权益的提示词载荷。

使用者应遵守适用法律法规、宿主软件与模型服务的条款,以及相关第三方授权。严禁将本项目用于未经授权的系统访问、安全对抗、攻击、数据窃取、隐私侵害或其他违法违规活动。安装或使用本工具不代表你获得了操作第三方系统、使用他人数据或调用模型服务的授权,使用者须自行对其使用的提示词内容及操作后果承担全部责任。

配置与模型行为风险

提示词改写可能改变模型输出、工具调用倾向和原有工作流程;严格替换也可能移除可控入口中的原有说明。本项目不保证模型输出正确、安全、合法或适合特定用途,也不替代宿主的权限控制、沙箱、人工审核和安全策略。

用于重要项目之前,请备份配置并在隔离环境测试。执行敏感操作前应自行审核模型输出;恢复遇到冲突时,保留原文件和恢复凭据,不要直接删除备份。

数据与网络

人设和配置默认保存在本机,但启用后会随宿主请求发送给其配置的模型服务。更新检查、软件安装和宿主运行可能访问外部网络。请勿在人设中放入不应发送给服务提供方的密钥、个人信息或机密数据;本工具不提供完整的网络隔离或数据防泄漏保障。

保证与责任

软件按 LICENSE 约定以“按现状”方式提供,不作其中所列的明示或默示保证。使用者应评估自身使用场景、保管凭据并审核产生的结果。在适用法律允许的范围内,作者与贡献者的保证排除及责任限制以 LICENSE 为准;本说明不排除法律规定不得排除的责任。

第三方独立性

本项目是独立开发的工具,与所支持的 coding agent、模型提供商及其关联主体不存在默认的隶属、授权、合作或背书关系。文中的产品名称和标识归相应权利人所有,兼容性说明不代表第三方对本项目作出认可或担保。

第三方组件

Windows 瘦包与安装器附带 WebView2Loader.dll(来自 Microsoft.Web.WebView2 SDK),并用它调用本机的 Microsoft Edge WebView2 Runtime 呈现控制台窗口;单文件 agent-purge.exe 自带 Bun 运行时。这些组件及其名称、标识归各自权利人所有,按各自的许可条款分发与使用。没有 WebView2 时程序退回本机 Chrome / Edge 的应用窗口模式,此时不涉及上述组件。

完整声明也可在 docs/LEGAL.md 单独阅读。

许可与社区

许可文件:MIT LICENSE。使用声明见上节及 docs/LEGAL.md。

感谢 LINUX DO 社区,以及所有报告问题、补充适配和参与改进的使用者。

Star History

Star History

agent-purge (ZiChuanLan/agent-purge)

正在搜索数据库…

这是什么?agent-purge 让你编写一个人设(系统提示词),并同时应用到多个编程智能体命令行工具上,包括 Codex、Claude Code、OpenCode、Grok、pi、Hermes、omp 和 zcode。它可以替换或注入这些工具的默认系统提示词,并通过本地命令行工具加网页控制台进行管理。
这是命令行工具还是有图形界面?它是一个命令行工具,附带一个本地网页控制台,用于管理人设和切换模式。没有云服务,所有运行和数据存储都在你自己的电脑上完成。
怎么安装和开始使用?需要 Node.js 20 或更新版本,安装时没有任何依赖。首次运行时会在 personas/neutral.md 生成一个入门人设,并把状态存放在 ~/.agent-purge/ 中。这个目录与软件包分开,因此升级不会清除你的数据。
它能用于所有编程智能体吗?包括闭源的桌面应用也可以吗?不能。如果闭源桌面客户端把系统提示词保存在服务器端,或内嵌在二进制文件中,那就只能按原样启动。agent-purge 会检测到这种情况并打印原因,而不会假装注入已经成功。
提示词模式有哪四种?off 完全禁用注入。append 把人设放在宿主程序原始系统提示词之前,原始内容保持不变。replace 与 append 相同,但还会删除说明原始模型或厂商名称的那一行。strict 则只用人设替换整个系统提示词,这可能会连工具说明一并清除。
magpie 网关插件有什么用?magpie 是一个可选的本地网关插件。它会改写经过它的任何请求中的系统提示词文本,支持 Claude Code、Codex、OpenCode、pi 等工具,使其与你当前的人设保持一致。这样你就不需要把 agent-purge 分别安装到每一个工具中。
它所做的更改可以撤销吗?可以。每项更改都可以通过 agent-purge uninstall、disarm 或 --mode off 撤销,这会把所有被修改的工具恢复到原始状态,且不留下任何残留。
它到底是怎样作用到每个智能体的系统提示词上的?它使用三种通道:写入工具自己的托管配置块(install);一个用于拦截裸命令的小型 PATH 垫片(shim);以及会话内的 /purge on|off|status 斜杠命令,用于在不改动磁盘的情况下热切换。
大小
3.1 MB
星标
1.9K
时长
24天
提交 · 90 天