Harness 与 Agent 工程 · 运行控制与长任务 · 2026-08-25

一切皆插件:DeepSeek Harness 工程拆解

DeepSeek Harness开源首日star破183k,以“一切皆插件”重构agent runtime,拆解仓库结构、主循环等工程细节,解析技术价值与社区反响。 核心内容:

  1. 开源首日技术表现与社区反馈(star/fork数据、Armin Ronacher评价)
  2. “一切皆插件”的工程架构拆解(仓库结构、核心子系统、可替换插件设计)
  3. 关键技术细节与使用场景分析(主循环、沙箱、日志及工程问题解答)

导读:DeepSeek 在 2026-08-13 开源的 dsh(developer preview),把 agent runtime 的每一层——模型适配器、工具注册表、会话日志、沙箱、审批策略、agent loop、UI——都拆成可挂载的插件。本文按"一切皆插件"这条线拆开 dsh 的工程实现,从仓库结构到事件三域,从 Turn/Step 主循环到沙箱与 append-only 日志,最后回答一个工程问题:什么时候该用、什么时候不该用、什么时候该关注它。


2026-08-13:开源第一天发生了什么

DeepSeek 在这一天把 agent harness 以 developer preview 形式开源,仓库地址 deepseek-ai/deepseek-harness,MIT 协议,编号 0.1.0-rc.6,README 在 Developer preview 一节写明警告:THERE WILL BE COMPATIBILITY-BREAKING CHANGES。

开源数小时 star 数破 3 万,到今天(2026-08-22)仓库 183k stars、20k forks(GitHub 仓库页),而发布节奏目前仍在加速。

但 dsh 不是新模型,也不是又一个 API 客户端。它做的是"把模型包起来让它能动"的那一层——harness。

Claude Code、Codex CLI、Cursor Composer 都在做类似的事,但 DeepSeek 把这件事的执行度拉到了另一个位置:连 agent loop 本身都是可替换的插件。

官方原文是"There is no privileged core to patch: you extend dsh by mounting a plugin beside the others"。

听起来像是又一句营销口号。

但打开仓库看,这不是口号:仓库根目录里 .agents/ 和 .claude/ 目录并存,AGENTS.md 和 CLAUDE.md 同名文件并存,packages 目录下按职责分成数十个 group、组内包平级,core/ 里是官方文档列出的 6 个核心子系统。

Armin Ronacher 第二天在 X 上的评价很能说明社区第一反应:"这是我第一次在这个领域看到真正新东西,让我想回头重审我们的某些选择。"

也有不少反对意见。

Hacker News 上有人立刻甩出 plugin fatigue:"Every product relying on 'community plugins' for their features implies it works fine the 6 first months, then it's a nightmare of incompatible, deprecated, incompatible plugins, with no consistency and no governance."

也有人嫌粗糙:UI 简陋、配置复杂、文档读起来像在啃论文。

还有一件事。@deepseek-ai/dsh 在 npm 上存在的前 62 小时里,每个 rc 版本都把 262.3 MiB 的 Claude Code 二进制打进了依赖闭包。

2026-08-12 22:36 UTC 发布的 0.0.1-rc.5,依赖闭包里就有 @anthropic-ai/claude-agent-sdk 及其平台原生二进制;0.1.0-rc.2(08-13 09:48 UTC)把这个依赖移除,安装体量随之大幅回落。

问题在于 npm 的 access 是 package 级不是 version 级——包从私有转 public 时,registry 上已存在的所有 rc 都自动变成 world-readable。

你今天还能 npm install @deepseek-ai/dsh@0.0.1-rc.5 装到那个带着 Claude Code 二进制的旧版本。这是开源流程里一次有教育意义的失误:scope public 之前应该清掉旧发布。


dsh 仓库长什么样

dsh 是一个大型 TypeScript monorepo。这些 packages 不是层叠的依赖树,而是按职责分组挂在 packages 目录下:

•核心(packages/core/):•session(append-only SessionEvent 日志)•system-prompt(提示词片段组装)•tools(作用域工具注册表)•agent(Agent 接口与 registry)•agent-loop(默认 driver)•scope(per-agent 作用域注册原语)•模型层(packages/llm/):消息与流词表、模型 adapter 接缝•执行环境:shell、subprocess、terminal(持久 PTY)、sandbox、fs、lsp、web(搜索与抓取)•Agent 能力:subagent、skill、workflow、jobs、todo、plan、goal•会话与数据:session-query、attachment、spill、storage、settings、credentials•人机协作:interaction(审批/权限/ask-user)、feedback、identity•接口层:api(Typert RPC 网关)、sdk(进程外 JSON-RPC SDK)、acp(Agent Client Protocol 服务端)、host/client(Web UI 两半)、hooks(Claude Code/Codex 协议桥)•自我修改:extensions(实时插件检视 + 模型自己写插件并挂载/卸载)这个列表有一个特点:几乎每个能力都有一个独立的 ctx 键。ctx.sessions、ctx.tools、ctx.agentLoop、ctx.shell、ctx.subprocess、ctx.sandbox、ctx.llm——没有"特殊"的子系统。

这是 Cordis 服务注册模型的核心:每个能力由某个插件提供,任何插件都可以替换某个服务的实现。这种结构最直接的好处是,单个 capability 的演进不会牵动其他 capability,bindings 只发生在 ctx 键的层面。

仓库根目录有一个细节值得注意:AGENTS.md 和 CLAUDE.md 两个文件并存,README 里写明"For agents, follow AGENTS.md"。这意味着 dsh 同时为 Claude Code 和其他 agent 提供工作入口——不只是兼容性宣称,而是根目录就摆了两份入口文件。


Profiles × Bundles × Patch:一切皆插件的"组装方式"

一个运行中的 dsh 不是一坨预编译产物,而是一棵插件树,按三层组合而成:

•Profile:命名组合,存在 Harness home 里。它列出 bundle 栈、用户自装的 out-of-tree 插件、以及用户自己的 cordis.patch.yml 补丁。web 和 headless 作为模板 ship。•Bundle:Cordis config rows 加代码的分发格式。它插入什么,上层依然可以 patch。•Patch:针对 row id 替换整段 config 或插入新 row。加载顺序很关键:profile 列出的每个 bundle 按序应用 → profile 的 cordis.patch.yml → home 层 patch → --patch 命令行 overlay。后者覆盖前者。

这种结构解决的是"怎么把插件装到合适位置"的问题。默认装一个 plugin 不会污染基础配置,因为它作为新 row 插在 patch 链最上层;要换底层实现只需要在 patch 层指向同一个 row id 给一个新实现。dsh --profile web --dump-config 命令会把组合后的实际插件树打印出来——这是排查"为什么我的 plugin 没生效"的最快路径。

## 打印 web profile 实际生效的插件树dsh --profile web --dump-config

packages/bundle/base 是每个 profile 的第一层(model adapters、tools、persistence、sandbox、approval policy、settings、credentials、telemetry),packages/bundle/web-app 在它上面加浏览器应用,packages/bundle/headless 加无 server 的一次性 runner。

这种分层保证了"先有最小可用再加 UI"的默认路径。


核心包与 ctx 键空间:一切皆插件的"基础字典"

dsh 把所有能力都映射到 ctx 键上。最核心的几个:

Package 职责 ctx 键
core/session append-only SessionEvent 日志与内存 store ctx.sessions
core/system-prompt prompt-section 与 tool-schema 组装 ctx.systemPrompt
core/tools 作用域工具注册表与受保护执行管道 ctx.tools
core/agent Agent 接口、live registry、agent/* 事件 ctx.agents
core/agent-loop Agent 接口的默认 driver ctx.agentLoop
llm/llm 消息与流词表 + adapter 接缝 ctx.llm

理解 dsh 架构有一把钥匙:底层 Cordis 框架约定每个注册都带一个 disposer(注销器)。注册 Tool 时记录"如何注销这个 Tool",注册 Prompt section 时记录"如何移除这段 prompt",挂载 Timer 时记录"如何停止这个 Timer"。

组件卸载时,按注册逆序回滚所有 effect。这就是 Cordis 的"时空可组合性"——卸载即回滚,不需要重启进程。dsh 能热装热卸,正是因为每个注册都自带了反向操作。

工程上的体现是:你正在跑一个 dsh 会话,往配置里加一个 plugin,registry 立刻生效;删掉它,注册的服务、监听、提示词片段、tool schema 全部消失,普通插件系统(Node 的 require 缓存、Python 的 sys.modules)很难做到这一点。下面是一个最小 plugin 的样子:

// 一个最小 dsh 插件:通过 ctx 注册一个 service、一个事件监听,并各自带 disposerimport type { Context } from '@deepseek-ai/d…
— 以上为试看内容(约 40%),开通会员后阅读全文 —

原文出处:https://www.53ai.com/news/OpenSourceLLM/2026082517502.html