服务重启器hackerFish/dsh-restart

dsh-restart

启动、重启与排障本机 DeepSeek Harness（dsh）Web 服务 —— 一个工具，两个入口：对话内技能 + 系统级启动器。

CI
License
Platform

什么是 DeepSeek Harness（dsh）？

DeepSeek Harness（dsh）是面向 DeepSeek 工作流的本地智能体运行框架。它的 web profile 在本地端口（默认 3080）提供浏览器 UI，配置与会话数据存放在 $DSH_HOME（默认 ~/.dsh）下。

dsh 是常驻本地服务，每个人迟早都会遇到同样的运维问题："界面打不开 / 3080 端口被占 / 想重启"。dsh-restart 用两个互补的入口回答这些问题：

| 入口 | 适用场景 | 使用方式 |
|---|---|---|
| DSH 技能（skills/） | dsh 正在运行，对话内操作 | 说"start dsh / restart dsh"（中文"启动 dsh / 重启 dsh"亦可），模型用自己的工具执行整套流程 |
| 启动器（launch/） | dsh 未运行或需要兜底引导 | 双击 launch.vbs（Windows）或运行 launch.sh / launcher.js |

本技能同时收录于兄弟项目 awesome-dsh-skills。

目录

- 功能特性
- 仓库结构
- 工作原理
- 前置要求
- 快速开始
- 启动器参数
- 安全模型
- 故障排查
- 开发
- 贡献
- 许可证

功能特性

- 安全重启逻辑 —— 识别占用端口的进程；未经显式 --force，绝不杀死非 node/dsh 类进程。
- 会话保全 —— 服务健康时默认不重启、只打开浏览器，对话历史不丢失。
- 跨平台 —— Windows / macOS / Linux / Android（Termux），极简 Linux 环境有 /proc 兜底探测。
- 零依赖 —— 启动器仅用 Node.js 内置模块；技能是经过校验的纯 SKILL.md。
- 格式经校验 —— 内置技能通过 tools/validate-skills.mjs，CI 在 Ubuntu 与 Windows 上每次 push / PR 自动执行。
- dsh 宕机也能用 —— 与对话内操作不同，启动器不依赖正在运行的 dsh 实例。

仓库结构

dsh-restart/
├── skills/
│   └── dsh-restart/SKILL.md   # DSH 技能 —— 对话内入口
├── launch/
│   ├── launcher.js            # 跨平台核心启动器
│   ├── launch.vbs             # Windows：隐藏启动 + 自动开浏览器
│   ├── launch.bat             # Windows：控制台入口
│   └── launch.sh              # macOS / Linux / Termux 入口
├── tools/
│   └── validate-skills.mjs    # 零依赖技能格式校验器
├── CONTRIBUTING.md            # 贡献指南
└── .github/workflows/
└── validate.yml           # CI —— Ubuntu + Windows 双平台矩阵

工作原理

检查端口 3080
│
├─ 空闲 ──────────────────────────► 启动 dsh web ──► 轮询 ──► 打开浏览器
│
└─ 占用 ──► 识别进程
│
├─ 非 node/dsh ──► 中止（需 --force）
│
└─ node/dsh ──► 探测 http://127.0.0.1:3080/
│
├─ 健康 ──► 只开浏览器（不重启）
└─ 残留 ──► 终止 ──► 等待端口释放 ──► 启动

1. 检查默认端口 3080（可用 --port 或 DSH_PORT 覆盖）。
2. 识别占用进程；除非显式传入 --force，拒绝杀死非 node/dsh 类进程。
3. 探测服务 —— 响应正常意味着"直接打开浏览器"：重启会丢失当前会话。
4. 清理残留进程 —— 终止后等待端口释放，再启动 dsh web（优先本机安装，回退 npx -y @deepseek-ai/dsh）。
5. 验证 —— 轮询直到界面有响应，再打开浏览器。

前置要求

- Node.js —— 启动器与 dsh 本身都需要。
- dsh —— 启动器会通过本机安装或 npx -y @deepseek-ai/dsh 启动（首次使用需联网）。
- 无其他依赖。

快速开始

方式 A —— 安装技能（对话内使用）

git clone https://github.com/hackerFish/dsh-restart.git
mkdir -p ~/.dsh/skills
cp -r dsh-restart/skills/* ~/.dsh/skills/

技能目录在会话启动时扫描 —— 开一个新会话，然后说 "启动 dsh" 或 "重启 dsh"。

方式 B —— 使用启动器（兜底引导）

Windows
launch\launch.vbs            # 双击，或在终端里：
node launch\launcher.js

macOS / Linux / Termux
./launch/launch.sh
node launch/launcher.js

可选 —— 桌面快捷方式（Windows）

为 launch\launch.vbs 创建快捷方式。双击即可隐藏启动 dsh 并自动打开浏览器。

启动器参数

| 参数 | 说明 |
|---|---|
| --dry-run | 只检查端口/进程状态，不启动任何东西。 |
| --force | 强制杀死占用端口的非 node/dsh 进程 —— 使用前务必确认。 |
| --port  | 覆盖监听端口（默认 3080）。 |
| --  | 透传给 dsh 的其余参数，如 -- web --port 4000。 |
| DSH_PORT | 与 --port 等效的环境变量。 |

安全模型

- 启动器绝不杀死看起来不像 node/dsh/deno/bun 的进程，除非传入 --force。
- 健康运行的实例默认不重启，只打开浏览器。
- 重启 dsh 会终止当前对话所在进程；技能在执行前会明确警告用户。
- 技能除进程管理与打开界面外不产生任何副作用。

故障排查

| 症状 | 处理 |
|---|---|
| 3080 端口被未知进程占用 | node launch/launcher.js --dry-run 先检查；确认后再决定是否 --force。 |
| 3080 被其他应用占用 | node launch/launcher.js --port 8080。 |
| dsh 起来了但界面打不开 | dsh web --help；dsh web --port 0 让系统分配空闲端口。 |
| 对话里技能不触发 | 确认技能已放入发现根（~/.dsh/skills 或项目 .dsh/skills）；需新会话生效。 |

开发

node tools/validate-skills.mjs    # 校验内置技能（零依赖）
node launch/launcher.js --dry-run # 启动器自检（只检查，不启动）

CI（.github/workflows/validate.yml）在每次 push / PR 时于 Ubuntu 与 Windows 双平台运行校验器，平台相关的路径问题在合并前就会被拦截。

贡献

见 CONTRIBUTING.md。

许可证

MIT © 2026 dsh-restart contributors