不装 Harness 练 DSH plugin:vendor/cordis 最小环境与 7 章练习路线
有件事挺耽误进度:想先弄懂插件怎么写,却卡在装 Harness、配密钥、挑 profile 上。其实仓库里自带了一套练习环境,一条命令就能跑,不需要任何密钥。这篇给的就是那条路线:怎么搭、每章练什么、练完怎么搬回真实环境。
谁适合先用这套 DSH plugin 练习环境
这套无密钥的 DSH plugin 练习环境适合三类人:没装 Harness、环境不干净、想理解框架。
三种情况,先练再装,收益最高。
第一种,还没装 Harness。 你想确认它值不值得投入,先看看插件模型长什么样,比装完再发现不合适便宜。第二种,装了但环境不干净。 机器上有多份 dsh、profile 状态混乱、改一次配置要排半天,这种时候在临时目录里做实验,不会污染真实数据。
第三种,想理解框架而不是某个功能。 你已经会写工具插件,但说不清 Fiber、inject、effect 之间的关系,7 章走一遍能补上这层。反过来说,只想让模型帮自己干活的用户不适合这套。 这里不产出可用界面,只产出理解。
三步把 DSH plugin 实验环境跑起来
DSH plugin 实验环境只需克隆仓库、建临时目录、写一份 cordis.yml 三步就能跑起来。
准备工作只有三条命令,官方教程给的就是这三步:
- 克隆仓库并安装依赖:
git clone https://github.com/deepseek-ai/deepseek-harness.git,然后cd deepseek-harness && pnpm install; - 建临时目录:
mkdir -p tmp/cordis-tutorial && cd tmp/cordis-tutorial; - 在目录里放一个
cordis.yml,例如只写一行指向你的插件文件,然后运行node --import tsx ../../vendor/cordis/bin.js。
这个启动器做的事很固定: 创建根 Context、挂载 Loader 插件、让 Loader 读取当前目录的 ./cordis.yml。插件有哪些、怎么配置,全部来自这份 YAML。--import tsx 的作用是不用先构建。 它让 Node 直接运行 TypeScript 文件,所以你改完代码保存,再跑一次就能看到结果。
tmp/ 已被 git 忽略。 你在里面写什么都不会进版本控制,可以放心试错。一份最小的 cordis.yml 只需要一行插件引用:
- name: './hello.ts'
hello.ts 里导出 name 与 apply 两个符号,运行启动器就能在终端看到 apply 里的输出。改完保存再跑一次即可,不需要清缓存。
三个 TypeScript 语法点提前知道,能少查很多资料: 类型注解只描述值、不影响运行;import type 在编译后消失,只用于类型约束;declare module 做声明合并,给 ctx 或事件补类型,但不产生任何运行时接线。
DSH plugin 路线 7 章各练什么
按这 7 章顺序练完,DSH plugin 的服务、事件与配置才能正确组合。
路线是递进的,每一章都会用到前一章的产物。按章对照:
| 章 | 你写什么 | 验证什么 |
|---|---|---|
| 1 | 一个导出 apply 的插件 | Loader 能挂载它,函数被执行 |
| 2 | 带 ctx.effect 的插件 | 卸载时资源被清理 |
| 3 | 一个 Service 与两个使用方 | inject 等到服务就绪、ctx 上能取到 |
| 4 | 一个事件与若干监听器 | 广播、顺序、waterfall 短路 |
| 5 | 带 Config 的插件 | 配置校验与默认值 |
| 6 | 多层 cordis.yml | 插件树组合与热重载 |
| 7 | 接一个真实工具注册 | 插件进入 Harness 的注册表 |
不要跳章。 第 3 章的服务依赖、第 4 章的事件分发、第 5 章的配置校验,都会在第 6 章的组合里同时出现;前面没跑通,后面出错时分不清是哪一层。
每章都留一个可观察结果。 第 1 章是控制台输出,第 2 章是卸载后的清理日志,第 3 章是服务缺失时的等待状态,第 4 章是监听器执行顺序,第 5 章是非法配置的报错。没有观察到结果,就等于没做。
和真实 DeepSeek Harness 的四处差别
DSH plugin 练习环境与真实 DeepSeek Harness 有四处关键差别,不能互相替代。
这套环境很好用,但不能把它当成 Harness 本身。四处关键差异:
第一,加载入口不同。 这里由 cordis.yml 直接指向源码文件;Harness 由 CLI 启动 profile,profile 里记录的是组合包列表。第二,没有界面。 这里看不到 Web UI,工具是否注册成功只能看日志或自检代码;Harness 里可以直接在界面里看工具列表与调用卡片。
第三,没有模型。 无密钥意味着无法验证「模型会不会在合适的时候选中你的工具」,只能验证工具被正确注册。
第四,数据不落 DSH_HOME。 这里的会话、配置都不进 ~/.dsh,所以练废了也不影响真实环境;反过来,也别指望在这里看到真实历史。
把这四点记住,就不会拿练习环境的结论去解释真实环境的故障。 比如「工具注册了但模型不调用」,在这套环境里永远复现不了。
练完怎么把 DSH plugin 搬进 Harness
搬进 Harness 时保留 DSH plugin 的 apply、name、inject 与服务名,目录结构可以丢掉。
搬的时候只搬逻辑,不搬目录结构。顺序如下:
- 把每章的
apply与相关函数抽到一个入口文件,保留name与inject; - 建一个最小 bundle:
package.json里声明dsh.bundle,cordis.patch.yml里按包名引用入口; - 用
--patch覆盖层先加载一次,确认与练习环境行为一致; - 再执行
dsh plugin --profile <名称> add装进 profile,验证安装后仍能加载; - 最后才考虑发布或提交市场。
第 3 步不能跳。 从「Loader 读本地文件」切到「profile 解析包名」是两套解析路径,先验证再安装,出问题时能立刻判断是打包问题还是逻辑问题。
注意服务名与事件名不要顺手改。 练习时起的名一旦被真实环境里的其他插件依赖,就成了公开契约;搬迁时保持原样,能省掉一轮 PENDING 排查。
什么时候该离开这套 DSH plugin 环境
一旦要验证模型调用、多插件装配或真实用户数据,就该离开这套 DSH plugin 环境。
练习环境的任务是建立心智模型,不是长期开发。出现下面任一信号,就该切到真实环境:
- 你要验证模型是否调用工具,或验证工具卡片的渲染;
- 你要测多个插件在同一个 profile 下的装配顺序;
- 你要测与宿主版本相关的兼容性,例如
engines.dsh范围; - 你要复现用户报告的问题,那必须在真实数据与真实 profile 下做。
练习环境回答「插件是什么」,真实环境回答「这个插件能不能用」。 两个问题都回答过,才算真正会写。
想看 Context 与 inject 的概念版,读 Cordis 入门;想理解热重载与组合,读 DSH plugin 热重载;想直接进入工程化起步,读 DSH plugin 从零怎么写。
常见问题
可以,DSH plugin 的练习不需要模型与密钥。仓库自带的 Cordis 教程用单文件启动器加载本地 cordis.yml,所有示例都不需要 API 密钥。你练的是插件装配、生命周期、服务与事件,不涉及模型调用。
写法基本相同,DSH plugin 在两种环境里都是导出 apply 与 name 的模块,差别只在承载环境。Cordis 教程用简化启动器读本地 cordis.yml,Harness 则由 CLI 启动 profile 并在 Web UI 中加载插件。
搬法是保留每章的 apply 逻辑,把 DSH plugin 换成 bundle 结构。package.json 声明 dsh.bundle、cordis.patch.yml 按包名引用入口;先用 --patch 覆盖层加载验证,再考虑打包安装。
能做装配验证,但不能验证 DSH plugin 的工具是否真的被模型选中。判断标准是插件成功加载、工具出现在注册表里;要确认模型调用,仍需要配置一个提供方和密钥。
相关术语
- Cordis
- Cordis 是 DeepSeek Harness 底层的插件框架,提供上下文、插件生命周期、服务与事件,Harness 的能力都挂载在它上面。— DeepSeek Harness 开发文档
- cordis.yml
- cordis.yml 是描述插件树的配置文件,启动器读取它决定加载哪些插件、以什么顺序与配置加载。— DeepSeek Harness 开发文档
- Loader
- Loader 是负责读取 cordis.yml、解析插件行并挂载插件的组件,它本身也以插件形式挂载在根上下文上。— DeepSeek Harness 开发文档
- profile
- profile 是 Harness 中具名的组装环境,位于 $DSH_HOME/profiles/<name>,与 Cordis 教程的临时目录不是同一层概念。— DeepSeek Harness 开发文档
来源
- DeepSeek Harness 开发文档:Cordis 教程· deepseek-harness
- DeepSeek Harness 开发文档:第一个插件· deepseek-harness
- deepseek-harness 仓库· deepseek-ai