julensun-ir/DSH-RESTART-TOOL

DSH-RESTART-TOOL

为 DeepSeek Harness (dsh) web 提供可靠的重启与关闭，供 agent（模型工具） 与 GUI（侧边栏电源控制） 使用。
可靠地重啟 / 關閉 DeepSeek Harness (dsh) web 服務，供 agent（模型工具） 與 GUI（側邊欄電源控制） 使用。

License: MIT

为什么存在 / 為什麼存在

在 Windows 上，朴素的重启流程往往以 “端口关闭了，但什么都没有回来” 收场。以下四个坑我们都踩过，并在代码中绕过了它们——就算你不装这个插件，也值得知道：
在 Windows 上，「普通重啟」往往以「端口關了、服務沒起來」收場。以下四個坑我們都踩過並在代碼裡繞過——就算你不裝這個插件，也值得知道：

1. 异步 spawn 竞态（最隐蔽的）/ 異步 spawn 競態（最隱蔽的） — 在 Windows 上，Node 的 child_process.spawn 是异步的。一个 helper 在 spawn 之后如果事件循环被清空（child.unref() 且没有其他待处理项），会在 CreateProcess 完成之前退出——新进程从未被创建，只留下空日志。修复方法：等待 'spawn' 事件（带重试），或保持事件循环被引用（轮询 / 监听器）。
Node 在 Windows 上 child.spawn 是異步的：helper 在 spawn(...) 後若事件循環立即清空，會在進程創建完成前退出——新進程從未被創建，只剩兩個空日誌。修法：等 'spawn' 事件（失敗重試）或保持事件循環被引用。
2. agent 沙箱的 kill-on-close job / agent 沙箱 kill-on-close job — DSH 将 agent shell 包裹在一个 JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE job 中（不允许 breakaway）：当宿主死亡时，agent 的 shell 及其 spawn 的一切都会随之死亡。agent 永远无法可靠地杀死并重新启动宿主本身；可靠的做法是让 宿主来 spawn helper（宿主的子进程不在该 job 中）。
DSH 給 agent 的 shell 套了 kill-on-close job（無 BREAKAWAY）：宿主一死，agent 的 shell 及其 spawn 的一切全部陪葬。可靠的路徑是讓宿主自己 spawn helper（宿主的子進程不在這個 job 裡）。
3. 在 Windows 上 SIGTERM 是不可捕获的硬杀 / Windows 上 SIGTERM 是不可捕獲硬殺 — process.kill(pid, 'SIGTERM') 映射为 TerminateProcess；DSH 的优雅 SIGTERM 处理器永远不会运行。只有 Ctrl+C（SIGINT）是可捕获的。
process.kill(pid,'SIGTERM') 在 Windows 映射為 TerminateProcess，優雅關閉處理器不會執行；只有 Ctrl+C（SIGINT）可捕獲。
4. taskkill /T /F 也会杀掉 helper 自己 / taskkill /T /F 會殺到 helper 自己 — 如果 helper 是宿主的子进程，树杀会干掉那个本应重新启动宿主的进程。要么只杀单个进程，要么在树遍历时排除你自己的进程链。
若 helper 是宿主的子進程，樹殺會把負責拉起的 helper 一起幹掉。要麼精確殺單個進程，要麼在樹遍歷時排除自身鏈。

功能 / 功能

| 能力 / 能力 | 入口 / 入口 | 状态 / 驗證 |
|---|---|---|
| 重启 DSH / 重啟 DSH | 模型工具 restart_dsh · GUI 图标按钮 · POST /dsh-restart/restart | ✅ 已在 Windows 上测试 / 實測 |
| 关闭 / 關機 | 模型工具 shutdown_dsh · GUI 图标按钮 · POST /dsh-restart/shutdown | ✅ 机制已测试（fence + routes）；实际动作由你自行尝试 / 機制實測，實際動作可自行體驗 |
| 重启确认 / 重啟確認 | GET /dsh-restart/status → {"restarted":true,"fromInstanceId":…} | ✅ 已测试 / 實測 |
| Session auto-resume / session 自動續跑 | 在重啟前記錄執行中的 session → 在新實例上注入「繼續」提示 | ✅ Tested (agent-triggered restart, nudge delivered) / 實測 |
| Health dot / 健康點 | GUI 側邊欄圓點（3 秒輪詢，綠/紅） | ✅ Rendered-tested / 渲染實測 |
| Restart overlay + auto-reload / 重啟遮罩 + 自動刷新 | 重啟時顯示全螢幕遮罩；新實例的 id 變更後自動 location.reload() | ✅ Rendered-tested / 渲染實測 |
| Watchdog (optional) / 監督者（可選） | 由配置控制 | ⚠️ Code ready, not battle-tested / 代碼就緒，未實戰 |

Install / 安裝

dsh plugin --profile web add github:julensun-ir/DSH-RESTART-TOOL
or local / 或本地
dsh plugin --profile web add file:./dsh-restart-tool

Restart dsh to activate. Optional config (in the profile's cordis.patch.yml):
重啟 dsh 生效。可選配置（profile 的 cordis.patch.yml）：

- id: dsh-restart-tool
config:
watchdogEnabled: true      # supervisor, default off / 監督者，默認關閉
watchdogCooldownMs: 60000
watchdogPollMs: 2000
autoContinueEnabled: true
continuePrompt: "The system has restarted. Please continue the work that was in progress."

GUI usage / GUI 使用

At the bottom of the sidebar (footer actions) you get two icon-only buttons (no text, so they do not squeeze neighbouring items such as the usage-stats row):
側邊欄底部出現兩個純圖標按鈕（無文字，避免擠壓相鄰項目如用量統計）：

- Refresh icon (Restart) / 刷新圖標（重啟） — click → full-screen "Restarting DeepSeek Harness…" overlay → the page auto-reloads once the new instance is up; hover shows a tooltip / 點擊後顯示全屏遮罩，新實例起來後頁面自動刷新，懸停有提示。
- Power icon (Shutdown) / 電源圖標（關機） — graceful shutdown, no auto-relaunch (start dsh manually afterwards) / 優雅關閉，不會自動重啟。
- Status dot / 狀態圓點 — green = online, red = offline/restarting, grey = unknown / 綠=在線，紅=離線/重啟中，灰=未知。

Architecture / 架構

Host process (node bin.js web)
├─ plugin apply (inject: tools, agents): tools / routes / auto-resume / watchdog
├─ restart_dsh called:
│    ├─ runningSessionIds(ctx) records running sessions (an agent-triggered call captures the current session)
│    ├─ writes the intent marker + resume marker
│    ├─ spawns a detached helper (detached, windowsHide, a real .cjs file)
│    └─ ctx.appExit graceful exit after 2s → hard-kill backstop at 12s
├─ new instance apply:
│    ├─ reads the marker (time-window match, compatible with the hidden-console wrapper) → status reports restarted
│    └─ tryAutoContinue: polls agents.get(sessionId), injects the "continue" nudge once resumed
└─ helper (a host child, outside the sandbox job, survives the host's death):
├─ waits for the port to free (up to 90s)
├─ relaunches with the same command line (Windows: hidden-console powershell wrapper)
├─ awaits the 'spawn' event (retry ×3) → confirms the process exists
├─ updates marker.newPid → the new host self-proves the restart
└─ verifies HTTP 200 → exits

Relationship with similar plugins / 與同類插件的關係
本插件结合了 agent 工具 + GUI 电源控制 + 完整验证闭环（spawn 确认 + HTTP 200 + marker 自证 + 自动续跑）。诚实声明：watchdog 未在生产环境实战检验；macOS/Linux 路径未实测（存在 POSIX 分支但未验证）；关机操作仅通过机制验证。如需全平台生产级保障，请同时参考 dsh-power-button 和 anweat/dsh-restart。
本插件提供 agent 工具 + GUI 电源控制 + 完整验证闭环（spawn 确认 + HTTP 200 + marker 自证 + 续跑提示）。诚实声明：watchdog 未在生产环境实战；macOS/Linux 未实测；关机仅机制验证。如需全平台生产级保障，请同时参考 power-button 与 anweat/dsh-restart。

验证 / 验证清单

- [x] 自动化：GET /dsh-restart/status restarted:true + fromInstanceId 逻辑（marker 时间窗口匹配）——由测试套件覆盖
- [x] 自动化：helper 日志（port free、spawned pid、http200=true）——由测试套件覆盖（真实 helper 子进程 + 模拟 host）
- [ ] 新 host PID 与旧的不同，HTTP 200——实时检查（helper newPid + HTTP 200 已由套件覆盖）
- [ ] agent 触发的重启向会话传递“继续”提示——实时检查（提示注入已由套件覆盖）
- [ ] 关机后，dsh-stopped.flag 存在且端口不再监听——实时检查（flag 写入已由套件覆盖）

测试 / 测试

npm test

基于 Node 内置 node:test 运行器的零依赖套件（在单个进程中运行——node --test CLI 运行器会通过管道为每个文件生成子进程，而 DSH agent 沙箱会以 EPERM 阻止该操作）：

| 文件 | 覆盖内容 |
|---|---|
| test/index.test.mjs | 插件导出、Config 形状、路径辅助函数、isTrustedRequest 防护、resolvePort、runningSessionIds、resume-marker 往返、relaunch-spec 端口处理、工具/路由注册、health/status 路由（restarted true/false）、405/403 防护、自动续跑提示（默认启用）、apply 时 watchdog spawn，以及一个完整重启循环（marker → helper 子进程 → relaunch → newPid → http200=true） |
| test/helper.test.mjs | 作为真实子进程的 restart-helper.cjs：relaunch + HTTP 200 验证、占用端口等待、spawn 失败重试（POSIX） |
| test/watchdog.test.mjs | 作为真实子进程的 watchdog.cjs：宕机端口 relaunch、有意重启 flag 抑制（包括损坏 flag）、冷却、日志打开失败存活、stop-flag 退出 |

三个 dsh peer 导入（@deepseek-ai/dsh-tools、dsh-llm、schemastery）通过 ESM resolve hook（test/loader.mjs）进行 stub——真实包位于 dsh 运行时中。集成测试通过生成的进程写入的日志/marker 文件进行断言，因为沙箱会阻止捕获子进程 stdout。

许可证 / 许可证

MIT