一个清理工具如何融入 DSH 生态:从目录结构到数据存储契约
一个清理工具如何融入 DSH 生态:从目录结构到数据存储契约
DeepSeek Harness(DSH)开源不到两天 GitHub 破万星、十二小时冲上五万星,紧接着官方桌面端上线、社区插件如雨后春笋——这是 2026 年 Agent 生态里最热的一轮叙事。热度之下,真正值得深挖的反而是那些"不起眼"的插件:它们如何在不改宿主源码的前提下,把自己长进一个正在快速演进的运行时生态里?
dsh-purge 就是这样一个样本。名字叫"清洗/清理",实际却是一个完整的红队评测插件:它要在官方 Web 与官方桌面端两套宿主机上同时工作,要管理提示词注入、规则集、技能库,还要支撑一个带 SQLite 事实库的"演练台"。这篇文章不讨论它的评测业务本身,而是把它当一枚切片,回答三个问题:DSH 生态约定了一套怎样的目录与存储结构?一个插件如何逐条对齐这些契约?对齐之后,这个"清理工具"又反过来撬动了生态的哪些演进?
DSH 生态的存储与目录约定
理解 dsh-purge 之前,先看它要嵌入的宿主长什么样。DSH 的目录契约不是一张散装清单,而是一套按"安装包 / 配置树 / 运行时数据"分层的约定。
$DSH_HOME 是一切数据的主根。 它承载用户侧的全部状态:prompt-inject.md(提示词覆盖文件)、rules/(规则集)、skills/(技能包)、profiles/<web|desktop>/(每个宿主一套 profile)。dsh-purge 在 lib/core.js 里把主目录探测逻辑写得很直白:DSH_HOME 环境变量 → dsh 启动器旁的 .dsh(便携包布局)→ ~/.dsh,桌面端则多走"当前正在运行的官方桌面安装"这一路,绝不借用 Web 启动器旁的主目录。
Profile 是插件的挂载点。 每个 profile 目录下有一个 package.json,其中 dsh.profile.bundles 声明这个宿主加载哪些 bundle。dsh-purge 的 README 给出了手动挂载的最小契约:
{
"name": "dsh-profile-web",
"private": true,
"dependencies": {
"dsh-purge": "file:../../plugins/dsh-purge"
},
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"dsh-purge"
],
"patchReload": "live"
}
}
}
命令行的等价物是 dsh plugin --profile web add dsh-purge / --profile desktop add dsh-purge——Web 与桌面各挂各的,两边分开安装、分开"应用",这正是 profile 隔离的体现。
技能与预设也有固定形状。 官方 @deepseek-ai/dsh-skill 约定技能目录为 $DSH_HOME/skills/<kebab-case-id>/SKILL.md;dsh-agent-presets 约定用户预设根为 $DSH_HOME/.agent-presets/。这两条约定在 dsh-purge 的 lib/skills.js 与 lib/redteam/index.js 中被原样遵守:技能名必须匹配 /^[a-z0-9]+(?:-[a-z0-9]+)*$/,预设被落到 $DSH_HOME/.agent-presets/redteam/。
一句话总结:DSH 的生态契约 = "一个主根($DSH_HOME)+ 一套 profile 挂载机制 + 一组有固定形状的资源目录(skills / presets / rules)"。任何插件想活得久,就得先在这棵目录树里找到自己的位置。
dsh-purge 如何对齐生态契约
对齐不是"把文件放到约定位置"这么简单,它发生在三个层次:包结构、配置注入、数据存储。
包结构:一个 bundle 长什么样
打开仓库根目录,dsh-purge 的布局本身就是为 DSH 生态设计的:
client.js—— 侧栏 UI(会话标题旁的 dsh-purge 入口);lib/—— 补丁、路径探测、注入组装与演练台核心;presets/redteam/—— 红队 agent 预设(preset.yml展示元数据 +agent.cordis.yml组合定义);skills/redteam/—— 随包技能(fofa-recon、nuclei-scan、suo5-tunnel 等);cordis.patch.yml—— bundle 的配置补丁入口。
package.json 里有一条关键声明:
"dsh": {
"bundle": { "patch": "./cordis.patch.yml" },
"client": {
"platform": "web",
"inject": ["@deepseek-ai/dsh-client-connection", "..."]
}
}
dshTarget: "0.2.0-rc.2" 直接把适配版本写进了元数据——生态契约是有版本锚的,对不上的补丁宁可显示"跳过"也不乱改文件。
配置注入:cordis.patch.yml 的克制与边界
cordis.patch.yml 是理解"对齐"一词的最佳注脚。它做了三件事:
- 主动退场:把旧生态里独立的
dsh-redteam-mode/dsh-redteam-ui等行disabled: true,明确"清洗 + 演练台都在本插件内",不外接、不 link 其它红队包; - 声明注入面:
inject: [systemPrompt, tools],把自己注册进宿主的两条官方扩展点上; - 落地演练台三个组件:
dsh-purge-redteam(预设 + 技能落地)、dsh-purge-redteam-store(SQLite 事实库,根目录dshHomePath('redteam'))、dsh-purge-redteam-ui(HTTP 桥POST /redteam/api)。
注意 !!js dshHomePath('redteam') 这个写法——它把"数据根目录"动态绑定到宿主约定的主根上,而不是写死一个绝对路径。这是生态对齐里最容易被忽略、却最重要的姿势:路径永远从宿主解析,而不是从插件自己的安装位置解析。
数据存储契约:一张可版本化的表结构
演练台的"事实库"是整个插件里生态契约色彩最浓的部分。lib/redteam/schema.js 把 SQLite 的 DDL 与迁移单独拆成一份"数据形状的唯一定义处",与业务逻辑解耦。核心设计有四条:
其一,库文件按靶标分。 RedteamStore(lib/redteam/store-core.js)把数据根组织成 engagements/<id>/,每个靶标一个目录,内含 engagement.yaml(元数据)、assets.db(资产事实库)、agents/(六角色提示词);全局的 redteam/current 是指向当前靶标的指针文件。攻击链、得分、凭据全部按靶标隔离,"报告不会再被别的靶标的成果污染"。
其二,schema 版本化靠迁移而非重建。 所有表结构变更走同一条纪律:PRAGMA table_info 探列 → 缺列才 ADD COLUMN,可重复执行、老库不用重建。连计分口径的大改版(《突破入侵类得分规则》25 条规则重构)都通过迁移把老得分点转 legacy 停用、保留用户自建点与历史命中——数据契约演进时,历史数据不是包袱而是资产。
其三,能力检测驱动降级。 FTS5 是 SQLite 编译期选项,Node 22.14 的 node:sqlite 没有、22.23 有。schema.js 在启动时用 :memory: 库探测,缺 FTS5 就整体降级为 LIKE 检索,还留了 REDTEAM_NO_FTS5=1 强制开关让 CI 能主动踩降级路径。契约的前提是"知道宿主给不给能力",而不是假设能力永远在。
其四,二进制与文本分层。 证据截图落 <靶标目录>/shots/,库里只存文件名与尺寸、sha256 等元数据;POC/EXP 正文进 pocs/<code>/<file>;原始请求、命令原文进 SQLite。这样 SQLite 保持轻量,报告又能按 file 字段索引到真实证据。
CREATE TABLE IF NOT EXISTS score_hit (
id INTEGER PRIMARY KEY AUTOINCREMENT,
point_id INTEGER NOT NULL,
asset_id INTEGER, vuln_id INTEGER, step_id INTEGER, target TEXT,
evidence TEXT, note TEXT,
points INTEGER, multiplier REAL DEFAULT 1,
recorded_by TEXT, recorded_at TEXT
);
这张表是"计分契约"的载体:points 承载档位差异(同一得分点普通 10 分/管理员 50 分),multiplier 承载 G5/G6 的翻倍规则,而 score-rules.js 里的 applyScoreCaps / evaluateScoreBoard 是计分的唯一实现——面板、报告、攻击链三处总分必须一致,靠的就是"同一份代码"而不是三处各写一遍。
统一操作分发:界面、CLI、智能体共用同一条路径
lib/redteam/store-core.js 里的 dispatch(store, req) 是一个极有生态意识的抽象:CLI、HTTP 桥接、智能体工具共用同一套 op 词汇(openEngagement、assetTest、addScoreHit……),保证"界面看到的、命令行验的、智能体写的是同一条路径"。数据契约因此不只对代码成立,也对工具、对模型成立——智能体通过 redteam_* 工具写入时,同样经过 validate.js 的路径穿越检查与枚举校验。
清理工具对生态演进的撬动
对齐生态契约是"融入",而 dsh-purge 真正有意思的地方在于:它把融入做成了对生态的反向塑造。
第一,把"评测流程"变成"数据流"。 红队模式(presets/redteam/agent.cordis.yml)把整条攻击链拆成信息收集 → 资产梳理 → 漏洞发现 → 漏洞利用 → 内网渗透五个阶段,每个阶段的结果都必须落库:资产进 asset 表、漏洞进 vuln 表、原始请求进 http_evidence、凭据进 credential、WebShell/隧道进 webshell/tunnel、步骤进 attack_step、得分进 score_hit。"没落库的发现 = 没发生"被写进角色提示词——评测的可信度不再依赖模型自觉,而依赖存储契约的完整性。
第二,知识库让单次评测反哺整个生态。 knowledge.db 是全局共享的 POC/EXP 库(跨靶标),智能体验证有效的通用利用脚本用 redteam_poc_add 回填,并强制携带 category、来源靶标、验证证据,脱敏掉内网专属信息。一次演练沉淀下来的不只是分数,而是"下一场演练可以直接检索"的资产。这等于在 DSH 生态里自建了一个随用随长的知识层。
第三,边界治理是生态长期主义的底色。 网络范围契约(lib/net-scope.js)把"大陆、香港、澳门默认禁止"写成 net-scope-allow.txt 白名单机制,密钥、网段、通配符一律在保存时丢弃;角色提示词反复强调"隧道必须说清目标侧那一端(entry_kind),self-only 不算突破"、"自己注册的账号不算得分权限(self_created)"。这些不是营销话术,而是刻进存储字段的硬约束——tunnelIsLegit() 直接按 entry_kind 判定,ACCOUNT_POINT_CODES 直接按 code 拦截自建账号。一个清理工具想要在生态里长期存活,合规边界必须跟数据契约一样可执行。
从界面侧看,这套对齐的结果是三个可操作的面板:清洗页(docs/preview/dock-clean.png)负责补丁的"应用/还原/卸载";规则集页(docs/preview/rules.png)管理多套 AGENTS.md / CLAUDE.md 的启用与编辑;补丁页(docs/preview/settings.png)按组展示每个补丁的应用状态。所有面板背后都是同一棵 $DSH_HOME 目录树和同一份 SQLite schema。
# 本地校验:五个入口文件全部通过 node --check
node --check lib/index.js
node --check lib/core.js
node --check lib/rewind.js
node --check lib/skills.js
node --check client.js
结语
回看 dsh-purge 的融入路径,可以提炼出三条对任何 DSH 插件都成立的结论:
- 目录契约是插件的生存边界:主根、profile、skills、presets 的形状决定插件能碰什么、不能碰什么,路径永远从宿主解析;
- 数据契约是插件的长期资产:SQLite schema 版本化迁移、FTS5 能力检测降级、计分唯一实现,让插件在宿主快速迭代时能安全演进、历史数据不归零;
- 可执行的边界比声明更有说服力:合规约束写进表结构字段和计分判定逻辑,而不是停在 README 的免责声明里。
一个名为"purge"(清洗)的工具,最终在 DSH 生态里长成了目录树的建设者、数据契约的履行者和评测标准的定义者。这或许就是生态的意义:不是单个插件有多强,而是每个插件都在用自己的方式,让整棵目录树和每一张表变得更可靠。