把 DeepSeek Harness 源码翻了一遍，这几个设计我想抄

原创

网络安全透视镜
网络安全透视镜

网络安全透视镜

2026年8月14日 00:40
江苏

在小说阅读器读本章

去阅读

8 月 13 号，DeepSeek 在公众号上发了个开源项目：DeepSeek Harness（命令行叫 dsh），MIT 协议，开发者预览版。官方给它的口号是“一切皆插件”。

这种话听多了容易麻。我把仓库拉下来翻了几天，结论是：这次他们没吹牛。

模型适配器、工具注册表、会话持久化、沙箱、Web UI，这些全是插件也就罢了——连 Agent Loop 本身都是个插件，挂在 ctx.agentLoop 上。你看它不顺眼，可以整个换掉，其他部分一行不用动。

“不存在需要打补丁的特权内核。”

架构文档里这句话写得很硬。做过框架的人都懂，敢写这句，比写一百句“灵活可扩展”难得多。

这篇不谈发布公告，就聊我从源码里翻出来的东西。

底下垫着的 Cordis，是这套东西的根

dsh 的插件系统不是自己造的轮子，用的是 Cordis（vendor 进仓库的，背后有篇论文，讲时空可组合性的编程范式）。Cordis 给的几个能力里，我觉得最要紧的是这条：所有注册都是可逆的副作用。

工具 schema、提示词段落、监听器、适配器，插件挂载时注册进来，卸载时跟着撤销。

听起来是小事，但 Agent 系统里的很多灵异 bug，根源都是“某个东西注册了却没人记得撤”。这条直接把这个类问题从根上掐了。

事件分了四种分发模式：emit（大家看着）、waterfall（层层包装的中间件）、parallel（并行扇出）、serial（排队执行）。分发模式是事件契约的一部分，写在声明里，由生成工具交叉校验——不是写在注释里靠自觉。

seam：换零件，不用换车

文档里最核心的概念叫 seam（能力接缝）。一个 seam 凑齐三个角色才算数：

• Service Definition

：定义接口的那个服务，占一个 ctx.<key>；
* Service Provider

：实现方，可以有好几个；
* Consumer

：用它的，一般是暴露给模型的工具。

举个例子就明白了。文件系统（ctx.fs）和子进程（ctx.subprocess）在 dsh 里属于同一个执行世界。仓库里自带了 fs-e2b 和 subprocess-e2b 两套远端实现——把这两个 Provider 一换，Bash、持久终端、LSP 就一起进了 E2B 远程沙箱，不需要给每个工具单独写一套远程分支。

工具插件化只解决模型能多做什么；seam 连模型在哪执行、记录存哪、权限怎么限都管。

翻 seam 清单的时候有个发现让我停了一下：ctx.subagents 的实现列表里，躺着 subagent-codex 和 subagent-claude-code。也就是说 dsh 原生支持把子任务委派给 Codex 和 Claude Code 这两个别家的 Agent 产品，只是默认 disabled。这个胸襟，在同类项目里不多见。

会话日志：整套系统里我最想抄的设计

大多数 Agent 产品把对话记录当 UI 的附属品，存一份给前端渲染用。DSH 反过来：会话日志是整个系统唯一的事实源，玩法接近事件溯源。

模型可见，即已记录。

抵达模型请求的一切——系统提示词、用户消息、模型输出的每个流式分片、工具调用和结果、上下文注入——都必须能从这条仅追加的日志里重建出来。

这不是文档里的口号，有一条运行时不变量（invariant）在盯着它，违反了会直接炸。

带来的好处很实在：fork、恢复、回放、遥测、持久化，全是从同一条事件流投影出来的。UI 不用猜发生过什么，存储不用另记一本账，出事故之后你能完整回答“模型当时到底看到了什么”，而不是对着半截回答干瞪眼。

配套的是三个事件域的分工：

• 要持久的事实走 session/event；
• 进行中的实时控制（inbox、步骤、请求拦截、steering）走 agent/*；
• 给某个 seam 挂策略走 fs/*、tools/* 这类能力事件。

改代码前先想清楚自己的东西属于哪个域，是文档反复强调的第一课。

工具执行那条流水线也值得一说。tool/call 事件是先落日志、再执行，然后依次过前置 waterfall（钩子、权限、沙箱）、一串单调守卫（只有两种票：拒绝，或弃权）、一次性审批、环绕分发（超时重试）、后置 waterfall，最后产出不可变的结果事件。每一层策略都有自己固定的位置，谁也不用去改循环。

四个 preset：整份仓库最能说明问题的地方

官方说 v0.1 交付了四种模式。代码里对应 apps/cli/config/agent-presets/ 下的四个目录，一个目录一份 agent.cordis.yml。模式之间没有分叉代码，差别全在组装文件里。

1. 标准模式（standard）

不用多讲，完整编码 Agent：文件编辑、Shell、检索、Skills、计划模式、目标、子代理、工作流，全乎。

2. PTC 模式（code）

这个就有意思了。我把它的配置和 standard 摆在一起看，插件行完全一样，就在末尾多了一坨：

- id: tool-presentation
  name: '@deepseek-ai/dsh-agent-tool-presentation'
  config:
    mode: code

这一行干的事，是把工具注册表呈现给模型的方式换掉：模型看到的不再是几十个孤立工具，而是一个生成的 TypeScript SDK 加唯一的 run_code 入口。

原本要五个来回的“读文件、筛结果、批量改”，现在写一段程序一次跑完。这就是 PTC（Programmatic Tool Calling）。

注意代码执行在架构里是独立的 ctx.codeRuntime seam，不是普通工具。说明官方清楚这玩意儿的代价：你把控制流交给模型写的代码，就得配套执行隔离、预算控制和错误约定。看它的类型定义，CodeRunResult 里错误是一个字段，绝不走 Promise rejection——这种约定都写死在代码注释里。

3. 极简模式（minimal）

只给两个工具：持久 bash 和 str_replace_editor。做 Agent 评测的对这个名字肯定眼熟。它的系统提示词配置更绝：

- id: persona
  name: '@deepseek-ai/dsh-persona'
  config:
    text: You are a helpful software engineer assistant.
    complete: true            # 屏蔽其他所有提示词段
    includeRuntimeContext: false

complete: true 的意思是：全局身份、Web 引导、工具使用建议，一概不许往里加。没有压缩，没有运行时上下文，提示词就一句话。

工具描述里甚至写着“你可以通过 apt 和 pip 访问常见包的镜像”——明摆着就是照着评测环境做的。

这模式的价值不在于弱，而在于干净。

不同 Agent 各自背着不同的工具集和提示词跑分，结果根本没法比。极简模式给了一个稳定的最小工具面，让“模型裸能力到底如何”变成一个能回答的问题。

4. 创造模式（cordis）

最野。它在标准能力之外挂了 tool-cordis：可以读取正在运行的运行时、在内存里挂载临时插件做实验、创作新 preset。它的 persona 直接告诉模型：“You can read and modify the harness you run on.”

但文件头部有一段警告，我读的时候是真愣了一下：

TRUST: cordis_mount evaluates model-written JavaScript against the live runtime… Treat a session on this preset as shell access.

模型写的 JS 直接在活着的运行时里求值，写出来的组装会被其他会话挂载。所以官方挑明了：这个模式按 shell 权限对待，是信任边界，不是玩具。

让 Agent 能改造自己的底座，这事儿很迷人，但 DSH 选择先把刀柄朝外递给你。

preset 机制本身还有几个细节值得记：

• preset 在整个进程里只挂载一次，会话通过 scope 父链加入，解析顺序是 agent → preset → global，近处遮蔽远处；
• 只有还没产出内容的空白会话能换 preset

。跑过的会话禁止切换（网关直接返回 agent-preset-locked）；
* 组装在 agent 发布前一次装好，运行中不重读，提示词前缀全程稳定——KV Cache 友好是刻意设计出来的。

切换动作本身也要作为会话事件落日志，因为 preset 决定了模型看到的 schema，按“模型可见即已记录”的规矩必须能重建。

上手和判断

跑起来很简单，Node 22.19+：

npx @deepseek-ai/dsh web

Web UI 起在 http://127.0.0.1:3080，设置页填个 DeepSeek API key 就能用。

建议先拿标准模式跑个真实任务，再切极简模式对比同一个任务的表现，差异比任何 benchmark 报告都直观。想看看自己机器上实际组装出了什么，dsh --profile web --dump-config 会把整棵配置树打出来，上面的每个条目都能被你自己的 patch 替换。

我的判断：现在拿它当生产底座还早，官方自己也说了，预览期会有破坏性变更。

但有三类人值得马上花时间：

• 做垂直 Agent 产品的

：你需要换模型、换存储、换权限策略，而不是接受一套拆不掉的默认实现；
* 做评测研究的

：极简模式加可回放事件流，是控制变量的干净地基；
* 维护复杂工具链的

：它给工具、流程、UI 提供了一套共同的运行时语义。

反过来，只想快速攒个单任务助手的，这套东西对你来说是绕远路。它服务的是那种能力会长、工具会换、要养三五年的系统。

最后说个题外话

这仓库比代码更让我意外的是文档：几乎每个包的 README 末尾都有一节“已知限制与暂缓事项”，把自己没做好的事一条条列出来——preset 代际不回收、副本会漂移、健康检查只是形状检查，全写在明面上。

一个敢把短板挂门口的底座，通常比把口号挂门口的靠谱。

素材与声明

本文信息来自 DeepSeek Harness 团队公众号 2026-08-13 发布文及 deepseek-harness 开源仓库 v0.1.0-rc.5 源码（README、docs/architecture、packages/preset 等）。项目处于开发者预览阶段，文中描述以该源码快照为准，后续版本可能调整。