DeepSeek Harness 解读：把 Agent 框架做成「Linux 内核」的野心

一天 78,604 ⭐，6,840 forks —— 这是 DeepSeek 在 2026-08-13 发布的 deepseek-harness（内部代号 dsh）的首日战绩。本文从架构视角拆解这个项目，聊聊它想做什么、怎么做、以及值不值得学。

它到底是什么

DeepSeek Harness 不是一个 Agent 产品，它是一个 Agent 运行时框架。

它的官方口号是 "Everything is a Plugin"（一切皆插件）。模型适配器、工具注册表、会话日志、Agent 循环本身 —— 这些传统 Agent 框架里"硬编码"的部分 —— 在 dsh 里全都变成了可热插拔的插件。

它想当 Agent 领域的 "Linux 内核"：核心只做调度和事件总线，其他一切都是用户空间插件。你想换 LLM？换 ctx.llm 的 adapter。你想换工具执行策略？换 ctx.tools 的 provider。你想给 Agent 整个换一套沙箱？换 ctx.sandbox 后端，连 Bash / PTY / LSP 全跟着走 —— 不需要 fork 任何代码。

底层基于 Cordis 的"时空可组合性"理论（论文）：注册是 effect（卸载时副作用自动撤销），依赖是 coeffect（响应式声明）。这两个数学性质叠加，从单组件到大系统都成立。

它怎么转：插件树组装

dsh 的运行时是一棵 插件树（Plugin Tree），启动时由"有序层"从空 entry list 组装：

Profile（命名组合）
  └─ 列出的 Bundles（按顺序）
       └─ Profile 的 cordis.patch.yml（覆盖前层）
            └─ Home-level patch
                 └─ --patch 叠加（命令行）

每层都可以覆盖前层，靠 id 寻址定位行。想看你的机器真实启了什么？一行：

dsh --profile web --dump-config

打印的每一行你都可以 patch 替换。

核心 ctx 服务只有 4 个：

其他 35+ 包（e2b、shell、subprocess、terminal、fs、lsp、skill、web、subagent、workflow、hooks...）都是挂在这 4 个服务上的能力。

5 类扩展点（一切新行为都挂这里）

dsh 铁律：新行为上扩展点，不改 loop。改 loop 必须同步更新架构文档。

举几个例子感受一下：

权限门 —— 一个普通 Cordis 插件，监听 tools/pre-execute：

export const name = 'permission-gate'
export function apply(ctx: Context) {
  ctx.on('tools/pre-execute', async (exec, next) => {
    if (!(await isAllowed(exec))) {
      return { kind: 'deny', reason: 'Denied by policy.' }
    }
    return next()
  })
}

UI 渲染 —— 监听 session/event 流（assistant token delta + turn/step 边界），输入走 agent.followup()：

ctx.on('session/event', (_session, event) => {
  if (event.type === 'assistant/chunk' && event.data.chunk.type === 'text-delta') {
    render(event.data.chunk.text)
  }
})
onUserInput(text => ctx.agents.get(SessionId('client-session'))?.followup(...))

协议驱动 —— 把 ACP/Claude Code/Codex 桥接到 ctx.agents，输入 → followup()，输出 → session/event 流。

5 条设计铁律（必读）

1. 新行为上扩展点，不改 loop —— 想动 Agent 循环？写插件，不要改 core。
2. waterfall 必须 next() —— 否则短路下游。这条在 lints 和文档里被反复强调。
3. Model-visible ⟺ logged —— 运行时不变量。任何到达模型请求的内容必须能从 session log 重建。绕过的代价是 fork/resume/telemetry 全部失效。
4. Capability seam 三件套 —— Service Definition + Service Provider + Consumer。一角色不构成 seam，必须三件套齐才能"换 provider 改全产品"。
5. 部署相关选择必须是 Config 字段 —— 不能是 DEFAULT_* 常量或测试 hook。协议常量/外部规范/安全不变量除外。

三个最容易翻车的卡点

1. 想改 core → 应该写 plugin 新手本能去改 agent-loop.ts。但 90% 的"想改循环"都是"应该写个新插件"。

2. waterfall 忘了 next() 监听器收 (args..., next)，必须调 next() 让链条继续。

3. 把模型可见字符串直接拼 prompt，没走 session log "Model-visible ⟺ logged" 是不变量。绕过 → fork/resume/telemetry 全部失效。

5 分钟上手

dsh 提供 5 个入口：

要求 Node ≥22.19，ESM-only。

我的判断

短期：不用急着部署，但读一遍 docs/architecture.md（11KB 精华），把"插件树启动模型"这个范式记进脑子。

中期：如果你正在做 Agent / 工具栈 / 工作流框架，dsh 是现成范式参考。它解决了三个老问题： - vendor lock-in：换 provider 不需要 fork - 测试污染：每个能力可独立 patch、可独立卸载 - 生态碎片化：所有能力走同一套事件总线，组合有数学保证

长期：等 0.1.0 正式版（不是 rc）出来再考虑生产用。当前 Developer Preview 阶段明确说会有破坏性更新。

灵魂一句话：

让"更换一个能力供应商"等价于"更换整个产品的灵魂"，而这一切都靠"时空可组合性"这个数学性质保证 —— 注册是 effect（时间维度可逆）、依赖是 coeffect（空间维度响应式），两层叠加构成可演化的系统。

参考链接： - 仓库：https://github.com/deepseek-ai/deepseek-harness - 主页：https://deepseek.com/harness - 架构文档：https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md - Cordis 入门：https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md - 插件 cookbook：https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cookbook/extension-cookbook.md - 论文：A Programming Paradigm for Spatiotemporal Composability