brockdsaver

English · 中文

English

Pre-boot rescue toolkit for DeepSeek Harness — validates profile composition, detects broken plugins, and provides one-click recovery without starting DSH.

Inspired by KSU's rescue kernel: the "safe mode" for your DSH profile.

Why?

DSH plugins are loaded from a composition tree (cordis.patch.yml + bundle patches). When a composition is broken (duplicate entry id, missing package, bad config), DSH crashes on startup and you can't even open the GUI — and you can't fix it because you can't open the settings panel.

brockdsaver runs outside of DSH (as a standalone CLI), so it can diagnose and fix compositions even when DSH itself is broken.

Install

npm install -g brockdsaver
# or
npx brockdsaver doctor --profile web

Commands

brockdsaver doctor   [--profile <name>]  Validate composition and detect broken plugins
brockdsaver recover  [--profile <name>]  Backup + attempt to fix by disabling problematic rows
brockdsaver backup   [--profile <name>]  Backup cordis.patch.yml and package.json
brockdsaver restore  [--profile <name>]  Restore from the most recent backup

Default profile is web. Use --profile tui for the TUI profile.

Requirements

doctor and recover run dsh --dump-config under the hood, which requires writing a temporary cordis.yml to the profile directory. Stop the DSH server first (dsh web → Ctrl+C) before running doctor or recover, otherwise the file may be locked by the running server.

backup and restore work anytime — they copy/restore cordis.patch.yml and package.json without touching cordis.yml.

What it detects

• Duplicate entry ids (e.g. a bundle patch and a user patch both insert the same id — the #1 cause of startup crashes)
• Unparseable compositions (broken YAML, invalid config)
• Disabled entries (reported for awareness)

Recovery flow

brockdsaver doctor
  → detects duplicate id "usage-vendor-stats"
  → recommended: run "brockdsaver recover"

brockdsaver recover
  → backs up config to .brockdsaver-backup-2026-08-16T01-30/
  → auto-disables the duplicate row in cordis.patch.yml
  → user runs "dsh web" — DSH starts normally

brockdsaver doctor
  → ✓ composition healthy

DSH Plugin Mode (dual-mode)

brockdsaver also runs inside DSH as a bundle plugin (declares dsh.bundle), so once DSH boots it provides:

• Health Check page in Settings — composition status, duplicate-id count, runtime errors, tool calls, uptime, bundle sources.
• Rescue notification banner — bottom-right toast appears when a fresh rescue event is logged (within 10 minutes), with details of what was detected/fixed. It stays until dismissed; dismissing marks that event as read so it does not reappear. A new rescue event shows a new banner.
• Rescue log — JSONL at $DSH_HOME/storages/brockdsaver-rescue.jsonl (max 10 entries, newest first), written by both the CLI and the plugin so a rescue triggered either way is visible in the UI.

Install as a plugin:

dsh plugin --profile web add "github:kirigayakazima/brockdsaver"

Development

node bin/brockdsaver.js doctor --help

License

MIT

中文

DeepSeek Harness 启动前救砖工具箱 — 校验 profile 组合、检测损坏的插件、一键恢复，无需启动 DSH。

灵感来自 KSU 的 rescue kernel：你的 DSH profile 的「安全模式」。

为什么需要

DSH 插件从组合树加载（cordis.patch.yml + 各 bundle 的 patch）。当组合损坏时（重复条目 id、缺失包、配置错误），DSH 启动即崩溃，连 GUI 都打不开 — 而你没法修它,因为你打不开设置面板。

brockdsaver 在 DSH 之外运行（作为独立 CLI），即使 DSH 本身坏了也能诊断并修复。

安装

npm install -g brockdsaver
# 或
npx brockdsaver doctor --profile web

命令

brockdsaver doctor   [--profile <名称>]  校验组合、检测损坏的插件
brockdsaver recover  [--profile <名称>]  备份 + 自动修复（禁用问题行）
brockdsaver backup   [--profile <名称>]  备份 cordis.patch.yml 和 package.json
brockdsaver restore  [--profile <名称>]  恢复到最近一次备份

默认 profile 是 web。

检测能力

• 重复条目 id（如 bundle patch 和 user patch 都 insert 同一个 id —— 这是启动崩溃的首要原因）
• 无法解析的组合（坏 YAML、无效配置）
• 已禁用条目（显示出来供确认）

修复流程

brockdsaver doctor
  → 检测到重复 id "usage-vendor-stats"
  → 建议: 运行 "brockdsaver recover"

brockdsaver recover
  → 备份配置到 .brockdsaver-backup-2026-08-16T01-30/
  → 自动在 cordis.patch.yml 中禁用重复行
  → 用户运行 "dsh web" — DSH 正常启动

brockdsaver doctor
  → ✓ 组合健康

DSH 插件模式（双形态）

brockdsaver 也作为 DSH bundle 插件（声明 dsh.bundle）运行在 DSH 内部，DSH 启动后提供：

• 设置页 Health Check：组合状态、重复 id 计数、运行时错误、工具调用、运行时长、bundle 来源。
• 救砖通知弹窗：右下角浮动提示，当有新鲜的救砖日志（10 分钟内）时出现，显示检测/修复详情。不自动消失，用户手动关闭；关闭后标记为已读，不再重复弹出。新的救砖事件会弹出新通知。
• 救砖日志：JSONL 文件 $DSH_HOME/storages/brockdsaver-rescue.jsonl（最多 10 条，最新优先），CLI 和插件都会写，所以无论哪种方式触发救砖，UI 都能看到。

作为插件安装：

dsh plugin --profile web add "github:kirigayakazima/brockdsaver"

License

MIT