插件开发九课 kbaynes/dsh-exploration-kit

DSH 探索套件

一套动手实践的九课教程，带你通过构建真实插件来学习 DeepSeek Harness（dsh）——从挂载第一个插件，到无人值守的自动化。

DSH 是插件式智能体运行时：每一项能力都是 Cordis 插件，挂载进同一个共享上下文。这套套件把这个机制讲一遍，然后每一课都指向不同的扩展接缝。

从这里开始 → 学习路径，然后是 第 1 课，不需要 API key。

九节课

| # | 课程 | 新机制 | 需要 API key？ |
| 1 | 挂载第一个插件 | 插件树、形态、fiber 生命周期 | 否 |
| 2 | 注册工具，用配置组合 | ctx.tools、Schemastery、补丁层 | 否 |
| 3 | 服务、隔离与热重载 | ctx. 服务、inject、HMR、清单 | 否 |
| 4 | 构建策略闸门 | tools/ 与 fs/ 瀑布事件、守卫 | 可选 |
| 5 | 有意识地组装上下文 | 上下文钩子、技能、命令 | 是 |
| 6 | 给会话持久状态 | SessionEventMap、投影、重放 | 否 |
| 7 | 运维 harness | 会话查询、遥测、token 计量 | 是 |
| 8 | 编排多个智能体 | 子代理、fork、工作流引擎 | 是 |
| 9 | 自动化 harness | 无头模式、SDK/ACP、定时、webhook | 是 |

另外还包含：能力地图——按子系统分组列出 DSH 的每项功能，并标注提供它的包或接缝；以及学习路径，解释课程排序。

仓库结构

content/ 教程本体——一个 Open Knowledge Format 包 index.md 包入口 feature-map.md 能力清单 learning-path.md 教程设计（排序、检查点） lessons/ 九节课 website/ VitePress 配置与主题（就地渲染 content/） kit-plugins/ 承载每课练习插件的 dsh 包 plugins/ 你自己的草稿区，用来写练习 examples/ 每课文件的生成镜像（CI 中做漂移检查） solutions/ 答案，卡住时用来 diff scripts/ 校验工具

content/ 是唯一事实来源。网站直接读取它，没有任何重复。

前置条件

要学习这些课程，你需要一份已经跑过 pnpm run build 的 DeepSeek Harness 源码检出，并且 dsh 已在 PATH 中。接着把本套件的练习 bundle 装进 dsh 配置档：

cd kit-plugins && pnpm install && cd ..
dsh plugin --profile kitdemo add link:$PWD/kit-plugins

插件为什么必须以 bundle 形式发布、而不能作为散装文件加载，见 kit-plugins/README.md。课程会针对那份检出创建并启动真实插件，所以没有检出就无法完成整个课程。检出与命令行环境的搭建，见 DSH 的开发指南。

要构建本站，你需要 Node.js ≥20 和 pnpm ≥10。开发环境已在 Node 22.23.1 搭配 pnpm 11.7.0 上验证通过，版本固定在 packageManager 中。

第 1–3 课和第 6 课不需要模型 API key。第 4、5 课以及第 7–9 课有配置好的服务商更好（而且大多必须有）。

构建本站

在仓库根目录执行：

pnpm run setup # installs BOTH dependency roots (see below)
pnpm run dev # local preview at http://127.0.0.1:5173
pnpm run build # static build into website/.vitepress/dist
pnpm run preview # serve the production build at http://127.0.0.1:4173

pnpm 需要显式批准构建脚本。 pnpm-workspace.yaml（以及 kit-plugins/ 里的第二个同名文件）按名字批准了 esbuild 的 postinstall。没有它，全新安装会以 ERR_PNPM_IGNORED_BUILDS 退出，退出码 1，但 node_modules 照样填好——本地很容易忽略，到了 CI 就是致命错误。

这里有两个依赖根，是刻意为之。 仓库根目录放站点工具链；kit-plugins/ 放课程插件自己的依赖。这个 bundle 不是 workspace 成员，因为它的包正是配置档在运行时解析的对象，把它并进根 workspace 会改变解析结果（ADR-0003）。代价是全新克隆需要装两次——pnpm run setup 会把两次都做掉。如果你只跑 pnpm install，pnpm run check:units 会明确告诉你，而不是抛一个 import 错误。

在意部署后的 URL 时，用 preview 而不是 dev：dev 从站点根目录提供服务，会掩盖 VitePress base 路径上的错误。

pnpm run dev 和 pnpm run build 会先跑 scripts/sync-site-docs.mjs，把 VERIFIED.md、CONTRIBUTING.md 和 THIRD-PARTY.md 复制进 content/ 供构建使用。这些副本是生成的，已被 git 忽略——要改就改根目录下的原文件。
为什么需要提升依赖。 VitePress 编译 content/ 里的 markdown，而 content/ 位于调用 VitePress 的目录之外*。pnpm 只为已声明的依赖创建符号链接，所以 Node 无法从那些文件里解析 vue，构建会失败并报 Rollup failed to resolve import "vue/server-renderer"。仓库的 .npmrc 设置了 shamefully-hoist=true 来解决这个问题；这是有意为之、有文档记录的变通做法，不是随手写错的配置。

pnpm 还可能打印 Ignored build scripts: esbuild。这条警告在这里无害 —— Vite 的平台二进制来自 esbuild 的可选依赖包，而不是它的 postinstall 脚本，忽略该脚本构建照样成功。想让它闭嘴，运行 pnpm approve-builds。

检查

pnpm run check:links # every relative link inside content/ resolves
pnpm run check:placeholders # no pre-publication placeholders remain
pnpm run validate # OKF conformance, if okflint is on your PATH
pnpm run check:upstream # upstream DSH links resolve (needs a checkout)
pnpm run check:examples # examples/ matches the canonical bundle

check:upstream 接受一个 DSH 检出路径作为参数，也可以从 DSH_CHECKOUT 读取：

DSH_CHECKOUT=~/src/deepseek-harness pnpm run check:upstream

$DSH_HOME 全程有效 —— 脚本读取 ${DSH_HOME:-$HOME/.dsh}，dsh 本身也接受这个变量，所以把 harness home 指向别处（比如指向沙箱内可写的位置）不需要改动这里的任何东西：

DSH_HOME=/tmp/dsh-verify pnpm run check:kit

它之所以存在，是因为课程用绝对 GitHub URL 链接到 DSH 文档，而像 docs/harness/plugins.md 这样看起来合理的路径可能根本不存在。CI 在每次 push 时运行那些不依赖环境的检查；完整的一套（包括每课单独的检查）在 verify against dsh 工作流里运行 —— 它会克隆 kit.target.json 中固定的那个提交的 harness，同时也是发布门禁。

想在你自己的检出上本地复现：

bash scripts/install-dsh-shim.sh <path-to-deepseek-harness> /tmp/dsh-bin
PATH=/tmp/dsh-bin:$PATH bash scripts/setup-verify-profiles.sh ""
DSH_CHECKOUT=<path-to-deepseek-harness> PATH=/tmp/dsh-bin:$PATH pnpm run check:kit

已从提交树的干净导出验证过：pnpm install --frozen-lockfile、pnpm run check:links 和 pnpm run build 全部成功，没有继承任何 node_modules。

部署站点

每次 push 到 main，站点都会通过 .github/workflows/site.yml 部署到 GitHub Pages。

一次性设置：Settings → Pages → Build and deployment → Source: GitHub Actions。该工作流不需要 secrets，也不需要 DSH 检出 —— 课程是文档，不是可执行代码。
站点随后会从 https://<owner>.github.io/dsh-exploration-kit/ 提供服务，这个地址必须与 website/.vitepress/config.mts 里的 base 一致。如果用的是用户/组织根站点或自定义域名，把 base 改成 /。

兼容性

编写与验证所依据的是 DeepSeek Harness 0.2.0-rc.2，上游 tag 为 dsh-v0.2.0-rc.2，commit 为 639ed015397290b3745d163aafe02ffee4aa3f84。

发布版本的 tag 会标明它针对的 harness 状态 —— v<kit-version>+dsh.<dsh-version>.g<short-dsh-sha> —— 这样你一眼就能看出某节课是否在你手上的 harness 上验证过。策略见 VERIFIED.md。

这套工具把该状态记录在一个地方，即 kit.target.json，而 pnpm run check:target 会把其他所有记录 —— 账本、本 README、路线图、tag 示例、bundle 的版本锁定、verify 脚本的默认值 —— 都对齐到这个文件。任意两处出现偏差，就等于对「验证了什么」做出虚假声明。

DSH 是开发者预览版，会不断变化。VERIFIED.md 精确记录了哪些步骤已针对该 commit 执行过、哪些只是有文档但未验证 —— 在相信某节课更进一步的结论之前，先读它。

项目状态与计划

九节课全部完成，而且其中的每一项退出检查条目都已执行，针对的是锁定的 harness 状态 —— 大多数无需密钥，跑的是仓库里可脚本化的 mock 服务商；有三项跑的是真实模型。确切的证据，以及一份刻意不做出声明的简短清单，都在 VERIFIED.md。

- ROADMAP.md —— 状态一览，按阶段、按课逐项列出。
- decisions/ —— 这套工具背后的工程决策，每一条都是先踩了坑才总结出来的。贡献之前值得一读。
- PLAN.md —— 详细的、以复选框驱动的实施计划，覆盖构建、测试、评审、发布准备和推广。
- PUBLISHING.md —— 把本仓库公开的操作手册，以及 pnpm run check:publication，这个门禁在准备就绪前会一直拒绝放行。

统领整个项目的规则：只有跑过并记录了观察结果的步骤，才算验证过。 如果你遇到按文档写的方式跑不通的地方，那就是缺陷，值得开 issue —— 见 CONTRIBUTING.md。

获取帮助与报告缺陷

开一个 issue。我们提供了两个模板：

- 课程缺陷 —— 某一步跑不通，或某项技术结论有误。请附上你的 DSH 版本；版本漂移是最常见的原因。
- 清晰度反馈 —— 步骤能跑通，但解释没讲明白。这类反馈真的很有价值：如果它把你绕晕了，也会把别人绕晕。
请先看 VERIFIED.md —— 从未执行过的课程，出问题的概率要高得多，先把预期摆正才是老实做法。

关于 DeepSeek Harness 本身的问题，请去上游提，不要发在这里。

参与贡献

欢迎纠错、把讲解写得更清楚，也欢迎新增课程。请看 CONTRIBUTING.md，另外注意，参与本项目即受 Code of Conduct 约束。

许可与署名

课程内容与网站采用 MIT 许可。DeepSeek Harness 由 DeepSeek AI 开发，采用 MIT 许可；本套件是独立、非官方的教学资源，与 DeepSeek AI 无隶属关系，也未获其背书。详见 THIRD-PARTY.md。