nx-ce 0.1.8 → 0.2.1

package/README.md

@@ -3,13 +3,13 @@
 [![npm version](https://img.shields.io/npm/v/nx-ce)](https://www.npmjs.com/package/nx-ce)
 [![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** is a lightweight Node.js adapter for `@anthropic-ai/claude-agent-sdk`. It provides two modes:
+**nx-ce** is a lightweight Node.js adapter for `@anthropic-ai/claude-agent-sdk`. As of **v0.2**, it provides a single mode:
 
-- **`nx-ce query`** — one-shot cold-start queries (stateless, CLI-friendly)
-- **`nx-ce serve`** — WebSocket multi-session server (persistent, concurrent clients)
+- **`nx-ce serve`** — WebSocket multi-session server (persistent, concurrent clients). All consumers (CLI scripts, Chrome extensions, native_host) connect via this single WS endpoint.
 
-**nx-ce** 是一个轻量级 Node.js 适配器，封装了 `@anthropic-ai/claude-agent-sdk`。支持两种运行模式：
-一次性冷启动查询与多会话 WebSocket 持久化服务器。
+**nx-ce** 是一个轻量级 Node.js 适配器，封装了 `@anthropic-ai/claude-agent-sdk`。
+**v0.2 起只提供一种模式**：`nx-ce serve` 启动 WebSocket 多会话服务器。
+所有调用方（CLI 脚本 / Chrome 扩展 / native_host）都通过这个唯一的 WS 端点与 SDK 通信。
 
 ---
 
@@ -35,47 +35,16 @@ npm install -g nx-ce
 ## Quick Start / 快速开始
 
 ```bash
-# One-shot query (stateless)
-nx-ce query "用中文回答：1+1=？" --model claude-haiku-4-5
-
-# Start WebSocket server (persistent, multi-session)
+# Start WebSocket server (the only mode)
 nx-ce serve --port 3100
 
 # In another terminal, run tests
 node test/serve-test.mjs
 ```
 
----
-
-## `nx-ce query` — One-Shot Cold-Start Query / 一次性冷启动查询
-
-```bash
-nx-ce query "解释这段代码" --model claude-sonnet-4-6
-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>` | Model override (default `claude-sonnet-4-6`) / 模型 ID |
-| `--claude-path <path>` | Path to Claude CLI binary / Claude CLI 路径 |
-| `--system-prompt <text>` | System prompt override / 系统提示词覆盖 |
-| `--resume <sessionId>` | Resume a prior session (long conversation) / 续接会话 |
-| `--skill <name>[,<name>...]` | Load specific skills (comma-separated, or `all`) / 加载 Skill |
-| `--include-metadata` | Include skills/tools/slashCommands in output / 附带元数据 |
-| `--no-persist` | Don't persist session / 不持久化 |
-| `--env "KEY=val,KEY2=val"` | Extra environment variables / 额外环境变量 |
-
-### JSON output
+> **v0.2 breaking change**: `nx-ce query` and `nx-ce skills` CLI subcommands removed. All consumers must use the WebSocket protocol. See the [Protocol](#websocket-protocol--websocket-协议) section below.
 
-```json
-// Default
-{ "text": "2", "sessionId": "sess_abc" }
-
-// With --include-metadata
-{ "text": "2", "sessionId": "sess_abc", "metadata": { "skills": [...], "tools": [...], ... } }
-```
+> **v0.2 破坏性变更**：移除 `nx-ce query` 和 `nx-ce skills` 子命令。所有调用方必须使用 WebSocket 协议。
 
 ---
 
@@ -298,21 +267,6 @@ Each session has its own `agentQuery()`, `MessageChannel`, `MonotonicClock`, and
 
 ---
 
-## `nx-ce skills` — List Available Skills / 列出可用 Skill
-
-```bash
-nx-ce skills --cwd "D:/project"
-```
-
-```json
-{ "skills": ["code-review", "browse", ...],
-  "tools": ["Read", "Edit", "Bash", ...],
-  "slashCommands": ["code-review", ...],
-  "agents": ["Explore", ...] }
-```
-
----
-
 ## State Persistence / 状态持久化
 
 State files at `~/.nx-ce/instances/{key}.json`. Key format: `{name}~{cwd}`.
@@ -343,9 +297,6 @@ State files at `~/.nx-ce/instances/{key}.json`. Key format: `{name}~{cwd}`.
 ## Development / 开发
 
 ```bash
-# One-shot query
-node ./bin/nx-ce.js query "你好"
-
 # Start server
 node ./bin/nx-ce.js serve --port 3100
 

package/bin/nx-ce.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 
 /**
- * nx-ce — Claude Engine
+ * nx-ce — Claude Engine (v0.2 serve-only)
  *
- * 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
+ * Single entry point — all consumers (CLI / Chrome extension / native_host)
+ * talk to the WebSocket server via the unified protocol.
+ *
+ *   nx-ce serve [--port 3100]   — start WebSocket server
+ *   nx-ce status                — list instance states
+ *   nx-ce help                  — show help
  */
 
 import { runCli } from '../src/cli.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nx-ce",
-  "version": "0.1.8",
-  "description": "Claude Engine — SDK adapter layer for native messaging host. Bridges @anthropic-ai/claude-agent-sdk calls over a length-prefixed JSON protocol.",
+  "version": "0.2.1",
+  "description": "Claude Engine — WebSocket adapter for @anthropic-ai/claude-agent-sdk. Single serve mode serves all consumers (CLI / Chrome extension / native_host) over a unified JSON-over-WebSocket protocol.",
   "type": "module",
   "main": "src/index.js",
   "bin": {
@@ -17,8 +17,8 @@
   },
   "scripts": {
     "nx-ce": "node ./bin/nx-ce.js",
-    "test": "node test/basic.js",
-    "start": "node ./bin/nx-ce.js"
+    "test": "node test/serve-test.mjs",
+    "start": "node ./bin/nx-ce.js serve"
   },
   "keywords": [
     "claude",
@@ -26,7 +26,8 @@
     "anthropic",
     "sdk",
     "native-messaging",
-    "chrome-extension"
+    "chrome-extension",
+    "websocket"
   ],
   "license": "MIT",
   "dependencies": {

package/src/cli.js

@@ -1,14 +1,15 @@
 /**
- * CLI — 子命令路由器
+ * CLI — 子命令路由器（v0.2 起仅 serve 模式）
  *
- * 模式：nx-sx/src/cli.js
- * 路由到 query | serve | status | help
+ * 历史:
+ *   - 旧版有 query（冷启动）/ skills（独立拉元数据）子命令
+ *   - v0.2 起所有调用统一收敛到 serve：所有元数据通过 getSkills 消息获取
+ *
+ * 路由: serve | status | help
  */
 
 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';
 
 /**
@@ -19,11 +20,9 @@ import { readState, listStates } from './session-store.js';
  * @returns {{ cmd: string, flags: object, args: string[] }}
  */
 export function parseArgs(argv = process.argv.slice(2)) {
-  const cmd = argv[0];          // 第一个参数为子命令
+  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++) {
@@ -31,13 +30,10 @@ export function parseArgs(argv = process.argv.slice(2)) {
     if (arg.startsWith('--')) {
       const eqIdx = arg.indexOf('=');
       if (eqIdx !== -1) {
-        // --key=value 格式
         flags[arg.slice(2, eqIdx)] = arg.slice(eqIdx + 1);
       } else if (rest[i + 1] === undefined || rest[i + 1].startsWith('--')) {
-        // --key 后面没有值，或下一个参数也是 flag → boolean flag
         flags[arg.slice(2)] = true;
       } else {
-        // --key value 格式（下一个参数作为值）
         flags[arg.slice(2)] = rest[++i] ?? true;
       }
     } else {
@@ -50,42 +46,14 @@ export function parseArgs(argv = process.argv.slice(2)) {
 
 /**
  * 运行 CLI 入口。
- * 根据子命令分发到对应的处理函数。
  */
 export async function runCli() {
-  const { cmd, flags, args } = parseArgs();
+  const { cmd, flags } = 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,
-      });
-
-      // 默认只返回 text + sessionId，加 --include-metadata 才返回 metadata
-      if (flags['include-metadata']) {
-        return result;
-      }
-      return { text: result.text, sessionId: result.sessionId };
-    }
-
     case 'serve': {
-      // WebSocket 持久化服务模式
+      // WebSocket 持久化服务模式（唯一数据通路）
       const name = flags.name || 'default';
-
       const result = await startServe({
         name,
         claudePath: resolveClaudePath(flags['claude-path']),
@@ -94,57 +62,41 @@ export async function runCli() {
         env: flags.env ? parseEnvString(flags.env) : undefined,
         port: flags.port ? parseInt(flags.port, 10) : undefined,
       });
-
       return result;
     }
 
     case 'status': {
-      // 查询实例状态
       const name = flags.name;
       if (name) {
-        return readState(name); // 查询指定实例
+        return readState(name);
       }
-      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;
+      return listStates();
     }
 
     case 'help':
+    case '--help':
+    case '-h':
     default:
-      // 显示帮助信息
       console.log(`
-	nx-ce — Claude Engine
+	nx-ce — Claude Engine (v0.2: serve-only)
 
 用法:
-  nx-ce query <prompt>            一次性冷启动查询
-    --model <id>                  模型覆盖
-    --claude-path <path>          Claude CLI 路径
-    --system-prompt <text>        系统提示词覆盖
-    --resume <sessionId>          续接之前的会话（长对话）
-    --skill <name>[,<name>...]    加载指定 Skill（逗号分隔，传 "all" 加载全部）
-    --include-metadata            输出中附带 skills/tools/slash_commands 列表
-    --no-persist                  不持久化会话
-    --env "KEY=value,KEY2=val"    额外环境变量
-
-  nx-ce serve                     WebSocket 持久化服务器（单一进程 / 多客户端）
+  nx-ce serve                     WebSocket 持久化服务器（唯一入口）
     --name <name>                 实例名称（默认: "default"）
     --port <port>                 WebSocket 端口（默认: 3100）
     --model <id>                  模型覆盖
     --claude-path <path>          Claude CLI 路径
+    --cwd <path>                  默认工作目录
     --env "KEY=value,..."         额外环境变量
 
   nx-ce status [--name <name>]   查看实例状态
 
-  nx-ce skills [--cwd <path>]        列出 SDK 可用 skill/tool/agent
-
   nx-ce help                      显示此帮助
+
+协议（ws://127.0.0.1:3100）:
+  C→S: query / getSkills / getStatus / listSessions / closeSession / ping
+  S→C: connected / init / turn_start / text / thinking / tool_use / done /
+       error / pong / skills / status / session_list / session_closed
 `);
       return null;
   }
@@ -152,32 +104,18 @@ export async function runCli() {
 
 /**
  * 解析 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 全局或用户本地安装
-  ];
+  const candidates = [process.env.CLAUDE_PATH, process.env.CLAUDE_CLI_PATH];
   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}
+ * 解析环境变量字符串 "KEY=val,KEY2=val2"
  */
 function parseEnvString(str) {
   const result = {};
@@ -189,13 +127,3 @@ function parseEnvString(str) {
   }
   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

@@ -2,12 +2,14 @@
  * nx-ce — 公开 API 入口
  *
  * 用法:
- *   import { runQuery } from 'nx-ce';
- *   const { text, sessionId } = await runQuery({ prompt: 'hello', ... });
+ *   import { startServe, readState } from 'nx-ce';
+ *   await startServe({ name: 'main', port: 3100 });
+ *
+ * v0.2 起：nx-ce 仅提供 WebSocket serve 模式，不再有冷启动 query。
+ * 所有调用方（CLI / Chrome 扩展 / native_host）都通过 WS 协议与 serve 通信。
  */
 
-export { runQuery } from './query.js';
-export { listSkills } from './skills.js';
+export { startServe } from './serve.js';
 export {
   readState,
   writeState,

package/src/serve.js

@@ -515,19 +515,43 @@ export async function startServe(options) {
           break;
 
         case 'getSkills': {
-          // 按 (name, cwd) 查 session
-          const key = sessionKey(sessionName, req.cwd);
-          const session = sessionManager.sessions.get(key);
-          if (session?.metadata) {
-            ws.send(JSON.stringify(session.metadata));
+          // 解析目标 session
+          //   带 session/cwd → 取该 session 的元数据
+          //   不带 → 取任意已 init 的 session 的元数据（server 级）
+          let meta = null;
+          if (req.session || req.cwd) {
+            const key = sessionKey(sessionName, req.cwd);
+            const session = sessionManager.sessions.get(key);
+            meta = session?.metadata;
+          } else {
+            // server 级：找任意一个已 init 的 session
+            for (const s of sessionManager.sessions.values()) {
+              if (s.metadata) { meta = s.metadata; break; }
+            }
+          }
+
+          if (meta) {
+            // 统一返回 type='skills'，便于客户端按 type 路由
+            ws.send(JSON.stringify({
+              type: 'skills',
+              sessionId: meta.sessionId,
+              model: meta.model,
+              skills: meta.skills || [],
+              tools: meta.tools || [],
+              slashCommands: meta.slashCommands || [],
+              agents: meta.agents || [],
+              cwd: meta.cwd,
+            }));
           } else {
+            // 无 init 元数据时：让客户端发一个 query 触发 init，或
+            // 等下一个 session 启动后再次 getSkills
             ws.send(JSON.stringify({
               type: 'skills',
               skills: [],
               tools: [],
               slashCommands: [],
               agents: [],
-              note: 'session not yet initialized',
+              note: 'no session has been initialized yet — send a query first',
             }));
           }
           break;

package/src/query.js

@@ -1,128 +0,0 @@
-/**
- * 冷启动查询 — 对 @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, metadata: object | 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;
-  let metadata = null;
-
-  // 遍历 SDK 返回的流式消息
-  for await (const message of response) {
-    // 如果已中止，中断查询
-    if (abortController.signal.aborted) {
-      await response.interrupt();
-      break;
-    }
-
-    // 从 init 消息中捕获 sessionId + 技能/工具/命令 元数据
-    if (message.type === 'system' && message.subtype === 'init') {
-      sessionId = message.session_id;
-      metadata = {
-        model: message.model,
-        skills: message.skills || [],
-        tools: message.tools || [],
-        slashCommands: message.slash_commands || [],
-        agents: message.agents || [],
-      };
-    }
-
-    // 提取助手的文本回复内容
-    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, metadata };
-}

package/src/skills.js

@@ -1,56 +0,0 @@
-/**
- * skills — 查询 SDK 可用的 skill / tool / agent 列表
- *
- * 使用一次超轻量 agentQuery() 获取 init 元数据。
- * 不发起真正对话，不持久化 session。
- */
-
-import { query as agentQuery } from '@anthropic-ai/claude-agent-sdk';
-
-/**
- * 获取 SDK 可用的 skills/tools/slashCommands/agents 列表。
- *
- * @param {object} [options]
- * @param {string} [options.cwd]        - 工作目录
- * @param {string} [options.claudePath] - Claude CLI 路径
- * @param {object} [options.env]        - 额外环境变量
- * @returns {Promise<{ skills: string[], tools: string[], slashCommands: string[], agents: string[] }>}
- */
-export async function listSkills(options = {}) {
-  const sdkOptions = {
-    cwd: options.cwd || process.cwd(),
-    model: 'claude-haiku-4-5',
-    permissionMode: 'bypassPermissions',
-    allowDangerouslySkipPermissions: true,
-    persistSession: false,
-    env: { ...process.env, ...options.env },
-  };
-
-  if (options.claudePath) {
-    sdkOptions.pathToClaudeCodeExecutable = options.claudePath;
-  }
-
-  // 用空 prompt 做一次超轻量 init
-  const response = agentQuery({ prompt: ' ', options: sdkOptions });
-
-  const result = {
-    skills: [],
-    tools: [],
-    slashCommands: [],
-    agents: [],
-  };
-
-  for await (const message of response) {
-    if (message.type === 'system' && message.subtype === 'init') {
-      if (Array.isArray(message.skills)) result.skills = message.skills;
-      if (Array.isArray(message.tools)) result.tools = message.tools;
-      if (Array.isArray(message.slash_commands)) result.slashCommands = message.slash_commands;
-      if (Array.isArray(message.agents)) result.agents = message.agents;
-      // init 消息后立即中断，不继续消耗资源
-      await response.interrupt().catch(() => {});
-      break;
-    }
-  }
-
-  return result;
-}