@modusensus/dsh-mneme 0.8.16 → 0.9.1

package/scripts/publish-gate.mjs

@@ -0,0 +1,197 @@
+// 发布闸门：publish 步之后**必须**确认这个版本真的能被 registry 看见，看不见就整轮失败。
+//
+// 为什么需要它：原先这一步是
+//   echo "Published: $(npm view "@modusensus/dsh-mneme@${V}" version)"
+// 命令替换里的失败**不会**让 `set -e` 退出。v0.8.16 那次日志白纸黑字写着
+// `npm error code E404 / 404 No match found for version 0.8.16`，step 与 job 却都是绿的。
+// 也就是说「真发不出去」（token 失效、权限不足、npm 侧拒绝）与「发出去了」在 CI 上是同一种
+// 颜色，只有人翻日志才看得出来 —— 闸门的意义恰恰是没人翻日志的时候。
+//
+// 为什么是轮询而不是一次性查询：registry 有传播延迟，v0.8.16 实测 publish 到可见约 4.5 分钟
+// （11:15:52Z → 11:20:22Z）。一次性查询只有两种结局：忽略失败（就是现在的假绿），或者拿传播
+// 延迟当发布失败（假红）。幂等跳过那条路径（版本已存在）**首次探测即通过**，所以只有真发新版
+// 才付等待成本。
+//
+// 为什么探测走 registry 公开 HTTP 面而不是 `npm view`：不依赖 .npmrc 里的 token、不依赖 npm CLI
+// 的 E404 语义，而且能把「还没传播」与「网络异常」分开报出来 —— 两种都重试，但日志里要能区分，
+// 否则排障时又得靠猜。
+//
+// 与 scripts/changelog-prep.mjs 同一个理由：逻辑收在可注入的模块里才测得到（probe/sleep/now 全
+// 可注入，单测零网络零等待），入口只负责读参数与决定退出码。
+
+import { pathToFileURL } from "node:url";
+
+export const PACKAGE_NAME = "@modusensus/dsh-mneme";
+export const REGISTRY_ORIGIN = "https://registry.npmjs.org";
+
+/** 默认 10 分钟：实测传播 ~4.5 分钟，留一倍余量；超时=发布失败，宁可红也不许假绿。 */
+export const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+/** 默认 15 秒：一次发布最多 40 次探测，日志行数与 registry 负载都可接受。 */
+export const DEFAULT_INTERVAL_MS = 15 * 1000;
+/** 单次探测的 HTTP 超时：挂死的请求必须自己失败，不能吃掉整段预算。 */
+export const DEFAULT_PROBE_TIMEOUT_MS = 15 * 1000;
+
+/**
+ * 单版本的 registry URL。scoped 包名必须整体 encodeURIComponent（`@scope/name` → `%40scope%2Fname`）：
+ * 直接拼裸 `/` 会被当成路径分隔符，registry 回 404 —— 那正是「闸门自己造成的假红」。
+ */
+export function versionUrl(name, version, origin = REGISTRY_ORIGIN) {
+  return `${origin.replace(/\/+$/, "")}/${encodeURIComponent(name)}/${encodeURIComponent(version)}`;
+}
+
+/**
+ * 探测一次「该版本是否已在 registry 上」。
+ *
+ * 永不抛错：任何异常都折成 `{ok:false, reason, detail}`，让上层的重试与超时逻辑保持单一形状。
+ * `reason` 取值：`missing`(404，多半是还没传播) / `network`(请求本身失败) / `http`(非 2xx/404) /
+ * `bad-json` / `mismatch`(200 但版本号对不上)。
+ *
+ * @param {string} version 如 "0.8.16"
+ * @param {{name?: string, origin?: string, fetchImpl?: typeof fetch, timeoutMs?: number}} [options]
+ * @returns {Promise<{ok: true, version: string, tarball: string} | {ok: false, reason: string, detail: string}>}
+ */
+export async function probeVersion(version, {
+  name = PACKAGE_NAME,
+  origin = REGISTRY_ORIGIN,
+  fetchImpl = globalThis.fetch,
+  timeoutMs = DEFAULT_PROBE_TIMEOUT_MS
+} = {}) {
+  const url = versionUrl(name, version, origin);
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+  } catch (error) {
+    return { ok: false, reason: "network", detail: `请求失败：${error?.message ?? error}（${url}）` };
+  }
+  if (response.status === 404) {
+    return { ok: false, reason: "missing", detail: `HTTP 404，registry 上还看不到（${url}）` };
+  }
+  if (!response.ok) {
+    return { ok: false, reason: "http", detail: `HTTP ${response.status}（${url}）` };
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch (error) {
+    return { ok: false, reason: "bad-json", detail: `响应不是 JSON：${error?.message ?? error}` };
+  }
+  if (body?.version !== version) {
+    return { ok: false, reason: "mismatch", detail: `registry 返回的版本是 ${body?.version ?? "(缺失)"}` };
+  }
+  return { ok: true, version, tarball: body?.dist?.tarball ?? "" };
+}
+
+/**
+ * 轮询到版本可见为止；超时即 `{ok:false, reason:"timeout"}`。
+ *
+ * 契约（单测锁的就是这条）：**看不见就绝不返回 ok:true**。任何把超时折叠成成功、或者把
+ * 「探测失败」当成「跳过校验」的改法，都等于退回 v0.8.16 那种假绿。
+ *
+ * @param {string} version
+ * @param {{name?: string, origin?: string, timeoutMs?: number, intervalMs?: number,
+ *          now?: () => number, sleep?: (ms: number) => Promise<void>,
+ *          probe?: () => Promise<{ok: boolean, detail?: string}>, log?: (line: string) => void}} [options]
+ */
+export async function waitForPublished(version, {
+  name = PACKAGE_NAME,
+  origin = REGISTRY_ORIGIN,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  intervalMs = DEFAULT_INTERVAL_MS,
+  now = () => Date.now(),
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  probe = () => probeVersion(version, { name, origin }),
+  log = () => {}
+} = {}) {
+  const startedAt = now();
+  let attempts = 0;
+  let lastError = "";
+  for (;;) {
+    attempts += 1;
+    const result = await probe();
+    // 探测成功即算通过，**不再回头比期限**：预算是「等多久才放弃」，不是「多久之后就算没发布」。
+    // 单次探测自带 HTTP 超时（默认 15 秒），所以晚到的成功最多超出预算十几秒；而版本真的在
+    // registry 上就等于发布成功，因为晚到几秒把它判红才是假红——这个闸门存在的理由正是消灭
+    // 假绿，不该顺手制造另一种失真。反过来，探测失败仍严格按预算收口（见下）。
+    if (result?.ok) {
+      return { ok: true, version, attempts, waitedMs: now() - startedAt, tarball: result.tarball ?? "" };
+    }
+    lastError = result?.detail ?? "未知原因";
+    const waitedMs = now() - startedAt;
+    log(`第 ${attempts} 次探测（已等 ${Math.round(waitedMs / 1000)}s）：${lastError}`);
+    if (waitedMs >= timeoutMs) {
+      return { ok: false, reason: "timeout", attempts, waitedMs, lastError };
+    }
+    // 只睡到预算耗尽为止：最后一次探测落在超时点上，不额外多睡一整轮。
+    await sleep(Math.min(intervalMs, timeoutMs - waitedMs));
+  }
+}
+
+/**
+ * 入口参数：位置参数是版本号，另可覆盖 `--timeout-ms` / `--interval-ms`（排障与手动跑用）。
+ * 缺版本号如实回报 `missing-version`，由入口打印用法并退出 1。
+ */
+export function parseArgs(argv = []) {
+  const out = { version: "", timeoutMs: DEFAULT_TIMEOUT_MS, intervalMs: DEFAULT_INTERVAL_MS };
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--timeout-ms" || arg === "--interval-ms") {
+      const key = arg === "--timeout-ms" ? "timeoutMs" : "intervalMs";
+      const value = Number(argv[i + 1]);
+      if (!Number.isFinite(value) || value <= 0) return { ok: false, reason: `${arg} 需要一个正数` };
+      out[key] = value;
+      i += 1;
+      continue;
+    }
+    positional.push(arg);
+  }
+  if (positional.length !== 1) return { ok: false, reason: "missing-version" };
+  out.version = positional[0];
+  return { ok: true, ...out };
+}
+
+/** 入口：CI 与手动都用它；失败一律 `process.exit(1)`，绝不吞掉。 */
+export async function main(argv = process.argv.slice(2), {
+  log = console.log,
+  error = console.error,
+  wait = waitForPublished
+} = {}) {
+  const parsed = parseArgs(argv);
+  if (!parsed.ok) {
+    error(`用法：node scripts/publish-gate.mjs <版本号> [--timeout-ms 600000] [--interval-ms 15000]`);
+    error(`参数有误：${parsed.reason}`);
+    return 1;
+  }
+  log(`等待 ${PACKAGE_NAME}@${parsed.version} 在 registry 上可见（最多 ${parsed.timeoutMs / 1000}s）…`);
+  const result = await wait(parsed.version, {
+    timeoutMs: parsed.timeoutMs,
+    intervalMs: parsed.intervalMs,
+    log
+  });
+  if (!result.ok) {
+    error(
+      `发布闸门未通过：${PACKAGE_NAME}@${parsed.version} 在 ${Math.round(result.waitedMs / 1000)}s 内` +
+      `（${result.attempts} 次探测）始终看不到 —— 最后一次：${result.lastError}`
+    );
+    error(`publish 步很可能失败了（token 失效 / 权限不足 / npm 侧拒绝），请翻上面 publish 步的日志。`);
+    return 1;
+  }
+  const waitedSec = Math.round(result.waitedMs / 1000);
+  log(`✓ ${PACKAGE_NAME}@${result.version} 已在 registry 上可见（第 ${result.attempts} 次探测，等了 ${waitedSec}s）`);
+  if (result.tarball) log(`  tarball: ${result.tarball}`);
+  return 0;
+}
+
+// import 即执行会让单测没法只 import 纯函数（changelog-prep.mjs 的同一教训），故用主模块判别。
+// 比较用 pathToFileURL：手拼 `file://${argv[1]}` 在本机（Windows 盘符 + 非 ASCII 路径）拼不出合法 URL，
+// 判别会恒假 —— 那样的失败是静默的：脚本什么也不做，还退出 0。
+//
+// 用 `process.exitCode` 而不是 `process.exit()`：刚做完 HTTP 请求就硬退，会在 Windows 上撞到
+// libuv 的 `Assertion failed: !(handle->flags & UV_HANDLE_CLOSING)`（实测 0.8.16 成功路径复现），
+// 退出码变成 0xC0000409 而不是 0 —— 一个把成功报成崩溃的退出路径，正好与本次要修的假绿同类。
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exitCode = await main();
+}

package/scripts/release-docs.mjs

@@ -0,0 +1,204 @@
+// 发布准备里「往两份 README 的版本表插占位行 + 回填路线图状态 + 核对 SECURITY.md 支持版本表」
+// 的单一实现。
+//
+// 为什么抽成模块而不是留在入口里：入口 scripts/release-prep.mjs 在仓库根、import 即执行，
+// 测不了。而这一步恰好静默失效过——根 README 的路线图表版本列写的是两段式 `**v0.9**`，
+// 而匹配规则只认三段式 `**v0.9.0**`，于是脚本对根 README 一个字节也没改，打印的却是
+// 「无版本表格行，跳过」：读起来像「这里不需要做」，实际是「这里没做」。v0.9.0 那次发布
+// 准备（a9f8e35）只有 5 个文件变动、根 README 的路线图与 News 一字未动，佐证这不是新问题。
+//
+// 与 scripts/changelog-prep.mjs、scripts/test-count-sync.mjs 同一个理由：规则收在共用模块里
+// 才测得到，也才不会两处各写一份。
+import { detectEol } from "./changelog-prep.mjs";
+
+// 版本号写在表格第一格才算「版本行」。三段式与两段式分开认：根 README 的路线图按 minor 排
+// （v0.9），子 README 的版本历史按 patch 排（v0.9.0），两者不能互相匹配——否则给根 README
+// 插一行 `**v0.9.1**` 会凭空造出一个不存在的 minor 条目。
+const THREE = /^\|\s*\*\*v(\d+\.\d+\.\d+)\*\*/;
+const TWO = /^\|\s*\*\*v(\d+\.\d+)\*\*/;
+
+const cellCount = (line) => line.split("|").filter((c) => c.trim()).length;
+const hasCJK = (s) => /[\u4e00-\u9fff]/.test(s);
+
+/** semver 比较，长度不同时缺位按 0 处理（两段式路由图对上三段式目标版本时要用）。 */
+function cmpVersion(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * 扫描文本里所有版本行，按写法分三段式 / 两段式，并按**表格块**分组。
+ *
+ * 为什么要分组：根 README 的中英路线图是两张独立的表，版本行一模一样。旧实现把所有版本行
+ * 合并成一个数组，「表里是否已有目标版本」于是变成全文件判断——给中文表插了行之后，英文表
+ * 就被判成「已存在」，永远补不上。分组之后每张表各自判断、各自插入。
+ *
+ * 分组规则：连续的版本行算一块，中间隔着表头/分隔行这类表格行也仍算同一块；遇到空行或正文
+ * 才收块。导出是为了让测试能拿真实 README 断言「这些表仍被认得出」——正则一旦被改窄，
+ * 用户看到的会是「无版本表格行，跳过」，而不是测试变红。
+ */
+export function scanReleaseRows(text) {
+  const three = [];
+  const two = [];
+  const blocks = [];
+  let current = null;
+  text.split(/\r?\n/).forEach((line, index) => {
+    const m3 = THREE.exec(line);
+    const m2 = m3 ? null : TWO.exec(line);
+    if (m3 || m2) {
+      const kind = m3 ? "three" : "two";
+      const row = { index, ver: (m3 || m2)[1], kind };
+      (kind === "three" ? three : two).push(row);
+      if (current && current.next === index) current.rows.push(row);
+      else {
+        current = { rows: [row], next: index + 1 };
+        blocks.push(current);
+      }
+      current.next = index + 1;
+      return;
+    }
+    if (current && /^\s*\|/.test(line)) current.next = index + 1;
+    else current = null;
+  });
+  return { three, two, blocks };
+}
+
+/** 按锚点行的列数与语言生成占位行。列数是「这张表有几列」的唯一判据：2 列=版本历史，3 列=路线图。 */
+function rowFor(anchorLine, version, date) {
+  const n = cellCount(anchorLine);
+  if (n <= 2) return date ? `| **v${version}**（${date}） | （待填） |` : `| **v${version}** | （待填） |`;
+  if (n === 3) {
+    return hasCJK(anchorLine)
+      ? `| **v${version}** | （待填） | 🚧 准备中 |`
+      : `| **v${version}** | TBD | 🚧 In prep |`;
+  }
+  return `| **v${version}** | 🚧 准备中 | （待填） | （待填） |`;
+}
+
+/**
+ * 给一份 README 插版本占位行，并把当前 minor 那行路线图的状态回填成已发布。
+ *
+ * 按**表块**而不是整份文件处理：根 README 的中英路线图是两张独立的表，版本行一模一样。合并成
+ * 一个数组判断「表里是否已有目标版本」，会让先插的中文表把英文表判成「已存在」。
+ *
+ * 返回 { text, actions }，而不是布尔：「没插」有三种原因（已存在 / 没有版本表 / 表里已有更高
+ * 版本），入口需要能如实说明是哪一种——旧实现在这里统一打印「跳过」，把「没做」说成了「不需要做」。
+ *
+ * @param {string} text README 全文
+ * @param {string} version 目标版本，如 "0.9.1"
+ * @param {string} date 如 "2026-10-18"
+ */
+export function syncReadmeTables(text, version, date) {
+  const [major, minor] = version.split(".");
+  const minorKey = `${major}.${minor}`;
+  const eol = detectEol(text);
+  const lines = text.split(/\r?\n/);
+  const { blocks, two } = scanReleaseRows(text);
+
+  const insertAfter = new Map();
+  const replaceAt = new Map();
+  const actions = [];
+
+  // 1) 逐张表块插占位行。**必须按块**：根 README 的中英路线图是两张独立的表、版本行一模一样，
+  //    旧实现把全文件所有版本行当一个数组，「表里已有目标版本」于是退化成全文件判断——先插的
+  //    中文表会让英文表被判成「已存在」，那张就永远补不上。
+  //    锚点取块内「低于目标的最新版本行」，不插表尾：这类表常在末尾写一条 v0.8.x 这样的概括行。
+  for (const block of blocks) {
+    const isHistory = block.rows[0].kind === "three";
+    const target = isHistory ? version : minorKey;
+    if (block.rows.some((r) => r.ver === target)) continue;
+    const lower = block.rows.filter((r) => cmpVersion(r.ver, target) < 0);
+    if (!lower.length) continue;
+    const anchor = lower.reduce((a, b) => (cmpVersion(b.ver, a.ver) > 0 ? b : a));
+    const anchorLine = lines[anchor.index];
+    let row = rowFor(anchorLine, target, date);
+    // 路线图的状态格直接写已发布，而不是「🚧 准备中」：这一行随 PR 一起进 main，合并之后紧接着
+    // 就是打 tag，所以它就是这次要发出去的那一版。若写成「🚧」，它不会自己变——下次跑发版准备
+    // 时回填的是那一版的补丁号（0.10.0 已发布，路线图却写 v0.10.1），把首个发布版本记错。
+    // 与下面第 2 步「不改写已发布行」不冲突：那条规则防的是抹掉「这个 minor 首个发布的是谁」。
+    if (!isHistory && cellCount(anchorLine) === 3) {
+      const released = hasCJK(anchorLine) ? `✅ 已发布（v${version}）` : `✅ Released (v${version})`;
+      const cells = row.split("|");
+      cells[cells.length - 2] = ` ${released} `;
+      row = cells.join("|");
+    }
+    insertAfter.set(anchor.index, row);
+    actions.push({ kind: "insert", table: isHistory ? "版本历史" : "路线图", after: `v${anchor.ver}` });
+  }
+
+  // 2) 回填当前 minor 那行仍是「🚧 准备中」的状态格——上一次发版留下的占位，发版准备这一刻
+  //    它就该变成已发布（版本号已定，是事实）。主题文字（第二格）始终不碰，那是人写的。
+  //
+  //    刻意不把「✅ 已发布（v0.9.0）」改写成「（v0.9.1）」：本脚本跑在打 tag 之前，改了就等于
+  //    在 PR 里提前宣布一个还没发出去的版本；PR 若被放弃，那行立刻变成谎话。补丁号只由人在
+  //    真正发出去之后按需要更新（与 v0.8 那行「至 v0.8.16」同一口径）。
+  for (const row of two) {
+    if (row.ver !== minorKey) continue;
+    const line = lines[row.index];
+    if (cellCount(line) < 3) continue;
+    const cells = line.split("|");
+    const old = cells[3].trim();
+    if (!/🚧/.test(old)) continue;
+    const next = hasCJK(line) ? `✅ 已发布（v${version}）` : `✅ Released (v${version})`;
+    cells[3] = ` ${next} `;
+    replaceAt.set(row.index, cells.join("|"));
+    actions.push({ kind: "rollup", table: "路线图", from: old, to: next });
+  }
+
+  if (!actions.length) return { text, actions };
+  const out = [];
+  lines.forEach((line, index) => {
+    out.push(replaceAt.has(index) ? replaceAt.get(index) : line);
+    if (insertAfter.has(index)) out.push(insertAfter.get(index));
+  });
+  return { text: out.join(eol), actions };
+}
+
+/** 取某一节（到下一个同级 ## 标题为止）。用节而不是全文 grep：历史审计节里也有版本号。 */
+export function sectionOf(text, heading) {
+  const start = text.indexOf(heading);
+  if (start < 0) return null;
+  const rest = text.slice(start + heading.length);
+  const end = rest.search(/\r?\n## /);
+  return end >= 0 ? rest.slice(0, end) : rest;
+}
+
+/**
+ * 核对 SECURITY.md 的支持版本表首行是否等于 package.json 的 major.minor。
+ *
+ * 只核对、不改写。跨 minor 发版时整张表要向下挪一格（0.10.x 活跃 / 0.9.x 尽力维护 /
+ * < 0.9.0 不支持），连停止维护那段措辞一起挪——这是维护策略的判断，机器替人写很容易
+ * 写出「0.9.x 已停止支持」这类真事故。所以入口硬失败、把话说明白，由人改。
+ *
+ * 为什么必须在这里拦：dsh-mneme/test/security-doc.test.js 也锁同一件事，但那条锁在
+ * 「PR 提交之后」才跑。脚本先拦，坏 PR 根本不会开出来。
+ */
+export function checkSupportTable(text, version) {
+  const [major, minor] = version.split(".");
+  const expected = `${major}.${minor}.x`;
+  const problems = [];
+  for (const [heading, label] of [
+    ["## Supported Versions", "英文"],
+    ["## 支持版本", "中文"],
+  ]) {
+    const body = sectionOf(text, heading);
+    if (body === null) {
+      problems.push(`${label}表：找不到「${heading}」一节`);
+      continue;
+    }
+    const rows = body.split(/\r?\n/).filter((l) => /^\|\s*[\d<]/.test(l));
+    if (!rows.length) {
+      problems.push(`${label}表：没解析出任何版本行（表格形状变了？）`);
+      continue;
+    }
+    const found = rows[0].split("|")[1].trim();
+    if (found !== expected) problems.push(`${label}表首行写的是 ${found}，应为 ${expected}`);
+  }
+  return { ok: problems.length === 0, expected, problems };
+}

package/scripts/release-notes.mjs

@@ -0,0 +1,162 @@
+// 从 CHANGELOG 小节渲染 GitHub Release 正文的单一实现。
+//
+// 为什么抽成模块：这段逻辑原先嵌在 .github/workflows/release.yml 的 node -e 内联脚本里，
+// 要改排版就得改工作流本体，也没法写测试——而 Release 正文恰恰是最需要反复试排版的东西。
+// 抽出来之后同样的输入产出同样的正文，本地能预览、CI 能锁形状。
+//
+// 排版目标：Release 页的默认视图要能一眼扫完，但完整正文不能丢——它同时是「这个版本到底
+// 改了什么」的唯一对外说明。做法是标题 + 一句导语默认可见，剩余正文折进 details，想细看的
+// 人点开，不想看的人不被淹。
+//
+// CHANGELOG 本体一个字不动：那是仓库内的完整记录（含决策理由与审计线索），压缩它等于销毁
+// 证据；分层只发生在对外渲染这一步。
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+// 句末标点以中文全角为主。刻意不认半角句号：v0.9.0 这类版本号里的点是同一个字符，
+// 认了会把导语切在版本号中间。
+const END = /[。！？]/;
+// 导语超长时的退让点，从强到弱。半角分号/逗号兜住中英混排的条目。
+const SOFT = ["；", "，", ";", ","];
+
+/** 取出某个版本的 CHANGELOG 小节正文（不含 ## [V] 标题行本身）；找不到返回 null。 */
+export function findSection(text, version) {
+  const re = new RegExp("^## \\[" + version.replace(/\./g, "\\.") + "\\][^\\n]*\\n", "m");
+  const start = text.search(re);
+  if (start === -1) return null;
+  const rest = text.slice(start + text.slice(start).indexOf("\n") + 1);
+  const next = rest.search(/^## \[/m);
+  return (next === -1 ? rest : rest.slice(0, next)).trim();
+}
+
+/** 拆 - **标题**：正文；不是这个形状返回 null，调用方按普通行原样保留。 */
+export function parseBullet(line) {
+  const m = line.match(/^- \*\*(.+?)\*\*(?:[：:]\s*)?([\s\S]*)$/);
+  if (!m) return null;
+  return { title: m[1].trim(), body: (m[2] || "").trim() };
+}
+
+/**
+ * 括号深度：全角（或半角( 进一层，）或) 出一层。导语绝不在未闭合的括号里断开——
+ * 「…（明文回吐 Bearer，」这种收尾等于把一句话切在从句中间，读者要回头找主语。
+ */
+function depthAt(s, end) {
+  let d = 0;
+  for (let i = 0; i < end; i += 1) {
+    const c = s[i];
+    if (c === "\uFF08" || c === "(") d += 1;
+    else if (c === "\uFF09" || c === ")") d = Math.max(0, d - 1);
+  }
+  return d;
+}
+
+/** 导语最短长度：低于它说明这句太短、离开上下文就没信息（实测有一条首句只有 8 字）。 */
+const MIN_LEDE = 24;
+
+/**
+ * 取导语，返回 {lede, consumed}。
+ *
+ * consumed 是导语在正文里吃掉的字符数：折叠块放 body.slice(consumed)，因此导语与细节不
+ * 重复——不记录它的话，用户点开折叠会看到同一句话出现两次。
+ *
+ * 优先级：① cap 内第一个长度达标（>= MIN_LEDE）的句末标点，整句收尾最干净；
+ * ② cap 内最后一个括号平衡的软标点（分号/逗号/顿号），用省略号收尾、并连标点一起吃进
+ * consumed（否则折叠块以「，」开头）；③ cap 内没有平衡软标点时，延到 cap 之后最近的平衡
+ * 软标点，容许有限超长；④ 兜底硬截断。
+ *
+ * 两条规则都是被真实语料逼出来的：v0.9.0 的「GET /external-api（明文回吐 Bearer，」是在
+ * 未闭合的括号里切断的（故有 depthAt）；同批有条首句「两处水源在说谎。」短到无法独立表意
+ * （故有 MIN_LEDE）。
+ */
+export function lede(body, cap = 150) {
+  if (!body) return { lede: "", consumed: 0 };
+  // 正文本身不比 cap 长：整段就是导语。这一条必须排在软断点搜索**之前**——否则短正文里
+  // 只要有个逗号就会被加上省略号，凭空说「后面还有」；逗号恰是最后一个字符时更荒唐：
+  // 省略号后面什么也没有，折叠块是空的。原先这条守在函数末尾，靠句末标点分支侥幸躲过多数
+  // 情况，只有「短且没有句末标点」的正文才会踩到。
+  if (body.length <= cap) return { lede: body, consumed: body.length };
+  for (let i = 0; i < body.length && i < cap; i += 1) {
+    if (END.test(body[i]) && i + 1 >= MIN_LEDE) return { lede: body.slice(0, i + 1), consumed: i + 1 };
+  }
+
+  let before = -1;
+  for (const mark of SOFT) {
+    let at = body.slice(0, cap).lastIndexOf(mark);
+    while (at !== -1 && depthAt(body, at) !== 0) at = body.slice(0, at).lastIndexOf(mark);
+    if (at > before) before = at;
+  }
+  if (before >= MIN_LEDE) return { lede: body.slice(0, before) + "\u2026", consumed: before + 1 };
+
+  const limit = Math.floor(cap * 1.6);
+  for (let i = cap; i < Math.min(body.length, limit); i += 1) {
+    if (SOFT.includes(body[i]) && depthAt(body, i) === 0) {
+      return { lede: body.slice(0, i) + "\u2026", consumed: i + 1 };
+    }
+  }
+
+  return { lede: body.slice(0, cap) + "\u2026", consumed: cap };
+}
+
+/**
+ * 渲染 Release 正文：输入 findSection 的结果（小节正文），输出可直接写进
+ * gh release --notes-file 的 Markdown。
+ *
+ * 折叠块的缩进按 GitHub 列表项的规则写成两个空格；少缩进一级会被渲染成独立段落，
+ * 整条子弹的视觉归属就断了。列表项内 details 与正文之间必须有空行，否则内部 Markdown 不解析。
+ */
+/**
+ * 把一个小节切成「块」：一个块 = 一条子弹 + 它下面所有缩进续行（含缩进的子列表）。
+ *
+ * 为什么必须先切块再渲染：CHANGELOG 里有 179 行缩进续行（0.8.6 / 0.8.7 / 0.8.12 等老版本集中
+ * 出现，另有 59 行 `  - ` 子列表）。逐行 trim 的写法会把续行当成独立段落甩到条目的
+ * `<details>` 外面——读者看到的是「条目正文只有一句，剩下的莫名其妙散在下面」，而且缩进没了、
+ * 子列表变成平铺段落。渲染的单位是**条目**，不是行。
+ */
+export function splitBlocks(sectionText) {
+  const blocks = [];
+  for (const raw of sectionText.split(/\r?\n/)) {
+    if (!raw.trim()) continue;
+    // 缩进行且当前有可挂靠的块 → 续行；否则（块首行之外的单行文本）另起一块。
+    if (/^[ \t]+\S/.test(raw) && blocks.length) {
+      blocks[blocks.length - 1].lines.push(raw.replace(/\s+$/, ""));
+      continue;
+    }
+    blocks.push({ lines: [raw.trim()] });
+  }
+  return blocks;
+}
+
+export function renderNotes(sectionText, opts = {}) {
+  const cap = opts.cap || 150;
+  const out = [];
+  for (const block of splitBlocks(sectionText)) {
+    const line = block.lines[0];
+    if (/^## /.test(line)) { out.push("", line, ""); continue; }
+    const b = parseBullet(line);
+    if (!b) { out.push(line); continue; }
+    // 导语**只从条目首行取**：可见行必须是单行，混进换行就等于把续行又推回 details 外面。
+    // 首行剩下的部分 + 全部续行（各自保留缩进，子列表才不会塌成段落）一起进折叠块。
+    const { lede: l, consumed } = lede(b.body, cap);
+    out.push("- **" + b.title + "**" + (l ? " — " + l : ""));
+    const rest = [b.body.slice(consumed).trim(), ...block.lines.slice(1).map((c) => c.replace(/\s+$/, ""))]
+      .filter(Boolean)
+      .join("\n");
+    if (rest) out.push("  <details><summary>细节</summary>", "", "  " + rest.replace(/\n/g, "\n  "), "", "  </details>");
+  }
+  return out.join("\n").replace(/\n{3,}/g, "\n\n").trim() + "\n";
+}
+
+/** release.yml 的调用方式：node dsh-mneme/scripts/release-notes.mjs <version>（cwd 为仓库根）。 */
+function main() {
+  const v = (process.argv[2] || "").replace(/^v/, "");
+  if (!/^\d+\.\d+\.\d+$/.test(v)) { console.error("usage: release-notes.mjs <version>"); process.exit(1); }
+  const md = readFileSync("dsh-mneme/CHANGELOG.md", "utf8");
+  const sec = findSection(md, v);
+  if (!sec) { console.error("changelog section not found: " + v); process.exit(1); }
+  const body = renderNotes(sec);
+  mkdirSync("notes", { recursive: true });
+  writeFileSync("notes/body.md", body);
+  console.log("--- extracted notes ---\n" + body.slice(0, 400));
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) main();