前言¶
在 DeepSeek Harness（DSH）里做全栈或前后端分离项目时，常见做法是：后端起一个 uvicorn 或 npm run dev，前端再起一个 Vite，还要记得端口别冲突、依赖谁先谁后。若这些都放在 DSH 自带终端或聊天里随手敲命令，进程是否还在跑、日志在哪、端口是否被旧实例占住，往往要再切到 VS Code 的「运行与调试」或单独开一个终端窗口核对。
dsh-runner 是社区维护的 DSH 客户端插件（维护者 lcx19970714，GitHub：lcx19970714/dsh-runner），目标是在 DSH 内提供接近 VS Code 任务运行器那一半的体验：服务启停、状态、输出、端口与依赖编排；不含断点与单步调试（那需要 DAP，属于另一量级）。适用于 DSH 0.2.1 线（README 注明 0.2.1-rc.2 实测）；package.json 中 engines.dsh 为 >=0.2.1-0 <0.3.0-0，当前插件版本 0.17.1，许可证 MIT。
这是什么¶
一句话：给 DSH 增加项目级「运行」面板——在客户端左侧导航打开 「运行」，按工作区分组查看并启动/停止/重启多条开发命令，看状态、端口徽标和日志；输入框下方仍保留紧凑的 「▶ 运行」 快捷菜单（启停重启与日志入口）。完整配置与 AI 侧维护则通过 Host 上的 commands.json 以及工具 dsh_runner_config、dsh_runner_run 完成。
社区目录页：https://www.skillhub.cn/plugins/lcx19970714/dsh-runner（SkillHub 为独立插件目录，与 DeepSeek / 幻方无官方从属关系）。
核心功能¶
下面介绍面板与 Host 侧已文档化的能力，均来自仓库 README。
「运行」面板¶
左侧 运行 打开的是全部项目视图（不依赖当前会话项目）：所有工作区里的命令与运行状态在一页展示。
- 按项目分组：每条命令按
projectRoot归组；标题显示工作区名（找不到时用路径末段）、完整路径、「当前」标记和运行计数。 - 分组可折叠：折叠状态写入
~/.dsh/dsh-runner/ui-state.json，跨会话与 Host 重启保留。 - 本组启停：每组有「本组启动 / 本组停止」，按该项目
dependsOn拓扑序执行。 - 全局命令：
scope: global的命令带「全局」标签；无当前项目会话时单列「全局命令」。 - 状态轮询：运行中 / 启动中 / 停止中 / 外部运行中 / 未运行等状态一目了然；顶部支持启动全部、停止全部、刷新、管理命令。
- 日志：点某行命令，下方显示该命令日志（每秒轮询，自动贴底；可清空、复制）。
配置里已删除但仍在运行的命令/项目仍会显示，避免「删配置就看不见进程」。
端口契约¶
对声明了 ports 的命令，插件按严格契约处理，而不是仅作提示：
- 启动前检查 IPv4 + IPv6 监听者，占用则
port-conflict。 - 启动后校验端口是否由本次启动的进程树监听；若命令静默换端口（例如 Vite 从 5174 改到 5175），判为
port-mismatch并终止进程，行内显示声明端口与实际/未绑定徽标。 - 同一
projectRoot或全局作用域内端口不可重复声明；不监听端口的构建/检查类命令应保持ports: []。 - 约每 6 秒诊断：非托管进程占用声明端口时，行内可显示「外部运行中」等，并提供「结束并启动」等入口（托管进程不能从端口入口直接杀，需先停对应命令）。
AI 工具¶
Host 提供两个 Tool，便于在对话里维护配置与操作进程：
| 工具 | 作用 |
|---|---|
dsh_runner_config |
配置的 list/create/update/delete/reorder，支持 env、ports、readyPort、readyTimeoutMs、dependsOn |
dsh_runner_run |
status / start / stop / restart / startAll / stopAll / diagnose / log |
Tool 说明要求：长驻服务用 dsh_runner_run，不要用终端工具——终端起的进程没有托管状态、日志与端口诊断，关会话还可能残留。
示例说法（README 原文意图）：「给这个项目加一个启动后端……端口 8001，就绪端口 8001」「把网页端改成依赖后端，端口 5174」「启动所有项目服务」「有哪些端口被不在插件里的进程占了」。
生命周期与数据¶
- 进程归属项目，与会话无关；Host 为状态唯一来源。
- DSH 或插件重载/升级不会因此杀掉已托管进程；重启后用 pid + 命令行标记接管仍在运行的进程。
- 数据位置（README 以 Windows 用户目录为例，实际为 DSH 配置下的
dsh-runner目录）： - 配置：
commands.json（模型 version 2） - 运行状态：
runner-state.json - 日志：
logs\<项目hash>\<命令id>.log（追加写入，不轮转）
安装与启用¶
推荐在 DSH 侧栏 插件 → 添加插件 → Install a third-party plugin，粘贴：
github:lcx19970714/dsh-runner
桌面版也可用命令行（需先完全退出 DSH）：
dsh plugin --profile desktop add github:lcx19970714/dsh-runner
装好后进入项目会话，左侧导航会出现 「运行」 图标。本地开发插件时使用 file:<仓库绝对路径> 添加，README 中有说明；正文任务要求不展开 git clone 步骤。
安装前建议自行查看仓库源码与 MIT 许可证；插件以当前 DSH Host 进程权限执行命令，配置中的 command 会交给 PowerShell 运行。
配置模型 commands.json¶
Host 是唯一配置源。README 示例路径为 C:\Users\main\.dsh\dsh-runner\commands.json；字段以 version 2 为准。节选结构如下：
{
"version": 2,
"ui": { "visible": true },
"commands": [
{
"id": "cmd-xxxx",
"title": "调试后端",
"command": "python -m uvicorn main:应用 --host 127.0.0.1 --port 8001 --reload",
"cwd": "H:\\AI达人BD系统-海外版\\后端",
"scope": "project",
"projectRoot": "H:\\AI达人BD系统-海外版",
"enabled": true,
"env": { "APP_ENV": "dev", "APP_PORT": "8001", "PYTHONUNBUFFERED": "1" },
"ports": [8001],
"readyPort": 8001,
"readyTimeoutMs": 120000,
"dependsOn": []
}
]
}
常用字段：title / command（显示名与 PowerShell 命令）、cwd、scope（project | global）、projectRoot、env、ports、readyPort、readyTimeoutMs（1000–1800000，默认 120000）、dependsOn（依赖的其他命令 id）。旧版 0.10/0.11 的 commands.json 可读，未知字段会被忽略；要启用端口预检与就绪等待，需补上 ports / readyPort。
面板内「管理命令」与 AI 的 dsh_runner_config 均可维护该文件；默认 projectRoot 对应当前会话工作区。
典型用法¶
- 安装插件，打开左侧 运行，确认当前项目分组出现。
- 通过管理命令或对话让 AI 写入后端、前端两条命令，前端
dependsOn指向后端 id，并声明真实监听的ports与readyPort。 - 使用「本组启动」或「启动全部」，观察状态点与端口徽标；点行查看日志。
- 若提示端口被占用，按对话框查看占用进程信息，选择结束占用后启动，或先在面板停止托管实例。
经过上面的步骤，日常 dev server 可在 DSH 内完成，而不必仅为「跑起来」单独开 VS Code 任务面板；需要断点调试时仍应使用 VS Code 或专用调试器。
适用场景与注意¶
适合：在 Windows 上用 DSH 0.2.1 线开发，希望把多服务启停、依赖顺序、端口一致性收拢到一个面板，并让 Agent 通过 dsh_runner_* 工具代劳配置与操作。
务必知晓的限制（README「限制与版本风险」）：
- 仅支持 Windows + PowerShell（Host 使用
taskkill、Get-CimInstance等）。 - 日志为文件轮询视图，非交互终端：无 stdin、无 Ctrl+C、无 ANSI 颜色；需要交互时用 DSH 终端，但长驻服务建议本插件托管。
- 依赖 DSH 0.2.1 内部客户端槽位（如
sidebar.panellist、settings.section）与 Host RPC；升级 DSH 后可能需要插件适配。 engines.node要求 >=22。
结尾¶
dsh-runner 把「在 DSH 里跑 dev server」从散落的终端命令，收成可配置、可诊断、可被 AI 操作的项目级运行面板；若你已在用 DSH 做智能体开发，值得在 SkillHub 目录页或 GitHub 仓库核对版本与说明后再安装。
- 目录页：https://www.skillhub.cn/plugins/lcx19970714/dsh-runner
- 仓库：https://github.com/lcx19970714/dsh-runner
