进程端口管家 janpauldahlke/dsh-agent-processes

dsh-agent-processes

为 DeepSeek Harness web UI 里的本地编码智能体提供宿主托管的进程与端口生命周期管理。

通过裸 bash 启动的长期本地进程会变成僵尸：智能体忘了 PID，端口一直被占，下次启动撞上 EADDRINUSE，然后智能体绕着一个其实是端口问题的 bug 改代码。这个插件给智能体配上一双好手——start / stop / list / logs / wait-ready，外加持久化 vault——同时给人一个 Processes 右侧栏和 composer 停靠芯片。

相关插件（同样是 web 右侧栏 / 停靠用的双面 dsh.bundle 形态）：

| 插件 | 仓库 |
| 长周期任务状态 | dsh-local-long-horizon |
| NVIDIA GPU 利用率 / 显存 / 功耗 | dsh-gpu-monitor-nvml |
| 本地 LLM 端点 / slot 健康 | dsh-slot-health |

本包：dsh-agent-processes。

已在 DeepSeek Harness 0.1.7-rc.2（dsh web）上验证。

环境要求

- DeepSeek Harness web 配置档（dsh web）。
- 构建需要 Node.js ≥ 20。

截图

浅色主题，与 DSH 默认一致。

| 面板 + 聊天（运行中） | Processes 面板（全屏） |
| Processes pane open | Processes fullscreen |

| 停靠芯片（右侧栏关闭，聊天指标活跃） |
| Composer dock chip |

你会看到什么

- Processes 右侧栏——跟随当前打开的聊天工作区。每条记录一张卡片：状态圆点（绿色运行中 / 琥珀色启动中 / 红色崩溃 / 灰色已停止）、id + 端口、pid + 存活时长、命令、cwd 基名、日志预览，以及 Kill / Restart / Clear。
- 停靠芯片——右侧栏关闭、且被跟随的工作区有东西在运行时，显示在聊天指标条上（Processes · :3000、Processes · 3 running……）。点击打开面板。
- 受管回收——带 port 启动时，先停掉该端口上任何已跟踪的占用者；外来（未跟踪）占用者会被拒绝，绝不杀掉。

安装

git clone https://github.com/janpauldahlke/dsh-agent-processes.git
cd dsh-agent-processes
npm install && npm run build
dsh plugin --profile web add "$(pwd)"

重启（或启动）dsh web，让宿主端 + 客户端两面加载：

env -u DSH_WEB_URL -u DSH_SHELL -u DSH_SESSION_ID dsh web --no-open

卸载：

dsh plugin --profile web remove dsh-agent-processes
restart the web instance that had the plugin

没有 harness 的 file: 依赖——宿主在 dsh 提供的实时 ctx.tools 服务上注册工具。改完要重新构建 lib/；客户端改动热加载，宿主改动需要重启 web shell。

智能体工具

| 工具 | 用途 |
| process_start | 启动 + 跟踪；可选端口等待 / 回收 |
| process_stop | SIGTERM → 3s 宽限 → SIGKILL（进程组） |
| process_list | 所有已跟踪记录（会重新检查存活状态） |
| process_logs | 查看某条记录捕获日志的尾部 |
| process_wait_ready | 轮询直到 127.0.0.1:port 接受连接（或超时） |
| process_ping | 插件存活探测 |

带 port 的 process_start：

1. 回收 —— 停掉该端口所有已跟踪、仍存活的占用者；在 reclaimed[] 中报告 id。
2. 外部占用检查 —— 如果该端口仍能接受连接，用带类型的错误拒绝（不杀进程）。
3. 就绪等待 —— TCP 连接 127.0.0.1:P（默认超时 15s）。超时是一种「形似成功」的结果，带 error: 'port-timeout'；进程保持运行。

记录会无损保存 argv，所以 UI / 路由的重启会在同一 id 下重跑同一条命令。

界面入口

| 入口 | 路径 / 名称 |
| Vault | ~/.dsh/storages/dsh-agent-processes/processes.json |
| 日志 | ~/.dsh/storages/dsh-agent-processes/logs/<id>.log |
| HTTP | GET / POST /api/dsh-agent-processes |
| UI | 右侧栏 Processes + 输入框停靠区小标签 |

GET /api/dsh-agent-processes
→ { ok, package, version, storageRoot, count, processes: […] }

POST /api/dsh-agent-processes { "action": "stop" | "restart" | "remove", "id": "…" }

面板每 2s 轮询一次（按引用计数 —— 最后一个查看者卸载后停止）。

推荐的 AGENTS.md 片段

Long-lived processes — use dsh-agent-processes

For anything that stays up (dev servers, watchers, long node servers):

- Start with process_start (include port if it listens). It reclaims tracked
holders of that port, refuses foreign ones, and waits for TCP readiness — do not start long-lived processes with raw bash or backgrounded &.
- Before assuming a port is free, check process_list; after starting, use
process_wait_ready instead of sleep.
- Stop with process_stop. Read process_logs when something looks wrong.
- On crash or port failure: read process_logs, fix, process_start again,
verify with process_wait_ready.
- Never kill untracked PIDs; if a foreign process holds the port, free it
manually or start on another port.

架构

双面包（与其他 web 右侧栏 / 停靠区插件同一标准）：

- Host（lib/index.js，ESM）—— vault、工具、HTTP 路由。
- Client（lib/client.js，CJS ModuleLoader 工厂）—— 右侧栏 + 停靠区小标签。
- Glue —— cordis.patch.yml + package.json 里的 dsh.bundle / dsh.client。

dsh-agent-processes/
├── package.json
├── build.mjs
├── cordis.patch.yml
├── media/ # README screenshots
├── scripts/ # shippable lifecycle smoke
├── test/ # node --test (vault + service)
├── src/host/ # vault, service, tools, route
├── src/client/ # pane + dock chip
├── src/shared/ # shared types
└── lib/ # built artifacts (required at runtime)

开发 / 测试

bash
npm test # node --test (vault + service; real child processes)
npm run smoke # shippable lifecycle smoke (start → ready → reclaim → foreign refuse)

限制

- 只杀自己跟踪的进程 —— 绝不向未跟踪的 PID 发信号；占用端口的外部进程会被拒绝，而不是被杀掉。
- 崩溃检测靠存活探测（采样器 + 按需复查），不靠监听信号。
- 没有日志轮转 —— 日志只追加，不清理。
- 没有按会话隔离 —— vault 按 web 配置档划分；UI 的作用域按 cwd 划分。
- 后续规划（不在 v0 中）：只读的 top-N 系统进程卡片。

贡献

安装、目录结构、PR 要求见 CONTRIBUTING.md。

许可证

MIT —— 见 LICENSE。