DeepSeek Harness (DSH) 插件机制解析:一切皆插件的 Agent 运行时

DeepSeek Harness (DSH) 插件机制解析:一切皆插件的 Agent 运行时

基于 deepseek-ai/deepseek-harness 仓库源码分析


一句话结论

dsh(DeepSeek Harness)是一个 Agent harness,核心设计是**「一切皆插件」**------它没有把功能写死在框架里,而是构建在基于 source-vendored 的 Cordis 4.0(vendor/cordis/,重命名 @deepseek-ai/cordis)之上,所有能力都以插件形式挂载。理解 dsh 的插件机制,就理解了整个 harness 的运行逻辑。


一、总体架构

六层结构:界面层(web/cli)→ 启动层(app-boot)→ 组合层(bundle patch)→ 核心层(约 50 个功能包)→ 能力层(工具、记忆、会话等)→ 框架层(vendor 的 Cordis/loader/include)。


二、插件机制的 4 个核心概念

1. Context 是 Proxy,不是普通对象

vendor/cordis/src/reflect.ts 的 get 陷阱 :读 ctx.xxx 时沿 fiber 链向上查找,找不到就报 cannot get property "X" without inject。

含义:插件不能随便读全局状态------每个属性都必须能追溯到注入来源。这保证了依赖关系的显式化。

2. Fiber 生命周期状态机

graph LR P[PENDING] --> L[LOADING] --> A[ACTIVE] L --> F[FAILED] A --> U[UNLOADING] --> D[DISPOSED] A --> F

PENDING → LOADING → ACTIVE / FAILED → UNLOADING → DISPOSED。epoch 依赖串 (fiber.ts _refresh())驱动自动 reload/unload------依赖版本变化时,相关 fiber 自动刷新。

3. ctx.effect() 是唯一注册原语

  • 所有副作用(监听事件、注册工具、创建资源)都必须通过 ctx.effect() 注册
  • disposers 逆序执行:卸载 = 精确回滚
  • 好处:无论插件以什么顺序加载/卸载,清理都不会泄漏

4. 事件 5 种分发方式

方式 语义 典型场景
emit 广播,不等待 通知类事件
parallel 并行执行 无依赖的监听者
serial 串行执行 有顺序要求的监听者
bail 短路返回 审批/校验,可拒绝
waterfall 逐个传递返回值 策略注入点

waterfall 是插件机制的关键:返回值可以修改后传给下一个监听者。dsh 的策略注入点全部用 waterfall:

  • tools/pre-execute(工具执行前拦截)
  • agent/request(组装请求前修改)
  • llm/stream(流式输出逐段加工)
  • internal/config(配置合并)

三、Profile 与 bundle 贴纸叠层

Profile = $DSH_HOME/profiles/<name>/,内容是一份 bundle 有序列表 + cordis.patch.yml。

bundle 补丁顺序(后贴赢):

  1. bundles(按配置顺序)
  2. profile patch
  3. home patch
  4. --patch overlays(命令行)

就像贴纸叠层:后贴的覆盖先贴的。调试命令:dsh --profile web --dump-config 可离线打印最终插件树。


四、Loader 与 Include:插件的加载与配置

Loader(vendor/loader/)

  • 核心模型:EntryTree / Entry
  • name 动态 import 模块 → ctx.registry.plugin() 开 fiber
  • internal/plugin 监听绑定 fiber↔entry
  • 插件自我 dispose 时写回 disabled: true(下次启动不加载)

Include(vendor/include/)

  • cordis.yml 是 YAML 方言,!!js 表达式延迟求值(配置值可以引用运行期对象)
  • applyEntryPatches:id 整体替换 / insert 追加,不做深合并
  • 理解:patch 是「替换或追加」,不是「递归合并」------避免歧义

五、类型声明合并机制

  • 103 个文件 declare module '@deepseek-ai/cordis' 扩充 Context/Events 接口
  • 156 个文件用 import type {} from '@deepseek-ai/dsh-xxx' 空类型导入拉声明(编译后擦除)
  • augmentation 跟着声明它的包走,不在 cordis 包里;外部插件作者必须显式拉取

引用服务 3 件事:

  1. 类型层:拉声明(import type {})
  2. 运行层:装 provider(ctx.provide)
  3. 依赖层:inject

六、一次对话的回合流程

会话日志是唯一事实来源------所有事件在发生时立刻追加(不是最后统一写)。

graph TD A[turn/start] --> B[认领输入] --> C[组装提示词] --> D[agent/pre-step] D -- 被拒 --> E[回合无 step 直接结束 turn/end] D -- 通过 --> F[step/start] --> G[user/message 落盘] G --> H[从日志推导历史] --> I[agent/request] --> J[llm/stream] J --> K[assistant/chunk*] --> L[assistant/message] --> M[tool/call] M --> N[tools/pre-execute] --> O[execute] --> P[post-execute] --> Q[tool/result] Q --> R[step/end] R -- 工具要再问一次 --> F R -- 完成 --> S[turn-stopping] --> T[turn/end]

持久事件清单 :turn/start、user/message、assistant/chunk、assistant/message、tool/call、tool/result、step/end、turn/end。


七、动手理解:一个最小插件长什么样

核心 API 只有三样:

js 复制代码
// 1. defineTool:声明一个工具
const tool = defineTool({
  name: 'demo-hello',
  execute: async (args) => { /* 干活 */ }
})

// 2. ctx.tools.register:挂载到 Context
ctx.tools.register(tool)

// 3. ctx.on('session/event'):订阅会话事件
ctx.on('session/event', (event) => { /* 观察 */ })

写插件 = 注册工具 + 订阅事件 + 用 effect 管理副作用。这就是「一切皆插件」的全部要义。


八、小词典(关键术语)

术语 含义
Harness Agent 的「运行容器」,管生命周期/依赖/事件
Cordis 插件化运行时框架(dsh 的 vendored 底座)
Fiber 单个插件的运行实例,有完整生命周期
Context (ctx) 插件的运行环境,Proxy 实现,属性需注入
effect 副作用注册原语,卸载时逆序回滚
epoch 依赖版本标识,变化时驱动 fiber 自动刷新
bundle 一组插件的打包单元,可被 patch
patch 对 bundle/配置的覆写(id 替换 / insert 追加)
Profile 一份运行配置:bundle 列表 + patch
waterfall 事件分发方式,返回值逐级传递(策略注入点)
Entry/EntryTree Loader 的加载单元模型
cordis.yml 配置方言,!!js 表达式延迟求值
声明合并 declare module 扩充 Cordis 接口的机制
provider 通过 ctx.provide 提供的服务实例
inject 依赖注入声明
dump-config 离线打印最终插件树的调试命令

推荐学习资源


参考

  • 仓库:deepseek-ai/deepseek-harness
  • 源码依据:vendor/cordis/src/reflect.ts、vendor/cordis/src/fiber.ts、vendor/loader/、vendor/include/、docs/architecture.md
相关推荐
QuZhengRong22 分钟前
【AI】Agent 全栈进阶|AgentScope 沙箱源码解析
python·学习·ai·agent·沙箱
阿里云大数据AI技术28 分钟前
孩子王基于阿里云Data Agent的智能体实践:300+Agent 覆盖400+业务场景
大数据·人工智能·agent
玄魂1 小时前
小红书/抖音图文排版利器——一个杂志风skill
人工智能·agent·视觉设计
用户71880080605782 小时前
服务全绿,Issue 却没人接:DeepSeek Superagent 本机部署踩坑记
agent
初学AI的小高2 小时前
RAG 知识库更新实战:增量索引、版本控制与可验证删除
后端·agent
钱栈up2 小时前
IDEA 一天冻死两次:顺着线程 dump 揪出 JRebel,再用 DCEVM 把它替掉
jvm·agent·intellij idea
文谦南宁AI普工2 小时前
把 eval 做成发布门禁:配对检验 + 三档判定,一个不到 200 行的纯标准库实现
agent·ai编程·产品
jerrywus3 小时前
用 AMD Radeon Cloud 免费跑 ComfyUI:从开机到打开界面
前端·agent·claude
前进的李工3 小时前
Agent 学习笔记 15:Agent 怎样响应事件与中途打断?
人工智能·笔记·agent·openclaw·工具设计·gpt-6 astra·原生异步
大模型真好玩4 小时前
大模型训练全流程实战指南实战篇(十八)——微调问答对数据构建技术
人工智能·agent·deepseek