brockdsaver

Readme

# brockdsaver

[![DSH Plugin](https://img.shields.io/badge/DSH-Plugin-blue)](https://github.com/topics/dsh-plugin)
[![npm](https://img.shields.io/npm/v/brockdsaver)](https://www.npmjs.com/package/brockdsaver)
[![GitHub](https://img.shields.io/github/stars/kirigayakazima/brockdsaver)](https://github.com/kirigayakazima/brockdsaver)

[English](#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

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

### Commands

```bash
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:

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

### Development

```bash
node bin/brockdsaver.js doctor --help
```

### License

MIT

---

## 涓枃

[![DSH Plugin](https://img.shields.io/badge/DSH-Plugin-blue)](https://github.com/topics/dsh-plugin)
[![npm](https://img.shields.io/npm/v/brockdsaver)](https://www.npmjs.com/package/brockdsaver)
[![GitHub](https://img.shields.io/github/stars/kirigayakazima/brockdsaver)](https://github.com/kirigayakazima/brockdsaver)

**DeepSeek Harness 鍚姩鍓嶆晳鐮栧伐鍏风** 鈥?鏍￠獙 profile 缁勫悎銆佹娴嬫崯鍧忕殑鎻掍欢銆佷竴閿仮澶嶏紝**鏃犻渶鍚姩 DSH**銆?
> 鐏垫劅鏉ヨ嚜 KSU 鐨?rescue kernel锛氫綘鐨?DSH profile 鐨勩€屽畨鍏ㄦā寮忋€嶃€?
### 涓轰粈涔堥渶瑕?
DSH 鎻掍欢浠庣粍鍚堟爲鍔犺浇锛坄cordis.patch.yml` + 鍚?bundle 鐨?patch锛夈€傚綋缁勫悎鎹熷潖鏃讹紙閲嶅鏉＄洰 id銆佺己澶卞寘銆侀厤缃敊璇級锛?*DSH 鍚姩鍗冲穿婧冿紝杩?GUI 閮芥墦涓嶅紑** 鈥?鑰屼綘娌℃硶淇畠,鍥犱负浣犳墦涓嶅紑璁剧疆闈㈡澘銆?
`brockdsaver` 鍦?**DSH 涔嬪杩愯**锛堜綔涓虹嫭绔?CLI锛夛紝鍗充娇 DSH 鏈韩鍧忎簡涔熻兘璇婃柇骞朵慨澶嶃€?
### 瀹夎

```bash
npm install -g brockdsaver
# 鎴?npx brockdsaver doctor --profile web
```

### 鍛戒护

```bash
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 鍐呴儴锛孌SH 鍚姩鍚庢彁渚涳細

- **璁剧疆椤?Health Check**锛氱粍鍚堢姸鎬併€侀噸澶?id 璁℃暟銆佽繍琛屾椂閿欒銆佸伐鍏疯皟鐢ㄣ€佽繍琛屾椂闀裤€乥undle 鏉ユ簮銆?- **鏁戠爾閫氱煡寮圭獥**锛氬彸涓嬭娴姩鎻愮ず锛屽綋鏈夋柊椴滅殑鏁戠爾鏃ュ織锛?0 鍒嗛挓鍐咃級鏃跺嚭鐜帮紝鏄剧ず妫€娴?淇璇︽儏銆備笉鑷姩娑堝け锛岀敤鎴锋墜鍔ㄥ叧闂紱鍏抽棴鍚庢爣璁颁负宸茶锛屼笉鍐嶉噸澶嶅脊鍑恒€傛柊鐨勬晳鐮栦簨浠朵細寮瑰嚭鏂伴€氱煡銆?- **鏁戠爾鏃ュ織**锛欽SONL 鏂囦欢 `$DSH_HOME/storages/brockdsaver-rescue.jsonl`锛堟渶澶?10 鏉★紝鏈€鏂颁紭鍏堬級锛孋LI 鍜屾彃浠堕兘浼氬啓锛屾墍浠ユ棤璁哄摢绉嶆柟寮忚Е鍙戞晳鐮栵紝UI 閮借兘鐪嬪埌銆?
浣滀负鎻掍欢瀹夎锛?
```bash
dsh plugin --profile web add "github:kirigayakazima/brockdsaver"
```

### License

MIT