remote-claude 0.1.0

package/server/shared_state.py

@@ -0,0 +1,198 @@
+"""
+会话共享状态 (mmap) — 全量快照架构
+
+Server 进程将 ClaudeWindow 快照全量写入 mmap 文件，其他进程可通过
+SharedStateReader 随时读取最新快照。
+
+设计原则：
+- 每次 write_snapshot() 全量写入序列化后的 ClaudeWindow JSON
+- 读端一次 read() 获取完整快照，无需逐条拼装
+- 写入复杂度 O(blocks 总数)，但避免了增量状态污染问题
+
+内存布局（200MB mmap 文件）：
+  [Header      64B] @0       magic(4B) + version(4B) + snapshot_len(4B) + sequence(4B) + 保留
+  [Snapshot  ~200MB] @64     JSON 序列化的 ClaudeWindow 快照
+
+文件路径：/tmp/remote-claude/<name>.mq
+"""
+
+import json
+import mmap
+import struct
+from dataclasses import asdict
+from pathlib import Path
+from typing import Optional
+
+# ── 布局常量 ──────────────────────────────────────────────────────────────────
+MMAP_SIZE        = 200 * 1024 * 1024  # 200MB
+HEADER_SIZE      = 64
+
+HEADER_OFFSET    = 0
+COMPLETED_OFFSET = HEADER_SIZE  # @64，快照数据起始
+
+MAGIC   = b'RCMQ'
+VERSION = 2
+
+# Header 内字段偏移
+_H_MAGIC          = 0   # 4B
+_H_VERSION        = 4   # 4B uint32
+_H_SNAPSHOT_LEN   = 8   # 4B uint32 — 快照 JSON 长度
+_H_SEQUENCE       = 12  # 4B uint32 — 写入序列号（单调递增）
+# [16:64] 保留
+
+
+def get_mq_path(session_name: str) -> Path:
+    """获取会话的共享状态文件路径"""
+    from utils.session import get_mq_path as _get_mq_path
+    return _get_mq_path(session_name)
+
+
+def _component_to_dict(c) -> dict:
+    d = asdict(c)
+    d['_type'] = type(c).__name__
+    return d
+
+
+def _block_id_from_dict(d: dict) -> str:
+    """从已序列化的 component dict 计算 block_id（与 server._block_id 逻辑一致）"""
+    t = d.get('_type', '')
+    if t == 'UserInput':
+        return f"U:{d.get('text', '')[:80]}"
+    elif t == 'OutputBlock':
+        content = d.get('content', '')
+        first_line = content.split('\n', 1)[0].strip()[:80]
+        return f"O:{first_line}"
+    elif t == 'OptionBlock':
+        sub = d.get('sub_type', 'option')
+        if sub == 'permission':
+            return f"P:{d.get('question', '')[:80]}"
+        return f"Q:{d.get('question', '')[:80]}"
+    elif t == 'PermissionBlock':
+        # 向后兼容旧数据
+        return f"P:{d.get('question', '')[:80]}"
+    elif t == 'AgentPanelBlock':
+        pt = d.get('panel_type', '')
+        if pt == 'detail':
+            return f"AP:{d.get('agent_name', '')[:80]}"
+        elif pt == 'summary':
+            return f"AP:summary:{d.get('agent_count', 0)}"
+        return f"AP:list:{d.get('agent_count', 0)}"
+    elif t == 'PlanBlock':
+        return f"PL:{d.get('title', '')[:80]}"
+    return ""
+
+
+# ── Writer ────────────────────────────────────────────────────────────────────
+
+class SharedStateWriter:
+    """写端：Server 进程持有，生命周期与 ProxyServer 相同"""
+
+    def __init__(self, session_name: str):
+        self._path = get_mq_path(session_name)
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+
+        self._f = open(self._path, 'w+b')
+        self._f.truncate(MMAP_SIZE)
+        self._f.flush()
+        self._mm = mmap.mmap(self._f.fileno(), MMAP_SIZE)
+
+        # 写入 header 初始值（magic + version + 全零计数字段）
+        self._mm.seek(HEADER_OFFSET)
+        self._mm.write(MAGIC)
+        self._mm.write(struct.pack('>I', VERSION))
+        self._mm.write(b'\x00' * (HEADER_SIZE - 8))
+        self._mm.flush()
+
+        self._sequence = 0
+
+    def write_snapshot(self, window) -> None:
+        """全量写入 ClaudeWindow 快照"""
+        try:
+            blocks = []
+            for b in window.blocks:
+                d = _component_to_dict(b)
+                d['block_id'] = _block_id_from_dict(d)
+                blocks.append(d)
+            # agent_panel 序列化（状态型组件，独立于 blocks）
+            agent_panel_dict = None
+            if window.agent_panel:
+                agent_panel_dict = _component_to_dict(window.agent_panel)
+                agent_panel_dict['block_id'] = _block_id_from_dict(agent_panel_dict)
+
+            # option_block 序列化（状态型组件，独立于 blocks）
+            option_block_dict = None
+            if window.option_block:
+                option_block_dict = _component_to_dict(window.option_block)
+                option_block_dict['block_id'] = _block_id_from_dict(option_block_dict)
+
+            snapshot = {
+                "blocks": blocks,
+                "status_line": _component_to_dict(window.status_line) if window.status_line else None,
+                "bottom_bar": _component_to_dict(window.bottom_bar) if window.bottom_bar else None,
+                "agent_panel": agent_panel_dict,
+                "option_block": option_block_dict,
+                "input_area_text": window.input_area_text,
+                "timestamp": window.timestamp,
+                "layout_mode": window.layout_mode,
+            }
+            data = json.dumps(snapshot, ensure_ascii=False).encode('utf-8')
+
+            # 超出可用空间则跳过（理论上 200MB 足够）
+            if COMPLETED_OFFSET + len(data) > MMAP_SIZE:
+                return
+
+            self._sequence += 1
+            mm = self._mm
+            mm.seek(COMPLETED_OFFSET)
+            mm.write(data)
+
+            # 更新 header（snapshot_len + sequence）
+            mm.seek(HEADER_OFFSET + _H_SNAPSHOT_LEN)
+            mm.write(struct.pack('>II', len(data), self._sequence))
+            mm.flush()
+        except Exception:
+            pass
+
+    def close(self):
+        try:
+            self._mm.close()
+            self._f.close()
+            self._path.unlink(missing_ok=True)
+        except Exception:
+            pass
+
+
+# ── Reader ────────────────────────────────────────────────────────────────────
+
+class SharedStateReader:
+    """读端：其他进程持有，按需调用 read() 获取最新快照。
+
+    使用直接文件 I/O 而非 mmap，避免 macOS 上 mmap ACCESS_READ 不可靠地
+    反映跨进程写入更新的问题。每次 read() 打开文件读取后关闭，保证读到最新数据。
+    """
+
+    _EMPTY = {"blocks": [], "status_line": None, "bottom_bar": None, "option_block": None}
+
+    def __init__(self, session_name: str):
+        self._path = get_mq_path(session_name)
+
+    def read(self) -> dict:
+        """读取当前完整快照，返回 dict"""
+        try:
+            with open(self._path, 'rb') as f:
+                header = f.read(16)
+                if len(header) < 16 or header[:4] != MAGIC:
+                    return self._EMPTY
+                version = struct.unpack('>I', header[4:8])[0]
+                if version < 2:
+                    return self._EMPTY
+                snapshot_len, _sequence = struct.unpack('>II', header[8:16])
+                if snapshot_len == 0:
+                    return self._EMPTY
+                f.seek(COMPLETED_OFFSET)
+                return json.loads(f.read(snapshot_len).decode('utf-8'))
+        except Exception:
+            return self._EMPTY
+
+    def close(self):
+        pass  # 无持久资源需要释放

package/stats/__init__.py

@@ -0,0 +1,38 @@
+"""
+Remote Claude 使用统计模块
+
+全局接口：
+  track(category, event, **kwargs)   —— 记录事件
+  close()                            —— 关闭前刷新
+"""
+
+_ENABLED = True
+_MIXPANEL_TOKEN = 'c4d804fc1fe4337132e4da90fdb690c9'
+
+from .collector import StatsCollector
+
+_collector = StatsCollector(enabled=_ENABLED)
+# 模块加载时自动初始化 Mixpanel（无需外部配置）
+_collector.set_mixpanel_token(_MIXPANEL_TOKEN)
+_collector.report_install()
+
+
+def track(category: str, event: str, **kwargs) -> None:
+    """记录事件（非阻塞，线程安全，异常不传播）"""
+    _collector.track(category, event, **kwargs)
+
+
+def init_mixpanel(token: str) -> None:
+    """配置 Mixpanel token（保留接口兼容性，通常无需手动调用）"""
+    _collector.set_mixpanel_token(token)
+    _collector.report_install()
+
+
+def report_daily(date: str = None) -> None:
+    """手动触发聚合上报（CLI --report 命令使用）"""
+    _collector.report_daily(date)
+
+
+def close() -> None:
+    """关闭前刷新队列"""
+    _collector.close()

package/stats/collector.py

@@ -0,0 +1,325 @@
+"""
+StatsCollector：事件收集器
+
+- 内存队列（deque）接收 track() 调用（O(1)，无 I/O）
+- 每 10 秒或满 50 条时批量写入 SQLite（WAL 模式）
+- 每日聚合上报 Mixpanel（~22 条/天）
+- 所有异常均被捕获，绝不影响主流程
+"""
+
+import os
+import sqlite3
+import threading
+import time
+from collections import deque
+from pathlib import Path
+from typing import Optional
+
+from .machine import get_machine_id, get_machine_info
+
+# SQLite 数据库路径（持久化，不受 /tmp 清理影响）
+_DB_DIR = Path.home() / ".local" / "share" / "remote-claude"
+_DB_PATH = _DB_DIR / "stats.db"
+
+# 批量写入阈值
+_FLUSH_INTERVAL = 10.0   # 秒
+_FLUSH_BATCH = 50        # 条
+
+# 数据保留天数
+_EVENTS_RETENTION = 90   # 天
+_SUMMARY_RETENTION = 365 # 天
+
+
+class StatsCollector:
+    """事件收集器：内存队列 + SQLite 批量写入 + 定时 Mixpanel 聚合上报"""
+
+    def __init__(self, enabled: bool = True):
+        self._enabled = enabled
+        self._queue: deque = deque(maxlen=10000)
+        self._lock = threading.Lock()
+        self._machine_id = get_machine_id()
+        self._conn: Optional[sqlite3.Connection] = None
+        self._mp = None              # Mixpanel 实例，延迟初始化
+        self._mp_token: str = ""
+        self._last_flush = 0.0
+        self._last_report_date: str = ""
+        self._is_first_run = False   # 是否首次运行（需上报 install 事件）
+
+        if self._enabled:
+            self._init_db()
+            self._check_first_run()
+            # 后台线程定时 flush
+            t = threading.Thread(target=self._flush_loop, daemon=True)
+            t.start()
+
+    # ── 公开接口 ──────────────────────────────────────────────────────────────
+
+    def track(self, category: str, event: str, session_name: str = '',
+              chat_id: str = '', value: int = 1, detail: str = '') -> None:
+        """记录事件到本地（非阻塞，线程安全）"""
+        if not self._enabled:
+            return
+        try:
+            now = time.time()
+            date = time.strftime('%Y-%m-%d', time.localtime(now))
+            # chat_id 脱敏：只保留前 8 位
+            safe_chat_id = chat_id[:8] if chat_id else ''
+            row = (now, date, category, event, session_name,
+                   safe_chat_id, value, detail, self._machine_id)
+            with self._lock:
+                self._queue.append(row)
+                should_flush = len(self._queue) >= _FLUSH_BATCH
+            if should_flush:
+                threading.Thread(target=self._flush, daemon=True).start()
+        except Exception:
+            pass
+
+    def set_mixpanel_token(self, token: str) -> None:
+        """配置 Mixpanel token（来自 .env）"""
+        if not token:
+            return
+        self._mp_token = token
+        try:
+            import mixpanel
+            self._mp = mixpanel.Mixpanel(token)
+        except ImportError:
+            pass  # mixpanel 未安装时静默跳过
+
+    def check_and_report(self) -> None:
+        """检查是否需要上报昨日数据（跨天检测，可在后台调用）"""
+        if not self._enabled or not self._mp:
+            return
+        try:
+            today = time.strftime('%Y-%m-%d')
+            if self._last_report_date == today:
+                return
+            yesterday = time.strftime('%Y-%m-%d',
+                                      time.localtime(time.time() - 86400))
+            self.report_daily(yesterday)
+            self._last_report_date = today
+        except Exception:
+            pass
+
+    def report_daily(self, date: Optional[str] = None) -> None:
+        """聚合指定日期数据并上报 Mixpanel（默认昨天）"""
+        if not self._enabled or not self._mp:
+            return
+        try:
+            if date is None:
+                date = time.strftime('%Y-%m-%d',
+                                     time.localtime(time.time() - 86400))
+            self._flush()  # 先把队列里的数据落库
+
+            conn = self._get_conn()
+            rows = conn.execute(
+                "SELECT category, event, COUNT(*), SUM(value) "
+                "FROM events WHERE date=? GROUP BY category, event",
+                (date,)
+            ).fetchall()
+
+            if not rows:
+                return
+
+            machine_info = get_machine_info()
+            for category, event, count, total_value in rows:
+                self._mp_track('daily_summary', {
+                    'category': category,
+                    'event': event,
+                    'count': count,
+                    'total_value': total_value,
+                    'date': date,
+                    **machine_info,
+                })
+
+            # 上报 heartbeat
+            active_sessions = self._count_active_sessions(date, conn)
+            self._mp_track('heartbeat', {
+                'date': date,
+                'active_sessions': active_sessions,
+                **machine_info,
+            })
+
+            # 写入 daily_summary 表（本地留存）
+            for category, event, count, total_value in rows:
+                conn.execute(
+                    "INSERT OR REPLACE INTO daily_summary "
+                    "(date, category, event, count, total_value) "
+                    "VALUES (?, ?, ?, ?, ?)",
+                    (date, category, event, count, total_value)
+                )
+            conn.commit()
+
+        except Exception:
+            pass
+
+    def close(self) -> None:
+        """关闭前刷新队列"""
+        if self._enabled:
+            try:
+                self._flush()
+            except Exception:
+                pass
+
+    # ── 内部方法 ──────────────────────────────────────────────────────────────
+
+    def _init_db(self) -> None:
+        """初始化 SQLite 数据库"""
+        try:
+            _DB_DIR.mkdir(parents=True, exist_ok=True)
+            conn = self._get_conn()
+            conn.executescript("""
+                PRAGMA journal_mode=WAL;
+                PRAGMA synchronous=NORMAL;
+
+                CREATE TABLE IF NOT EXISTS events (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    timestamp REAL NOT NULL,
+                    date TEXT NOT NULL,
+                    category TEXT NOT NULL,
+                    event TEXT NOT NULL,
+                    session_name TEXT DEFAULT '',
+                    chat_id TEXT DEFAULT '',
+                    value INTEGER DEFAULT 1,
+                    detail TEXT DEFAULT '',
+                    machine_id TEXT NOT NULL
+                );
+
+                CREATE TABLE IF NOT EXISTS daily_summary (
+                    date TEXT,
+                    category TEXT,
+                    event TEXT,
+                    count INTEGER,
+                    total_value INTEGER,
+                    PRIMARY KEY (date, category, event)
+                );
+
+                CREATE TABLE IF NOT EXISTS meta (
+                    key TEXT PRIMARY KEY,
+                    value TEXT
+                );
+
+                CREATE INDEX IF NOT EXISTS idx_events_date
+                    ON events(date);
+                CREATE INDEX IF NOT EXISTS idx_events_category
+                    ON events(category, event);
+            """)
+            conn.commit()
+            # 清理过期数据
+            self._cleanup_old_data(conn)
+        except Exception:
+            pass
+
+    def _check_first_run(self) -> None:
+        """检查是否首次运行"""
+        try:
+            conn = self._get_conn()
+            row = conn.execute(
+                "SELECT value FROM meta WHERE key='first_run'"
+            ).fetchone()
+            if row is None:
+                self._is_first_run = True
+                conn.execute(
+                    "INSERT INTO meta (key, value) VALUES ('first_run', ?)",
+                    (time.strftime('%Y-%m-%d'),)
+                )
+                conn.commit()
+        except Exception:
+            pass
+
+    def _get_conn(self) -> sqlite3.Connection:
+        """获取 SQLite 连接（线程本地）"""
+        if self._conn is None:
+            self._conn = sqlite3.connect(str(_DB_PATH), check_same_thread=False)
+        return self._conn
+
+    def _flush(self) -> None:
+        """批量写入 SQLite"""
+        with self._lock:
+            if not self._queue:
+                return
+            rows = list(self._queue)
+            self._queue.clear()
+
+        try:
+            conn = self._get_conn()
+            conn.executemany(
+                "INSERT INTO events "
+                "(timestamp, date, category, event, session_name, "
+                "chat_id, value, detail, machine_id) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                rows
+            )
+            conn.commit()
+            self._last_flush = time.time()
+        except Exception:
+            # 写失败，把数据放回队列头部（尽力保留）
+            with self._lock:
+                for row in reversed(rows):
+                    self._queue.appendleft(row)
+
+    def _flush_loop(self) -> None:
+        """后台定时 flush 线程"""
+        while True:
+            try:
+                time.sleep(10)
+                elapsed = time.time() - self._last_flush
+                with self._lock:
+                    has_data = bool(self._queue)
+                if has_data and elapsed >= _FLUSH_INTERVAL:
+                    self._flush()
+                self.check_and_report()
+            except Exception:
+                pass
+
+    def _cleanup_old_data(self, conn: sqlite3.Connection) -> None:
+        """清理过期数据"""
+        try:
+            conn.execute(
+                "DELETE FROM events WHERE date < date('now', ?)",
+                (f"-{_EVENTS_RETENTION} days",)
+            )
+            conn.execute(
+                "DELETE FROM daily_summary WHERE date < date('now', ?)",
+                (f"-{_SUMMARY_RETENTION} days",)
+            )
+            conn.commit()
+        except Exception:
+            pass
+
+    def _mp_track(self, event_name: str, properties: dict) -> None:
+        """上报单条 Mixpanel 事件"""
+        if not self._mp:
+            return
+        try:
+            self._mp.track(self._machine_id, event_name, properties)
+        except Exception:
+            pass
+
+    def _count_active_sessions(self, date: str,
+                               conn: sqlite3.Connection) -> int:
+        """统计指定日期有 start 事件的会话数"""
+        try:
+            row = conn.execute(
+                "SELECT COUNT(DISTINCT session_name) FROM events "
+                "WHERE date=? AND category='session' AND event='start'",
+                (date,)
+            ).fetchone()
+            return row[0] if row else 0
+        except Exception:
+            return 0
+
+    def report_install(self) -> None:
+        """首次运行时上报 install 事件和 user profile"""
+        if not self._mp or not self._is_first_run:
+            return
+        try:
+            machine_info = get_machine_info()
+            import datetime
+            self._mp.people_set(self._machine_id, {
+                '$name': machine_info['hostname'],
+                **machine_info,
+                'first_seen': datetime.datetime.now().isoformat(),
+            })
+            self._mp_track('install', machine_info)
+        except Exception:
+            pass

package/stats/machine.py

@@ -0,0 +1,47 @@
+"""
+机器标识模块
+
+持久化 UUID（~/.remote-claude-id），用于 Mixpanel distinct_id 和跨机器去重。
+"""
+
+import os
+import platform
+import uuid
+from pathlib import Path
+
+
+_ID_FILE = Path.home() / ".remote-claude-id"
+_machine_id: str | None = None
+
+
+def get_machine_id() -> str:
+    """获取（或生成）机器 UUID，持久化到 ~/.remote-claude-id"""
+    global _machine_id
+    if _machine_id:
+        return _machine_id
+
+    if _ID_FILE.exists():
+        try:
+            _machine_id = _ID_FILE.read_text().strip()
+            if _machine_id:
+                return _machine_id
+        except Exception:
+            pass
+
+    # 首次生成
+    _machine_id = str(uuid.uuid4())
+    try:
+        _ID_FILE.write_text(_machine_id)
+    except Exception:
+        pass  # 写失败也继续，只是无法持久化
+
+    return _machine_id
+
+
+def get_machine_info() -> dict:
+    """获取机器基础信息（用于 Mixpanel user profile）"""
+    return {
+        "hostname": platform.node(),
+        "os": f"{platform.system()} {platform.release()}",
+        "python": platform.python_version(),
+    }