DeepSeek Harness 插件开发完整指南

随着大模型应用开发进入深水区，如何构建可扩展、可维护的 Agent 工具系统成为工程师面临的核心挑战。DeepSeek Harness 作为新一代 Agent 运行时框架，采用了一种独特的插件化架构设计——没有传统意义上的「内核 + 插件」分层，而是将所有能力（包括工具、LLM 适配器、会话持久化、Web 服务器等）统一抽象为插件。这一设计理念看似简单，却蕴含着深刻的工程哲学：加能力等于往组合里加一行，修改行为等于覆盖已有行。理解这一点，是掌握 Harness 插件开发的第一步。

概述

在 Harness 的插件体系中，每个插件必须导出四个具名符号：name（诊断标识）、inject（硬依赖声明）、Config（配置 schema）、apply（唯一入口）。这四个导出构成了插件与框架之间的契约，其中任何一环都不可或缺。值得注意的是，框架的 unwrapExports 机制会将默认导出折叠成插件本体，导致 inject 等元数据被静默丢弃——插件看似正常加载，实则依赖声明失效，行为诡异却无任何报错。这种「隐式失效」是新手极易踩入的陷阱，解决方案只有一个：始终使用具名导出。

插件的四个具名导出：不可动摇的契约

ctx.plugin() 返回的 Fiber 实例是插件的运行时载体，它持有依赖状态、已校验的配置、生命周期副作用和清理逻辑。服务（tools、agents、sessions 等）挂在 Context 上，获取方式有三种且语义截然不同：通过 inject 数组声明硬依赖，框架保证服务就绪后才执行 apply；通过 ctx.get() 获取可选依赖，可能返回 undefined；通过 ctx.inject(names, callback) 获取局部依赖，回调只在服务存在时才执行。判断标准很明确：这个服务缺失时，插件应该「等待」还是「降级」？前者用 inject，后者用 ctx.get。框架的 Guard 机制会拒绝未声明的访问，直接引用 ctx.someService 而未在 inject 中声明将触发报错——这是框架主动帮你发现问题的机制。

Fiber 运行时与依赖获取的三种策略

配置系统采用分层 patch 语义，配置树从空根开始依次叠加：profile bundles → profile 目录的 cordis.patch.yml → home 级 patch → 命令行 --patch 指定层。开发者可以通过 dsh --profile web --dump-config 随时查看最终组合结果。Patch 有三种操作：覆盖（写标识 + 字段）、插入（用 insert 关键词）、禁用（覆盖并设为 disabled）。一个关键细节是：覆盖是浅层键赋值而非深合并，写 config 会整体替换原有配置，原本的五个字段只写一个，另外四个就消失了。insert 不带标识则追加到顶层，带标识则插进目标 group 的 config。顺序同样重要：patch 按列表顺序应用，插入的行会被立即索引，后面的 patch 可以再次覆盖它。

Isolate Realm：作用域隔离的艺术

开发一个真实可用的插件需要关注几个实践要点。首先，工具的 description 是模型判断「何时调用」的唯一依据，参数 schema 只告诉模型怎么调、告诉它何时调才是 description 的职责。其次，长时间运行的任务必须观察 exec.signal 实现取消，同时注意幂等处理（connect/error/timeout/abort 都可能先到）、显式关闭 socket、手动摘除监听器。第三，错误文案是接口的一部分——它会原样进入模型对话，原则是稳定（同样错误同样措辞）、可操作（说清哪个值错了）、前置（在开任何 socket 之前校验完）。最后，失败不是错误：连接被拒、超时应作为 open 为 false 的正常结果返回，而非抛出异常，因为这直接影响模型行为——抛错让它倾向重试，正常返回则让它继续推进。

如有侵权，请联系删除。