前言¶
DeepSeek Harness（下文简称 DSH）的理念是「一切皆插件」：Tool、Config、Service、Event、middleware 最终都要以插件的方式接入。对刚开始接触插件开发的人来说，难点通常不是缺文档，而是缺一个把概念串起来、能装进 profile 跑通、每一步都有可观察输出的最小例子。
下面介绍 dsh-plugin-practice。它把插件开发的核心概念拆成六个递进的小课，代码按课程逐步累积，本身同时也是一个标准 DSH Bundle，可以用官方命令安装和卸载。
这是什么¶
dsh-plugin-practice 由 Ri0n72Y 维护，定位是用于学习 DeepSeek Harness / Cordis 插件开发的最小练习仓库，版本 0.1.0。它是 TypeScript 包，通过 prepare 脚本用 tsdown 从 src/ 构建到 lib/。
它解决的具体问题是：每个概念都落成一段可运行代码，并给出从构建、安装、启动到验证的完整命令链；每课都有对应的 Agent 测试语句和预期输出，学完即可自行验证。
仓库里有两个 patch 文件，对应两种加载方式：cordis.patch.yml 供正式 Bundle 使用；cordis.dev.patch.yml 用于 overlay 模式直接加载本地 TypeScript 源码。
课程内容¶
当前内容覆盖六个小课：
| Lesson | 文件 | 核心概念 |
|---|---|---|
| 1 | src/plugin.ts |
apply(ctx)、ctx.effect()、disposer、插件生命周期 |
| 2 | src/workspace-info.ts |
inject = ['tools']、defineTool()、参数与 canonical output |
| 3 | src/configurable-greet.ts |
Config interface、Schemastery、默认值、运行时配置校验 |
| 4 | src/workspace-name-service.ts + src/workspace-name-tool.ts |
Service Provider、Context declaration merging、Consumer / inject |
| 5 | src/workspace-event-* |
typed Events、ctx.emit()、ctx.on()、松耦合广播 |
| 6 | src/workspace-transform-* |
ctx.waterfall()、next()、around middleware、短路 |
几点说明：
- Lesson 1 的插件运行时每 5 秒输出一次
[practice-lifecycle] heartbeat，卸载时输出disposed，用来观察ctx.effect()注册的副作用和 disposer 的清理时机。 - Lesson 3 的
configured_greet工具使用 Bundle patch 中的greeting: Hi，对应 Config 默认值与运行时配置校验。 - Lesson 4 通过 Context declaration merging 自定义
ctx.workspaceNameService，Provider 与 Consumer 分属两个文件。 - Lesson 6 同时演示 around middleware 的包装与 block middleware 的短路：输入
hello经 uppercase 后返回HELLO；输入blocked words会在 block middleware 中短路默认处理，最终得到** BLOCKED **。
环境要求¶
1、Node.js ^22.19.0 || >=24.0.0；
2、pnpm（仓库声明 pnpm@11.7.0）；
3、本机已安装可直接执行的 dsh CLI。
先运行下面命令确认 CLI 可用，再进行后面的步骤：
dsh --help
本地开发与一键部署¶
克隆仓库并安装依赖：
git clone https://github.com/Ri0n72Y/dsh-plugin-practice.git
cd dsh-plugin-practice
pnpm install
日常开发完成后执行：
pnpm deploy
deploy 在 package.json 中定义为：
{
"scripts": {
"deploy": "pnpm run prepare && dsh plugin --profile practice add ."
}
}
也就是先用 tsdown 从 src/ 构建出 lib/，再把当前 checkout 安装或更新进 practice profile。然后启动 DSH：
dsh --profile practice
如果想先检查最终组合配置：
dsh --profile practice --dump-config
默认开发 profile 固定为 practice，需要换名字时直接调整 package.json 中的 deploy script。
用官方命令安装¶
pnpm deploy 只是把构建和官方安装命令串起来，插件安装和 profile 管理仍然由 DSH 完成。也可以跳过本地步骤，直接安装 Git 仓库：
dsh plugin --profile practice add github:Ri0n72Y/dsh-plugin-practice
本仓库是 TypeScript 包，package.json 提供了 prepare，Git 安装后会自动从 src/ 构建 lib/。注意 pnpm 10+ 第一次安装 Git 依赖时，可能需要在 profile 的 pnpm-workspace.yaml 中通过 allowBuilds 授权构建脚本。
能被这样安装，是因为 package.json 按官方约定声明了 Bundle manifest：
{
"dsh": {
"bundle": {
"patch": "./cordis.patch.yml"
}
}
}
安装链路是：dsh plugin add 读取 dsh.bundle 指向的 cordis.patch.yml，patch 再通过包导出路径加载构建后的 lib/*.js。
源码开发 / overlay 模式¶
改源码时如果不想每次都构建，可以走 overlay 模式直接加载 .ts 文件。先把 cordis.dev.patch.yml 中的 /ABSOLUTE/PATH/TO/dsh-plugin-practice 替换为仓库真实绝对路径，然后运行：
dsh web --patch /ABSOLUTE/PATH/TO/dsh-plugin-practice/cordis.dev.patch.yml
如果是从 DeepSeek Harness 源码仓库运行 CLI，则使用：
pnpm dsh web --patch /ABSOLUTE/PATH/TO/dsh-plugin-practice/cordis.dev.patch.yml
安装后测试¶
经过上面的步骤部署并启动后，在 Agent 中逐条测试：
Use the workspace_info tool and tell me the current workspace.
Use configured_greet to greet Ada.
Use workspace_name and return only the workspace name.
Use announce_workspace to announce the current workspace.
Use waterfall_demo with input "hello".
Use waterfall_demo with input "blocked words".
预期行为：
workspace_info返回当前 DSH Node 进程的cwd和目录名。configured_greet使用 patch 中的greeting: Hi，例如返回Hi, Ada!。workspace_name通过自定义的ctx.workspaceNameService 获取目录名。announce_workspace发出practice/workspace-announced事件，监听插件在终端输出[workspace-event] announced: <name>。waterfall_demo("hello")返回HELLO；waterfall_demo("blocked words")返回** BLOCKED **。- 后台每 5 秒输出一次
[practice-lifecycle] heartbeat，卸载时输出disposed。
六个小课对应的运行时行为都能直接观察到。
卸载与常用命令¶
卸载插件：
dsh plugin --profile practice remove dsh-plugin-practice
常用开发命令：
pnpm run typecheck
pnpm run build
pnpm run check
pnpm deploy
dsh --profile practice --dump-config
dsh --profile practice
适用场景与注意¶
适合想上手 DSH / Cordis 插件开发的开发者，尤其是希望按 lifecycle → Tool → Config → Service → Event → middleware 的顺序把概念过一遍的人。仓库体量小，主要依赖为 @deepseek-ai/cordis ^4.0.1、@deepseek-ai/dsh-tools ^0.1.0-rc.5、@deepseek-ai/schemastery ^3.18.1，适合直接读源码。
使用前注意：
1、插件以当前 dsh 进程的权限运行。安装任何第三方插件前都应先检查源码；本仓库的许可证在抓取的资料中没有明确声明（package.json 的 files 中列有 LICENSE 文件），以仓库实际内容为准。
2、DSH 仍处于快速迭代阶段，如果 API 发生 breaking change，应优先对照官方开发文档和当前 TypeScript 接口调整，不要假设仓库代码始终可用。
3、本文命令统一使用 practice profile；与现有 profile 冲突或需要隔离时，对应调整 deploy script 及安装命令中的 --profile 参数。
结尾¶
dsh-plugin-practice 的价值在于「可运行」：每个概念对应一段源码、一条测试语句和一份预期输出，学习路径闭环。如果你在找 DSH 插件开发的第一个练手项目，可以从它开始。
- 社区目录页（独立站点，与 DeepSeek / 幻方无官方从属关系）：https://www.skillhub.cn/plugins/Ri0n72Y/dsh-plugin-practice
- GitHub 仓库：https://github.com/Ri0n72Y/dsh-plugin-practice
