DeepSeek Harness源码解读：一切皆插件的Agent如何跑起来

从跑通到读懂：DeepSeek Harness 的两个层次

国产版 Claude Code 的期待值正在升温，而 DeepSeek^广告 在官网子工程里放出的 Harness 预览版，给出了一个相当激进的答案——一切皆插件。按照 B 站这期源码教程的拆解，模型、工具、技能、沙箱、存储、循环调度、UI 全部由插件组成，这意味着 Agent 的每个功能单元都是可替换、可扩展的。作者把课程分成两条主线：先快速跑通，再精读核心流程与一次对话的源码。

这种「先跑起来」的设计对新手很友好。安装版只需 Node.js 环境，终端执行 npx @deepseek-ai/dsh --web 就能拉起 Web 界面；源码版则是 clone 仓库后走 pnpm 安装流程，用 --port 8080 避开默认的 3080 端口，避免与已有的应用版实例冲突。启动成功后终端会打印 DSH Web 和本地地址，浏览器打开即进入一个酷似 DeepSeek 主站的对话框。

有一点值得注意：作者在 apps/cli/src/bin.ts 里手动插入了一行 console.log，打印 ds running from source 来确认当前实例确实来自源码而非安装包。这个调试手法看似简单，却是源码阅读时区分运行路径的实用技巧。

插件架构：为什么「一切皆插件」是核心设计

「一切皆插件」这五个字是理解 Harness 的钥匙。在作者展示的代码结构里，Agent 的每一项能力——模型接入、工具调用、技能注册、沙箱执行、存储、循环调度、UI 渲染——都作为独立插件存在。

这种设计带来的直接好处是模型供应商的完全可插拔。设置页里默认提供 DeepSeek 的 API Key 入口，但用户也可以切换到 Google、Kimi、Amazon 等提供方，甚至走「自定义」通道接入任意兼容模型。换句话说，Harness 不绑定自家模型，它更像一个 Agent 运行时框架，模型只是其中一个插件位。

从工程角度看，插件化把耦合点收敛到了插件契约上。想加一个新工具，不需要改动主循环，只需按内核约定注册插件。作者在课程里专门留了一段讲「如何基于内核写自己的工具插件」，这也是这套架构对开发者最有吸引力的地方。

插件契约（Plugin Contract）是插件化架构的隐含前提：宿主程序在加载插件前，必须约定一组稳定的接口——插件导出的生命周期钩子、可访问的宿主能力（如注册工具、订阅事件、读写配置）、以及数据结构与错误语义。契约一旦变更，所有第三方插件都可能失效，因此成熟框架会用语义化版本号和适配层来缓冲。文中「契约稳定性决定生态上限」的判断正源于此：插件数量越多，破坏性变更的迁移成本越高。评估一个插件化 Agent 框架时，可以重点看它是否公开契约文档、是否对契约做版本管理、以及内核是否允许插件在运行时热加载。

主循环与事件总线：一次对话背后的调度逻辑

课程的核心是精读一次对话的完整源码路径，涉及主循环、事件总线、提示词组装三个关键环节。虽然直播中更多是演示而非逐行讲解，但骨架已经清晰：

• 主循环负责驱动 Agent 的多轮推理与工具调用，决定何时继续、何时终止；
• 事件总线承担插件之间的消息分发，让 UI、工具、存储等模块以松耦合方式响应状态变化；
• 提示词组装把系统指令、会话上下文、工具描述拼装成最终发送给模型的请求。

这种分层让「一切皆插件」不至于沦为空话——主循环和事件总线是相对稳定的骨架，插件则挂载其上。作者在演示中把 VS Code 里的源码目录直接摊开，配合启动日志定位入口，展示了从 bin.ts 出发追踪调用链的路径。

对于想深入 Agent 开发的人来说，这条路径比单纯使用 Web Coding 工具读代码更有价值：工具能帮你解释片段，但面试、简历和实际排障时，你需要的是对核心流程的整体把握。

Agent 主循环（Agent Loop）通常是一个「推理—行动—观察」的往复过程：把当前上下文发给模型，若模型返回工具调用请求，就执行工具并把结果追加回上下文，再次请求模型，直到模型给出终止信号或达到轮数/预算上限。循环设计的关键取舍包括：终止条件如何判定（模型显式停止、无工具调用、最大轮数）、工具结果如何裁剪以避免上下文膨胀、以及错误如何回灌给模型自我修正。事件总线（Event Bus）则是解耦手段：发布者只负责发出事件，订阅者按需响应，二者互不感知。在 Agent 场景中，token 流式输出、工具开始/结束、状态变更等都以事件形式广播，UI 与日志模块各自订阅，主循环无需为每个消费者写专门回调。

与 FDE 的关系：Agent 框架的落地想象

课程后半段把 Harness 与 FDE（Forward Deployed Engineer）岗位联系起来，并提到了开源平台 Palantir 旗下的 C-Medical（直播中名称略有口误），将其视为 FDE 终极形态的一种初级体验，涉及本体（Ontology）等概念。

这部分属于作者的延伸展望，单一来源，尚未有更多材料佐证。但逻辑链条可以理解：插件化的 Agent 运行时，配合可定制的工具与数据接入，正是企业级落地场景中 FDE 需要动手搭建的东西。Harness 的预览版定位，某种程度上也是在为这类工程化需求试水。

FDE（Forward Deployed Engineer，前沿部署工程师）指常驻客户现场、把通用平台改造成客户可用方案的工程角色，需要同时具备产品理解、数据建模和快速编码能力。文中提到的本体（Ontology）源自 Palantir 的术语体系，指对业务实体、属性与关系的显式建模层，让上层应用和查询建立在统一语义之上，而非直接操作原始表。将插件化 Agent 运行时与 FDE 联系起来，逻辑在于：现场工程师可以按客户业务注册工具插件、接入数据源、定制提示词与流程，而不必 fork 整个框架。需要说明的是，这部分属于作者的延伸联想，与 Harness 本身的功能边界并无直接对应关系。

实践建议与当前局限

需要明确的是，Harness 目前仍是预览版，接口和插件规范都可能变动。上手时建议：用源码版启动并保留自定义日志，便于确认运行来源；工作目录不要放在系统盘根目录，单独建一个 Demo 目录更安全；API Key 优先走设置页配置，避免硬编码。

对于想写插件的人，先跑通一次对话、再顺着主循环和事件总线读代码，比一上来就啃插件内核效率更高。至于「一切皆插件」最终能撑起多大的生态，取决于预览版之后插件契约的稳定性——这一点目前还没有足够信息判断。