前言¶
在 DSH 裏和智能體協作時，對話窗口往往佔滿屏幕，但本地開發仍要同時跑後端、前端，甚至註冊中心或遷移腳本。IDE 的運行配置通常是「單選」：點一次只能起一個進程，日誌分散在多個窗口，前端起來時也缺少「後端已在應答」的客觀依據。多項目 monorepo 還要自己記目錄、命令和啓動順序。
dsh-dev-runner 是 DeepSeek Harness 的客戶端插件，把項目表、啓動順序、就緒探測和日誌收進右側欄，並在會話頂欄提供整棧啓停。它對具體技術棧不做假設——Maven、npm、Python、Go、Docker Compose 都以數據形式配置，自動發現只給出可審查的提議。
這是什麼¶
- 名稱：dsh-dev-runner（倉庫 1020252969/dsh-dev-runner）
- 維護者：1020252969
- 分類：客戶端（側欄 + 頂欄控件）
- 定位：一鍵拉起整套開發環境；在側欄增刪改項目，在同一側讀帶顏色、可搜索、可下載的日誌，全程不必爲啓停反覆切出對話。
插件不替代構建系統：清單裏讀不到的意圖（例如多模塊 Maven 要先 install）仍需你自行用啓動前步驟或命令表達。
核心功能¶
項目編排¶
- 一張可見的項目表，每項包含工作目錄、常駐命令、環境變量、角色（
backend/frontend/service/infra）等。 - 啓動前步驟（
before）：可設輸出校驗（expect）和「失敗也繼續」（continueOnError）。 - 就緒判定用 TCP 端口、主機或 HTTP URL 探測，而不是僅看進程是否存在；HTTP 任意響應即視爲就緒並回報狀態碼。
dependsOn：例如後端就緒後再起前端。autoRestart帶熔斷：短時間連續異常退出多次後停止繼續拉起。oneShot：本應退出的命令（遷移、代碼生成等）以done結束，不算失敗，依賴方仍可繼續。
自動發現¶
指定根目錄後，插件讀取常見清單並提議啓動命令與端口依據（按下「應用」前不會寫入）：
| 檢測器 | 依據文件 | 提議命令示例 |
|---|---|---|
| Maven | pom.xml |
spring-boot:run、quarkus:dev 等 |
| Gradle | build.gradle[.kts] |
gradlew bootRun |
| Node | package.json、vite.config.* |
dev / start / serve；uni-app 傾向 dev:h5 |
| Python | manage.py、requirements.txt、pyproject.toml |
runserver、uvicorn、flask run 等 |
| Go | go.mod |
go run . |
| Compose | docker-compose.yml、compose.yml |
docker compose up |
端口來自配置文件、.env、腳本參數或 Compose 映射；未寫明時標註爲約定值；不猜測未激活的 profile 或佔位符環境變量。掃描默認最多 120 秒，可取消；目錄留空時默認掃第一個已配置項目的父目錄。Vite 代理指向後端端口，或掃描中只有一個後端時，前端提議會自動接到該後端。
側欄與頂欄¶
- 側欄：項目列表（狀態、運行時長、重啓次數）、表單編輯、校驗（缺字段、非法端口、環依賴等會拒保存並列原因）。
- 日誌：ANSI 彩色、篩選與跳轉、跟隨、清空、複製、下載爲
‹id›.log；內存保留約每項目 2000 行。 - 頂欄藥丸：狀態點、
運行中/總數、整棧啓動/停止；點狀態可打開面板。空會話無會話頭時該控件不可見。
HTTP 接口¶
路由前綴 /dev-runner/api，僅迴環訪問，跨源頁面無法借瀏覽器驅動。提供狀態、項目 CRUD、單項目/整棧啓停、發現與應用候選、日誌分頁與文本下載等（詳見倉庫 README 表格）。
安裝與啓用¶
桌面 profile 安裝：
dsh plugin --profile desktop add dsh-dev-runner
從本地源碼目錄安裝（客戶端無構建步驟，可直接 file: 路徑）：
dsh plugin --profile desktop add 'file:<absolute path to the checkout>'
裝好後側欄引導會出現 Dev services。默認無需額外配置：打開面板輸入掃描目錄，確認候選即可落盤。
環境要求（來自 package.json）：DSH >=0.2.0-rc.2 || >=0.2.1-rc.2 || >=0.2.2-alpha.3；peer 依賴 @deepseek-ai/schemastery ^3.18.4。
典型用法¶
配置來源¶
生效表有兩個來源，同時存在時以存儲文件爲準：
<DSH_HOME>/.dev-runner/projects.json（未設置DSH_HOME時用~/.dsh）- profile 補丁
cordis.patch.yml裏dev-runner.config.projects
GET /status 與面板會標明當前來源（store、store-empty 或 config）。刪掉 projects.json 可回退到 YAML 補丁。
profile 示例片段¶
在 cordis.patch.yml 中預置後端 + 前端與依賴（路徑需改爲你的絕對路徑）：
- insert:
- id: dev-runner
name: 'dsh-dev-runner'
config:
discoverDepth: 2
projects:
- id: backend
name: API
cwd: <absolute path to your shop-api checkout>
command: mvn -Dmaven.test.skip=true spring-boot:run
role: backend
readyPort: 8080
readyTimeoutMs: 180000
env:
SPRING_PROFILES_ACTIVE: dev
- id: frontend
name: 商城前端
cwd: <absolute path to your shop-ui checkout>
command: npm run dev:h5
role: frontend
readyPort: 5173
args: -- --host
dependsOn: [backend]
autoRestart: true
before:
- name: 生成接口代碼
command: npm run gen:api
expect: 'generated'
常用字段：readyPort / readyHost / readyUrl、dependsOn、before、autoRestart、oneShot 等；完整說明見 README 項目字段表。
日常操作¶
- 打開側欄 Dev services 面板，必要時對倉庫根目錄執行自動發現並應用候選。
- 在頂欄點擊整棧啓動，或按依賴順序單獨啓停項目。
- 在側欄查看日誌；需要留檔時用下載得到
‹id›.log。
也可通過 /dev-runner/api 腳本化（例如 POST /start-all、POST /discover）。
適用場景與注意¶
適合：經常在 DSH 會話旁同時維護後端 + 前端（或其它多進程棧）；希望用端口/URL 證明「可以連了」再串行啓動；希望日誌集中在側欄而不是多個終端。
邊界與權限：
- 插件以當前 DSH 進程權限啓動子進程；安裝前應閱讀源碼與 MIT 許可證。
- Windows 上難以向子進程組投遞 SIGINT，停止行爲爲直接終止，面板會如實說明。
- 就緒探測不等於健康檢查：端口通即算就緒，應用可能仍在預熱。
- 環境變量：插件只下發你在項目裏聲明的
env；宿主會先剝離憑據與DSH_*，需要繼承的內容請顯式寫入。
社區目錄 SkillHub 插件頁 與 GitHub 爲獨立信息源，與 DeepSeek / 幻方無官方從屬關係；DSH 生態一貫是「一切皆插件」，可按需從目錄或倉庫安裝。
結尾¶
dsh-dev-runner 把「項目表 + 依賴順序 + 就緒探測 + 側欄日誌」接到 DSH 桌面客戶端上，用數據描述命令而非綁定某一框架。若你正在 SkillHub 或 GitHub 上挑選客戶端類 DSH 插件，可用官方命令 dsh plugin --profile desktop add dsh-dev-runner 試用；細節與 API 以 GitHub README 爲準。
