DeepSeek Harness 深度解析：一切皆插件的 Agent 运行时
1. 为什么需要 Harness？
2026年8月13日，DeepSeek在MIT许可证下开源了DeepSeek Harness，一个Agent运行时框架（命令行工具dsh），上线数小时内GitHub Stars突破33,000。要理解这次发布的意义，需要先回答一个问题：AI Agent领域长期缺失的是什么？
过去两年，Agent领域的注意力几乎完全集中在模型层——更大的参数量、更长的上下文窗口、更高的基准分数。但一个被反复验证的事实是：顶尖模型配上平庸的运行时，其表现不如一个好模型配上优秀的运行时。正如华为诺亚方舟实验室等机构在综述中所指出的，Agent的质量（成功、效率、安全与泛化）并非单纯由模型能力决定，而是从模型能力、运行时基础设施、任务结构和评估设计的交互中涌现的[1]。
DeepSeek将这一洞察浓缩为一个公式：
Agent = Model + Harness
模型是Agent的推理引擎，但推理引擎需要一套运行时才能感知环境、调用工具、维护状态、在多次交互中持续工作。Harness就是这套运行时。没有Harness的模型，只是一个昂贵的自动补全工具。
在这个框架下，大多数AI编码Agent（Claude Code、Codex、Cursor）都是集成产品——模型、工具、执行循环和UI紧密耦合。DeepSeek Harness选择了一条不同的路：将Harness本身作为独立产品开源，并让其中每一个组件都可替换。
2. 核心理念：一切皆插件
2.1 没有特权核心
Harness的架构文档中有一句关键表述：
没有需要打补丁的特权核心；你通过在其他插件旁边挂载一个插件来扩展dsh。
这意味着：模型适配器、工具注册表、会话日志、Agent循环、沙箱、存储、调度、UI——全部是插件。Cordis内核只负责三件事：挂载插件、卸载插件、解析插件间依赖。所有实际能力都存在于插件中。
传统Agent框架的扩展方式是：找到对应的源码文件，修改它，重新编译。Harness的扩展方式是：写一个插件，挂载到配置中。换模型、换沙箱、改Agent循环逻辑、扩展UI——全部在配置层面完成，不需要fork源代码。
2.2 分层组合机制
Harness的启动过程是一个分层配置的叠加：
命令行 --patch 覆盖 ← 最高优先级 ↑ Home 级 ~/.dsh/cordis.patch.yml ↑ Profile 级 cordis.patch.yml ↑ Bundle 列表（按顺序堆叠） ↑ dsh-base（底层基础设施）Profile是命名的运行配置（web和headless是两个内置模板）。Bundle是插件的分发格式，在自己的package.json中声明身份和Cordis配置行。Patch让你在不修改Bundle源代码的情况下覆盖任何配置行。执行dsh --profile web --dump-config可以看到完整的配置树，打印出来的任何一行都可以被一个Patch替换。
3. Cordis：形式化基础
Harness的插件系统建立在Cordis之上——一个由北京大学与DeepSeek联合研究的形式化框架，其核心论文《A Programming Paradigm for Spatiotemporal Composability》与Harness同一天发布[2]。
3.1 问题：动态组合的两个维度
传统软件组合是静态的——函数调用、模块导入在编译时确定。但Agent Harness面临的是动态组合：组件在运行时加载、卸载、重新配置。Cordis将这个问题分解为两个正交维度：
时间可组合性：当一个插件被卸载时，它对系统所做的所有修改必须被完全、安全地逆转。插件注册的文件监听器、分配的内存、打开的网络连接——卸载时必须全部清理，不留残留。
空间可组合性：插件之间需要声明和管理依赖关系。当插件A依赖插件B，而B被卸载或更新时，A必须被妥善通知和处理。
3.2 两个核心机制
Cordis用两个形式化机制解决这两个维度：
可逆效应（Revertible Effects）：插件的每次注册操作都是一个"效应"，每个效应携带一个逆操作。运行时跟踪所有效应。插件卸载时，运行时自动执行所有逆操作，将上下文恢复到挂载前的状态——这保证了时间可组合性。
响应式协效应（Reactive Coeffects）：插件声明它"需要什么"（协效应规约）。上下文变化时，运行时根据规约自动通知插件——激活、停用或不受影响——这保证了空间可组合性。
Cordis论文还证明了一个关键定理：如果一个系统的每个组件都满足局部时空可组合性，那么整个系统也满足全局时空可组合性。这为Agent的自演化（生成并部署新工具或子Agent，而不破坏现有系统）提供了形式化保证。
4. 架构深度解析
4.1 Turn-Step：Agent的工作循环
Harness的Agent循环是精确的Turn-Step模型，每个事件都有明确的扩展点：
turn/start ├─ 声明下一输入 + 已排队的消息 ├─ 组装 prompt sections + tool schemas ├─ agent/pre-step ← 可拦截、重写或拒绝输入 ├─ 拒绝或空输入 → 关闭turn（不产生step，但日志记录） └─ 接受 → step/start ├─ 追加消息到会话日志 ├─ agent/request → llm/stream → assistant/message ├─ tool/call* → pre-execute → execute → post-execute → tool/result* ├─ step/end ├─ 需要更多工具调用 → 进入下一step └─ 完成 → agent/turn-stopping → turn/end三个关键设计：
append-only会话日志。模型看到的一切——系统提示、推理、工具调用及结果、子Agent调度、每次上下文注入——都被记录在不可修改的事件流中。运行时有一个不变性断言：任何到达模型请求的内容都必须能从日志中重建。基于这个日志，你可以恢复、分叉、搜索和回放任何一次运行。
瀑布式事件。agent/pre-step、agent/request、llm/stream和tools/*事件是瀑布式的，监听器必须调用next()才能委托给下一个处理器。这意味着你可以插入中间件来拦截、修改或拒绝任何阶段的请求。
agent/pre-step作为决策点。这个事件决定模型看到什么。监听器可以重写声明的消息，也可以直接拒绝。被拒绝的第一次声明仍然会关闭一个持久化的turn，确保日志中记录了这次尝试——这使得"Agent为什么没做某事"也可以被审计。
4.2 Capability Seam：可替换的能力接缝
Harness引入了一个精妙的概念——Seam（接缝）。一个Seam是一个可替换的能力，由三个角色组成：
- Service Definition：声明接口
- Service Provider：实现接口
- Consumer：使用接口（通常是模型可见的工具）
Seam解释了为什么替换一个Provider可以级联影响整个产品。文件系统和子进程Provider共享一个执行世界——将它们指向一个远程沙箱，Bash、PTY和LSP也一起移动，不需要单独修改。子Agent Provider在同一个接口后面可以变化很大——从一个全新的子Agent到另一个产品中的委托turn。
这意味着，添加一个新能力不只是"写一个工具"，而是设计全部三个角色：定义接口、提供实现、暴露给模型。
4.3 核心包与扩展点
Harness的代码被组织为一系列核心包，每个包在Cordis上下文树中贡献一个特定的服务。下表展示了核心包及其扩展方式：
| 目标 | 机制 |
|---|---|
| 添加模型Provider | 在ctx.llm上注册适配器 |
| 添加模型可见能力 | 在ctx.tools上注册，Schema自动加入Prompt组装 |
| 给会话不同的能力集 | 组合Agent预设，使用isolate域 |
| 添加Shell执行 | 注册ctx.shell后端 |
| 添加后台工作 | 在ctx.jobs上注册 |
| 添加文件系统访问或策略 | 注册ctx.fsProvider或监听fs/*事件 |
| 限制子进程 | 使用ctx.sandbox后端 |
| 拦截请求、工具或Turn | 使用agent/*或tools/*事件 |
| 添加模型可见上下文 | 调用agent.inject() |
| 分叉活跃会话 | ctx.sessions.fork(source, boundary?, childSessionId?) |
| 将注册限定到一个Agent | 使用该Agent的agent.ctx |
5. 四种运行时模式
同一个插件系统通过不同组合服务于不同场景：
| 模式 | 工具集 | 设计目的 |
|---|---|---|
| Standard | 完整工具集：文件编辑、Shell、搜索、技能、规划、子Agent、工作流 | 日常开发的全功能编码Agent |
| Code | 所有Standard能力 + TypeScript Code Mode SDK | 模型在单次往返中编排多步操作，减少延迟和Token消耗 |
| Minimal | 仅持久化Bash + str_replace_editor | 模型基准测试的最简环境 |
| Creator | 所有Standard能力 + 运行时检查、插件实验、预设创作指导 | 构建自定义Agent预设 |
Minimal模式的存在本身就是一个重要声明：DeepSeek官方的Code Agent基准测试是在Minimal模式下运行的。这意味着，不同Harness的基准分数不可直接比较——你在生产环境中的实际表现，高度依赖于你使用的Harness和脚手架。
6. 安全沙箱与模型无关性
6.1 OS级隔离
Agent沙箱是很多工具偷工减料的地方。DeepSeek Harness提供了操作系统级别的容器隔离：
- Linux：通过自定义Node addon使用Landlock——内核的无特权访问控制机制
- macOS：使用Seatbelt（基于TrustedBSD MAC的沙箱框架）
- Windows：使用ACL受限令牌运行器
这些是浏览器用来隔离不受信任代码的同类机制。考虑到编码Agent执行的是任意模型生成的命令，这种级别的隔离不是可选项——它是基础设施的底线要求。
6.2 模型无关性：一个战略赌注
Harness虽然由DeepSeek开发，但设计上完全模型无关。它内置了Anthropic、OpenAI、Google Gemini、AWS Bedrock、Azure的Provider插件，以及自定义OpenAI兼容网关。甚至可以将Claude Code和OpenAI Codex作为子Agent提供者，并读取两者的hooks.json和AGENTS.md/CLAUDE.md文件。
这体现了DeepSeek的战略判断：价值沉淀在基础设施层，而非模型层。如果这一判断正确，MIT许可的Harness + MIT许可的开源权重模型，就是一个端到端不受任何专有厂商约束的Agent栈。
7. 局限与开放问题
开发者预览阶段。Harness目前是v0.1 Developer Preview，DeepSeek明确警告"将有兼容性破坏性变更"。适合实验和插件开发，暂不适合生产环境。
治理模式。Harness目前不接受外部Pull Request。社区贡献通过GitHub Discussions和构建社区插件进行。这是许可证层面开源，但治理层面尚未开源——对于一个定位为"模块化替代方案"的项目，这一张力将直接影响其生态的多样性和韧性。
插件生态的碎片化风险。"一切皆插件"意味着核心不提供任何"默认正确"的配置。当每个团队都在组合自己的插件栈，兼容性测试的矩阵会急剧膨胀。VSCode扩展生态的成功依赖于一个稳定的核心API——Harness连核心本身都可以替换，这既是力量也是风险。
调试复杂度。append-only日志提供了可追溯性，但当问题涉及多个插件在瀑布式事件链中的交互时，定位根因仍然困难。目前Harness没有提供可视化的调试工具来帮助开发者理解插件间的因果关系。
与现有框架的关系。Harness不是LangChain或AutoGPT的替代品——它位于更底层。它不提供预置的Agent策略或Prompt模板，而是提供一个可组合的运行时。这种定位意味着更高的学习曲线，但也意味着更大的灵活性。对于已经投入其他框架的团队，迁移成本需要仔细评估。
8. 总结
DeepSeek Harness代表了Agent基础设施的一个范式转移：从"模型中心"到"基础设施中心"，从"修改框架"到"组合插件"，从"黑箱运行"到"完全可追溯"，从"形式化缺失"到"理论基础完备"。
它能否成为Agent基础设施的"Linux时刻"，取决于三个变量：社区采用的速度、治理模式从"DeepSeek主导"向"社区共建"的演进、以及Cordis理论在真实世界的自演化Agent场景中能否兑现其形式化承诺。但有一点是确定的：Agent基础设施层已经从一个被忽视的附属品，变成了AI领域最值得关注的前沿阵地。
附录：快速上手
通过npx启动Web UI（默认运行在http://127.0.0.1:3080）：
npx @deepseek-ai/dsh web从源码安装：
gitclone https://github.com/deepseek-ai/deepseek-harness.gitcddeepseek-harnesspnpminstallpnpmrun buildpnpmdsh web查看完整配置树：
dsh--profileweb --dump-config社区插件：在GitHub上标记dsh-plugin主题的仓库可被Harness直接挂载。
参考文献
- Jianyuan Guo et al. (多机构合作，含华为诺亚方舟实验室), “From Question Answering to Task Completion: A Survey on Agent System and Harness Design.” arXiv:2606.20683, Jun 2026. 从模型-Harness耦合视角审视Agent系统，分解六大运行时职责。
- Yifan Shi, Wei Zhang (北京大学), Tianyi Cui (DeepSeek-AI), “A Programming Paradigm for Spatiotemporal Composability.” Preprint, Aug 2026. Cordis的形式化基础论文，定义可逆效应和响应式协效应。
