前言¶
在 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
