可靠执行护栏 fj2devivh/dsh-reliability-plugins

DSH 可靠性插件

一个构建在 DeepSeek Harness（DSH）——DeepSeek 开源、基于插件的 agent 运行时——之上的 10 插件可靠性层，它将不可靠的 LLM 视为既定前提，并通过能力级隔离而非提示词层面的客套来约束它们。此处发布了两个插件和四个独立工具作为参考实现；其余为内部生产组件。

在一个高强度的一周内构建完成（2026-09-15 → 09-22），作为我的个人生产系统，通过真实事故不断迭代，并在机制层面的市场对比中，针对官方生态系统的 601 个插件进行了验证。

⚠️ 这是一个以精选形式发布的个人生产环境。代码由 AI 在设计优先、验证密集的工作流下生成：我负责架构、验收标准和阴性对照测试框架；模型编写了大部分代码行。我认为这种分工——人类判断输入，生成代码输出，机器验证——才是本仓库的真正主题。

问题

用多 agent harness 驱动真实项目时，我不断遭遇三类系统性故障：

| 故障类别 | 表现 | 根本原因 |
| 上下文污染 | 意图层读取原始源代码和日志来“检查”执行器，被细节淹没（“被施工灰尘呛住”），并开始自行其是——忘记了整体设计 | 决策与执行之间没有分离 |
| 虚假完成 | 执行器在未完成时报告“完成”；没有人重新检查 | 没有独立的验收层 |
| 向上污染 | 脏的中间状态流入到达用户/上层的报告 | 现场数据与决策上下文之间没有隔离 |

这些问题正是如今业界归类为上下文工程和agent 可靠性的同一批问题。区别在于：大多数产品用更好的提示词来解决它们。我则通过让被禁止的操作在工具 schema 层面变得不可能来解决。

架构

用户的言辞与标准 (notes/*/.md)
│
▼
┌──────────────────┐
│ 意图层 │ 理解、分解、 │ （双预设） │ 定义验收、接受 │ │ │ intent-guard: │ • 无 write/edit schema（完全看不到“修改”） │ 能力级 │ • 无 read/glob/grep/shell schema（看不到现场） │ 隔离 │ • 只有 compass：白名单报告与人类言辞 └────────┬─────────┘ 任务书 + 权限租约 │ ▼ ┌──────────────────┐ │ 执行层 │ 生成的子 agent，拥有自己的上下文 │ │ │ executor-gate: │ • 出生时默认冻结 │ 预算租约 │ • 按任务解锁：工具 × 范围 × 配额 │ │ • 预算耗尽 → 自动停止，报告“未完成” │ executor-loop: │ • 目标状态机跨会话与进程重启持续存在 │ 0-token 判据 │ └────────┬─────────┘ │ dispatch_audit（黑盒） ▼ ┌─────────────────────────────────────────────┐ │ AUDIT LAYER │ │ 在阴性对照下运行，不写入任何内容 │ → 结构化验收报告 │ 报告落在 notes/_endstate/audits/ │ （intent 唯一可读取的内容） └─────────────────────────────────────────────┘

配角阵容：criteria-gate（规则不得在任务书内部被发明——每条规则都必须追溯到人工编写的源文件）、knowledge-gate、endstate-loop（差距测量器 + 累积账本）、endstate-view / executor-view（可观测性面板；endstate 面板通过真实工具调用编辑状态，而不唤醒模型）。

关键设计决策

1. 能力层 > 提示层。 read/glob/grep/pwsh/bash 已从 intent 层的工具表中移除——已在真实 ToolRuntime 上验证：intent 看到 4 个工具，executor 看到 11 个。不是“请不要看”——而是眼睛根本没有安装。
2. 大声失败，逐名处理。 tools.restrict() 在遇到未知工具名时会抛出异常；一个错误名称会静默导致整个掩码未被应用。因此掩码按名称逐个分发，任何“存在但未被移除”的情况都会引发警告。
3. 默认冻结的 executor 配合预算租约。 权限 = 工具 × 范围 × 配额，按任务授予。耗尽是一次正确的停止，而非懒惰。gate 自身的源代码永远不可被租用；三次约束挑战 → 熔断。
4. 状态判据，零 token。 目标延续由宿主侧状态机判定（每次检查 0 token），对比市场上将日志重放给评判模型的做法（每轮一次 LLM 调用）。
5. 处处阴性对照。 预检 gate、冒烟测试——每项检查都嵌入一个必须变红的探针；如果反例保持绿色，整个判定就不可信。
6. 事后复盘驱动的规则。 apply() 永不抛出异常（2026-09-15 的教训：一个会抛异常的插件导致整个窗口无法启动）。每一次事故都变成了一件工具或一条法则。

诚实的边界

- 工具模式隔离不是文件系统沙箱。intent 层仍然可以派发子代理去查看——它读取的是报告，而不是自己爬取站点。真正的只读需要操作系统级挂载，这超出了本文范围。
- 第二道防护层（judgeCleanRoom）被明确标注为启发式——它捕捉的是“随意窥探”，而非蓄意绕过。其上的能力层则不是启发式的。
- 这些插件所挂钩的 harness API 尚处于 1.0 之前，将会发生变化；而这些理念（负向对照、预算租约、能力隔离）并不绑定于 DSH。
- 模型无关是必然要求。 harness 接受多个模型提供方，而此处修复的每一类故障——污染、虚假完成、向上污染——都与模型无关。一个较弱的捆绑模型并不会削弱这一层；反而让护栏变得更加必要。模型越差，能力级隔离就越有价值。

工程纪律

- preflight-dsh.mjs——在重启之前预测“桌面端是否仍能启动？”，并内置负向对照。退出码：0 绿色 / 1 无法打开（附原因）/ 2 缺少依赖。
- verify-all.mjs——总闸门：补丁 YAML、真实 profile 组合、回退 home、已链接插件、app.asar 完整性、快照健康。
- snapshot.mjs + 回滚脚本——一条命令回到已知良好状态。
- 语义化退出码——smoke.mjs：0 通过 / 1 断言失败 / 2 缺少依赖（绝不伪装成失败）。

市场对照

针对官方 awesome-dsh-plugin 列表中 601 个插件的机制级对照（docs/市场对照分析.md）。举一个例子：对比 dsh-loop-continue——该插件会恢复一个在叙述中途停止的 agent 回合（回合内，每次检查调用一次 LLM 裁判）；而我的 executor-loop 回答的是另一个问题——目标能否在会话压缩和进程重启后存活（跨会话，0 token）。两者可以共存。这次练习还抓出了我自己的两条错误建议（把单插件框架套用于架构级问题）；它们已在文档中撤回，并附上理由。

证据

- 意图层工具表（真实 ToolRuntime）：subagent, dispatch_audit, read_compass, list_compass——4 个工具。执行层：11 个。
- 幸存下来的事故：intent-guard 曾锁死所有会话；executor-loop 手写的 Config 曾让桌面端变砖。两者都成了回归测试。
- 回归套件运行真实的 Context、真实的 apply、从 app.asar 中提取的真实工具名——没有 mock，没有重新实现的逻辑。

仓库地图（发布时）

dsh-intent-guard/ 意图层的能力级隔离 （已发布） dsh-executor-gate/ 默认冻结的执行 + 预算租约 （已发布） preflight-dsh.mjs 带负向对照的启动预测器 （已发布） verify-all.mjs 总验证闸门 （已发布） snapshot.mjs 已知良好快照与恢复 （已发布） repair-profiles.mjs profile 修复工具 （已发布） docs/ 架构笔记、市场对照、演示脚本内部生产组件（在 docs/DUAL-MODE.md 中描述，尚未发布）： dsh-criteria-gate/ 规则来源门禁 dsh-executor-loop/ 持久目标状态机 knowledge-gate、endstate-loop、endstate-view、executor-view

许可证

工具采用 MIT 许可证。插件作为参考实现发布——它们编码的是我的生产策略；请分叉并根据你的策略重新调整。

作者： 刘新月——会计专业出身，后转型为 AI 系统构建者；曾在中国排名前 20 的会计师事务所工作 6 个月（完整经历忙季，参与 10 个以上项目），之后全力投入智能体工程。正是在会计师事务所的现场工作经历，让这个仓库如此重视验收证据。简历