本地应用停靠VANvonZHANG/dsh-docks

dsh-docks

一个面向 DeepSeek Harness 的通用 Web 应用停靠系统：任何本地 Web 服务（marimo、Pluto.jl、gradio、streamlit……）通过一行声明即可进入 dsh，并与 agent 会话并行运行。零重写、零转换——只需 *.localhost 通配符主机路由 + iframe。

形态（v2）

docks 是一个纯宿主停靠服务；UI 委托给 DSH-better-sidebar：

- 停靠内容：在 better-sidebar 的内嵌浏览器标签页中打开 http://.localhost:3081/
- 停靠控制：better-sidebar 的“docks”标签页（应用列表 + 状态点 + 启动/停止 + 打开）
- agent 工具：在对话中说“启动 marimo”，或直接调用 docks 工具（list/status/start/stop/restart）

前置条件

- 安装 dsh-better-sidebar（dsh plugin --profile web add dsh-better-sidebar）
- 在 better-sidebar 设置中启用 browserNoSandbox（全局禁用沙箱；接受“所有网页和 GUI 共享同一源”的权衡，仅适用于本地受信任的应用）
- （可选）启用 agentOpenTools，以便模型可以通过 sidebar_open 直接将 URL 推送到浏览器标签页

用法

1. docks list（在对话中或通过 agent 工具）→ 获取 http://marimo.localhost:3081/
2. 打开该 URL（sidebar_open 或在地址栏中输入）→ marimo 在浏览器标签页中运行
3. “docks”控制面板标签页 → 一览所有应用状态、启动/停止、点击“↗”打开浏览器标签页

架构

- host：node:http 监听 127.0.0.1:3081，根据 Host 头反向代理到应用的真实端口；注入 FRAME_SCRIPT，将同源打开折叠回 iframe（停靠语义）；提供 /_docks/state、/_docks/command、/docks/api/origin
- client：向 better-sidebar 注册的控制面板标签页（软依赖；没有它时，就是纯 agent 工具）
- agent：docks 工具（list/status/start/stop/restart）

配置参考

声明挂在 profile patch 中的 - id: docks / config 下。listen.host 只允许 127.0.0.1（v1 不提供 0.0.0.0；安全态势与 dsh 主服务一致）。

| 字段 | 默认值 | 描述 |
|---|---|---|
| listen.host | 127.0.0.1 | 仅 127.0.0.1 |
| listen.port | 3081 | docks 面板服务监听的端口（被占用时，激活失败并提示更改此值） |
| restarts.maxConsecutive | 3 | 连续崩溃重启限制；耗尽 → failed |
| restarts.stableUptimeMs | 60000 | 连续运行超过此持续时间会重置重启计数器 |
| restarts.backoffMs | 1000, 2000, 4000 | 崩溃重启退避序列（以最后一个值为上限；连续运行 ≥ stableUptimeMs 后计数器重置） |
| apps[] | [] | 应用声明列表，见下文 |

应用声明分为两个级别（v1 实现 L0+L1）：

L1 managed（docks 处理启动/停止、探测、崩溃重启、期望状态恢复）

| 字段 | 默认值 | 描述 |
|---|---|---|
| name | 必填 | 子域名；必须匹配 ^[a-z0-9-]+$，不可重复 |
| title | name | 显示名称 |
| command | L1 必填 | 可执行文件（与 external 互斥） |
| args | [] | 命令行参数 |
| port | L1 必填 | 应用实际监听的端口（启动前会预先检查是否被占用） |
| cwd / env | — | 工作目录 / 字符串环境变量 |
| healthPath | / | HTTP 探测路径，期望返回就绪响应（<500） |
| healthTimeoutMs | 120000 | 探测超时（Pluto 首次启动预编译可能需要一两分钟；marimo 建议 30000） |
| startup | manual | manual 按需启动；auto 在激活时启动（按应用例外） |
| mode | attached | detached 会被 schema 接受，但 v1 会返回“未实现”错误 |

L0 纯访问（无进程；路由器直接透传；状态点 unreachable 表示外部服务不可达）

| 字段 | 描述 |
|---|---|
| name | 同上 |
| external | L0 必填，仅支持本地 http://127.0.0.1: 地址，且不得与 command 同时使用 |

将计算与观测分离（安全说明）

重型模拟不要放进 docks。 将多核 / 长时间运行的计算本身放在 tmux / systemd / slurm 下运行；docks 只托管“观测面”Web 应用。docks 与 dsh 共享生命周期——dsh 崩溃会连带终止已附加的应用进程。正确的做法是：在外部会话中运行计算，并在 docks 中只声明一个指向其 UI 端口的 L0 纯访问（external: http://127.0.0.1:8501）。命令/状态端点仅监听回环地址，并拒绝跨源 Origin。

开发

pnpm install
pnpm test        # vitest
pnpm typecheck   # tsc --noEmit
pnpm build       # tsdown

（配置详情、L0/L1、启动模型：见 spec）