DeepSeek Harness Plugin from Scratch

一套从真实代码审计中提炼的 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。正文越过十个 checkpoint 时，右侧 src/index.ts 会从空文件逐步增长到完整插件；每个 checkpoint 都位于对应解释和代码片段之后，只显示刚刚讲过的新增行。阅读器只投影仓库中的 Markdown、checkpoint manifest 和自动生成快照，不维护第二份教程源码，也不部署网站。