claude-remote 0.1.0 → 0.1.1

package/README.md

@@ -1,10 +1,10 @@
-# Claude API Remote Control
+# Claude Remote
 
 > 在手机上远程操控 Claude Code —— 随时随地写代码、审批权限、切换模型。
 
 ## 这是什么？
 
-一个轻量级的远程控制桥接器，让你可以通过手机浏览器或 Android App 连接到电脑上运行的 Claude Code，实现：
+一个轻量级的远程控制桥接器，让你可以通过 Android App 连接到电脑上运行的 Claude Code，实现：
 
 - 💬 远程对话 —— 发消息、看回复、完整的 Markdown 渲染
 - 🔧 工具调用可视化 —— 实时查看 Claude 正在读哪个文件、执行什么命令
@@ -12,50 +12,79 @@
 - 🔄 模式切换 —— Default / Plan / Accept Edits / Bypass
 - 📱 斜杠命令 —— /model /compact /clear /cost /help
 
-## 架构
+## 快速开始
 
-```
-┌─────────────┐     WebSocket     ┌──────────────┐     PTY      ┌────────────┐
-│  手机浏览器  │ ◄──────────────► │  server.js   │ ◄──────────► │ Claude Code│
-│  / App      │    ws://ip:3100   │  (Bridge)    │   node-pty   │   (CLI)    │
-└─────────────┘                   └──────────────┘              └────────────┘
-                                        │
-                                        │ 读取 JSONL transcript
-                                        ▼
-                                  ~/.claude/projects/
+### 1. 安装
+
+```bash
+npm install -g claude-remote
 ```
 
-**server.js** 是核心桥接层：
-- 通过 `node-pty` 启动并管理 Claude Code CLI 进程
-- 监听 `~/.claude/projects/` 下的 JSONL transcript 文件，实时解析事件
-- 通过 WebSocket 将事件广播给所有连接的客户端
-- 转发客户端输入到 Claude PTY
+### 2. 启动
 
-## 快速开始
+在任意项目目录下运行：
+
+```bash
+claude-remote
+```
+
+会在当前目录启动 Claude Code 并开启远程控制服务（默认端口 3100）。
 
-### 1. 启动 Bridge Server
+指定端口：
 
 ```bash
-# 首次运行先安装依赖
-cd /path/to/claudecode_api_RemoteControl
-npm install
+PORT=8080 claude-remote
+```
+
+### 3. App 连接
+
+安装 Android App 后，在设置页输入服务器地址连接。根据你的网络环境，有以下三种方式：
 
-# 在任意项目目录下，用完整路径启动（默认端口 3100）
-node /path/to/claudecode_api_RemoteControl/server.js
+#### 方式一：局域网直连
 
-# 或指定端口
-PORT=8080 node /path/to/claudecode_api_RemoteControl/server.js
+手机和电脑在同一 Wi-Fi 下，直接输入电脑内网 IP：
+
+```
+ws://<电脑IP>:3100
 ```
 
-### 2. 手机浏览器访问
+> 适合在家或办公室使用，最简单、延迟最低。
+
+#### 方式二：Tailscale 组网
 
-确保手机和电脑在同一局域网，浏览器打开：
+通过 [Tailscale](https://tailscale.com) 虚拟局域网，手机和电脑不在同一网络也能连接。
 
+1. 电脑和手机都安装 Tailscale 并登录同一账号
+2. 在 Tailscale 管理面板查看电脑的 Tailscale IP（通常是 `100.x.x.x`）
+3. App 中输入：
+
+```
+ws://<Tailscale IP>:3100
+```
+
+> 适合跨网络使用，无需公网暴露，安全可靠。
+
+#### 方式三：Cloudflare Tunnel 公网访问
+
+通过 [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) 将本地服务暴露到公网。
+
+1. 安装 `cloudflared` 并登录
+2. 启动隧道：
+
+```bash
+cloudflared tunnel --url http://localhost:3100
 ```
-http://<电脑IP>:3100
+
+3. 获得一个 `https://xxx.trycloudflare.com` 的地址
+4. App 中输入（注意用 `wss://`）：
+
 ```
+wss://xxx.trycloudflare.com
+```
+
+> 适合在外网或移动网络下远程控制，支持 HTTPS/WSS 加密。
 
-### 3. Android App（可选）
+### 4. 编译 Android App
 
 ```bash
 cd app
@@ -64,26 +93,25 @@ npx tauri android init
 npx tauri android dev
 ```
 
-App 启动后输入 server 地址连接即可。
-
-## 项目结构
+## 架构
 
 ```
-├── server.js              # Bridge 服务器（HTTP + WebSocket + PTY）
-├── web/
-│   └── index.html         # Web UI（单文件 SPA）
-├── app/                   # Tauri 2.0 Android 客户端
-│   ├── src/
-│   │   ├── index.html     # 入口页面（含连接页）
-│   │   ├── main.js        # 业务逻辑
-│   │   └── styles.css     # 样式
-│   └── src-tauri/
-│       ├── src/lib.rs     # Rust 入口（最小化）
-│       └── tauri.conf.json
-├── hooks/                 # Claude Code permission hooks
-└── package.json
+┌─────────────┐     WebSocket     ┌──────────────┐     PTY      ┌────────────┐
+│  Android App│ ◄──────────────► │  server.js   │ ◄──────────► │ Claude Code│
+│             │   ws://ip:3100   │  (Bridge)    │   node-pty   │   (CLI)    │
+└─────────────┘                   └──────────────┘              └────────────┘
+                                        │
+                                        │ 读取 JSONL transcript
+                                        ▼
+                                  ~/.claude/projects/
 ```
 
+**server.js** 是核心桥接层：
+- 通过 `node-pty` 启动并管理 Claude Code CLI 进程
+- 监听 `~/.claude/projects/` 下的 JSONL transcript 文件，实时解析事件
+- 通过 WebSocket 将事件广播给所有连接的客户端
+- 转发客户端输入到 Claude PTY
+
 ## 功能特性
 
 | 功能 | 说明 |
@@ -96,7 +124,8 @@ App 启动后输入 server 地址连接即可。
 | 斜杠命令菜单 | 输入 `/` 弹出命令面板 |
 | 模型切换 | 底部面板选择，toast 即时反馈 |
 | 断线重连 | 自动重连 + 事件回放，不丢消息 |
-| 外部链接 | 点击链接跳转系统浏览器，不影响 WebView |
+| 图片上传 | 手机拍照/选图发送到 Claude Code |
+| 代码 Diff | GitHub 风格行内高亮 |
 | 安卓适配 | 安全区、虚拟键盘、大触摸目标 |
 
 ## 依赖
@@ -104,11 +133,11 @@ App 启动后输入 server 地址连接即可。
 - **Node.js** >= 18
 - **node-pty** —— PTY 终端模拟
 - **ws** —— WebSocket 服务
-- **Tauri 2.0** —— Android App（可选，需要 Rust 工具链）
+- **Tauri 2.0** —— Android App（需要 Rust 工具链）
 
 ## TODO
 
-> 本项目看到 Claude Code 官方远程控制，可惜不支持api调用的模式，于是空闲时间摸鱼用 vibing code 写的小东西，目前处于快速迭代阶段。
+> 本项目看到 Claude Code 官方远程控制，可惜不支持 API 调用的模式，于是空闲时间摸鱼用 vibing code 写的小东西，目前处于快速迭代阶段。
 
 - [x] 提问与计划远程弹窗（AskUserQuestion / ExitPlanMode 远程交互）
 - [x] 自动审批命令模式
@@ -118,5 +147,6 @@ App 启动后输入 server 地址连接即可。
 - [x] 缓存机制 —— 避免每次 App 重连全量回放
 - [x] App 支持图片上传
 - [x] /命令指令及样式美化
+- [x] npm 包化 —— `npm install -g claude-remote` 全局安装，`claude-remote` 一键启动
+- [x] AI 截图显示 —— 工具返回的图片（如 Playwright 截图）全宽渲染，点击全屏查看
 - [ ] Tool Use 状态渲染（进行中 / 成功 / 失败）
-- [ ] npm 包化 —— 改造为 npm install 全局安装，支持 npx 一键启动

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-remote",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Remote control bridge for Claude Code REPL - drive from phone/WebUI",
   "main": "server.js",
   "bin": {

package/server.js

@@ -16,11 +16,12 @@ const PROJECTS_DIR = path.join(CLAUDE_HOME, 'projects');
 let claudeProc = null;
 let transcriptPath = null;
 let currentSessionId = null;
-let transcriptOffset = 0;
-let eventBuffer = [];
-let eventSeq = 0;
-const EVENT_BUFFER_MAX = 5000;
-let tailTimer = null;
+let transcriptOffset = 0;
+let eventBuffer = [];
+let eventSeq = 0;
+const EVENT_BUFFER_MAX = 5000;
+let nextWsId = 0;
+let tailTimer = null;
 let discoveryTimer = null;
 let switchWatcher = null;
 let expectingSwitch = false;
@@ -36,7 +37,6 @@ const IMAGE_UPLOAD_TTL_MS = 15 * 60 * 1000;
 let approvalSeq = 0;
 const pendingApprovals = new Map();  // id → { res, timer }
 const pendingImageUploads = new Map();
-let currentMode = 'default';
 let approvalMode = 'default';  // 'default' | 'partial' | 'all'
 const ALWAYS_AUTO_ALLOW = new Set(['TaskCreate', 'TaskUpdate']);
 const PARTIAL_AUTO_ALLOW = new Set(['Read', 'Glob', 'Grep', 'Write', 'Edit']);
@@ -44,10 +44,28 @@ const PARTIAL_AUTO_ALLOW = new Set(['Read', 'Glob', 'Grep', 'Write', 'Edit']);
 // --- Logging → file only (never pollute the terminal) ---
 const LOG_FILE = path.join(os.homedir(), '.claude', 'bridge.log');
 fs.writeFileSync(LOG_FILE, `--- Bridge started ${new Date().toISOString()} ---\n`);
-function log(msg) {
-  const line = `[${new Date().toISOString()}] ${msg}\n`;
-  fs.appendFileSync(LOG_FILE, line);
-}
+function log(msg) {
+  const line = `[${new Date().toISOString()}] ${msg}\n`;
+  fs.appendFileSync(LOG_FILE, line);
+}
+
+function wsLabel(ws) {
+  const clientId = ws && ws._clientInstanceId ? ` client=${ws._clientInstanceId}` : '';
+  return `ws#${ws && ws._bridgeId ? ws._bridgeId : '?'}${clientId}`;
+}
+
+function sendWs(ws, msg, context = '') {
+  if (!ws || ws.readyState !== WebSocket.OPEN) return false;
+  ws.send(JSON.stringify(msg));
+  if (msg.type === 'status' || msg.type === 'transcript_ready' || msg.type === 'replay_done') {
+    const extra = [];
+    if (msg.sessionId !== undefined) extra.push(`session=${msg.sessionId ?? 'null'}`);
+    if (msg.lastSeq !== undefined) extra.push(`lastSeq=${msg.lastSeq}`);
+    if (msg.resumed !== undefined) extra.push(`resumed=${msg.resumed}`);
+    log(`Send ${msg.type}${context ? ` (${context})` : ''} -> ${wsLabel(ws)}${extra.length ? ` ${extra.join(' ')}` : ''}`);
+  }
+  return true;
+}
 
 // ============================================================
 //  1. Static file server
@@ -76,12 +94,6 @@ const server = http.createServer((req, res) => {
         return;
       }
 
-      // Track mode from hook payload
-      if (data.permission_mode && data.permission_mode !== currentMode) {
-        currentMode = data.permission_mode;
-        broadcast({ type: 'mode', mode: currentMode });
-      }
-
       if (ALWAYS_AUTO_ALLOW.has(data.tool_name)) {
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ decision: 'allow' }));
@@ -167,23 +179,32 @@ const server = http.createServer((req, res) => {
 // ============================================================
 const wss = new WebSocketServer({ server });
 
-function broadcast(msg) {
-  const raw = JSON.stringify(msg);
-  for (const ws of wss.clients) {
-    if (ws.readyState === WebSocket.OPEN) ws.send(raw);
-  }
-}
+function broadcast(msg) {
+  const raw = JSON.stringify(msg);
+  const recipients = [];
+  for (const ws of wss.clients) {
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(raw);
+      recipients.push(wsLabel(ws));
+    }
+  }
+  if (msg.type === 'working_started' || msg.type === 'turn_complete' || msg.type === 'status' || msg.type === 'transcript_ready') {
+    log(`Broadcast ${msg.type} -> ${recipients.length} client(s)${recipients.length ? ` [${recipients.join(', ')}]` : ''}`);
+  }
+}
 
 function latestEventSeq() {
   return eventBuffer.length > 0 ? eventBuffer[eventBuffer.length - 1].seq : 0;
 }
 
-function sendReplay(ws, lastSeq = null) {
-  const normalizedLastSeq = Number.isInteger(lastSeq) && lastSeq >= 0 ? lastSeq : null;
-  const replayFrom = normalizedLastSeq == null ? 0 : normalizedLastSeq;
-  const records = replayFrom > 0
-    ? eventBuffer.filter(record => record.seq > replayFrom)
-    : eventBuffer;
+function sendReplay(ws, lastSeq = null) {
+  const normalizedLastSeq = Number.isInteger(lastSeq) && lastSeq >= 0 ? lastSeq : null;
+  const replayFrom = normalizedLastSeq == null ? 0 : normalizedLastSeq;
+  const records = replayFrom > 0
+    ? eventBuffer.filter(record => record.seq > replayFrom)
+    : eventBuffer;
+
+  log(`Replay start -> ${wsLabel(ws)} from=${replayFrom} count=${records.length} currentSession=${currentSessionId ?? 'null'}`);
 
   for (const record of records) {
     ws.send(JSON.stringify({
@@ -193,13 +214,13 @@ function sendReplay(ws, lastSeq = null) {
     }));
   }
 
-  ws.send(JSON.stringify({
-    type: 'replay_done',
-    sessionId: currentSessionId,
-    lastSeq: latestEventSeq(),
-    resumed: normalizedLastSeq != null,
-  }));
-}
+  sendWs(ws, {
+    type: 'replay_done',
+    sessionId: currentSessionId,
+    lastSeq: latestEventSeq(),
+    resumed: normalizedLastSeq != null,
+  }, 'sendReplay');
+}
 
 function sendUploadStatus(ws, uploadId, status, extra = {}) {
   if (!ws || ws.readyState !== WebSocket.OPEN) return;
@@ -244,24 +265,28 @@ setInterval(() => {
   }
 }, 60 * 1000).unref();
 
-wss.on('connection', (ws) => {
-  ws.send(JSON.stringify({
-    type: 'status',
-    status: claudeProc ? 'running' : 'starting',
-    hasTranscript: !!transcriptPath,
-    cwd: CWD,
-    sessionId: currentSessionId,
-    lastSeq: latestEventSeq(),
-  }));
-
-  if (currentSessionId) {
-    ws.send(JSON.stringify({
-      type: 'transcript_ready',
-      transcript: transcriptPath,
-      sessionId: currentSessionId,
-      lastSeq: latestEventSeq(),
-    }));
-  }
+wss.on('connection', (ws, req) => {
+  ws._bridgeId = ++nextWsId;
+  ws._clientInstanceId = '';
+  log(`WS connected: ${wsLabel(ws)} remote=${req.socket.remoteAddress || '?'} ua=${JSON.stringify(req.headers['user-agent'] || '')}`);
+
+  sendWs(ws, {
+    type: 'status',
+    status: claudeProc ? 'running' : 'starting',
+    hasTranscript: !!transcriptPath,
+    cwd: CWD,
+    sessionId: currentSessionId,
+    lastSeq: latestEventSeq(),
+  }, 'initial');
+
+  if (currentSessionId) {
+    sendWs(ws, {
+      type: 'transcript_ready',
+      transcript: transcriptPath,
+      sessionId: currentSessionId,
+      lastSeq: latestEventSeq(),
+    }, 'initial');
+  }
 
   // New clients should explicitly request a resume window. Keep a delayed
   // full replay fallback so older clients still work.
@@ -276,12 +301,20 @@ wss.on('connection', (ws) => {
     let msg;
     try { msg = JSON.parse(raw); } catch { return; }
 
-    switch (msg.type) {
-      case 'resume': {
-        ws._resumeHandled = true;
-        if (ws._legacyReplayTimer) {
-          clearTimeout(ws._legacyReplayTimer);
-          ws._legacyReplayTimer = null;
+    switch (msg.type) {
+      case 'hello':
+        ws._clientInstanceId = String(msg.clientInstanceId || ws._clientInstanceId || '');
+        log(`WS hello from ${wsLabel(ws)} page=${JSON.stringify(msg.page || '')} ua=${JSON.stringify(msg.userAgent || '')}`);
+        break;
+      case 'debug_log':
+        if (msg.clientInstanceId) ws._clientInstanceId = String(msg.clientInstanceId);
+        log(`ClientDebug ${wsLabel(ws)} event=${msg.event || 'unknown'} detail=${JSON.stringify(msg.detail || {})}`);
+        break;
+      case 'resume': {
+        ws._resumeHandled = true;
+        if (ws._legacyReplayTimer) {
+          clearTimeout(ws._legacyReplayTimer);
+          ws._legacyReplayTimer = null;
         }
 
         if (!currentSessionId) {
@@ -294,17 +327,23 @@ wss.on('connection', (ws) => {
           break;
         }
 
-        const canResume = (
-          msg.sessionId &&
-          msg.sessionId === currentSessionId &&
-          Number.isInteger(msg.lastSeq) &&
-          msg.lastSeq >= 0 &&
-          msg.lastSeq <= latestEventSeq()
-        );
-
-        sendReplay(ws, canResume ? msg.lastSeq : null);
-        break;
-      }
+        const clientServerLastSeq = Number.isInteger(msg.serverLastSeq) && msg.serverLastSeq >= 0
+          ? msg.serverLastSeq
+          : null;
+        const canResume = (
+          msg.sessionId &&
+          msg.sessionId === currentSessionId &&
+          Number.isInteger(msg.lastSeq) &&
+          msg.lastSeq >= 0 &&
+          msg.lastSeq <= latestEventSeq() &&
+          (clientServerLastSeq == null || msg.lastSeq <= clientServerLastSeq)
+        );
+
+        log(`Resume request from ${wsLabel(ws)} session=${msg.sessionId ?? 'null'} lastSeq=${msg.lastSeq} serverLastSeq=${clientServerLastSeq ?? 'null'} canResume=${canResume}`);
+
+        sendReplay(ws, canResume ? msg.lastSeq : null);
+        break;
+      }
       case 'input':
         // Raw terminal keystrokes from xterm.js in WebUI
         if (claudeProc) claudeProc.write(msg.data);
@@ -324,6 +363,7 @@ wss.on('connection', (ws) => {
           if (/^\/clear\s*$/i.test(text.trim())) {
             markExpectingSwitch();
           }
+          broadcast({ type: 'working_started' });
           claudeProc.write(text);
           setTimeout(() => {
             if (claudeProc) claudeProc.write('\r');
@@ -499,93 +539,16 @@ wss.on('connection', (ws) => {
     }
   });
 
-  ws.on('close', () => {
-    if (ws._legacyReplayTimer) {
-      clearTimeout(ws._legacyReplayTimer);
-      ws._legacyReplayTimer = null;
-    }
-    cleanupClientUploads(ws);
-  });
+  ws.on('close', () => {
+    if (ws._legacyReplayTimer) {
+      clearTimeout(ws._legacyReplayTimer);
+      ws._legacyReplayTimer = null;
+    }
+    log(`WS closed: ${wsLabel(ws)}`);
+    cleanupClientUploads(ws);
+  });
 });
 
-// ============================================================
-//  3. PTY Mode Detection (ANSI side-channel parsing)
-// ============================================================
-let ptyTextBuf = '';
-
-function stripAnsi(s) {
-  // eslint-disable-next-line no-control-regex
-  return s.replace(/\x1B(?:\[[\x20-\x3f]*[0-9;]*[A-Za-z]|\].*?(?:\x07|\x1B\\)|\([B0])/g, '');
-}
-
-function detectModeFromPTY(data) {
-  // Ink (Claude Code's TUI framework) redraws by sending cursor-up
-  // sequences (\x1B[<n>A) followed by new content.  When we detect a
-  // redraw we MUST clear the accumulated text buffer, otherwise stale
-  // mode keywords from previous renders linger and cause false matches.
-  if (/\x1B\[\d*A/.test(data)) {
-    ptyTextBuf = '';
-  }
-
-  ptyTextBuf += stripAnsi(data);
-  if (ptyTextBuf.length > 4000) ptyTextBuf = ptyTextBuf.slice(-2000);
-
-  const tail = ptyTextBuf.slice(-500);
-  const lc = tail.toLowerCase();
-
-  let detected = null;
-
-  // The status bar always contains "for shortcuts".
-  // (Older versions: "shift+tab to cycle", newer: "? for shortcuts")
-  const anchorIdx = Math.max(lc.lastIndexOf('for shortcuts'), lc.lastIndexOf('shift+tab'));
-
-  if (anchorIdx >= 0) {
-    // Inspect ~80 chars BEFORE and AFTER the anchor.
-    // The mode label can appear on either side depending on status bar layout:
-    //   "⏸ plan mode on  ? for shortcuts"   ← mode BEFORE anchor
-    //   "? for shortcuts  ⏵⏵ accept edits"  ← mode AFTER anchor
-    const before = lc.slice(Math.max(0, anchorIdx - 80), anchorIdx);
-    const after  = lc.slice(anchorIdx, Math.min(lc.length, anchorIdx + 80));
-    const win = before + after;
-    log(`Mode window: [${win}]`);
-
-    if (win.includes('plan')) {
-      detected = 'plan';
-    } else if (win.includes('accept')) {
-      detected = 'acceptEdits';
-    } else if (win.includes('bypass')) {
-      detected = 'bypassPermissions';
-    } else {
-      // Status bar present but no mode keyword → default
-      detected = 'default';
-    }
-  } else {
-    // No status-bar anchor — check for explicit toggle messages
-    // that Claude prints when mode changes (e.g. "⏸ plan mode on")
-    if (/plan mode on/i.test(lc) || /\u23F8\s*plan/i.test(tail)) {
-      detected = 'plan';
-    } else if (/accept edits on/i.test(lc) || /\u23F5\u23F5\s*accept/i.test(tail)) {
-      detected = 'acceptEdits';
-    } else if (/bypass.*on/i.test(lc)) {
-      detected = 'bypassPermissions';
-    }
-    // Check if buffer has status-bar content but anchor was mangled
-    // If we see mode indicators like ⏸ or ⏵⏵ without explicit text
-    else if (tail.includes('\u23F8')) {
-      detected = 'plan';
-    } else if (tail.includes('\u23F5\u23F5')) {
-      detected = 'acceptEdits';
-    }
-  }
-
-  if (detected && detected !== currentMode) {
-    currentMode = detected;
-    broadcast({ type: 'mode', mode: currentMode });
-    log(`Mode detected from PTY: ${currentMode}`);
-    ptyTextBuf = '';  // reset after detection
-  }
-}
-
 // ============================================================
 //  4. PTY Manager — local terminal passthrough
 // ============================================================
@@ -617,7 +580,6 @@ function spawnClaude() {
   claudeProc.onData((data) => {
     if (isTTY) process.stdout.write(data);   // show in the terminal you ran the bridge from
     broadcast({ type: 'pty_output', data });  // push to WebUI
-    detectModeFromPTY(data);
   });
 
   // === Local terminal input → PTY ===
@@ -851,6 +813,7 @@ function startTailing() {
           const event = JSON.parse(line);
           // Detect /clear from JSONL events (covers terminal direct input)
           if (event.type === 'user' || (event.message && event.message.role === 'user')) {
+            broadcast({ type: 'working_started' });
             const content = event.message && event.message.content;
             if (typeof content === 'string' && /^\/clear\s*$/i.test(content.trim())) {
               markExpectingSwitch();