dsh-safe-start

August 18, 2026 · View on GitHub

面向 DSH（DeepSeek Harness）新手的安全配置工具包：Skill + 脚本，让 agent 在配置/维护 dsh web 服务时"先想清楚再做"，崩了能自己修，不依赖人工救场。

背景：DSH 新手让 agent 自己装插件/改配置，最容易把服务装崩（pnpm 重构 node_modules 弄坏 node-pty、kill 进程断会话、皮肤叠加、坏 JSON……）。本工具包把这些真实事故反推成可执行的 SOP，用 Skill 给 agent 装上"刹车"，用脚本给服务配上"安全带"。

这是什么：这是一个 Skill + 脚本工具包，不是 dsh 插件。 它不通过 dsh plugin add 安装，也不需要进 node_modules；安装方式是运行 install.ps1 把 5 个 Skill 放入 $DSH_HOME/skills/ 并附赠 backup/rollback/watchdog/healthcheck 脚本，让 agent 自动获得"安全自配置 + 崩溃自愈 + 防呆"能力。

一、这是什么

组件	作用
`skills/`（5 个 Skill）	给 agent 的 SOP：新手总纲（dsh-beginner-self-config）、安全配置（dsh-safe-config）、崩溃自愈（dsh-crash-recovery）、手动装插件（dsh-plugin-install）、安全开发（dsh-plugin-dev）。装进 `$DSH_HOME/skills/` 后，会话自动加载
`templates/`	铁律模板（AGENTS.md）、pnpm 防坑模板（pnpm-workspace.yaml）、补丁示例（cordis.patch.yml）
`scripts/`	备份 backup、回滚 rollback、守护 watchdog（挂了自动拉起，可连崩自动回滚）、体检 healthcheck（一键四层验证），PowerShell + bash 双版本，零第三方依赖
`install.ps1 / install.sh`	一键安装：探测 `$DSH_HOME` → 复制 skills → 幂等合并 AGENTS.md → 可选注册 watchdog

核心方法论（三查三不碰）：

三查：查结构（package.json 的 bundle 声明/入口/依赖版本/scripts/files）、查构建（lib 是否发布/原生依赖/monorepo）、查激活（补丁行冲突/重复 service/slot 竞争/皮肤叠加）
三不碰：不碰 pnpm 安装命令、不碰运行中的 web 进程、不碰多皮肤/多冲突插件同时激活

设计目标：新手 agent 自助闭环——拿到任务先分类（装/改/修/开发）→ 走对应 Skill → 崩了先回滚再诊断 → 自愈后四层验证 → 告知用户可继续工作。全程不需要人工/其他 agent 救场。

二、3 步安装

Windows（PowerShell）

# 1. 进入工具包目录，右键"在终端中打开"（或 cd 过去）
cd dsh-safe-start

# 2. 安装（自动探测 $DSH_HOME；探测不到就手动指定）
.\install.ps1
# 或显式指定：
.\install.ps1 -DshHome F:\DSH\.dsh

# 3.（可选）注册 watchdog：服务挂掉后 10 秒内自动拉起
.\install.ps1 -RegisterWatchdog -WatchdogStartCommand "F:\DSH\启动脚本.cmd"

Linux / macOS（bash）

# 1. 进入工具包目录
cd dsh-safe-start

# 2. 安装
./install.sh
# 或指定 DSH_HOME：./install.sh -h "$HOME/.dsh"

# 3.（可选）注册 watchdog（crontab @reboot）
WATCHDOG_START_CMD='cd /opt/dsh && pnpm dsh web > dsh-web.log 2>&1' ./install.sh --cron

安装后立刻验证：

# 看 3 个 skill 是否就位
Get-ChildItem "$env:DSH_HOME\skills" | Select-Object Name
# 看 AGENTS.md 是否含受管块
Select-String -Path "$env:DSH_HOME\AGENTS.md" -Pattern "dsh-safe-start:begin"
# 试跑一次备份
& "$env:DSH_HOME\scripts\dsh-safe-start\backup.ps1"

安装是幂等的：重复运行会替换受管块而不是叠加，脚本/模板已存在且相同就跳过。被覆盖前会先备份成 .bak-<时间戳> 的文件：skills 的 SKILL.md 与 AGENTS.md（scripts/templates 用 -Force 覆盖时不自动备份，覆盖前请自行确认差异或先备份）。

三、日常使用

Skill（自动生效，不用手动调）

Skill	什么时候用	一句话内容
`dsh-beginner-self-config`	新手 agent 第一次自配置 dsh、或想完整走一遍	总纲：摸底→备份→分类→执行→验证→交差完整旅程 + 新手十大防呆 + 工具速查
`dsh-safe-config`	agent 要改配置/装插件/管皮肤/重启前	任务路由 + 三查三不碰 + 配置修改 SOP + 四层验证闭环 + 完成自检清单
`dsh-crash-recovery`	服务打不开/启动报错/插件加载失败	先回滚再诊断的应急原则 + 现象→诊断→修复→验证故障清单 + 恢复后继续工作
`dsh-plugin-install`	agent 要安装/卸载插件	环境前置检查 + 安装前检查清单 + 危险信号 + 手动复制流程 + 安装失败立即回滚
`dsh-plugin-dev`	用户让 agent "写个插件/工具/skill"	产物分层（L1 skill / L2 脚本 / L3 插件）+ 隔离开发 + 安全试装回滚闭环

脚本

# 备份当前配置（package.json / pnpm-workspace.yaml / cordis.patch.yml 快照到带时间戳目录）
& "$env:DSH_HOME\scripts\dsh-safe-start\backup.ps1"

# 列备份 → 一键还原（还原前自动先把当前状态存成 pre-rollback-*）
& "$env:DSH_HOME\scripts\dsh-safe-start\rollback.ps1" -List
& "$env:DSH_HOME\scripts\dsh-safe-start\rollback.ps1" -Latest
& "$env:DSH_HOME\scripts\dsh-safe-start\rollback.ps1" -Target dsh-safe-start-20260101-120000

# 一键健康体检：配置层 dump-config + 清单层 __DSH_BOOT__ + 加载层逐插件 client.js 全 200
# 默认自动保存基线到 %TEMP%\dsh-safe-start-healthcheck 并在下次对比（-NoBaseline 关闭）
& "$env:DSH_HOME\scripts\dsh-safe-start\healthcheck.ps1"
& "$env:DSH_HOME\scripts\dsh-safe-start\healthcheck.ps1" -ExpectedPlugin dsh-better-sidebar

# 安装/升级本工具包前先预演（-DryRun 只打印将执行的动作，零写入）
& "$env:DSH_HOME\scripts\dsh-safe-start\install.ps1" -DryRun

# 守护：10 秒轮询 3080，挂了自动拉起（防抖 60 秒，防重启风暴）
& "$env:DSH_HOME\scripts\dsh-safe-start\watchdog.ps1" -StartCommand "F:\DSH\启动脚本.cmd" -LogFile F:\DSH\watchdog.log

# 自愈守护：连崩 2 次（90 秒窗口内）自动回滚最近快照再拉起（需要 -DshHome）
& "$env:DSH_HOME\scripts\dsh-safe-start\watchdog.ps1" -DshHome "$env:DSH_HOME" -StartCommand "F:\DSH\启动脚本.cmd" -AutoRollback -LogFile F:\DSH\watchdog.log

# 单次健康检查（脚本里可用）：0 = 在线，1 = 挂
& "$env:DSH_HOME\scripts\dsh-safe-start\watchdog.ps1" -Once -CheckUrl http://127.0.0.1:3080/ -RequireBootToken

bash 对应 backup.sh / rollback.sh / watchdog.sh（含 -AutoRollback 等价物：AUTO_ROLLBACK=1 环境变量）/ healthcheck.sh（curl + node），全部已在 Ubuntu 24.04/WSL 实测，参数见脚本头部注释。

新手 agent 自助闭环（开发 → 安装 → 自愈 → 继续）

分类：新手/完整流程先读 dsh-beginner-self-config（总纲）；单项任务对号入座——装插件→dsh-plugin-install；改配置/皮肤→dsh-safe-config；崩了→dsh-crash-recovery；"写个插件/工具"→dsh-plugin-dev。
动手前：先备份（backup.ps1），一次只改一个点。
失败兜底：任何一步 dump-config 不过 → 立即回滚（rollback.ps1 -Latest -Yes），不猜着改。
完成后自检：逐项过 dsh-safe-config 第 5 节清单（备份在、验证过、重启方案明确、结果已告知）。
日常兜底：watchdog.ps1 -AutoRollback 让服务挂了能自愈；healthcheck.ps1 随时体检。

四、崩溃急救表（先看这张表，再动手）

现象	处理	详见
启动失败 `Cannot find package node-pty/index.js`	从同机完好副本（如 DSH-better-sidebar 的 node_modules）复制 node-pty 完整目录回 profile，删 `node-pty.broken`	dsh-crash-recovery 1.1
dump-config 报解析错误 / 服务秒退	用 write 工具整体重写坏 JSON/YAML（先 read 确认）	dsh-crash-recovery 1.2
启动日志有 Error / 重复注册	dump-config 找错、核对 dependencies 与 bundles 一致性；修不好就 rollback	dsh-crash-recovery 1.3
首次打开"插件加载失败"，过一会才好	冷启动未就绪窗口，就绪轮询等全部插件 client.js 200 再开；硬刷新 Ctrl+F5	dsh-crash-recovery 1.4
服务能开但某插件报加载失败	跑 `healthcheck.ps1`，看 L3 层哪个 client.js 非 200，对症处理	dsh-crash-recovery 1.4
样式错乱、皮肤互相覆盖	只保留一个皮肤（用户偏好为准），其余停用	dsh-crash-recovery 1.5
会话中断、服务挂起	由用户重启；绝不 kill web 进程（kill = 自杀）	dsh-crash-recovery 1.6
`ERR_PNPM_NO_MATCHING_VERSION`	`npm view <pkg> versions` 查实际版本，改 manifest	dsh-crash-recovery 1.7
插件装了不激活 / ENOENT cordis.patch.yml	从仓库源补漏打包文件；检查 dsh.bundle.patch 声明	dsh-plugin-install 2
大改动后崩了、根因不明	先 `rollback.ps1 -Latest -Yes` 回滚到最近良好状态，再诊断	dsh-crash-recovery 0.5

通用自愈顺序：备份 → 诊断（dump-config / 日志 / 端口）→ 最小修复 → 验证（dump-config 无错 → 首页有 __DSH_BOOT__ → 全插件 client.js 200）→ 征得用户同意再重启。

五、FAQ

Q：为什么绝不跑 pnpm install？ A：pnpm 会全量重构 node_modules，重装被运行中进程占用的 node-pty → 残缺目录 → 启动失败。本机真实事故：agent 跑 pnpm 装崩后要另一个 agent 救场。手动复制流程可控、可回滚。

Q：kill 一下 web 进程不就重启了吗？ A：agent 自己就跑在 web 上，kill 会中断会话、可能让服务挂起。需要重启：先改完文件 → 备份 → 验证 → 征得用户同意，由用户重启或用户明确授权。

Q：Skill 装在哪？会被升级覆盖吗？ A：装在 $DSH_HOME/skills/<name>/。部署自带的 skill 目录（升级会覆盖）不要动；本工具包装的是用户级目录，安全。

Q：watchdog 会自动重启吗？ A：注册后（Windows 计划任务 / crontab @reboot）随登录启动，10 秒轮询；检测到挂掉且距上次重启超过防抖时间（默认 60 秒）才拉起，防重启风暴。不配启动命令时只监控告警不重启。

Q：改坏了怎么办？ A：rollback.ps1 -Latest 一键还原到最近快照（还原前自动备份当前状态，双重保险）。日常改配置前养成跑 backup.ps1 的习惯。

Q：JSON 用 PowerShell 写行不行？ A：不行。PowerShell 的 `n 不转义、Set-Content -Encoding UTF8 写 BOM，都会破坏 JSON.parse。配置一律用 write 工具整体重写。

Q：支持哪些环境？ A：ps1 需要 PowerShell 5.1+ 或 pwsh；sh 需要 bash 4+（macOS 自带）。零第三方依赖：不装 npm 包、不需要 curl/nc（端口探测用 .NET / bash /dev/tcp）。

六、卸载

# 1. 删掉安装的 skill
Remove-Item "$env:DSH_HOME\skills\dsh-beginner-self-config", "$env:DSH_HOME\skills\dsh-safe-config", "$env:DSH_HOME\skills\dsh-crash-recovery", "$env:DSH_HOME\skills\dsh-plugin-install", "$env:DSH_HOME\skills\dsh-plugin-dev" -Recurse -Force
# 2. 从 AGENTS.md 删除受管块（begin/end 之间），或直接还原 .bak-* 备份
# 3. 删工具目录
Remove-Item "$env:DSH_HOME\scripts\dsh-safe-start" -Recurse -Force
# 4.（Windows）删除计划任务
Unregister-ScheduledTask -TaskName "dsh-safe-start-watchdog" -Confirm:$false

七、项目结构

dsh-safe-start/
├── skills/
│   ├── dsh-beginner-self-config/SKILL.md # 新手自配置总纲（完整旅程 + 十大防呆 + 工具速查）
│   ├── dsh-safe-config/SKILL.md      # 安全配置 SOP（任务路由、三查三不碰、验证闭环、自检清单）
│   ├── dsh-crash-recovery/SKILL.md   # 故障自愈 SOP（先回滚再诊断、现象→诊断→修复→验证、恢复后继续工作）
│   ├── dsh-plugin-install/SKILL.md   # 手动安装插件 SOP（环境前置检查 + 危险信号 + 失败即回滚）
│   └── dsh-plugin-dev/SKILL.md       # 安全开发 SOP（L1 skill / L2 脚本 / L3 插件分层 + 试装回滚闭环）
├── templates/
│   ├── AGENTS.md                     # 全局铁律模板（{{DSH_HOME}} 占位符，安装时替换）
│   ├── pnpm-workspace.yaml           # allowBuilds / minimumReleaseAge 防坑模板
│   └── cordis.patch.yml              # 安全补丁示例（insert/disabled/皮肤互斥）
├── scripts/
│   ├── backup.ps1 / backup.sh        # 配置快照（带时间戳目录 + SHA-256 清单）
│   ├── rollback.ps1 / rollback.sh    # 列备份 → 还原（还原前先备份当前）
│   ├── watchdog.ps1 / watchdog.sh    # 10s 轮询 3080，挂了自动拉起（防抖 + 日志；均可连崩自动回滚）
│   ├── healthcheck.ps1 / healthcheck.sh # 一键四层体检（dump-config / __DSH_BOOT__ / 插件 client.js 全 200）
├── install.ps1 / install.sh          # 一键安装（幂等）
├── README.md                         # 本文件
└── LICENSE                           # MIT

许可证

MIT License（见 LICENSE）。

本工具包借鉴了 DSH 官方生态（awesome-deepseek-harness、Oh-My-DSH）与真实运维事故经验；templates/cordis.patch.yml 中的补丁语义说明源自 dsh-base bundle 官方注释。