前言¶

在 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