dsh-process-panel
DeepSeek Harness（dsh）的侧栏进程面板插件：
在 Web GUI 里管理长时后台进程 —— 启动、停止、重启、看实时日志，AI 侧通过 sv_* 工具操作。
A sidebar process panel for DeepSeek Harness: manage long-running background
processes (start / stop / restart / live logs) from the Web GUI, with matching
sv_* tools for the agent. Installs as a standard DSH bundle.
┌ 侧栏 ───────────────┐
│ 记忆系统 │
│ 工作区 │
│ …会话列表… │
│ 进程任务 ● 2 │ ← 侧栏底部，紧挨「设置」的官方座位
│ 设置 │
└─────────────────────┘
功能
- 侧栏入口「进程任务」：位于侧栏底部、紧挨「设置」（官方
sidebar.footer.action 座位），
徽标显示运行中的任务数；点开是全屏面板，左侧任务列表、右侧实时日志。
- 任务状态一目了然：运行中 / 孤儿进程 / 已失效 / 已停止 / 已退出 / 启动失败。
- 面板按钮：
重启、停止、终止（针对孤儿进程）、清除，列表顶部还有 清理已结束。
- 日志体验：默认选中第一个运行中的任务并自动跟随底部；手动上滚即暂停跟随，滚回底部恢复。
- AI 工具：
sv_start / sv_stop / sv_restart / sv_logs / sv_list / sv_clear，
所以你（或你的 agent）只要说「启动后端」「看下 backend 日志」就够了。
- 任务归属宿主进程：所有会话与 GUI 面板共享同一份任务列表。
任务状态语义
| 状态 | 含义 | 面板能做什么 |
|---|
running | 本 dsh 进程的子进程，正常可控 | 重启 / 停止 |
orphan | dsh 被强杀（kill -9 / 崩溃）时活下来的进程。面板读不到它的输出（管道随旧进程消失），只保留 pid | 只能「终止」（按 pid 发 SIGTERM→SIGKILL） |
lost | dsh 重启过，进程已不在；命令行与日志仍保留 | 重启（一键拉回来）/ 清除 |
stopped / exited / failed | 已结束 | 重启 / 清除 |
dsh 正常退出（SIGTERM/SIGINT，含 systemctl restart）会连任务一起结束；
只有 kill -9 / 崩溃才可能留下「孤儿进程」，此时面板会如实显示并提供「终止」。
环境要求与兼容性
| 依赖 | 版本 |
|---|
| DeepSeek Harness | 0.1.1-rc.2（本插件在该版本上开发并验证） |
@deepseek-ai/dsh-tools | 0.1.1-rc.2（已锁死在 dependencies，随插件一起安装） |
| Node.js | ^22.19.0 || >=24.0.0 |
| pnpm | 11（corepack enable pnpm） |
版本锁定说明：插件在运行时 import "@deepseek-ai/dsh-tools"，该包与 dsh 主版本同步发布。
本项目把它写成精确版本依赖（不是 peer），以确保任何安装方式下都能解析到与宿主匹配的实现；
升级 dsh 后如果行为异常，请把这里的版本与本表对齐。
安装
本插件以 bundle 形式分发：仓库自带 cordis.patch.yml 并在 package.json 声明
dsh.bundle.patch，因此 dsh plugin add 会自动把插件层登记进 profile，无需手工改配置文件。
方式一：拉源码后一条命令（推荐，无需任何授权）
git clone https://github.com/ALIWUER/dsh-process-panel.git
cd dsh-process-panel
./install.sh # 装进 web profile；也可 ./install.sh <profile>
install.sh 做三件事：安装依赖并构建 → 注册 bundle → 打印验证命令。等价于手动执行：
pnpm install && pnpm run build
dsh plugin --profile web add "$PWD"
方式二：直接从 GitHub 安装
dsh plugin --profile web add github:ALIWUER/dsh-process-panel#v0.5.0
pnpm ≥10 默认拒绝执行 git 依赖的构建脚本，首次会失败并给出提示 —— 把 pnpm 打印的包键写进该
profile 的 pnpm-workspace.yaml 后重试：
allowBuilds:
dsh-process-panel: true
⚠️ 安全提示：这一步等于允许该仓库的代码在你的机器上执行构建。
请锁定 tag 或 commit（如 #v0.5.0），不要直接装 main 这种浮动引用。
验证与生效
dsh --profile web --dump-config | grep -A2 process-panel # 应看到 id: process-panel
# 然后重启 dsh web（bundle 层在启动时装配）
打开 GUI，侧栏底部（设置旁边）即可看到「进程任务」。若之前开着页面，请刷新一次。
卸载
dsh plugin --profile web remove dsh-process-panel
配置
| 配置项 | 默认值 | 说明 |
|---|
stateDir | $DSH_HOME/process-panel | 任务快照（状态 + 最近日志）的存放目录 |
在 profile 的 cordis.patch.yml 里覆盖（patch 按行替换，需要重述该行所有键）：
- insert:
- id: process-panel
name: 'dsh-process-panel'
config:
stateDir: '/path/to/my/process-panel'
使用
GUI
点侧栏底部「进程任务」→ 面板。左侧点任务看日志，行内按钮做操作，顶部「清理已结束」批量清掉已结束记录
（仍在运行的孤儿进程会保留）。
自然语言（AI 侧）
| 你说 | 会调用 |
|---|
| 「启动后端」「把 backend 跑起来」 | sv_start |
| 「重启 backend」「改完代码重新部署」 | sv_restart |
| 「停掉 backend」 | sv_stop |
| 「看下 backend 日志」 | sv_logs |
| 「现在有哪些任务在跑」 | sv_list |
| 「清理一下已结束的任务」 | sv_clear |
sv_start 的 command 是一个字符串（直接 spawn，不做 shell 解析；需要管道/重定向请写成 bash -c '...'）。
开发
pnpm install
pnpm run typecheck # tsc --noEmit
pnpm run build # rolldown（host ESM + client CJS）+ 生成类型
pnpm run dev # rolldown --watch
- 改 host 半边 → 重启 dsh（
systemctl restart dsh-web）。
- 改 client 半边 → 刷新页面即可（
/plugins/<包名>/client.js 不缓存）。
- 本地联调：
dsh plugin --profile <你自己的 profile> add "$PWD" 装的是指向本目录的链接，
构建后重启即生效。
实现要点
插件的每一处副作用都归属 dsh 的 Cordis 容器，停止/更新/卸载时自动回收：
| 半边 | 贡献 | 所有权 |
|---|
| client | sidebar.footer.action 入口（{ wide } 由座位下发，收起时自动变圆图标） | ctx.slots.inject + ctx.slots.register |
| client | shell.overlay 全屏面板（该层本身 click-through，面板自行开启 pointer-events） | 同上 |
| client | 轮询 | 注入的 timer 服务（ctx.interval），无全局定时器 |
| client | 样式 | 注入一张 style[data-plugin-css]（0.1.1-rc.2 无 styles 服务，与官方面板同法） |
| host | sv_list / sv_start / sv_stop / sv_restart / sv_logs / sv_clear | ctx.effect(() => ctx.tools.register(...)) |
| host | `GET | POST /sv-api/process-panel/*` |
| host | 停机钩子（把子进程一起带走）、SIGKILL 升级定时器 | ctx.effect(...) + ctx.timeout(...) |
重启是「先停干净再起」：SIGTERM → 等进程真正退出（最多 5s，超时再 SIGKILL）→ 才重新拉起，
所以像 dev server 这类占端口的任务不会因为端口没释放而 EADDRINUSE 起不来。
已知限制
- 入口与面板分别挂在
sidebar.footer.action / shell.overlay 两个座位名上；dsh 大版本若改名，
入口会消失，跟进修这里即可（不会再依赖任何产品 DOM 类名）。
- 已脱离 dsh 的
orphan 进程：面板只能显示 pid 并终止它，无法读取它的输出（管道已随旧进程消失）。
- 面板 HTTP 接口挂在
/sv-api/process-panel/{state,action}（仅本机 GUI 使用）。
- 命令以
spawn 直接执行、不经 shell（&&、管道、重定向请自行包 bash -c '...'）。
License
MIT
