lemonmmice/dsh-agent-toolchain

dsh-agent-toolchain

让编码代理对其自身改动可验证地负责的工程运行时。

CI
License
Release
Node
MCP

一套插件和一个 MCP 服务器，让编码代理不仅能写代码——它还能看到正在运行的桌面应用程序、驱动它、测量它、捕获它通过网络发送的内容，并验证它刚刚所做的改动。每个插件都是一个小的、可组合的构建块；它们共同闭合了“代理写了一个改动”与“该改动确实有效”之间的环路——并产出证明这一点的证据。

被驱动的示例窗口，在代理向其输入并点击 Greet 之后

一条命令即可针对本仓库中附带的一次性 WPF 窗口运行整个环路——构建它、驱动它、读回结果，然后让 verify_report 裁定本次运行所声称的内容：

npm run demo          # build → launch → drive → read → verdict
npm run demo:perf     # + catch a deliberately blocked UI thread

真实输出（npm run demo，路径已缩短）：

1. environment self-check
ok   toolchain_status reports what is configured        (toolchain_status, 542 ms)
2. build the sample app (and bind the result to a runId)
ok   build_run → 0 errors                               (build_run, 3353 ms)
3. launch and look at the real window
ok   ui_launch brings the window up                     (ui_launch, 11929 ms)
ok   ui_observe(state) sees the controls                (ui_observe, 62 ms)
4. drive it — this is the part a code-reading agent cannot do
ok   type into the Input box                            (ui_drive, 458 ms)
ok   click Greet                                        (ui_drive, 314 ms)
ok   read the result back out of the UI                 (ui_observe, 79 ms)
ok   capture a screenshot as evidence                   (ui_observe, 35 ms)
5. adjudicate: claims vs evidence
ok   verify_report returns a verdict                    (verify_report, 57 ms)

verdict: pass
steps: 9/9 ok

npm run demo:perf 还会报告 stutterCount=1, maxMs=1474——示例应用故意将其 UI 线程阻塞整整 1500 ms，而性能探针必须捕获到这一点。

该演示并非仅供演示的代码。mcp/demo/run-demo.mjs 是一个普通的 MCP 客户端：它通过 stdio 启动 mcp/server.mjs，并调用 Claude Code、Cursor、Cline 或 Codex 会调用的相同工具。如果它能通过，那么 MCP 这一面就是可用的。
录制 GIF：在屏幕录制器运行时执行 npm run demo:perf 就是预期的捕获方式——窗口在每一步都会做一些可见的事情。docs/media/ 是录制内容的存放位置。

问题

编码代理非常擅长生成补丁，但它们对补丁之后发生的事情视而不见：构建是否失败了？UI 是否真的渲染了新页面？应用程序触发了哪些 API 调用，其中是否有一个挂起了 20 秒？这次改动是否引入了内存泄漏或 UI 卡顿？

传统代理通过阅读代码来验证。这套工具链让它们通过观察正在运行的应用程序来验证——就像人类 QA 工程师那样——然后让它们展示证据。

循环

修改代码 → 构建 (dsh-build) → 驱动客户端 (dsh-ui-drive)
→ 捕获 API (dsh-api-visualizer, dsh-postman)
→ 检查性能 (dsh-perf) / 挂起 (dsh-hang-inspector)
→ 记住经验教训 (dsh-memory)
声称“完成” → verify_report：声明与证据对比 → 一个裁决
失败 / 交接 → failure_record → 失败语料库（数据飞轮）

快速开始

路径 A —— 演示路径（无需 Rust，约五分钟）

正是 npm run demo 所演练的那些工具——build_run、ui_ 系列、verify_report、perf_probe、http_request——既不需要 Rust 也不需要 MSVC。已在一个 plugins//bin/ 目录为空的检出上验证过。

1. Node.js 20+ 和一个 .NET SDK（示例目标为 net10.0-windows）。
2. npm install --prefix mcp —— MCP 服务器是唯一有依赖的东西。
3. npm run demo。

不会向仓库目录树写入任何内容：一次演示运行会将其截图、构建日志、验证报告以及任何失败记录保存在 .dsh-agent-toolchain/demo/ 下（已被 gitignore）。

路径 B —— 完整桌面模式

API 捕获存储、内存索引、火焰折叠和终端检查器会加载 Rust Node-API 模块。构建你需要的那些（Rust + Visual C++ 构建工具），或者使用已经附带它们的部署：

npm run build:capture-store        # dsh-api-visualizer (+ shared by dsh-verify)
npm run build:memory-store         # dsh-memory
npm run build:trace-fold           # dsh-perf flame folding
npm run build:terminal-inspector   # dsh-win-terminal-inspector

然后运行 pwsh -File install.ps1（试运行）或 pwsh -File install.ps1 -Apply，将插件复制到你的 DSH 配置文件中，在 cordis.patch.yml 中注册它们，并重启宿主。

这是阅读代码的代理做不到的

- 区分“0 个错误”和“文件已被编译”。 旧式 .csproj 项目不会自动包含新的 .cs 文件，因此构建可能报告成功，而你的文件从未被编译。build_compile_check 专门回答这个问题，有三种状态——在编译集合中、可证明不在、或无法读取（绝不会静默地判定为“不在”）。
- 操作并观察真实应用程序。 ui_observe / ui_drive / ui_flow 按名称或 AutomationId 查找控件、点击、输入、等待条件、回读值，并捕获窗口范围的截图。只读操作永远不需要权限；任何点击或输入的操作都必须通过 allowSideEffects=true，并且可选的快照新鲜度门控会拒绝针对过期 UI 的操作。
- Jev 辅助的 UI 决策。 ui_jev 将经过脱敏的 UIA 控件列表发送给 Jev，让它选择一个有界的候选操作，然后复用相同的确定性 UI 执行器和安全门控。Jev 永远不会收到像素、生成任意输入或绕过授权；参见 docs/jev-ui.md。
- 拒绝轻信智能体的说法。 收尾总结会变成一份声明列表，verify_report 会根据机器证据——构建记录、API 捕获存储、磁盘上的文件、真实命令、git 状态——对每条声明进行裁定，产生 pass / incomplete / fail。与证据相矛盾的声明会自动记录到失败语料库中（类别 agent-misjudge）。当工具无法看到某些内容时，它们会说“未验证”，而不是“已通过”。

工具——共 55 个，其中 23 个为只读

唯一事实来源是 lib/tool-registry.mjs；两个界面（DSH 插件和 MCP）都由它生成，因此它们不会彼此偏离。每个工具一行，按你想做的事情排序 → docs/tools.md。

| 插件 | 它为智能体做什么 |
| --- | --- |
| dsh-build | 将 MSBuild / dotnet build 作为工具运行：增量构建、结构化错误列表（文件/行/列/代码）、错误重新解析、编译成员资格检查。构建默认值会根据仓库布局自动解析（旧版客户端布局逐字节保留其默认值；标准仓库获得 .sln/.slnx + 平台自动检测）。 |
| dsh-ui-drive | 通过 UIA 驱动正在运行的 Windows 桌面客户端：查找/点击/输入/读取/截图、可视化树转储、带断言的多步骤流程、截图 + 视觉描述。 |
| dsh-verify | 收尾裁定界面：声明与证据的裁定，以及失败语料库工具。lib/verify 之上的薄壳——与 MCP verify_report 背后是同一个引擎。 |
| dsh-api-visualizer | 捕获客户端的 HTTP 流量：实时面板、JSONL 存储、调用方归属、自动响应规则、基线/契约回归、可选的 Fiddler 风格本地代理。 |
| dsh-postman | 测试框架内的 Postman 风格 HTTP 客户端：从主机编写/发送请求（无浏览器 CORS）、历史存储、WebSocket 客户端、http_request 智能体工具。 |
| dsh-perf | UI 卡顿测量（窗口消息延迟、P50/P95/P99、卡顿事件）、完整转储捕获 + ClrMD 分析、托管堆统计、GC 根保留路径、ETW 跟踪 / 热点堆栈 / 火焰图与分配折叠、UI 冻结（挂钟时间）分析。 |
| dsh-hang-inspector | 挂起诊断：监控主窗口响应性，自动收集证据包（冻结截图、时间线、进程信息、net-trace 尾部、转储），分析托管线程堆栈并将挂起映射到项目源码。 |
| dsh-memory | 测试框架的长期记忆：对已索引的工作区文档进行语义搜索、跨会话键值约定、mtime 增量索引、过期分块淘汰、保存时的令牌/密钥过滤。 |
| dsh-win-terminal-inspector | 针对持久化 shell 的 Windows 终端（ConPTY）检查。 |
| dsh-jev | 可选的 TypeSafe Jev 决策层：批量类型化路由/证据判断，需显式选择启用远程数据；仅作建议，绝不执行所选操作。 |

亮点

- 一套工具链，适配所有 agent：同一套工具既为 DeepSeek Harness 插件提供支持，也适用于任何 MCP 客户端 —— 参见 mcp/。Claude Code、Cursor、Cline 和 Codex 都能使用完全相同的 lib/ 代码来驱动客户端、运行构建、捕获 API 并搜索记忆。
- 安全优先的 UI 自动化：click/setvalue/key 需要显式设置 allowSideEffects=true；只读操作始终安全。一个可操作的终止开关和一个可选的拒绝优先策略凌驾于每个操作之上，且恢复操作刻意不作为 agent 工具提供。
- 诚实的测量：性能数据来自真实的窗口消息往返，每份报告都会说明该方法无法看到什么；成本表在无法确定时写“unknown”，而不是编造数字；空枚举报告为“未读取”，绝不报告为“那里什么都没有”。
- 失败语料库就是护城河：失败路径会自我记录 —— 构建错误、ui_flow 断言失败、ui_drive/http 失败，以及 verify_report 的声明与证据不匹配，都会按固定的 7 类分类法自动追加记录。参见 docs/failure-corpus.md。
- 仅限回环的控制 API，并且每个环境特定的值（客户端 exe、窗口标题、证据目录、工具路径、源码根目录）都是带合理默认值的环境变量：没有硬编码的机器，没有内嵌的凭据。

适用于任何 MCP 客户端

claude mcp add --scope user dsh-agent-toolchain -- cmd /c node \mcp\server.mjs

Cursor、Cline 和其他 stdio 客户端使用相同的命令。配置细节、进度通知、输出预算以及诚实的平台矩阵见 mcp/README.md。

安装（详情）
每个插件都是一个可直接放入的宿主插件。将插件目录复制到你的 DSH 配置文件的 plugins/ 中（对于面板，则复制到 node_modules/@dsh-agent-toolchain/），并在 cordis.patch.yml 中注册它：

- insert:
- id: ui-drive
name: './plugins/dsh-ui-drive/index.js'

scripts/deploy-plugins.mjs（由 install.ps1 包装）是执行该复制的受支持方式；--check 会报告漂移而不写入。

共享的 lib/： dsh-build、dsh-ui-drive 和 dsh-verify 会导入仓库根目录下的 lib/ 模块（decode、build-resolve、failure-corpus、capture-store、verify/report）。它们的相对导入会相对于配置文件根目录解析，因此请将你需要的文件复制到配置文件中，路径为 /lib/…（与 monorepo 的 lib/ 目录树保持一致）：

/
plugins/dsh-build/...     # 每个插件目录按原样复制
lib/
decode.mjs
build-resolve.mjs
failure-corpus.mjs
capture-store.mjs
verify/report.mjs

缺少共享模块会导致插件在加载时崩溃（静态导入）；而 failure-corpus/verify 的动态导入则会降级为空操作。

然后重启宿主，并向 agent 请求 toolchain_status —— 它会报告已配置的内容、来自哪个来源（进程环境变量 / 用户注册表 / 未设置），以及哪些内容无法检查。

平台范围（如实说明）

证据主干（verify / 失败语料库 / 捕获 / 记忆 / http）、dotnet 构建引擎和构建目标解析是跨平台的。UI 驱动、VS-MSBuild 引擎以及性能/挂起探针仅限 Windows，在 macOS/Linux 上它们会报告 unconfigured，而不是假装可用。各工具的矩阵见 mcp/README.md；兼容性矩阵（harness × 插件 × MCP 版本）见 docs/compatibility.md。

这是如何构建的

本仓库旨在成为其自身论点的可运行示例，因此过程是产物的一部分，而不是脚注：

- 一名实现者，两名独立审查者——来自不同的供应商。 工作在这里实现，然后以只读方式分别交给 Codex 和 Claude，要求各自去证伪而不是赞同（“有价值的输出是我在没有证据的情况下所声称的内容，以及能推翻它的反例”）。每一轮通常以部分发现被接受并修复、另一些则用证据反驳而告终——审查者不会为了达成一致而表示赞同。
- 被接受的发现会变成测试，而不是一段文字。 这就是为什么几十个测试文件会以产生它们的轮次命名（Codex r30、Codex r37、@codex r54、Codex 第十二轮）：无法执行的审查结论会立即失效。
- 审查结果本身也要经过裁定。 2026-09-11 的跨模型审查轮次是用本仓库所交付的同一套“主张对证据”机制来收尾的。
- 失败语料库记录了谁发现了什么 —— 包括 agent-misjudge，这是机器可以独立捕获的一类失败（docs/failure-corpus.md）。

先前技术及致谢

本项目从哪些地方学到了什么——逐个包、逐个文件地说明——包括哪些内容被有意未采纳，以及对不在本仓库中的审查报告的诚实盘点——都收录在 docs/prior-art.md 中。

概览：

- OpenAI Codex（codex-rs，Apache-2.0，Copyright 2025 OpenAI） —— 影响最大的单一来源。其工作区的一个 76 文件子集已在本地研究；所采纳的是接口形态、策略结构和命名规范（Guardian 审批层、工具规范注册表、调用追踪规范、计算机使用访问控制模型、截断策略）。此处未内置任何 Codex 源代码，也未复制任何文件 —— 每个实现都是独立重新实现的，且 native/*/.rs 中不包含任何 Codex 引用。Codex 同时也是一个被测对象：bench/harness/bench.mjs 将其作为被测代理运行。
- Anthropic 和 OpenAI 的测试框架写作，以及 Mitchell Hashimoto 的表述 —— 本项目所依托的框架；失败语料库是 Hashimoto 的“设计一个解决方案，使代理永远不会再犯那个错误”转化为存储。
- PerfView —— perf 插件的 trace、hotstacks、flame 和 GC 视图的参考实现。docs/perfview-parity.md 既跟踪差距，也跟踪匹配项。
- ClrMD / DumpStack、ETW（xperf/WPR）、WinDbg（cdb） —— 已封装并解析，其中的陷阱记录在 docs/native-stacks.md 中。

文档

| 文档 | 内容 |
| --- | --- |
| ROADMAP.md | 公开的三年计划及其设计原则 |
| docs/architecture.md | 各部分如何组合 |
| docs/tools.md | 全部 55 个工具，每个一行，按你想做的事情分组 |
| docs/prior-art.md | 本项目从哪些地方学到了什么（按包），以及有意未复制的内容 |
| docs/verify-package.md | 提案：将验证核心提取为独立包 —— 状态：未实现 |
| docs/failure-corpus.md | 失败分类法和记录模式 |
| docs/verification-report.md | 声明类型和判定语义 |
| docs/agent-toolchain-evaluation.md | 对此工具链的测量，以及仍然薄弱的部分 |
| docs/ui-drive-safety-boundary.md | UI 自动化允许做什么 |
| CHANGELOG.md | SemVer 历史（Keep a Changelog） |

贡献
参见 CONTRIBUTING.md。npm run check 是仓库门禁（语法、禁止引用、schema DSL、PowerShell 编码）；npm run verify 运行整个测试套件。

许可证

Apache-2.0（各插件的 LICENSE 文件与此一致）。