nx-ce 0.1.0

package/README.md

@@ -0,0 +1,180 @@
+# nx-ce — Claude Engine
+
+**nx-ce** 是一个轻量级 Node.js 适配器，封装了 `@anthropic-ai/claude-agent-sdk`。
+通过长度前缀的 JSON 协议（与 Chrome Native Messaging 格式一致）在 stdin/stdout 上暴露 SDK 接口，
+支持一次性冷启动查询与持久化服务两种运行模式。
+
+**nx-ce** is a lightweight Node.js adapter for `@anthropic-ai/claude-agent-sdk`.
+It exposes the SDK over stdin/stdout via a length-prefixed JSON protocol (identical to Chrome native messaging),
+supporting both one-shot cold-start queries and persistent serve sessions.
+
+---
+
+## 项目家族 / Family
+
+| Package | 角色 / Role |
+|---------|-------------|
+| **nx-ce** | Claude Engine — SDK 适配层 / SDK adapter layer |
+| [nx-sx](https://github.com/jokelx/nx-sx) | Sandbox eXecution — 窗口/终端管理器 / window & terminal manager |
+
+---
+
+## 安装 / Install
+
+```bash
+npm install nx-ce
+# 或全局安装 / or install globally
+npm install -g nx-ce
+```
+
+---
+
+## 命令行用法 / CLI Usage
+
+### `nx-ce query <prompt>` — 一次性冷启动查询 / One-shot cold-start query
+
+```bash
+nx-ce query "解释这段代码" --model claude-sonnet-4-6
+nx-ce query "Explain this code" --model claude-haiku-4-5 --no-persist
+nx-ce query "继续之前的对话" --resume sess_abc123
+nx-ce query "Analyze" --skill git-workflow,code-review
+nx-ce query "Analyze" --skill all
+```
+
+| 选项 / Flag | 说明 / Description |
+|-------------|-------------------|
+| `--model <id>` | 模型 ID 覆盖（默认 `claude-sonnet-4-6`）/ Model override |
+| `--claude-path <path>` | Claude CLI 可执行文件路径 / Path to Claude CLI binary |
+| `--system-prompt <text>` | 系统提示词覆盖 / System prompt override |
+| `--resume <sessionId>` | 续接之前的会话（长对话）/ Resume a prior session |
+| `--skill <name>[,<name>...]` | 加载指定 Skill（逗号分隔，传 `all` 加载全部）/ Load specific skills |
+| `--no-persist` | 不持久化会话 / Don't persist session |
+| `--env "KEY=value,KEY2=val"` | 额外环境变量 / Extra environment variables |
+
+### `nx-ce serve` — 持久化管理器进程 / Persistent manager process
+
+```bash
+nx-ce serve --name chat-tab-1
+nx-ce serve --name default --model claude-sonnet-4-6
+```
+
+通过 stdin/stdout 接收 4B+JSON 协议消息，保持一个持久化的 SDK 会话。
+Reads/writes 4B+JSON protocol messages over stdin/stdout, maintaining a persistent SDK session.
+
+| 选项 / Flag | 说明 / Description |
+|-------------|-------------------|
+| `--name <name>` | 实例名称（默认 `"default"`）/ Instance name |
+| `--model <id>` | 模型 ID 覆盖 / Model override |
+| `--claude-path <path>` | Claude CLI 可执行文件路径 / Path to Claude CLI binary |
+| `--env "KEY=value,..."` | 额外环境变量 / Extra environment variables |
+
+### `nx-ce status` — 查看实例状态 / Show instance state
+
+```bash
+nx-ce status                  # 列出所有实例 / List all instances
+nx-ce status --name chat-tab-1  # 查看指定实例 / Show specific instance
+```
+
+### `nx-ce help` — 显示帮助 / Show help
+
+```bash
+nx-ce help
+```
+
+---
+
+## 协议 / Protocol
+
+所有 IPC 使用与 Chrome Native Messaging 一致的线缆格式：
+
+All IPC uses the same wire format as Chrome native messaging:
+
+```
+[4 bytes LE uint32 = 负载长度 / payload length][UTF-8 JSON payload]
+```
+
+### 查询（一次性）/ Query (one-shot)
+
+```
+→ { "prompt": "...", "model": "...", "systemPrompt": "..." }
+← { "text": "...", "sessionId": "sess_xxx" }
+```
+
+### 服务（持久化）/ Serve (persistent)
+
+```
+→ { "id":"1", "type":"query", "prompt":"..." }
+← { "id":"1", "type":"text", "content":"..." }
+← { "id":"1", "type":"tool_use", "name":"readFile", "input":{...} }
+← { "id":"1", "type":"thinking", "content":"..." }
+← { "id":"1", "type":"done", "sessionId":"..." }
+
+→ { "type":"ping" }
+← { "type":"pong", "sessionId":"..." }
+```
+
+协议消息类型 / Message types:
+
+| 方向 / Dir | type | 说明 / Description |
+|------------|------|-------------------|
+| → | `query` | 用户输入 / User input |
+| ← | `text` | 文本回复 / Text response |
+| ← | `tool_use` | 工具调用请求 / Tool use request |
+| ← | `thinking` | 思考过程 / Model thinking |
+| ← | `done` | 本轮完成，含会话 ID / Turn complete with session ID |
+| ← | `error` | 错误消息 / Error message |
+| → | `ping` | 心跳检测 / Heartbeat |
+| ← | `pong` | 心跳回复 / Heartbeat response |
+
+---
+
+## 架构 / Architecture
+
+```
+Chrome Extension / 浏览器扩展
+       ↕ Native Messaging (4B+JSON)
+Native Host (Go)
+       ↕ 4B+JSON (via executor.startProcess)
+nx-ce serve (Node.js)
+       ↕ @anthropic-ai/claude-agent-sdk
+Claude Code CLI (子进程 / subprocess)
+```
+
+---
+
+## 状态持久化 / State
+
+状态持久化到 `~/.nx-ce/instances/{name}.json`。
+每个命名实例存储其 PID、会话 ID 和启动时间，用于崩溃恢复和会话续接。
+
+Persisted to `~/.nx-ce/instances/{name}.json`. Each named instance stores its PID, session ID, and start time for crash recovery and session resumption.
+
+示例状态文件 / Example state file:
+
+```json
+{
+  "name": "chat-tab-1",
+  "pid": 12345,
+  "startedAt": "2026-06-06T10:30:00.000Z",
+  "sessionId": "sess_abc123",
+  "model": "claude-sonnet-4-6"
+}
+```
+
+---
+
+## 开发 / Development
+
+```bash
+# 本地运行 / Run locally
+node ./bin/nx-ce.js query "你好"
+
+# 检查语法 / Check syntax
+node -c src/*.js
+```
+
+---
+
+## License / 许可证
+
+MIT

package/bin/nx-ce.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+/**
+ * nx-ce — Claude Engine
+ *
+ * CLI entry point. Routes to subcommands:
+ *   nx-ce query "prompt"    — one-shot cold-start query
+ *   nx-ce serve             — persistent manager process (stdin/stdout protocol)
+ *   nx-ce status            — show instance state
+ */
+
+import { runCli } from '../src/cli.js';
+
+runCli()
+  .then((result) => {
+    if (result) {
+      console.log(JSON.stringify(result));
+    }
+  })
+  .catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "nx-ce",
+  "version": "0.1.0",
+  "description": "Claude Engine — SDK adapter layer for native messaging host. Bridges @anthropic-ai/claude-agent-sdk calls over a length-prefixed JSON protocol.",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "nx-ce": "bin/nx-ce.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "nx-ce": "node ./bin/nx-ce.js",
+    "test": "node test/basic.js",
+    "start": "node ./bin/nx-ce.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "anthropic",
+    "sdk",
+    "native-messaging",
+    "chrome-extension"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.159"
+  }
+}

package/src/cli.js

@@ -0,0 +1,179 @@
+/**
+ * CLI — 子命令路由器
+ *
+ * 模式：nx-sx/src/cli.js
+ * 路由到 query | serve | status | help
+ */
+
+import { existsSync } from 'node:fs';
+import { runQuery } from './query.js';
+import { startServe } from './serve.js';
+import { readState, listStates } from './session-store.js';
+
+/**
+ * 解析命令行参数。
+ * 支持 --key=value 和 --key value 两种格式。
+ *
+ * @param {string[]} argv - 命令行参数数组（默认 process.argv.slice(2)）
+ * @returns {{ cmd: string, flags: object, args: string[] }}
+ */
+export function parseArgs(argv = process.argv.slice(2)) {
+  const cmd = argv[0];          // 第一个参数为子命令
+  const rest = argv.slice(1);
+
+  // 解析 --key=value 或 --key value 选项
+  // positional 只收集非 -- 开头的参数
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg.startsWith('--')) {
+      const eqIdx = arg.indexOf('=');
+      if (eqIdx !== -1) {
+        // --key=value 格式
+        flags[arg.slice(2, eqIdx)] = arg.slice(eqIdx + 1);
+      } else {
+        // --key value 格式（下一个参数作为值）
+        flags[arg.slice(2)] = rest[++i] ?? true;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  return { cmd, flags, args: positional };
+}
+
+/**
+ * 运行 CLI 入口。
+ * 根据子命令分发到对应的处理函数。
+ */
+export async function runCli() {
+  const { cmd, flags, args } = parseArgs();
+
+  switch (cmd) {
+    case 'query': {
+      // 冷启动查询
+      const prompt = args[0] || flags.prompt;
+      if (!prompt) {
+        throw new Error('用法: nx-ce query <prompt> [--model ...] [--claude-path ...]');
+      }
+
+      const result = await runQuery({
+        prompt,
+        model: flags.model,
+        cwd: flags.cwd || process.cwd(),
+        claudePath: resolveClaudePath(flags['claude-path']),
+        systemPrompt: flags['system-prompt'],
+        persistSession: flags['no-persist'] ? false : undefined,
+        resumeSessionId: flags.resume,
+        skills: parseSkills(flags.skill),
+        env: flags.env ? parseEnvString(flags.env) : undefined,
+      });
+
+      return result;
+    }
+
+    case 'serve': {
+      // 持久化服务模式
+      const name = flags.name || 'default';
+
+      const result = await startServe({
+        name,
+        claudePath: resolveClaudePath(flags['claude-path']),
+        model: flags.model,
+        cwd: flags.cwd || process.cwd(),
+        env: flags.env ? parseEnvString(flags.env) : undefined,
+      });
+
+      return result;
+    }
+
+    case 'status': {
+      // 查询实例状态
+      const name = flags.name;
+      if (name) {
+        return readState(name); // 查询指定实例
+      }
+      return listStates();      // 列出所有实例
+    }
+
+    case 'help':
+    default:
+      // 显示帮助信息
+      console.log(`
+	nx-ce — Claude Engine
+
+用法:
+  nx-ce query <prompt>            一次性冷启动查询
+    --model <id>                  模型覆盖
+    --claude-path <path>          Claude CLI 路径
+    --system-prompt <text>        系统提示词覆盖
+    --resume <sessionId>          续接之前的会话（长对话）
+    --skill <name>[,<name>...]    加载指定 Skill（逗号分隔，传 "all" 加载全部）
+    --no-persist                  不持久化会话
+    --env "KEY=value,KEY2=val"    额外环境变量
+
+  nx-ce serve                     持久化管理器进程（stdin/stdout）
+    --name <name>                 实例名称（默认: "default"）
+    --model <id>                  模型覆盖
+    --claude-path <path>          Claude CLI 路径
+    --env "KEY=value,..."         额外环境变量
+
+  nx-ce status [--name <name>]   查看实例状态
+
+  nx-ce help                      显示此帮助
+`);
+      return null;
+  }
+}
+
+/**
+ * 解析 Claude CLI 路径。
+ * 优先使用命令行参数，然后检查环境变量。
+ *
+ * @param {string|undefined} flag - 命令行传入的路径
+ * @returns {string|undefined} 解析后的路径，未找到则返回 undefined（由 SDK 自动检测）
+ */
+function resolveClaudePath(flag) {
+  if (flag) return flag;
+  // 常见位置
+  const candidates = [
+    process.env.CLAUDE_PATH,
+    process.env.CLAUDE_CLI_PATH,
+    // Windows: npx、npm 全局或用户本地安装
+  ];
+  for (const c of candidates) {
+    if (c && existsSync(c)) return c;
+  }
+  // 未找到，让 SDK 自动检测
+  return undefined;
+}
+
+/**
+ * 解析环境变量字符串为对象。
+ * 格式: "KEY=value,KEY2=val2"
+ *
+ * @param {string} str - 逗号分隔的 KEY=value 对
+ * @returns {object}
+ */
+function parseEnvString(str) {
+  const result = {};
+  for (const pair of str.split(',')) {
+    const eqIdx = pair.indexOf('=');
+    if (eqIdx !== -1) {
+      result[pair.slice(0, eqIdx)] = pair.slice(eqIdx + 1);
+    }
+  }
+  return result;
+}
+
+/**
+ * 解析 --skill 参数。
+ * 逗号分隔的列表 → 数组；"all" → "all"（由 SDK 处理）。
+ */
+function parseSkills(value) {
+  if (value === undefined || value === null || value === '') return undefined;
+  if (value === 'all' || value === 'ALL') return 'all';
+  return value.split(',').map((s) => s.trim()).filter(Boolean);
+}

package/src/index.js

@@ -0,0 +1,11 @@
+/**
+ * nx-ce — 公开 API 入口
+ *
+ * 用法:
+ *   import { runQuery } from 'nx-ce';
+ *   const { text, sessionId } = await runQuery({ prompt: 'hello', ... });
+ */
+
+export { runQuery } from './query.js';
+export { readState, writeState, deleteState, listStates } from './session-store.js';
+export { readMessage, writeMessage } from './protocol.js';

package/src/protocol.js

@@ -0,0 +1,115 @@
+/**
+ * 协议 — 长度前缀的 JSON 消息通信
+ *
+ * 线缆格式（与 native_host/internal/protocol/protocol.go 一致）：
+ *   [4 字节 LE uint32 = 载荷长度][UTF-8 JSON 载荷]
+ *
+ * 这是 nx-ce 与原生主机之间的唯一通信契约。
+ */
+
+import { Buffer } from 'node:buffer';
+
+/** 单条消息最大字节数（10 MB，与 Go 端对齐） */
+const MAX_MESSAGE_SIZE = 10 * 1024 * 1024;
+
+/**
+ * 从可读流中精确读取 n 个字节。
+ *
+ * @param {import('stream').Readable} stream - 可读流
+ * @param {number} n - 需要读取的字节数
+ * @returns {Promise<Buffer|null>} 成功返回 Buffer，正常 EOF 返回 null，出错则 reject
+ */
+function readExactly(stream, n) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let remaining = n;
+
+    /** 尝试从流中同步读取数据 */
+    function tryRead() {
+      while (remaining > 0) {
+        const chunk = stream.read(remaining);
+        if (chunk === null) {
+          // 暂无数据 — 等待 readable 或 end 事件
+          waitForData();
+          return;
+        }
+        chunks.push(chunk);
+        remaining -= chunk.length;
+      }
+      // 已读取全部所需字节
+      cleanup();
+      resolve(Buffer.concat(chunks));
+    }
+
+    /** 注册异步等待回调 */
+    function waitForData() {
+      // 流已结束 → 信号 EOF
+      if (stream.readableEnded || stream.destroyed) {
+        cleanup();
+        resolve(null);
+        return;
+      }
+      stream.once('readable', tryRead);
+      stream.once('end', onEnd);
+      stream.once('error', onError);
+    }
+
+    function onEnd() {
+      cleanup();
+      resolve(null);
+    }
+
+    function onError(err) {
+      cleanup();
+      reject(err);
+    }
+
+    /** 清理注册的事件监听器 */
+    function cleanup() {
+      stream.removeListener('readable', tryRead);
+      stream.removeListener('end', onEnd);
+      stream.removeListener('error', onError);
+    }
+
+    tryRead();
+  });
+}
+
+/**
+ * 从可读流中读取一条消息。
+ *
+ * @param {import('stream').Readable} stream - 可读流
+ * @returns {Promise<object|null>} 解析后的 JSON 对象，正常 EOF 返回 null
+ */
+export async function readMessage(stream) {
+  const headerBuf = await readExactly(stream, 4);
+  if (headerBuf === null) return null; // 正常 EOF
+
+  const length = headerBuf.readUInt32LE(0); // 小端序解析载荷长度
+
+  if (length > MAX_MESSAGE_SIZE) {
+    throw new Error(`message too large: ${length}`);
+  }
+
+  const payloadBuf = await readExactly(stream, length);
+  if (payloadBuf === null) {
+    throw new Error('unexpected EOF during message payload');
+  }
+
+  return JSON.parse(payloadBuf.toString('utf8'));
+}
+
+/**
+ * 向可写流中写入一条消息。
+ *
+ * @param {import('stream').Writable} stream - 可写流
+ * @param {object} data - 要发送的数据对象（会被 JSON 序列化）
+ */
+export function writeMessage(stream, data) {
+  const payload = Buffer.from(JSON.stringify(data), 'utf8');
+  const header = Buffer.alloc(4);
+  header.writeUInt32LE(payload.length, 0); // 小端序写入载荷长度
+
+  stream.write(header);
+  stream.write(payload);
+}

package/src/query.js

@@ -0,0 +1,120 @@
+/**
+ * 冷启动查询 — 对 @anthropic-ai/claude-agent-sdk 的一次性调用
+ *
+ * 参考 claudian 的 claudeColdStartQuery.ts（简单的非持久化路径）。
+ * 不含 MessageChannel、流式消费循环或 Electron 兼容代码。
+ */
+
+import { query as agentQuery } from '@anthropic-ai/claude-agent-sdk';
+
+/**
+ * 执行一次冷启动查询并返回完整的文本结果。
+ *
+ * @param {object} options
+ * @param {string} options.prompt          - 用户提示词
+ * @param {string} [options.systemPrompt]  - 系统提示词覆盖
+ * @param {string} [options.model]         - 模型 ID 覆盖
+ * @param {string} options.cwd             - 工作目录
+ * @param {string} options.claudePath      - Claude CLI 可执行文件路径
+ * @param {object} [options.env]           - 额外的环境变量
+ * @param {string[]} [options.tools]       - 工具白名单（省略则使用 SDK 默认值）
+ * @param {boolean} [options.persistSession] - 是否持久化会话（默认 true）
+ * @param {string} [options.resumeSessionId] - 恢复之前的会话
+ * @param {string[]|'all'} [options.skills] - 加载哪些 Skill（数组或 'all'）
+ * @param {AbortController} [options.signal] - 中止信号
+ * @returns {Promise<{ text: string, sessionId: string | null }>}
+ */
+export async function runQuery(options) {
+  const {
+    prompt,
+    systemPrompt,
+    model,
+    cwd,
+    claudePath,
+    env = {},
+    tools,
+    persistSession,
+    resumeSessionId,
+    skills,
+    signal,
+  } = options;
+
+  // 组装 SDK 选项
+  const sdkOptions = {
+    cwd: cwd || process.cwd(),
+    model: model || 'claude-sonnet-4-6',
+    pathToClaudeCodeExecutable: claudePath,
+    permissionMode: 'bypassPermissions', // 跳过权限确认
+    allowDangerouslySkipPermissions: true,
+    env: {
+      ...process.env,
+      ...env, // 合并额外环境变量
+    },
+  };
+
+  // 以下为可选参数的条件注入
+  if (systemPrompt) {
+    sdkOptions.systemPrompt = systemPrompt;
+  }
+
+  if (tools !== undefined) {
+    sdkOptions.tools = tools;
+  }
+
+  if (persistSession === false) {
+    sdkOptions.persistSession = false;
+  }
+
+  if (resumeSessionId) {
+    sdkOptions.resume = resumeSessionId;
+  }
+
+  if (skills !== undefined) {
+    sdkOptions.skills = skills;
+  }
+
+  if (signal) {
+    sdkOptions.abortController = signal;
+  }
+
+  // 确保总有一个 abort controller
+  const abortController = signal || new AbortController();
+  sdkOptions.abortController = abortController;
+
+  // 发起 SDK 查询（返回异步迭代器）
+  const response = agentQuery({ prompt, options: sdkOptions });
+
+  let text = '';
+  let sessionId = null;
+
+  // 遍历 SDK 返回的流式消息
+  for await (const message of response) {
+    // 如果已中止，中断查询
+    if (abortController.signal.aborted) {
+      await response.interrupt();
+      break;
+    }
+
+    // 从初始化消息中捕获会话 ID
+    if (message.type === 'system' && message.subtype === 'init' && message.session_id) {
+      sessionId = message.session_id;
+    }
+
+    // 提取助手的文本回复内容
+    if (message.type === 'assistant' && message.message?.content) {
+      const content = message.message.content;
+      if (typeof content === 'string') {
+        text += content;
+      } else if (Array.isArray(content)) {
+        // 内容块数组，筛选出 text 块
+        for (const block of content) {
+          if (block.type === 'text') {
+            text += block.text;
+          }
+        }
+      }
+    }
+  }
+
+  return { text, sessionId };
+}

package/src/serve.js

@@ -0,0 +1,216 @@
+/**
+ * 服务端 — 持久化管理器进程
+ *
+ * 通过 stdin/stdout 运行，使用 4B+JSON 格式协议。
+ * 每个实例维护一个持久化的 agentQuery() 会话。
+ *
+ * 协议消息（与 native_host/protocol.go 线缆格式一致）：
+ *   → { "id":"...", "type":"query", "prompt":"..." }
+ *   ← { "id":"...", "type":"text", "content":"..." }
+ *   ← { "id":"...", "type":"done", "sessionId":"..." }
+ *   ← { "id":"...", "type":"error", "content":"..." }
+ *   → { "type":"ping" }
+ *   ← { "type":"pong", "sessionId":"..." }
+ */
+
+import { query as agentQuery } from '@anthropic-ai/claude-agent-sdk';
+import { readMessage, writeMessage } from './protocol.js';
+import { readState, writeState, deleteState } from './session-store.js';
+
+/**
+ * 启动一个持久化服务会话。
+ * 从 stdin 读取，向 stdout 写入，持续运行直到 stdin 关闭。
+ */
+export async function startServe(options) {
+  const { name, claudePath, model, cwd, env } = options;
+
+  // 检查是否有可恢复的会话状态
+  const existingState = readState(name);
+
+  // 组装 SDK 选项
+  const sdkOptions = {
+    cwd: cwd || process.cwd(),
+    model: model || 'claude-sonnet-4-6',
+    pathToClaudeCodeExecutable: claudePath,
+    permissionMode: 'bypassPermissions', // 跳过权限确认
+    allowDangerouslySkipPermissions: true,
+    env: { ...process.env, ...env },
+  };
+
+  // 如果存在之前的会话 ID，恢复会话
+  if (existingState?.sessionId) {
+    sdkOptions.resume = existingState.sessionId;
+  }
+
+  // 简单的异步消息队列（供 SDK 侧消费方拉取）
+  const pendingMessages = [];  // 待发送消息缓冲区
+  let resolveNext = null;     // 下一轮迭代的 resolve 函数
+  let turnActive = false;     // 当前轮次是否活跃
+  let channelClosed = false;  // 通道是否已关闭
+
+  // 消息通道：作为异步迭代器供 SDK 消费
+  const messageChannel = {
+    [Symbol.asyncIterator]() {
+      return {
+        next: () => {
+          // 有缓冲消息且当前轮次空闲 → 立即返回
+          while (pendingMessages.length > 0 && !turnActive) {
+            turnActive = true;
+            return Promise.resolve({
+              value: pendingMessages.shift(),
+              done: false,
+            });
+          }
+          // 通道已关闭 → 结束迭代
+          if (channelClosed) return Promise.resolve({ done: true, value: null });
+          // 否则等待消息入队或轮次完成
+          return new Promise((resolve) => {
+            resolveNext = resolve;
+          });
+        },
+      };
+    },
+  };
+
+  /**
+   * 将 SDK 用户消息入队。
+   * 优先直接交付给等待中的迭代器，否则放入缓冲区（最多 8 条）。
+   */
+  function enqueueMessage(sdkUserMessage) {
+    if (resolveNext) {
+      turnActive = true;
+      const r = resolveNext;
+      resolveNext = null;
+      r({ value: sdkUserMessage, done: false });
+    } else if (pendingMessages.length < 8) {
+      pendingMessages.push(sdkUserMessage);
+    }
+  }
+
+  /** 当前轮次完成：重置状态并触发下一轮读取 */
+  function onTurnComplete() {
+    turnActive = false;
+    const r = resolveNext;
+    resolveNext = null;
+    if (r) r({ done: true, value: null });
+  }
+
+  // 启动持久化查询
+  const response = agentQuery({
+    prompt: messageChannel,
+    options: sdkOptions,
+  });
+
+  let currentSessionId = existingState?.sessionId || null;
+
+  // 持久化初始状态
+  writeState(name, {
+    name,
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+    sessionId: currentSessionId,
+    model: sdkOptions.model,
+  });
+
+  // 后台任务：消费 SDK 输出并写入 stdout
+  const consumerPromise = (async () => {
+    try {
+      for await (const message of response) {
+        // 捕获初始化消息中的会话 ID，更新持久化状态
+        if (message.type === 'system' && message.subtype === 'init' && message.session_id) {
+          currentSessionId = message.session_id;
+          writeState(name, {
+            name,
+            pid: process.pid,
+            startedAt: new Date().toISOString(),
+            sessionId: currentSessionId,
+            model: sdkOptions.model,
+          });
+        }
+
+        // 助手消息 → 区分为 text / tool_use / thinking 块写入 stdout
+        if (message.type === 'assistant' && message.message?.content) {
+          const content = message.message.content;
+          if (typeof content === 'string') {
+            writeMessage(process.stdout, { type: 'text', content });
+          } else if (Array.isArray(content)) {
+            for (const block of content) {
+              if (block.type === 'text') {
+                writeMessage(process.stdout, { type: 'text', content: block.text });
+              } else if (block.type === 'tool_use') {
+                writeMessage(process.stdout, {
+                  type: 'tool_use',
+                  name: block.name,
+                  input: block.input,
+                  id: block.id,
+                });
+              } else if (block.type === 'thinking') {
+                writeMessage(process.stdout, { type: 'thinking', content: block.thinking });
+              }
+            }
+          }
+        }
+
+        // result 消息表示当前轮次完成
+        if (message.type === 'result') {
+          writeMessage(process.stdout, { type: 'done', sessionId: currentSessionId });
+          onTurnComplete();
+        }
+      }
+    } catch (err) {
+      if (err?.code === 'ABORT_ERR') return; // 主动中断，非错误
+      writeMessage(process.stdout, {
+        type: 'error',
+        content: err instanceof Error ? err.message : String(err),
+      });
+    }
+  })();
+
+  // 主循环：从 stdin 读取协议消息，转发给 SDK
+  try {
+    while (true) {
+      let req;
+      try {
+        req = await readMessage(process.stdin);
+      } catch (err) {
+        if (err?.message?.startsWith?.('message too large')) {
+          writeMessage(process.stdout, { type: 'error', content: 'message too large' });
+          continue;
+        }
+        break; // EOF 或解析错误 → 关闭
+      }
+
+      if (!req) break; // 正常 EOF
+
+      // 根据消息类型路由
+      if (req.type === 'query' && req.prompt) {
+        // 构建 SDK 用户消息
+        const sdkMessage = {
+          type: 'user',
+          message: {
+            role: 'user',
+            content: req.prompt,
+          },
+          session_id: currentSessionId || '',
+          uuid: `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`,
+        };
+
+        enqueueMessage(sdkMessage);
+      } else if (req.type === 'ping') {
+        // ping/pong 心跳
+        writeMessage(process.stdout, { type: 'pong', sessionId: currentSessionId });
+      }
+    }
+  } finally {
+    // 清理：关闭通道、中断查询、等待消费完成、删除状态文件
+    channelClosed = true;
+    if (resolveNext) {
+      resolveNext({ done: true, value: null });
+    }
+    try {
+      await response.interrupt();
+    } catch { /* 忽略中断错误 */ }
+    await consumerPromise;
+    deleteState(name);
+  }
+}

package/src/session-store.js

@@ -0,0 +1,88 @@
+/**
+ * 会话存储 — 磁盘上的持久化状态
+ *
+ * 模式：nx-sx 的 writeState/readState。
+ * 目录：$HOME/.nx-ce/instances/{name}.json
+ */
+
+import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** 状态文件存储目录 */
+const STATE_DIR = join(homedir(), '.nx-ce', 'instances');
+
+/** 确保存储目录存在 */
+function ensureDir() {
+  mkdirSync(STATE_DIR, { recursive: true });
+}
+
+/**
+ * 读取指定实例的持久化状态。
+ *
+ * @param {string} name - 实例名称
+ * @returns {object|null} 状态对象，不存在则返回 null
+ */
+export function readState(name) {
+  ensureDir();
+  const path = join(STATE_DIR, sanitize(name));
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 写入指定实例的持久化状态。
+ *
+ * @param {string} name - 实例名称
+ * @param {object} state - 要持久化的状态对象
+ */
+export function writeState(name, state) {
+  ensureDir();
+  const path = join(STATE_DIR, sanitize(name));
+  writeFileSync(path, JSON.stringify(state, null, 2), 'utf8');
+}
+
+/**
+ * 删除指定实例的持久化状态。
+ *
+ * @param {string} name - 实例名称
+ */
+export function deleteState(name) {
+  const path = join(STATE_DIR, sanitize(name));
+  try {
+    rmSync(path, { force: true });
+  } catch {
+    // 文件不存在则静默忽略
+  }
+}
+
+/**
+ * 列出所有已知的实例。
+ *
+ * @returns {Array<{ name: string, state: object }>}
+ */
+export function listStates() {
+  ensureDir();
+  const files = readdirSync(STATE_DIR);
+  return files
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => {
+      const name = f.slice(0, -5); // 去掉 .json 后缀
+      const state = readState(name);
+      return { name, state };
+    });
+}
+
+/**
+ * 将实例名称清理为安全的文件名。
+ * 移除非字母数字的字符，替换为下划线。
+ *
+ * @param {string} name - 原始实例名称
+ * @returns {string} 安全的文件名（带 .json 后缀）
+ */
+function sanitize(name) {
+  return `${String(name).replace(/[^a-zA-Z0-9._-]/g, '_')}.json`;
+}