开发者指南
Cordis 入门
DeepSeek Harness 底层 Cordis 插件框架的核心概念：插件、ctx、服务、事件与可逆副作用
Cordis 是 DeepSeek Harness 底层以 vendor 方式引入的插件框架。编写 Harness 插件之前，先掌握下面这些核心概念；更完整的服务/事件参考见各能力子系统的生成文档。
五个核心概念
- 插件是实现 Service 的对象。 插件可以是一个带可选
inject与apply(ctx)字段的函数，也可以是Service子类，其生命周期由 Cordis 挂载到当前上下文中。 - 上下文是服务的容器。 一个服务占据稳定的
ctx.<key>（如ctx.tools、ctx.llm、ctx.sessions）；其他插件通过 key 查找服务，而非导入具体实现。 - 用
inject声明服务依赖。 插件声明所需服务后，会等待这些服务就绪才启动；加载顺序由服务依赖表达，而非手动编排启动序列。 - 类型化事件用于通信。 服务通过 TypeScript 声明合并注册事件名，再以
emit、waterfall（瀑布式事件）、parallel或serial方式分发，分别对应观察、包装、并行扇出或按序执行。 - 注册是可逆的副作用。 提示词片段、工具 schema、适配器、提供方与监听器通过
ctx.effect()或ctx.on()安装，reload 与 teardown 时会按预期撤销。
事件分发模式
每个事件具有以下分发模式之一，且只能通过对应方法分发。
| 模式 | 是否 await | 分发顺序 | 是否有返回值 |
|---|---|---|---|
emit | 否 | 监听器按注册顺序观察 | 否 |
waterfall | 否 | 监听器按注册顺序观察 | 是 |
parallel | 是 | 所有监听器并行观察事件 | 否 |
serial | 是 | 监听器按注册顺序观察 | 是 |
分发模式是事件公开约定的一部分。
waterfall 语义
ctx.waterfall 是环绕中间件。监听器接收 (...args, next)，调用 next() 会把下游结果带回当前层，可再包装后返回；不调用 next() 直接返回则短路。
协作式监听器通常修改一个共享请求或决策对象，然后委托。仅做标注或观察的监听器必须委托；策略监听器在拥有决策权时可以直接返回。
一个最小插件
import type { Context } from '@deepseek-ai/cordis'
export const name = 'my-plugin'
export const inject = ['tools']
export function apply(ctx: Context) {
ctx.effect(() => {
const timer = setInterval(heartbeat, 5000)
return () => clearInterval(timer) // disposer（资源释放函数）
})
}inject 让插件等待 tools 就绪；ctx.effect() 返回的函数会在插件卸载时运行。
实践规则
- 把行为封装成插件：工具流水线属于
ctx.tools，模型流式输出属于ctx.llm，agent loop（智能体循环）协调属于ctx.agents。 - 拦截与策略优先用事件；直接能力调用优先用服务方法。
- 每个注册都应有对应的 disposer：从
ctx.effect()返回一个，或用 Cordis 提供的辅助方法自动处理。若 teardown 顺序有要求，把相关工作放进同一个 effect。