swarmpath-claudecode-bridge 1.0.0 → 1.2.0

package/README.md

@@ -1,33 +1,45 @@
-# SwarmPath Claude Code Bridge v2.4.1
+# SwarmPath Claude Code Bridge v2.5
 
-手机远程控制 Mac 本地 Claude Code — 一行命令连接，自动登录，无需手动粘贴 Token。
+手机远程控制 Mac 本地 Claude Code — 一行命令连接，自动登录，支持 Chat + Terminal 双模式。
 
 ## 快速开始
 
 ```bash
 # 第一步：配置（仅首次）
-npx swarmpath-claudecode-bridge --setup
+npx swarmpath-claudecode-bridge@latest --setup
 
 # 第二步：启动（任意项目目录下）
 cd ~/my-project
-npx swarmpath-claudecode-bridge
+npx swarmpath-claudecode-bridge@latest
 
 # 第三步：手机 SwarmPath Chat 输入配对码
 /connect XXXXXX
 ```
 
-## 原理
+npm 包地址：https://www.npmjs.com/package/swarmpath-claudecode-bridge
+
+## 双模式
+
+### Chat 模式（默认）
+
+在 Bridge session 中发消息，Claude Code 以 `claude -p` 非交互模式执行，流式返回结果。适合手机端使用。
+
+### Terminal 模式（v2.5 新增）
+
+点击 header 栏的 `>_` 按钮切换到 Terminal 模式，在网页中嵌入真正的终端（xterm.js），通过 PTY 双向通信，获得和本地终端完全一致的 Claude Code 体验：
+
+- 完整交互式 TUI（进度条、颜色、动画）
+- 支持 `/` 命令（`/help`、`/compact` 等）
+- 窗口 resize 自适应
+- 建议在桌面端使用（手机屏幕较小）
 
 ```
-手机 SwarmPath Chat          SwarmPath 服务器           Mac 本地
-     |                           |                       |
-     |                           |<-- WebSocket --------| bridge 启动 + 自动登录
-     |                           |--- 配对码 A3X7 ----->| 终端显示
-     |-- /connect A3X7 -------->| 配对成功                |
-     |                           |                       |
-     |-- 发送消息 ------------->|-- ws 转发 ------------>|
-     |                           |                       | claude -p "..." --resume
-     |<-- 流式回显 -------------|<-- ws 流式回传 --------|
+手机/桌面 xterm.js              SwarmPath 服务器         Mac 本地
+    |                              |                      |
+    |-- ws {input} --------------->|-- ws terminal_input ->|
+    |                              |                       | node-pty → claude 交互模式
+    |<-- ws {data} ----------------|<-- ws terminal_data --|
+    |-- ws {resize} -------------->|-- ws terminal_resize >|
 ```
 
 ## 安装 & 配置
@@ -35,13 +47,13 @@ npx swarmpath-claudecode-bridge
 ### 前置条件
 
 - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)（终端输入 `claude --version` 验证）
-- Node.js 18+
+- Node.js 18+（Terminal 模式需要编译 `node-pty` 原生模块）
 - SwarmPath Chat 账号
 
 ### 首次配置
 
 ```bash
-npx swarmpath-claudecode-bridge --setup
+npx swarmpath-claudecode-bridge@latest --setup
 ```
 
 交互式输入：
@@ -64,10 +76,10 @@ SwarmPath 服务器地址 [wss://www.swarmpathchat.com]:
 
 ```bash
 # 当前目录
-npx swarmpath-claudecode-bridge
+npx swarmpath-claudecode-bridge@latest
 
 # 指定项目目录
-npx swarmpath-claudecode-bridge --cwd /Users/apple/my-project
+npx swarmpath-claudecode-bridge@latest --cwd /Users/apple/my-project
 ```
 
 输出：
@@ -94,13 +106,16 @@ npx swarmpath-claudecode-bridge --cwd /Users/apple/my-project
 /connect F8USY4
 ```
 
-### 对话
+### Chat 模式对话
 
 在 Bridge session 中直接发消息：
 - `帮我看看当前目录有什么文件`
 - `帮我写一个 hello.py`
 - `运行测试`
-- `帮我把这个项目的架构图绘制出来`
+
+### Terminal 模式
+
+点击 header 右侧 `>_` 图标切换到 Terminal 模式，直接使用 Claude Code 交互式界面。
 
 ### 切换模型
 
@@ -139,13 +154,14 @@ export SWARMPATH_TOKEN=eyJ...
 
 | 特性 | 说明 |
 |------|------|
+| **Chat + Terminal 双模式** | Chat 模式适合手机，Terminal 模式提供完整 TUI 体验 |
 | **自动登录** | 首次 `--setup` 后，后续启动自动用存储的凭据登录 |
 | **Token 自动续期** | 每 12 分钟自动刷新，无需手动干预 |
 | **断线重连** | WebSocket 断开后自动重连（指数退避 5s → 60s） |
 | **Token 过期自动恢复** | 4001 断开时自动重新登录并重连 |
 | **长对话上下文** | `--resume` 复用 Claude session，多轮对话保持上下文 |
 | **远程文件浏览** | 资源管理器远程浏览 Mac 文件（只读） |
-| **`/cd` 切目录** | 动态切换工作目录，无需重启 |
+| **`/cd` 切目录** | 动态切换工作目录，自动重置 session |
 
 ## 安全
 

package/index.mjs

@@ -10,13 +10,17 @@
  *   npx swarmpath-claudecode-bridge --server wss://... --token <jwt>  # Manual token mode
  */
 
-import { spawn } from 'child_process';
+import { spawn, execSync as _execSync } from 'child_process';
 import { resolve, join, extname } from 'path';
 import { readdirSync, statSync, readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
 import { homedir } from 'os';
 import { createInterface } from 'readline';
 import WebSocket from 'ws';
 
+// node-pty for terminal mode (optional — gracefully degrade if not available)
+let pty = null;
+try { pty = (await import('node-pty')).default || (await import('node-pty')); } catch {};
+
 // ---------------------------------------------------------------------------
 // Config file
 // ---------------------------------------------------------------------------
@@ -176,6 +180,9 @@ let activeRequestId = null;
 let claudeSessionId = null;
 let shuttingDown = false;
 
+/** Terminal PTY sessions: requestId → pty instance */
+const terminalSessions = new Map();
+
 const HEARTBEAT_MS = 30_000;
 const RECONNECT_MS = 5_000;
 const MAX_RECONNECT_MS = 60_000;
@@ -238,6 +245,7 @@ function connect() {
     // If token expired, auto-refresh and reconnect
     if (code === 4001 && !shuttingDown) {
       console.log('🔑 Token 过期，尝试自动续期...');
+      cfg.accessToken = null; // Clear expired token so ensureToken fetches a new one
       try {
         TOKEN = await ensureToken(cfg);
         console.log('🔑 续期成功，重新连接...');
@@ -306,6 +314,22 @@ function handleMessage(msg) {
       handleFileRequest(msg);
       break;
 
+    case 'terminal_start':
+      handleTerminalStart(msg);
+      break;
+
+    case 'terminal_input':
+      handleTerminalInput(msg);
+      break;
+
+    case 'terminal_resize':
+      handleTerminalResize(msg);
+      break;
+
+    case 'terminal_stop':
+      handleTerminalStop(msg);
+      break;
+
     case 'error':
       console.error('Server error:', msg.message);
       break;
@@ -387,6 +411,7 @@ function executePrompt(requestId, prompt, model) {
       activeChild = null;
       activeRequestId = null;
     }
+    if (code !== 0 && stderrBuf.trim()) console.error(`  ⚠ stderr [${requestId}]: ${stderrBuf.trim().slice(0, 200)}`);
     console.log(`  ✓ 完成 [${requestId}] (exit=${code})`);
   });
 
@@ -420,6 +445,76 @@ function processClaudeEvent(requestId, event, hasSentDelta) {
   return false;
 }
 
+// ---------------------------------------------------------------------------
+// Terminal PTY operations
+// ---------------------------------------------------------------------------
+function handleTerminalStart(msg) {
+  const { requestId, cols, rows } = msg;
+  if (!pty) {
+    wsSend({ type: 'terminal_exit', requestId, exitCode: -1, error: 'node-pty not available' });
+    return;
+  }
+  // Kill existing terminal for this requestId if any
+  if (terminalSessions.has(requestId)) {
+    try { terminalSessions.get(requestId).kill(); } catch {}
+    terminalSessions.delete(requestId);
+  }
+
+  // Resolve full path to claude — node-pty doesn't search PATH like shell
+  let claudePath = 'claude';
+  try {
+    claudePath = _execSync('which claude', { encoding: 'utf-8' }).trim() || 'claude';
+  } catch {}
+
+  console.log(`  🖥  Terminal start [${requestId}] (${cols}x${rows}) → ${claudePath}`);
+  let term;
+  try {
+    term = pty.spawn(claudePath, [], {
+      name: 'xterm-256color',
+      cols: cols || 120,
+      rows: rows || 30,
+      cwd: CWD,
+      env: { ...process.env, TERM: 'xterm-256color' },
+    });
+  } catch (err) {
+    console.error(`  🖥  Terminal spawn failed: ${err.message}`);
+    wsSend({ type: 'terminal_exit', requestId, exitCode: -1, error: err.message });
+    return;
+  }
+  terminalSessions.set(requestId, term);
+
+  term.onData((data) => {
+    wsSend({ type: 'terminal_data', requestId, data });
+  });
+
+  term.onExit(({ exitCode }) => {
+    console.log(`  🖥  Terminal exit [${requestId}] (code=${exitCode})`);
+    terminalSessions.delete(requestId);
+    wsSend({ type: 'terminal_exit', requestId, exitCode });
+  });
+}
+
+function handleTerminalInput(msg) {
+  const term = terminalSessions.get(msg.requestId);
+  if (term) term.write(msg.data);
+}
+
+function handleTerminalResize(msg) {
+  const term = terminalSessions.get(msg.requestId);
+  if (term && msg.cols && msg.rows) {
+    try { term.resize(msg.cols, msg.rows); } catch {}
+  }
+}
+
+function handleTerminalStop(msg) {
+  const term = terminalSessions.get(msg.requestId);
+  if (term) {
+    console.log(`  🖥  Terminal stop [${msg.requestId}]`);
+    try { term.kill(); } catch {}
+    terminalSessions.delete(msg.requestId);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // File operations
 // ---------------------------------------------------------------------------
@@ -441,8 +536,9 @@ function handleFileRequest(msg) {
       const st = statSync(newCwd);
       if (!st.isDirectory()) throw new Error('Not a directory');
       CWD = newCwd;
+      claudeSessionId = null; // Reset session — old session is tied to previous cwd
       wsSend({ type: 'cwd', cwd: CWD });
-      console.log(`  📂 切换目录: ${CWD}`);
+      console.log(`  📂 切换目录: ${CWD} (session reset)`);
       wsSend({ type: 'file_response', requestId, data: { cwd: CWD } });
     } else if (action === 'tree') {
       const tree = buildTree(CWD, '', msg.depth || 3, !!msg.showHidden);
@@ -511,6 +607,10 @@ function shutdown() {
     activeChild.kill('SIGTERM');
     setTimeout(() => { if (activeChild && !activeChild.killed) activeChild.kill('SIGKILL'); }, 2000);
   }
+  for (const [, term] of terminalSessions) {
+    try { term.kill(); } catch {}
+  }
+  terminalSessions.clear();
   if (ws) ws.close(1000, 'Shutdown');
   setTimeout(() => process.exit(0), 3000);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swarmpath-claudecode-bridge",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Connect local Claude Code to SwarmPath Chat — control your Mac from your phone",
   "type": "module",
   "bin": {
@@ -19,6 +19,7 @@
   },
   "license": "MIT",
   "dependencies": {
+    "node-pty": "^1.2.0-beta.12",
     "ws": "^8.19.0"
   }
 }