@namewta/speculo 1.0.18 → 1.0.20

package/template/skills/github-npm-ops/references/release-notes-injection.md

@@ -1,238 +0,0 @@
-# CHANGELOG → GitHub Release notes 注入
-
-让每次 `git push origin vX.Y.Z` 触发的 GitHub Release **正文非空**、**与 CHANGELOG 段落严格一致**的标准方案。
-
-## 1. 为什么 GitHub Release 默认是空的
-
-`softprops/action-gh-release@v2` 仅设 `generate_release_notes: true` 时,GitHub 内部调用的是 **REST API `POST /repos/{owner}/{repo}/releases/generate-notes`**,该接口的输入是「上一个 tag → 当前 tag」之间的 **commit + PR + label**,优先取 PR 标题做分类。
-
-两种典型场景下生成器会"贫瘠":
-
-| 场景 | 生成器输出 | 原因 |
-|------|----------|------|
-| 直 push main(无 PR 流程) | 仅 `Full Changelog: vA...vB` 一行 | 生成器没有 PR 可分类,只能给 compare 链接 |
-| 有 PR 但仓库没有 `.github/release.yml` | 全部 PR 都被塞进 "What's Changed" 一节 | 没有 label → 章节映射 |
-
-而仓库通常已经维护了 `CHANGELOG.md`(Keep a Changelog 格式)。**正确做法是把 CHANGELOG 段落作为 Release 正文的事实来源**,自动生成器仅作为补充链接。
-
-## 2. 注入方案
-
-核心思路:在 workflow 里加一步,从 `CHANGELOG.md` 抽取当前 tag 对应的版本段落,写到 `release-notes.md`,再通过 `softprops/action-gh-release` 的 `body_path` 注入。
-
-### 2.1 完整 workflow 步骤
-
-加到 `Verify bin entry` 之后、`Publish to npm` 之前(也可以放 publish 之后,只要在 Create GitHub Release 之前):
-
-```yaml
-- name: Extract release notes from CHANGELOG.md
-  run: |
-    VERSION="${GITHUB_REF_NAME#v}"
-    awk -v v="$VERSION" '
-      $0 ~ "^## \\["v"\\]" { found=1; print; next }
-      found && /^## \[/ { exit }
-      found && /^---[[:space:]]*$/ { next }
-      found { print }
-    ' CHANGELOG.md > release-notes.md
-
-    if [ ! -s release-notes.md ]; then
-      echo "::warning::CHANGELOG.md 中未找到 [$VERSION] 段落,回退到自动生成。"
-      echo "See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for details." > release-notes.md
-    fi
-
-    echo "--- Release notes preview ---"
-    cat release-notes.md
-    echo "-----------------------------"
-
-- name: Create GitHub Release
-  uses: softprops/action-gh-release@v2
-  if: success()
-  with:
-    tag_name: ${{ github.ref_name }}
-    name: Release ${{ github.ref_name }}
-    body_path: release-notes.md          # ← 关键
-    generate_release_notes: true         # ← 与 body_path 共存,不冲突
-    draft: false
-    prerelease: false
-  env:
-    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-```
-
-### 2.2 awk 抽取规则解释
-
-```awk
-$0 ~ "^## \\["v"\\]" { found=1; print; next }   # 1. 命中 "## [X.Y.Z]" 起始锚点,开关打开,打印当行
-found && /^## \[/ { exit }                       # 2. 已在段落内,遇到下一个 "## [" 立刻退出
-found && /^---[[:space:]]*$/ { next }            # 3. 跳过 "---" 分隔符(GitHub Release 不需要)
-found { print }                                  # 4. 段落内的其他行原样输出
-```
-
-边界用例:
-
-- **段落是 CHANGELOG 末尾**:没有下一个 `## [`,awk 跑到 EOF 自然结束
-- **存在 `[Unreleased]` 段落**:不会被误抓,因为锚点要求精确匹配 `[X.Y.Z]` 形式
-- **版本号含连字符(rc / beta)**:`0.0.10-rc1` 也能匹配,因为 awk 把 `v` 当字面量
-- **CHANGELOG 缺该段**:`-s` 测试为空 → 写入兜底文案 + 输出 warning
-
-### 2.3 `body_path` + `generate_release_notes` 共存语义
-
-`softprops/action-gh-release@v2` 在两者同时存在时:
-
-- **正文头部**:`body_path` 文件内容(你的 CHANGELOG 段落)
-- **正文尾部**:GitHub 自动生成的 "What's Changed" + "Full Changelog" compare 链接
-
-这是最优组合:**人写的精炼说明 + 机器可追溯的 PR/commit 索引**。
-
-## 3. 事后修复历史 Release(已发布版本正文为空)
-
-GitHub Release 的正文(body)**事后可改**(tag 不可改、npm 包不可改、但 Release body 可改)。两种方式:
-
-### 3.1 命令行(推荐)
-
-`notes_file` 只是一次性传给 `gh --notes-file` 的中间文件；若需要保留回填记录或 release notes，由调用方写入 `<Path>{roots.state}/commands/{command}/{date}-{scope}-{topic}[-NN].md</Path>`。
-
-```bash
-VERSION="0.0.10"
-notes_file="$(mktemp -t speculo-release-notes.XXXXXX)"
-trap 'rm -f "$notes_file"' EXIT
-
-awk -v v="$VERSION" '
-  $0 ~ "^## \\["v"\\]" { found=1; print; next }
-  found && /^## \[/ { exit }
-  found && /^---[[:space:]]*$/ { next }
-  found { print }
-' CHANGELOG.md > "$notes_file" && \
-  gh release edit "v$VERSION" --notes-file "$notes_file"
-```
-
-### 3.2 GitHub UI
-
-进入 `https://github.com/<owner>/<repo>/releases/tag/vX.Y.Z`,右上角铅笔图标 → 粘贴 CHANGELOG 段落 → Update release。
-
-### 3.3 批量回填多个历史版本
-
-```bash
-notes_file="$(mktemp -t speculo-release-notes.XXXXXX)"
-trap 'rm -f "$notes_file"' EXIT
-
-for v in 0.0.7 0.0.8 0.0.9; do
-  awk -v ver="$v" '
-    $0 ~ "^## \\["ver"\\]" { found=1; print; next }
-    found && /^## \[/ { exit }
-    found && /^---[[:space:]]*$/ { next }
-    found { print }
-  ' CHANGELOG.md > "$notes_file"
-
-  if [ -s "$notes_file" ]; then
-    gh release edit "v$v" --notes-file "$notes_file"
-    echo "✓ v$v"
-  else
-    echo "✗ v$v: CHANGELOG 中无对应段落,跳过"
-  fi
-done
-```
-
-## 4. 进阶:走 PR 流程的项目
-
-若仓库以 PR 为主、合并产生 commit,推荐 **同时**保留 CHANGELOG 注入 + 配置 `.github/release.yml` 让自动生成器分类更友好。
-
-### 4.1 `.github/release.yml`(GitHub 原生分类配置)
-
-```yaml
-# .github/release.yml
-changelog:
-  exclude:
-    labels:
-      - ignore-for-release
-      - dependencies      # 可选:依赖升级单独成节
-  categories:
-    - title: 🚀 Features
-      labels:
-        - feat
-        - feature
-        - enhancement
-    - title: 🐛 Bug Fixes
-      labels:
-        - fix
-        - bug
-    - title: 📚 Documentation
-      labels:
-        - docs
-        - documentation
-    - title: ♻️ Refactoring
-      labels:
-        - refactor
-    - title: 🧪 Testing
-      labels:
-        - test
-    - title: 🔧 Maintenance
-      labels:
-        - chore
-        - ci
-    - title: Other Changes
-      labels:
-        - "*"
-```
-
-效果:`generate_release_notes` 自动产出的 "What's Changed" 会被分类到上述章节中,与 CHANGELOG 段落叠加在 Release 正文内。
-
-### 4.2 配套的 PR label 自动化
-
-参考仓库已有 `.github/labeler.yml` + `.github/workflows/label-pr.yml`,基于改动路径自动打 label。也可让 PR 模板提示作者按 Conventional Commits 选择类型。
-
-## 5. 多语言 CHANGELOG 处理
-
-如果项目同时维护 `CHANGELOG.md` + `CHANGELOG-ZH.md`,Release 正文应优先取**主语言**(通常英文)。两种策略:
-
-### A. workflow 选择主语言(简单)
-
-```yaml
-- name: Extract release notes
-  run: |
-    # 主语言文件名作为输入
-    awk -v v="${GITHUB_REF_NAME#v}" '...' CHANGELOG.md > release-notes.md
-```
-
-### B. workflow 拼接双语(完整)
-
-```yaml
-- name: Extract release notes (bilingual)
-  run: |
-    VERSION="${GITHUB_REF_NAME#v}"
-    EXTRACT='$0 ~ "^## \\["v"\\]" { found=1; print; next } found && /^## \[/ { exit } found && /^---[[:space:]]*$/ { next } found { print }'
-
-    {
-      awk -v v="$VERSION" "$EXTRACT" CHANGELOG.md
-      echo
-      echo "---"
-      echo
-      echo "### 中文版本说明"
-      echo
-      awk -v v="$VERSION" "$EXTRACT" CHANGELOG-ZH.md
-    } > release-notes.md
-```
-
-## 6. 常见坑位
-
-| 坑 | 现象 | 解法 |
-|---|------|------|
-| `body_path` 文件不存在 | action 失败 `Could not find the body_path` | 加 `if [ ! -s release-notes.md ]` 兜底写入 |
-| awk 没匹配到 | release-notes.md 为空,Release 正文兜底文案 | 检查 CHANGELOG 段落标题与 tag 是否对应(`v0.0.10` ↔ `## [0.0.10]`) |
-| awk 多匹配(同一版本写了两次) | Release 正文重复内容 | CHANGELOG 是 source of truth,先去重 |
-| 全角中括号 `【】` 被当锚点 | 抽取失败 | CHANGELOG 标题统一用半角 `[` |
-| body_path 文件含 BOM | Release 渲染异常 | 用 `sed -i '1s/^\xef\xbb\xbf//' release-notes.md` 去 BOM |
-
-## 7. 验证
-
-每次发布后必查:
-
-```bash
-# Release body 必须非空且包含 CHANGELOG 关键章节
-gh release view "v$VERSION" --json body --jq '.body' | head -20
-
-# 三端齐绿才算发布完成
-npm view @scope/pkg version
-gh release view "v$VERSION" --json isDraft,isPrerelease,publishedAt
-gh run view <run-id> --json conclusion,jobs --jq '{conclusion, steps: [.jobs[].steps[] | select(.name | contains("Extract") or contains("Release")) | {name, conclusion}]}'
-```
-
-`Extract release notes` 步骤未 success → Release 正文将走兜底文案,需排查 awk 是否抽空。

package/template/skills/github-npm-ops/references/release-pipeline.md

@@ -1,108 +0,0 @@
-# npm + GitHub Release 编排
-
-把一次 npm 包发布拆成可验证的单向流水线：前置检查 -> 普通改动 commit -> docs-sync -> release commit -> tag -> workflow 监控 -> 三端验证 -> docs-sync 记录 release 节点。
-
-## Iron Law
-
-- 禁止提交破坏构建的代码；release 前必须运行仓库声明的 lint / test / build 或等价质量闸。
-- docs-sync 必须由调用方按 `<Path>{roots.commands}/docs-sync.md</Path>` 执行；输入起点来自最后修改 state 文件的 commit，终点是运行前清洁后的 HEAD，并写入 `last_range`。
-- tag 必须精确指向 release commit，即包含 `package.json` version bump 与 CHANGELOG 迁移的 commit；禁止指向后续 docs / state commit。
-- npm 已成功上传后，同一 version 不可重发；不要通过删 tag 或 unpublish 试图覆盖。
-
-## Phase 0 — 前置检测
-
-读取 `preflight-checklist.md` 和 `publish-detection.md`，固定确认：
-
-- 当前分支是发布分支，默认 `main`
-- 工作区干净，远端可达，`gh auth status` 正常
-- Node 与包管理器满足仓库声明
-- `.github/workflows/release.yml` 存在
-- 已确定 `PUBLISH_TO_NPM=true | false`
-- `<Path>{roots.state}/commands/docs-sync/state.json</Path>` 存在且可解析；不存在时转 docs-sync command 的首次 bootstrap
-- 目标 tag `vX.Y.Z` 不存在，除非正在执行明确的失败恢复
-
-任一项不通过就停止，输出修复建议。
-
-## Phase 1 — 普通改动 commit
-
-- 运行仓库质量闸：优先 `pnpm check`，否则按项目脚本组合 lint / test / build。
-- 审查提交粒度；不把无关修改塞进一个 commit。
-- 暂存显式路径，避免 `git add .` 纳入噪声。
-- 使用 Conventional Commits；body 说明做了什么和为什么。
-
-## Phase 2 — Docs Sync
-
-- 由调用方执行 `<Path>{roots.commands}/docs-sync.md</Path>`。
-- 只修改全局 state 与 workflow sidecar 已确认范围中需要同步的文档或知识资产。
-- CHANGELOG 类文档只写 `[Unreleased]`，保留该段落。
-- 本阶段由 docs-sync 自动提交文档、报告与 state；最终 release commit 仍在 Phase 3 创建，发布后再由 Phase 6 记录为新输入终点。
-
-## Phase 3 — 版本 bump + release commit + tag
-
-读取 `version-bump-flow.md`。
-
-- 将 CHANGELOG 的 `[Unreleased]` 内容迁移到 `## [X.Y.Z] - YYYY-MM-DD` 或项目既有等价格式，并重新保留空 `[Unreleased]`。
-- 将 `package.json#version` 改为 `X.Y.Z`；tag 使用 `vX.Y.Z`。
-- 运行质量闸；除非调用方明确记录外部预演证据，不跳过。
-- release commit 只包含版本 bump 与 CHANGELOG 迁移，提交信息为 `chore(release): vX.Y.Z`。
-- 记录 `RELEASE_COMMIT_SHA`。
-- 先 push 发布分支，再 `git tag vX.Y.Z $RELEASE_COMMIT_SHA`，再 push tag。
-
-## Phase 4 — 监控 release workflow
-
-用 `gh run list` 找到 head SHA 等于 `RELEASE_COMMIT_SHA` 的 release run，再 `gh run watch --exit-status`。
-
-重点检查：
-
-- Verify tag matches package version
-- lint / tests / build / bin entry
-- Extract release notes from CHANGELOG
-- Publish to npm（仅 `PUBLISH_TO_NPM=true`）
-- Create GitHub Release
-
-失败时进入 `failure-recovery.md` 和 `troubleshooting-playbook.md`。
-
-## Phase 5 — 三端验证
-
-始终验证：
-
-```bash
-gh release view "vX.Y.Z" --json name,tagName,isDraft,isPrerelease,body
-gh run list --workflow release.yml --limit 1 --json conclusion,headSha
-```
-
-判定：
-
-- Release 非 draft、非 prerelease
-- Release body 非空，且包含 CHANGELOG 段落；仅 `Full Changelog` 一行视为残缺
-- workflow conclusion 为 success，headSha 等于 `RELEASE_COMMIT_SHA`
-
-仅当 `PUBLISH_TO_NPM=true` 时验证：
-
-```bash
-npm view "<package-name>" version
-npm view "<package-name>" dist-tags
-```
-
-判定 version 与 `dist-tags.latest` 均为 `X.Y.Z`。
-
-## Phase 6 — 记录 release 输入节点
-
-仅当 Phase 1-5 全绿时执行。再次调用 `<Path>{roots.commands}/docs-sync.md</Path>`，并确认运行前 `HEAD` 等于 `RELEASE_COMMIT_SHA`：
-
-- state 的 `last_range.to_sha` 必须等于 `RELEASE_COMMIT_SHA`。
-- `last_range.from_sha` 来自最后修改旧 state 的 commit，或迁移期 explicit baseline。
-- docs-sync 写入 release 后报告/state commit；tag 继续精确指向 release commit，不移动。
-
-本 skill 不直接改 state 或 workflow sidecar；原子写入、范围检查和本地 commit 均由 docs-sync command 负责。
-
-## 完成报告
-
-报告至少包含：
-
-- 版本号、release commit SHA、tag SHA
-- workflow run id 与结论
-- GitHub Release 检查结果
-- npm 检查结果或跳过原因
-- docs-sync `last_range` 与 state-file baseline commit
-- 失败恢复或后续建议

package/template/skills/github-npm-ops/references/setup-npm-token.md

@@ -1,63 +0,0 @@
-# 配置 npm Token 与 GitHub Secret
-
-npm 现在强制要求发布时通过 2FA 或等效机制。Classic token 在多数账号设置下会返回 `E403`，必须改用 **Granular Access Token**。
-
-## 生成 Granular Access Token
-
-1. 登录 [npmjs.com](https://www.npmjs.com)，点头像 → **Access Tokens**
-2. 点 **Generate New Token** → 选择 **Granular Access Token**
-3. 关键字段：
-
-   | 字段                    | 推荐值                                                                                     |
-   | ----------------------- | ------------------------------------------------------------------------------------------ |
-   | Token name              | `<package>-ci-release`（可识别用途）                                                       |
-   | Expiration              | 90–365 天；设提醒到期前轮换                                                                 |
-   | Packages and scopes     | 选 `Only select packages and scopes`，勾选目标包或整个 scope（如 `@scope`）                |
-   | Permissions             | **Read and write**                                                                         |
-   | Allowed organizations   | 如果在组织下发布，勾选对应组织                                                             |
-   | Bypass two-factor auth  | 勾选（CI 无法交互完成 2FA）                                                                |
-   | Allowed IP ranges       | 留空（GitHub Actions runner IP 不固定）                                                    |
-
-4. 点 **Generate**，**立刻复制** token，关掉页面就再也看不到了
-
-## 配置到 GitHub Secret
-
-1. 仓库 → **Settings** → **Secrets and variables** → **Actions**
-2. 点 **New repository secret**
-3. `Name: NPM_TOKEN`，`Value: <粘贴 token>`
-4. 点 **Add secret**
-
-## 在 workflow 中引用
-
-```yaml
-- name: Publish to npm
-  run: npm publish --provenance --access public
-  env:
-    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-```
-
-重点：变量名必须是 `NODE_AUTH_TOKEN`（`actions/setup-node` 约定），不是 `NPM_TOKEN`。Secret 的名字可以是 `NPM_TOKEN`，但要映射过来。
-
-## 验证 token 生效
-
-本地不需要这个 token，它只在 CI 使用。如果想本地预演：
-
-```bash
-echo "//registry.npmjs.org/:_authToken=<token>" >> ~/.npmrc
-npm whoami   # 应返回你的 npm 用户名
-npm publish --dry-run --access public
-```
-
-预演完记得把 `.npmrc` 里的这行删掉。
-
-## 轮换策略
-
-- Token 到期前 7 天收到邮件提醒
-- 轮换步骤：生成新 token → 更新 GitHub Secret → 在 npm 上 revoke 旧 token
-- 如果怀疑泄露：立即在 npm Access Tokens 页面点 **Revoke**，workflow 会在下次运行时失败，再补生成新 token
-
-## 常见误区
-
-- **不要用 Classic Token 的 `Automation` 类型** — 某些账号策略下仍会触发 2FA 检查
-- **不要把 token 写进 `.npmrc` 提交** — 只能走 `secrets`
-- **不要与个人 publish token 混用** — CI 用专用 token，出问题可独立撤销

package/template/skills/github-npm-ops/references/troubleshooting-playbook.md

@@ -1,293 +0,0 @@
-# Release 故障排查手册
-
-基于真实失败记录的排查流程。遇到问题先按这个顺序走。
-
-## 统一诊断流程
-
-```bash
-# 1. 找到失败的 run
-gh run list --workflow release.yml --limit 5 \
-  --json databaseId,conclusion,displayTitle
-
-# 2. 查看失败步骤的日志
-gh run view <databaseId> --log-failed 2>&1 \
-  | grep -E "npm error|npm warn publish|##\[error\]|Error:" \
-  | head -30
-
-# 3. 按下面的错误表对应修复
-```
-
-## 错误分类与修复
-
-### 1. `E404 Not Found - PUT /<pkg>`
-
-```
-npm error code E404
-npm error 404 Not Found - PUT https://registry.npmjs.org/my-cli
-npm error 404  The requested resource 'my-cli@0.0.2' could not be found
-              or you do not have permission to access it.
-```
-
-**两种原因：**
-
-- **包名被占用**：别人已注册这个名字，你没权限写入
-- **私有包但未创建 scope/org**：scope 不存在
-
-**诊断：**
-
-```bash
-npm view <pkg-name>              # 有内容说明被占
-npm owner ls <pkg-name>          # 看当前 owner
-```
-
-**修复：**
-
-- 改用 scoped 包名：`@yourname/pkg-name`
-- 同步更新 `package.json` 的 `name` 字段
-- 若要用现有名字：联系当前 owner 做 transfer，或走 `npm support`
-
-### 2. `E403 Two-factor authentication required`
-
-```
-npm error code E403
-npm error 403 403 Forbidden - PUT https://registry.npmjs.org/@scope%2fmy-cli
-              - Two-factor authentication or granular access token
-              with bypass 2fa enabled is required to publish packages.
-```
-
-**原因：** 使用了 Classic Token 或未开启 2FA bypass 的 Granular Token。
-
-**修复：**
-
-1. npm → Access Tokens → **Generate New Token** → **Granular Access Token**
-2. 勾选 **Bypass two-factor authentication**
-3. 选择目标包或 scope，permission 为 **Read and write**
-4. 复制新 token，更新 GitHub Secret `NPM_TOKEN`
-5. 重新触发 workflow（删旧 tag 重推）
-
-详见 [setup-npm-token.md](./setup-npm-token.md)。
-
-### 3. `EUSAGE Can't generate provenance for new or private package`
-
-```
-npm error code EUSAGE
-npm error Can't generate provenance for new or private package,
-          you must set `access` to public.
-```
-
-**原因：** Scoped 包默认 private，首次发布未加 `--access public`。
-
-**修复：**
-
-```yaml
-- run: npm publish --provenance --access public
-```
-
-### 4. `E422 Error verifying sigstore provenance bundle`
-
-```
-npm error code E422
-npm error 422 Unprocessable Entity - PUT https://registry.npmjs.org/@scope%2fmy-cli
-              - Error verifying sigstore provenance bundle:
-              Failed to validate repository information:
-              package.json: "repository.url" is "", expected to match
-              "https://github.com/owner/my-cli" from provenance
-```
-
-**原因：** `package.json` 缺 `repository.url`，或值与实际 GitHub 仓库不匹配。
-
-**修复：**
-
-```json
-{
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/owner/my-cli"
-  }
-}
-```
-
-- URL 不要带 `.git` 后缀也能通过（npm 会归一化）
-- 注意大小写：虽然 GitHub 不区分，但 provenance 严格校验，保持与 workflow 运行环境一致
-
-### 5. `Tag version does not match package.json version`
-
-```
-Tag version (0.0.2) does not match package.json version (0.0.1)
-```
-
-**原因：** 打 tag 前忘记 bump `package.json`，或 bump 后没 commit。
-
-**修复：**
-
-```bash
-# 删除错误 tag
-git tag -d v0.0.2
-git push origin :refs/tags/v0.0.2
-
-# 修复 package.json
-npm version 0.0.2 --no-git-tag-version    # 只改文件，不打 tag
-git add package.json && git commit -m "chore: bump version to 0.0.2"
-git push origin main
-
-# 重新打 tag
-git tag v0.0.2
-git push origin v0.0.2
-```
-
-### 6. `npm warn publish "bin[name]" script name ... was invalid and removed`
-
-```
-npm warn publish "bin[my-cli]" script name dist/cli/index.js was invalid and removed
-```
-
-**原因：** `bin` 路径没有 `./` 前缀，或 npm 版本对该路径格式敏感。
-
-**修复：** 确认 `package.json` 已经是 `"./dist/cli/index.js"`。如果已经正确但警告仍在，可能是 npm 的误报——检查 npm publish 最终有没有返回 `+ @scope/pkg@version`，有就成功了。
-
-### 7. Workflow 根本没触发
-
-**诊断：**
-
-```bash
-gh run list --workflow release.yml --limit 3
-# 如果最新的那个不在列表里，就是没触发
-```
-
-**原因：**
-
-- Tag 名不匹配 `v*` 模式
-- Tag 已存在，再次 push 被 Git 拒绝
-- 仓库关闭了 Actions
-
-**修复：**
-
-```bash
-# 确认 tag 推到远端了
-git ls-remote --tags origin | grep v0.0.2
-
-# 如果旧 tag 残留，先删
-git tag -d v0.0.2
-git push origin :refs/tags/v0.0.2
-
-# 重新打
-git tag v0.0.2
-git push origin v0.0.2
-```
-
-### 8. 安装 pnpm 或 Node 失败
-
-```
-Error: Unable to find 'pnpm' executable
-```
-
-**修复：** 在 setup 里加：
-
-```yaml
-- uses: pnpm/action-setup@v2
-  with:
-    version: 9     # 匹配 packageManager 字段或 lockfile 格式
-```
-
-如果 `package.json` 里写了 `packageManager: "pnpm@9.x.x"`，`pnpm/action-setup` 可不传 `version`，它会自动读取。
-
-### 9. `npm ERR! 403 Forbidden - PUT` 但 token 正常
-
-可能是包名大小写问题。npm 内部是小写，但 `package.json` 里写了大写：
-
-```json
-{ "name": "MyCli" }     // ❌
-{ "name": "my-cli" }    // ✅
-```
-
-### 10. GitHub Release 正文为空 / 仅一行 `Full Changelog`
-
-```
-Release v0.0.10 (Latest)
-Full Changelog: v0.0.9...v0.0.10
-[Source code (zip)] [Source code (tar.gz)]
-```
-
-**原因**：`softprops/action-gh-release@v2` 只设了 `generate_release_notes: true`，而 GitHub 自动生成器从 PR 标题 + label 抽取 changelog。直 push main 的仓库没有 PR 流量，生成器只剩 compare 链接可写。
-
-**修复（workflow 改造）**：在 Create GitHub Release 之前加一步从 `CHANGELOG.md` 抽取段落，再用 `body_path` 注入。完整 YAML 见 [workflow-yaml-reference.md](workflow-yaml-reference.md) 的 `Extract release notes from CHANGELOG.md` 步骤；模式说明见 [release-notes-injection.md](release-notes-injection.md)。
-
-**修复（事后回填历史 Release，无需重发版）**：按 [release-notes-injection.md](release-notes-injection.md) 抽取 CHANGELOG 段落，再 `gh release edit "v$VERSION" --notes-file "$notes_file"`。
-
-**诊断**：
-
-```bash
-# Release body 长度过短就是出问题了
-gh release view v0.0.10 --json body --jq '.body | length'
-
-# workflow 里 Extract release notes 步骤是否存在并 success
-gh run view <run-id> --json jobs \
-  --jq '.jobs[].steps[] | select(.name | test("Extract|Release"))'
-```
-
-### 11. `Extract release notes` 步骤报 "release-notes.md is empty"
-
-**根因**：CHANGELOG 段落标题与 tag 不匹配，awk 抽空。
-
-**自查**：
-
-```bash
-# 实际 CHANGELOG 标题
-grep '^## \[' CHANGELOG.md | head -5
-
-# 当前 tag 应当对应的标题
-echo "## [${GITHUB_REF_NAME#v}]"
-```
-
-常见问题：
-
-- 全角中括号 `【0.0.10】` 而非半角 `[0.0.10]`
-- 版本号有 `v` 前缀（`## [v0.0.10]`）— awk 期望去前缀的纯数字
-- 段落写错位置（`[Unreleased]` 段还没迁移到正式版本段）
-
-## 发布成功但找不到包
-
-典型场景：workflow 显示绿色，但 `npm view @scope/pkg` 返回 404。
-
-- **传播延迟**：npm CDN 有 30–60 秒缓存延迟，等一下再查
-- **日志确认**：`gh run view <id> --log | grep "+ @scope"`——有 `+ @scope/pkg@version` 才算真的成功
-- **provenance 页面**：https://search.sigstore.dev/ 能查到签名日志
-
-```bash
-# 等待 + 轮询
-for i in {1..10}; do
-  npm view @scope/my-cli version 2>/dev/null && break
-  sleep 10
-done
-```
-
-## 已发布但需要撤回
-
-npm **24 小时内**可以 `unpublish`（仅限无依赖项）：
-
-```bash
-npm unpublish @scope/my-cli@0.0.2
-```
-
-超过 24 小时或有依赖者只能 `deprecate`：
-
-```bash
-npm deprecate @scope/my-cli@0.0.2 "Security issue, use 0.0.3+"
-```
-
-**npm 不允许重发同一个 version**——即使 unpublish 过了。必须 bump 版本号。
-
-## 排查 checklist
-
-按顺序检查，90% 的问题在前三项：
-
-1. [ ] `NPM_TOKEN` 是 Granular Token、bypass 2FA、包含目标 scope 的 read+write
-2. [ ] `package.json` 有 `repository.url` 且匹配 GitHub repo
-3. [ ] Workflow 含 `permissions: id-token: write` 和 `--access public`
-4. [ ] Tag 版本与 `package.json` version 字符一致
-5. [ ] Publish step 在 Release step 之前
-6. [ ] Workflow 触发器是 `on.push.tags: ['v*']`，没写 branches
-7. [ ] `bin` 路径以 `./` 开头
-8. [ ] `files` 字段不排除构建产物
-9. [ ] **Workflow 包含 `Extract release notes from CHANGELOG.md` 步骤，且 `Create GitHub Release` 设了 `body_path: release-notes.md`**
-10. [ ] **CHANGELOG.md 顶部有当前版本对应的 `## [X.Y.Z]` 段落（半角中括号）**