本文目录+
先理解 DSH Plugin 的最小模型
DeepSeek Harness 由 Cordis 驱动，产品行为不是一个固定 Core 外面再挂少量插件，而是由可组合 Plugin Tree 构成。插件获得共享 Context，并通过它注册 Service、Event、Tool、UI、Policy、Storage 或其他能力。
最小 Function Plugin 很简单：导出 name 与 apply(ctx)。如果依赖 tools、llm 等其他 Service，再用 inject 声明，Cordis 会在依赖准备好后再激活插件。
import type { Context } from '@deepseek-ai/cordis'
export const name = 'my-dsh-plugin'
export const inject = ['tools']
export function apply(ctx: Context) {
// 在这里通过 ctx 注册能力。
}先选清楚插件真正要负责哪种能力
DSH 的扩展点不只有 Tool。应该先选择与业务行为匹配的 Capability Seam，而不是把所有功能都硬塞到一个模型 Tool 里。
模型 Tool
在 ctx.tools 上注册结构化模型能力。
模型 Provider
在 ctx.llm 上提供新的模型适配器。
后台任务
通过 ctx.jobs 提供长任务、轮询或计划任务。
Policy / 拦截
通过 tools/*、agent/*、fs/* 等事件控制和观察执行。
UI 集成
消费 Session Event 或注册 Web 端展示能力。
Service Provider
提供其他插件可以通过 Context 消费的可替换 Service。
用一个小 Tool 跑通第一个插件
Tool 很适合作为第一条完整链路：定义输入 Schema、返回 Canonical Value，再把结果渲染成模型可见内容。DSH 会在 execute 前校验参数，并在插件卸载时撤销 Tool 注册。
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'
export const name = 'project-info'
export const inject = ['tools']
export function apply(ctx: Context) {
ctx.tools.register(defineTool({
name: 'project_info',
description: 'Return a small project summary.',
parameters: { name: { type: 'string', required: true } },
output: {
schema: { type: 'string' },
render: (_args, value) => [{ type: 'text', text: value }],
},
async execute(args) {
return 'Project: ' + args.name
},
}))
}真正用于生产的 Tool 还要继续设计取消、结构化输出、Policy Hook、Replay-safe UI 展示以及真实执行路径测试。
把插件打包成 DSH Bundle
要让 Profile 可以稳定安装，一个 Package 可以在 package.json 中声明 dsh.bundle，并让它指向 Cordis Patch。Patch 负责把配置行插入 Profile，而上层 Profile/User Patch 仍然可以覆盖这些配置。
{
"name": "@example/my-dsh-plugin",
"type": "module",
"dsh": {
"bundle": {
"patch": "./cordis.patch.yml"
}
}
}- insert:
- id: my-dsh-plugin
name: '@example/my-dsh-plugin'- 把 Patch 文件放进 Package 的发布 files。
- 导出 Cordis Loader 能真正 resolve 的运行入口。
- 对消费的 DSH Service 声明合适的 Peer Dependencies。
- Bundle 只挂载这个 Package 真正负责的行为，避免把无关能力一起塞进去。
验证完整加载链，而不是只测一个函数
Unit Test 只能证明你的函数工作；Plugin 真正需要证明的是 Harness 能 resolve、mount、满足 inject 依赖、执行能力并正确卸载。发布前应在真实 DSH Composition 中跑一遍。
pnpm dsh web --patch ./scratch-plugin/cordis.ymldsh --profile web --dump-config- 确认插件已经出现在最终 Plugin Tree。
- 从用户真正使用的 Web/TUI/Headless 表面执行一次能力。
- 测试失败路径和 unload，而不是只测试正常返回。
- Node 与 Peer Dependency 范围要跟当前 developer preview 保持一致。
发布并让 DSH 生态发现你的插件
社区插件可以独立于官方 Monorepo 发布，并依赖需要的 @deepseek-ai Package。安装路径稳定后，应把仓库、Package、Profile、安装命令和验证方式写清楚，并添加 dsh-plugin GitHub Topic。
- README：能力、目标 Profile、安装、配置、限制和验证步骤。
- package.json：Package Identity、Exports、版本、License、Engines、Dependencies 与 dsh.bundle。
- Repository：dsh-plugin Topic、Release/Tag、Changelog、Issue 或 Support 入口。
- Verification：提供一条可以复现“插件已经加载且能力可用”的验证方式。
一手资料
本文以 DeepSeek AI 官方 Harness 仓库与当前开发文档为主要依据；由于 Harness 仍处于 Developer Preview，具体命令与契约以后续官方版本为准。