工作区 MCP 注册 l33tdawg/dsh-workbench

dsh-workbench

为 DeepSeek Harness 写的插件，作者拿它跑真实的编码工作，不是跑演示。每个插件都堵住一个具体的缺口：智能体可能任务做完了，却没确认活儿是真的——改了文件却没看到落地结果，说「完成」却没经过任何检查，凭记忆断言一个数字，同一个会话里第十次回答同一个审批问题。

它们都很小，彼此独立，谁也不是框架。装 dsh-uplift 可以一次性挂载整套，也可以单独装某一个包，或者看下面的表格，只取你真正用得上的那个循环。

从哪开始：

- 正在跑 Harness，想要可靠性插件？ 装 dsh-uplift，再读 为什么有这些插件，了解它们背后的前提。
- 想让 Harness 里的 MCP 服务器和其他智能体工具里的一致？ 根包能做到，直接读工作区自己的 .mcp.json；见安装和配置。
- 想要证据？记分卡记录了已经建了什么、测了什么、还有什么没测。
- 撞上同一堵墙？ 已经针对 Harness 本身提了十七条报告和评论，索引在 patches/。

把工作区在 .mcp.json 里声明的 MCP 服务器注册到 DeepSeek Harness——走 Harness 自己的 mcp-client，不是重新实现一套。

// <workspace>/.mcp.json — the same file Claude Code, Codex, and others read {
"mcpServers": {
"sage": { "command": "/Applications/SAGE.app/Contents/MacOS/sage-gui", "args": ["mcp"] },
"remote": { "url": "https://example.test/mcp", "headers": { "X-Key": "v" } }
}
}

重启之后，那个服务器的工具会以 mcp__sage__ 出现在会话里，跟直接在加载器配置里配好服务器一模一样。

为什么有这些插件

编码智能体看不见文件系统。它看见的是工具结果。这些插件各自堵住一个时刻：智能体可能任务做完了，却没确认活儿是真的——改了文件却没看到落地结果，说「完成」却没经过任何检查，凭记忆断言一个数过的数字，同一个会话里第十次回答同一个审批问题。每个包的 README 讲自己的循环；这一节讲整套。

这个失败模式就是本仓库存在的理由，它和「跟另一个 harness 功能对齐」不是一回事。工作前提更窄：错误只有在智能体还能看见它的时候才修得了，所以机械性的循环值得先堵上，优先于任何依赖模型表现良好的东西。

老实说另一半：堵住一个循环，并没有被证明能降低错误率。撤销类错误率确实从每 100 次工具调用 3.5 降到 1.6，覆盖整个安装，但单个会话占了 30.1% 的事件，而 census 说得很直白：一个会话占主导的合并比率，不能作为关于 harness 的证据。安装这些插件，是因为这些循环值得闭合，而不是因为已经证明这样做能让模型更好。

本仓库中的插件

每个包都有自己的 README，目录名就是入口。

| 包 | 作用 |
| dsh-uplift | 一个包，安装下面整套可靠性包。 |
| dsh-guidance-pack | 行为提示词指引：规划、验证、编辑约束、破坏性操作、汇报。 |
| dsh-apply-patch | 多文件原子 apply_patch —— 一次调用，多个 hunk，全成或全不成。 |
| dsh-edit-feedback | 把 Harness 已经算出的 diff 返回给模型，让它知道自己的编辑落在哪里。 |
| dsh-verify-on-edit | 通过 debounce 跟踪文件工具的编辑，完成前检查待处理的编辑，报告明确结果，并允许每轮一次纠正性续写。 |
| dsh-check-claims | 把可计数的断言变成命令，给出确切答案，针对工作树或指定修订版本。 |
| dsh-compaction-todo | 压缩后恢复保存的任务状态，不产生重复提醒；可选加入 workflow_context，记录目标、约束、决策和剩余检查。 |
| dsh-approval-memory | 用命令前缀规则回答审批瀑布，并且一旦人类允许过某类升级，本次会话余下时间都照此回答。 |
| dsh-recall-gate | 拒绝一轮中第一个改文件的调用，直到该轮回忆起自己的记忆，这样点名工作树的已提交记忆会在写入之前到达，而不是之后。 |

仓库的其余部分

另外四个目录装着其余内容：

- tools/ —— 会话日志审计、可靠性 census、请求预算检查和修复工具。README 解释了所报告的测量值及其局限；各个脚本自带用法头。
- bench/ —— research/RELIABILITY-EVAL.md 要求的受控对比：小型 fixture 跑两套配置，二者只差挂载了哪些插件，补丁按 fixture 自己的测试评分。README 说明了已经展示和尚未展示的内容。
- patches/ —— 针对 deepseek-harness 提交的八份报告、一份提案和十一条评论，索引在 UPSTREAM-REPORTS.md，另有承载本地修复的 applier，以及提交后所做的更正。
- research/ —— Codex 对比和这套包背后的测量。scorecard 是入口。

可靠性包

安装 dsh-uplift，即可把 guidance、editing、verification、claim-checking 和 continuity 这几个插件一起挂载。它的配置档补丁会启用 workflow_context；单独安装 dsh-compaction-todo 时，除非配置了 workflowContext: true，否则该工具默认关闭。

verification 会保留防抖窗口内文件工具成功完成的编辑，并在正常收尾前检查待处理的编辑。通过任意 shell 命令做的编辑不在跟踪范围内。结果会区分通过、报告失败、超时、检查不可用、未配置检查、失败输出无法解析、取消这几种情况。检查沿用会话的 shell 策略，并尊重当前轮次中明确提出的跳过测试或检查的请求。完成守卫每轮可以请求一次纠正性续跑；它会尊重停止请求和审批上限。保存的工作流笔记是模型编写的任务状态，不代表可以额外执行操作。

回归用例与评估指南记录了测试覆盖的内容，以及如何对比编码任务的结果。本地运行 node tools/reliability-census.mjs --json 生成的报告会读取会话日志，不会上传对话记录。缺少 verification 记录意味着覆盖情况未知；基线测试和通过的插件测试并不能证明模型质量有所提升，原因见上文的归因说明。替换已安装的插件代码后，重启 Harness 以加载新模块。

CHANGELOG.md记录了每个版本改了什么、发布前测了什么。它是带注释标签消息的来源，而不是那份消息的副本，所以从克隆的仓库里就能读到某个版本背后的思路。

workspace-mcp 为什么存在

Harness 只从自己的加载器配置（cordis.patch.yml 和配置档补丁）读取 MCP 服务器配置。它的 mcp-client 包要求每个服务器对应一个插件实例，并且要静态声明。于是项目的 .mcp.json——这个文件本来已经告诉其他所有智能体工具需要哪些服务器——对 Harness 不可见，每个服务器都得在 Harness 专属配置里重新写一遍。这个插件会读取该文件，并为每个服务器挂载一个 mcp-client，这样工作区文件就成了项目声明服务器的唯一位置。

上游没法把它作为补丁收下：deepseek-harness 明确表示不接受外部 pull request，并建议这类改动走插件生态。这个插件就是为此而生。

SAGE 集成

复用正在运行的 SAGE 服务

桌面宿主可以直接用 SAGE 已有的 HTTP MCP 端点。这样能保留项目已批准的身份，也不会创建长期存活的 sage-gui mcp 子进程：

- id: workspace-mcp
config:
files: ['.dsh/mcp.json']
perAgent: true
sage:
url: http://127.0.0.1:8080/v1/mcp/streamable
tokenDirectory: /absolute/private/path/dsh-sage-tokensyaml
tokenCommand: /Applications/SAGE.app/Contents/MacOS/sage-gui
identities:
/absolute/path/to/workspace: /absolute/path/to/existing/agent.key

已有的 SAGE 节点必须健康，并且固定的身份必须已经由该节点批准和管理。会话首次挂载时，插件会在本地操作员权限下运行短时存在的 mcp-token create 命令行。它会把该会话的普通智能体 bearer 缓存到一个 mode-0600 文件中，该文件位于 mode-0700 目录下；之后的挂载和重启会复用它。MCP 客户端只会收到那个 bearer，绝不会收到操作员的签名密钥。如果这台主机只应使用已有的缓存凭据，那么在完成配置后省略 tokenCommand。

token 按 endpoint、workspace、identity 和持久 Harness 会话 ID 划分作用域。同一个项目里的不同会话会拿到不同的 token，因为 SAGE 把 HTTP 对话状态和持久工作声明都绑定到 bearer 上。重启后要保留缓存。要轮换 token，先用 sage-gui mcp-token revoke <id> 撤销文件里的 id，然后在重新挂载会话前删除那个私有缓存文件。缓存文件包含凭据：绝不要提交它们。

HTTP 模式优先于 workspace 的 sage stdio 声明。凭据缺失、项目未映射或连接失败时，会直接报告，不会启动 mcp 或 serve；其他已配置的 MCP 服务器仍会挂载。新项目需要显式固定且已批准的身份。此模式挂载时，旧插件版本留下的桥接会被清理，而且 workspace-mcp 插件重新配置后，每个智能体的客户端现在会卸载。

旧版 stdio 集成

在插件行上设置 sage: {}，会为每个 workspace 挂载一个 SAGE MCP 服务器，这样每个 workspace 都以自己的智能体身份签名，而不是跨项目共用一个大脑。

身份通过 SAGE_IDENTITY_PATH 显式固定，因为这是 SAGE 唯一无条件应用的规则（cmd/sage-gui/mcp.go 会先解析 SAGE_IDENTITY_PATH，然后是 SAGE_AGENT_KEY，最后是从工作目录派生的按项目密钥；身份解析从不参考 SAGE_PROJECT）。

派生路径在 GUI 主机里并不可靠——Electron 应用会为派生的子进程复用自己的工作目录，所以派生出的身份会以 profile* 命名，并随 profile 变化而变化。为每个 workspace 固定身份： yaml
- id: workspace-mcp
config:
sage:
identities:
/absolute/path/to/workspace: /absolute/path/to/agent.key

没有条目的 workspace 会回退到 SAGE 自己的派生逻辑，这对命令行主机有效。注意插件仍会把 cwd 设为 workspace，因为对按 workspace 运行的服务器来说，这才是正确的工作目录，尽管身份不能依赖它。

值得了解的后果：

- 新 workspace 首次打开时会注册新智能体，操作员必须先批准一次，它才能读写记忆。这就是每个工作区隔离的成本。
- 如果你的部署已经在 harness 加载器配置里声明了 SAGE 服务器，删掉它：同一作用域里两个服务器都声明 serverName: sage，会让 mcp-client 抛错并中止启动。
- 设置 sage.serverName、sage.command、sage.args 或 sage.env，可以改命名空间、二进制、参数或环境变量。
yaml
- id: workspace-mcp
config:
sage: {}

安装 sh

from the profile directory, or with the plugin manager's install action

pnpm add --dir "$DSH_HOME/profiles/web" /path/to/dsh-workspace-mcp

harness 自带的插件管理器也能完成这些步骤——设置里的 Plugins 页面，或者智能体可以调用的 install_bundle 动作，把当前目录作为目标——新安装的 bundle 在运行中的应用里无需重启即可生效。替换已安装的包仍需重启，因为模块必须重新导入。

然后把 bundle 加进 profile manifest 的有序列表： json { "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "@l33tdawg/dsh-workspace-mcp"] } } }

重启 Harness。附带的 cordis.patch.yml 会插入一行 workspace-mcp；照常从 profile 补丁层覆盖它的任意配置字段。手动操作有两点要注意：改动 manifest 却没动有序的 dsh.profile.bundles 列表，运行中的应用会忽略；应用运行时编辑补丁层会就地重组 profile——这能触达什么、不能触达什么，见 patches/FINDING-profile-reload-boundary.md。

配置

| 字段 | 默认值 | 含义 |
| root | '' | 要搜索的工作区。留空表示 Harness 进程的工作目录，也就是会话启动时所在的工作区。 |
| files | ['.mcp.json', '.dsh/mcp.json'] | 要读取的文件，按顺序。共享服务器键冲突时，后面的文件胜出，丢失的一方会记日志。 |
| allowEnv | false | 文件是否允许解析 ${env:NAME} 引用。 |
| env | {} | ${env:NAME} 可以解析成的值，仅在 allowEnv 为 true 时查询。 |
| envOverrides | {} | 强制施加到每个启动的服务器上的值，覆盖文件里声明的。 |
| perAgent | false | 按每个存活的根智能体挂载一次，挂在该智能体的作用域里，取自其会话记录的工作区。 |
| sage | 未设置 | SAGE 集成。{} 会按每个工作区通过 stdio 挂载一个 SAGE 服务器；url 搭配 tokenDirectory 则改用运行中的 SAGE HTTP 服务。见 SAGE 集成。 |
| clientModule | 未设置 | 要挂载的 @deepseek-ai/dsh-mcp-client 命名空间。见下文。 |
| verbose | false | 记录每次文件读取和每个挂载的服务器。 |
| toolCallTimeoutMs | 60000 | 单次工具调用或资源请求的超时。 |

按智能体挂载

perAgent: true 会按每个存活的根智能体挂载服务器，而不是按每个进程，纳入该智能体自己的工具作用域，并且从它的会话所记录的工作区纳入。进程级挂载在 GUI 宿主里不可能正确：在那里，Harness 进程的工作目录是配置档目录，而不是会话工作区，所以每个工作区解析出的都是同一批文件，并且——对 SAGE 来说——推导出的都是同一个以配置档命名的智能体。用这个模式，会读取工作区自己的 .mcp.json，每个子进程都以该工作区作为 cwd 运行，而 SAGE 正是从 cwd 推导智能体身份。

替换

${workspaceFolder} 和 ${workspaceRoot} 解析为 root；${cwd} 解析为条目自身的 cwd（一旦设置），否则解析为 root。整值形式的 ${env:NAME} 解析为 env[NAME]。

安全

.mcp.json 声明命令，而这个插件会运行它们。 因此，克隆一个仓库并在 Harness 中打开它，就会以你的用户身份执行该仓库 .mcp.json 里写明的任何东西。这是从工作区文件读取服务器定义所固有的——正是这一点让这个文件方便。这里没有任何沙箱隔离。

由此产生两个具体决定，两者都是有意为之：

- 除非运维人员主动开启，否则拒绝 ${env:NAME}。 默认情况下，克隆来的仓库无法通过它的 .mcp.json 读取 Harness 进程环境。只有对你信任的工作区，才启用 allowEnv 并在 env 下写出值；必须使用整值引用，所以文件无法把密钥拼进更长的字符串，比如 --token=${env:TOKEN}。
- 当仓库不该携带 .mcp.json 时，把它从版本控制中移除。 插件默认启用并读取约定文件名，所以对不可信的目录树，唯一可靠的退出方式就是让该目录树不包含这个文件——或者在配置档的 workspace-mcp 行上设置 files: []。

clientModule

插件必须挂载同一个 mcp-client，即正在运行的 Harness 所用的那个。另装一份会保留自己的工具注册表，注册不出任何可观察到的东西，看起来就像一个空工作区。插件先尝试 import('@deepseek-ai/dsh-mcp-client')，它会通过正在运行的安装的依赖图解析。如果失败，或者选错了副本，就在加载器行上显式固定： yaml
- id: workspace-mcp
config:
clientModule: {!!js ctx.loader.import('@deepseek-ai/dsh-mcp-client')}

行为与失败

- 文件缺失时静默处理：大多数工作区什么都不声明。
- JSON 无效、文档不是对象、mcpServers 成员不是对象，或者条目既没有 command 也没有 url，都会报为错误并跳过。文件其余部分仍会加载。
- 服务器键必须匹配 [A-Za-z0-9_-]{1,32}，因为 mcp-client 用它作为工具命名空间（mcp__<serverName>__<tool>）。
- 带 "disabled": true 的条目会被跳过，和其他客户端一样。
- 拒绝 "type": "sse"：HTTP+SSE 传输已退役。把条目指向 Streamable HTTP 端点，或者用 stdio。
- 一台服务器连接失败，不会拖垮其他服务器：每台服务器单独挂载，failOnStartupError: false，所以挂掉的服务器只会记一条日志，之后由 mcp-client 自己的重连策略重试，不会阻塞启动。
- 服务器随插件的 fiber 一起生死，所以 Harness 会正常卸载它们。

开发 sh
npm install # dev dependencies only
npm test # the workspace-mcp tests, the log tools, and every package suite
npm run typecheck # parse every package and tool the profile loads directly

packages/ 下每个包也有自己的测试命令，只想跑某一个套件时可以用。uplift README 列出了这个 bundle 的套件；评估指南 给出了针对性的验证、补全和连续性检查。

tests/integration.test.ts 会启动真实的工具注册表和真实的 mcp-client，写入 .mcp.json，然后断言 fixture 的工具落进了注册表——测试跑的是真实客户端，不是替身。

对照真实 harness 的验证

除了上面的测试，插件还在 2026 年 10 月 1 日对照已发布的 harness 做过验证，驱动时用了隔离的 DSH_HOME，没有碰任何用户配置档。配置档是手写的副本，抄自随包发布的 headless 模板，把 @deepseek-ai/dsh（0.2.0-rc.2）装进那个 home，再把这个包链接进配置档的 node_modules，方式和配置档安装时的链接一样。验证了什么，怎么验证的：

| 结论 | 证据 |
| 加载器能从配置档解析这个包，并组装出它的行 | dsh --profile --dump-config 打印出 workspace-mcp 行，带随包发布的配置，位于 # == @l33tdawg/dsh-workspace-mcp 之下 |
| 入口能通过 harness 加载器以 TypeScript 加载 | 同样的 import 在普通 Node 22 类型剥离下，从配置档目录里也能成功，所以不需要构建步骤 |
| apply 在真实 harness 进程里运行，工作目录就是工作区目录 | apply 里的临时插桩在 headless 启动期间记录到 cwd=<workspace> root="" |
| 插件自己的 @deepseek-ai/* import 能从裸符号链接配置档解析 | 入口、schemastery、dsh-mcp-client 都能从只含符号链接的配置档成功 import；其余部分由 harness 的运行时解析提供 |
| 工作区文件能被找到并解析 | 同样的插桩记录到 .mcp.json exists=true，而故意写坏的文件触发了插件自己的 invalid JSON 诊断 |
| 声明的服务器被挂载，工具被注册 | 对照工作区 .mcp.json 启动真实的 ToolRuntime 和真实的 mcp-client，注册了 mcp__echo__echo |

想复现，在一个临时目录里： sh
export DSH_HOME=/tmp/dsh-check
mkdir -p "$DSH_HOME/profiles/check/node_modules/@l33tdawg"
cd "$DSH_HOME" && npm install @deepseek-ai/dsh

把随包发布的 headless 模板复制到 profiles/check，然后：

printf '%s' '[]' > "$DSH_HOME/profiles/check/cordis.yml"
ln -s /path/to/dsh-workspace-mcp "$DSH_HOME/profiles/check/node_modules/@l33tdawg/dsh-workspace-mcp"

把 "@deepseek-ai/dsh-base"、"@deepseek-ai/dsh-headless" 和这个包加进

那个配置档 package.json 的 dsh.profile.bundles，然后，在一个

带有 .mcp.json 的工作区里：

"$DSH_HOME/node_modules/.bin/dsh" --profile check --dump-config # 组装这一行 "$DSH_HOME/node_modules/.bin/dsh" --profile check "any task" # 启动它

给想复现的人两点提醒。root 默认取 harness 进程的工作目录，配置档启动时就是会话启动所在的工作区——这是验证过的，不是猜的，也正是 files: ['.mcp.json'] 能找到工作区文件、而不是配置档自己目录的原因。另外，插件的诊断信息会写进 harness 日志：挂载失败会出现在 harness 的日志里，不会打到 stdout。