nx-ce 0.1.1 → 0.1.4

package/README.md

@@ -4,12 +4,12 @@
 [![CI](https://github.com/joke-lx/nx-ce/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/joke-lx/nx-ce/actions/workflows/npm-publish.yml)
 
 **nx-ce** 是一个轻量级 Node.js 适配器，封装了 `@anthropic-ai/claude-agent-sdk`。
-通过长度前缀的 JSON 协议（与 Chrome Native Messaging 格式一致）在 stdin/stdout 上暴露 SDK 接口，
-支持一次性冷启动查询与持久化服务两种运行模式。
+通过长度前缀的 JSON 协议在 stdin/stdout 上暴露 SDK 接口，
+支持一次性冷启动查询与 WebSocket 持久化服务器两种运行模式。
 
 **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.
+It exposes the SDK via a WebSocket server or stdin/stdout protocol,
+supporting both one-shot cold-start queries and persistent server sessions.
 
 ---
 
@@ -55,23 +55,27 @@ nx-ce query "Analyze" --skill all
 | `--no-persist` | 不持久化会话 / Don't persist session |
 | `--env "KEY=value,KEY2=val"` | 额外环境变量 / Extra environment variables |
 
-### `nx-ce serve` — 持久化管理器进程 / Persistent manager process
+### `nx-ce serve` — WebSocket 持久化服务器 / WebSocket server
+
+单例进程，多客户端共享一个 SDK 会话，请求排队处理。
+Single process with multi-client support and FIFO query queue.
 
 ```bash
+nx-ce serve                     # 默认端口 3100
+nx-ce serve --port 3100         # 指定端口
 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 |
+| `--port <port>` | WebSocket 端口（默认 `3100`）/ WebSocket port |
 | `--model <id>` | 模型 ID 覆盖 / Model override |
 | `--claude-path <path>` | Claude CLI 可执行文件路径 / Path to Claude CLI binary |
 | `--env "KEY=value,..."` | 额外环境变量 / Extra environment variables |
 
+> WebSocket 地址: `ws://127.0.0.1:3100`
+
 ### `nx-ce status` — 查看实例状态 / Show instance state
 
 ```bash
@@ -87,60 +91,96 @@ nx-ce help
 
 ---
 
-## 协议 / Protocol
+## WebSocket 协议 / WebSocket Protocol
+
+服务端地址 `ws://127.0.0.1:PORT`（默认 3100）。所有消息均为 JSON 字符串（不含长度前缀）。
+
+Server at `ws://127.0.0.1:PORT` (default 3100). All messages are JSON strings (no length prefix).
 
-所有 IPC 使用与 Chrome Native Messaging 一致的线缆格式：
+### 客户端发送 / Client → Server
 
-All IPC uses the same wire format as Chrome native messaging:
+| type | 字段 / Fields | 说明 / Description |
+|------|---------------|-------------------|
+| `query` | `prompt: string`, `id?: string` | 发起查询 / Submit a query |
+| `ping` | 无 | 心跳检测 / Heartbeat |
+| `getSkills` | 无 | 拉取技能/工具列表 / Fetch skills & tools |
 
+```json
+→ { "type": "query", "prompt": "解释这段代码" }
+→ { "type": "ping" }
+→ { "type": "getSkills" }
 ```
-[4 bytes LE uint32 = 负载长度 / payload length][UTF-8 JSON payload]
+
+### 服务端发送 / Server → Client
+
+**连接建立 / On connect:**
+
+```json
+← { "type": "connected", "sessionId": "sess_xxx", "port": 3100 }
+← { "type": "init", "sessionId": "sess_xxx", "model": "claude-sonnet-4-6",
+    "skills": [...], "tools": [...], "slashCommands": [...], "agents": [...] }
 ```
 
-### 查询（一次性）/ Query (one-shot)
+**查询响应 / Query response (streamed chunks):**
 
+```json
+← { "type": "text",     "content": "这是一段回复..." }
+← { "type": "thinking", "content": "模型思考过程..." }
+← { "type": "tool_use", "name": "readFile", "input": {...}, "id": "toolu_xxx" }
+← { "type": "done",     "sessionId": "sess_xxx" }
 ```
-→ { "prompt": "...", "model": "...", "systemPrompt": "..." }
-← { "text": "...", "sessionId": "sess_xxx" }
 
-# 加 --include-metadata 时返回 metadata
-# With --include-metadata, response includes metadata:
-← { "text": "...", "sessionId": "sess_xxx", "metadata": { "skills": [...], "tools": [...], "slashCommands": [...] } }
+**其他 / Other:**
+
+```json
+← { "type": "pong",  "sessionId": "sess_xxx" }
+← { "type": "skills", "skills": [...], "tools": [...], "slashCommands": [...], "agents": [...] }
+← { "type": "error", "content": "error message" }
 ```
 
-### 服务（持久化）/ Serve (persistent)
+### 完整示例 / Full exchange
 
 ```
-→ { "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": "query", "prompt": "Hello" }
+← { "type": "text",     "content": "Hello! How can I help you today?" }
+← { "type": "done",     "sessionId": "sess_abc123" }
 
-→ { "type":"ping" }
-← { "type":"pong", "sessionId":"..." }
+→ { "type": "ping" }
+← { "type": "pong",     "sessionId": "sess_abc123" }
+```
 
-→ { "type":"getSkills" }
-← { "type":"skills", "skills":["browse",...], "tools":["Read",...], "slashCommands":[...], "agents":[...] }
+### 单例机制 / Singleton guarantee
 
-(首次 init 自动推送)
-← { "type":"init", "skills":[...], "tools":[...], ... }
+重复启动 `nx-ce serve` 会在同一端口上失败：
+
+```
+端口 3100 已被占用 — nx-ce 单例进程已在运行中
+Port 3100 already in use — another nx-ce instance is running
 ```
 
-协议消息类型 / Message types:
+---
+
+## 协议 / Protocol (stdin/stdout)
+
+`nx-ce query` 子命令仍使用长度前缀 JSON（Chrome Native Messaging 格式）：
+
+```
+[4 bytes LE uint32 = 负载长度 / payload length][UTF-8 JSON payload]
+```
 
-| 方向 / 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 |
-| → | `getSkills` | Go 端按需拉取技能/工具列表 / Fetch skills/tools list |
-| ← | `init` / `skills` | 技能列表回复 / Skills metadata response |
+### 查询（一次性）/ Query (one-shot)
+
+```
+→ { "prompt": "...", "model": "...", "systemPrompt": "..." }
+← { "text": "...", "sessionId": "sess_xxx" }
+```
+
+### 带元数据输出 / With metadata
+
+```
+← { "text": "...", "sessionId": "sess_xxx",
+    "metadata": { "skills": [...], "tools": [...], "slashCommands": [...] } }
+```
 
 ---
 
@@ -148,10 +188,8 @@ All IPC uses the same wire format as Chrome native messaging:
 
 ```
 Chrome Extension / 浏览器扩展
-       ↕ Native Messaging (4B+JSON)
-Native Host (Go)
-       ↕ 4B+JSON (via executor.startProcess)
-nx-ce serve (Node.js)
+       ↕ WebSocket (ws://127.0.0.1:3100)
+nx-ce serve (Node.js)   ← 单例进程 / singleton process
        ↕ @anthropic-ai/claude-agent-sdk
 Claude Code CLI (子进程 / subprocess)
 ```
@@ -165,8 +203,6 @@ Claude Code CLI (子进程 / subprocess)
 
 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",
@@ -182,9 +218,12 @@ Persisted to `~/.nx-ce/instances/{name}.json`. Each named instance stores its PI
 ## 开发 / Development
 
 ```bash
-# 本地运行 / Run locally
+# 本地运行一次查询 / Run a one-shot query
 node ./bin/nx-ce.js query "你好"
 
+# 启动 WebSocket 服务 / Start WebSocket server
+node ./bin/nx-ce.js serve --port 3100
+
 # 检查语法 / Check syntax
 node -c src/*.js
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nx-ce",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "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",
@@ -30,6 +30,7 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.159"
+    "@anthropic-ai/claude-agent-sdk": "^0.3.159",
+    "ws": "^8.21.0"
   }
 }

package/src/cli.js

@@ -8,6 +8,7 @@
 import { existsSync } from 'node:fs';
 import { runQuery } from './query.js';
 import { startServe } from './serve.js';
+import { listSkills } from './skills.js';
 import { readState, listStates } from './session-store.js';
 
 /**
@@ -82,7 +83,7 @@ export async function runCli() {
     }
 
     case 'serve': {
-      // 持久化服务模式
+      // WebSocket 持久化服务模式
       const name = flags.name || 'default';
 
       const result = await startServe({
@@ -91,6 +92,7 @@ export async function runCli() {
         model: flags.model,
         cwd: flags.cwd || process.cwd(),
         env: flags.env ? parseEnvString(flags.env) : undefined,
+        port: flags.port ? parseInt(flags.port, 10) : undefined,
       });
 
       return result;
@@ -105,6 +107,15 @@ export async function runCli() {
       return listStates();      // 列出所有实例
     }
 
+    case 'skills': {
+      const result = await listSkills({
+        cwd: flags.cwd || process.cwd(),
+        claudePath: resolveClaudePath(flags['claude-path']),
+        env: flags.env ? parseEnvString(flags.env) : undefined,
+      });
+      return result;
+    }
+
     case 'help':
     default:
       // 显示帮助信息
@@ -122,14 +133,17 @@ export async function runCli() {
     --no-persist                  不持久化会话
     --env "KEY=value,KEY2=val"    额外环境变量
 
-  nx-ce serve                     持久化管理器进程（stdin/stdout）
+  nx-ce serve                     WebSocket 持久化服务器（单一进程 / 多客户端）
     --name <name>                 实例名称（默认: "default"）
+    --port <port>                 WebSocket 端口（默认: 3100）
     --model <id>                  模型覆盖
     --claude-path <path>          Claude CLI 路径
     --env "KEY=value,..."         额外环境变量
 
   nx-ce status [--name <name>]   查看实例状态
 
+  nx-ce skills [--cwd <path>]        列出 SDK 可用 skill/tool/agent
+
   nx-ce help                      显示此帮助
 `);
       return null;

package/src/index.js

@@ -7,5 +7,14 @@
  */
 
 export { runQuery } from './query.js';
-export { readState, writeState, deleteState, listStates } from './session-store.js';
+export { listSkills } from './skills.js';
+export {
+  readState,
+  writeState,
+  deleteState,
+  listStates,
+  LifecycleState,
+  createState,
+} from './session-store.js';
 export { readMessage, writeMessage } from './protocol.js';
+export { generateId, MonotonicClock, getMachineId, formatBytes } from './util.js';