AndyZHENG0715/dsh-recovery

dsh-recovery

中文版本请见 README-ZH.md

DeepSeek Harness 恢复系统：一个纯 Node、零运行时依赖的 CLI，外加一个进程内看门狗包，通过诊断 → 快照 → 回滚 → 安全模式 → 启动验证的分阶段流程，帮助 DSH 从损坏的配置、插件、预设、会话或升级回归中恢复。

当前状态

- P0：CLI 恢复流程 — 已实现
- P1：启动器和自动恢复阶梯 — 已实现
- P2：进程内看门狗包 — 已实现
- P3：救援胶囊 / DSH 运行时回滚 / 会话修复 — 已规划

命令

| 命令 | 用途 |
|---|---|
| scan | 扫描 profile、settings、storages、用户预设和会话中的常见损坏 |
| snapshot | 创建恢复快照；支持组合、用户资产和可选数据层 |
| rollback | 回滚到 --latest、--good 或 --id  |
| safemode enter/exit | 进入或退出安全模式 profile |
| boot-probe | 在临时 DSH_HOME 中运行静态和真实启动验证 |
| doctor | 汇总扫描结果、状态、快照清单和恢复提示 |
| list | 列出快照 |
| launch | 启动包装器，支持透明 argv 转发、启动标记和恢复阶梯 |
| quarantine | 管理被隔离的行 |
| unquarantine | 恢复被隔离的行 |
| guard | 安全模式 profile 守卫 |

常用标志：

- --home ：默认为 $DSH_HOME / ~/.dsh
- --profile web：默认 profile
- --dsh ：默认为 $DSH_RECOVERY_DSH_DIR
- --json：机器可读输出

退出码：

- 0：成功
- 1：错误 / 探测失败
- 2：用法错误

运行

node bin/dsh-recovery.mjs scan --json
node bin/dsh-recovery.mjs snapshot --reason before-upgrade
node bin/dsh-recovery.mjs boot-probe --live --mark-good
node bin/dsh-recovery.mjs rollback --good
DSH_HOME=~/.dsh node bin/dsh-recovery.mjs safemode enter
node bin/dsh-recovery.mjs launch --profile web -- --port 3080

如果 pnpm 不可用，--install 会发出明确的警告。你可以通过 --pnpm  或 DSH_RECOVERY_PNPM 指向一个二进制文件。

安全模型

- 快照内容绝不包含机密：
- settings.yaml 默认以脱敏结构存储（secret 键 → *），并附带原始 SHA-256
- .credentials.yaml 仅做指纹记录；其内容绝不会被复制
- 需要 --include-settings 才会存储原始 settings.yaml
- 回滚前会自动创建回滚前快照
- boot-probe 仅写入 $TMPDIR 下的临时 home；真实 home 绝不会被修改
- boot-probe 的实时阶段会传入 --no-open，因此不会打开浏览器
- 快照清单记录 DSH 版本和文件 SHA-256 哈希，用于升级归因
- 诊断和事件输出在导出前应进行脱敏

P1 启动器和恢复阶梯

替换直接 dsh 启动：透明转发 + 启动标记 + 自动恢复
node bin/dsh-recovery.mjs launch --profile web -- --port 3080

隔离管理与一键恢复
node bin/dsh-recovery.mjs quarantine list
node bin/dsh-recovery.mjs unquarantine --id

安全模式配置文件守卫
node bin/dsh-recovery.mjs guard --once
node bin/dsh-recovery.mjs guard --poll-ms 30000

启动器将恢复状态记录在 recovery/journal.log 和 recovery/incidents/ 中：

1. 崩溃证据：正常退出时清除启动标记；若标记仍然存在，则下次启动将其视为崩溃证据
2. 归因隔离：若某个非核心第三方行失败，则写入一条标记为 disabled 的行，并重启进程
3. 回滚：若无法归因失败，或某个核心行失败，则恢复上一个良好快照
4. 熔断器：在时间窗口内反复失败会触发 safemode

阈值位于 recovery/config.json 中的 boot. 和 guard. 下，可被覆盖。launch 还接受：

- --retries
- --ready-ms
- --threshold
- --window-ms
- --no-ladder
- --no-auto-safe-boot

P2 进程内看门狗包

packages/dsh-recovery-watchdog 是一个可安装的 dsh 包：

dsh plugin --profile web add link:/abs/path/dsh-recovery/packages/dsh-recovery-watchdog

它负责：

- 在 fiber 失败后隔离非核心行
- 写入和清除启动标记与心跳
- 在插件安装变更前拍摄 Tier A+B 快照
- 协调已安装但缺失于 bundles 层的依赖
- 隔离损坏的用户预设，并将默认预设回退到 standard
- 在运行时验证用户预设挂载健康状况
- 暴露仅限回环的状态与渲染报告路由
- 在设置中注册恢复状态卡片

测试

npm test        # node --test；在隔离的 DSH_HOME 副本中运行，绝不触碰真实的 ~/.dsh

当前测试覆盖包括：

- YAML 子集解析器单元测试
- 损坏检测
- 三层快照与脱敏
- 回滚恢复与验证门禁
- safemode 进入/退出
- boot-probe 静态门禁 + HTTP 200 门禁
- doctor 聚合
- P2 看门狗单元与 E2E 路径

说明

- 已在 @deepseek-ai/dsh@0.1.1-rc.2 和 Node 24 上验证
- zstd 会话解码需要 Node >= 22.15
- boot-probe 和 launch 依赖可用的 DSH 安装
- 完整验收步骤记录在 docs/ACCEPTANCE.md 中

路线图

P3
- 救援胶囊
- DSH 运行时回滚
- 会话修复

项目文档

- docs/dsh-recovery-design.md
- docs/dsh-recovery-research.md
- docs/ACCEPTANCE.md