dsh-ops

August 17, 2026 · View on GitHub

配套插件 dsh-ops-health 已被社区主列表 Awesome DeepSeek Harness Plugin 收录

给 AI 代理：如果你正在协助维护 dsh（DeepSeek Harness）部署，请先读 runbook.md 和 docs/diagnosis-table.md，优先使用 scripts/ 里的脚本，而不是从头探索式排查。如果所有工具调用都在约 1 毫秒内崩溃（prepare / undefined），那是宿主级故障： 立即停止在 dsh 内部排查，改用独立脚本（见 runbook 第 3 节）。

面向 DeepSeek Harness (dsh) Windows 部署的独立运维工具集，无需 AI、纯本地脚本、0 token。

诞生于一次真实事故（2026-08-15）：一个损坏的第三方主题 + 重复的插件行 + 重复安装的核心包，导致所有 dsh 会话崩溃（宿主级 prepare 崩溃），而 dsh 自身无法自诊断。

核心认知：宿主级故障会让每个 dsh 会话全部倒下，所以工具必须不依赖 dsh 就能运行—— 纯 PowerShell，零 token，零 AI。

功能

工具	作用	成本
`fix-service.ps1`	智能一键修复：从最新快照往回逐个还原 + 自动重启 + 自动体检，找到第一个健康状态停下（保住中间改动）；动手前先把现场存为 `pre-fix-*`	0 token
`restore-known-good.cmd`	快速回退到最近一次全绿快照（`known-good-auto`，由每次全绿体检自动刷新）	0 token
`check-health.ps1`	8 项体检：端口、HTTP、启动清单中的期望包、组合树重复行、核心包双份、备份纪律、静态 lint（`main` 引用浏览器全局的包）。每次运行追加到 `<dsh>/logs/health-history.log`；全绿时自动刷新 known-good-auto 快照	0 token
`backup-config.ps1`	快照 profile 配置（cordis.yml / cordis.patch.yml / package.json / pnpm-workspace.yaml / settings.yaml）+ 包清单 → `<dsh>/backups/<时间戳>/`	0 token
`restore-snapshot.ps1`	从快照还原配置（带确认）	0 token
`list-snapshots.ps1`	列出快照（文件数、创建时间）	0 token
`diff-snapshot.ps1`	对比两个快照的配置差异（审计"改了什么"）	0 token
`restart-service.ps1`	服务未运行则启动；验证端口和 HTTP 200	0 token
`watchdog.ps1`	计划任务用静默看门狗；配置健康才重启（连续 2 次失败停止重试并提示还原快照）	0 token
`watch-config.ps1`	配置一变就自动快照（轮询+防抖，留 20 份）+ 审计日志 `<dsh>/logs/config-watch.log`	0 token
`audit-ops.ps1`	项目自检：PS 语法 / cmd 引用完整性 / 控制台中文乱码风险 / 密钥模式 / check-health 副本漂移	0 token
`runbook.md`	铁律、标准流程、症状→排查对照表	—

双击友好的 .cmd 入口在 cmd/ 目录。

快照体系（三层防线）

层	谁在更新	用途
`auto-<时间戳>`	`watch-config.ps1` 每次配置变动自动拍（留 20 份）	逐级回退的原料
`known-good-auto`	`check-health.ps1` 每次全绿自动刷新	快速回退的安全基准
`known-good-<日期>`	手动（`backup-config.ps1 -Name`）	人工确认的里程碑

双击友好的 .cmd 入口在 cmd/ 目录。

DSH 插件：dsh-ops-health（独立仓库）

浏览器/桌面壳里点一下就能体检，不用切 PowerShell。插件源码在独立仓库 MiraculousGarfield/dsh-ops-health （本仓库不再维护 plugin/ 副本，避免双份漂移）。

侧边栏「🩺 健康检查」按钮 → 纯 HTTP 路由 /ops/health → 隐藏窗口跑 check-health.ps1 → 结构化报告卡片（✓/✗ 逐项 + 总结 + 处置提示）
按钮配色跟随主题：取 --dsw-alias-brand-primary（DSH 主题品牌色，皮肤覆盖时自动跟随皮肤），不依赖主题服务，任何主题/皮肤下都协调
路由直接注册在 webServer 上，不经过工具注册表：agent 工具调用崩了（宿主级故障以外的形态）按钮仍可用；进程级故障时按钮同样不可用，兜底仍是本仓库的独立脚本
本机安装姿势（手册铁律）：包复制到 <profile>\node_modules\dsh-ops-health，在 cordis.patch.yml 插入 - insert: [{id: ops-health, name: 'dsh-ops-health'}]，重启服务生效。不要用 github 依赖 + bundle 注册：bundle 一旦注册就绝不能删包目录（cannot resolve profile bundle 会让服务拒绝启动）

安装与部署

dsh-ops 刻意免安装：克隆到任意位置直接运行（所有路径自动探测）。唯一可选的安装是 配置监听自动启动：

# 1. 克隆到任意位置（推荐 %USERPROFILE%\.dsh\ops\）
git clone https://github.com/MiraculousGarfield/dsh-ops.git

# 2. （可选）注册 watch-config 登录自启 —— 零窗口（VBS）
powershell -NoProfile -ExecutionPolicy Bypass -File install.ps1

# 卸载
powershell -NoProfile -ExecutionPolicy Bypass -File install.ps1 -Uninstall

说明：

install.ps1 通过用户 Startup 文件夹注册自启（无需管理员权限、VBS 零窗口包装、无控制台闪烁），并立即启动监听；-Uninstall 移除
watch-config.ps1 只保留最近 20 份自动快照（-MaxAutoSnapshots）；手动快照（known-good-*、带时间戳备份）永不清理
系统级看门狗刻意不安装：大多数场景不需要 dsh 服务 24 小时常驻——桌面壳或手动 restart-service.ps1 已足够；如确实需要，可自行把 scripts\watchdog.ps1 注册为计划任务（它静默运行、只写日志）

快速开始

# 一键体检
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\check-health.ps1

# 自定义 profile / 端口 / 期望主题包
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\check-health.ps1 -Profile web -Port 3080 -ExpectTheme <你的主题包名>

# 任何配置改动前先备份
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\backup-config.ps1

# 从快照还原
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\restore-snapshot.ps1 -Snapshot known-good-20260815

# 服务未运行则重启
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\restart-service.ps1

自动发现（无需配置）

DSH home：$env:DSH_HOME 或 %USERPROFILE%\.dsh
dsh 启动器：$env:DSH_BIN 覆盖，其次 %LOCALAPPDATA%\npm-cache\_npx 下的 npx 缓存，再其次 <dsh>\profiles\node_modules
node.exe：PATH，其次标准安装位置

安全铁律（完整版见 `runbook.md`）

永远不要在 dsh profile 里 pnpm add 随意包——可能拉入重复核心包，让所有会话崩溃。
永远不要 insert 一个已经在 dsh.profile.bundles 里的插件行（重复条目）。
主题/插件包：main 必须是合法的服务端入口；浏览器代码只能通过 exports["./client"] + dsh.client 元数据暴露。绝不要把 main 指向浏览器脚本。
每次改动前备份（backup-config.ps1），改动后体检（check-health.ps1）。

环境要求

Windows（PowerShell 5.1+、netstat、powershell.exe）
Node.js 在 PATH 上（仅组合树查重和重启服务需要）

文档

runbook.md — 铁律与标准流程
docs/diagnosis-table.md — 症状 → 先查什么
docs/case-study-2026-08-15.md — 事故复盘（匿名化），也是本工具的缘起

License

MIT

功能