前言¶
在 DSH（DeepSeek Harness）里做全栈或后端开发时，会话往往对应一个仓库：前端 dev server、Spring Boot、Python API、Docker Compose 各跑一条命令。常见做法是另开终端窗口，或依赖 IDE 里的运行配置。DSH 会话头部本身没有统一入口来列出「当前项目该起哪些服务、端口是否被占、输出在哪看」。dsh-service-runner 由社区维护者 sqzssg12138 发布，分类为客户端插件，在会话头部右上角提供类似 IDEA 的服务启停面板：多工作区隔离、多语言自动探测、实时日志，以及端口占用者的查询与处置。
这是什么¶
dsh-service-runner（GitHub：sqzssg12138/dsh-service-runner）给 DSH Desktop 增加工作区级服务管理 UI 与 host 侧进程控制。服务定义持久化在本地；启停与日志通过 /service-runner 前缀的 HTTP 接口供面板同源调用。host 侧只使用 Node 内置模块与 DSH 的 webServer 接缝，不依赖 @deepseek-ai/* 内部包；client 侧仅依赖 react，避免双份 React 导致 hooks 异常。
核心功能¶
会话头部面板¶
安装并重启 DSH Desktop 后，会话头部右上角（后台任务按钮旁）会出现「服务」按钮。状态点含义：灰=已停止，黄闪=启动中，绿=运行中，红=失败；绿色时按钮上的数字表示运行中的服务数。
多工作区隔离¶
服务按工作区根目录分别保存；切换会话即切换项目配置。工作区路径优先从会话权威工作区（host 经 sessionPersistence 读取会话头中的 cwd）取得；取不到时回退到会话目录名反解；仍失败可在面板底部手填绝对路径，填过一次会记住。
自动探测与编辑¶
第一次使用可进入编辑态，点「探测工作区」生成候选列表。支持 Node/前端、Maven/Gradle/Java、Python、Docker Compose；扫描范围为工作区根目录及一层子目录（如 apps/、packages/），并跳过 node_modules、target、.git 等。包管理器按 lockfile 在 pnpm/yarn/bun/npm 间选择；端口可从 vite.config.*、application.y[a]ml、.env、脚本参数等推断。
工作区存在 .idea 时，会优先解析 JetBrains 运行配置（新式 .idea/runConfigurations/*.xml 与旧式 workspace.xml 的 RunManager 均支持），候选排在启发式结果之前；无法忠实还原为命令行的配置类型会跳过，避免列表被默认模板灌满。多模块 Maven 聚合项目在根目录以 -pl … -am 形式生成命令，以匹配 reactor 语义。
探测规则摘要见下表（细节以仓库 README 为准）：
| 语言 | 触发文件 | 生成的命令（示例） |
|---|---|---|
| node | package.json 含 dev/develop/serve/start |
按 lockfile 选包管理器，如 pnpm run dev |
| java | pom.xml |
wrapper 或 mvn spring-boot:run 等 |
| java | build.gradle[.kts] |
gradlew bootRun 或 gradle bootRun |
| java | target/*.jar |
java -jar target/xxx.jar |
| python | manage.py |
python manage.py runserver |
| python | main.py/app.py + 依赖清单 |
python -m uvicorn main:app --reload |
| docker | compose 文件 | docker compose up |
编辑态可改名称、命令、端口，删除不需要的行后保存；列表态可对单条服务执行启动、停止、重启，并通过「日志」查看实时输出。
日志与端口¶
日志区支持时间戳、子串过滤、清空缓冲、下载为带 ISO 时间戳的 <服务名>.log。每个服务最近保留 2000 行缓冲。
展开服务后，若配置了端口，面板可显示该端口的监听进程（pid、进程名、启动时间、命令行），并提供「结束该进程」「重新检查」。结束操作需二次确认；host 会在执行前重新核对 pid，端口易主时拒绝误杀。
停止与重启时：Windows 上先尝试温和关闭（taskkill /T 不带 /F，约 1.5s），再强杀进程树，最后按声明端口兜底清理可能残留的 dev server；POSIX 上对应 SIGTERM 后 SIGKILL。DSH 退出或卸载插件时，本插件启动的进程会被一并结束，不留下占端口的孤儿进程。
数据与安全¶
- 服务定义文件：
<DSH_HOME>/service-runner/services.json（可直接编辑，刷新面板生效）。 - 运行状态仅存在内存中。
HTTP 路由均受信任围栏约束：Host 须为回环地址、不得为跨站 sec-fetch-site，若带 Origin 则须与 Host 一致，以降低恶意网页对本机 /service-runner/action 的 CSRF 风险。
安装与启用¶
前置条件（来自仓库说明）：
| 依赖 | 要求 |
|---|---|
| DSH Desktop | 在 0.1.5-rc.2 上开发与验证 |
| Node.js | ≥ 20 |
| pnpm | 用于依赖安装与构建 |
官方文档给出的安装方式为克隆仓库、构建后以 link 装入 profile（以下命令摘自 README，路径请替换为本机绝对路径）：
git clone https://github.com/sqzssg12138/dsh-service-runner.git
cd dsh-service-runner
pnpm install
pnpm run build
dsh plugin --profile desktop add "link:<克隆到的绝对路径>"
卸载：
dsh plugin --profile desktop remove dsh-service-runner
修改插件代码后需重新 pnpm run build 并重启 DSH：profile 的 bundle 组合与 client 注册发生在启动时，不支持热加载新 bundle。
插件以当前 DSH 进程权限在本机启停子进程；安装前应阅读源码与 MIT 许可证，确认符合你的安全与合规要求。
典型用法¶
- 重启 DSH Desktop，打开目标项目会话，点右上角「服务」。
- 首次使用：点「编辑」→「探测工作区」，在列表中调整名称、命令、端口后「保存」。
- 在列表态对服务点「启动 / 停止 / 重启」；需要排查输出时点「日志」。
- 若启动失败且与端口有关，在日志区上方查看占用者，必要时经确认结束该进程后再启动。
本地调试探测结果而不启动 DSH 时，仓库提供 node scripts/probe-detect.mjs "<工作区路径>" 等脚本（见 GitHub「开发与测试」一节）。
适用场景与注意¶
适合：在 DSH 会话内频繁切换前后端或多模块 Java 项目、希望把 dev server 与 DSH 同屏管理、并需要端口冲突可视化的开发者。
注意：
- 端口就绪判断在端口被其他进程占用时不作数；插件会标注「未经端口确认」的就绪状态，避免误报。
- Windows 上不使用
detached: true启动，否则 stdout/stderr 无法进入面板。 - 自动探测生成的是候选命令，复杂 VM 参数、自定义脚本仍建议在编辑态核对；IDEA 无法还原的配置会被跳过而非猜测。
- 社区目录 SkillHub 插件页 与 DeepSeek / 幻方无官方从属关系；DSH 生态以「一切皆插件」为方向，本插件为社区贡献的客户端扩展。
链接¶
- 目录页：https://www.skillhub.cn/plugins/sqzssg12138/dsh-service-runner
- 源码与完整 API、探测规则、已知限制：https://github.com/sqzssg12138/dsh-service-runner
