DeepSeek Harness 源码解析 · 第 44 讲
DeepSeek Harness 源码解析系列 第 44 讲：总结与最佳实践 基于 DeepSeek Harness 源码 · 2026-09-24 💡 本讲一句话： 这是收官篇——不引入新模块，而是把前 43 讲的架构收敛成三条可复用的设计模式（效果注册、中间件链、运行时不变量），再给出一张"一次请求的完整数据流"总图。读完你手里就有一套自建 Agent Harness 的方法论。 一、一切皆插件：这个仓库的第一性原理 43 讲里我们拆过 Cordis 框架、Agent Loop、工具管道、沙箱、MCP、持久化……模块很多，但它们的组织方式惊人地一致： 没有任何一个能力是"写死在核心里的" 。仓库根目录的 AGENTS.md 把这条原则写在最前面—— 📄 AGENTS.md（仓库根，第 3-5 行） DeepSeek Harness is a plugin-based agent harness on vendored Cordis: // 整个产品构建在内嵌（vendored）的 Cordis 框架之上，而不是自己造运行时 everything is a plugin. // 第一性原理：一切皆插件——session、工具、沙箱、MCP 没有一个是核心硬编码 Read docs/architecture.md before changing packages/; // 改任何包之前先读架构文档——包之间的组合关系比单个包的代码更重要 follow docs/AGENTS.md for documentation. // 文档规范单独成文：README/JSDoc 是变更的一部分，不是事后补的 这句话的工程含义是： 核心（core）只负责"编排"，不负责"能力" 。Agent Loop 不知道工具怎么执行、沙箱怎么隔离——它只知道"有一个叫 tools/execute 的事件可以拦截"。于是第 10 讲的工具注册、第 13 讲的超时守卫、第 20 讲的 MCP，全部以同一种姿势插进同一个管道。 🔑 为什么这样设计： 把"能力"从核心剥离后，新增一个工具 = 新增一个包 + 一条 ctx.on() 拦截，零侵入。这正是第 38 讲扩展系统、第 39 讲 Hook 桥接能成立的前提——它们只是"插件的插件"。 二、模式一：注册即效果（Registration is an Effect） 第 5 讲依赖注入、第 8 讲 Agent 注册表反复出现同一个 API： ctx.effect() 。它把"注册一个东西"变成"产生一个可撤销的效果"——返回值就是 disposer（清理函数）。看 AgentRegistry.register 的真实实现： 📄 packages/core/agent/src/index.ts（第 450-457 行） register(agent: Agent): () => void { // 注册一个 agent；返回类型是"无参清理函数"——签名就宣告了：注册必然可撤销 const dispose = this.ctx.effect(function* (this: AgentRegistry) { // ctx.effect() 把一段生成器登记为"效果"：Cordis 会在 owner 卸载时按 yield 位置精确回滚 yield this.enter(agent, this.ctx.agent) // enter() 完成真正的插入并返回 detach 闭包；单独 yield = 让 Cordis 嵌套管理它的反注册时机 this.announce(agent) // announce() 广播 agent/created——放在 yield 之后：先落位、再对外可见 }.bind(this), 'agents.register()') // 第二个参数是效果的名字，loader 诊断和 HMR 安全测试都靠它定位"谁注册的" return dispose // 直接返回 disposer 本身（不包一层）——保持闭包身份稳定，调用方可以幂等地多次调用 } // 注册完成：disposer 已交给调用方，生命周期闭环 这段代码浓缩了三个设计决策： 🔹 yield 的位置就是回滚的锚点 。源码注释（第 4…