DeepSeek Harness
如何使用 Cordis 构建 DeepSeek Harness 插件
创建最小 TypeScript 插件，通过补丁加载，并理解依赖注入与清理机制。
deepseek harness plugin知识学习US编辑简报更新 2026-08-26
你将学会
- A minimal plugin exports apply(ctx) and can be inserted through cordis.yml.
- Absolute module paths make the patch loader resolution explicit.
- Use inject for services and ctx.effect for explicit cleanup.
开始前需要
- Basic HTTP and API knowledge
Leave with a concrete implementation checklist and a testable starting point.
先看结论
- 最小插件导出 apply(ctx)，并可通过 cordis.yml 插入。
- 绝对模块路径让 Loader 解析边界明确。
- 服务用 inject，显式资源用 ctx.effect 清理。
最小插件契约
官方教程把插件定义为导出 apply 函数的 TypeScript 模块。加载时 Cordis 传入 Context，插件通过它注册能力；最小示例只在加载时输出日志。
函数形式适用于很多场景。需要声明依赖或提供服务类时，再使用对象或 class 形式。
通过补丁加载
创建临时项目，在 cordis.yml overlay 中插入插件的绝对路径，然后运行 `pnpm dsh web --patch ./scratch-plugin/cordis.yml`。教程预期启动时能看到插件日志。
绝对路径要求是有意设计的：补丁只提供配置，不会改变 Loader 解析模块时使用的 Profile 目录。启动前用 `pwd` 验证路径。
依赖与清理
如果插件使用 tools 或 llm 等服务，应在 inject 中声明。Cordis 会等待依赖服务就绪后再调用 apply。
通过 ctx 注册的监听器、工具和计时器会在插件卸载时清理。网络连接等显式资源则应使用 ctx.effect() 返回 disposer。
如何选择
| 比较维度 | 方案 A | 方案 B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
实施步骤
- 1
创建带 apply 函数的 TypeScript 模块。
- 2
在 Web 补丁中插入绝对路径。
- 3
用 --patch 启动并确认日志。
- 4
仅在需要时加入 inject 和 effect。
可复制示例
ts
import type { Context } from '@deepseek-ai/cordis'
export const name = 'hello-plugin'
export function apply(ctx: Context) {
console.log('[hello-plugin] plugin loaded!')
}常见问题
何时使用 class 插件？
当插件要向其他插件提供服务时使用 class；多数注册场景使用函数形式即可。
资料来源
- DeepSeek Harness first plugin tutorial来源核查 2026-08-27