DeepSeek Harness 插件：dsh-pr-description

前言¶

DeepSeek Harness (DSH) 的理念是“一切皆插件”。在 DSH 社區中，代碼評審類的插件已較爲豐富，但針對 PR 描述的自動生成工具相對稀缺。dsh-pr-description 是 DSH 原生工具，定位爲模型推理（Model Inference）開發輔助，它能分析當前分支的 diff，生成符合 Conventional Commits 規範的 PR 標題、描述和自審清單，解決開發者手動編寫 PR 文檔的痛點。

功能¶

插件通過 pr_describe 工具執行一個確定性的工作流，主要包含以下步驟：

確定範圍：執行 git diff --name-status，對比當前分支與基線（base）的差異。
統計與歸類：統計新增/修改/刪除的文件數及行數，並根據文件擴展名和變更內容（如符號變更、關鍵詞）將變更歸類爲 docs、test、chore、feat、fix 或 refactor。
提取符號：通過輕量級正則提取新增的函數、類或導出符號。
生成文本：拼裝 Conventional Commits 標題（feat(scope): 動詞短句）和五段式描述（動機/方案/影響/測試/風險），並生成自審清單。
輸出與交互：將結果寫入 PR_DESCRIPTION.md 並在會話內渲染。支持交互確認（confirm）和直接調用 gh CLI 提交 PR（openPr）。

安裝與啓用¶

插件通過 bundle patch 的方式掛載，安裝後可直接使用。

dsh plugin --profile demo add ./dsh-pr-description

在 DSH 的配置文件 cordis.yml 中，插件會自動以裸包名 dsh-pr-description 掛載，指向 lib/index.js。

用法¶

會話內調用¶

在會話中直接調用 pr_describe 工具：

分析當前分支的改動，用 pr_describe 生成 PR 描述並確認後寫入

工具參數¶

參數	類型	默認值	說明
`workdir`	string	配置 `workdir` 或進程 cwd	git 倉庫目錄
`base`	string	自動探測	對比基線，支持 `origin/HEAD` 等多種探測路徑
`titleStyle`	string	`conventional`	標題風格，可選 `conventional` 或 `plain`
`confirm`	boolean	`false`	生成前 ask-user 交互確認，取消則不落盤
`openPr`	boolean	`false`	gh 可用時直接提 PR，不可用則跳過
`output`	string	`PR_DESCRIPTION.md`	輸出文件路徑（相對 workdir）
`locale`	string	`zh`	模板語言，支持 `zh` 或 `en`

插件配置¶

在 cordis.yml 中插入配置項：

- insert:
    - id: pr-describe
      name: 'dsh-pr-description'
      config:
        locale: 'zh'
        defaultTitleStyle: 'conventional'
        outputFile: 'PR_DESCRIPTION.md'
        defaultBase: ''        # 留空 = 自動探測
        workdir: ''            # 留空 = 進程 cwd

開發¶

本插件依賴 DeepSeek Harness 的源碼檢出，使用 link: 依賴指向相鄰的 dsh-src。

開發者需要在同級目錄檢出官方 Harness 並構建：

# 在同級 dsh-src 目錄執行
pnpm install && pnpm run build
# 回到本倉庫執行
pnpm install --offline && pnpm build

測試命令包括離線冒煙測試和 E2E 測試：

node tests/smoke.offline.mjs
pnpm test:e2e
pnpm build

注意事項¶

確定性生成：當前版本的五段描述爲確定性模板拼裝，未調用 LLM 進行語義潤色。如需更靈活的語義生成，需在生成後接入模型處理。
權限邊界：插件需要讀取面（git diff）、命令面（固定 argv，非 shell）、寫面（寫入 PR_DESCRIPTION.md）及外部服務（gh CLI）權限。所有命令執行採用固定 argv，不拼接 shell 字符串。
失敗邊界：當 diff 過大（DIFF_TOO_LARGE）、基線探測失敗或分類規則收斂失敗時，插件會返回結構化錯誤。
依賴前置：生產環境版本會盡量將 link: 依賴替換爲 npm registry 真實版本。

總結¶

dsh-pr-description 爲 DSH 開發者提供了一套標準化的 PR 描述生成流程。通過確定性規則而非大模型，保證了生成結果的可復現性和可控性，適合需要在 CI 或本地工作流中快速產出規範 PR 文檔的場景。更多細節可查看 GitHub 倉庫。