🛡️ dsh-startup-guard

简体中文 | English

DeepSeek Harness 启动守卫 —— 在启动前修复会话日志、预检插件组合、执行宿主插件冒烟测试并隔离崩溃源，让「插件损坏 / 日志损坏」再也无法把 DSH 卡死在启动。

📖 简介

DSH 的功能由大量第三方插件组合而成：某个插件包缺失、patch 语法损坏、client 产物未构建、甚至宿主 apply() 抛一个运行时异常，都可能让整个应用启动即崩。dsh-startup-guard 在启动早期异步执行七道检查，能自动修复 / 回滚 / 隔离问题源——它是「解析 → 组合 → 执行 → 崩溃兜底」的四层防线，而不仅仅是一组文件检查。

安装后零配置即生效，日常开销 < 0.5s。

✨ 核心能力

🚀 快速开始

dsh plugin --profile web add dsh-startup-guard          # npm（预构建，免构建授权）
# 或从源码安装：
dsh plugin --profile web add github:aokamoaki/dsh-startup-guard

已发布到 npm：dsh-startup-guard@1.0.0（npm 页面）。

重启 dsh web 后自动生效。首次启动会：

1. 扫描并（如有需要）修复会话日志；
2. 快照当前插件清单；
3. 对每个第三方插件做一次宿主冒烟 + 客户端校验；
4. 把结果写入 ~/.dsh/dsh-preflight-report.json 供你查看。

⚙️ 模式与配置

配置文件：~/.dsh/dsh-startup-guard.json（缺省使用默认值）。

{
  "mode": "fix",
  "smoke": true,
  "smokeTimeoutMs": 15000,
  "clientVmCheck": true,
  "clientFactorySmoke": false,
  "quarantineOnCrash": true,
  "autoRepairComposition": true,
  "tornTailGraceMs": 300000,
  "keepSnapshots": 10,
  "exclude": ["some-bundle-i-trust"]
}

🛡️ 自动禁用的安全策略

冒烟跑在 mock 环境，失败可能是真实 bug，也可能是插件依赖真实 DSH 服务的环境缺口。因此：

• 单独的冒烟失败不会自动禁用（只写入报告与 fixNeeded）；
• 上次启动确实崩溃过（崩溃标记在场）→ 冒烟失败插件自动禁用；
• 插件显式声明 "dsh": { "smoke": true } → 冒烟失败自动禁用；
• 插件声明 "dsh": { "smoke": false } 或在 exclude 中 → 跳过冒烟；
• 客户端产物损坏（解析类检查）→ 照常自动禁用。

误禁用时，删除 profile cordis.patch.yml 里对应的 - id: "xxx" / disabled: true 条目即可（原 patch 已备份到 repair-backups/）。

🗂️ 数据位置

~/.dsh/
├── dsh-preflight.log            # 运行日志（超阈值自动轮转 .old）
├── dsh-preflight-state.json     # 扫描状态 + 冒烟指纹缓存
├── dsh-preflight-report.json    # 每次运行的机器可读摘要
├── dsh-crash-state.json         # 崩溃标记（启动器/桌面应用写入，guard 消费后删除）
├── dsh-boot-state.json          # 启动标记（宿主插件写入、正常关闭清除；异常退出时作为崩溃证据）
├── dsh-preflight-block.json     # strict 模式拦截标记（启动器读取）
├── dsh-startup-guard.json       # 配置（可选）
├── repair-backups/              # 修复/禁用前的原文件备份
└── plugin-snapshots/            # 清单 + link 源码 + 指纹快照

🔌 集成

guard 有三个入口，任一崩溃场景都有兜底；纯 web（不经任何外壳直接 dsh web）也具备崩溃隔离——宿主插件自写启动标记，上次启动未正常结束即视为崩溃：

1. 桌面客户端（dsh-desktop-app）：spawn server 前以子进程运行 guard-runner.mjs；server 崩溃时写崩溃标记，正常退出清除启动标记
2. Web 启动器（dsh-launcher.ps1）：启动循环内调用 guard-sessions.mjs；崩溃时写标记；发现 strict 块标记则拒绝启动并弹窗；正常停止清除启动标记
3. 宿主插件：dsh web 启动早期异步执行；写/清启动标记，并据启动标记触发隔离

CLI：

node guard-sessions.mjs                # fix 模式
node guard-sessions.mjs --dry-run      # 只报告，不修改任何文件
node guard-sessions.mjs --mode report  # 同 dry-run
node guard-sessions.mjs --mode strict  # fix + strict 拦截

核心 API：

import { runGuard } from 'dsh-startup-guard/lib/guard-core.mjs';
const r = await runGuard(home, { dryRun: true });
// r: { repaired, rolledBack, autoDisabled, broken, hostBroken,
//      smokeUnresolved, issues, fixNeeded, blocked, crash, lines, ... }

🛠️ 开发

dsh-startup-guard/
├── lib/
│   ├── index.js          # 宿主入口（fire-and-forget，动态 import）
│   └── guard-core.mjs    # 核心：runGuard + 全部检查
├── test/guard-core.test.mjs  # 73 个用例（node:test，mock home，零依赖）
├── cordis.patch.yml      # bundle 注册
└── package.json

npm test                          # node --test（73 个用例）
node guard-sessions.mjs --dry-run # 对真实 home 干跑（只读）

设计原则：

• fire-and-forget：守卫自身失败只写日志，绝不抛进启动流程；
• 原子写：所有文件修改均 tmp+rename，中途崩溃不留半写文件；
• 优雅降级：会话解码器缺失时只跳过会话扫描，其余检查照常；
• 单实例锁：dsh-preflight.lock 串行化多个入口，避免并发写竞态。

📄 许可

MIT

DeepSeek Harness 社区插件，与 DeepSeek 官方无关。