jinkang19940922/deepseek-harness-launcher

dshctl — DSH Web 管理工具

管理 git 源码部署的 DeepSeek Harness（dsh web）。

- Windows 版：dshctl.bat（纯批处理，本文档主体所述）
- Ubuntu / Linux 版：dshctl.sh（bash，功能对齐，见文末「Ubuntu / Linux 版」章节）
- 当前版本：v0.2.0（新增 Ubuntu/Linux 版；版本与变更明细见 CHANGELOG.md）

- 源码位置：D:\DSH\deepseek-harness
- 默认端口：3080
- 默认代理：http://192.168.10.222:37890

使用方式

方式一：交互菜单 —— 双击 dshctl.bat，按数字选择操作。

方式二：命令行（cmd 或 PowerShell 中调用）：

dshctl.bat start               启动 dsh web
dshctl.bat proxy               带代理启动（用配置的代理地址）
dshctl.bat proxy [URL] [端口]  指定代理地址 / 端口（仅当次生效）
dshctl.bat setproxy            查看当前代理地址
dshctl.bat setproxy [URL]      保存自定义代理地址（持久化，之后 proxy 启动生效）
dshctl.bat setproxy clear      恢复默认代理地址
dshctl.bat stop                停止 dsh web
dshctl.bat restart             重启 dsh web
dshctl.bat status              运行状态（PID / 健康检查 / 日志位置）
dshctl.bat autostart           安装开机自启（默认常规启动）
dshctl.bat autostart proxy      安装开机自启（带代理启动）
dshctl.bat autostart-remove    卸载开机自启（常规/代理方式均可直接卸载）
dshctl.bat update              一键更新升级（自动识别分支 / 标签方式）
dshctl.bat update -y           同上，跳过确认（适合脚本调用）
dshctl.bat update -y 3099      指定端口并跳过确认
dshctl.bat install             一键安装（git 克隆源码 + 装依赖 + 构建 Web）
dshctl.bat install D:\DSH\dsh  安装到指定目录（默认用脚本顶部 DSH_DIR）
dshctl.bat uninstall           一键无残留卸载（会先列出影响清单并要求确认）

端口参数可省略（默认 3080）：dshctl.bat start 3099。

交互菜单中选 [6] 安装开机自启 会先弹出子菜单，选择 常规启动 或 带代理启动 后执行安装；卸载开机自启无需选择，直接卸载。

交互菜单中选 [8] 设置代理地址 可查看/修改自定义代理：输入新地址保存，输入 0 恢复默认，直接回车取消。

交互菜单中选 [9] 一键更新升级 会先显示更新计划（当前版本 / 目标版本 / 是否落后），输入 Y 才开始停止服务并更新；输入其他任意键取消。

交互菜单中选 [10] 安装 / 卸载 DSH 会弹出子菜单：[1] 安装（git 克隆源码部署）、[2] 卸载（一键无残留清理）、[0] 返回主菜单。卸载会先打印完整影响清单并要求输入 Y 确认。

功能说明

| 功能 | 说明 |
|---|---|
| 启动 | 在源码目录后台启动 node --import tsx/esm apps/cli/src/bin.ts web --port N，日志落盘，等待健康检查通过 |
| 代理启动 | 注入 HTTP_PROXY/HTTPS_PROXY/ALL_PROXY/NO_PROXY/NODE_USE_ENV_PROXY 后启动；代理地址优先级：命令行参数 > 自定义（setproxy 保存）> 脚本默认 |
| 设置代理 | 查看/保存/清除自定义代理地址，持久化到 %USERPROFILE%\.dsh-ctl\proxy.txt；菜单选 8 交互设置，命令行 setproxy [URL] / setproxy clear |
| 一键更新升级 | git 源码更新：检查环境与工作区 → fetch 比对（代理优先、失败自动直连）→ 显示计划并确认 → 停止服务 → 同步源码 → pnpm install → pnpm run build:lib → pnpm run build:web → 按原启动模式重启；依赖安装失败自动回滚源码 |
| 停止 | 按端口查找监听进程并终止（含进程树） |
| 重启 | 停止后重新启动（保留端口） |
| 状态 | 运行中/已停止、PID、启动模式（常规/代理）及代理地址、HTTP 健康检查、安装位置、日志路径 |
| 开机自启 | 注册表 Run 键 + VBS 隐藏启动（登录时后台拉起 dsh）；菜单安装时弹出子菜单选择常规/代理启动（命令行可用 autostart / autostart proxy 指定）；卸载无需选择，两种方式均可卸载 |
| 一键安装 | git 克隆源码（代理优先、失败自动直连）→ 检出最新 dsh-v 发布标签 → pnpm install --frozen-lockfile → pnpm run build:lib → pnpm run build:web；已有完整部署或目标目录非空时拒绝执行，半成品安装可重复执行补全 |
| 一键卸载（无残留） | 停服务 → 删开机自启 → 删源码目录 → 删运行目录 → 删用户数据（~\.dsh）→ 清历史桌面版残留/桌面快捷方式/残留计划任务 → 核对残留；执行前打印影响清单并要求确认 |

配置（dshctl.bat 顶部，可按需修改）

| 变量 | 默认值 | 说明 |
|---|---|---|
| DSH_DIR | D:\DSH\deepseek-harness | dsh 源码目录 |
| DSH_PORT | 3080 | 默认端口 |
| DSH_PROXY | http://192.168.10.222:37890 | 默认代理地址（可被 setproxy 自定义地址覆盖） |
| DSH_RUN_DIR | %USERPROFILE%\.dsh-ctl | 运行目录（日志/自启脚本/代理配置） |
| DSH_REPO | https://github.com/deepseek-ai/deepseek-harness.git | 安装时克隆的源码仓库地址 |

一键更新升级（update）

在源码目录用 git 拉取最新代码并重建，全程自动，完成后服务回到原来的启动模式。

更新策略自动识别（按当前仓库形态决定，无需手动传参）：

| 当前形态 | 判定方式 | 执行动作 |
|---|---|---|
| 位于某个分支 | git rev-parse --abbrev-ref HEAD 不是 HEAD | 快进合并跟踪的远端分支（git merge --ff-only origin/） |
| 游离于 dsh-v 发布标签 | 等同于 HEAD（如当前部署停在 dsh-v0.1.5-rc.2） | 检出最新的 dsh-v 标签（按版本号排序，取最大者） |

想从“标签方式”改为“跟随 master 分支”：在源码目录执行一次 git checkout master，之后 update 就会自动按分支方式快进更新。

执行流程：环境检查（源码入口 / node / git / pnpm）→ 工作区必须干净 → git fetch origin --tags（优先走代理，失败自动直连）→ 显示更新计划并等待确认 → 停止该端口上的 dsh web → 检出/快进源码 → pnpm install --frozen-lockfile → pnpm run build:lib（工作区库） → pnpm run build:web（Web 前端）→ 按原模式（常规/代理）重启并做健康检查。

build:lib 是 Web 构建的前置步骤：缺它时 vite build 会解析不到工作区包（如 dsh-experimental-webworker-runtime）而失败，这也是全新克隆上直接跑 build:web 会报错的原因。

失败处理：

| 失败环节 | 行为 |
|---|---|
| 环境检查 / 工作区不干净 / fetch 失败 / 已是最新 | 直接退出，不动服务 |
| git 检出或合并失败 | 源码未变更，按原模式把服务拉起来 |
| pnpm install 失败 | 源码回滚到更新前提交，并把服务拉起来 |
| 工作区库或 Web 构建失败 | 不回滚（会打印手动回退命令），提示重跑 update |

注意：

- 更新期间服务是停止状态（pnpm install + Web 构建通常需要数分钟），请避开使用高峰。
- 需要网络（fetch 与依赖下载）以及 pnpm、git 在 PATH 中。
- 源码目录有未提交改动时会直接拒绝更新，避免覆盖你的改动。
- 端口参数只接受数字：dshctl.bat update 3099；dshctl.bat update master 这类误传会被拦下。
- 自动化调用可加 -y 跳过确认：dshctl.bat update -y。

一键安装 / 卸载（install / uninstall）

菜单 [10] 打开子菜单；命令行直接用 install / uninstall。

安装（install）

流程：工具链检查（git / node / pnpm，无 pnpm 时自动回退 corepack pnpm）→ 目标目录状态判定 → git clone（代理优先，失败自动直连）→ 检出按版本号排序最新的 dsh-v 发布标签 → pnpm install --frozen-lockfile → pnpm run build:lib → pnpm run build:web。

目录状态判定：

| 目标目录状态 | 行为 |
|---|---|
| 不存在 / 空目录 | 正常安装 |
| 已是 dsh 源码，且 node_modules 与 apps\web\dist 都存在 | 拒绝（提示改用 update 升级或 uninstall 卸载） |
| 已是 dsh 源码，但缺依赖或构建产物 | 判定为半成品安装，跳过克隆，直接补全安装 |
| 存在且非空、但不是 dsh 源码 | 拒绝覆盖，提示清空目录或改 DSH_DIR |

失败处理：克隆失败只清理“仅含 .git”的半成品目录；依赖安装或构建失败会保留源码并提示重跑安装补全。

卸载（uninstall，无残留）

先打印影响清单（每项含路径与文件数/体积），输入 Y 才开始执行：

| 顺序 | 清理项 | 说明 |
|---|---|---|
| 1 | 运行中的服务 | 停止指定端口上的 dsh web（含进程树）；停止失败则中止，避免删一半 |
| 2 | 开机自启 | 删除 HKCU\...\Run\DSH Web AutoStart 与 ~\.dsh-ctl\dsh-autostart.vbs |
| 3 | 源码目录 | DSH_DIR（仅在确认是 dsh 源码目录时才删，否则跳过并警告） |
| 4 | 运行目录 | %USERPROFILE%\.dsh-ctl（日志/状态/代理配置/自启脚本） |
| 5 | 用户数据 | %USERPROFILE%\.dsh（会话历史、凭据、设置——删除后不可恢复） |
| 6 | 历史残留 | %LOCALAPPDATA%\dsh-web-launcher、%LOCALAPPDATA%\dsh-plugin-desktop-updater、桌面 DeepSeek Harness.lnk |
| 7 | 计划任务 | dsh-triv（若存在则删除；不存在则跳过） |
| 8 | 空父目录 | 源码目录的父目录若已空则一并删除 |

执行后自动核对残留并逐项报告；仍有残留通常是被文件占用，关闭资源管理器/终端/浏览器后重跑即可（本操作可重复执行）。

不会删除（共享工具，避免影响其它程序）：Node.js、Git、pnpm 存储/缓存、HKCU 的 HTTP_PROXY/HTTPS_PROXY 环境变量、桌面 DSH启动器.lnk（它指向本工具本身）、Node.js 防火墙规则。

重要提醒：

- 卸载会删除会话历史与凭据，且若 GUI/会话正使用该部署会立即中断当前会话——请在原生 cmd（Win+R → cmd）中执行，不要在 DSH 会话内的终端执行。
- 影响清单的体积统计依赖 PowerShell 递归统计（Win10/11 自带），约占十几秒。
Ubuntu / Linux 版（dshctl.sh）

同一套功能的 bash 实现，命令名与 Windows 版完全一致，便于两平台无痛切换。

chmod +x dshctl.sh      # 首次使用赋予执行权限（git 克隆后若已是 755 可跳过）
./dshctl.sh doctor      # 建议先在目标机做环境自检
./dshctl.sh             # 交互菜单

依赖（均为 Ubuntu 常见组件；本工具本身不需要 root）：

| 组件 | 用途 | 缺失后果 |
|---|---|---|
| bash 4+ / coreutils | 运行脚本 | — |
| git | 克隆 / 更新 | install、update 直接报错 |
| node 22.19+ 或 24+ | 运行 dsh web（doctor 会校验版本） | 无法运行 |
| pnpm（缺失自动回退 corepack pnpm） | 依赖安装与构建 | 报错并给出安装指引 |
| curl 或 bash /dev/tcp | 健康检查 | 自动回退 /dev/tcp，无影响 |
| ss（iproute2）或 lsof | 按端口定位进程 | 停止/状态提示安装 iproute2 |
| systemctl --user | 开机自启 | 给出 crontab / XDG 替代方案 |

与 Windows 版的差异（均为平台适配，命令语义不变）：

- 启动：setsid（无则 nohup）后台拉起，日志仍写 ~/.dsh-ctl/logs/dsh-.out/.err.log，并额外记录 PID 文件 ~/.dsh-ctl/dsh-.pid；
- 停止：先 SIGTERM 优雅终止（默认最多等 15s），超时才 SIGKILL；"已停止"以真实端口探活（bash 内建 /dev/tcp）为最终判据，端口仍开绝不虚报成功；
- 开机自启：写 ~/.config/systemd/user/dsh-web.service 并 systemctl --user enable --now，同时尝试 loginctl enable-linger（无登录也随系统启动）；日志用 journalctl --user -u dsh-web -f 查看；
- 卸载：清理 systemd 用户单元 + linger、源码目录、运行目录、用户数据 ~/.dsh，并逐项核对残留（Linux 侧无注册表/桌面版残留，相应项不适用）；
- 编码：UTF-8，无 GBK / 代码页限制；
- 配置：支持环境变量覆盖，便于多实例与测试 ——
DSH_DIR（默认 $HOME/deepseek-harness）、DSH_PORT、DSH_PROXY、DSH_REPO、DSH_RUN_DIR（默认 $HOME/.dsh-ctl）、DSH_DATA_DIR（默认 $HOME/.dsh）。

命令一览（与 Windows 版同名）：

./dshctl.sh start [端口]              # 启动
./dshctl.sh proxy [URL] [端口]        # 带代理启动（URL 可省略）
./dshctl.sh setproxy [URL|clear]      # 查看 / 设置 / 清除自定义代理
./dshctl.sh stop|restart|status [端口]
./dshctl.sh autostart [start|proxy]   # 安装开机自启（systemd 用户单元）
./dshctl.sh autostart-remove          # 卸载开机自启
./dshctl.sh update [-y] [端口]        # 一键更新升级
./dshctl.sh install [目标目录]        # 一键安装（git 克隆源码）
./dshctl.sh uninstall [源码目录]      # 无残留卸载
./dshctl.sh doctor                    # 环境自检

已验证范围（隔离环境 81 项断言全通过：主流程 61 项 + 启动链路/回归 20 项）：命令分发与端口校验、代理读写、install 全链路（克隆 → 检出最新 dsh-v 标签 → pnpm install → build:lib → build:web → 完成）、半成品自动补全、已完整部署拒绝、update 标签模式与分支模式升级、脏工作区与分叉拒绝、确认输入 EOF 时一律取消（安全底线）、uninstall 影响清单 + 确认 + 删除 + 残留核对、菜单与子菜单、status/stop 对真实监听进程生效、启动链路（后台脱离 + PID 文件 + 健康等待 + 状态写入）。

尚未在真机 Ubuntu 验证：systemd 用户单元与 linger 的实际生效、ss/lsof 端口发现（脚本已内置回退与明确告警）、真实 node + pnpm 的完整构建与 dsh web 启动 —— 建议在目标机先跑 ./dshctl.sh doctor。

日志

- 服务日志：%USERPROFILE%\.dsh-ctl\logs\dsh-.out.log / .err.log
- 启动失败排查：先看 .err.log（如端口占用、profile 锁冲突等）

注意事项

- 同一用户数据目录（profile）下只能运行一个 dsh web 实例（task-board 锁），换端口启动第二个实例会失败——需先停止现有实例。
- 脚本启动时会清空可能被外部环境预置的交互/状态变量（INTERACTIVE、choice、setup_choice、as_choice、NEWPROXY、UP_ANS、UN_ANS、menu_bad 等），只由脚本自身设置。否则在预置了这些变量的环境里（例如某些自动化/代理 shell 会预置 INTERACTIVE=1、choice=9）调用 dshctl.bat status 会被误判为菜单模式，菜单还可能沿用继承值执行错误操作（如误停服务）。
- 菜单在连续 5 次无效输入后会自动退出，避免输入被重定向/耗尽时菜单空转。
- 更新前请确保源码目录干净（无未提交改动），否则 update 会拒绝执行。
- 编码为 GBK（中文 Windows cmd 原生支持），请勿用其他编辑器另存为 UTF-8。
- 行尾必须为 CRLF，编辑后请勿转换为 LF（仓库已用 .gitattributes 锁定：.bat 强制 CRLF、*.sh 强制 LF）。

许可证

本项目采用 MIT License 授权。

版本

当前版本 v0.2.0，完整变更明细见 CHANGELOG.md。