desktop、web、headless 三形态通吃:agent-purge 的 dsh cordis 插件通道揭秘
desktop、web、headless 三形态通吃:agent-purge 的 dsh cordis 插件通道揭秘
agent-purge 是一款面向多 coding agent 的系统提示词注入工具:一份 persona 人设,可同时喂给 codex、claude、opencode、grok、omp、hermes、pi、zcode 等各家编码智能体,支持热切换、全程可逆。这篇文章以 dsh(DeepSeek Harness) 为例,揭秘 agent-purge 里最有意思的一块设计:如何用一套 cordis 插件代码,同时覆盖 desktop、web、headless 三种运行形态。
为什么 dsh 特殊:一份软件,三种形态
agent-purge 支持表里的大多数 harness 只有一个入口(启动参数或配置文件),而 dsh 有三种形态并行:
- desktop:Electron 桌面端,profile 被 Electron 进程独占;
- web:网页形态;
- headless:命令行形态,可直接
dsh --profile headless启动。
三种形态各用一个独立的 profile 目录(~/.dsh/profiles/<name>/),各自有独立的配置和插件发现路径。换句话说,"装一个插件"不是装一处,而是装三处。
README.md 里的表述很直白:dsh "desktop / web / headless 共用一套 cordis 插件,装在各自 profile 的 node_modules/agent-purge/,并在 cordis.patch.yml 里 - insert 挂上,不改 app.asar"。
三个插件名分工协作
dsh 通道背后不是单个插件,而是三个互不覆盖的插件名,分工见 lib/dsh.mjs 的注释与 lib/dsh.mjs 的常量定义:
| 插件名 | 职责 | 生命周期 |
|---|---|---|
agent-purge |
常驻注入:每轮请求现读 state.json 和当前人设 |
直到卸载 |
agent-purge-slash |
注册会话内 /purge 热切命令,不碰系统提示词 |
直到卸载 |
agent-purge-session |
一次性注入,人设快照直接编译进插件源码 | 进程退出即删 |
三个名字是刻意错开的:终端敲 agent-purge dsh 走一次性的 agent-purge-session,不会顶掉常驻的 agent-purge;装 /purge 热切命令时走 agent-purge-slash,又不会覆盖注入逻辑。一次性启动的组装逻辑在 backends/index.mjs。
两个值得注意的设计:
- 常驻插件不写死人设:每一轮都现读
state.json和personas/active.md。切换人设、改模式、/purge off全部下一轮生效,无需重启。 - 插件知道自己在哪个形态里:通过自身路径
profiles/<name>推断 desktop / web / headless,运行日志dsh.log一行一条(写失败静默),出问题时能定位到具体形态。
一条 cordis.patch.yml 挂载是怎么生效的
dsh 的 cordis 生态支持 patch 层:每个 profile 目录下的 cordis.patch.yml 可以声明额外插件。agent-purge 在每个 profile 里写入的是一段带标记的内容:
# >>> agent-purge:agent-purge
- insert:
- id: agent-purge
name: agent-purge
# <<< agent-purge:agent-purge
标记块由 # >>> agent-purge:<name> 成对包裹,对三个 profile 幂等写入(同一段不会重复追加),核心实现在 lib/dsh.mjs:
- 预检拒绝覆盖:同名目录若已存在,且其
package.json里没有 agent-purge 写的agentPurge: true标记,直接抛错拒绝——不碰别人的同名包; - 原子安装:先登记再动手,中途任何一步抛错,就按相反顺序回滚本轮已写的全部文件。"宁可完全没装,也不留半套";
- 按字节卸载:只删标记之间的那一段。当初若整份替换过原文件,原文副本藏在插件目录的
.patch.before里,卸载时整份还原;原本没有该文件的,卸载后直接删掉,不留空壳。
还有个细节很见功力:只装进 dsh 自己建过的 profile(以带 package.json 为判据)。如果你连一次 dsh 都没跑过,它会报"先启动一次 dsh,让它把 profile 建好再来装",而不是留下一个可能让 dsh 判定"profile 不存在"而拒绝启动的空目录。
Web 面板里精细开关三种形态
装完默认三形态全开。想"只在 headless 生效、desktop 保持原样"?不用动任何磁盘文件,本地 Web 控制台(agent-purge web,默认 http://127.0.0.1:7788)的 dsh 卡片上有 desktop / web / headless 三个"生效形态"按钮:
- 勾选只改
state.json里的dshProfiles字段(渲染逻辑见 web/ui.html,状态读写见 lib/state.mjs); - 常驻插件每轮 assemble 现读该字段,下一轮对话即生效,全关、再打开都不需要重启。
这就是把"磁盘层"(install / uninstall)和"开关层"(profile 勾选)彻底解耦的好处:勾选即时可逆,卸载按字节还原,两个层面互不牵连。
实测:5,713 字 → 68 字
能力表里的数字全部是本地假 provider 抓请求体的实测值,不是估算。matrix.json 里 dsh 一条写着:
实测版本 0.2.1-rc.2,默认 system 5,713 字,注入后 68 字;headless / desktop / web 三形态各验一遍,插件 canary 确实出现在 system 段里。
也就是说,三种形态下原本 5,700 多字的系统提示词都能被一份 68 字的人设干净接管 👌
安装与卸载:两条命令
只要本机装了 dsh(先启动一次,让它把 profile 建好),常驻安装就是:
agent-purge install dsh # 三个 profile 各装一份常驻插件
agent-purge uninstall dsh # 按字节撤掉,不留残渣
安装后重启一次 dsh 让插件加载;此后换人设、改模式、关开关全部热生效。想再要会话内 /purge on | off | status | mode 热切命令,可单独安装 slash 插件(细节见 lib/slashes.mjs),常驻注入与热切命令仍各走各的插件名,互不干扰。
小结
dsh 通道是 agent-purge 整体思路的一个缩影:
- 一套插件代码,三形态通吃:desktop / web / headless 不各写各的分支;
- 三个插件名各司其职:常驻、热切、一次性互不覆盖;
- 标记挂载 + 完整回滚:只写自己那段、只删自己那段,卸载按字节还原;
- 形态级热开关:
dshProfiles让任意形态即开即关,无需重启。
如果你在多种形态下同时跑 dsh,又希望它们共用一份人设,这条 cordis 插件通道基本是唯一可行路径——而 agent-purge 已经把它铺好了 🧩
相关源码入口:lib/dsh.mjs(三插件源码与安装/回滚)、lib/persist.mjs(常驻 install / uninstall)、backends/index.mjs(一次性启动)、matrix.json(能力矩阵与实测数据)。