MarchLiu/dsh-farm

dsh-farm 🚜

DSH 服务农场插件：注册、启动、停止、重启并监视长期运行的项目服务——智能体可以通过工具完成这些操作，你也可以通过 Web UI 完成。

安装

dsh plugin --profile  add /path/to/dsh-farm

之后重启 DSH Web 界面。

你将获得

- UI：侧边栏底部有一个 🚜 按钮，带有运行中服务数量的徽标；点击它会打开概览抽屉——服务按工作区分组显示，带有状态圆点、启动/停止/重启按钮，以及一个支持实时跟随（SSE）、子串搜索和下载/导出的日志视图。如果安装了 DSH-better-sidebar，同一个面板会改为该侧边栏中的 Farm 标签页——参见 UI 所在位置。
- 删除：某一行上的 🗑 会删除该服务。☑ select 会将抽屉切换为多选模式——勾选行（或 全选），然后 删除 (n) 会打开一个确认对话框，列出目标；在你确认之前不会删除任何内容。farm.yaml 中的服务在两种路径中都会置灰：该文件拥有它们，因此你需要通过编辑文件来移除它们。
- 智能体工具：farm_status / farm_start / farm_stop /
farm_restart / farm_logs(service, tail, search) /
farm_register(name, workspace, command, ...) /
farm_unregister(service | services)。在会话中说“帮我把 dev server
注册到 farm 并启动”，智能体就会完成其余工作。
- farm.yaml（可选，按工作区，便于提交到版本库）：

services:
dev-server:
command: pnpm dev
cwd: sub/dir        # optional, resolved against the workspace
autoRestart: true
env:
PORT: 5173

声明的服务会自动出现在 UI 和 farm_status 中
（source: yaml）；该文件始终是唯一事实来源。

UI 所在位置

dsh-farm 会在运行时决定，将面板渲染到任何可用的宿主中：

| DSH-better-sidebar | 面板出现的位置 |
|---|---|
| 已安装 | better-sidebar 中的一个 🚜 Farm 标签页（单实例，带有运行数量徽标）；dsh-farm 自己的底部按钮和抽屉会退让 |
| 未安装 | dsh-farm 自己的 🚜 底部按钮 + 右侧抽屉 |

无需配置，并且 better-sidebar 不是依赖项——dsh-farm 会在运行时按名称查找该服务，并在其不存在时继续工作。它还会在 DSH 运行期间双向跟随 better-sidebar 的启用或禁用。

给任何扩展此插件的人的实现说明：betterSidebar 有意不放在客户端半部分的 inject 中。在 DSH 的 cordis 中，声明但缺失的服务会使整个插件停摆，这也会连带使回退 UI 下线——插件会完全消失，而不是回退。运行时的可选查找钩子是 ctx.get('betterSidebar')
（不存在时为 undefined），而 ctx.on('internal/service', …) 会捕获 better-sidebar 稍后到达或离开的情况。该事件可能会触发多次
对于同一次到达，因此注册是幂等的。

行为说明

- 服务作为 DSH 进程的子进程（/bin/sh -c）启动，因此当 DSH 退出时它们会被回收。动态注册在重启后会保留在 $DSH_HOME/storages/dsh-farm/services.json 中（状态不会保留）。
- 停止 = SIGTERM，然后在 3 秒宽限期后 SIGKILL。
- autoRestart 会以指数退避（1 秒 → 16 秒）重试异常退出，最多 5 次。
- 日志：每个服务有 5000 行的内存环形缓冲区，外加 $DSH_HOME/storages/dsh-farm/logs/.log 下的仅追加文件。
- 删除服务会先停止它，然后删除其注册表行、其实时日志流及其日志文件。Id 由 workspace + name 派生，因此这可以防止之后重新注册同名服务时继承过期的日志。项目文件绝不会被改动。

HTTP API（仅限 localhost，前缀 /farm）

| 路由 | 含义 |
|---|---|
| GET /farm/services?workspace= | 列出（合并 farm.yaml 条目） |
| POST /farm/services | 注册/更新一个动态服务 |
| GET /farm/services/:id | 获取一个服务 |
| DELETE /farm/services/:id | 注销一个（先停止它；对 farm.yaml 服务返回 400） |
| POST /farm/services/batch-delete | 批量注销 — { ids: [] } → { ok, deleted, failed } |
| POST /farm/services/:id/start\|stop\|restart | 生命周期 |
| GET /farm/services/:id/logs?tail=&search=&export=1 | 日志，export=1 下载 |
| GET /farm/services/:id/logs/stream | SSE 实时跟踪 |

配置（在 profile 补丁中覆盖）

- id: farm
config:
dataDir: /abs/path   # default $DSH_HOME/storages/dsh-farm
ringLines: 5000
stopGraceMs: 3000