前言¶

在 DSH 裏發佈項目或插件時，發版前常要人肉覈對幾件事：package.json 是否改過、鎖文件是否同步；CHANGELOG 是否還是上一版；下載頁或站點頁面是否寫着舊版本號；流水線裏是否還硬編碼着 RELEASE_VERSION=0.9.0。漏掉其中一項，用戶裝上後纔會發現版本對不上，或商店頁顯示上個月的號。

下面介紹 feely0208/dsh-release-guard（npm 包名 @deepwhale-cn/dsh-release-guard）。它把“現在能不能發、還差什麼”變成一條命令，每項檢查給出結論和證據。DSH 社區目錄是獨立站點，與 DeepSeek / 幻方無官方從屬關係。

這是什麼¶

一句話定位：發版前的一致性檢查工具，不判斷代碼質量，也不跑測試或構建，只判斷髮版元數據和文件是否自洽。

倉庫爲 feely0208/dsh-release-guard，包名爲 @deepwhale-cn/dsh-release-guard。README 的 package.json 顯示當前版本 0.1.0，許可證爲 MIT，要求 dsh >=0.1.0-rc.6 <0.3.0、node >=18。

核心能力¶

它做六項檢查：

1、版本一致性：package.json 與 npm 系鎖文件之間的版本是否一致。
2、tag 與遠端狀態：依據本地已有的 origin/<branch> 引用判斷，不做 git fetch。
3、CHANGELOG / 更新說明：檢查是否覆蓋當前版本。
4、站點 / 前端文件版本號：按 siteVersionGlobs 命中文件中的 x.y.z 字面量判斷。
5、發版流水線硬編碼：檢查是否存在自己漏改的舊版本族字面量。
6、可選 registry 檢查：加 --npm 時額外請求一次 registry，且只讀。

輸出有三種：人讀文本；--json 機器可讀；退出碼 0 可發、1 有阻斷、2 只有警告，可直接接進 CI 或發版腳本。

判據可通過倉庫根目錄的 .release-guard.json 配置，不用改代碼，也不寫死任何項目路徑。默認行爲只讀本機 git，不聯網；只有加 --npm 才請求 registry。裝好後，側欄會出現「深鯨發版守衛」面板，填倉庫路徑點檢查，逐項列出證據與建議動作。

安裝與啓用¶

README 給出的安裝命令是：

dsh plugin --profile web add @deepwhale-cn/dsh-release-guard

這條命令會以 web profile 安裝插件。裝好後，側欄出現「深鯨發版守衛」面板；也可以直接走命令行。無需手動拼接 dsh plugin add github:owner/repo。

典型用法¶

命令行用法如下：

dsh-release-guard /path/to/repo          # 人讀
dsh-release-guard /path/to/repo --json   # 機器可讀
dsh-release-guard /path/to/repo --npm    # 額外查 registry（聯網）
echo $?                                  # 0 可發 / 1 有阻斷 / 2 只有警告

上面四條命令分別對應人讀輸出、機器可讀輸出、額外聯網檢查、讀取退出碼。--npm 是唯一會聯網的路徑，且只請求一次 registry。

判據怎麼配¶

默認值只寫通用約定，不認識任何具體項目。倉庫根目錄可放 .release-guard.json，字段與 README 示例一致：

{
  "versionFile": "package.json",
  "lockFiles": ["package-lock.json", "npm-shrinkwrap.json"],
  "changelog": "CHANGELOG.md",
  "notesFiles": ["assets/whatsnew.json", "whatsnew.json"],
  "siteVersionGlobs": ["index.html", "docs/**/*.html", "public/**/*.html"],
  "workflowGlobs": [".github/workflows/*.yml", ".github/workflows/*.yaml"],
  "tagPrefixes": ["v", ""],
  "ignoreDirs": ["node_modules", ".git", "dist", "build", "out", ".next", "coverage", "vendor"]
}

不用 CHANGELOG 的倉庫，可以把 changelog 設爲 null。站點版本文件在別處，改 siteVersionGlobs，glob 支持 **、*、?。只認 1.2.3 不認 v1.2.3，把 tagPrefixes 改成 [""]；兩種都認就保留默認值。

自測¶

倉庫自帶的自測命令是：

bash tests/run.sh

README 說明會構造三個臨時倉庫 fixture，不碰本機真實倉庫，也不聯網。乾淨倉庫必須 0 阻斷、0 警告；髒倉庫必須至少 3 個阻斷，且證據帶具體版本號；只有警告的倉庫退出碼必須是 2。

適用場景與注意¶

適合想在發版前把“還差什麼”固定成機器可讀結論的維護者，也適合想把檢查塞進 CI 的場景。它不判斷代碼質量、不跑測試、不構建，只檢查發版元數據與文件是否自洽。

需要注意，插件會以當前 dsh 進程的權限運行，裝前應檢查源碼與許可證。倉庫 package.json 標明 MIT，但不同倉庫的實際分發內容仍需自行覈對。它默認只讀本機 git，不做 git fetch；遠端是否已推送只能依據本地已有的 origin/<branch> 引用，沒 fetch 過會給出警告而不是猜。

其他邊界：流水線硬編碼按版本族判定，只報自己漏改的舊版本，當前 1.0.64 時，只把 1.0.x 的舊字面量算阻斷，其他版本族如 electron 43.4.0、隨包運行時 0.2.0-rc.2 會忽略；純註釋行、@v4.1.0 這類 action 引用、node-version / DSH_ / runtime 等運行時行也會被跳過。更新說明支持條目數組、versions、releases、頂層平鋪等形狀，_comment 之類以 _ 開頭的鍵忽略。鎖文件當前只解析 npm 系的 package-lock.json / npm-shrinkwrap.json；pnpm、yarn 鎖定結構可按需擴展 lockFiles，當前不解析。README 也聲明使用者須遵守所在地區法律法規，並對使用後果自行承擔責任。

結尾¶

它的價值不在於替團隊做發佈決策，而在於把發版前最容易漏掉的版本一致性檢查變成一條命令、一份證據和三個可接進腳本的退出碼。

目錄頁：https://www.skillhub.cn/plugins/feely0208/dsh-release-guard

GitHub：https://github.com/feely0208/dsh-release-guard