zhuye 0.1.0 → 0.1.5

package/README.md

@@ -8,7 +8,16 @@
 npm install zhuye
 ```
 
-需要本机有 `zhuye` 二进制在 PATH(或通过 `ZHUYE_BIN` 指向)。从 [GitHub Releases](https://github.com/Asketisch/ZhuYe/releases) 下载,或从本仓库 `make build` 产出 `target/release/zhuye`。
+安装即用:主包通过 optional dependencies 自动安装当前平台的平台子包
+(`zhuye-darwin-arm64` / `zhuye-darwin-x64` / `zhuye-linux-x64` /
+`zhuye-linux-arm64` / `zhuye-win32-x64`),内嵌对应平台的 `zhuye`
+二进制,SDK 优先解析它 —— 无需自装二进制、无需配环境变量。
+
+二进制解析优先级:显式 `options.bin` → `ZHUYE_BIN` → 平台子包内嵌
+二进制 → PATH 上的 `zhuye`。当前平台不在支持矩阵(如 musl/Alpine)
+时回退 PATH:从 [GitHub Releases](https://github.com/Asketisch/ZhuYe/releases)
+下载,或从本仓库 `make build` 产出 `target/release/zhuye` 后以
+`ZHUYE_BIN` 指向。
 
 ## 用法
 
@@ -62,7 +71,7 @@ const handshake = await agent.nextGlobalEvent({ timeoutMs: 5000 });
 
 | 变量 | 作用 |
 |------|------|
-| `ZHUYE_BIN` | `zhuye` 二进制路径(默认搜索 PATH)。 |
+| `ZHUYE_BIN` | `zhuye` 二进制路径(最高优先级覆盖;缺省用平台子包内嵌二进制)。 |
 | `ZHUYE_MODEL` | 模型名(spec,例如 `mock/mock-1` 用于离线 SDK 测试)。 |
 | `ZHUYE_REMOTE_TOOL_TIMEOUT_SECS` | 远程工具等待客户端回执的上限,默认 120s。 |
 

package/dist/agent.d.ts

@@ -5,7 +5,11 @@ import { Event, Op, ReviewDecision, ToolOutput } from './protocol.js';
 export type ToolHandler = (args: Record<string, unknown>) => Promise<ToolOutput> | ToolOutput;
 /** ZhuyeAgent 启动选项。 */
 export interface ZhuyeAgentOptions {
-    /** `zhuye` 二进制路径。默认读 env `ZHUYE_BIN` → PATH 上的 `zhuye`。 */
+    /**
+     * `zhuye` 二进制路径。缺省按优先级解析:env `ZHUYE_BIN` → 随包安装
+     * 的平台子包内嵌二进制(`zhuye-<平台>` optional dependency)→
+     * PATH 上的 `zhuye`。
+     */
     bin?: string;
     /** 工作目录(传给 serve 的 env)。 */
     cwd?: string;

package/dist/agent.js

@@ -13,6 +13,7 @@
 //! ```
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
+import { resolveBundledBinary } from './binary.js';
 const ZHUYE_BIN_ENV = 'ZHUYE_BIN';
 const DEFAULT_BIN = 'zhuye';
 const READLINE_LIMIT = 16 * 1024 * 1024;
@@ -46,7 +47,12 @@ export class ZhuyeAgent {
         // config 目录都定位不到),options.env 只做增量覆盖。
         const env = { ...process.env, ...options.env };
         const spawnOpts = {
-            bin: options.bin ?? process.env[ZHUYE_BIN_ENV] ?? DEFAULT_BIN,
+            // 解析优先级:显式指定 → 环境变量 → 随平台子包内嵌的二进制 →
+            // PATH 上的 `zhuye`。内嵌优先于 PATH:它与 SDK 版本严格配套。
+            bin: options.bin ??
+                process.env[ZHUYE_BIN_ENV] ??
+                resolveBundledBinary() ??
+                DEFAULT_BIN,
             args: ['serve'],
             cwd: options.cwd,
             env,

package/dist/binary.d.ts

@@ -0,0 +1,16 @@
+/** 当前平台对应的 npm 平台子包名;不在支持矩阵时返回 null。 */
+export declare function platformPackageName(platform?: string, arch?: string): string | null;
+/** 由平台子包目录推导二进制路径(纯函数拆分,便于单测)。 */
+export declare function binaryPathFromPackageDir(pkgDir: string): string;
+/**
+ * 解析随包安装的内嵌 `zhuye` 二进制的绝对路径。
+ *
+ * 平台子包未落地(不支持的平台,或 optionalDependencies 安装失败 ——
+ * npm 对 optional 依赖失败静默容忍)时返回 null,由 spawn 链回退到
+ * PATH 上的 `zhuye`。
+ *
+ * 用 createRequire 而非 import.meta.resolve:后者在旧 Node 需要
+ * experimental 标志;createRequire 自 Node 12.2 稳定,且天然解析
+ * node_modules 的真实落盘路径。
+ */
+export declare function resolveBundledBinary(): string | null;

package/dist/binary.js

@@ -0,0 +1,49 @@
+//! 内嵌二进制解析:定位随平台子包(optionalDependencies)安装的
+//! `zhuye` 可执行文件,让 `npm install zhuye` 后开箱即用。
+//!
+//! 解析优先级见 `agent.ts` 的 spawn 链:options.bin → ZHUYE_BIN →
+//! 本模块 → PATH 上的 `zhuye`。
+import { accessSync, constants } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+/** process.platform → process.arch → npm 平台子包名(与发布矩阵一一对应)。 */
+const PLATFORM_PACKAGES = {
+    darwin: { arm64: 'zhuye-darwin-arm64', x64: 'zhuye-darwin-x64' },
+    linux: { arm64: 'zhuye-linux-arm64', x64: 'zhuye-linux-x64' },
+    win32: { x64: 'zhuye-win32-x64' },
+};
+const EXE_SUFFIX = process.platform === 'win32' ? '.exe' : '';
+/** 当前平台对应的 npm 平台子包名;不在支持矩阵时返回 null。 */
+export function platformPackageName(platform = process.platform, arch = process.arch) {
+    return PLATFORM_PACKAGES[platform]?.[arch] ?? null;
+}
+/** 由平台子包目录推导二进制路径(纯函数拆分,便于单测)。 */
+export function binaryPathFromPackageDir(pkgDir) {
+    return join(pkgDir, 'bin', `zhuye${EXE_SUFFIX}`);
+}
+/**
+ * 解析随包安装的内嵌 `zhuye` 二进制的绝对路径。
+ *
+ * 平台子包未落地(不支持的平台,或 optionalDependencies 安装失败 ——
+ * npm 对 optional 依赖失败静默容忍)时返回 null,由 spawn 链回退到
+ * PATH 上的 `zhuye`。
+ *
+ * 用 createRequire 而非 import.meta.resolve:后者在旧 Node 需要
+ * experimental 标志;createRequire 自 Node 12.2 稳定,且天然解析
+ * node_modules 的真实落盘路径。
+ */
+export function resolveBundledBinary() {
+    const pkg = platformPackageName();
+    if (pkg === null)
+        return null;
+    try {
+        const require = createRequire(import.meta.url);
+        const manifest = require.resolve(`${pkg}/package.json`);
+        const bin = binaryPathFromPackageDir(join(manifest, '..'));
+        accessSync(bin, constants.X_OK);
+        return bin;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from './protocol.js';
 export { ZhuyeAgent, ToolHandler, ZhuyeAgentOptions, } from './agent.js';
+export { platformPackageName, resolveBundledBinary, } from './binary.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 //! `zhuye` —— TS SDK 公共入口。
 export * from './protocol.js';
 export { ZhuyeAgent, } from './agent.js';
+export { platformPackageName, resolveBundledBinary, } from './binary.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zhuye",
-  "version": "0.1.0",
+  "version": "0.1.5",
   "description": "ZhuYe Agent SDK for TypeScript: spawn `zhuye serve` and drive it over JSONL stdio.",
   "author": "ZhuYe Agent Contributors",
   "homepage": "https://github.com/Asketisch/ZhuYe#readme",
@@ -35,5 +35,12 @@
     "@types/node": "^20.11.0",
     "typescript": "^5.4.0",
     "vitest": "^1.6.0"
+  },
+  "optionalDependencies": {
+    "zhuye-darwin-arm64": "0.1.5",
+    "zhuye-darwin-x64": "0.1.5",
+    "zhuye-linux-x64": "0.1.5",
+    "zhuye-linux-arm64": "0.1.5",
+    "zhuye-win32-x64": "0.1.5"
   }
-}
+}