DDA-DIGITAL/dsh-web-lifecycle

dsh-web-lifecycle

一个 DSH Web 插件，在侧边栏底部放置两个按钮：

sidebar footer  →  [ ⟳ Restart ]     停止服务器，在同一主机/端口上
重新启动一个完全相同的实例，
并重新加载此页面
→  [ ⏻ Shutdown ]    彻底停止服务器，以便释放终端，
然后关闭此标签页

两者都会先请求确认。不用再每天多次切换到终端来重启 harness——晚上收工时也无需清理任何东西。

- 同一端口，同一会话。 重启会固定已解析的端口，因此浏览器 cookie 的 authority 保持不变——你会保持登录状态，重新加载后打开的会话也会恢复。
- 两种重启传输方式。 可独立运行（分离式重新启动），并且通过捆绑的 dshweb 包装器启动时更快、对终端更友好。
- 无运行时依赖。 仅使用 Node 内置模块。
- 不支持时保持惰性。 没有 webServer / 没有 appExit → 不会挂载任何内容，宿主永远不会受到影响。

安装

from GitHub
dsh plugin --profile web add github:DDA-DIGITAL/dsh-web-lifecycle

from a local checkout
dsh plugin --profile web add /path/to/dsh-web-lifecycle

from npm, once published
dsh plugin --profile web add dsh-web-lifecycle

然后重启一次 dsh web，以便加载宿主端部分，并刷新页面以加载客户端部分：

dsh --profile web --dump-config   # the row web-lifecycle should be listed

重启

| 启动模式 | 会发生什么 |
|---|---|
| dshweb（受监督） | 以代码 75 退出；包装器会在大约一秒内在同一终端中重新启动。 |
| 普通 dsh web（分离式） | 一个位于其自身进程会话中的协调器会比正在退出的进程存活更久，等待端口释放，启动一个完全相同的 dsh web，对其进行健康检查，并将整个链条记录到 $DSH_HOME/plugins-data/dsh-web-lifecycle/restart.log。 |

无论哪种方式，页面都会等待源断开、等待它重新响应，然后重新加载自身。

关闭

关闭会以代码 0 退出——故意不是 75——因此包装器的重新启动条件为假，你的提示符会回来：

dshweb: dsh web stopped (exit 0); supervisor exiting

不会启动协调器，因此没有任何东西能让服务器恢复。在普通 dsh web 下，进程只是退出（它本来就是分离式的，所以你的终端早已空闲）。

关于关闭标签页

该插件确实会尝试为你关闭标签页（window.close()），当 GUI 作为已安装的 PWA 或应用窗口运行时，这可以生效。对于普通浏览器标签页，它不会生效：浏览器只允许页面关闭由脚本打开的窗口，而 DSH 会把 URL 交给你的操作系统浏览器，因此没有 opener。

所以标签页分两步处理：先尝试关闭，然后——如果它仍然存在——显示一张全屏卡片，上面写着 “dsh web has stopped”，并将标签页标题改为
dsh web stopped，并提醒你按 ⌘W / Ctrl+W。关闭时没有自动重载：已经没有什么可加载的了。

监督进程包装器（可选，推荐）

模式 A 让服务器保持附着在你的终端上，并使重启耗时约 1 秒：

install -m 0755 scripts/dshweb ~/bin/dshweb     # 或 /usr/local/bin
dshweb                                          # 与 dsh web 相同的标志
dshweb --port 3080

该包装器在循环中运行 dsh web，并将退出码 75 视为“重新启动我”。Ctrl-C 仍然有效（SIGINT 退出码为 130，不是 75，因此循环停止），而 Shutdown 退出码为 0，也会停止循环。没有包装器时，插件仍然可用——只是回退到分离式重新启动。

配置

默认值位于插件行（cordis.patch.yml）中，并由插件自身重新应用：

- id: web-lifecycle
config:
confirm: true          # 在执行任一操作前显示确认弹窗
allowShutdown: true    # false 会完全隐藏 Shutdown 行
healthTimeoutMs: 30000 # 分离式重启等待新服务器的时长
logToConsole: true     # 将插件的决策记录到 dsh web 日志中

在 $DSH_HOME/profiles/web/cordis.patch.yml 中按 id 覆盖该行——该文件会被实时监视，因此更改无需重启即可生效。

一次操作的代价

两种操作都会中断进程正在运行的一切：活动轮次、子代理、后台作业和已计划的工作。会话本身是持久的，重启后会重新打开，但任何进行中的内容都会丢失——这就是确认弹窗默认开启的原因。如果你更喜欢单击操作，可以用 confirm: false 将其关闭。

在关闭之后，唯一的恢复方式是通过终端：dshweb 或 dsh web。

故障排除

| 症状 | 该怎么办 |
|---|---|
| 按钮缺失 | 检查 dsh --profile web --dump-config 是否列出了 web-lifecycle，然后重启 dsh web 并刷新页面。 |
| 覆盖层显示“没有回来” | 阅读 $DSH_HOME/plugins-data/dsh-web-lifecycle/restart.log；它以失败的启动输出结尾。用 dsh web 手动启动服务器。 |
| 红色状态点 | 通道没有响应——宿主端未挂载，或页面已过期。刷新；如果仍然存在，从终端重启一次。 |
| 重启有效，但标签页要求你进行身份验证 | 端口已更改。不要用 --port 0 启动服务器，并保持包装器的标志与原始调用完全相同。 |
| 关闭卡片保持打开 | 在普通标签页中是预期行为——按 ⌘W。在 PWA/应用窗口中它会自行关闭。 |
| 监督进程（launchd/systemd/pm2）不断复活服务器 | 不支持：关闭会停止进程，监督进程又会启动它。 |

工作原理

- 宿主端（lib/index.js）在 webServer 上注册一个前缀路由
/dsh-web-lifecycle，包含 POST /status、POST /restart 和 POST /shutdown。
请求会通过宿主自身的浏览器防护
(connection.requestRejection：Host/Origin 信任加上签名 cookie),
回退到环回检查。
- 浏览器部分(lib/client.js)由客户端模块宿主在
/plugins/dsh-web-lifecycle/client.js 提供，并向
sidebar.footer.action 槽位注册一个条目。该槽位的容器是 flex 行，因此第二个
条目会渲染在 Restart 旁边而不是其下方；所以两行都放在同一个条目内，由插件自己的列容器
进行堆叠。
- 退出码即协议：75 = 重新启动我，0 = 停止。单元测试固定了
两者，因为混淆它们会把 Shutdown 变成 Restart。

有两个宿主怪癖被刻意规避，二者都是在构建过程中发现的：

1. connection.rpc.handle 在 @deepseek-ai/dsh 0.1.5-rc.1 中不可用——它
通过一个从未注入 webServer 的上下文访问 webServer，因此每次调用
都会抛出 cannot get property "webServer" without inject。直接注册路由
正是 connection 插件为其自己的 /api 路由所做的。
2. ctx.get("connection") 在从未声明它的上下文上返回 undefined，
这会将浏览器防护静默降级为仅环回。因此该服务
在 inject 列表中命名并作为属性读取，这是
cordis 允许的唯一访问形式。

开发

npm test     # node --test: config, argv planning, waits, lifecycle policy, HTTP envelope, client bundle shape
npm run check

布局：

lib/relaunch.js       两半共享的纯辅助函数（argv 规划、等待、端口、退出码）
lib/index.js          宿主部分：路由、重启/关闭策略、协调器生成
lib/restart-agent.mjs 分离式协调器（仅分离式重启）
lib/client.js         浏览器部分：页脚行、弹出框、状态卡片、标签页关闭
scripts/dshweb        监督器包装器（退出码 75 = 重新启动，其他任何值 = 停止）
test/                 单元测试

许可证

MIT——参见 LICENSE。

仓库：