larkin 0.2.75 → 0.2.77

package/dist/platform/callback-capability.cjs

@@ -50,6 +50,7 @@ exports.verifyCallbackProbe = verifyCallbackProbe;
 const node_crypto_1 = require("node:crypto");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const secure_metadata_js_1 = require("./secure-metadata.cjs");
 const APP_ID = /^cli_[A-Za-z0-9]+$/;
 const NONCE = /^[a-f0-9]{32}$/;
 function credentialFile(configDir, appId) {
@@ -59,7 +60,7 @@ function credentialFile(configDir, appId) {
 }
 function readCredential(file) {
     const stat = fs.lstatSync(file);
-    if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o777) !== 0o600
+    if (!stat.isFile() || stat.isSymbolicLink() || !(0, secure_metadata_js_1.exactMode)(stat, 0o600)
         || (typeof process.getuid === "function" && stat.uid !== process.getuid())) {
         throw new Error("callback capability credential must be an owned 0600 regular file");
     }

package/dist/platform/callback-capability.mjs

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { exactMode } from "./secure-metadata.mjs";
 const APP_ID = /^cli_[A-Za-z0-9]+$/;
 const NONCE = /^[a-f0-9]{32}$/;
 function credentialFile(configDir, appId) {
@@ -10,7 +11,7 @@ function credentialFile(configDir, appId) {
 }
 function readCredential(file) {
     const stat = fs.lstatSync(file);
-    if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o777) !== 0o600
+    if (!stat.isFile() || stat.isSymbolicLink() || !exactMode(stat, 0o600)
         || (typeof process.getuid === "function" && stat.uid !== process.getuid())) {
         throw new Error("callback capability credential must be an owned 0600 regular file");
     }

package/dist/platform/config.cjs

@@ -60,6 +60,7 @@ const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const root_layout_js_1 = require("./root-layout.cjs");
+const secure_metadata_js_1 = require("./secure-metadata.cjs");
 const runtime_model_catalog_js_1 = require("../runtime/runtime-model-catalog.cjs");
 const process_inspect_cjs_1 = __importDefault(require("./process-inspect.cjs"));
 const TOP_FIELDS_V3 = new Set(["version", "serverId", "activeAgent", "agents"]);
@@ -264,7 +265,7 @@ function assertPrivateConfigMetadata(metadata, label = "配置文件") {
         throw new Error(`${label} 必须是普通文件`);
     if (typeof process.getuid === "function" && metadata.uid !== process.getuid())
         throw new Error(`${label} owner 不是当前用户`);
-    if ((metadata.mode & 0o777) !== 0o600)
+    if (!(0, secure_metadata_js_1.exactMode)(metadata, 0o600))
         throw new Error(`${label} 权限必须是 0600`);
 }
 function readPrivateFile(file, root, limit, label) {
@@ -663,13 +664,7 @@ function atomicWriteConfig(file, value) {
     try {
         fs.renameSync(temporary, file);
         fs.chmodSync(file, 0o600);
-        const dirFd = fs.openSync(path.dirname(file), "r");
-        try {
-            fs.fsyncSync(dirFd);
-        }
-        finally {
-            fs.closeSync(dirFd);
-        }
+        (0, secure_metadata_js_1.fsyncDirectoryOf)(file);
     }
     catch (error) {
         try {

package/dist/platform/config.mjs

@@ -3,6 +3,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { TargetRootLayout, resolveConfigDir as resolveRootConfigDir } from "./root-layout.mjs";
+import { exactMode, fsyncDirectoryOf } from "./secure-metadata.mjs";
 import { CURRENT_RUNTIME_MODELS } from "../runtime/runtime-model-catalog.mjs";
 import processInspect from "./process-inspect.cjs";
 const TOP_FIELDS_V3 = new Set(["version", "serverId", "activeAgent", "agents"]);
@@ -207,7 +208,7 @@ export function assertPrivateConfigMetadata(metadata, label = "配置文件") {
         throw new Error(`${label} 必须是普通文件`);
     if (typeof process.getuid === "function" && metadata.uid !== process.getuid())
         throw new Error(`${label} owner 不是当前用户`);
-    if ((metadata.mode & 0o777) !== 0o600)
+    if (!exactMode(metadata, 0o600))
         throw new Error(`${label} 权限必须是 0600`);
 }
 function readPrivateFile(file, root, limit, label) {
@@ -606,13 +607,7 @@ function atomicWriteConfig(file, value) {
     try {
         fs.renameSync(temporary, file);
         fs.chmodSync(file, 0o600);
-        const dirFd = fs.openSync(path.dirname(file), "r");
-        try {
-            fs.fsyncSync(dirFd);
-        }
-        finally {
-            fs.closeSync(dirFd);
-        }
+        fsyncDirectoryOf(file);
     }
     catch (error) {
         try {

package/dist/platform/release-artifacts.mjs

@@ -6,6 +6,7 @@ export const RELEASE_TARGETS = Object.freeze([
     { platform: "darwin", arch: "x64", bunTarget: "bun-darwin-x64-baseline" },
     { platform: "linux", arch: "arm64", bunTarget: "bun-linux-arm64" },
     { platform: "linux", arch: "x64", bunTarget: "bun-linux-x64-baseline" },
+    { platform: "windows", arch: "x64", bunTarget: "bun-windows-x64-baseline" },
 ]);
 export function artifactFilename(version, platform, arch) {
     if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version))
@@ -13,14 +14,20 @@ export function artifactFilename(version, platform, arch) {
     if (!RELEASE_TARGETS.some((target) => target.platform === platform && target.arch === arch)) {
         throw new Error(`unsupported release target: ${platform}-${arch}`);
     }
-    return `larkin-v${version}-${platform}-${arch}`;
+    const suffix = platform === "windows" ? ".exe" : "";
+    return `larkin-v${version}-${platform}-${arch}${suffix}`;
+}
+/** Node's `os.platform()` reports Windows as "win32"; canonical release manifests use "windows". */
+export function normalizeReleasePlatform(platform) {
+    return platform === "win32" ? "windows" : platform;
 }
 export function sha256File(file) {
     return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
 }
 export function selectReleaseArtifact(manifest, platform, arch) {
-    const record = manifest.artifacts.find((candidate) => candidate.platform === platform && candidate.arch === arch);
-    if (!record || !RELEASE_TARGETS.some((target) => target.platform === platform && target.arch === arch)) {
+    const canonicalPlatform = normalizeReleasePlatform(platform);
+    const record = manifest.artifacts.find((candidate) => candidate.platform === canonicalPlatform && candidate.arch === arch);
+    if (!record || !RELEASE_TARGETS.some((target) => target.platform === canonicalPlatform && target.arch === arch)) {
         throw new Error(`unsupported platform: ${platform}-${arch}`);
     }
     if (record.file !== artifactFilename(manifest.version, record.platform, record.arch) || !/^[a-f0-9]{64}$/.test(record.sha256)) {

package/dist/platform/secure-metadata.cjs

@@ -0,0 +1,48 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWindows = void 0;
+exports.exactMode = exactMode;
+exports.notGroupOrWorldAccessible = notGroupOrWorldAccessible;
+exports.fsyncDirectory = fsyncDirectory;
+exports.fsyncDirectoryOf = fsyncDirectoryOf;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Cross-platform secure-metadata helpers. POSIX platforms enforce ownership and
+ * mode bits (fail-closed). Windows has no POSIX mode bits, so mode-bit assertions
+ * are skipped there; ownership on Windows is enforced by the filesystem/ACL and the
+ * parent-directory containment checks elsewhere. Windows runtime behavior is marked
+ * unverified (Owner decision B: no Windows validation in this delivery).
+ */
+exports.isWindows = process.platform === "win32";
+/** POSIX: `mode & 0o777` must equal `expected`. Windows: always passes. */
+function exactMode(stat, expected) {
+    if (exports.isWindows)
+        return true;
+    return (stat.mode & 0o777) === expected;
+}
+/** POSIX: group/other must have no access bits. Windows: always passes. */
+function notGroupOrWorldAccessible(stat) {
+    if (exports.isWindows)
+        return true;
+    return (stat.mode & 0o077) === 0;
+}
+/** Fsync a directory after rename for durability. Windows cannot open a directory for fsync, so this is a no-op. */
+function fsyncDirectory(directory) {
+    if (exports.isWindows)
+        return;
+    const fd = node_fs_1.default.openSync(directory, node_fs_1.default.constants.O_RDONLY);
+    try {
+        node_fs_1.default.fsyncSync(fd);
+    }
+    finally {
+        node_fs_1.default.closeSync(fd);
+    }
+}
+/** Fsync the parent directory of `file` after rename for durability. Windows: no-op. */
+function fsyncDirectoryOf(file) {
+    fsyncDirectory(node_path_1.default.dirname(file));
+}

package/dist/platform/secure-metadata.mjs

@@ -0,0 +1,38 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Cross-platform secure-metadata helpers. POSIX platforms enforce ownership and
+ * mode bits (fail-closed). Windows has no POSIX mode bits, so mode-bit assertions
+ * are skipped there; ownership on Windows is enforced by the filesystem/ACL and the
+ * parent-directory containment checks elsewhere. Windows runtime behavior is marked
+ * unverified (Owner decision B: no Windows validation in this delivery).
+ */
+export const isWindows = process.platform === "win32";
+/** POSIX: `mode & 0o777` must equal `expected`. Windows: always passes. */
+export function exactMode(stat, expected) {
+    if (isWindows)
+        return true;
+    return (stat.mode & 0o777) === expected;
+}
+/** POSIX: group/other must have no access bits. Windows: always passes. */
+export function notGroupOrWorldAccessible(stat) {
+    if (isWindows)
+        return true;
+    return (stat.mode & 0o077) === 0;
+}
+/** Fsync a directory after rename for durability. Windows cannot open a directory for fsync, so this is a no-op. */
+export function fsyncDirectory(directory) {
+    if (isWindows)
+        return;
+    const fd = fs.openSync(directory, fs.constants.O_RDONLY);
+    try {
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** Fsync the parent directory of `file` after rename for durability. Windows: no-op. */
+export function fsyncDirectoryOf(file) {
+    fsyncDirectory(path.dirname(file));
+}

package/dist/platform/telemetry-spool.cjs

@@ -10,6 +10,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_zlib_1 = __importDefault(require("node:zlib"));
 const process_state_js_1 = require("./process-state.cjs");
+const secure_metadata_js_1 = require("./secure-metadata.cjs");
 const READY = /^(?:span-[0-9a-f-]+|import-[0-9a-f]{64})\.json$/;
 const REMNANT = /^\.(?:corrupt|write|ack|delete|stale-lock|purge)-[0-9A-Za-z-]+(?:\.(?:json|tmp|dir))?$/;
 const HEX_TRACE = /^[0-9a-f]{32}$/;
@@ -333,13 +334,7 @@ class TelemetrySpool {
             descriptor = undefined;
             node_fs_1.default.renameSync(temporary, file);
             node_fs_1.default.chmodSync(file, 0o600);
-            const directory = node_fs_1.default.openSync(this.config.spoolDir, node_fs_1.default.constants.O_RDONLY);
-            try {
-                node_fs_1.default.fsyncSync(directory);
-            }
-            finally {
-                node_fs_1.default.closeSync(directory);
-            }
+            (0, secure_metadata_js_1.fsyncDirectory)(this.config.spoolDir);
         }
         finally {
             if (descriptor !== undefined)
@@ -479,13 +474,7 @@ class TelemetrySpool {
             }
             for (const entry of moved)
                 node_fs_1.default.unlinkSync(entry.quarantine);
-            const directory = node_fs_1.default.openSync(this.config.spoolDir, node_fs_1.default.constants.O_RDONLY);
-            try {
-                node_fs_1.default.fsyncSync(directory);
-            }
-            finally {
-                node_fs_1.default.closeSync(directory);
-            }
+            (0, secure_metadata_js_1.fsyncDirectory)(this.config.spoolDir);
         }
         catch {
             for (const entry of moved.reverse())

package/dist/platform/telemetry-spool.mjs

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import zlib from "node:zlib";
 import { inspectProcess } from "./process-state.mjs";
+import { fsyncDirectory } from "./secure-metadata.mjs";
 const READY = /^(?:span-[0-9a-f-]+|import-[0-9a-f]{64})\.json$/;
 const REMNANT = /^\.(?:corrupt|write|ack|delete|stale-lock|purge)-[0-9A-Za-z-]+(?:\.(?:json|tmp|dir))?$/;
 const HEX_TRACE = /^[0-9a-f]{32}$/;
@@ -326,13 +327,7 @@ export class TelemetrySpool {
             descriptor = undefined;
             fs.renameSync(temporary, file);
             fs.chmodSync(file, 0o600);
-            const directory = fs.openSync(this.config.spoolDir, fs.constants.O_RDONLY);
-            try {
-                fs.fsyncSync(directory);
-            }
-            finally {
-                fs.closeSync(directory);
-            }
+            fsyncDirectory(this.config.spoolDir);
         }
         finally {
             if (descriptor !== undefined)
@@ -472,13 +467,7 @@ export class TelemetrySpool {
             }
             for (const entry of moved)
                 fs.unlinkSync(entry.quarantine);
-            const directory = fs.openSync(this.config.spoolDir, fs.constants.O_RDONLY);
-            try {
-                fs.fsyncSync(directory);
-            }
-            finally {
-                fs.closeSync(directory);
-            }
+            fsyncDirectory(this.config.spoolDir);
         }
         catch {
             for (const entry of moved.reverse())

package/dist/platform/telemetry-tracing.cjs

@@ -15,6 +15,7 @@ const sdk_trace_node_1 = require("@opentelemetry/sdk-trace-node");
 const telemetry_spool_js_1 = require("./telemetry-spool.cjs");
 const telemetry_uploader_js_1 = require("./telemetry-uploader.cjs");
 const process_state_js_1 = require("./process-state.cjs");
+const secure_metadata_js_1 = require("./secure-metadata.cjs");
 const nanos = ([seconds, nanoseconds]) => (BigInt(seconds) * 1000000000n + BigInt(nanoseconds)).toString();
 // OTel JS uses zero-based SpanKind values while OTLP's enum starts at 1.
 const kind = (value) => value + 1;
@@ -82,13 +83,7 @@ function atomicStateWrite(file, value) {
         node_fs_1.default.writeFileSync(temporary, JSON.stringify(value), { mode: 0o600, flag: "wx" });
         node_fs_1.default.renameSync(temporary, file);
         node_fs_1.default.chmodSync(file, 0o600);
-        const directory = node_fs_1.default.openSync(node_path_1.default.dirname(file), node_fs_1.default.constants.O_RDONLY);
-        try {
-            node_fs_1.default.fsyncSync(directory);
-        }
-        finally {
-            node_fs_1.default.closeSync(directory);
-        }
+        (0, secure_metadata_js_1.fsyncDirectoryOf)(file);
     }
     finally {
         try {

package/dist/platform/telemetry-tracing.mjs

@@ -8,6 +8,7 @@ import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
 import { TelemetrySpool } from "./telemetry-spool.mjs";
 import { startTelemetryUploader } from "./telemetry-uploader.mjs";
 import { inspectProcess } from "./process-state.mjs";
+import { fsyncDirectoryOf } from "./secure-metadata.mjs";
 const nanos = ([seconds, nanoseconds]) => (BigInt(seconds) * 1000000000n + BigInt(nanoseconds)).toString();
 // OTel JS uses zero-based SpanKind values while OTLP's enum starts at 1.
 const kind = (value) => value + 1;
@@ -75,13 +76,7 @@ function atomicStateWrite(file, value) {
         fs.writeFileSync(temporary, JSON.stringify(value), { mode: 0o600, flag: "wx" });
         fs.renameSync(temporary, file);
         fs.chmodSync(file, 0o600);
-        const directory = fs.openSync(path.dirname(file), fs.constants.O_RDONLY);
-        try {
-            fs.fsyncSync(directory);
-        }
-        finally {
-            fs.closeSync(directory);
-        }
+        fsyncDirectoryOf(file);
     }
     finally {
         try {

package/dist/setup/bot-register.mjs

@@ -435,7 +435,7 @@ export async function main() {
         die("--result-file 必须是配置根目录内的 .setup-result-<pid>.json");
     }
     if (argv.some((arg) => arg === "--app-id" || arg.startsWith("--app-id="))) {
-        die("不支持 --app-id；机器人必须在飞书网页中选择");
+        die("不支持 --app-id；机器人必须在飞书（Lark）网页中选择");
     }
     if (!autoSelect)
         die("setup 注册阶段必须由交互式选择流程启动");
@@ -482,16 +482,16 @@ export async function main() {
         },
         onQRCodeReady: ({ url, expireIn }) => {
             qrcode.generate(url, { small: true }, (code) => say(code));
-            say(`\n打开以下链接（或扫码），${Math.round(expireIn / 60)} 分钟内有效：\n\n  ${url}\n\n[setup 2/5] 等待飞书网页完成授权并回传凭证…`);
+            say(`\n打开以下链接（或扫码），${Math.round(expireIn / 60)} 分钟内有效：\n\n  ${url}\n\n[setup 2/5] 等待飞书（Lark）网页完成授权并回传凭证…`);
             say(openBrowser(url) ? "[setup] 已在默认浏览器打开授权页" : "[setup] 未能自动打开浏览器，请手动打开上面的链接");
         },
         onStatusChange: ({ status, interval }) => {
             if (status === "domain_switched")
                 say("[setup] 已切换到 Lark 域名");
             if (status === "slow_down")
-                say(`[setup] 飞书要求降低轮询频率，${interval || "稍后"}秒后继续`);
+                say(`[setup] 飞书（Lark）要求降低轮询频率，${interval || "稍后"}秒后继续`);
             if (status === "polling" && ++pollingCount % 12 === 0)
-                say(`[setup] 仍在等待飞书回传凭证（约 ${pollingCount / 12} 分钟）…`);
+                say(`[setup] 仍在等待飞书（Lark）回传凭证（约 ${pollingCount / 12} 分钟）…`);
         },
     }).catch(() => die("网页授权失败；未执行凭证同步、文件写入或 Agent 绑定，请重试 setup"));
     const { client_id: rawId, client_secret: rawSecret, user_info: userInfo } = result || {};
@@ -559,7 +559,7 @@ export async function main() {
                         throw new Error(`官方 Pi ${providerId} 登录失败或已取消；credential/config 未修改`);
                     }
                     if (process.env.LARKIN_TEST_SKIP_BUILTIN_PI_PROVIDER_TURN !== "1") {
-                        say("正在验证内置 Pi provider（受控单轮，不发送飞书消息）…");
+                        say("正在验证内置 Pi provider（受控单轮，不发送飞书（Lark）消息）…");
                         try {
                             await verifyOfficialPiProviderTurn(piRuntime, choice.model);
                         }

package/dist/setup/grant-scopes.mjs

@@ -39,7 +39,7 @@ const APP_ID = selected.agentId;
 if (explicitAppId && explicitAppId !== selected.feishuAppId)
     throw new Error("--app-id 必须等于所选 Agent 的 App ID");
 if (!/^cli_[A-Za-z0-9]+$/.test(APP_ID))
-    throw new Error(`无效飞书 App ID：${APP_ID}`);
+    throw new Error(`无效飞书（Lark） App ID：${APP_ID}`);
 const SEND_TO = flag("--send-to", "");
 const TENANT = flag("--tenant", "feishu");
 const WAIT_MIN = Number(flag("--wait-min", "9"));
@@ -76,7 +76,7 @@ function sendUrlToChat(url, minutes) {
     const result = spawnSync(managed.command.command, [...managed.command.argsPrefix, "im", "+messages-send", "--chat-id", SEND_TO, "--text", text, "--json"], {
         encoding: "utf8", env: managed.env,
     });
-    log(result.status === 0 ? "[grant] 更新链接已发到飞书群" : `[grant] 发链接失败: ${(result.stderr || "").trim().split("\n")[0]}`);
+    log(result.status === 0 ? "[grant] 更新链接已发到飞书（Lark）群" : `[grant] 发链接失败: ${(result.stderr || "").trim().split("\n")[0]}`);
 }
 export async function main() {
     log(`=== 给 bot ${APP_ID} 增补读取权限(registerApp 更新流) ===`);
@@ -94,7 +94,7 @@ export async function main() {
         },
         onQRCodeReady: (info) => {
             const minutes = Math.max(1, Math.round(info.expireIn / 60));
-            log("\n请用飞书扫码或打开链接，确认给应用增补权限：\n");
+            log("\n请用飞书（Lark）扫码或打开链接，确认给应用增补权限：\n");
             qrcode.generate(info.url, { small: true });
             log(`\n链接: ${info.url}\n有效期约 ${minutes} 分钟（⚠️ 需本进程保持轮询，否则 user_code 立即失效）\n`);
             if (URL_FILE) {

package/dist/setup/setup-bind.mjs

@@ -87,7 +87,7 @@ async function pickProfile() {
     const profiles = listProfiles();
     if (profiles.length === 0)
         die("lark-cli 里还没有 bot profile。请运行 larkin setup 创建或连接机器人");
-    say("\n可复用的飞书机器人（lark-cli profiles）：");
+    say("\n可复用的飞书（Lark）机器人（lark-cli profiles）：");
     profiles.forEach((profile, index) => say(`  [${index + 1}] ${profile.name}  appId=${profile.appId}${profile.active ? "  (当前活跃，默认)" : ""}`));
     say("  （创建新机器人请退出后运行 larkin setup）");
     const activeIndex = Math.max(0, profiles.findIndex((profile) => profile.active));
@@ -298,7 +298,7 @@ export async function main() {
             }
             if (!readinessAlreadyCompleted) {
                 piRuntime ??= await createOfficialPiModelRuntime(CFG_DIR, profile.appId);
-                say("正在验证内置 Pi provider（受控单轮，不发送飞书消息）…");
+                say("正在验证内置 Pi provider（受控单轮，不发送飞书（Lark）消息）…");
                 try {
                     if (!(process.env.LARKIN_TEST_SKIP_BUILTIN_PI_PROVIDER_TURN === "1" && process.env.LARKIN_TEST_BOT_REGISTER_MODULE)) {
                         await verifyOfficialPiProviderTurn(piRuntime, selection.model, authAbort.signal);
@@ -329,7 +329,7 @@ export async function main() {
     say("\n启动这个 Agent：");
     say("  larkin start                     # 单服务启动全部已配置 Agent");
     say(`  larkin start --agent ${profile.appId}  # 仅调试这个 Agent`);
-    say("创建独立飞书机器人 + Agent：");
+    say("创建独立飞书（Lark）机器人 + Agent：");
     say("  larkin setup");
 }
 if (path.resolve(process.argv[1] || "") === path.resolve(fileURLToPath(import.meta.url))) {

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "larkin",
-  "version": "0.2.75",
+  "version": "0.2.77",
   "private": false,
   "larkinPackageRole": "npm-published",
   "files": [
     "dist/",
     "assets/",
+    "scripts/npm/",
     "README.md",
     "LICENSE",
     "SECURITY.md",
@@ -15,9 +16,9 @@
   "packageManager": "bun@1.3.14",
   "license": "Apache-2.0",
   "type": "module",
-  "description": "把 Codex、Claude Code 和 Pi Agent Runtime 接到飞书的本地 Runtime Host",
+  "description": "把 Codex、Claude Code 和 Pi Agent Runtime 接到飞书（Lark）的本地 Runtime Host",
   "bin": {
-    "larkin": "dist/app/cli.mjs"
+    "larkin": "scripts/npm/larkin-bin-shim.mjs"
   },
   "repository": {
     "type": "git",
@@ -28,6 +29,7 @@
     "typecheck": "bun run scripts/typecheck.mjs",
     "build": "bun run scripts/build.mjs",
     "prepare": "bun run build",
+    "postinstall": "node scripts/npm/install-binary.mjs",
     "version:bump": "bun run scripts/bump-version.mjs",
     "release:check-version": "bun run scripts/check-release-version.mjs",
     "release:smoke": "bun run scripts/release/smoke.ts",

package/scripts/npm/install-binary.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// npm postinstall: download the matching platform standalone binary from the
+// GitHub Release for this package version, verify its SHA-256, and install it
+// atomically under <pkg>/larkin-bin/<platform>-<arch>/. The npm tarball itself
+// never ships the binary; this runs only for registry/git installs (never in the
+// source repo, which ships src/ and scripts/build.mjs).
+//
+// Failures are non-fatal on purpose: `bin` (scripts/npm/larkin-bin-shim.mjs)
+// falls back to the Bun-compiled JS entry when the binary is unavailable.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(HERE, "..", "..");
+
+function warn(message) {
+  process.stderr.write(`[larkin install] ${message}\n`);
+}
+
+function inSourceRepo() {
+  return fs.existsSync(path.join(PKG_ROOT, "src")) && fs.existsSync(path.join(PKG_ROOT, "scripts", "build.mjs"));
+}
+
+async function fetchWithTimeout(url, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { redirect: "follow", signal: controller.signal });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    return Buffer.from(await response.arrayBuffer());
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function expectedSha256(checksumsText, filename) {
+  for (const line of String(checksumsText).split(/\r?\n/)) {
+    const [sha, name] = line.trim().split(/\s+/);
+    if (name === filename && /^[a-f0-9]{64}$/.test(sha)) return sha;
+  }
+  return null;
+}
+
+async function main() {
+  if (process.env.LARKIN_NPM_BINARY_DISABLE === "1") return;
+  if (inSourceRepo()) return;
+
+  // 延迟导入编译产物：源码仓库/CI 中 `dist/` 可能尚未构建，静态 import 会在
+  // 守卫之前失败（bun install 会运行根包 postinstall）。
+  const { RELEASE_TARGETS, artifactFilename, normalizeReleasePlatform, sha256File } = await import(
+    "../../dist/platform/release-artifacts.mjs"
+  );
+
+  const platform = normalizeReleasePlatform(os.platform());
+  const arch = os.arch();
+  const target = RELEASE_TARGETS.find((candidate) => candidate.platform === platform && candidate.arch === arch);
+  if (!target) return; // no standalone binary for this platform → JS fallback
+
+  let version;
+  try {
+    version = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, "package.json"), "utf8")).version;
+  } catch (error) {
+    warn(`无法读取包版本：${error instanceof Error ? error.message : String(error)}`);
+    return;
+  }
+
+  let filename;
+  try {
+    filename = artifactFilename(version, target.platform, target.arch);
+  } catch (error) {
+    warn(`跳过下载：${error instanceof Error ? error.message : String(error)}`);
+    return;
+  }
+
+  const baseUrl = String(process.env.LARKIN_RELEASE_BASE_URL || `https://github.com/eddiearc/larkin/releases/download/v${version}`).replace(/\/+$/, "");
+  const destinationDir = path.join(PKG_ROOT, "larkin-bin", `${target.platform}-${target.arch}`);
+  const destination = path.join(destinationDir, target.platform === "windows" ? "larkin.exe" : "larkin");
+
+  let expected;
+  try {
+    const checksums = await fetchWithTimeout(`${baseUrl}/SHA256SUMS`, 30_000);
+    expected = expectedSha256(checksums.toString("utf8"), filename);
+  } catch (error) {
+    if (fs.existsSync(destination)) {
+      warn(`SHA256SUMS 下载失败，保留已安装二进制：${error instanceof Error ? error.message : String(error)}`);
+      return;
+    }
+    warn(`SHA256SUMS 下载失败，将回退到 Bun JS 入口：${error instanceof Error ? error.message : String(error)}`);
+    return;
+  }
+  if (!expected) {
+    warn(`SHA256SUMS 中缺少 ${filename} 的校验和，将回退到 Bun JS 入口`);
+    return;
+  }
+
+  if (fs.existsSync(destination) && sha256File(destination) === expected) return; // already current
+
+  let bytes;
+  try {
+    bytes = await fetchWithTimeout(`${baseUrl}/${filename}`, 5 * 60_000);
+  } catch (error) {
+    warn(`二进制下载失败，将回退到 Bun JS 入口：${error instanceof Error ? error.message : String(error)}`);
+    return;
+  }
+
+  fs.mkdirSync(destinationDir, { recursive: true });
+  const temporary = path.join(destinationDir, `.larkin.${process.pid}.${Date.now()}.tmp`);
+  try {
+    fs.writeFileSync(temporary, bytes);
+    if (sha256File(temporary) !== expected) throw new Error("checksum mismatch");
+    fs.chmodSync(temporary, 0o755);
+    fs.renameSync(temporary, destination);
+    process.stderr.write(`[larkin install] installed ${filename}\n`);
+  } catch (error) {
+    try { fs.unlinkSync(temporary); } catch { /* best effort */ }
+    warn(`安装二进制失败，将回退到 Bun JS 入口：${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+main().catch((error) => {
+  warn(`安装二进制异常，将回退到 Bun JS 入口：${error instanceof Error ? error.message : String(error)}`);
+});

package/scripts/npm/larkin-bin-shim.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// npm `bin` entry. Prefers the postinstall-downloaded standalone binary; falls
+// back to the Bun-compiled JS entry when the binary is absent (unsupported
+// platform or a failed/interrupted install) and Bun is on PATH.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { RELEASE_TARGETS, normalizeReleasePlatform } from "../../dist/platform/release-artifacts.mjs";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(HERE, "..", "..");
+
+const platform = normalizeReleasePlatform(os.platform());
+const target = RELEASE_TARGETS.find((candidate) => candidate.platform === platform && candidate.arch === os.arch());
+const binary = target
+  ? path.join(PKG_ROOT, "larkin-bin", `${target.platform}-${target.arch}`, target.platform === "windows" ? "larkin.exe" : "larkin")
+  : null;
+const argv = process.argv.slice(2);
+
+function run(command, args) {
+  const result = spawnSync(command, args, { stdio: "inherit" });
+  if (result.error) return null;
+  return result.status ?? 0;
+}
+
+if (binary && fs.existsSync(binary)) {
+  const status = run(binary, argv);
+  if (status !== null) process.exit(status);
+  process.stderr.write(`[larkin] 平台二进制启动失败，尝试 Bun fallback…\n`);
+}
+
+const bunEntry = path.join(PKG_ROOT, "dist", "app", "cli.mjs");
+if (fs.existsSync(bunEntry)) {
+  const bun = process.env.LARKIN_BUN || "bun";
+  const status = run(bun, [bunEntry, ...argv]);
+  if (status !== null) process.exit(status);
+}
+
+process.stderr.write(
+  "[larkin] 未找到可用的平台二进制，也未找到 Bun。\n" +
+  "  - 联网重新安装会自动下载对应平台二进制：npm install -g larkin\n" +
+  "  - 或安装 Bun 1.3.14 后重试（会走 JS 入口 fallback）\n" +
+  "  - 或从 GitHub Release 下载 standalone 二进制：https://github.com/eddiearc/larkin/releases\n",
+);
+process.exit(1);