remote_claude: Instructions file for Claude Code

CLAUDE.md/AGENTS.md

This file provides guidance to Claude-Code/Codex when working with code in this repository.

关键语言要求

你必须完全使用 简体中文 进行交互、思考和汇报。

项目概述

Remote Claude 是一个双端共享 Claude/Codex CLI 工具。通过 PTY + Unix Socket 架构，支持多个终端客户端和飞书客户端并发连接同一个 Claude 或 Codex 会话，实现协作式 AI 对话。

架构

Claude/Codex CLI (PTY)
      │
  server.py         ← PTY 代理，管理进程/控制权/历史缓存
      │
  Unix Socket (/tmp/remote-claude/<name>.sock)
      │
  ┌───┴────┐
  │        │
client.py  SessionBridge (lark_client/)
(终端)     (飞书机器人)

核心模块：

• remote_claude.py — CLI 入口，子命令：start / attach / list / kill / lark
• server/server.py — PTY 代理服务器，pty.fork() 启动 Claude/Codex，asyncio Unix Socket 广播输出
• server/parsers/claude_parser.py — Claude CLI 终端输出解析（区域切分、Block 分类、执行状态判断）
• server/parsers/codex_parser.py — Codex CLI 终端输出解析（无分割线、› 提示符、背景色区域检测）
• server/component_parser.py — 向后兼容 shim（实际实现在 server/parsers/）
• server/shared_state.py — 共享内存写入（.mq 文件）
• client/client.py — 终端客户端，raw mode 输入转发
• utils/protocol.py — 消息协议（JSON + \n 分隔，二进制数据 base64 编码）。7 种消息类型：INPUT / OUTPUT / CONTROL / STATUS / HISTORY / ERROR / RESIZE
• utils/session.py — socket 路径管理、会话生命周期
• utils/components.py — 控制权状态机，SHARED（默认，所有人可输入）和 EXCLUSIVE（独占）两种模式

飞书客户端 (lark_client/)：

• main.py — WebSocket 入口，事件分发
• lark_handler.py — 命令路由，以 chat_id 为 key 统一管理群聊/私聊的 bridge 和绑定
• session_bridge.py — 连接 Unix Socket，仅负责输入发送（send_input/send_key）和连接管理
• shared_memory_poller.py — 流式滚动卡片轮询器：每秒轮询 .mq 共享内存，通过 hash diff 驱动 CardSlice/StreamTracker 就地更新或冻结+开新卡
• card_builder.py — build_stream_card(blocks, status_line, bottom_bar, is_frozen, agent_panel, option_block, session_name, disconnected)：四层结构卡片构建（内容区/状态区/交互区/菜单）+ 辅助卡片（session_list/menu/help/dir 等）
• card_service.py — 飞书卡片 API 服务（create/update/send）
• rich_text_renderer.py — 持久化 pyte Screen 封装（server 端实时喂入）

Server 端数据流（全量快照架构）：

PTY data → self._renderer.feed(data) → HistoryScreen(220×100, history=5000) 持久化实时更新
                                            ↓ SU/SD 正确执行（ESC[nS/ESC[nT）
                                            ↓ 滚出行 → history.top（最多 5000 行）
                                            ↓（flush 触发）
                            （开启 --debug-screen）_write_screen_debug(原始 screen) → _screen.log
                                            ↓
                                    VirtualScreen(history.top + screen.buffer)
                                            ↓
                                    ScreenParser.parse(vscreen)
                                            ↓
                                    raw components 列表
                                            ↓
                                    分拣：visible_blocks / status_line / bottom_bar
                                            ↓
                                 ┌── 时序窗口平滑 ──┐
                                 │ _FrameObs 记录原始值 │
                                 │ 平滑 status_line     │
                                 │ 平滑 block blink     │
                                 └────────┬──────────┘
                                          ↓
                                    all_blocks = visible_blocks
                                          ↓
                                    ClaudeWindow 快照
                                          ↓
                                ├→ _messages.log (debug)
                                └→ .mq 共享内存 (全量覆写)