feat(release): distribute binaries as per-platform zips

Author: duck-bubi-ya

.github/workflows/publish.yml

@@ -18,7 +18,7 @@ on:
           - channel
           - stable
       channel:
-        description: "dist-tag (channel mode only, e.g. mcp/plugin/advisor)"
+        description: "Required when mode=channel. dist-tag name, e.g. mcp / plugin / release-test (lowercase, digits, dashes)"
         required: false
         type: string
 
@@ -55,6 +55,9 @@ jobs:
             | sudo tar -xz -C /usr/local/bin gitleaks
           gitleaks version
 
+      - name: Ensure zip (per-platform binary archives)
+        run: sudo apt-get update && sudo apt-get install -y zip
+
       - run: pnpm install --frozen-lockfile
 
       # Binary compile uses `bun build --compile` CLI (not Bun.build API).
@@ -78,6 +81,12 @@ jobs:
       contents: write # create prerelease GitHub Release with binary assets
       id-token: write # OIDC for npm Trusted Publishing + provenance
     steps:
+      - name: Require channel input
+        if: ${{ inputs.channel == '' }}
+        run: |
+          echo "::error::mode=channel requires the workflow input \"channel\" (e.g. mcp, plugin, release-test). Leave mode=stable if you do not need a dist-tag."
+          exit 1
+
       - uses: actions/checkout@v6
 
       - uses: pnpm/action-setup@v6
@@ -97,6 +106,9 @@ jobs:
             | sudo tar -xz -C /usr/local/bin gitleaks
           gitleaks version
 
+      - name: Ensure zip (per-platform binary archives)
+        run: sudo apt-get update && sudo apt-get install -y zip
+
       - run: pnpm install --frozen-lockfile
 
       # Binary compile uses `bun build --compile` CLI (not Bun.build API).

docs/agents/binary-distribution.md

@@ -108,7 +108,7 @@ node tools/release/publish-channel.mjs --channel test --knowledge --dry-run
 
 - [ ] 验证 npm 上能装：`npm view bailian-cli@<tag> version`;如发布 `knowledge-studio-cli`，同时 `npm view knowledge-studio-cli@<tag> version`
 - [ ] 试装一次：`npm i -g bailian-cli@<tag> && bl --version`;如发布 `knowledge-studio-cli`，同时 `npm i -g knowledge-studio-cli@<tag> && kscli --version`
-- [ ] （若本次含二进制）GitHub Release 页可见资产，`install.sh` / `latest.json` 经 FC 同步到 OSS 后可访问；清单见 [binary-distribution.md](binary-distribution.md)
+- [ ] （若本次含二进制）GitHub Release 可见 `bl-*.zip` + `SHA256SUMS`；OSS 侧 `channels/latest.json` 与 install 脚本由 FC/仓外维护；清单见 [binary-distribution.md](binary-distribution.md)
 
 ## 常见漏点（基于历史踩坑）
 

docs/agents/publish.md

@@ -21,7 +21,8 @@ export function getCliCdnBase(): string {
 
 /**
  * Channel manifest on OSS (after FC sync): `{base}/channels/{channel}.json`
- * Formal releases use `latest.json` (default).
+ * Formal installs still read `channels/latest.json` on OSS; this repo no longer
+ * attaches `latest.json` to GitHub Releases (FC / ops maintain OSS latest).
  */
 export function channelManifestUrl(channel = "latest"): string {
   return `${getCliCdnBase()}/channels/${channel}.json`;
@@ -66,7 +67,18 @@ export function detectBinaryPlatform(): { os: string; arch: string; fileSuffix:
   return { os, arch: normalizedArch, fileSuffix };
 }
 
+/** Release download asset: `bl-<ver>-<os>-<arch>.zip`. */
 export function binaryAssetFileName(
+  version: string,
+  os: string,
+  arch: string,
+  _exe = false,
+): string {
+  return `bl-${version}-${os}-${arch}.zip`;
+}
+
+/** Uncompressed binary name inside the zip. */
+export function binaryInnerFileName(
   version: string,
   os: string,
   arch: string,

packages/core/src/install/cdn.ts

@@ -11,8 +11,10 @@ export {
   DEFAULT_INSTALL_SCRIPT_URL,
   GITHUB_RELEASES_BASE,
   binaryAssetFileName,
+  binaryInnerFileName,
   channelManifestUrl,
   detectBinaryPlatform,
   getCliCdnBase,
   releaseAssetUrl,
 } from "./cdn.ts";
+export { extractZipEntryToFile } from "./unzip-asset.ts";

packages/core/src/install/index.ts

@@ -0,0 +1,109 @@
+/**
+ * Extract a single file entry from a ZIP into `destPath` (overwrites).
+ * Uses yauzl (already a core dependency for dataset ZIP validation).
+ */
+import { createWriteStream } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { pipeline } from "node:stream/promises";
+import * as yauzl from "yauzl";
+
+function openZip(zipPath: string): Promise<yauzl.ZipFile> {
+  return new Promise((resolve, reject) => {
+    yauzl.open(zipPath, { lazyEntries: true }, (error, zipfile) => {
+      if (error || !zipfile) {
+        reject(error ?? new Error(`Failed to open zip: ${zipPath}`));
+        return;
+      }
+      resolve(zipfile);
+    });
+  });
+}
+
+function entryBaseName(fileName: string): string {
+  const normalized = fileName.replace(/\\/g, "/");
+  return normalized.includes("/") ? normalized.slice(normalized.lastIndexOf("/") + 1) : normalized;
+}
+
+/**
+ * Extract `entryName` (or the first non-directory entry) from `zipPath` to `destPath`.
+ * Returns the archive entry basename that was extracted.
+ */
+export async function extractZipEntryToFile(
+  zipPath: string,
+  destPath: string,
+  entryName?: string,
+): Promise<string> {
+  const zipfile = await openZip(zipPath);
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+
+    const fail = (error: unknown) => {
+      if (settled) return;
+      settled = true;
+      try {
+        zipfile.close();
+      } catch {
+        /* ignore */
+      }
+      reject(error instanceof Error ? error : new Error(String(error)));
+    };
+
+    const succeed = (baseName: string) => {
+      if (settled) return;
+      settled = true;
+      try {
+        zipfile.close();
+      } catch {
+        /* ignore */
+      }
+      resolve(baseName);
+    };
+
+    zipfile.on("error", fail);
+    zipfile.on("end", () => {
+      if (settled) return;
+      fail(
+        new Error(
+          entryName
+            ? `Zip entry not found: ${entryName} in ${zipPath}`
+            : `Zip has no file entries: ${zipPath}`,
+        ),
+      );
+    });
+
+    zipfile.on("entry", (current: yauzl.Entry) => {
+      if (settled) return;
+      const name = current.fileName.replace(/\\/g, "/");
+      if (name.endsWith("/")) {
+        zipfile.readEntry();
+        return;
+      }
+      const base = entryBaseName(name);
+      const isMatch = entryName ? name === entryName || base === entryName : true;
+      if (!isMatch) {
+        zipfile.readEntry();
+        return;
+      }
+
+      zipfile.openReadStream(current, (streamError, readStream) => {
+        if (streamError || !readStream) {
+          fail(streamError ?? new Error(`Failed to read zip entry: ${current.fileName}`));
+          return;
+        }
+        void (async () => {
+          try {
+            await mkdir(dirname(destPath), { recursive: true });
+            await pipeline(readStream, createWriteStream(destPath));
+            succeed(base);
+          } catch (error) {
+            fail(error);
+          }
+        })();
+      });
+    });
+
+    zipfile.readEntry();
+  });
+}

packages/core/src/install/unzip-asset.ts

@@ -3,6 +3,7 @@ import {
   detectInstallMethod,
   isCompiledBinary,
   binaryAssetFileName,
+  binaryInnerFileName,
 } from "../src/install/index.ts";
 
 test("isCompiledBinary respects BAILIAN_COMPILED", () => {
@@ -23,7 +24,12 @@ test("detectInstallMethod respects BAILIAN_INSTALL_METHOD", () => {
   else process.env.BAILIAN_INSTALL_METHOD = previous;
 });
 
-test("binaryAssetFileName formats windows exe", () => {
-  expect(binaryAssetFileName("1.2.3", "windows", "x64", true)).toBe("bl-1.2.3-windows-x64.exe");
-  expect(binaryAssetFileName("1.2.3", "darwin", "arm64", false)).toBe("bl-1.2.3-darwin-arm64");
+test("binaryAssetFileName uses per-platform zip", () => {
+  expect(binaryAssetFileName("1.2.3", "windows", "x64", true)).toBe("bl-1.2.3-windows-x64.zip");
+  expect(binaryAssetFileName("1.2.3", "darwin", "arm64", false)).toBe("bl-1.2.3-darwin-arm64.zip");
+});
+
+test("binaryInnerFileName keeps exe suffix inside zip", () => {
+  expect(binaryInnerFileName("1.2.3", "windows", "x64", true)).toBe("bl-1.2.3-windows-x64.exe");
+  expect(binaryInnerFileName("1.2.3", "darwin", "arm64", false)).toBe("bl-1.2.3-darwin-arm64");
 });

packages/core/tests/install-method.test.ts

@@ -1,19 +1,21 @@
-import { mkdir, rename, unlink, writeFile, chmod } from "node:fs/promises";
+import { mkdir, rename, unlink, writeFile, chmod, readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 import {
   binaryAssetFileName,
+  binaryInnerFileName,
   channelManifestUrl,
   detectBinaryPlatform,
+  extractZipEntryToFile,
   getConfigDir,
   releaseAssetUrl,
   writeInstallMethodSync,
 } from "bailian-cli-core";
 
 export interface ChannelManifest {
   version: string;
-  assets?: Record<string, { file?: string; sha256?: string; url?: string }>;
+  assets?: Record<string, { file?: string; sha256?: string; url?: string; inner?: string }>;
 }
 
 export async function fetchBinaryChannelVersion(
@@ -81,40 +83,46 @@ function sha256(buffer: Buffer): string {
 
 /**
  * Download and install a newer standalone binary in place of the current install.
+ * Assets are per-platform `.zip` files; checksum applies to the zip.
  * Returns the installed version string.
  */
 export async function performBinaryUpdate(targetVersion: string): Promise<string> {
   const { os, arch, fileSuffix } = detectBinaryPlatform();
+  const exe = fileSuffix === ".exe";
   const manifest = await fetchBinaryChannelManifest("latest");
   const assetKey = `${os}-${arch}`;
   const assetMeta = manifest?.assets?.[assetKey];
-  const fileName =
-    assetMeta?.file ?? binaryAssetFileName(targetVersion, os, arch, fileSuffix === ".exe");
+  const zipName = assetMeta?.file ?? binaryAssetFileName(targetVersion, os, arch, exe);
+  const innerName = assetMeta?.inner ?? binaryInnerFileName(targetVersion, os, arch, exe);
   const expectedSha = assetMeta?.sha256;
-  const url = assetMeta?.url ?? releaseAssetUrl(targetVersion, fileName);
+  const url = assetMeta?.url ?? releaseAssetUrl(targetVersion, zipName);
 
-  const tmpPath = join(shareRoot(), ".tmp", fileName);
-  const buffer = await downloadToFile(url, tmpPath);
+  const tmpZip = join(shareRoot(), ".tmp", zipName);
+  const buffer = await downloadToFile(url, tmpZip);
   const actualSha = sha256(buffer);
   if (expectedSha && expectedSha !== actualSha) {
-    await unlink(tmpPath).catch(() => {});
-    throw new Error(`Checksum mismatch for ${fileName}`);
+    await unlink(tmpZip).catch(() => {});
+    throw new Error(`Checksum mismatch for ${zipName}`);
   }
 
   const versionDir = join(shareRoot(), "versions", targetVersion);
   await mkdir(versionDir, { recursive: true });
   const binaryName = process.platform === "win32" ? "bl.exe" : "bl";
   const finalPath = join(versionDir, binaryName);
-  await rename(tmpPath, finalPath);
+  const tmpBinary = join(shareRoot(), ".tmp", binaryName);
+  await extractZipEntryToFile(tmpZip, tmpBinary, innerName);
+  await unlink(tmpZip).catch(() => {});
+  await rename(tmpBinary, finalPath);
   if (process.platform !== "win32") {
     await chmod(finalPath, 0o755);
   }
 
   const binDir = binRoot();
   await mkdir(binDir, { recursive: true });
   if (process.platform === "win32") {
-    await writeFile(join(binDir, "bl.exe"), buffer);
-    await writeFile(join(binDir, "bailian.exe"), buffer);
+    const installed = await readFile(finalPath);
+    await writeFile(join(binDir, "bl.exe"), installed);
+    await writeFile(join(binDir, "bailian.exe"), installed);
   } else {
     const { symlink } = await import("node:fs/promises");
     for (const name of ["bl", "bailian"] as const) {