DeepSeek Harness：一切皆插件的智能体运行框架

技术解读 · 依据 deepseek-ai/deepseek-harness 仓库文档（docs/architecture.md、docs/capability-seams.md、docs/user/guide/）整理 · 2026-08

一句话定位。 DeepSeek Harness（dsh）是 DeepSeek AI 开源的智能体运行框架，核心主张是一切皆插件（everything-is-a-plugin）：模型适配器、工具注册表、会话日志，乃至 agent 主循环本身，都是与普通扩展地位平等的插件，可替换、可卸载、配置即组合。本文的回答只有两个问题：为什么要把框架本身变成插件树，以及这套设计如何让一个 Agent 框架"可验证、可替换、可重放"。

1　为什么需要 Agent Harness

大模型的能力被"能不能动手"分成两段。在聊天界面里，模型只能输出文本；而在真实任务里，一个 Agent 需要读取并修改文件、执行命令、观察输出、调用搜索与浏览器工具、委派子代理、多步迭代直到任务完成。所谓 harness（运行框架），解决的就是在这两段之间搭桥的问题——把大模型的推理能力接到真实世界的执行能力上。

但"怎么搭桥"，行业里最常见的做法是把能力写死在框架里。加一个工具要改框架源码，换一个模型要改适配层，想定制提示词、工具策略或审批流程往往无从下手。结果是 Agent 框架变成黑盒：定制即分叉，升级即痛苦，出问题时连"AI 到底做了什么"都不可信。dsh 对这一痛点的回应是反直觉的：让框架本身也变成可装配的插件——把"框架"从一段待维护的代码，变成一棵可以在配置里逐层重构的树。没有特权核心，就没有需要打补丁的地方。

2　它是什么：一个没有特权核心的框架

dsh 不是聊天机器人，而是一个"装配层"：它把大模型与文件系统、终端、工具、子代理等能力组织成一个可执行智能体。它的架构主张用一个词概括——一切皆插件。在 dsh 里，ctx.llm（模型适配）、ctx.tools（工具注册表）、ctx.sessions（会话日志）、ctx.agentLoop（主循环）全部以插件形式挂在同一个上下文上，与任何普通扩展地位平等。官方文档的说法是 "There is no privileged core to patch"——没有需要打补丁的特权核心。这带来一个直接后果：产品定制从"改源码"变成"配插件"，而框架升级与本地定制不再互相打架。

dsh 由 Cordis 驱动。Cordis 是一种组合框架：插件向共享上下文贡献服务、类型化事件与可逆副作用，设计见论文《A Programming Paradigm for Spatiotemporal Composability》。任何一个运行中的 dsh，就是一棵在启动时按层装配出来的插件树。

图 1　Agent 的组成：大模型作为推理内核，外围是可插拔的能力接缝。一个 Agent 不是一个应用，而是一组插件的组合结果。

3　装配结构：Profile、Bundle 与插件树

运行一个 dsh，用的是 dsh 命令行加一个具名 profile。profile 是一个命名组合：列出它堆叠的 bundle 集合，持有用户自己的 cordis.patch.yml，并记录 profile 级安装的外部插件。bundle 是"配置行 + 代码"的分发格式，下层 bundle 构成上层的基础。装配顺序是固定的：bundle 顺序 → profile patch → 用户 patch → --patch 覆盖。任何一行配置都可以被上层 patch 整体替换或插入新行。

图 2　装配结构：五个内置 profile 模板（web / headless / sdk / sdk-minimal / acp）共享 dsh-base 基础层，再叠应用层与用户 patch，最终装成一棵插件树。

这套分层 patch 的机制值得停下来想一层：它意味着产品的差异不是"不同的代码"，而是"不同的配置叠放顺序"。想改产品，加一行配置或挂一个插件即可；想回滚，卸载插件即可。对框架作者而言，这还解决了最难的维护问题——没有分支。社区插件挂在用户层之上，不触碰基础层，就不会随基础层漂移而腐烂。

4　能力接缝：定义、实现、消费

把能力组织成可替换的接缝（Capability Seam），是 dsh 最重要的抽象。一个完整的接缝包含三个角色：Service Definition（声明接口，定义 ctx.* 键与类型化事件）、Service Provider（实现接口的一个或多个后端）、Consumer（使用该能力的消费方，通常是一个模型工具）。一个能力永远不是单一角色，而是三者齐全；只有角色各自独立演化时才拆分。

图 3　核心主干与外圈可换接缝。接缝的语义是：换 Provider 即换产品。

接缝的意义在于换 Provider 即换整个产品，而不只是换一个函数。文件系统与子进程共享同一个执行世界——把它们一起指向远程沙箱（E2B）时，Bash、PTY、LSP 会整体迁移到远程 Linux 环境，不需要为每个能力分叉一套逻辑。子代理接缝同样如此：从进程内子代理，到把 turn 委托给 Codex、Claude Code，再到 ACP 的自动化 agent，变化都只发生在 Provider 层，模型工具与主循环完全无感。这是"可替换"从口号变成工程现实的关键：变化被限制在接口后面，接口本身不变。

5　会话日志即真相

如果说接缝解决了"框架怎么组织"，那么会话日志解决了"Agent 怎么被信任"。dsh 有一条极强的不变量：模型可见 ⟺ 已被日志记录——凡到达模型请求的内容，都必须能从会话日志重建；因此新增任何模型可见输入，必然要求新增一条会话事件。这条不变量把"发生了什么"从主观描述变成可验证的工程事实。

会话日志是只追加（append-only）的事件流，几乎一切功能都从它派生，而不是各存一份状态。

图 4　会话日志是唯一真相源：fork、续跑、标题、遥测、持久化、UI 全部从同一事件流派生，因此这些功能之间不会互相不一致。

这带来的工程收益是结构性的。首先，可复现：原始 assistant/chunk 事件被保留，日志可以逐字重放模型输出与 UI；任何一次出错的会话都能还原到当时的完整上下文。其次，单一数据源：fork、续跑、标题、遥测各自从日志派生，彼此不可能产生状态漂移。最后，可审计：安全策略、审批、沙箱事件都在同一流里，事后可以完整追责。对把 Agent 放进生产环境的人来说，"AI 干了什么"第一次有了一个可以回答的确切答案。

6　执行流：step 与 turn

dsh 的执行模型是两个术语：一次 step 是一次模型请求加上它调用的工具；一个 turn 是零个或多个 step，从首个输入被认领时开启，到不再欠任何工作为止。主循环从唯一 inbox 认领输入，装配提示词分节与工具 schema，然后流式执行，每步结束判断是否需要下一步。

图 5　单轮 turn 的执行流。step 内工具可连续调用；turn 跨多个 step 直到没有欠账。

这段流程里最关键的不是"循环"，而是拦截点。agent/pre-step 决定模型看到什么（监听者可以重写或拒绝输入）；agent/request、llm/stream 与三个 tools/* 事件是 waterfall——监听者必须调用 next() 委托，否则短路整个链。这意味着审计、改提示词、加工具策略、做权限检查，都发生在文档化的扩展点上，而不是散落在主循环的 if 里。主循环保持短小，复杂度被"事件"推开。

7　安全模型：沙箱、审批与权限预设

让 Agent 真正动手，必然要面对"让模型执行任意命令"的风险。dsh 的安全模型分三层。底层是沙箱接缝（ctx.sandbox）：消费方把即将 spawn 的 argv 原样交给后端，后端用按调用（per-call）的策略包裹它并回报执行情况——从本机裸执行到远程 E2B 沙箱，只换一个 Provider。中层是审批接缝（ctx.approval）：一次性权限决策，缺省 fail-closed（无人应答即拒绝）。上层是权限预设表：workspace-write 与 danger-full-access 一键切换"沙箱模式 + 审批策略"的组合，普通用户不必理解底层旋钮。

这一分层把安全从"功能"变成了"可替换的接缝"——与第 4 节的逻辑完全一致。更值得注意的是审批的 fail-closed 语义：安全上缺省是"不可用即拒绝"，而不是"尽量放行"。对 Agent 这类高风险执行场景，这个默认方向是正确且有示范意义的。

8　运行形态与生态

dsh 覆盖四种运行形态：浏览器 Web UI（web，本地交互式会话）、一次性任务（headless，适合 CI / 脚本）、SDK（sdk，TypeScript 与 Python 双 SDK 投影同一个主循环与会话事件，Python 运行时把 dsh CLI 打进 wheel、客户端拉起 --profile sdk）、ACP（acp，自动化专用协议，无人工界面）。此外，dsh 提供 Claude Code / Codex 的 hook 桥，并允许把 turn 委托给它们作为子代理后端——不同产品的 Agent 可以在同一会话里互相调用，因为它们共享同一条 ctx.subagents 接缝。

生态方面：MIT 许可；插件仓库打上 dsh-plugin 话题便于被发现；社区包括 GitHub Discussions、Discord 与中文企微群；文档站提供中英双语。项目处于开发者预览阶段，README 明确提示未来将有破坏兼容性的变更——对研究者和早期采用者这是福利（迭代快），对需要长期稳定的团队这是需要评估的风险。

9　结论

dsh 的核心主张，是把"智能体框架"从黑盒变成一棵可组合的插件树。三个支柱相互支撑：没有特权核心，能力即接缝，任何组件可替换、可卸载；会话日志即真相，模型可见即被记录，一切功能从同一事件流派生；执行在文档化扩展点上展开，主循环短小，复杂度被事件推开。它的意义不在于多一个 Agent 应用，而在于提供了一个可验证、可替换、可重放的框架底座——对想研究 Agent 架构、或自建 Agent 产品的团队，这是一个值得跟踪的开源实现。

参考文献

• DeepSeek Harness 官方仓库与 README：deepseek-ai/deepseek-harness（MIT）。
• 《DeepSeek Harness Architecture》：docs/architecture.md——装配、事件、执行流与扩展点。
• 《Capability Seams And Core Services》：docs/capability-seams.md——接缝清单与角色分类。
• 《Use the Web UI》用户指南：docs/user/guide/。
• Cordis：A Programming Paradigm for Spatiotemporal Composability，arXiv:2608.25512。