前言¶
在 DeepSeek Harness (DSH) 的生態中，Stacked PR（堆疊 PR）常用於管理具有依賴關係的多層級代碼變更。然而，當底層 PR 需要修改時，變基操作會重寫提交 SHAs，導致原先的 CI 驗證記錄失效。如果沒有額外的校驗，開發者可能誤以爲“測試通過”並直接合並，從而引入未經驗證的代碼。
dsh-stack 是 DeepSeek Harness 的一個 Cordis 插件，它爲堆疊 PR 工作流提供了一套強制性的安全策略。它覆蓋了從同步、驗證到合併和清理的全流程，通過 SHA 綁定的驗證記錄，確保每次合併前的測試狀態是可追溯且有效的。這是對 GitHub 分支保護規則的防禦深度補充，而非替代品。
核心功能¶
dsh-stack 在命令執行過程中會依次校驗以下八個安全點：
-
G-ENV（環境與認證校驗）
確保當前環境滿足要求：GitHub CLI 版本 >= 2.90.0，gh-stack擴展版本 >= 0.1.0，且具備 GraphQL 認證權限。 -
G-TREE（工作區清潔校驗）
在執行同步或變基前，通過git status --porcelain檢查工作區。若存在未提交的修改，操作將被阻止。 -
G-TOPO（拓撲結構校驗）
驗證 PR 依賴鏈的完整性，拒絕跨 Fork 倉庫、循環依賴或孤立節點的存在。 -
G-TEST（重寫層測試校驗）
當變基觸達某一層時，強制運行該層的本地測試套件（默認pnpm test或npm test），並將測試結果寫入驗證記錄。 -
G-VERIFY（驗證記錄校驗）
拒絕合併當前 Head SHA 沒有對應驗證記錄的分支。若記錄缺失、過期或失敗，合併請求將被阻塞。 -
G-LAND（合併資格校驗）
檢查 CI 構建狀態是否爲綠色，以及代碼審查是否已獲批准。 -
G-POLL（合併狀態輪詢）
在執行合併後，持續輪詢 GitHub API 確認分支狀態確認爲MERGED。 -
G-DEL（零依賴清理校驗）
在刪除分支前，嚴格檢查該分支是否存在開放依賴。只有依賴計數爲 0 時才允許刪除。
安裝與配置¶
安裝¶
通過 npm 安裝插件：
dsh plugin --profile default add dsh-stack
前置條件¶
在安裝前，請確保環境滿足以下要求：
* Node.js >= 22
* GitHub CLI >= 2.90.0
* gh-stack 擴展 >= 0.1.0
配置測試命令¶
默認情況下，插件使用 pnpm test 或 npm test。若項目使用其他測試框架，需在配置文件中指定驗證命令。配置文件路徑爲 $DSH_HOME/profiles/default/cordis.patch.yml：
- replace:
- id: stack
config:
validationCommand: ['pytest', '-q'] # 自定義測試命令，以數組形式傳入
validationTimeoutMs: 600000 # 設置超時時間（毫秒）
注意：更改
validationCommand會使之前的驗證記錄失效，因此必須重新運行驗證流程。
驗證安裝¶
安裝完成後，可以通過以下命令確認配置已生效：
dsh --profile default --dump-config | grep stack
適用場景與注意事項¶
適用場景：
* 使用 gh stack 進行多層級 PR 管理的開發者。
* 依賴 CI 結果來決定代碼合併權的團隊。
* 希望在本地命令行層面增加一層安全防護的 DSH 用戶。
注意事項：
* 防禦深度：該插件是防禦策略的一部分，不應替代 GitHub 倉庫的分支保護規則。
* 構建腳本限制：如果使用 pnpm >= 10，Git 依賴的構建腳本可能會被阻止。若安裝失敗，需將包名添加到 $DSH_HOME/profiles/default/pnpm-workspace.yaml 的 allowBuilds 字段中。
* 記錄失效：修改驗證命令會導致歷史記錄失效，必須重新測試。
