DeepSeek Harness —— 一切皆插件的 Agent Harness
一份讲”怎么实现 + 为什么这么设计”的解读。本文以 2026-08-13 开源的 DeepSeek Harness（
dsh）为主轴，串起它与 Claude Code 2026|Claude Code 2026、pi|pi 的取舍对比。涉及既往知识点时用[[双向链接]]就地引用，不再单开”回顾”章节。
1. DeepSeek Harness 是什么
DeepSeek Harness（dsh）是 DeepSeek AI 于 2026-08-13 开源的开源 agent harness（智能体框架），MIT 协议，TypeScript 实现，开源约十天即达 18 万+ stars。当前是 developer preview（开发者预览）：
“DeepSeek Harness is currently in developer preview and is iterating rapidly. THERE WILL BE COMPATIBILITY-BREAKING CHANGES.”
官方公告页沿用了与 Harness工程 页面一致的公式：
“Agent = Model + Harness”
“The model is the soul of an agent. A harness lets an agent understand its environment, use tools, and keep working in real-world settings.”
它面向的是 agent harness 开发者（不是终端用户）。理解它和 learn-claude-code教程、pi-coding-agent最小化设计 关系的关键，就一句话：前两者的 harness 都有一个”不可替换的核心”，DSH 连核心本身都是插件。 官方架构文档的原话：
“There is no privileged core to patch: you extend dsh by mounting a plugin beside the others.”
本文其余章节，就是在拆解这句话”怎么实现”、“代价是什么”。
2. 理论根基：为什么”一切皆插件”能成立
“一切皆插件”不是一句营销口号，它背后有一个形式化基础——Cordis 框架及其论文《Cordis时空可组合性论文》。这一节讲的是实现原理，不是概念罗列。
2.1 问题：动态组合有两个正交难点
论文指出，从插件系统到”自我演化的 agent harness”，现代软件都需要动态组合，但它长期缺乏形式化基础。作者把它拆成两个正交维度：
“temporal composability, the ability to completely revert a component’s side effects upon removal.”
“spatial composability, the ability to declare and reactively manage inter-component dependencies.”
- 时间可组合性：组件被移除时，副作用能完全回退。
- 空间可组合性：组件间依赖能声明式表达并响应式管理。
2.2 两个运行时机制怎么实现
对应这两个维度，论文给出了两个机制：
“we formalize revertible effects, in which every context transformation carries an inverse that the runtime tracks.”
“we formalize reactive coeffects, in which each change of the context notifies a component against its coeffect specification.”
- 可逆效应（revertible effects）：每次 context 变换都携带一个逆变换，由运行时追踪。这就是”注册返回 disposer、卸载能回退”的原理来源。
- 反应式共效应（reactive coeffects）：context 每次变化，都按组件的 coeffect 规格通知它。这就是”依赖声明 + 事件通知”的原理来源。
2.3 统一成一个 context 类型
“We unify the effect context and the coeffect context into a single context type, which constitutes a programming paradigm.”
PS：为什么要把两个 context 统一？因为”回退”和”依赖”是同一件事的两面——一个组件既是”往 context 里写效果”的生产者，又是”依赖 context 里别人服务”的消费者。分开建模会产生两套不一致的运行时；统一成一个 context，才能让”组件”这个概念同时携带可逆性与响应性，进而构成一个可演算的编程范式。
落到 Cordis 的 API，就是五个思想（官方 primer）：插件是对象、context 是服务仓库（ctx.<key>）、inject 声明依赖、typed events 通信、注册是可逆 effect。详见 Cordis 与 时空可组合性。
3. “一切皆插件”怎么实现
上一节是理论，这一节是工程落地。DSH 里”插件”不是挂在核心外的扩展，而是系统里唯一的存在方式。
3.1 注册即 effect：可逆的来源
Cordis 的铁律：
“Registrations are effects: every contribution goes through
ctx.effect()/ctx.on(); a registry’sregister()returns the disposer.”
每一个贡献（prompt 段落、工具 schema、适配器、事件监听器）都通过 ctx.effect() / ctx.on() 安装，register() 返回 disposer。插件卸载时，disposer 把这些贡献可预测地回退。这就是第 2 节”可逆效应”的工程落点。
PS：为什么强制”每个注册都返回 disposer”？因为只有注册可逆，“可替换”才是安全的——否则换掉一个插件会留下孤儿状态。这直接回应了 Harness工程 里”扩展不侵入核心”的老问题：learn-claude-code教程 靠 Hook 的发布-订阅来不污染循环，DSH 则更进一步，靠”注册可逆”让每个插件都能被干净地装上和拆下。
3.2 inject 声明依赖：加载顺序的由来
插件用 inject 声明它需要哪些服务，只有这些服务存在后它才被加载。PS：加载顺序不是手动编排的启动序列，而是从依赖关系推导出来的。这对应论文里的”反应式共效应”——依赖被声明，变化被通知。
3.3 四种事件分发模式
事件按四种模式分发，各自解决不同的协作需求：
| Mode | 是否 await | 顺序 | 有返回值 |
|---|---|---|---|
emit | 否 | 注册顺序 | 否 |
waterfall | 否 | 注册顺序 | 是 |
parallel | 是 | 并行 | 否 |
serial | 是 | 注册顺序 | 是 |
其中 waterfall 是”环绕式中间件”：监听器收到 (...args, next)，调 next() 委派给下一个服务，直接 return 则短路。PS：waterfall 正是权限拦截、prompt 改写这类”要么放行、要么接管”的场景所需的语义——它把 learn-claude-code教程 里 Hook 的”返回 blocked 中断”和 MCP 模型上下文协议 工具调用的”转发-等待-打包”统一成了同一个原语。
3.4 组合来自配置：profile / bundle / patch
一个运行中的 dsh 是启动时按序分层组装出来的插件树：
- Profile：命名组合，列出所堆叠的 bundles、外置插件、用户的
cordis.patch.yml。 - Bundle：Cordis config rows + 代码的分发格式。
- 分层顺序：bundle 按序 → profile patch → home patch →
--patch。patch 按 row id 定位并整体替换。
用 dsh --profile web --dump-config 能打印本机实际启动的树，任何一行都能被自定义 patch 替换。
PS：为什么用”分层配置”而不是”改代码”？官方公告页的答案是——开发者能在配置里选择/替换/扩展任何能力，不改源码。这和 pi-coding-agent最小化设计 里 Mario Zechner”你敢碰我 system prompt 我立刻改回来”的诉求殊途同归：可组合性就是”拥有感”——只不过 Mario 靠”代码量小到能全读懂”，DSH 靠”配置分层到能全改写”。
4. 会话日志：单一真相源
DSH 的第二根支柱，回答”Agent 的状态放在哪”这个问题。详见 会话日志单一真相源。
4.1 推导而非存储
“A
Sessionis an append-only log of typedSessionEvents — the single source of truth… The LLM message history is derived from the log, never stored separately; replay is re-derivation from the same events.”
模型看到的 LLM 消息历史，是 deriveMessages() 从日志投影出来的，不单独存一份。
PS：为什么”推导”而非”存两份”？两份真相源会漂移——你存的”消息历史”和实际发生过的”事件”迟早对不上。只存一条 append-only 日志，历史就永远是事实的投影，不存在第二份需要同步的拷贝。
4.2 核心不变量：模型可见 ⟺ 已记录
“Model-visible means logged. Anything that reaches a model request must be reconstructable from the log, and a runtime invariant asserts it.”
任何进入模型请求的内容，都必须能从日志重建；这条不变量由运行时断言强制。新增一个”模型可见的输入”（比如一种新的上下文注入），就必须新增一个 session event 类型。
PS：为什么要用运行时断言来强制？因为这是”可追溯性”的物理保证。官方公告页把它的价值说得很直白：
“Everything the model sees is recorded in an append-only session log… Resume, fork, search, and replay all operate on the same event stream.”
4.3 与”文件即接口”的关系
这一设计和 文件即接口 同源，但推进了一步：Mario 的 TODO.md / PLAN.md 是零散的文件，DSH 把状态统一成一条可重放、可审计、可派生的事件流。上一课诊断的 Subagent”渐进式信息偏移”、TodoWrite”状态锁在模型内存里”，在 DSH 里被”一切从同一条日志读状态”部分消解——因为状态不再散落在多个地方。
5. 能力接缝（Capability Seam）
DSH 统一”可替换点”的词汇，叫 能力接缝：
“A seam is a swappable capability with three roles: a Service Definition declaring the interface, a Service Provider implementing it, and a Consumer using it, commonly a model-facing tool.”
三角色：服务定义（接口）、服务提供者（实现）、消费者（通常是对模型暴露的工具）。只有单一角色不算接缝——新增一个能力意味着设计齐三个角色。
PS：接缝的价值在”一次替换改变整个产品”：
“Filesystem and subprocess providers share one execution world, so pointing them at a remote sandbox moves Bash, PTY, and LSP with them, with no provider forks.”
文件系统与子进程 provider 共享同一个执行世界，把它们指向远程沙箱，Bash、PTY、LSP 一起迁移，不需要为每个能力写独立分叉。Subagent 也是接缝——从”一个全新子 agent”到”在另一个产品里委派一个回合”，都藏在同一个接口后面。
回顾关联：之前学到的|之前学到的 Tool Use（dispatch table）、Subagent、MCP 模型上下文协议 在 DSH 里都被收编为”接缝”的不同实例。这是对”加一个新工具 = 在 dispatch table 加一行”的升级——DSH 连 dispatch table 本身（ctx.tools）都是接缝。
6. 三方对比：Claude Code / pi / DSH 的取舍
这是本文的核心分析章节。三者的共同点是都遵守 Agent = Model + Harness，分歧在于**“核心能不能换”**。
6.1 先看 Claude Code 2026 的新变化
本文对 Claude Code 的认知基于 2026-08 抓取的最新 CHANGELOG（2.1.241）|2026-08 抓取的最新 CHANGELOG（2.1.241），与 2025 年的旧认知|2025 年的旧认知 有实质差异——这正是你担心”旧资料时效性不好”的地方：
- 插件系统：Claude Code 把 slash commands、agents、skills、hooks、MCP 统一打包成插件（
commands/ + agents/ + skills/ + hooks/ + .mcp.json），用marketplace.json分发。这是对旧认知里”四类扩展机制”的打包层。 - Subagent 一等公民 + 多智能体：官方 code-review 插件 = 5 个并行 Sonnet agent（CLAUDE.md 合规/缺陷/历史/PR 历史/注释），feature-dev = code-explorer/code-architect/code-reviewer。旧认知里的 Subagent 是”主从、临时”，现在产品内置了并行的多 agent 工作流。
- 跨会话消息：
ListAgents/SendMessage/ teammates，跨机器会话像队友一样通信。旧认知里这是 learn-claude-code教程 s15 的”Agent Team”设想，现在进了产品。 - 沙箱（Linux/macOS）、Auto mode 权限分类器（severity-scored）、Remote Control / 云会话、
/goal长期目标、worktree 隔离。
但要注意一个边界：Claude Code 核心实现不公开——我们只能看到 CHANGELOG 和插件面，看不到它内部的循环、状态、权限怎么实现。这个”实现可见性”本身就是三方对比的一个维度。
6.2 对比表
| 维度 | Claude Code（2.1.241） | pi（pi-coding-agent最小化设计） | DSH（0.1.1-rc.2） |
|---|---|---|---|
| 核心可否替换 | 否（固定核心 + 挂载点，插件是打包层） | 否但极简（代码量小，作者全掌控） | 是（连 agent loop 都是插件） |
| 工具哲学 | 专用工具铺路、防错 | 4 工具（read/write/edit/bash），信任模型 | 工具是接缝；按模式选（Standard 全 / Minimal 两工具） |
| System prompt | 运行时拼接、长 | <1000 tokens | PromptSection + order + waterfall 装配 |
| 状态管理 | 会话 + 记忆 + /goal（闭源） | 文件（TODO.md / PLAN.md） | append-only 会话日志派生一切 |
| MCP | 原生支持 | 反对（CLI + README） | hooks 桥接兼容 + 接缝统一 |
| Subagent / 多 agent | 插件内 agents/ + 跨会话消息 | 无（bash 自调用 + tmux） | 接缝 + experimental Agent Teams |
| 权限 | 三道闸门 + Auto mode 分类器 + 沙箱 | YOLO（无权限系统） | interaction 插件（approval/permission/commands） |
| 扩展方式 | 装插件 / 写 hook / 加 MCP | 改源码（代码量小） | 挂插件 + 改配置（cordis.yml/patch） |
| 实现可见性 | 核心闭源 | 全开源 | 全开源（含 architecture/AGENTS/子系统文档） |
| 成熟度 | 产品级（2.1.x，14 万+ stars） | 个人项目（Terminal-Bench 验证） | developer preview（明确破坏性变更） |
6.3 取舍分析
Claude Code 的取舍：用”核心不可替换”换取可预测性 + 生态——插件的 agents/、skills/、hooks/ 都挂在一个稳定的产品核心上，第三方插件作者不用理解核心就能扩展。代价是 Mario Zechner 批评过的膨胀（“80% 的功能我用不到”）和核心黑盒（你无法替换它，只能绕开它）。它的 2026 演进方向其实是”在不放开核心的前提下，把挂载点打包得更整齐”——插件系统就是这一思路的产物。
pi 的取舍：用”极致可控”换取极简——system prompt <1000 tokens、4 工具、无 MCP/Subagent，换来 上下文工程 上的完全掌控。代价是一切自己写：缺 grep/glob/ls 这类搜索工具，模型要自己拼 bash；没有现成的多 agent 协作，只能 bash 自调用 + tmux。它成立的边界是”前沿模型 + 单人场景”。
DSH 的取舍：用”最大化可组合性”换取理解成本 + 不稳定——连循环都能换，意味着你要理解一个行为，得先搞清是哪几个插件在树上、按什么顺序分层；而 developer preview 的破坏性变更意味着你现在学的 API 可能随时变。它的边界是”你要自己组装一个 Agent 环境”的场景，而不是”开箱即用”。
一句话总结三者的哲学：
- Claude Code：“把环境设计成模型不犯错的形状，但核心由我们掌控。”
- pi：“信任模型，别替它做判断，也别造你不需要的东西。”
- DSH：“把’该信任模型还是该约束模型’这件事，交给配置去选。“
7. DSH 如何内置两派：四种运行时模式
上一节的三方对比，DSH 其实用一个机制就回答了”极简派 vs 工程派”这个 老争论|老争论——它把两派做成了配置选项。官方公告页列出四种模式：
- Standard mode（标准模式）：完整工具集——file editing、shell、file/web search、skills、planning、goals、subagents、workflows。这是工程派（Claude Code 路线）的内置化。
- Code mode（代码模式）：Standard 全部能力，但工具通过 Code Mode SDK 暴露，“so the model can combine multi-step operations in one TypeScript program”——让模型在单个 TypeScript 程序里编排多步操作。这是第三种路线：把”编排权”从 harness 的循环逻辑转移到模型写出的代码里。
- Minimal mode（极简模式）：只保留两个工具——persistent bash +
str_replace_editor，“for benchmarking models in a minimal environment”——这是极简派（pi|pi 路线）的内置化。 - Creator mode（创作者模式）：inspect 当前 runtime、在内存中测试 Cordis 插件、组合成新模式。这是元层次：你不是在两派之间选，而是在”捏一个自己的派别”。
PS：为什么 DSH 要内置 Minimal mode？因为它要回答一个 pi-coding-agent最小化设计 里反复出现的实证问题——“极简 Agent 到底能不能打”。Minimal mode 的官方定位是 benchmarking，说明它把”极简”当成一个可测量的配置，而不是一个哲学立场。反过来，Standard mode 又说明它不否认”工程派”的价值。争议被可组合性吸收了：不再是”该不该用 MCP/Subagent”，而是”我这个场景用哪个 profile”。
这一节直接回应了你说的”DSH 里包含两者的配置选项”——是的，Standard 和 Minimal 就是两派，Creator 则是”都不选，自己组”。
8. Agent Notes：Agent 自己写设计文档
Agent Notes（代理笔记）是 DSH 独有的制度，也最能体现它”自我演化”的定位。
实现：每条 Agent Note 是一个类 RFC 的文件，路径编码 {lifecycle}/{class}/yyyy-mm-dd-topic-title.md。生命周期 proposed/ → implemented/ / rejected/，类别 feature/bug-fix/simplification/architecture/process/testing。implemented 笔记强制包含 ## Problem / ## Decision / ## Alternatives considered / ## Consequences。归档后永久冻结。
PS：为什么强制 ## Alternatives considered？官方原文给了理由：
“A decision recorded without what it beat invites re-litigation.”
（一个没记录”它打败了谁”的决策，会招致反复争论。）而”每个非平凡改动必须配一条 Agent Note”这条铁律，本质是把设计决策的隐性知识外化成可机械校验的文件——而且执行者是它自己的 agent（DSH 用自己的 agent 开发自己）。
与 pi 的对照：Mario 的博客|Mario 的博客 之所以珍贵，正因为它记录了每个”不做”背后的理由。DSH 把这个实践制度化了。差别在于：Mario 的”理由”是他作为人类作者写的；DSH 的”理由”是 agent 在开发过程中被强制写下的。这也是论文里那个词组 “self-evolving agent harnesses（自我演化的 agent harness）” 的一个具体样本。
9. 争议与未定
正反观点都应覆盖：
- 官方自己承认不稳定：“THERE WILL BE COMPATIBILITY-BREAKING CHANGES”，版本才 0.1.1-rc.2，明确 “foundation over blast radius”（基础优先于影响半径）。
- “可替换”不等于”应该替换”：可替换的循环仍需要一个稳定的
Agent契约作为生态锚点，否则插件生态无法建立。DSH 用”接缝 + 单一真相源 + 运行时不变量”来兜住灵活性，防止变成”人人各拼各的”。 - 极简派的质疑依然有效：Mario 会问——如果你真信”模型已经够强”，为什么还需要这么重的插件框架？DSH 的 Minimal mode 是”框架里选出来的极简”，和 Mario”从零手写、完全拥有 system prompt”的极简，仍是两种东西。
- 未验证：18 万 stars 是关注度，不是生产验证；Agent Notes 能否规模化、Agent Team 的 token 协调开销、Code mode 的实际效果，都还没有实测数据。
10. 一张更新的决策地图
| 你的场景 | 推荐路径 |
|---|---|
| 学习 Agent 原理 | 先 learn-claude-code教程 理解机制，再 [[DeepSeek-Harness官方仓库与架构|读 DSH 架构 |
| 想系统学 Harness 工程 | 本文 + Cordis时空可组合性论文 补理论，Claude-Code插件系统与2026演进 看产品化演进 |
| 个人日常编程，强模型 | 极简路线（4 工具 / DSH Minimal mode） |
| 个人日常编程，国产中等模型 | 工程路线（完整 Harness + Hook 兜底）/ DSH Standard mode |
| 想自己拼一个 Agent 环境 | DSH（配置组合 + Creator mode），接受 developer preview 不稳定 |
| 团队协作 / CI/CD | 完整 Harness + 状态落盘 + 错误恢复；多 agent 慎用 |
| 想研究”可替换的 harness 架构” | DSH + Cordis，重点读 一切皆插件、会话日志单一真相源、能力接缝 |
参考来源
本文锚定在 2026-08-23 实时抓取的以下权威来源（原始底稿见 processed/ 目录）：
| 来源 | 说明 |
|---|---|
| deepseek-ai/deepseek-harness 官方仓库 | README、docs/architecture.md、AGENTS.md、docs/cordis-primer.md、子系统文档、.agents/notes（Agent Notes 制度） |
| DeepSeek Harness 官方公告页 | deepseek.com/harness/en/（“Everything is a plugin. Every run is traceable.”、四种运行时模式） |
| cordiverse/cordis + paper | Cordis 框架 +《A Programming Paradigm for Spatiotemporal Composability》（2026-08-13 草稿） |
| anthropics/claude-code 官方仓库 | README、CHANGELOG（2.1.241）、plugins/README.md、.claude-plugin/marketplace.json（2026-08 抓取） |
| Hacker News | ”DeepSeek Harness developer preview”（745 分）社区反应 |
| 既往知识点（wiki 已摄入可追溯） | Anthropic官方Agent构建指南、learn-claude-code教程、pi-coding-agent最小化设计、Harness范式串讲 |