Harness 与 Agent 工程 · 运行控制与长任务 · 2026-08-16

DeepSeek Harness 插件开发全指南

面向有Node/TypeScript基础的工程师,DeepSeek Harness插件开发全指南,助你独立开发、排错,基于官方源码实践。

核心内容:

  1. Harness插件架构:无内核插件分层,195个包均为cordis插件
  2. 插件核心结构:四个具名导出(name/inject/Config/apply)的规范与重要性
  3. 插件运行时:Fiber实例与三种依赖获取方式

DeepSeek Harness 插件开发全指南

面向已有 Node / TypeScript 基础的工程师。目标是读完能独立写出一个被真实挂载、工具出现在会话里的插件,并且能自己排错。

全文的机制结论均来自 @deepseek-ai/dsh 0.1.0-rc.6 安装目录下的源码与实际执行结果。

195 个包全是插件 4 个具名导出 0.1.0-rc.6 开发者预览

// 环境前置

npm install -g @deepseek-ai/dsh # 需要 Node 22+dsh --version # 0.1.0-rc.6

配合阅读:安装目录里有两份更详细的官方技能文档 —— cordis-plugin-development(动态插件,420 行)与 editing-cordis-compositions(组合与 realm,154 行)。

01

一切皆插件

Harness 没有「内核 + 插件」的分层。安装目录下的 195 个 @deepseek-ai 包全部是 cordis 插件 —— 包括工具、LLM 适配器、会话持久化、Web 服务器、前端 UI,甚至沙箱策略。

加能力 = 往组合里加一行

没有第二套配置语言,也没有「插件 API」和「内核 API」的区别。你写的插件和官方的 dsh-tool-bash 地位完全相同。

改行为 = 覆盖已有的行

想换掉某个官方实现,就在 patch 层用同一个标识覆盖它的 config,或者关掉再插自己的。

底层框架是 cordis —— 一个显式依赖注入 + 作用域服务 + 生命周期清理的插件框架。

02

插件的形状:四个具名导出

/** 诊断信息里显示的名字 */export const name = 'my-plugin'/** 硬依赖的服务;不满足时插件停在 PENDING 不执行 */export const inject = ['tools']/** schemastery 配置 schema,框架据此校验组合里的 config */export const Config = z.object({ greeting: z.string() })/** 唯一入口。在这里注册一切副作用 */export functionapply(ctx, config) { }

绝对不要用 export default

Loader 的 unwrapExports 会把默认导出折叠成插件本体,inject 等具名元数据会被静默丢弃 —— 插件照常加载,但依赖声明没了,行为诡异且没有报错。官方为此写过事故复盘。规则:只用具名导出。

这四个导出是整套体系里唯一不变的部分。后面无论工具变得多复杂,骨架一行都不会动。

03

Fiber 与三种依赖获取方式

ctx.plugin() 启动一个插件,返回一个 Fiber —— 插件的运行时实例,持有依赖状态、已校验的 config、生命周期副作用和清理逻辑。它的状态机决定了你的代码到底跑没跑。

服务是挂在 Context 上的具名对象(ctx.tools、ctx.agents、ctx.sessions…)。获取方式有三种,语义完全不同:

inject = ['x'] 硬依赖。框架保证 apply 执行时服务已就绪;不存在则停在 PENDING 等待,事后出现会重新激活插件
ctx.get('x') 可选依赖。不声明、不等待,可能返回 undefined,必须自己处理缺失
ctx.inject(names, cb) 局部硬依赖。回调拿到子 Context,只有服务出现时才执行 —— 核心能力硬依赖、增强能力软依赖的标准写法

Guard 会拒绝未声明的访问:直接写 ctx.someService 而没在 inject 里声明,会报 service "someService" is not declared。但也不要为了省一个 undefined 判断就滥用 inject。

判断标准:这个服务缺失时,插件是应该「等」(inject),还是应该「降级运行」(ctx.get)?

04

Isolate realm:最容易出事的机制

服务实现存储在 Context 的一张符号表里:服务名 → symbol。ctx.isolate(name, label) 创建一张遮蔽表,给这个名字换一个新的私有 symbol;服务归属判断就是比较这个 symbol。传同一个 label 可以让两个 isolate 作用域合流,不传则每次都是全新的私有 symbol。

Preset 是每个会话挂载一份的。如果 preset 里某一行发布了服务却没有 isolate realm,这个服务就注册进了进程全局 realm —— 第二个会话挂载同一个 preset 时同名服务撞车,挂载直接被拒。

// 官方 standard preset 里的真实例子


- id: delegation name: cordis:group group: trueisolate: workflows: true# 每个挂载方一份私有 realmconfig: - id: workflow-worker-thread name: '@deepseek-ai/dsh-workflow-worker-thread' - id: tool-workflow # 消费者也在 group 里name: '@deepseek-ai/dsh-tool-workflow'

反向的坑同样致命:把一个纯消费者单独包进 isolate group,它会去解析一个空的私有 realm,找不到 host 提供的实例 —— 结果是「挂载成功,但什么都不贡献」,且没有任何报错。官方 standard 里的 tool-bash、tool-jobs、tool-goal 就是刻意平铺在顶层的。

培训要点:判断一行该不该进 realm,看它发布什么,不看它叫什么。名字看不出来,就用探针查(见第 09 节)。

05

事件与清理纪律

事件有两种派发模式,监听器签名不同。普通事件各监听器独立执行;waterfall 事件的最后一个参数是 next:

ctx.on('agent/pre-step', async ({ agent, turn, step }, next) => { const decision = await next() // 必须调用并返回,除非有意截断if (decision.kind === 'reject') return decision return { kind: 'enter', messages: [...decision.messages, extra] } }, { prepend: true }) // 插到监听链最前面

不调 next() 就等于截断了整条下游链。写之前一定要先确认目标事件是哪种模式 —— 猜错了要么监听器不生效,要么把别人的逻辑全掐了。

核心纪律:插件停止 / 更新 / 移除后,它贡献的一切必须消失。框架提供了这些清理感知 API:

ctx.on(...) 事件监听,随 fiber 自动移除
ctx.effect(fn, label) 托管一个返回 disposer 的外部订阅
ctx.timeout / interval 定时器(需要 inject 里声明 timer)
各注册 API 的返回值 register 等返回 disposer,需要时保存

ctx.effect 的语义: ▸ execute 立即执行 ▸ 产生的 disposer 在「返回的 disposer 被调用」或「fiber 卸载」中较早的那个时机逆序执行 ▸ 重复调用 disposer 是 no-op ▸ 在已销毁的 fiber 上调用会抛 INACTIVE_EFFECT

禁止模块级副作用。模块只会被 import 一次,但插件可能被挂载多次、卸载多次。写在模块作用域的 setInterval 永远不会被清理 —— 所有副作用都必须在 apply 里通过 ctx 的 API 建立。

06

配置树与 patch 语义

配置树从空根开始,按顺序叠加 patch 层:profile bundles → profile 目录的 cordis.patch.yml → home 级 patch → 命令行 --patch 指定的覆盖层。随时可以离线检查结果,不启动应用:

dsh --profile web --dump-default-config # 不含用户层dsh --profile web --dump-config # 完整组合结果

培训要点:任何「我改了配置但没生效」的问题,第一步都是 --dump-config 看最终树,而不是猜。

patch 只有三种操作:覆盖(写标识 + 要改的字段)、插入(用 insert)、禁用(其实就是一次普通覆盖,写 disabled)。

覆盖是浅层键赋值,不是深合并

源码就是一层 for 循环逐键赋值。所以 patch 里写 config 会整体替换原有 config。原本有五个字段,你只写一个,另外四个就没了 —— 必须把要保留的字段一并写全。

加新行必须用 insert。想加新行却用了覆盖语法,会得到 patch: entry "X" not found。insert 不带标识则追加到顶层,带标识则插进该 group 的 config(目标必须是 group)。

另外三个行为细节值得记: ▸ 顺序:patch 按列表顺序应用,插入的行会被立即索引,后面的 patch 可以再覆盖它 ▸ name 字段:非 insert 的 patch 里写 name 会当作守卫,与目标不符则跳过并警告 —— 建议写上,防止标识漂移后误改 ▸ 匹配不到只警告、不启动失败,所以一定要看警告输出

07

两个平面与模块解析

整个体系最需要先想清楚的决策

判断规则只有一条:一个服务,只要有 agent 平面之外的消费者,就不能移进 preset。

官方给的例子是 subagents:这个注册表要回答来自 host api-proxy 的跨会话查询。放进 preset 会同时坏两件事 —— host 那一行永远等不到服务,第二个会话挂载时又撞名。正确做法是注册表和后端留在 host,preset 只贡献委派工具。

不能移进 preset 原因
agent-loop 只注册一个 agent 工厂,第二次会抛错
各注册表 它们负责每会话分层,自身不能是每会话的
会话持久化 移进去会导致会话列表碎片化
sandbox / approval 刻意的边界:让 preset 放宽自己的限制等于取消限制

四种解析基准,容易踩空

同一个字符串,写在不同位置,解析基准完全不同。最反直觉的一条是:preset 行的裸包名…

— 以上为试看内容(约 40%),开通会员后阅读全文 —

原文出处:https://www.53ai.com/news/LargeLanguageModel/2026081613046.html