前言¶
DeepSeek Harness (DSH) 在 0.1.7+ 版本中引入了声明式的 cordis.patch.yml 机制，并移除了旧的目录扫描模式。在框架升级过程中，现有的 Agent 预设声明极易因包名重命名、配置键变更或语法迁移而失效，导致 UI 上仅显示「加载失败」，且无法定位具体原因。
dsh-preset-doctor 是一个 DeepSeek Harness 插件，旨在自动检测并修复这些失效的预设声明。它通过零 LLM 介入的确定性代码，处理从旧格式迁移、包名替换到原子化修复的全过程。
核心功能¶
该插件提供以下自动化能力：
- 自动扫描：检测失效的 Agent 预设声明。
- 自动迁移：将旧格式的目录结构自动转换为声明式 patch。
- 自动替换：根据迁移表自动替换已重命名的包名。
- 配置键拆分：自动将
persona配置中的text键拆分为prefix和suffix。 - 路径改写：将本地路径（
.//../）自动改写为file://URL。 - 安全写入：修复前自动备份（
.bak）与原子写入，支持幂等操作。 - 链式收敛：支持链式收敛处理版本漂移，确保不同时代的预设能统一适配当前版本。
安装与启用¶
通过 npm 全局安装插件，然后添加到 DSH 中。
npm install -g dsh-preset-doctor
dsh plugin add dsh-preset-doctor
安装完成后，插件会在 DSH 进程启动约 1 秒后自动扫描 $DSH_HOME/cordis.patch.yml、profiles/<name>/cordis.patch.yml 及遗留的 .agent-presets/ 目录。
使用方法¶
修复生效需要重启 DSH 进程（预设注册表仅在启动时加载）。在会话中可执行以下命令：
/preset-doctor：扫描并自动执行机械修复。/preset-doctor scan：仅扫描并报告，不执行写盘操作。
技术细节与限制¶
- 零 LLM 介入：完全基于
@deepseek-ai/schemastery和yaml库进行静态分析和修复。 - 仅语法修复：插件保证修复后的预设语法合法、可加载，但不保证修复后的行为与旧版本完全等价。
- 安装行为：插件安装过程本身不安装依赖、不修改
package.json、不重启进程。 - 环境依赖：宿主版本需满足
engines.dsh要求（>=0.1.1-rc.1），并依赖@deepseek-ai/cordis（>=4.0.1 <5）。
资源¶
- GitHub: https://github.com/drscrewdriver/dsh-preset-doctor
- 目录页: https://www.skillhub.cn/plugins/drscrewdriver/dsh-preset-doctor
