remote-claude 0.1.0

package/.env.example

@@ -0,0 +1,15 @@
+# Remote Claude 飞书客户端配置
+
+# 飞书应用配置（必填）
+# 在飞书开发者后台创建应用获取: https://open.feishu.cn/app
+FEISHU_APP_ID=cli_xxxxx
+FEISHU_APP_SECRET=xxxxx
+
+# 用户白名单（可选）
+# 启用后只有白名单中的用户可以使用
+ENABLE_USER_WHITELIST=false
+ALLOWED_USERS=ou_xxxxx,ou_yyyyy
+
+# 机器人名称（用于群聊命名，默认 Claude）
+BOT_NAME=Ys-Claude
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Remote Claude Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,231 @@
+# Remote Claude
+
+**在电脑终端上打开的 Claude Code 进程，也可以在飞书中共享操作。电脑端、手机端无缝来回切换**
+
+电脑上用终端跑 Claude Code 写代码，同时在手机飞书上看进度、发指令、点按钮 — 不用守在电脑前，随时随地掌控 AI 编程。
+
+## 为什么需要它？
+
+Claude Code 只能在启动它的那个终端窗口里操作。一旦离开电脑，就只能干等。Remote Claude 让你：
+
+- **飞书里直接操作** — 手机/平板打开飞书，就能看到 Claude 的实时输出，发消息、选选项、批准权限，和终端里一模一样。
+- **用手机无缝延续电脑上做的工作** — 电脑上打开的Claude进程，也可以用飞书共享操作，开会、午休、通勤、上厕所时，都可以用手机延续之前在电脑上的工作。
+- **在电脑上也可以无缝延续手机上的工作** - 在lark端也可以打开新的Claude进程启动新的工作，回到电脑前还可以`attach`共享操作同一个Claude进程，延续手机端的工作。
+- **多端共享操作** — 多个终端 + 飞书可以共享操作同一个claude进程，回到家里ssh登录到服务器上也可以通过`attach`继续操作在公司ssh登录到服务器上打开的claude进程操作。
+- **机制安全** - 完全不侵入 Claude 进程，remote 功能完全通过终端交互来实现，不必担心 Claude 进程意外崩溃导致工作进展丢失。
+
+## 飞书端体验
+
+- 彩色代码输出，ANSI 着色完整还原
+- 交互式按钮：选项选择、权限确认，一键点击
+- 流式卡片更新：Claude 边想边输出，飞书端实时滚动显示
+- 后台 agent 状态面板：查看并管理正在运行的子任务
+
+## 快速开始
+
+### 1. 克隆并初始化
+
+```bash
+git clone https://github.com/yyzybb537/remote_claude.git
+cd remote_claude
+./init.sh
+```
+
+`init.sh` 会自动安装 uv、tmux 等依赖，配置飞书环境（可选），并写入 `cla` / `cl` 快捷命令。执行完成后重启终端生效。
+
+### 2. 启动
+
+| 快捷命令 | 说明 |
+|------|------|
+| `cla` | 启动 Claude (以当前目录路径为会话名) |
+| `cl` | 同 `cla`，但跳过权限确认 |
+
+### 3. 从其他终端连接(一般不需要)
+
+```bash
+remote-claude list
+remote-claude attach <会话名>
+```
+
+### 4. 从飞书端连接
+
+#### 4.1 配置飞书机器人
+
+1. 登录[飞书开放平台](https://open.feishu.cn/)，创建企业自建应用
+2. 执行命令`cp .env.example .env`, 获取 **App ID** 和 **App Secret**，填入 `.env` 文件
+3. 用`cla`或`cl`启动一次claude（会附带启动飞书客户端，如果之前已经启动过，需要重启飞书客户端: "remote-claude lark restart" ） 
+4. 企业自建应用页面`添加应用能力`（机器人能力）
+5. 企业自建应用页面配置事件回调（如果第3步没启动成功这里配置不了）：
+  - `事件与回调` -> `事件配置` -> `订阅方式`右边的笔图标 -> `选择：使用长连接接收事件` -> `点击保存` -> `下面添加事件: 接收消息 v2.0 (im.message.receive_v1)`
+  - `事件与回调` -> `回调配置` -> `订阅方式`右边的笔图标 -> `选择：使用长连接接收回调` -> `点击保存` -> `下面添加回调: 卡片回传交互 (card.action.trigger)`
+6. 企业自建应用页面配置权限：
+  - `权限管理` -> `批量导入/导出权限` -> 导入以下内容
+```json
+{
+  "scopes": {
+    "tenant": [
+      "base:app:read",
+      "base:field:read",
+      "base:form:read",
+      "base:record:read",
+      "base:record:retrieve",
+      "base:table:read",
+      "board:whiteboard:node:read",
+      "calendar:calendar.free_busy:read",
+      "cardkit:card:write",
+      "contact:contact.base:readonly",
+      "contact:user.employee_id:readonly",
+      "contact:user.id:readonly",
+      "docs:document.comment:read",
+      "docs:document.content:read",
+      "docs:document.media:download",
+      "docs:document.media:upload",
+      "docs:document:import",
+      "docs:permission.member:auth",
+      "docs:permission.member:create",
+      "docs:permission.member:transfer",
+      "docx:document.block:convert",
+      "docx:document:create",
+      "docx:document:readonly",
+      "docx:document:write_only",
+      "drive:drive.metadata:readonly",
+      "drive:drive.search:readonly",
+      "drive:drive:version:readonly",
+      "drive:file:download",
+      "drive:file:upload",
+      "im:chat.members:read",
+      "im:chat.members:write_only",
+      "im:chat.tabs:read",
+      "im:chat.tabs:write_only",
+      "im:chat.top_notice:write_only",
+      "im:chat:create",
+      "im:chat:delete",
+      "im:chat:operate_as_owner",
+      "im:chat:read",
+      "im:chat:update",
+      "im:message.group_at_msg:readonly",
+      "im:message.group_msg",
+      "im:message.p2p_msg:readonly",
+      "im:message.reactions:read",
+      "im:message.reactions:write_only",
+      "im:message:readonly",
+      "im:message:recall",
+      "im:message:send_as_bot",
+      "im:message:update",
+      "im:resource",
+      "sheets:spreadsheet.meta:read",
+      "sheets:spreadsheet.meta:write_only",
+      "sheets:spreadsheet:create",
+      "sheets:spreadsheet:read",
+      "sheets:spreadsheet:write_only",
+      "space:document:delete",
+      "space:document:retrieve",
+      "wiki:wiki:readonly"
+    ],
+    "user": [
+      "base:app:read",
+      "base:field:read",
+      "base:record:read",
+      "base:record:retrieve",
+      "base:table:read",
+      "calendar:calendar.event:create",
+      "calendar:calendar.event:delete",
+      "calendar:calendar.event:read",
+      "calendar:calendar.event:reply",
+      "calendar:calendar.event:update",
+      "calendar:calendar.free_busy:read",
+      "calendar:calendar:read",
+      "cardkit:card:write",
+      "contact:user.base:readonly",
+      "contact:user.employee_id:readonly",
+      "contact:user.id:readonly",
+      "docs:document.comment:read",
+      "docs:document.content:read",
+      "docs:document.media:download",
+      "docs:document.media:upload",
+      "docx:document.block:convert",
+      "docx:document:create",
+      "docx:document:readonly",
+      "docx:document:write_only",
+      "im:chat.managers:write_only",
+      "im:chat.members:read",
+      "im:chat.members:write_only",
+      "im:chat.tabs:read",
+      "im:chat.tabs:write_only",
+      "im:chat.top_notice:write_only",
+      "im:chat:delete",
+      "im:chat:read",
+      "im:chat:update",
+      "im:message.reactions:read",
+      "im:message.reactions:write_only",
+      "im:message:readonly",
+      "im:message:recall",
+      "im:message:update",
+      "search:docs:read",
+      "search:suite_dataset:readonly",
+      "sheets:spreadsheet.meta:read",
+      "sheets:spreadsheet.meta:write_only",
+      "sheets:spreadsheet:create",
+      "sheets:spreadsheet:read",
+      "sheets:spreadsheet:write_only",
+      "space:document:retrieve",
+      "task:task:read",
+      "task:task:readonly",
+      "task:task:write",
+      "task:task:writeonly",
+      "task:tasklist:read",
+      "task:tasklist:writeonly",
+      "wiki:wiki:readonly"
+    ]
+  }
+}
+```
+7. 企业自建应用页面: `创建版本` -> `发布到线上`
+8. 至此，完成飞书机器人配置
+
+#### 4.2 通过飞书机器人操作claude
+
+1. 从飞书搜素刚刚创建的飞书机器人（第一次搜比较慢，如果搜不到可能是忘记发布了）
+2. 飞书中与机器人对话，可用命令: 
+  - `/help` 展示可用命令
+  - `/menu` 展示菜单卡片，后续操作都操作这个卡片上的按钮即可
+
+## 使用指南
+
+### 快捷命令
+
+| 命令 | 说明 |
+|------|------|
+| `cla` | 启动飞书客户端 + 以当前目录路径为会话名启动 Claude |
+| `cl` | 同 `cla`，但跳过权限确认 |
+
+### 终端命令
+
+```bash
+remote-claude start <会话名>     # 启动新会话
+remote-claude attach <会话名>    # 连接现有会话
+remote-claude list               # 查看所有会话
+remote-claude kill <会话名>      # 终止会话
+```
+
+### 飞书客户端
+
+```bash
+remote-claude lark start         # 启动（后台运行）
+remote-claude lark stop          # 停止
+remote-claude lark restart       # 重启
+remote-claude lark status        # 查看状态
+```
+
+飞书中与机器人对话，可用命令：`/menu`、`/attach`、`/detach`、`/list`、`/help` 等。
+
+## 系统要求
+
+- **操作系统**: macOS 或 Linux
+- **依赖工具**: [uv](https://docs.astral.sh/uv/)、[tmux](https://github.com/tmux/tmux)、[Claude CLI](https://claude.ai/code)
+- **可选**: 飞书企业自建应用
+
+## 文档
+
+- [CLAUDE.md](./CLAUDE.md) — 项目架构和开发说明
+- [LARK_CLIENT_GUIDE.md](./LARK_CLIENT_GUIDE.md) — 飞书客户端完整指南

package/bin/cl

@@ -0,0 +1,20 @@
+#!/bin/bash
+# 解析符号链接，兼容 macOS（不支持 readlink -f）
+SOURCE="$0"
+while [ -L "$SOURCE" ]; do
+    DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+    SOURCE="$(readlink "$SOURCE")"
+    [[ "$SOURCE" != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+SCRIPT_DIR="$(cd -P "$(dirname "$SOURCE")" && cd .. && pwd)"
+
+# uv 路径兜底
+if ! command -v uv &>/dev/null; then
+    [ -f "$HOME/.local/bin/uv" ] && export PATH="$HOME/.local/bin:$PATH"
+fi
+
+# 检查飞书配置
+source "$SCRIPT_DIR/scripts/check-env.sh" "$SCRIPT_DIR"
+
+uv run --project "$SCRIPT_DIR" python3 "$SCRIPT_DIR/remote_claude.py" lark start
+uv run --project "$SCRIPT_DIR" python3 "$SCRIPT_DIR/remote_claude.py" start "${PWD}_$(date +%m%d_%H%M%S)" -- --dangerously-skip-permissions --permission-mode=dontAsk "$@"

package/bin/cla

@@ -0,0 +1,20 @@
+#!/bin/bash
+# 解析符号链接，兼容 macOS（不支持 readlink -f）
+SOURCE="$0"
+while [ -L "$SOURCE" ]; do
+    DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+    SOURCE="$(readlink "$SOURCE")"
+    [[ "$SOURCE" != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+SCRIPT_DIR="$(cd -P "$(dirname "$SOURCE")" && cd .. && pwd)"
+
+# uv 路径兜底
+if ! command -v uv &>/dev/null; then
+    [ -f "$HOME/.local/bin/uv" ] && export PATH="$HOME/.local/bin:$PATH"
+fi
+
+# 检查飞书配置
+source "$SCRIPT_DIR/scripts/check-env.sh" "$SCRIPT_DIR"
+
+uv run --project "$SCRIPT_DIR" python3 "$SCRIPT_DIR/remote_claude.py" lark start
+uv run --project "$SCRIPT_DIR" python3 "$SCRIPT_DIR/remote_claude.py" start "${PWD}_$(date +%m%d_%H%M%S)" -- "$@"

package/bin/remote-claude

@@ -0,0 +1,21 @@
+#!/bin/bash
+# 解析符号链接，兼容 macOS（不支持 readlink -f）
+SOURCE="$0"
+while [ -L "$SOURCE" ]; do
+    DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+    SOURCE="$(readlink "$SOURCE")"
+    [[ "$SOURCE" != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+INSTALL_DIR="$(cd -P "$(dirname "$SOURCE")" && cd .. && pwd)"
+
+# uv 路径兜底
+if ! command -v uv &>/dev/null; then
+    [ -f "$HOME/.local/bin/uv" ] && export PATH="$HOME/.local/bin:$PATH"
+fi
+
+# lark 子命令：检查 .env 配置
+if [ "$1" = "lark" ]; then
+    source "$INSTALL_DIR/scripts/check-env.sh" "$INSTALL_DIR"
+fi
+
+exec uv run --project "$INSTALL_DIR" python3 "$INSTALL_DIR/remote_claude.py" "$@"

package/client/client.py

@@ -0,0 +1,251 @@
+"""
+客户端连接器
+
+- 终端 raw mode 处理
+- Socket 连接
+- 输入转发
+- 输出显示
+- Ctrl+D 退出
+"""
+
+import asyncio
+import os
+import sys as _sys
+_sys.path.insert(0, str(__import__('pathlib').Path(__file__).parent.parent))  # 根目录 → protocol, utils
+import sys
+import tty
+import termios
+import signal
+import select
+from typing import Optional
+
+from utils.protocol import (
+    Message, MessageType, InputMessage, ResizeMessage,
+    encode_message, decode_message
+)
+from utils.session import get_socket_path, generate_client_id, get_terminal_size
+
+try:
+    from stats import track as _track_stats
+except Exception:
+    def _track_stats(*args, **kwargs): pass
+
+
+# 特殊按键
+CTRL_D = b'\x04'  # Ctrl+D - 退出
+
+
+class RemoteClient:
+    """远程客户端"""
+
+    def __init__(self, session_name: str):
+        self.session_name = session_name
+        self.socket_path = get_socket_path(session_name)
+        self.client_id = generate_client_id()
+
+        # 连接
+        self.reader: Optional[asyncio.StreamReader] = None
+        self.writer: Optional[asyncio.StreamWriter] = None
+        self.buffer = b""
+
+        # 状态
+        self.running = False
+
+        # 终端设置
+        self.old_settings = None
+
+    async def connect(self) -> bool:
+        """连接到服务器"""
+        if not self.socket_path.exists():
+            print(f"错误: 会话 '{self.session_name}' 不存在")
+            return False
+
+        try:
+            self.reader, self.writer = await asyncio.open_unix_connection(
+                path=str(self.socket_path)
+            )
+            return True
+        except Exception as e:
+            print(f"连接失败: {e}")
+            return False
+
+    async def run(self):
+        """运行客户端"""
+        if not await self.connect():
+            return
+
+        self.running = True
+        _track_stats('terminal', 'connect', session_name=self.session_name)
+
+        # 设置终端 raw mode
+        self._setup_terminal()
+
+        # 设置信号处理
+        self._setup_signals()
+
+        # 发送初始终端尺寸，让 server 将 PTY 调整为实际终端大小
+        rows, cols = get_terminal_size()
+        await self._send_resize(rows, cols)
+
+        try:
+            # 并行运行输入和输出处理
+            await asyncio.gather(
+                self._read_server(),
+                self._read_stdin(),
+                return_exceptions=True
+            )
+        finally:
+            self._cleanup()
+
+    def _setup_terminal(self):
+        """设置终端 raw mode"""
+        if sys.stdin.isatty():
+            self.old_settings = termios.tcgetattr(sys.stdin)
+            tty.setraw(sys.stdin.fileno())
+
+    def _restore_terminal(self):
+        """恢复终端设置"""
+        if self.old_settings:
+            termios.tcsetattr(sys.stdin, termios.TCSADRAIN, self.old_settings)
+
+    def _setup_signals(self):
+        """设置信号处理"""
+        signal.signal(signal.SIGWINCH, self._handle_resize)
+
+    def _handle_resize(self, signum, frame):
+        """处理终端大小变化"""
+        if self.running and self.writer:
+            rows, cols = get_terminal_size()
+            asyncio.create_task(self._send_resize(rows, cols))
+
+    async def _send_resize(self, rows: int, cols: int):
+        """发送终端大小"""
+        msg = ResizeMessage(rows, cols, self.client_id)
+        await self._send_message(msg)
+
+    async def _read_server(self):
+        """读取服务器消息"""
+        while self.running:
+            try:
+                msg = await asyncio.wait_for(self._read_message(), timeout=0.5)
+                if msg is None:
+                    self.running = False
+                    break
+                await self._handle_server_message(msg)
+            except asyncio.TimeoutError:
+                continue
+            except Exception:
+                break
+
+    async def _read_message(self) -> Optional[Message]:
+        """读取一条消息"""
+        while True:
+            if b"\n" in self.buffer:
+                line, self.buffer = self.buffer.split(b"\n", 1)
+                try:
+                    return decode_message(line)
+                except Exception:
+                    continue
+
+            try:
+                data = await self.reader.read(4096)
+                if not data:
+                    return None
+                self.buffer += data
+            except Exception:
+                return None
+
+    async def _handle_server_message(self, msg: Message):
+        """处理服务器消息"""
+        if msg.type == MessageType.OUTPUT:
+            data = msg.get_data()
+            sys.stdout.buffer.write(data)
+            sys.stdout.buffer.flush()
+
+        elif msg.type == MessageType.HISTORY:
+            data = msg.get_data()
+            sys.stdout.buffer.write(data)
+            sys.stdout.buffer.flush()
+
+    async def _read_stdin(self):
+        """读取标准输入"""
+        loop = asyncio.get_event_loop()
+
+        while self.running:
+            try:
+                # 在线程池中读取标准输入（带超时）
+                data = await loop.run_in_executor(None, self._read_stdin_sync)
+                if data:
+                    await self._handle_input(data)
+                    if not self.running:
+                        break
+            except Exception:
+                break
+
+    def _read_stdin_sync(self) -> bytes:
+        """同步读取标准输入（带超时，便于检查 running 状态）"""
+        # 使用 select 等待输入，超时 0.1 秒
+        rlist, _, _ = select.select([sys.stdin], [], [], 0.1)
+        if rlist:
+            return os.read(sys.stdin.fileno(), 1024)
+        return b""
+
+    async def _handle_input(self, data: bytes):
+        """处理输入"""
+        # Ctrl+D 退出
+        if data == CTRL_D:
+            self.running = False
+            return
+
+        # 其他按键都发送给 Claude
+        _track_stats('terminal', 'input', session_name=self.session_name,
+                     value=len(data))
+        await self._send_input(data)
+
+    async def _send_input(self, data: bytes):
+        """发送输入"""
+        msg = InputMessage(data, self.client_id)
+        await self._send_message(msg)
+
+    async def _send_message(self, msg: Message):
+        """发送消息"""
+        if self.writer:
+            try:
+                data = encode_message(msg)
+                self.writer.write(data)
+                await self.writer.drain()
+            except Exception:
+                pass
+
+    def _cleanup(self):
+        """清理"""
+        self.running = False
+        _track_stats('terminal', 'disconnect', session_name=self.session_name)
+        self._restore_terminal()
+
+        if self.writer:
+            try:
+                self.writer.close()
+            except Exception:
+                pass
+
+        print("\n已断开连接")
+
+
+def run_client(session_name: str):
+    """运行客户端"""
+    client = RemoteClient(session_name)
+
+    try:
+        asyncio.run(client.run())
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    import argparse
+    parser = argparse.ArgumentParser(description="Remote Claude Client")
+    parser.add_argument("session_name", help="会话名称")
+    args = parser.parse_args()
+
+    run_client(args.session_name)

package/lark_client/__init__.py

@@ -0,0 +1,3 @@
+"""
+Remote Claude 飞书客户端
+"""

package/lark_client/capture_output.py

@@ -0,0 +1,91 @@
+"""
+捕获 remote_claude 的实际输出用于分析
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from utils.protocol import Message, MessageType, decode_message
+from utils.session import get_socket_path
+
+
+async def capture_output(session_name: str, duration: int = 30):
+    """捕获会话输出"""
+    socket_path = get_socket_path(session_name)
+
+    if not socket_path.exists():
+        print(f"会话 {session_name} 不存在")
+        return
+
+    print(f"连接到 {session_name}...")
+
+    reader, writer = await asyncio.open_unix_connection(path=str(socket_path))
+
+    print(f"已连接，捕获 {duration} 秒的输出...")
+    print("=" * 60)
+
+    buffer = b""
+    outputs = []
+
+    async def read_messages():
+        nonlocal buffer
+        while True:
+            try:
+                data = await asyncio.wait_for(reader.read(4096), timeout=1.0)
+                if not data:
+                    break
+                buffer += data
+
+                while b"\n" in buffer:
+                    line, buffer = buffer.split(b"\n", 1)
+                    try:
+                        msg = decode_message(line)
+                        if msg.type == MessageType.OUTPUT:
+                            raw_data = msg.get_data()
+                            outputs.append(raw_data)
+                            print(f"收到 {len(raw_data)} 字节:")
+                            print(f"  原始: {raw_data[:100]}...")
+                            print(f"  解码: {raw_data.decode('utf-8', errors='replace')[:100]}...")
+                            print()
+                    except Exception as e:
+                        print(f"解析错误: {e}")
+            except asyncio.TimeoutError:
+                continue
+            except Exception as e:
+                print(f"读取错误: {e}")
+                break
+
+    try:
+        await asyncio.wait_for(read_messages(), timeout=duration)
+    except asyncio.TimeoutError:
+        pass
+
+    writer.close()
+    await writer.wait_closed()
+
+    print("=" * 60)
+    print(f"共收到 {len(outputs)} 条输出消息")
+
+    # 保存原始输出到文件
+    output_file = Path("/tmp/claude_raw_output.bin")
+    with open(output_file, "wb") as f:
+        for data in outputs:
+            f.write(data)
+            f.write(b"\n---\n")
+
+    print(f"原始输出已保存到 {output_file}")
+
+    # 合并并分析
+    all_data = b"".join(outputs)
+    print(f"\n合并后总长度: {len(all_data)} 字节")
+    print(f"合并后内容:\n{all_data.decode('utf-8', errors='replace')}")
+
+
+if __name__ == "__main__":
+    session = sys.argv[1] if len(sys.argv) > 1 else "test"
+    duration = int(sys.argv[2]) if len(sys.argv) > 2 else 30
+
+    asyncio.run(capture_output(session, duration))