desktop、web、headless 三形态通吃:agent-purge 的 dsh cordis 插件通道揭秘

原创2026-10-30 09:13:492,126 阅读

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。

两个值得注意的设计:

  1. 常驻插件不写死人设:每一轮都现读 state.json 和 personas/active.md。切换人设、改模式、/purge off 全部下一轮生效,无需重启。
  2. 插件知道自己在哪个形态里:通过自身路径 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(能力矩阵与实测数据)。

登录后查看全文
agent-purge