fix(release): fix binary CI publish and clarify release modules

Stabilize Bun compile on 1.2.19, align manifests with OSS consumers,
and split gh / webhook / mode helpers out of binary-release.

Author: duck-bubi-ya

docs/agents/binary-distribution.md

@@ -31,8 +31,9 @@ Publish workflow
 ### A. 本仓库构建 / Release
 
 - [ ] `node tools/release/lib/binary-build.mjs --mode stable --host`
-- [ ] `dist-bin/` 含矩阵二进制、`SHA256SUMS`、`latest.json`（channel 为 `<name>.json`）
-- [ ] dry-run：`node tools/release/lib/binary-release.mjs --mode stable --skip-build --dry-run`
+- [ ] `dist-bin/` 含**完整**矩阵二进制、`SHA256SUMS`、`latest.json`（channel 为 `<name>.json`）
+- [ ] manifest asset 只有 `file` + `sha256`（无硬编码 `url`；客户端按 OSS `{base}/releases/{version}/{file}` 拼）
+- [ ] dry-run：`node tools/release/lib/binary-release.mjs --mode stable --dry-run`（不编译）
 - [ ] Release **不含** 生产 install 脚本
 
 ### B. 仓外（联调时确认）
@@ -53,19 +54,31 @@ node tools/release/lib/binary-release.mjs --mode stable --skip-build --dry-run
 vp check
 ```
 
+实现分层（均在 `tools/release/lib/`）：
+
+- `binary-build.mjs` / `binary-compile.mjs` — 编译 + manifest
+- `binary-options.mjs` — 共享 `--mode` / `--channel` 校验
+- `binary-release.mjs` — 编排（stable/channel 上传哪些资产）
+- `gh-release.mjs` — `gh release` create / clobber / verify
+- `oss-sync-webhook.mjs` — 可选 FC 通知
+
 ## 常见漏点
 
-| 漏点                   | 后果                      |
-| ---------------------- | ------------------------- |
-| 只发 npm、未建 Release | FC 无源可同步             |
-| FC 未跑完用户就 curl   | OSS 404 / 半包            |
-| 矩阵变更未通知脚本方   | 装错 arch / 永久失败      |
-| webhook 配错当发版失败 | 不应；webhook 失败只 warn |
-| 用 `Bun.build({ compile })` 代替 CLI | Bun ≤1.2.19 可能 exit 0 但不写 outfile → `sha256` ENOENT |
-| 编译后未 `chmod` windows `.exe` | Bun 1.2.19 在 Unix 上写出 mode `000` → `sha256` / upload `EACCES` |
+| 漏点                                 | 后果                                                              |
+| ------------------------------------ | ----------------------------------------------------------------- |
+| 只发 npm、未建 Release               | FC 无源可同步                                                     |
+| FC 未跑完用户就 curl                 | OSS 404 / 半包                                                    |
+| 矩阵变更未通知脚本方                 | 装错 arch / 永久失败                                              |
+| webhook 配错当发版失败               | 不应；webhook 失败只 warn                                         |
+| 用 `Bun.build({ compile })` 代替 CLI | Bun ≤1.2.19 可能 exit 0 但不写 outfile → `sha256` ENOENT          |
+| 编译后未 `chmod` windows `.exe`      | Bun 1.2.19 在 Unix 上写出 mode `000` → `sha256` / upload `EACCES` |
+| manifest 写死 GitHub `url`           | FC 同步后 `bl update` 仍打 GitHub，绕开 OSS                       |
+| `--dry-run` 仍全量 compile           | 本地验证极慢；dry-run 应只规划 gh / webhook                       |
+| 用 `--host` 产物去 upload            | 半包上架；release 路径会校验完整矩阵                              |
 
 ## 编译实现注意
 
 - `binary-compile.mjs` 必须走 **`bun build --compile --outfile …`**，不要用 `Bun.build({ compile })`（CI 钉 `1.2.19` 时 API 会假成功）。
 - 编译后校验 outfile 存在再算 SHA256。
 - 每个产物在哈希前 `chmod 0755`（规避 Bun 1.2.19 windows cross-compile 无权限，见 oven-sh/bun#21308）。
+- channel 同日同 commit 共用一个 `v0.0.0-beta-…` Release；滚动 tag `channel-<name>` 只挂 `<name>.json`。

docs/agents/publish.md

@@ -16,10 +16,13 @@
 ```text
 publish-stable.mjs / publish-channel.mjs   ← 唯一发版入口
         ├─ npm（pnpm publish）
-        └─ binary（lib/binary-release → lib/binary-build + gh release）
+        └─ binary（lib/binary-release
+              → binary-build
+              → gh-release
+              → oss-sync-webhook）
 ```
 
-`tools/release/lib/binary-release.mjs` / `binary-build.mjs` 是实现，一般不要单独当发版入口（调试可用）。详细约定见 [binary-distribution 方案](../proposals/binary-distribution.md)。
+`tools/release/lib/binary-release.mjs` 等是实现，一般不要单独当发版入口（调试可用）。详细约定见 [binary-distribution](binary-distribution.md)。
 
 两种模式：
 

tools/release/lib/binary-build.mjs

@@ -16,12 +16,11 @@ import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 import { parseArgs } from "node:util";
 import { ROOT, readPackageJson, PACKAGES } from "./packages.mjs";
-import { assertChannel } from "./validate.mjs";
+import { manifestFileName, normalizeModeChannel } from "./binary-options.mjs";
 
 const BINARY_COMPILE = fileURLToPath(new URL("./binary-compile.mjs", import.meta.url));
 const CLI_ENTRY = join(ROOT, "packages/cli/src/main.ts");
 const DEFAULT_OUTDIR = join(ROOT, "dist-bin");
-const DEFAULT_CDN = "https://github.com/modelstudioai/cli/releases";
 const USAGE =
   "Usage: node tools/release/lib/binary-build.mjs [--mode stable|channel] [--channel <name>] [--host] [--target <bun-target>] [--outdir <dir>]\n";
 
@@ -33,6 +32,16 @@ export const BINARY_TARGETS = [
   { bunTarget: "bun-windows-x64", os: "windows", arch: "x64", exe: true },
 ];
 
+/** Asset basename for a matrix row: `bl-<ver>-<os>-<arch>[.exe]`. */
+export function binaryAssetName(version, { os, arch, exe }) {
+  return `bl-${version}-${os}-${arch}${exe ? ".exe" : ""}`;
+}
+
+/** Full matrix basenames for a version (order matches BINARY_TARGETS). */
+export function matrixAssetNames(version) {
+  return BINARY_TARGETS.map((target) => binaryAssetName(version, target));
+}
+
 function log(message = "") {
   process.stdout.write(`${message}\n`);
 }
@@ -41,10 +50,6 @@ function writeJson(path, value) {
   writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
 }
 
-function cdnBase() {
-  return (process.env.BAILIAN_CLI_CDN || DEFAULT_CDN).replace(/\/$/, "");
-}
-
 function parseCliArgs(argv) {
   const { values } = parseArgs({
     args: argv,
@@ -78,22 +83,12 @@ function normalizeBuildOptions({
   mode = "stable",
   channel = null,
 }) {
-  if (mode !== "stable" && mode !== "channel") {
-    throw new Error(`--mode must be stable or channel, got: ${mode}`);
-  }
-  if (mode === "channel") {
-    if (!channel) throw new Error("--mode channel requires --channel <name>");
-    assertChannel(channel);
-    if (channel === "stable") {
-      throw new Error(`--channel cannot be "stable"; use --mode stable`);
-    }
-  }
+  const modeChannel = normalizeModeChannel(mode, channel);
   return {
     outdir: outdir ?? DEFAULT_OUTDIR,
     onlyTarget,
     hostOnly: Boolean(hostOnly),
-    mode,
-    channel: mode === "channel" ? channel : null,
+    ...modeChannel,
   };
 }
 
@@ -133,16 +128,12 @@ function sha256File(path) {
   return createHash("sha256").update(readFileSync(path)).digest("hex");
 }
 
-function assetFileName(version, os, arch, exe) {
-  return `bl-${version}-${os}-${arch}${exe ? ".exe" : ""}`;
-}
-
 function compileOne({ bunTarget, os, arch, exe }, version, outdir, entry) {
-  const fileName = assetFileName(version, os, arch, exe);
+  const fileName = binaryAssetName(version, { os, arch, exe });
   const outfile = join(outdir, fileName);
   log(`compile ${bunTarget} → ${fileName}`);
 
-  // Bun.build() lives in binary-compile.mjs (must run under Bun); this file stays Node.
+  // binary-compile.mjs shells out to `bun build --compile` (CLI); this file stays Node.
   const result = spawnSync(
     "bun",
     [BINARY_COMPILE, "--entry", entry, "--outfile", outfile, "--target", bunTarget],
@@ -165,15 +156,19 @@ function writeChecksums(outdir, artifacts) {
   writeFileSync(join(outdir, "SHA256SUMS"), `${lines.join("\n")}\n`);
 }
 
-function writeChannelManifest(outdir, version, artifacts, mode, channel) {
-  const base = cdnBase();
+/**
+ * Write latest.json (stable) or <channel>.json (channel).
+ * Asset entries carry file + sha256 only — no baked download URL.
+ * Consumers (bl update / install scripts) resolve via BAILIAN_CLI_CDN +
+ * `{base}/releases/{version}/{file}` (see packages/core releaseAssetUrl).
+ */
+function writeManifest(outdir, version, artifacts, mode, channel) {
   const assets = Object.fromEntries(
     artifacts.map((item) => [
       `${item.os}-${item.arch}`,
       {
         file: item.fileName,
         sha256: item.sha256,
-        url: `${base}/download/v${version}/${item.fileName}`,
       },
     ]),
   );
@@ -184,9 +179,9 @@ function writeChannelManifest(outdir, version, artifacts, mode, channel) {
     releasedAt: new Date().toISOString(),
     assets,
   };
-  const names = mode === "stable" ? ["latest.json"] : [`${channel}.json`];
-  for (const name of names) writeJson(join(outdir, name), manifest);
-  return names;
+  const name = manifestFileName(mode, channel);
+  writeJson(join(outdir, name), manifest);
+  return [name];
 }
 
 function cliVersion() {
@@ -207,7 +202,7 @@ function smokeTestHostBinary(artifacts, outdir) {
   }
 }
 
-/** Compile binaries into `outdir` and write checksums + channel manifest. */
+/** Compile binaries into `outdir` and write checksums + manifest. */
 export function buildBinaryArtifacts(rawOptions = {}) {
   const options = normalizeBuildOptions(rawOptions);
   const { outdir, mode, channel } = options;
@@ -223,7 +218,7 @@ export function buildBinaryArtifacts(rawOptions = {}) {
 
   const artifacts = targets.map((target) => compileOne(target, version, outdir, CLI_ENTRY));
   writeChecksums(outdir, artifacts);
-  const manifests = writeChannelManifest(outdir, version, artifacts, mode, channel);
+  const manifests = writeManifest(outdir, version, artifacts, mode, channel);
   smokeTestHostBinary(artifacts, outdir);
 
   log(`\nBuilt ${artifacts.length} binary(ies):`);

tools/release/lib/binary-compile.mjs

@@ -2,9 +2,8 @@
  * Single-target Bun compile helper. Must be run with Bun on PATH:
  *   bun tools/release/lib/binary-compile.mjs --entry <path> --outfile <path> --target <bun-target>
  *
- * Uses `bun build --compile` (CLI), not `Bun.build({ compile })`.
- * Bun ≤1.2.19's Build API can report success without writing `compile.outfile`
- * (API support landed properly around 1.2.21). CLI works on the pinned CI version.
+ * Uses `bun build --compile` (CLI). The Bun.build({ compile }) API on ≤1.2.19
+ * can exit 0 without writing outfile; CI pins 1.2.19 so we stay on the CLI.
  *
  * Called by binary-build.mjs (Node orchestration stays on Node).
  */
@@ -61,9 +60,6 @@ if (result.status !== 0) {
 }
 
 if (!existsSync(outfile)) {
-  console.error(
-    `bun build --compile exited 0 but outfile missing: ${outfile}\n` +
-      `(Bun Build API compile.outfile is unreliable on some versions; this helper uses the CLI.)`,
-  );
+  console.error(`bun build --compile exited 0 but outfile missing: ${outfile}`);
   process.exit(1);
 }

tools/release/lib/binary-options.mjs

@@ -0,0 +1,29 @@
+/**
+ * Shared mode / channel / manifest naming for binary-build and binary-release.
+ */
+import { assertChannel } from "./validate.mjs";
+
+/**
+ * @param {string} mode
+ * @param {string | null | undefined} channel
+ * @returns {{ mode: "stable" | "channel", channel: string | null }}
+ */
+export function normalizeModeChannel(mode = "stable", channel = null) {
+  if (mode !== "stable" && mode !== "channel") {
+    throw new Error(`--mode must be stable or channel, got: ${mode}`);
+  }
+  if (mode === "channel") {
+    if (!channel) throw new Error("--mode channel requires --channel <name>");
+    assertChannel(channel);
+    if (channel === "stable") {
+      throw new Error(`--channel cannot be "stable"; use --mode stable`);
+    }
+    return { mode, channel };
+  }
+  return { mode: "stable", channel: null };
+}
+
+/** Manifest basename written to dist-bin / uploaded to Releases. */
+export function manifestFileName(mode, channel) {
+  return mode === "stable" ? "latest.json" : `${channel}.json`;
+}