前言¶
DeepSeek Harness（DSH）的核心理念是“一切皆插件”。随着本地安装的插件数量增加，开发者面临的问题逐渐从“如何使用”转向“如何管理”。如何确认一个插件是否与其声明的能力一致？不同插件之间是否存在冲突？升级 DSH 版本后，现有插件是否还能正常工作？DSH Harbor 针对已安装在机器上的插件，提供了一份基于证据的只读账本。它通过能力清单、声明与检测对比、运行时归属、冲突检测、版本漂移追踪以及升级预检等功能，帮助开发者在不破坏现有环境的前提下进行治理。
核心能力¶
DSH Harbor 对插件进行证据优先的治理，主要包含以下能力：
- 能力清单：扫描 DSH 配置文件中的所有第三方插件，报告固定的 13 种能力词汇。源代码发现结果携带
file:line证据，确保来源可追溯。 - 声明 vs 检测：将插件在
package.json中的能力声明与实际检测情况进行比对，暴露缺失或未知的能力 ID，并在声明格式错误时关闭报告，防止单一坏包影响整体结果。 - 运行时归属：在 DSH 主机运行时，枚举工具、提供者、路由，并将其仅归属于当前激活配置文件中安装的插件。未安装的插件对应的宿主机注册表会被标记为覆盖缺口。
- 冲突检测：在账本中查找同一配置文件下的工具名称、路由前缀、提供者 ID、客户端模块 ID 以及顺序敏感的消息钩子。
- 版本漂移：检测跨配置文件的版本差异，默认为本地离线模式。可选的上游检查独立于预检流程，且结果会被缓存。
- 变更时间线：快照追踪添加、移除、版本转换、配置文件迁移、能力变更和声明变更。
- 升级预检：在升级 DSH 前检查插件兼容性，验证
dsh.client.injectID 和宿主机对等范围，并检查配置文件中的agent-presets.default是否存在迁移问题。
使用方法¶
DSH Harbor 提供了 CLI 命令用于扫描和预检。
升级预检¶
升级前，你可以使用以下命令检查插件在目标 DSH 版本下的兼容性：
# 列出发行标签、最新版本和本地缓存的宿主机树
harbor preflight --list
# 检查 DSH 的下一个版本（或指定具体版本）
harbor preflight --dsh next
# 检查特定版本，并以 JSON 格式输出
harbor preflight --dsh 0.1.5-rc.2 --json
跨进程/非安装状态检查¶
在不处于特定配置文件（如在 CI 环境中）或未安装某个包时，可以显式指定检查对象：
# 检查当前仓库（需先构建）
harbor preflight --dsh next --plugin .
# 检查远程包
harbor preflight --dsh next --pack @scope/some-plugin@1.2.3
注意事项¶
- 运行环境与权限：DSH 插件在宿主机的 Node 运行时域中运行，拥有与 DSH 本身相同的本地权限。因此，安装和启用前应检查源码与许可证。
- Node 版本要求：
resolve hook需要 Node.js 版本不低于 20.6。 - 离线模式：默认扫描路径为离线模式，只有明确使用
--check-updates、harbor preflight或设置面板中的更新操作才会联系注册表。 - 配置检查：DSH 0.1.2 引入了内置代理预设的重命名（
code->ptc）。如果settings.yaml中的agent-presets.default未迁移，新会话将失败，预检会报告该问题。 - 账本性质：DSH Harbor 是已安装插件的只读账本，用于提供证据和发现冲突，而非修复问题。
总结¶
DSH Harbor 专注于对已安装的 DeepSeek Harness 插件进行客观、证据优先的治理。它通过提供冲突检测、版本漂移追踪和升级预检等机制，帮助开发者在复杂的插件生态中保持环境的可预测性和稳定性。
