插件开发范式指南Opr4Mp3r/deepseek-harness-plugin-from-scratch

从零开始编写 DeepSeek Harness 插件

一套从真实代码审计中提炼的 DeepSeek Harness 插件开发范式，以及一个可以安装、运行和逐步阅读的 TypeScript 插件。

这个仓库回答的不是“apply() 怎么写”，而是一个插件如何在真实 Harness 中做到：依赖正确、配置可验证、注册可撤销、服务可替换、模型可见内容可回放、测试覆盖真实装配路径。

非官方社区教程。审计基线是 deepseek-ai/deepseek-harness@47f9438，日期为 2026-08-13；示例依赖公开包 0.1.0-rc.6。Harness 尚处于预发布阶段，请先看兼容性说明。

先得到一张地图

Harness 的核心设计可以压缩成六句话：

1. 一切行为都是插件，普通功能不修改 agent-loop。
2. 必需依赖用 inject；可选读取用 ctx.get()；可选子贡献用 ctx.inject()。
3. 所有注册和外部资源都必须属于可撤销 effect。
4. 可替换能力由 Service Definition、Service Provider、Consumer 三种角色组成。
5. waterfall 是 around middleware；除非有意短路，监听器必须调用 next()。
6. 模型能看到的内容必须能从 Session log 重建：model-visible ⇔ logged。

cordis.yml / preset
│
▼
Cordis plugin fiber ── inject ──► services
│                             │
├── reversible effects        ├── Definition
│   (tools/events/resources)  ├── Provider
│                             └── Consumer
▼
agent extension points ──► Session log ──► model request / replay / UI

5 分钟运行与阅读

需要 Node.js ^22.19.0 或 >=24，以及 pnpm 11。审计和本地锁定环境是 Node.js 22.21.1、pnpm 11.7.0。

pnpm install --frozen-lockfile
pnpm smoke:source
pnpm smoke:loader
pnpm check

这些命令不需要 API key，也不会发起模型请求。smoke:source 验证仓库内的 TypeScript 源码；smoke:loader 先生成 lib/index.js，再由 plain Node.js 通过真实 Loader + Include 执行一次 greet。pnpm check 还会把 tarball 安装进隔离 consumer，以裸包名重新执行 Loader，防止源码相对路径掩盖发布错误。

本地交互阅读器不需要构建：

pnpm preview

打开 http://127.0.0.1:4175。01–05 五章都是独立的互动教程：切换章节后，右侧会换成本章自己的多文件仓库，并随正文依次加入生命周期资源、Definition / Provider / Consumer、Session 重放测试或发布验收代码。51 个 checkpoint 都位于对应解释和代码片段之后，只高亮刚刚讲过的新增行。阅读器直接投影 Markdown、manifest 和 canonical source，不维护第二份教程源码，也不需要部署网站。

安装进 Harness profile

当前仓库尚未发布到 npm registry。先从 checkout 生成包含 lib/ 和组合层的 tarball，再安装：

pnpm pack
dsh plugin --profile tutorial add ./deepseek-harness-plugin-from-scratch-0.1.0.tgz
dsh --profile tutorial --dump-config

最后一条命令应出现 # == deepseek-harness-plugin-from-scratch 层和 id: greet-tool。包内的 dsh.bundle.patch 指向 cordis.patch.yml；该 patch 使用裸包名加载已构建入口。缺少这两项时，dsh plugin add 只会安装普通依赖，不会激活插件。

默认配置是 Hello, .。如需修改，在该 profile 的 cordis.patch.yml 中覆盖整行配置；patch 不会深度合并 config，因此两个字段都要重述：

- id: greet-tool
config:
greeting: '你好'
excited: true

仓库用下面的独立检查执行完整安装路径：打包、dsh plugin add、配置层检查、启动 profile、调用 greet。默认使用固定的公开 CLI @deepseek-ai/dsh@0.1.0-rc.6，需要联网但不需要密钥：

pnpm check:profile

维护者审计上游新提交时，可把 DSH_HARNESS_ROOT 指向已安装依赖的 Harness checkout；同一脚本会改用该 checkout 的源码 CLI。也可以直接从 GitHub 安装，把占位符替换为已审计的完整 commit SHA：

dsh plugin --profile tutorial add 'github:Opr4Mp3r/deepseek-harness-plugin-from-scratch#FULL_COMMIT_SHA'
仓库为 GitHub dependency 提供自包含 prepare，但 pnpm 10 及以上会先拒绝执行并打印需要加入该 profile pnpm-workspace.yaml 的确切 allowBuilds 键。只对已审计并锁定到 commit 的源码授权，然后重新执行安装命令；希望避免安装时执行构建时，请使用上面的预构建 tarball。

像读文章一样看代码

每章各自维护 canonical source；examples/tutorials.json 只规定章节顺序，各章 checkpoints.json 把正文 marker 映射到一个真实文件。生成器据此产出完整仓库快照和 unified patch，CI 验证 manifest、源码 marker、正文片段与阅读触发点逐字一致；每一步只能向一个文件插入已解释的行，最后一步必须等于本章全部 canonical source。

| 章节 | checkpoint | 右侧仓库最终包含 | GitHub 阅读终点 | 运行证据 |
|---|---:|---|---|---|
| 01 最小插件 | 10 | 配置、schema、工具输入/输出、执行与 UI intent | 10-assembly.ts | pnpm smoke:source |
| 02 生命周期 | 9 | awaited event、timer、在途任务、异步 disposer、卸载测试 | 09-await-quiescence/ | pnpm test |
| 03 能力三角色 | 12 | Definition、可替换 Provider、Consumer 与 swap 测试 | 12-swap-provider/ | pnpm test |
| 04 事件与持久化 | 11 | waterfall、deferred context、AgentLoop、日志重建与 JSON replay | 11-json-replay/ | pnpm test |
| 05 测试与发布 | 9 | unit、fiber、Loader、built entry、tarball consumer、profile activation | 09-profile-activation/ | pnpm check / pnpm check:profile |

提交的 TypeScript canonical examples 进入同一个 strict program；unit 与 lifecycle 由 Vitest 执行，Loader、built entry、tarball consumer 和 profile 则由表中对应的真实命令验收。中间仓库快照是教学投影：它们保证来源明确、顺序只增和最终逐字一致，不假装每一个尚未讲完的阶段都是独立发布包。

diff 同样由生成器产生，因此 GitHub 中也能查看每一步。修改任一教程时，同步更新本章 canonical source、checkpoints.json 和正文中的解释、代码片段与 marker，然后运行：

pnpm generate:checkpoints
pnpm check

学习路径

1. 架构地图：插件、Context、Service、event、Session log 如何协作。
2. 最小插件：从空仓库到一个完整工具，每段解释只引入对应代码。
3. 生命周期与 effect：异步 effect、资源 quiescence 与卸载测试。
4. 能力三角色：什么时候拆 Definition / Provider / Consumer，以及四种常见拓扑。
5. 事件与持久化：waterfall、commit point、model-visible ⇔ logged。
6. 测试与发布：为何 100% 单测仍可能完全不可用。
7. 反模式：审计中最容易踩的 17 个坑。
8. 交付检查单：可以直接复制到 PR 描述。
9. 审计报告：每条结论对应的上游源码证据。

仓库结构

docs/                         五章渐进教程、参考和审计证据
examples/tutorials.json       互动章节的唯一顺序目录
examples/progressive/         可安装的最小 Consumer 源码与 composition
examples/lifecycle/           外部资源、effect 与 quiescence 教程
examples/capability/          Definition / Provider / Consumer 教程
examples/events/              durable context、AgentLoop 与 replay 教程
examples/testing/             从 unit 到 profile activation 的验收教程
examples//checkpoints/       自动生成的多文件仓库快照
cordis.patch.yml              安装后加入 profile 的组合层
lib/                          构建生成的 ESM 入口与类型声明（不提交）
preview/                      无构建的本地 scrollytelling 阅读器
scripts/                      checkpoint 与文档防漂移检查
audit-manifest.json           审计 commit、日期与运行时版本基线

兼容性

本教程同时钉住两类版本：

- 审计语义：Harness commit 47f943859bef60e4160492346772ded9b24f765a。
- 可运行示例：公开 npm 包 @deepseek-ai/dsh- 0.1.0-rc.6 与 @deepseek-ai/cordis 4.0.1。
- 装配与配置：@deepseek-ai/cordis-plugin-include 1.0.6、@deepseek-ai/cordis-plugin-loader 1.0.2、@deepseek-ai/schemastery 3.18.1。
- 发布包 peer window：@deepseek-ai/cordis ^4.0.1、@deepseek-ai/dsh-tools ^0.1.0-rc.5；CI 与 tarball smoke 仍锁定上面的 rc.6 实现。

上游在首个正式 tag 前明确不承诺兼容旧格式，因此升级依赖时应重新执行审计清单，而不是只看 TypeScript 是否通过。

参考与边界

本仓库借鉴 PI from Scratch 的方法：先画模块地图，再沿数据流引入概念；最终源码是事实源，教程 checkpoint 由脚本生成。仓库不构建或部署网站；GitHub 内可以直接浏览编号快照和 diff，本地 pnpm preview 则提供滚动驱动的代码演进效果。

教程中的五套代码都经过缩小，以便一次只讲清一个 Harness 责任。要把其中的模式合并进 Harness 主仓库，还需满足所属包的 invariant、真实 Loader composition、keyless snapshot、README/JSDoc、双语文档与 Agent Note 等仓库规则，详见测试与发布。

参与贡献

请阅读 CONTRIBUTING.md。安全问题请按 SECURITY.md 私下报告。项目采用 MIT License。