ci: GitHub Release 自动触发 npm 发版（Trusted Publishing）

- 新增 .github/workflows/release.yml：release published 事件触发，校验 tag 与 package.json 版本一致后 pnpm publish --provenance - 认证走 npm Trusted Publishing（OIDC），无需 NPM_TOKEN secret - workflow_dispatch 提供 dry_run 调试入口（只打包不发版） - AGENTS.md 补充发版流程与 npm 后台一次性配置说明
2026-08-17 00:12:29 +08:00
parent 8d9ab1cd2f
commit 6f52aa79d2
2 changed files with 106 additions and 0 deletions
@@ -0,0 +1,97 @@
+name: Release
+
+# Publishes `dsh-better-sidebar` to npm via npm Trusted Publishing (OIDC) —
+# no NPM_TOKEN secret required, provenance is attached to the tarball.
+#
+# Trigger: a GitHub Release is published (tag vX.Y.Z). The tag MUST match
+# package.json `version`; the workflow verifies this before publishing.
+#
+# One-time npm-side setup (manual, on npmjs.com):
+#   1. package `dsh-better-sidebar` -> Settings -> Publishing access
+#      -> Trusted Publishers -> "Add Trusted Publisher".
+#   2. Provider: GitHub Actions
+#      Organization or user: omdsh-dev
+#      Repository:           DSH-better-sidebar
+#      Workflow filename:    release.yml
+#      Environment:          (blank)
+#   3. Save. Do NOT add an NPM_TOKEN secret — Trusted Publishing replaces it.
+# Canonical reference: https://docs.npmjs.com/trusted-publishers
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: Pack and verify everything, but do not publish
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+  id-token: write  # mint the OIDC token npm Trusted Publishing exchanges
+
+concurrency:
+  group: npm-release
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: build · verify · publish
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # Tests run git log against this repository and need full history.
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v6
+        with:
+          version: 11
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+          cache: pnpm
+
+      # The plugin's git revert/cherry-pick spawn git without an identity
+      # (see tests/smoke.spec.ts); the runner has none by default.
+      - name: Configure git identity for tests
+        run: |
+          git config --global user.name "dsh-better-sidebar-ci"
+          git config --global user.email "ci@dsh.invalid"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Verify release tag matches package.json version
+        if: github.event_name == 'release'
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          expected="v$(node -p "require('./package.json').version")"
+          echo "package.json version: ${expected#v}"
+          echo "release tag:          ${RELEASE_TAG}"
+          if [ "${RELEASE_TAG}" != "${expected}" ]; then
+            echo "::error::Release tag ${RELEASE_TAG} does not match package.json version ${expected#v} (expected ${expected})."
+            exit 1
+          fi
+
+      - name: Build
+        run: pnpm build
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Test
+        run: pnpm test
+
+      - name: Dry-run publish (validation only)
+        if: github.event_name == 'workflow_dispatch' && github.event.inputs.dry_run == 'true'
+        run: pnpm publish --dry-run --no-git-checks
+
+      - name: Publish to npm
+        if: github.event_name == 'release' || github.event.inputs.dry_run != 'true'
+        run: pnpm publish --provenance --access public --no-git-checks
@@ -23,6 +23,15 @@ better-sidebar 从 v0.4.0 起暴露 `ctx.betterSidebar` 服务（Cordis context

 本地跑：`pnpm build && pnpm pack && pnpm exec playwright install chromium && pnpm test:mount`（需 PATH 上有 `dsh` 或可经 npx 拉取）。DSH CLI 版本在 CI 钉住 `@deepseek-ai/dsh@0.1.0-rc.6`（与插件 peer 范围同步）。`tests/e2e` 的 spec 命名 `*.e2e.ts` + vitest `exclude` 双保险与 vitest 隔离；**改动 vitest `exclude` 时必须保留默认排除项**（`exclude` 会整体替换默认值）。

+### npm 发版（GitHub Release → npm publish）
+
+`.github/workflows/release.yml` 在 GitHub Release 发布（tag `vX.Y.Z`）时自动发版到 npm：
+
+1. **发版前置**：`package.json` 版本号 bump 到 `X.Y.Z`（manifest 一致性守卫会校验其它副本），CI 全绿后打 tag `vX.Y.Z` 并发布 GitHub Release。tag 必须与 package.json 版本一致——workflow 在发布前校验，不匹配直接失败、不发版。
+2. **流程**：workflow 依次执行 `pnpm build` / `pnpm typecheck` / `pnpm test`，校验 tag，然后 `pnpm publish --provenance --access public`（`prepublishOnly` 会重建产物；产物带 provenance 签名）。
+3. **认证**：走 npm **Trusted Publishing（OIDC）**，不需要也不应配置 `NPM_TOKEN` secret。一次性手动配置（在 npmjs.com 完成）：package `dsh-better-sidebar` → Settings → Publishing access → Trusted Publishers → Add Trusted Publisher，字段为 Provider `GitHub Actions`、Organization `omdsh-dev`、Repository `DSH-better-sidebar`、**Workflow filename `release.yml`**、Environment 留空。未配置前发布会失败（OIDC 交换报错），配置后无需改 workflow。
+4. **调试**：`workflow_dispatch` 手动触发 + `dry_run=true` 只打包验证、不发版。
+
 ---

 ## 1. 服务定位