# 发布规范

发布由 `.github/workflows/publish.yml` 自动执行。GitHub Release 发布后，流水线依次运行守卫、构建、发布三段。

## 版本策略

- `package.json` 的 `version` 是唯一版本源。tag 名、GitHub Release、npm 版本由它派生。
- 版本号遵循语义化版本。0.x 阶段：`minor` 为破坏性变更或新增能力；`patch` 为缺陷修复。宿主（DSH GUI）集成验证通过后升 `1.0.0`。
- 正式发布版本号不含预发布后缀。预发布版本（`X.Y.Z-rc.N`）由维护者本地执行 `npm publish --tag next`。
- 仅文档变更合入主干，随下一个版本发布。

## 运行环境

- runner `ubuntu-24.04`；Node 22；pnpm 9；npm 11（发布段）；ffmpeg/ffprobe 由 apt 安装。
- 权限最小化：顶层无权限；仅发布段持 `id-token: write`。
- 同一 Release 至多一个发布流程（concurrency）。
- 超时：守卫 5 分钟，构建 20 分钟，发布 10 分钟。

## 三段流水线

| 段 | 权限 | 内容 |
| --- | --- | --- |
| 守卫 | contents: read | tag 等于 `v{version}`；版本号无预发布后缀；Release 非 draft、非 prerelease；tag 提交在 `main` 历史内 |
| 构建 | contents: read | 构建 → 包内容白名单审计 → `npm pack` 产出 tarball → 上传 artifact → 全量测试（含 e2e）→ 宿主契约自检 |
| 发布 | id-token: write | 下载同一 tarball → `npm publish --provenance` → 发布后验证 |

发布物唯一来源是构建段产出的 tarball。发布段只发布该 tarball。

## 包内容与发布后验证

- 包内容白名单：`package.json` 的 `files` 数组。审计脚本 `scripts/check-package.mjs`。
- 发布后验证（流水线内置）：`scripts/verify-release.mjs` 直查 registry 元数据，确认精确版本存在且 `dist-tags.latest` 指向该版本。观察窗口 5 分钟。provenance 以发布日志中 transparency log 链接为准。
- 发布步骤对 workflow 重跑幂等：registry 已存在该版本时跳过 `npm publish`，只执行验证。

## 环境绑定

npm Trusted Publisher 与 workflow 两侧的 Environment 设置必须一致。当前两侧均为空。

## 发布步骤

1. `main` 升版本并推送：

   ```powershell
   npm version patch   # 或 minor
   git push --follow-tags
   ```

2. 等待该提交 CI 绿。
3. GitHub → Releases → Draft a new release：tag 填 `v{版本}`，目标选升版提交，填写变更要点，Publish release。
4. 流水线自动执行三段；Actions 页面复核全绿。
5. npm 页面复核版本、latest 标签与 provenance 徽标。

## 失败处理

发布前失败（npm 上无该版本）：

1. 修复缺陷并合入 `main`。
2. 删除该 Release 与 tag。
3. 版本号升 patch，重新发布。tag 不改指向，失败版本号作废。

已发布缺陷：

1. `npm deprecate dsh-pf-stream@{版本} "原因"`。
2. 发新 patch 版本。npm 已发布版本固定，不可覆盖或删除。

## 审计

每个正式版本对应：npm 版本 = tag `v{版本}` = 升版提交 = CI 构建的 tarball。provenance 证明构建来源。发布历史在 Releases、Actions、npm attestations 三处可交叉核对。