dsh-ctl — DeepSeek Harness 生命周期控制插件

dsh (DeepSeek Harness) 生命周期控制：停止 / 重启 / 状态 / 开机自启，全部在 dsh 内部完成 —— 斜杠命令、本地 HTTP 端点、可复用服务三合一。

Lifecycle control for the DeepSeek Harness Web: stop / restart / status / logon autostart, all from inside dsh — slash commands, local HTTP endpoints, and a reusable service.

| | | |---|---| | 平台 Platform | Windows（自启）/ 全平台（命令与端点） | | 依赖 Dependencies | 零运行时依赖，仅 peer 依赖 @deepseek-ai/cordis | | 安装 Install | dsh plugin --profile web add dsh-ctl |

解决的问题 / Problem

关掉 shell 也杀不掉 dsh web 的进程？本插件让 dsh 自己管理自己：

• 停止：优雅退出（先落盘会话再关进程），不再需要到处找 PID。
• 重启：先拉起一个「静默接力」进程，再退出当前进程 —— 端口交接完成后由接力进程以隐藏窗口方式启动新的 dsh，会话历史都在，刷新即可恢复。
• 状态：当前 URL / PID / 运行时长 / 自启状态，一眼可见。
• 开机自启：向 Windows「启动」文件夹写入一个 VBS，登录时静默（无窗口）拉起与当前完全相同的 dsh web 命令；若登录时已有实例在跑则自动跳过。

Can't kill dsh web by closing the shell? This plugin lets dsh manage itself: graceful stop (checkpoint before exit), restart (a silent relay process takes over the port, then a hidden-window dsh starts), status, and Windows logon autostart (a Startup-folder VBS that silently launches the same dsh web command; skips automatically if an instance is already running).

安装 / Install

dsh plugin --profile web add dsh-ctl

重启 dsh web 后生效（配置热重载不会激活新增 bundle）。验证：浏览器打开 http://127.0.0.1:3080/dshctl/status，或在启动日志里看到 dsh-ctl ready: ...。

Takes effect after the dsh web process restarts. Verify by opening http://127.0.0.1:3080/dshctl/status or by finding dsh-ctl ready: ... in the startup log.

用法 / Usage

斜杠命令 / Slash commands（Web 输入框）

| 命令 | 作用 | |---|---| | /dshctl 或 /dshctl status | 显示 URL / PID / 运行时长 / 自启状态 | | /dshctl stop now | 优雅停止 dsh（now 是防误触确认词） | | /dshctl restart now | 静默重启 dsh（端口交接后自动拉起） | | /dshctl autostart on | 启用 Windows 登录自启 | | /dshctl autostart off | 关闭自启 | | /dshctl autostart status | 查看自启状态 |

HTTP 端点 / HTTP endpoints（默认绑定 127.0.0.1）

| 方法 | 路径 | 说明 | |---|---|---| | GET | /dshctl/status | 状态 JSON | | POST | /dshctl/stop | 优雅停止 | | POST | /dshctl/restart | 静默重启 | | POST | /dshctl/autostart | body {"action":"on"\|"off"\|"status"} |

示例：

curl http://127.0.0.1:3080/dshctl/status
curl -X POST http://127.0.0.1:3080/dshctl/restart

安全提示：变更类端点默认只信任本机回环。若把 dsh 绑定到 0.0.0.0，请在配置里设置 token（见下），调用时带 ?token=<值>。 Security note: mutation endpoints trust loopback only by default. If you bind dsh to 0.0.0.0, set token in config and call with ?token=<value>.

服务 / Service

其他插件可注入 dshctl 服务使用：

export const inject = ['dshctl']
// apply(ctx) { ctx.dshctl.stop() } 等

配置 / Config（profile 的 cordis.patch.yml）

- id: dsh-ctl
  config:
    # 控制端点令牌；留空 = 仅本机、不校验。建议在 LAN 暴露时设置。
    token: ''

工作原理 / How it works

• 停止：调用 dsh boot 提供的 appExit（优雅 dispose，先落盘会话与检查点）；不可用时回退 SIGTERM。
• 重启 / 自启：复用 scripts/relaunch.mjs —— 轮询旧 PID / 端口释放后，以 detached + windowsHide 方式拉起与当前完全相同的命令（node <bin.js> web ...），进程与任何终端脱离，关 shell 不影响它。
• 自校验（0.1.1 起）：relaunch.mjs 拉起新进程后不再静默退出，而是把新进程输出追加写入日志（默认 $DSH_HOME/dsh-ctl-relaunch.log），在约 45 秒内校验「新进程存活 && 端口已监听」并做 2 秒稳定性确认。若新进程因 EADDRINUSE 等提前退出、或端口被别的进程（保活/双开/升级残留）抢占，会读日志尾部诊断、按 --retries 重试，重试耗尽后以非零退出码报错——绝不再「拉起失败却假装成功」。
• 自启：%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\dsh-ctl-autostart.vbs，由插件在 autostart on 时生成（含当前端口与工作目录）；--skip-if-busy 保证登录时已有实例不会重复启动。

限制 / Limitations

• 开机自启仅支持 Windows（其他平台 supported: false，其余功能不受影响）。
• 重启后浏览器需手动刷新（会话历史持久化在 $DSH_HOME/sessions，可继续）。

License

MIT