前言¶
在 DSH 的「一切皆插件」思路下，插件开发不只是写一个 apply() 函数。更常见的问题是：依赖是否正确、配置是否能验证、注册是否能撤销、服务是否能替换、模型可见内容是否能回放、测试是否覆盖真实装配路径。
deepseek-harness-plugin-from-scratch 围绕这些问题给出一套代码审计后的渐进教程，并提供一个可以安装、运行和逐步阅读的 TypeScript 插件。
这是什么¶
这是一个由 Opr4Mp3r 维护的非官方社区教程仓库，项目采用 MIT License。
它面向想读懂 DSH 插件装配路径的开发者，重点是生产级插件需要的检查点：配置可验证、注册可撤销、服务可替换、模型可见内容可回放、测试覆盖真实装配路径。
仓库当前尚未发布到 npm registry。Harness 处于预发布阶段；上游在首个正式 tag 前明确不承诺兼容旧格式。
核心功能¶
下面介绍仓库提供的能力：
- 可安装、运行和逐步阅读的 TypeScript 插件。
- 提供
greet-tool工具及cordis.patch.yml组合层。 - 提供
pnpm smoke:source、pnpm smoke:loader、pnpm check等本地验证命令。 - 提供
pnpm preview本地交互阅读器。 - 用真实装配路径覆盖测试与发布检查。
本地运行与阅读¶
环境要求是 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
pnpm smoke:source 和 pnpm smoke:loader 用于本地验证源码与加载路径，pnpm check 执行更完整的检查。
启动本地阅读器：
pnpm preview
打开 http://127.0.0.1:4175，可以按章节阅读插件代码。
安装进 Harness profile¶
由于当前仓库尚未发布到 npm registry，可以先从源码生成 tarball，再安装到 tutorial profile：
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 插件在 profile 中的配置层。
需要注意：如果缺少 dsh.bundle.patch 指向的 cordis.patch.yml，dsh plugin add 只会安装普通依赖，不会激活插件。
如果要在该 profile 的 cordis.patch.yml 中覆盖插件配置，patch 不会深度合并 config，因此覆盖配置时相关字段都要重述。下面示意这种配置覆盖方式：
- id: greet-tool
config:
# 需要重述要覆盖的配置字段
完整安装路径检查¶
仓库提供一条独立检查命令，用于执行完整安装路径：
pnpm check:profile
这条命令会执行打包、dsh plugin add、配置层检查、启动 profile 并调用 greet。
GitHub 安装与构建限制¶
仓库中也给出从 GitHub commit 安装的形式：
dsh plugin --profile tutorial add 'github:Opr4Mp3r/deepseek-harness-plugin-from-scratch#FULL_COMMIT_SHA'
这里 FULL_COMMIT_SHA 是占位符，需要替换为具体 commit SHA。由于该安装路径可能触发构建，且 pnpm 10 及以上可能要求加入 allowBuilds，如果希望避免在安装时执行构建，可以使用前面的预构建 tarball 安装方式。
适用场景与注意¶
适合以下情况：
- 想读懂 DSH 插件的依赖、注册、服务和回放路径。
- 想用一个可运行的 TypeScript 插件对照真实装配路径。
- 想在本地先做
smoke、check、preview，再决定是否安装进 profile。
需要注意：
- 插件会以当前 dsh 进程权限运行；安装前应检查源码、依赖和许可证。
- 该仓库是 MIT License 的非官方社区教程。
- Harness 处于预发布阶段；上游在首个正式 tag 前明确不承诺兼容旧格式。
- 当前仓库尚未发布到 npm registry；安装路径以仓库给出的 tarball 或 GitHub commit 为准。
- 从 GitHub commit 安装时，注意占位符、commit 选择和 pnpm 构建限制。
结尾¶
这个仓库的价值在于把 DSH 插件开发从“函数怎么写”推进到“插件如何被真实装配、验证和回放”。如果要继续看源码，可以从 GitHub 仓库开始。
GitHub 仓库：
https://github.com/Opr4Mp3r/deepseek-harness-plugin-from-scratch
