@namewta/speculo 0.1.0

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

@@ -0,0 +1,236 @@
+# 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 → 章节映射 |
+
+而仓库通常已经维护了 `CHANGELOGS.md`(Keep a Changelog 格式)。**正确做法是把 CHANGELOG 段落作为 Release 正文的事实来源**,自动生成器仅作为补充链接。
+
+## 2. 注入方案
+
+核心思路:在 workflow 里加一步,从 `CHANGELOGS.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 CHANGELOGS.md
+  run: |
+    VERSION="${GITHUB_REF_NAME#v}"
+    awk -v v="$VERSION" '
+      $0 ~ "^## \\["v"\\]" { found=1; print; next }
+      found && /^## \[/ { exit }
+      found && /^---[[:space:]]*$/ { next }
+      found { print }
+    ' CHANGELOGS.md > release-notes.md
+
+    if [ ! -s release-notes.md ]; then
+      echo "::warning::CHANGELOGS.md 中未找到 [$VERSION] 段落,回退到自动生成。"
+      echo "See [CHANGELOGS.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOGS.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 命令行(推荐)
+
+```bash
+# 一行命令:抽取 → 回填 → 清理
+VERSION="0.0.10"
+awk -v v="$VERSION" '
+  $0 ~ "^## \\["v"\\]" { found=1; print; next }
+  found && /^## \[/ { exit }
+  found && /^---[[:space:]]*$/ { next }
+  found { print }
+' CHANGELOGS.md > /tmp/notes.md && \
+  gh release edit "v$VERSION" --notes-file /tmp/notes.md && \
+  rm /tmp/notes.md
+```
+
+### 3.2 GitHub UI
+
+进入 `https://github.com/<owner>/<repo>/releases/tag/vX.Y.Z`,右上角铅笔图标 → 粘贴 CHANGELOG 段落 → Update release。
+
+### 3.3 批量回填多个历史版本
+
+```bash
+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 }
+  ' CHANGELOGS.md > /tmp/notes.md
+
+  if [ -s /tmp/notes.md ]; then
+    gh release edit "v$v" --notes-file /tmp/notes.md
+    echo "✓ v$v"
+  else
+    echo "✗ v$v: CHANGELOG 中无对应段落,跳过"
+  fi
+done
+rm -f /tmp/notes.md
+```
+
+## 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 > /tmp/en.md
+    awk -v v="$VERSION" "$EXTRACT" CHANGELOG-ZH.md > /tmp/zh.md
+
+    {
+      cat /tmp/en.md
+      echo
+      echo "---"
+      echo
+      echo "### 中文版本说明"
+      echo
+      cat /tmp/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/speculo/skills/github-npm-ops/references/release-pipeline.md

@@ -0,0 +1,108 @@
+# npm + GitHub Release 编排
+
+把一次 npm 包发布拆成可验证的单向流水线：前置检查 -> 普通改动 commit -> docs-sync -> release commit -> tag -> workflow 监控 -> 三端验证 -> docs-sync 基线推进。
+
+## Iron Law
+
+- 禁止提交破坏构建的代码；release 前必须运行仓库声明的 lint / test / build 或等价质量闸。
+- docs-sync 必须由调用方按 `workflows/dev/D-docs-sync/D-docs-sync.md` 执行，基于 `.speculo/dev/docs-sync-state.json#last_sync_sha..HEAD` 的 git diff。
+- 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`
+- `.speculo/dev/docs-sync-state.json` 存在且可解析；不存在时转 `dev/D-docs-sync` 首次运行流程
+- 目标 tag `vX.Y.Z` 不存在，除非正在执行明确的失败恢复
+
+任一项不通过就停止，输出修复建议。
+
+## Phase 1 — 普通改动 commit
+
+- 运行仓库质量闸：优先 `pnpm check`，否则按项目脚本组合 lint / test / build。
+- 审查提交粒度；不把无关修改塞进一个 commit。
+- 暂存显式路径，避免 `git add .` 纳入噪声。
+- 使用 Conventional Commits；body 说明做了什么和为什么。
+
+## Phase 2 — Docs Sync
+
+- 由调用方执行 `workflows/dev/D-docs-sync/D-docs-sync.md`。
+- 只修改 tracked docs 中需要同步的文档。
+- CHANGELOG 类文档只写 `[Unreleased]`，保留该段落。
+- 本阶段不推进 docs-sync state 到 release commit；最终基线推进放到 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 — 推进 docs-sync 基线
+
+仅当 Phase 1-5 全绿时执行。本 skill 不直接写 `.speculo/`；把基线推进交给调用方的 release workflow 或 `workflows/dev/D-docs-sync/D-docs-sync.md`，只向其提供以下取值：
+
+- `last_sync_sha` 推进到 `RELEASE_COMMIT_SHA`。
+- `previous_sync_sha` 使用推进前的 `last_sync_sha`。
+- `synced_docs` 使用 Phase 2 实际修改的文档列表；空同步为 `[]`。
+
+调用方把 state 推进作为 release tag 之后的普通 docs commit，tag 不移动；写入机制（原子写、schema 校验）由 D-docs-sync workflow 负责。
+
+## 完成报告
+
+报告至少包含：
+
+- 版本号、release commit SHA、tag SHA
+- workflow run id 与结论
+- GitHub Release 检查结果
+- npm 检查结果或跳过原因
+- docs-sync state old/new baseline
+- 失败恢复或后续建议

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

@@ -0,0 +1,63 @@
+# 配置 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，出问题可独立撤销