zhuye 0.1.1 → 0.1.6

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;
@@ -15,6 +19,12 @@ export interface ZhuyeAgentOptions {
     spawnOptions?: Omit<SpawnOptions, 'bin' | 'args' | 'env' | 'cwd'>;
     /** `session_configured` 握手超时(ms)。默认 30s。 */
     handshakeTimeoutMs?: number;
+    /**
+     * 子进程 stderr 接管回调。提供后每个原始块交给回调(落文件 /
+     * 送日志系统 / 过滤降噪),不再硬编码直通宿主 stderr。
+     * 未提供时维持旧行为(透传宿主 stderr)。
+     */
+    onStderr?: (chunk: Buffer) => void;
 }
 interface SpawnOptions {
     bin: string;

package/dist/agent.js

@@ -13,10 +13,20 @@
 //! ```
 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;
 const STDIN_HANDSHAKE_TIMEOUT_MS = 30_000;
+/** 握手失败时随异常携带的 stderr 尾部块数上限。 */
+const STDERR_TAIL_LINES = 32;
+/** 把 stderr 尾部 ring buffer 拼成诊断文本(解码容错)。 */
+function stderrTailText(tail) {
+    return tail
+        .map((c) => c.toString('utf-8').trim())
+        .filter((s) => s.length > 0)
+        .join(' | ');
+}
 /**
  * 主类:启动并维护一个常驻 `zhuye serve` 子进程,把 JSONL 协议包装
  * 成 Promise / AsyncIterable 给 TS 用户。
@@ -46,7 +56,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,
@@ -56,9 +71,20 @@ export class ZhuyeAgent {
             env: spawnOpts.env,
             stdio: ['pipe', 'pipe', 'pipe'],
         });
-        // 子进程 stderr → 当前进程 stderr(让 tracing 日志透传)。
+        // 子进程 stderr → 提供 onStderr 回调时交给回调;否则透传
+        // 当前进程 stderr。无论哪种模式,尾部都保留在 ring buffer 里,
+        // 握手期子进程死亡时把真实原因带进异常。
+        const stderrTail = [];
         child.stderr.on('data', (chunk) => {
-            process.stderr.write(chunk);
+            stderrTail.push(chunk);
+            if (stderrTail.length > STDERR_TAIL_LINES)
+                stderrTail.shift();
+            if (options.onStderr) {
+                options.onStderr(chunk);
+            }
+            else {
+                process.stderr.write(chunk);
+            }
         });
         const proc = {
             child,
@@ -72,29 +98,83 @@ export class ZhuyeAgent {
             readyResolve = res;
             readyReject = rej;
         });
+        // 握手期死亡时 ready 被拒绝;若调用方从未 await 它(spawn 后
+        // 直接 close / 只用全局事件),挂一个 no-op 兜底标记已处理,
+        // 避免 unhandled rejection 打爆宿主。后续 await 仍能拿到该错误。
+        ready.catch(() => { });
         const agent = new ZhuyeAgent(proc, ready);
+        // 握手是否仍在进行 —— 子进程在握手期退出时,ready 立刻拒绝
+        // (带 stderr 尾部),不再傻等满握手超时后报泛化的 timed out。
+        let handshakeSettled = false;
         // 子进程意外退出 → 通知所有 close 监听者(submit / prompt 等
         // 仍 await 中的 promise 借此抛错 / 收尾)。
         child.on('exit', (code, signal) => {
-            agent.handleServeExit(new Error(`zhuye serve exited unexpectedly (code=${code} signal=${signal ?? 'none'})`));
+            // 阶段标记必须在 exit 时刻捕获:等待 stderr 排空期间握手状态
+            // 可能被翻转,措辞判定要以死亡时的阶段为准。
+            const wasHandshake = !handshakeSettled;
+            // 握手期死亡与运行期死亡措辞区分,方便排障定位。
+            const buildErr = () => {
+                const tail = stderrTail.length
+                    ? ` stderr tail: ${stderrTailText(stderrTail)}`
+                    : '';
+                return wasHandshake
+                    ? new Error(`zhuye serve exited during handshake (code=${code} signal=${signal ?? 'none'})${tail}`)
+                    : new Error(`zhuye serve exited unexpectedly (code=${code} signal=${signal ?? 'none'})${tail}`);
+            };
+            if (!wasHandshake) {
+                agent.handleServeExit(buildErr());
+                return;
+            }
+            // 竞态:子进程写 stderr 后立刻退出时,`exit` 事件可能先于
+            // stderr 的 `data` 事件投递(管道排空晚于进程退出),此刻同步读
+            // stderrTail 会拿到空尾、丢失真实原因。握手失败不在毫秒级关键
+            // 路径上 —— 等 `close`(stdio 全部关闭,stderr 必已投递)或至多
+            // 500ms 兜底,再构建错误。
+            let drainSettled = false;
+            const finish = () => {
+                if (drainSettled)
+                    return;
+                drainSettled = true;
+                // 等待期间 stdout 缓冲可能投递了 session_configured:握手实际
+                // 成功则让路,不再以失败拒绝。
+                if (handshakeSettled)
+                    return;
+                handshakeSettled = true;
+                const err = buildErr();
+                readyReject(err);
+                agent.handleServeExit(err);
+            };
+            child.once('close', finish);
+            const drainTimer = setTimeout(finish, 500);
+            drainTimer.unref?.();
         });
         // spawn 失败(典型:二进制路径不存在,ENOENT):ChildProcess 的
         // error 事件没有监听者会以 uncaught exception 打爆宿主进程;这里
         // 转为握手失败(ready 尚未 settle 时立即拒绝,否则等握手超时)。
         child.on('error', (err) => {
             const failure = new Error(`zhuye serve failed to start: ${err.message}`);
-            readyReject(failure);
+            if (!handshakeSettled) {
+                handshakeSettled = true;
+                readyReject(failure);
+            }
             agent.handleServeExit(failure);
         });
         const handshakeMs = options.handshakeTimeoutMs ?? STDIN_HANDSHAKE_TIMEOUT_MS;
         const timer = setTimeout(() => {
-            readyReject(new Error(`zhuye serve handshake timed out after ${handshakeMs}ms`));
+            if (handshakeSettled)
+                return;
+            handshakeSettled = true;
+            readyReject(new Error(`zhuye serve handshake timed out after ${handshakeMs}ms` +
+                (stderrTail.length
+                    ? ` stderr tail: ${stderrTailText(stderrTail)}`
+                    : '')));
         }, handshakeMs);
         timer.unref?.();
         // 在握手阶段消费 stdout,直到见到 session_configured 后再切给
         // 业务消费者 —— 简单做法:让后台 consumer 自己处理,ready 在
         // session_configured 时 resolve。
         agent.onceSessionConfigured = () => {
+            handshakeSettled = true;
             clearTimeout(timer);
             readyResolve();
         };
@@ -114,6 +194,9 @@ export class ZhuyeAgent {
             readyResolve = res;
             readyReject = rej;
         });
+        // 与 spawn 同款兜底:握手超时拒绝而调用方从未 await 时,
+        // 不让 unhandled rejection 打爆宿主;后续 await 仍能拿到该错误。
+        ready.catch(() => { });
         const agent = new ZhuyeAgent(proc, ready);
         const timer = setTimeout(() => {
             readyReject(new Error(`fromStdio handshake timed out after ${handshakeTimeoutMs}ms`));
@@ -156,8 +239,14 @@ export class ZhuyeAgent {
             const msg = ev.msg;
             if (msg.type === 'agent_message_delta')
                 result += msg.delta;
-            else if (msg.type === 'agent_message')
-                result += msg.text;
+            else if (msg.type === 'agent_message') {
+                // 全量消息是权威快照 —— 覆盖(而非追加)已累计的 delta,
+                // 协议允许同轮混合下发时不会产生重复文本。text 经 typeof 守卫:
+                // EventMsg 联合含开放成员(UnknownEventMsg),窄化后仍是 unknown。
+                const { text } = msg;
+                if (typeof text === 'string')
+                    result = text;
+            }
             else if (msg.type === 'turn_complete')
                 break;
             else if (msg.type === 'turn_aborted') {

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.1",
+  "version": "0.1.6",
   "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.6",
+    "zhuye-darwin-x64": "0.1.6",
+    "zhuye-linux-x64": "0.1.6",
+    "zhuye-linux-arm64": "0.1.6",
+    "zhuye-win32-x64": "0.1.6"
   }
-}
+}