DeepSeek Harness (DSH) 采用全插件化架构。版本升级时，插件兼容性、存储格式变更以及会话数据迁移是三个主要风险点。dsh-compat-guard 是一个 npm 包，旨在为 DSH 提供一套兼容性治理方案，包括升级前置闸门、存储格式指纹校验、自动备份、会话迁移以及 Profile 级别的锁文件管理。
核心能力¶
该插件主要解决以下四个场景：
-
升级前置检查（闸门）
使用dsh-guard preflight进行检查。它会回答三个问题：插件兼容性、存储格式破坏性变更、自动备份。如果存储格式发生破坏性变更，升级将被拒绝（exit 1）。这是为了防止因存储格式变更导致的数据丢失事故。 -
插件×DSH 兼容矩阵
通过机器生成的兼容性数据，替代人工撰写的文章。注册表托管在 Blue-Whale-Harness 仓库中，包含插件的兼容状态和存储格式信息。 -
会话数据迁移
提供migrate命令。流程遵循安全优先原则：检测（detectLegacy）-> 备份 -> 转换 -> 验证 -> 检查点。支持将 SQLite 格式转换为 zstd JSONL 格式，并对未知格式仅做备份而不强制转换。 -
Profile 级锁文件与回滚
生成profiles/<name>/dsh.guard.lock.json。记录插件版本、配置 Hash、存储格式版本等信息。支持snapshot（快照）、verify（与锁文件比对）和rollback（一键回滚）。
安装¶
作为独立 CLI 工具安装：
npm i -g dsh-compat-guard
（可选）安装到 DSH profile 中以获得引导期探针：
dsh plugin --profile <name> add dsh-compat-guard
使用¶
日常使用需要将 dsh 命令通过 dsh-guard 包裹，以便在执行插件操作前自动过闸门。
设置别名/函数：
# bash
alias dsh='dsh-guard dsh'
# pwsh
function dsh { dsh-guard dsh @args }
常用命令：
- 状态检查：查看当前版本、dist-tags、存储指纹及锁文件状态。
dsh-guard status
- 升级前检查：执行
preflight，自动备份并检查插件兼容性与存储格式。
dsh-guard preflight
- 创建快照与锁文件：记录当前 Profile 的完整状态。
dsh-guard snapshot
- 验证一致性：对比当前环境与锁文件，检测团队漂移。
dsh-guard verify
- 回滚：恢复到之前的快照。
dsh-guard rollback
- 透传模式：手动调用
dsh-guard dsh对特定子命令进行前置检查。
dsh-guard dsh plugin add <plugin-name>
注意事项与边界¶
- 闸门非强制性：由于 DSH launcher 的
dsh plugin没有前置钩子，闸门无法强制拦截。必须通过别名dsh='dsh-guard dsh'的方式在用户端强制执行纪律。dsh-web-app内部的命令行解析机制也不支持插件树内挂载第二个解析器。 - 注册表来源：兼容矩阵数据托管在 Blue-Whale-Harness 的
compat/目录，默认通过 CDN 获取。离线时可能需要缓存。 - 格式指纹与未知数据：
lib/formats.json是种子数据。如果目标版本的存储格式未在注册表中登记，工具只会警告而不会静默放行。 - 迁移与验证：迁移 JSONL schema 必须对照目标版本确认；
verify命令的完整性校验基于插件package.json的 sha256，而非 npm integrity。
结语¶
dsh-compat-guard 是一套针对 DSH 升级风险的防御性工具集。通过前置闸门和 Profile 锁文件，它为智能体开发环境提供了数据安全的最后一道防线。更多细节可参考 GitHub 仓库 或 插件目录。
