前言¶
DeepSeek Harness (DSH) 采取「一切皆插件」的理念。当版本升级导致第三方插件冲突，GUI 无法启动时，常规修复手段失效。此时需要一种能在插件体系之外生效的工具，dsh-rescue 正是为解决这一场景设计。
当 DSH 因插件冲突陷入死锁，dsh-rescue 临时摘除 profile 中所有第三方插件层，让 dsh 以纯核心启动并自行修复；修完一条命令即可原样还原。
是什么¶
dsh-rescue 是 DeepSeek Harness (DSH) 的救援模式工具，由 Iliyasfiel 维护，采用 MIT 许可证。
它是一个启动级工具，而非插件。其核心原理是直接编辑 profile 的 manifest（清单文件），剥离 dsh.profile.bundles 中定义的第三方 bundle。因为内置核心层（如 @deepseek-ai/dsh-base）不在 dependencies 中，它们会被保留，从而确保 DSH 能以一个纯净的核心启动。
核心能力¶
该工具提供以下核心功能：
- 临时剥离：移除 profile stack 中所有第三方 bundle。
- 纯核心启动：允许 DSH 在没有第三方插件干扰的情况下启动，用于修复。
- 一键还原：修复完成后，通过一条命令恢复原始插件栈。
- 事务化备份：在修改 manifest 前先备份和记录状态，修改失败会自动回滚。
- 协调式退出：
exit命令会智能还原，仅当插件包仍在dependencies时才恢复，已删除的插件不会被强行复活。 - 零依赖离线：纯 Node 实现，无需
pnpm，完全离线可用。 - 生态兼容入口：提供一个惰性的
cordis bundle入口（apply()为空操作），使其可作为插件被dsh plugin add安装，但实际运行机制是 CLI。
安装¶
全局安装 CLI（推荐，这是救援路径）：
npm install -g dsh-rescue
或者，将其注册为生态兼容的 bundle（可选）：
dsh plugin --profile web add dsh-rescue
典型用法¶
救援工具的工作目录默认为 $DSH_HOME/profiles（DSH_HOME 通常指向 ~/.dsh），默认 web GUI profile 名为 web。
基本命令¶
dsh-rescue enter <profile> # 进入救援模式：仅保留核心层，隔离第三方插件
dsh-rescue exit <profile> # 退出救援模式：协调并还原原始插件栈
dsh-rescue status <profile> # 查看状态：救援状态、核心层与第三方层的拆分情况
dsh-rescue help
典型救援流程¶
当 DSH 无法启动时，停止当前进程并执行以下步骤：
# 1. 进入救援模式
dsh-rescue enter web
# 2. 此时 profile 仅包含核心层，DSH 应能正常启动
dsh web
# 3. 在 GUI 或 CLI 中修复插件冲突（例如移除冲突的包）
dsh plugin --profile web remove <conflicting-package>
# 4. 退出救援模式，还原插件栈
dsh-rescue exit web
# 5. 恢复正常启动
dsh web
行为细节¶
- 判定规则：工具仅依据
dependencies和dsh.profile.bundles的交集来判定第三方插件，不依赖包名前缀假设，因此对 DSH 核心形态的变化更稳健。 - 不可侵入性：救援工具不能作为插件安装在 DSH 内部运行（它会成为被隔离的对象）。因此，其真正的机制是 CLI，而 bundle 入口是刻意设计为惰性的（
apply()为空），仅用于生态兼容。 - 状态管理：
enter只精简bundles，保留dependencies。exit会精确还原bundles，仅当插件包仍存在于dependencies中时才恢复。- 救援期间若宿主自动补写了默认配置，
exit会精确移除这些自动写入的配置，保持还原的干净。
适用场景与注意¶
- 适用场景：版本升级导致 GUI 无法启动，需要在不启动插件的情况下修复 profile 配置。
- 注意：
- 救援工具以当前 dsh 进程的权限运行，安装前应检查源码。
- 不能在已经处于救援模式的 profile 中再次
enter，或对非 profile 目录、无状态目录执行操作，系统会报错并拒绝修改。 - 由于是直接编辑 manifest，操作前建议备份 profile 目录。
