前言¶
DSH 的擴展能力依賴大量第三方插件組合而成。一個插件包缺失、cordis.patch.yml 中的條目失效、client 產物不可用，或者宿主插件在啓動階段拋出運行時錯誤，都可能在啓動時把 dsh web 卡住。
dsh-startup-guard 是一個面向 DeepSeek Harness 的啓動守衛插件。它在啓動前檢查會話日誌、插件清單、bundle 解析、patch 組合、client 產物和宿主 apply()，把可修復的問題先處理掉，並把高風險插件隔離起來。
這是什麼¶
dsh-startup-guard 由 aokamoaki 維護，許可證爲 MIT。
它的一句話定位是：在啓動前修復會話日誌、預檢插件組合、執行宿主插件冒煙測試，並隔離崩潰源，避免「插件損壞 / 日誌損壞」把 DSH 卡死在啓動。
這個插件不是替代 DSH 本身，而是在 DSH 插件體系內提供一個啓動前檢查與兜底層。
核心功能¶
下面介紹它已覈實的幾項能力。
會話日誌修復¶
它可以修復 session.jsonl[.zstd] 中的 seq 損壞、torn 尾幀和過期緩存，並在修復前備份原件。
適合的場景是：本地 ~/.dsh 中的會話日誌已經出現異常，但不想直接刪除整份日誌，先做一次可回溯的修復。
插件清單與源碼快照¶
它會爲 profile 的 package.json、cordis.patch.yml、pnpm 清單以及 link 插件源碼生成快照，並記錄 host/client/patch 指紋。
這一步的作用是把當前插件組合固定下來，後續回滾或排查時有可比較的基線。
bundle 預檢與回滾¶
它會校驗第三方 bundle 目錄是否可解析。缺失時會回滾到可解析快照，並把壞清單另存爲 package.json.broken。
這適合處理插件包安裝後目錄不完整、路徑解析失敗、或 package.json 與真實 bundle 不一致的問題。
組合預檢與自動禁用¶
它會檢測 entry id 重複、name 不可解析和 YAML 致命形態。
對 name 失效的 row，它可以自動禁用；在 strict 模式下，會寫塊標記並讓啓動器拒絕啓動。
client 產物校驗¶
它會校驗 client 產物中的 exports['./client'] 與 __ModuleLoader__.load 註冊，並在 vm 沙箱中執行加載，同時檢測重複 client id。
這一步針對的是“插件能安裝，但 client 產物不可用”的情況。
宿主 apply() 冒煙¶
它會在子進程和 mock Cordis 環境中執行第三方插件的 apply()，識別啓動即拋出的錯誤，並按指紋緩存結果。
這一步用於發現宿主插件在啓動早期就拋異常的運行時問題。
崩潰隔離¶
它會基於崩潰標記或啓動標記觸發全量冒煙。是否自動禁用冒煙失敗插件，還要看崩潰標記是否在場、插件是否顯式聲明 smoke 爲 true，或是否屬於客戶端產物損壞。
這個機制在純 dsh web 場景下也會生效。
安裝與啓用¶
先安裝插件：
dsh plugin --profile web add dsh-startup-guard
如果要從 GitHub 源碼安裝，可以用：
dsh plugin --profile web add github:aokamoaki/dsh-startup-guard
安裝後，重啓 dsh web 即自動生效。
運行環境方面，package.json 要求 Node >=22.13，並聲明 peerDependency：
"@deepseek-ai/cordis": "^4.0.1"
配置文件位於：
~/.dsh/dsh-startup-guard.json
該配置可選，缺省使用默認值。
模式包含 report、fix 和 strict，其中 fix 是默認模式；strict 會寫塊標記並讓啓動器拒絕啓動。
典型用法¶
首次啓動¶
首次啓動後，它會執行以下動作：
1、掃描並修復會話日誌；
2、快照當前插件清單；
3、執行宿主冒煙和客戶端校驗；
4、寫入運行報告。
報告文件位於：
~/.dsh/dsh-preflight-report.json
本地幹跑¶
如果只是想看檢查結果，可以先運行：
node guard-sessions.mjs --dry-run
如果要在 strict 模式下檢查：
node guard-sessions.mjs --mode strict
調用核心入口¶
它也可以通過核心 API 調用：
import { runGuard } from 'dsh-startup-guard/lib/guard-core.mjs';
const r = await runGuard(home, { dryRun: true });
runGuard 是核心入口，傳入 home 目錄和運行參數，返回本次 guard 的執行結果。
運行數據與恢復¶
運行數據會寫入 ~/.dsh，包括：
dsh-preflight.log
dsh-preflight-state.json
dsh-preflight-report.json
dsh-crash-state.json
dsh-boot-state.json
dsh-preflight-block.json
repair-backups/
plugin-snapshots/
其中，repair-backups/ 用於保存修復或禁用前的原文件備份；plugin-snapshots/ 用於保存插件清單和源碼快照。
如果發生誤禁用，可以刪除對應 profile 的 cordis.patch.yml 中的 disabled 條目。原 patch 已備份到 repair-backups/。
自動禁用策略¶
這裏需要注意它的禁用邊界：
1、單獨的冒煙失敗不會自動禁用；
2、崩潰標記在場，且冒煙失敗時，對應插件可被自動禁用；
3、插件顯式聲明 smoke 爲 true 時，冒煙失敗可被自動禁用；
4、客戶端產物損壞則照常自動禁用。
這個策略比較謹慎：冒煙跑在 mock 環境，失敗既可能是真實錯誤，也可能是插件依賴真實 DSH 服務導致的環境缺口。
適用場景與注意¶
適合以下使用者：
1、日常維護 dsh web profile 的人；
2、組合多個第三方 DSH 插件的開發者；
3、希望把會話日誌損壞、patch 失效、bundle 解析失敗、client 產物問題從“啓動即崩”變成“啓動前檢查 + 可回滾”的人。
使用前需要確認：
1、許可證爲 MIT；
2、README 聲明與 DeepSeek 官方無關；
3、插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證；
4、不要把它理解成 DSH 官方應用商店或官方發行渠道的一部分；
5、目錄頁 URL 未在已覈實資料中確認，建議以 GitHub 倉庫爲準。
鏈接¶
GitHub 倉庫：
https://github.com/aokamoaki/dsh-startup-guard
安裝命令：
dsh plugin --profile web add dsh-startup-guard
