dsh-gokifu-compact 1.11.3 → 1.11.5

package/CHANGELOG.md

@@ -1,5 +1,86 @@
 # 更新记录
 
+## 1.11.5 — 2026-10-31
+
+### S10d · 测试运行器终于能区分「跳过」与「通过」，「空壳用例」不再是绿的
+
+**问题**：旧 `run.mjs` 里，平台/权限不对时用 `return` 早退，**会计入 passed** —— 单看
+「N passed」根本排除不了跳过；而且一个**一条断言都没有**的用例也会静默算通过。
+
+**改法**
+
+| 能力 | 说明 |
+|---|---|
+| `t.skip(reason)` | 计入 `skipped`，不计 pass/failed；**exit code 只由 failed 决定** |
+| 汇总行 | `== N passed, M skipped, K failed ==`（新增中间那段，跳过不再藏在 passed 里） |
+| **零断言检测** | `assertions === 0` **且**源码里没有 `throw` / `assert` 证明 ⇒ 计入 `zeroAssertions` 并**按失败处理**。本仓 300+ 用例是 throw 风格（算有证明），空壳用例从此不再静默算 pass |
+| `--dir=` | 仅供 `run-skip` 夹具指向临时目录 |
+
+- **`install-link` 6 处平台/权限早退改为 `t.skip(...)`**，原有断言一字未改。
+- 新增 `test/run-skip.test.mjs` **3 条**：四态（pass/fail/skip/零断言）可区分、skip 不导致失败、零断言严格红。
+
+**变异自检**：删掉 skip 分支 ⇒ `run-skip` 红；删掉零断言检测 ⇒ `run-skip` 红。
+
+### 验证
+
+- 全量：**476 passed / 0 failed / 0 skipped**（36 个测试文件；473 + 3）
+- `install-link` **29/0** · `run-skip` **3/0** · `rooms` 15/0 · `verify-install` **16/16**
+- `bench 2000`：**351 tokens**（与基线一致）
+- `npm pack --dry-run --json`：**71 文件**（数量不变，只改 `test/`）
+
+**未验证**
+
+- 零断言检测只认 `assertions` 计数与 `throw`/`assert` 的**文本证据**：如果一个用例用别的方式实打实地检查了东西（例如把结果写进外部文件再断言），仍可能被误判 —— 目前本仓没有这种写法。
+- `skipped` 总数现在是 0（本机 Windows）。**跨平台**（Linux/macOS 上那 6 条会真的 skip）没有实跑过。
+
+## 1.11.4 — 2026-10-31
+
+### 发布脚本加固：坏 remote 在预演阶段就红，git 步骤事务化
+
+**背景是一起真实事故**：1.11.3 发布时 `scripts/release.mjs --yes --npm` 返回 **EXIT 1** ——
+仓库 `remote.origin.url` 被写成 `git+https://…`（那串正是 `package.json` 的 `repository.url`，
+在 npm 里是规范写法，**但不是合法的 git remote**）。旧体检用正则匹配 `github.com:` 照样通过；
+真做时 `git push` 全崩，**而脚本继续建 Release、继续 `npm publish`**，留下
+「npm 已发 / Release 已建 / main 没推 / tag 指向旧 commit」的半途状态。
+
+**新增 `scripts/release-lib.mjs`**（纯逻辑、可单测、零副作用）
+
+| 导出 | 作用 |
+|---|---|
+| `parseRepo(url)` | 只认 scp 式 `git@github.com:o/r(.git)`、`ssh://git@github.com/o/r`、`https://github.com/o/r`；`git+*`、`file://`、非 GitHub、空 → `null` |
+| `classifyRemote(url)` | **先判 scheme 再判仓库**；`git+…` 直接拒，并给出可执行的修法（`git remote set-url origin git@github.com:<owner>/<repo>.git`） |
+| `runTransaction(steps)` | 顺序执行 + **首步失败即中止**，返回 `{ok, done, failed, error, aborted}` |
+
+**`scripts/release.mjs` 体检从 5 项增到 8 项**
+
+- ⑤ **remote 必须是合法 GitHub URL**（不再「正则匹配到 github.com 就算过」）
+- ⑥ **`git ls-remote --heads origin` 必须成功** —— 远端不可达直接红
+- ⑦ **`git fetch` 失败从 note 改成 red** —— 旧版把「不知道远端正不正常」当成「跳过检查继续发版」
+- ⑧ **tag 已存在时区分两种情况**：指向本 commit ⇒「不能发两次」；**指向别的 commit**（1.11.3 的现场：Release API 自动建了轻量 tag）⇒ **不自动 force**，报错并给 `git push --force origin refs/tags/<tag>:refs/tags/<tag>` 的人工修法
+
+**真做改成事务**：`runTransaction([push 分支, tag -a && push tag])` → 任一失败即 `abort()`，
+打印「已完成 / 未执行：tag · npm · Release」；**`npm publish` 移到 Release 之前** ——
+npm 失败就不建 Release（避免「Release 说有、npm 上没有」）；Release 失败仍 exit 1。
+
+**`scripts/check-maintenance.mjs` 也补了两项**（日常维护就能提前发现）
+
+- ⑧ `remote.origin` 必须是合法 GitHub URL（复用 `classifyRemote`，同一份判据）
+- ⑨ `git rev-parse --show-toplevel` 必须等于 cwd（防串仓 —— `ROOT` 取 `process.cwd()`，
+  在子目录或别人的仓库里跑会把版本号/CHANGELOG/tag 写错对象而看起来一切正常）
+
+**验证**
+
+- 全量：**473 passed / 0 failed**（36 个测试文件；463 + 10 条 `release-hardening`）
+- `check-maintenance`：**9 项**
+- `npm pack --dry-run --json`：**71 文件**（70 + `scripts/release-lib.mjs`；`release.mjs` 运行时依赖它，必须随包）
+- **预演**：release-ready 的临时克隆上 `node scripts/release.mjs` → **EXIT 0**；
+  同一克隆把 remote 换成 `git+https://…` → **EXIT 1**，报错点名协议并给修法
+
+**未验证**
+
+- 未改 `.github/workflows/release.yml`（存在时脚本走「推 tag 自动建 Release」分支，本次未触碰）。
+- `check-maintenance` 的 ⑧ 只判 URL 形状，**不探远端可达性**（保持「不需要网络」的定位；可达性由 `release.mjs` 的 ⑥ 在发版时把关）。
+
 ## 1.11.3 — 2026-10-31
 
 ### P0-1 · `exit` 判据收紧：不再被正文子串误判

package/README.md

@@ -1,6 +1,6 @@
 # dsh-GOkifu-compact
 
-> 当前版本：**`1.11.3`** · npm [`dsh-gokifu-compact`](https://www.npmjs.com/package/dsh-gokifu-compact) · [GitHub Releases](https://github.com/MYCF711/dsh-GOkifu-compact/releases) · 更新记录见 [CHANGELOG.md](CHANGELOG.md)
+> 当前版本：**`1.11.5`** · npm [`dsh-gokifu-compact`](https://www.npmjs.com/package/dsh-gokifu-compact) · [GitHub Releases](https://github.com/MYCF711/dsh-GOkifu-compact/releases) · 更新记录见 [CHANGELOG.md](CHANGELOG.md)
 
 **DSH 的棋谱式上下文压缩后端 —— 把「历史 → 一段摘要」换成「历史 → 可复盘的棋谱 DAG + 每步只有 351 tokens 的热清单」。**
 
@@ -8,7 +8,7 @@
 热清单     351 tokens       （2000 边合成夹具 · L5 降级档 · 2026-10-30/10-31 两次实测同值；旧版全量 28,800）
 失败保留   8 / 8            （历史口径 †；官方 8 段模板 4.67 / 8）
 清单开销   未复现/待测       （原载 0.2% = 历史单会话 v1.3.1 后实测；无复跑命令、无对照组；源 evidence/真实计费核对.md）
-验证       463 项单测 · 真实包 8/8 † · 真实进程 fold 3~6/6 †
+验证       476 项单测（0 skipped） · 真实包 8/8 † · 真实进程 fold 3~6/6 †
 ```
 
 GO = 围棋，kifu = 棋谱，compact = 压缩。一局棋下完，棋谱上不只有落子顺序，还有每一手的评语。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-gokifu-compact",
-  "version": "1.11.3",
+  "version": "1.11.5",
   "description": "DSH context-compression backend with a go game record (kifu) DAG: node = position, edge = attempted move + result. Incremental fold (each span summarized once), failure memory that survives compaction, transposition detection (chess-engine style), and a tiny hot ledger rebuilt every step.",
   "repository": {
     "type": "git",

package/scripts/check-maintenance.mjs

@@ -18,6 +18,7 @@
 import { readFileSync, existsSync } from "node:fs"
 import { join, resolve } from "node:path"
 import { spawnSync } from "node:child_process"
+import { classifyRemote } from "./release-lib.mjs"
 
 const ROOT = resolve(process.argv[2] ?? ".")
 const results = []
@@ -141,6 +142,28 @@ ok(usesAnnotated,
    "用 lightweight tag ⇒ Release 页没有 tag 说明、`git cat-file -t` 只看到 commit，历史无法解释",
    '把 scripts/release.mjs 里的 "git tag <tag>" 改成 "git tag -a <tag> -m \\"release <tag>\\""')
 
+// ── ⑧ remote 必须是合法的 GitHub URL ─────────────────────────────────
+// 2026-10-31 事故：`remote.origin.url` 被写成 `git+https://github.com/…`（从 package.json 的
+// repository.url 抄来的写法）。旧判据用正则匹配 `github.com:` ⇒ 照样通过；真做时 `git push`
+// 全崩（git 去找 remote helper `git-remote-git+https`）。这里复用 release-lib 的同一份判据，
+// 让日常维护就能提前发现坏 remote，而不是等到发版那一刻。
+const remoteUrl = git(["config", "--get", "remote.origin.url"]) ?? ""
+const remoteCheck = classifyRemote(remoteUrl)
+ok(remoteCheck.ok,
+   "remote.origin 是合法的 GitHub URL",
+   remoteCheck.ok ? "" : remoteCheck.reason,
+   "git remote set-url origin git@github.com:<owner>/<repo>.git")
+
+// ── ⑨ 当前目录必须就是仓库根（防串仓）──────────────────────────────
+// `ROOT` 取 `process.cwd()`：若在子目录或另一个仓库里跑，版本号 / CHANGELOG / tag
+// 全会指向错误的对象，而输出看起来一切正常。
+const topLevel = git(["rev-parse", "--show-toplevel"])
+const sameRepo = !!topLevel && resolve(topLevel) === resolve(ROOT)
+ok(sameRepo,
+   "当前目录就是仓库根（git rev-parse --show-toplevel === cwd）",
+   sameRepo ? "" : `cwd=${ROOT}，仓库根=${topLevel || "(取不到)"} —— 发布脚本会写错对象`,
+   "cd 到 git rev-parse --show-toplevel 打印的那个目录再跑")
+
 // ── 输出 ──────────────────────────────────────────────────────────────
 
 report()

package/scripts/release-lib.mjs

@@ -0,0 +1,103 @@
+/**
+ * release-lib.mjs —— `release.mjs` 的纯逻辑层（可单测，零副作用）
+ *
+ * 为什么单独拆出来：2026-10-31 的真实事故 —— 仓库 `remote.origin.url` 被写成
+ * `git+https://github.com/…`（非法 scheme），`release.mjs` 的体检**照样通过**（正则能匹配
+ * `github.com:`），直到真做 `git push` 才炸；而当时的执行顺序是「push → tag → **Release → npm**」，
+ * 于是留下「npm 已发、Release 已建、但 main 没推、tag 指向错误 commit」的半途状态。
+ *
+ * 本文件把两件事变成可测的纯函数：
+ *   ① `classifyRemote()`：**先判 scheme 再判仓库**，`git+*` 直接拒，并给出可执行的修法；
+ *   ② `runTransaction()`：**顺序执行 + 首个失败即中止**，让「git 步骤成功之后才允许副作用」成为结构保证，
+ *      而不是散落在调用点的 if。
+ */
+
+/** 非法 remote scheme 前缀：`git+https:` / `git+ssh:` / `git+file:` … */
+const BAD_SCHEME_RE = /^git\+/i
+
+/** GitHub 仓库的三种合法写法：scp 式 ssh、`ssh://`、`https://`。 */
+const SSH_RE = /^[a-z0-9._-]+@github\.com:([^/\s]+)\/([^/\s]+)$/i
+const SSH_URL_RE = /^ssh:\/\/(?:[a-z0-9._-]+@)?github\.com(?::\d+)?\/([^/\s]+)\/([^/\s]+)\/?$/i
+const HTTPS_RE = /^https?:\/\/github\.com\/([^/\s]+)\/([^/\s]+)\/?$/i
+
+/**
+ * 解析 GitHub remote。
+ * @returns {{owner:string, repo:string}|null} 不是 GitHub 或用了非法 scheme 时返回 null
+ */
+export function parseRepo(url) {
+  const raw = String(url ?? "").trim()
+  if (!raw || BAD_SCHEME_RE.test(raw)) return null
+  for (const re of [SSH_RE, SSH_URL_RE, HTTPS_RE]) {
+    const m = raw.match(re)
+    if (m) {
+      const repo = m[2].replace(/\.git$/i, "")
+      if (!m[1] || !repo) return null
+      return { owner: m[1], repo }
+    }
+  }
+  return null
+}
+
+/**
+ * 判断 remote 能不能用，并给出人话理由。
+ * @returns {{ok:true, repo:{owner:string,repo:string}, url:string} | {ok:false, reason:string}}
+ */
+export function classifyRemote(url) {
+  const raw = String(url ?? "").trim()
+  if (!raw) {
+    return { ok: false, reason: "remote.origin.url 为空 —— 没有远端就发不了版（git remote add origin …）" }
+  }
+  if (BAD_SCHEME_RE.test(raw)) {
+    const scheme = raw.split(":").slice(0, 2).join(":").split("+")[0]
+    return {
+      ok: false,
+      reason:
+        `remote.origin.url 用了非法协议（${raw.slice(0, raw.indexOf(":") + 1)}…）—— ` +
+        `git 会去找 remote helper「git-remote-${scheme}+」并报 "is not a git command"。` +
+        `改成 git@github.com:<owner>/<repo>.git（推荐）或 https://github.com/<owner>/<repo>.git：` +
+        `git remote set-url origin git@github.com:<owner>/<repo>.git`,
+    }
+  }
+  const repo = parseRepo(raw)
+  if (!repo) {
+    return { ok: false, reason: `remote.origin.url 不是 GitHub 仓库（${raw}）—— 这个脚本只处理 GitHub` }
+  }
+  return { ok: true, repo, url: raw }
+}
+
+/**
+ * 顺序执行一串步骤，**第一个失败就停**，后面的步骤一律不执行。
+ *
+ * 这就是「git push 成功之后才允许 npm / Release」的结构保证：把有副作用的动作排进 steps，
+ * 前面任何一步抛错，`ok` 就是 false，调用方据此直接退出（不再执行剩余副作用）。
+ *
+ * @param {{name:string, run:() => any}[]} steps
+ * @param {{
+ *   onStart?:(step:{name:string}, index:number)=>void,
+ *   onSettled?:(step:{name:string}, error:any, value:any)=>void,
+ * }} [opts]
+ * @returns {{ok:boolean, done:string[], failed:string|null, error:any, aborted:string[]}}
+ */
+export function runTransaction(steps, opts = {}) {
+  const list = Array.isArray(steps) ? steps : []
+  const done = []
+  for (let i = 0; i < list.length; i++) {
+    const step = list[i]
+    if (opts.onStart) opts.onStart(step, i)
+    try {
+      const value = step.run()
+      if (opts.onSettled) opts.onSettled(step, null, value)
+      done.push(step.name)
+    } catch (error) {
+      if (opts.onSettled) opts.onSettled(step, error, undefined)
+      return {
+        ok: false,
+        done,
+        failed: step.name,
+        error,
+        aborted: list.slice(i + 1).map((s) => s.name),
+      }
+    }
+  }
+  return { ok: true, done, failed: null, error: null, aborted: [] }
+}

package/scripts/release.mjs

@@ -13,8 +13,12 @@
 // 体检项（任一不过就退出码 1，且 --yes 也不动手）：
 //   ① package.json 有 version               ② CHANGELOG 有这一版那一段
 //   ③ 工作区干净                            ④ 当前在默认分支
-//   ⑤ 不落后远端                            ⑥ tag 还没被占
-//   ⑦ 推得上去（远端可达）
+//   ⑤ remote 是合法 GitHub URL（拒 git+https 之类）  ⑥ 远端可达（ls-remote 必须成功）
+//   ⑦ 不落后远端（fetch 必须成功，失败=红，不再吞成 note）  ⑧ tag 还没被占
+//
+// 执行顺序（**事务化**：前一步失败 ⇒ 后面一步根本不执行）：
+//   push 分支 → tag -a + push tag → npm publish（--npm 时）→ GitHub Release
+//   ⇒ git 步骤没过，绝不会出现「npm 已发 / Release 已建，但 main 没推」的半途状态。
 //
 // 需要 GitHub token 才能建 Release：
 //   GITHUB_TOKEN / GH_TOKEN 环境变量。没有也能跑 —— 它会打印手工建 Release 的命令。
@@ -22,6 +26,7 @@
 import { execSync, execFileSync } from "node:child_process"
 import { readFileSync, existsSync } from "node:fs"
 import { join } from "node:path"
+import { classifyRemote, runTransaction } from "./release-lib.mjs"
 
 const ROOT = process.cwd()
 const argv = new Set(process.argv.slice(2))
@@ -136,40 +141,70 @@ if (branch) {
   if (!dirty) bad("工作区有未提交的改动 —— 发布的内容必须和提交一致")
 }
 
-/** owner/repo —— 支持 ssh 与 https 两种 remote */
-function parseRepo(url) {
-  const m = String(url).match(/github\.com[:/]([^/]+)\/([^/.]+?)(?:\.git)?$/)
-  return m ? { owner: m[1], repo: m[2] } : null
-}
-const gh = remote ? parseRepo(remote) : null
-if (!gh) bad(`remote.origin 不是 GitHub 仓库（${remote || "空"}）—— 这个脚本只处理 GitHub`)
+/**
+ * remote 能不能用 —— 先判 scheme 再判仓库。
+ * 这一层是 2026-10-31 事故的直接产物：`git+https://…` 曾被当成合法 GitHub URL，
+ * 体检全绿、push 全崩。判定逻辑在 release-lib.mjs 里（可单测）。
+ */
+const remoteCheck = remote ? classifyRemote(remote) : { ok: false, reason: "没有 remote.origin" }
+const gh = remoteCheck.ok ? remoteCheck.repo : null
+if (!remoteCheck.ok) bad(remoteCheck.reason)
 
 let behind = 0
 if (gh && branch) {
-  try {
-    sh("git fetch origin --quiet")
-    const counts = sh(`git rev-list --left-right --count origin/${branch}...HEAD`)
-    const [b, a] = counts.split(/\s+/).map(Number)
-    behind = b || 0
-    if (behind > 0) bad(`落后远端 ${behind} 个提交 —— 先 pull / merge，别在旧基线上发版`)
-    if (a > 0) note(`本地领先远端 ${a} 个提交（发布时会一起推上去）`)
-  } catch {
-    note("git fetch 失败 —— 跳过「是否落后远端」检查")
+  // ⑤/⑥ 远端可达：ls-remote 必须成功。失败 ⇒ 红（不许「跳过检查」继续发版）。
+  if (!shOk("git ls-remote --heads origin")) {
+    bad(
+      "git ls-remote origin 失败 —— 远端不可达（URL 写错 / 凭据失效 / 网络不通）。" +
+        "先跑 `git ls-remote origin` 亲自确认能通，再发版。",
+    )
+  } else {
+    try {
+      sh("git fetch origin --quiet")
+      const counts = sh(`git rev-list --left-right --count origin/${branch}...HEAD`)
+      const [b, a] = counts.split(/\s+/).map(Number)
+      behind = b || 0
+      if (behind > 0) bad(`落后远端 ${behind} 个提交 —— 先 pull / merge，别在旧基线上发版`)
+      if (a > 0) note(`本地领先远端 ${a} 个提交（发布时会一起推上去）`)
+    } catch (e) {
+      // ⑦ fetch 失败不再是 note —— 那就是「不知道远端正不正常」，不能发版。
+      bad(`git fetch origin 失败（${String(e.stderr || e.message).trim().split("\n")[0]}）—— 远端状态未知，先修好再发版`)
+    }
   }
 }
 
-// ── ⑥ tag 是否已被占 ─────────────────────────────────────────────────
+// ── ⑧ tag 是否已被占（并区分「指向本 commit」与「指向别的 commit」）──────
+// 1.11.3 的现场：Release API 在 push 失败后**自动建了一个轻量 tag**，指向当时远端的旧 commit。
+// 那种情况不能默默 force —— 必须让人确认「这个 tag 是不是发错了」。
 
 let tagExistsLocal = false
 let tagExistsRemote = false
+let tagCommitLocal = ""
+let tagCommitRemote = ""
 if (gh) {
   tagExistsLocal = shOk(`git rev-parse -q --verify refs/tags/${tag}`)
+  if (tagExistsLocal) tagCommitLocal = sh(`git rev-parse -q --verify refs/tags/${tag}^{commit}`)
   try {
     const out = sh(`git ls-remote --tags origin refs/tags/${tag}`)
     tagExistsRemote = out.length > 0
+    // ls-remote 对 annotated tag 会同时给 `<tagobj>\trefs/tags/x` 和 `<commit>\trefs/tags/x^{}`；
+    // 取 deref 行（`^{}`）的 sha 才是它指向的 commit。
+    const deref = out.split("\n").find((l) => l.includes(`refs/tags/${tag}^{}`))
+    const plain = out.split("\n").find((l) => l.endsWith(`refs/tags/${tag}`))
+    tagCommitRemote = (deref ?? plain ?? "").split(/\s+/)[0] ?? ""
   } catch {}
+  const headSha = shOk("git rev-parse HEAD") ? sh("git rev-parse HEAD") : ""
+  const pointsAtHead = (sha) => !!sha && !!headSha && (sha === headSha || headSha.startsWith(sha))
   if (tagExistsLocal || tagExistsRemote) {
-    bad(`tag ${tag} 已存在 —— 同一个版本号不能发两次；先 bump version`)
+    if (tagExistsRemote && tagCommitRemote && !pointsAtHead(tagCommitRemote)) {
+      bad(
+        `远端 tag ${tag} 已存在，但指向 ${tagCommitRemote.slice(0, 12)}（不是 HEAD ${headSha.slice(0, 12)}）—— ` +
+          `可能是上次发布中断时由 Release API 自动建的轻量 tag。脚本**不会自动 force**。` +
+          `确认这个 tag 发错之后，手工修：git push --force origin refs/tags/${tag}:refs/tags/${tag}`,
+      )
+    } else {
+      bad(`tag ${tag} 已存在 —— 同一个版本号不能发两次；先 bump version`)
+    }
   }
 }
 
@@ -205,16 +240,16 @@ for (const n of notes) console.log(C.yellow(`  ! ${n}`))
 // ── 计划 ─────────────────────────────────────────────────────────────
 
 const plan = []
-plan.push({ what: `git push origin ${branch}`, why: "第 4 步：git 源检测看默认分支 HEAD" })
+plan.push({ what: `git push origin ${branch}`, why: "第 4 步：git 源检测看默认分支 HEAD（**失败即中止，后面一步都不做**）" })
 plan.push({ what: `git tag -a ${tag} -m "release ${tag}" && git push origin ${tag}`, why: "第 6 步：annotated tag（带消息）让「某 bug 出在哪版」可查，且 GitHub Release 才有说明" })
+if (ALSO_NPM) {
+  const script = pkg.scripts?.["publish:npm"] ? "npm run publish:npm" : "npm publish"
+  plan.push({ what: script, why: "第 5 步：npm 源的用户比 registry 上的 version（**排在 Release 之前**：npm 失败就不建 Release）" })
+}
 plan.push({
   what: `POST /repos/${gh.owner}/${gh.repo}/releases`,
   why: `第 6 步：Release 正文 = CHANGELOG 的 ${version} 段（${releaseBody.split("\n").length} 行，已去掉 > 起因）`,
 })
-if (ALSO_NPM) {
-  const script = pkg.scripts?.["publish:npm"] ? "npm run publish:npm" : "npm publish"
-  plan.push({ what: script, why: "第 5 步：npm 源的用户比 registry 上的 version" })
-}
 plan.push({ what: "四条验证", why: "第 7 步：npm 版本 / tarball 内容 / magpie plugin list / Release 在" })
 
 console.log(C.bold("计划：\n"))
@@ -228,27 +263,84 @@ if (DRY) {
   process.exit(0)
 }
 
-// ── 真做 ─────────────────────────────────────────────────────────────
+// ── 真做（事务化：前一步失败 ⇒ 后面一步根本不执行）────────────────────
 
 const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN || ""
 console.log()
 
-function run(cmd, label) {
-  process.stdout.write(`  ${label} … `)
+const doneSteps = []
+
+/**
+ * 失败即中止：把「后面还有什么没做」写清楚，然后退出 1。
+ * 这是 2026-10-31 事故的教训 —— 当时 push/tag 全失败，脚本却继续建 Release、继续 npm publish，
+ * 留下「npm 有、main 没推、tag 指向旧 commit」的半途状态。
+ */
+function abort(step, detail) {
+  console.log(C.red(`\n✗ 已中止：${step} 失败 —— 后续步骤全部未执行`))
+  console.log(C.dim(`  已完成：${doneSteps.length ? doneSteps.join(" → ") : "（无）"}`))
+  if (detail) console.log(C.dim(`  ${detail}`))
+  console.log(
+    C.dim(
+      `  未执行：${["tag -a " + tag, ALSO_NPM ? "npm publish" : null, "GitHub Release"]
+        .filter(Boolean)
+        .join(" · ")}`,
+    ),
+  )
+  console.log(C.dim("  ⇒ 没有任何新的对外副作用被制造出来。修好远端后重跑同一条命令。\n"))
+  process.exit(1)
+}
+
+// ①② 推分支 + annotated tag —— 走 runTransaction（首步失败 ⇒ tag 步根本不执行）
+const gitTx = runTransaction(
+  [
+    {
+      name: `push ${branch}`,
+      label: `push ${branch}`,
+      run: () => sh(`git push origin ${branch}`, { stdio: "pipe" }),
+      hint: "远端不可达或被拒。**tag / npm / Release 一件都没做。**",
+    },
+    {
+      name: `tag ${tag}`,
+      label: `tag ${tag}`,
+      run: () => sh(`git tag -a ${tag} -m "release ${tag}" && git push origin ${tag}`, { stdio: "pipe" }),
+      hint: "本地 tag 可能已建；远端 tag 没上去。修好后单独补：git push origin " + tag,
+    },
+  ],
+  {
+    onStart: (step) => process.stdout.write(`  ${step.label} … `),
+    onSettled: (step, err) => {
+      if (!err) return console.log(C.green("ok"))
+      console.log(C.red("失败"))
+      console.log(C.dim(String(err.stderr || err.message).trim().split("\n").slice(0, 4).join("\n")))
+    },
+  },
+)
+if (!gitTx.ok) {
+  const failedStep = gitTx.done.length === 0 ? `git push origin ${branch}` : `tag -a ${tag} && git push origin ${tag}`
+  const hint = gitTx.done.length === 0
+    ? "远端不可达或被拒。**tag / npm / Release 一件都没做。**"
+    : "本地 tag 可能已建；远端 tag 没上去。修好后单独补：git push origin " + tag
+  abort(failedStep, hint)
+}
+doneSteps.push(`push ${branch}`, `tag ${tag}`)
+
+// ③ npm 发布（在 Release 之前：npm 失败就不该留下一个「Release 说有、npm 上没有」的状态）
+let published = null
+if (ALSO_NPM) {
+  const npmScript = pkg.scripts?.["publish:npm"] ? "npm run publish:npm" : "npm publish"
+  console.log(C.dim(`\n  ${npmScript}（npm 登记有 1~2 分钟延迟，别在这窗口里重试）\n`))
   try {
-    sh(cmd, { stdio: "pipe" })
-    console.log(C.green("ok"))
-    return true
-  } catch (e) {
-    console.log(C.red("失败"))
-    console.log(C.dim(String(e.stderr || e.message).trim().split("\n").slice(0, 4).join("\n")))
-    return false
+    execSync(npmScript, { cwd: ROOT, stdio: "inherit" })
+    published = true
+    doneSteps.push(`npm publish ${version}`)
+  } catch {
+    published = false
+  }
+  if (!published) {
+    abort(`${npmScript}`, "npm 没发出去（OTP / 2FA / 权限 / 网络）。**GitHub Release 未创建。**")
   }
 }
 
-const pushed = run(`git push origin ${branch}`, `push ${branch}`)
-const tagged = run(`git tag -a ${tag} -m "release ${tag}" && git push origin ${tag}`, `tag ${tag}`)
-
 let released = false
 
 /** 这个仓库有没有 release.yml（有的话推 tag 就会自动建 Release，我们不该再建一遍） */
@@ -354,19 +446,6 @@ if (token) {
   console.log(C.dim("    正文直接把 CHANGELOG 里 " + version + " 那一段粘过去"))
 }
 
-let published = null
-if (ALSO_NPM) {
-  const script = pkg.scripts?.["publish:npm"] ? "npm run publish:npm" : "npm publish"
-  console.log(C.dim(`\n  ${script}（npm 登记有 1~2 分钟延迟，别在这窗口里重试）\n`))
-  try {
-    execSync(script, { cwd: ROOT, stdio: "inherit" })
-    published = true
-  } catch {
-    published = false
-    console.log(C.red("  npm 发布失败"))
-  }
-}
-
 // ── 第 7 步留给人看的清单 ─────────────────────────────────────────────
 
 console.log(C.bold("\n第 7 步 · 四条验证（逐条跑，别只看版本号）：\n"))
@@ -385,5 +464,11 @@ console.log(
   ),
 )
 
-const failed = !pushed || !tagged || (ALSO_NPM && !published)
+// 走到这里说明 push / tag /（npm）全部成功。Release 失败仍是失败（否则「npm 有、Release 没有」）。
+const failed = !!token && !released
+if (failed) {
+  console.log(C.red("\n✗ GitHub Release 没建成 —— push/tag/npm 都已完成，只差 Release："))
+  console.log(C.dim("  手工建：GitHub → Releases → Draft a new release → 选 " + tag))
+  console.log(C.dim("  或重跑本脚本（tag 已存在会先被 ⑧ 拦住；那就手工建一次）"))
+}
 process.exit(failed ? 1 : 0)