前言¶
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
