前言¶
DeepSeek Harness（DSH）支持通过插件扩展功能，社区维护了一个公共插件列表。在向该列表提交插件之前，需要符合一套具体的规范。手动检查 dsh.bundle 配置、cordis.patch.yml 挂载关系以及 peerDependencies 的版本范围容易出错，尤其是在处理 DeepSeek Harness 的预发布版本时。
dsh-plugin-preflight 是一个专门用于解决这些问题的工具。它的作用是在提交或发布插件前，自动验证其结构是否符合规范，并检测常见的兼容性问题。
这是什么¶
dsh-plugin-preflight 是一个零依赖的 DSH 插件，用于对 DeepSeek Harness 插件进行预检。
- 维护者：AphyTOT
- 许可协议：MIT
- 核心定位：开发者诊断工具，用于在插件提交前进行自动化校验。
核心功能¶
该工具主要验证以下五个方面的内容：
- dsh.bundle 清单验证
检查dsh.bundle配置是否存在且正确。如果只声明了dsh.client而没有dsh.bundle，这是导致插件提交被拒绝的最常见原因。 - cordis.patch.yml 挂载检查
验证dsh.bundle.patch指向的文件是否存在，以及补丁层是否正确挂载（检查行名、ID 是否匹配）。 - 客户端包形状校验
检查dsh.client导出是否正确，确保客户端模块系统能够加载该包。 - Peer Dependencies 兼容性
检测peerDependencies中的预发布版本兼容性问题。DeepSeek Harness 会发布预发布版本（如0.1.5-rc.2），普通的版本范围可能会静默排除这些版本，导致运行时ERESOLVE错误。 - 清单完整性
检查package.json是否存在 BOM、营销语言、缺少仓库 URL，以及 CLI 可执行文件是否包含在files[]中。
安装与启用¶
将此插件添加到当前 DSH 配置文件中：
dsh plugin --profile web add dsh-plugin-preflight
安装后，它会在 DSH 环境中注册一个只读的、面向模型的工具。你可以直接在 DSH 会话中调用它：
plugin_preflight(dir)
典型用法¶
安装后，可以通过命令行工具在任意目录下运行预检。
检查当前目录：
npx dsh-plugin-preflight
检查指定路径的仓库：
npx dsh-plugin-preflight path/to/repo
在 CI 环境中使用（遇到警告即报错）：
npx dsh-plugin-preflight --strict
适用场景与注意¶
适用场景
* 在向 awesome-dsh-plugin 提交插件前进行自检。
* 在发布插件到 npm 前确保清单和依赖配置正确。
注意点
- 运行环境：开发环境仅在 Windows 下经过测试。
- npm 发布：该插件尚未发布到 npm，直接通过 npm 安装的路径未经验证。
- 本地路径安装：使用本地路径安装时，系统会创建一个 junction（Windows 下类似软链接），实际是 pnpm link 的行为。由于 Node 解析 ESM 导入时通过真实路径向上查找
node_modules，这可能导致无法正确找到宿主包。本插件通过延迟加载宿主包来规避这个问题，确保即使运行时环境不可达，插件也能作为 CLI 工具运行而不导致 DSH 进程崩溃。 - 预发布版本验证范围：关于
peer/prerelease-tuple的验证目前仅基于 fixtures（测试数据），尚未在大量真实发布的插件上全面测试。
结语¶
dsh-plugin-preflight 能够覆盖插件提交规范中的大部分机器可验证规则。通过在本地或 CI 中运行它，可以避免因清单配置错误或版本范围陷阱导致的提交被拒或运行时错误。
