remote-claude 1.0.3 → 1.0.5

package/lark_client/shared_memory_poller.py

@@ -202,8 +202,8 @@ class SharedMemoryPoller:
                 logger.error(f"_poll_once 异常: {e}", exc_info=True)
 
     async def _poll_once(self, tracker: StreamTracker) -> None:
-        """单次轮询：读取共享内存 → diff → 创建/更新卡片"""
-        # 延迟初始化 Reader
+        """单次轮询：读取共享内存 → diff → 创建/更新卡片 → 就绪通知"""
+        # 步骤 1：延迟初始化 Reader
         if tracker.reader is None:
             try:
                 from shared_state import get_mq_path, SharedStateReader
@@ -230,94 +230,114 @@ class SharedMemoryPoller:
         agent_panel = state.get("agent_panel")
         option_block = state.get("option_block")
         cli_type = state.get("cli_type", "claude")
+        # timestamp 存在说明 server 已写入有效快照（即使内容全空，如 Codex 就绪等待输入）
+        has_valid_snapshot = state.get("timestamp") is not None
 
-        # 就绪状态转换检测
-        await self._check_ready_notification(tracker, blocks, status_line, option_block, cli_type)
+        # 步骤 2：仅计算就绪状态，不发送通知
+        should_notify = self._update_ready_state(tracker, blocks, status_line, option_block, agent_panel)
 
+        # 步骤 3：卡片操作（含创建/更新/拆分）
+        await self._do_card_update(tracker, blocks, status_line, bottom_bar, agent_panel, option_block, cli_type, has_valid_snapshot=has_valid_snapshot)
+
+        # 步骤 4：通知在卡片操作之后发送，确保新卡先出现
+        if should_notify:
+            await self._send_ready_notification(tracker, cli_type)
+
+    async def _do_card_update(
+        self, tracker: StreamTracker, blocks: List[dict],
+        status_line: Optional[dict], bottom_bar: Optional[dict],
+        agent_panel: Optional[dict], option_block: Optional[dict],
+        cli_type: str,
+        has_valid_snapshot: bool = False,
+    ) -> None:
+        """卡片操作主体：获取活跃卡片 → 创建/更新/拆分"""
         # 获取活跃卡片（最后一张且未冻结）
         active = None
         if tracker.cards and not tracker.cards[-1].frozen:
             active = tracker.cards[-1]
 
         if not blocks and not status_line and not bottom_bar and not agent_panel and not option_block and active is None:
-            return  # 完全无内容且无活跃卡片时不创建卡片
+            if not has_valid_snapshot:
+                return  # 真的还没有快照，不创建卡片
+            # 有效快照但内容全空（如 Codex 就绪等待输入），继续创建就绪卡片
 
         if active is None:
             # 需要创建新卡片
             await self._create_new_card(tracker, blocks, status_line, bottom_bar, agent_panel, option_block, cli_type=cli_type)
-        else:
-            # 有活跃卡片，检查是否需要更新
-            blocks_slice = blocks[active.start_idx:]
+            return
 
-            # blocks 骤降检测（compact/重启导致 blocks 从头累积）
-            if len(blocks) < active.start_idx:
-                logger.warning(
-                    f"[blocks regression] len(blocks)={len(blocks)} < start_idx={active.start_idx}, "
-                    f"resetting start_idx to 0 (session={tracker.session_name})"
-                )
-                active.start_idx = 0
-                blocks_slice = blocks[0:]
-                tracker.content_hash = ""  # 强制刷新
+        # 有活跃卡片，检查是否需要更新
+        blocks_slice = blocks[active.start_idx:]
 
-            # 超限检查
-            if len(blocks_slice) > MAX_CARD_BLOCKS:
-                await self._freeze_and_split(tracker, blocks, status_line, bottom_bar, agent_panel, option_block, cli_type=cli_type)
-                return
+        # blocks 骤降检测（compact/重启导致 blocks 从头累积）
+        if len(blocks) < active.start_idx:
+            logger.warning(
+                f"[blocks regression] len(blocks)={len(blocks)} < start_idx={active.start_idx}, "
+                f"resetting start_idx to 0 (session={tracker.session_name})"
+            )
+            active.start_idx = 0
+            blocks_slice = blocks[0:]
+            tracker.content_hash = ""  # 强制刷新
 
-            # hash diff
-            new_hash = self._compute_hash(blocks_slice, status_line, bottom_bar, agent_panel, option_block)
-            if new_hash == tracker.content_hash:
-                return  # 无变化
+        # 超限检查
+        if len(blocks_slice) > MAX_CARD_BLOCKS:
+            await self._freeze_and_split(tracker, blocks, status_line, bottom_bar, agent_panel, option_block, cli_type=cli_type)
+            return
 
-            # 更新卡片
-            from .card_builder import build_stream_card
-            card_dict = build_stream_card(blocks_slice, status_line, bottom_bar, agent_panel=agent_panel, option_block=option_block, session_name=tracker.session_name, cli_type=cli_type)
+        # hash diff
+        new_hash = self._compute_hash(blocks_slice, status_line, bottom_bar, agent_panel, option_block)
+        if new_hash == tracker.content_hash:
+            return  # 无变化
 
-            # 大小超限检查（与 blocks 数量超限同一套逻辑）
-            card_size = len(json.dumps(card_dict, ensure_ascii=False).encode('utf-8'))
-            if card_size > CARD_SIZE_LIMIT:
-                freeze_count = self._find_freeze_count(blocks_slice, tracker.session_name)
-                await self._freeze_and_split(
-                    tracker, blocks, status_line, bottom_bar, agent_panel, option_block,
-                    cli_type=cli_type, freeze_count=freeze_count,
-                )
-                return
+        # 更新卡片
+        from .card_builder import build_stream_card
+        card_dict = build_stream_card(blocks_slice, status_line, bottom_bar, agent_panel=agent_panel, option_block=option_block, session_name=tracker.session_name, cli_type=cli_type)
 
-            active.sequence += 1
-            success = await self._card_service.update_card(
-                card_id=active.card_id,
-                sequence=active.sequence,
-                card_content=card_dict,
+        # 大小超限检查（与 blocks 数量超限同一套逻辑）
+        card_size = len(json.dumps(card_dict, ensure_ascii=False).encode('utf-8'))
+        if card_size > CARD_SIZE_LIMIT:
+            freeze_count = self._find_freeze_count(blocks_slice, tracker.session_name)
+            await self._freeze_and_split(
+                tracker, blocks, status_line, bottom_bar, agent_panel, option_block,
+                cli_type=cli_type, freeze_count=freeze_count,
             )
+            return
 
-            if getattr(success, 'is_element_limit', False):
-                # 元素超限：冻结旧卡 + 推新流式卡
-                await self._handle_element_limit(
-                    tracker, blocks, status_line, bottom_bar, agent_panel, option_block,
-                    cli_type=cli_type,
-                )
-                return
-            elif not success:
-                # 降级：创建新卡片替代
-                logger.warning(
-                    f"update_card 失败 card_id={active.card_id} seq={active.sequence}，降级为新卡片"
-                )
-                _track_stats('card', 'fallback', session_name=tracker.session_name,
-                             chat_id=tracker.chat_id)
-                new_card_id = await self._card_service.create_card(card_dict)
-                if new_card_id:
-                    await self._card_service.send_card(tracker.chat_id, new_card_id)
-                    active.card_id = new_card_id
-                    active.sequence = 0
-            else:
-                _track_stats('card', 'update', session_name=tracker.session_name,
-                             chat_id=tracker.chat_id)
+        active.sequence += 1
+        success = await self._card_service.update_card(
+            card_id=active.card_id,
+            sequence=active.sequence,
+            card_content=card_dict,
+        )
 
-            tracker.content_hash = new_hash
-            logger.debug(
-                f"[UPDATE] session={tracker.session_name} blocks={len(blocks_slice)} "
-                f"seq={active.sequence} hash={new_hash[:8]}"
+        if getattr(success, 'is_element_limit', False):
+            # 元素超限：冻结旧卡 + 推新流式卡
+            await self._handle_element_limit(
+                tracker, blocks, status_line, bottom_bar, agent_panel, option_block,
+                cli_type=cli_type,
+            )
+            return
+        elif not success:
+            # 降级：创建新卡片替代
+            logger.warning(
+                f"update_card 失败 card_id={active.card_id} seq={active.sequence}，降级为新卡片"
             )
+            _track_stats('card', 'fallback', session_name=tracker.session_name,
+                         chat_id=tracker.chat_id)
+            new_card_id = await self._card_service.create_card(card_dict)
+            if new_card_id:
+                await self._card_service.send_card(tracker.chat_id, new_card_id)
+                active.card_id = new_card_id
+                active.sequence = 0
+        else:
+            _track_stats('card', 'update', session_name=tracker.session_name,
+                         chat_id=tracker.chat_id)
+
+        tracker.content_hash = new_hash
+        logger.debug(
+            f"[UPDATE] session={tracker.session_name} blocks={len(blocks_slice)} "
+            f"seq={active.sequence} hash={new_hash[:8]}"
+        )
 
     async def _create_new_card(
         self, tracker: StreamTracker, blocks: List[dict],
@@ -342,8 +362,8 @@ class SharedMemoryPoller:
                 )
 
         blocks_slice = blocks[start_idx:]
-        if not blocks_slice and not status_line and not bottom_bar and not agent_panel and not option_block:
-            return
+        # 注意：不在此处提前 return，上层 _do_card_update 已做过滤，
+        # 走到这里说明确实需要创建卡片（如 Codex 就绪等待输入的空内容卡片）
 
         from .card_builder import build_stream_card
         card_dict = build_stream_card(blocks_slice, status_line, bottom_bar, agent_panel=agent_panel, option_block=option_block, session_name=tracker.session_name, cli_type=cli_type)
@@ -487,53 +507,57 @@ class SharedMemoryPoller:
             )
             tracker.last_notify_message_id = None
 
-    async def _check_ready_notification(
+    def _update_ready_state(
         self, tracker: StreamTracker,
         blocks: list, status_line: Optional[dict], option_block: Optional[dict],
-        cli_type: str = "claude"
-    ) -> None:
-        """检测就绪状态转换（忙碌→就绪），群聊中发送 @所有人 提醒"""
-        current_ready = _is_ready(blocks, status_line, option_block)
+        agent_panel: Optional[dict] = None,
+    ) -> bool:
+        """更新就绪状态，返回是否需要发送就绪通知（不执行发送）"""
+        current_ready = _is_ready(blocks, status_line, option_block, agent_panel)
         prev_ready = tracker.prev_is_ready
         tracker.prev_is_ready = current_ready
+        return current_ready and not prev_ready and tracker.is_group and _notify_enabled
 
-        if current_ready and not prev_ready and tracker.is_group and _notify_enabled:
-            count = _increment_ready_count()
-            uid = tracker.notify_user_id or "all"
-            cli_name = "Claude" if cli_type == "claude" else "Codex"
-            logger.info(f"就绪提醒: chat_id={tracker.chat_id[:8]}..., count={count}, uid={uid}, "
-                        f"last_msg={'有' if tracker.last_notify_message_id else '无'}")
-
-            if tracker.last_notify_message_id and uid != "all" and _urgent_enabled:
-                # 已有通知消息 + 加急开关开启 → 尝试加急
-                try:
-                    ok = await self._card_service.send_urgent_app(
-                        tracker.last_notify_message_id, [uid]
-                    )
-                    if ok:
-                        # 加急成功 → 15 秒后自动取消
-                        asyncio.create_task(self._cancel_urgent_later(
-                            tracker.last_notify_message_id, [uid], delay=5
-                        ))
-                    else:
-                        # 加急失败（权限未开通等）→ 降级发新消息
-                        label = ""
-                        text = f'<at user_id="{uid}">{label}</at> {cli_name} 已就绪，等待您的输入...（这是第{count}次通知）'
-                        msg_id = await self._card_service.send_text(tracker.chat_id, text)
-                        if msg_id:
-                            tracker.last_notify_message_id = msg_id
-                except Exception as e:
-                    logger.warning(f"加急通知失败: {e}")
-            else:
-                # 首次通知（或无法加急时）→ 发新消息，记录 message_id
-                label = "所有人" if uid == "all" else ""
-                text = f'<at user_id="{uid}">{label}</at> {cli_name} 已就绪，等待您的输入...（这是第{count}次通知）'
-                try:
+    async def _send_ready_notification(
+        self, tracker: StreamTracker, cli_type: str = "claude"
+    ) -> None:
+        """发送就绪通知（加急或新消息），应在卡片操作完成后调用"""
+        count = _increment_ready_count()
+        uid = tracker.notify_user_id or "all"
+        cli_name = "Claude" if cli_type == "claude" else "Codex"
+        logger.info(f"就绪提醒: chat_id={tracker.chat_id[:8]}..., count={count}, uid={uid}, "
+                    f"last_msg={'有' if tracker.last_notify_message_id else '无'}")
+
+        if tracker.last_notify_message_id and uid != "all" and _urgent_enabled:
+            # 已有通知消息 + 加急开关开启 → 尝试加急
+            try:
+                ok = await self._card_service.send_urgent_app(
+                    tracker.last_notify_message_id, [uid]
+                )
+                if ok:
+                    # 加急成功 → 5 秒后自动取消
+                    asyncio.create_task(self._cancel_urgent_later(
+                        tracker.last_notify_message_id, [uid], delay=5
+                    ))
+                else:
+                    # 加急失败（权限未开通等）→ 降级发新消息
+                    label = ""
+                    text = f'<at user_id="{uid}">{label}</at> {cli_name} 已就绪，等待您的输入...（这是第{count}次通知）'
                     msg_id = await self._card_service.send_text(tracker.chat_id, text)
                     if msg_id:
                         tracker.last_notify_message_id = msg_id
-                except Exception as e:
-                    logger.warning(f"就绪提醒发送失败: {e}")
+            except Exception as e:
+                logger.warning(f"加急通知失败: {e}")
+        else:
+            # 首次通知（或无法加急时）→ 发新消息，记录 message_id
+            label = "所有人" if uid == "all" else ""
+            text = f'<at user_id="{uid}">{label}</at> {cli_name} 已就绪，等待您的输入...（这是第{count}次通知）'
+            try:
+                msg_id = await self._card_service.send_text(tracker.chat_id, text)
+                if msg_id:
+                    tracker.last_notify_message_id = msg_id
+            except Exception as e:
+                logger.warning(f"就绪提醒发送失败: {e}")
 
     async def _cancel_urgent_later(self, message_id: str, user_ids: list, delay: float = 15) -> None:
         """延迟取消加急通知"""
@@ -597,10 +621,11 @@ class SharedMemoryPoller:
 
 # ── 模块级辅助函数 ────────────────────────────────────────────────────────────
 
-def _is_ready(blocks: list, status_line: Optional[dict], option_block: Optional[dict]) -> bool:
-    """数据层就绪判断：无 streaming block、无 status_line（option_block 不影响就绪）"""
+def _is_ready(blocks: list, status_line: Optional[dict], option_block: Optional[dict], agent_panel: Optional[dict] = None) -> bool:
+    """数据层就绪判断：无 streaming block、无 status_line、无后台 agent（option_block 不影响就绪）"""
     has_streaming = any(b.get("is_streaming", False) for b in blocks)
-    return not has_streaming and status_line is None
+    has_agents = agent_panel is not None
+    return not has_streaming and status_line is None and not has_agents
 
 
 _READY_COUNT_FILE = USER_DATA_DIR / "ready_notify_count"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remote-claude",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "双端共享 Claude CLI 工具",
   "bin": {
     "remote-claude": "bin/remote-claude",

package/remote_claude.py

@@ -252,6 +252,44 @@ def cmd_status(args):
     return 0
 
 
+WATCHDOG_SCRIPT = USER_DATA_DIR / "watchdog.sh"
+WATCHDOG_PID_FILE = USER_DATA_DIR / "watchdog.pid"
+
+
+def _start_watchdog():
+    """启动后台 watchdog（如果尚未运行）"""
+    if not WATCHDOG_SCRIPT.exists():
+        return  # 脚本不存在时静默跳过
+    # 检查是否已在运行
+    if WATCHDOG_PID_FILE.exists():
+        try:
+            pid = int(WATCHDOG_PID_FILE.read_text().strip())
+            os.kill(pid, 0)
+            return  # 已在运行
+        except (ProcessLookupError, ValueError, OSError):
+            pass
+    process = subprocess.Popen(
+        ["bash", str(WATCHDOG_SCRIPT)],
+        stdout=subprocess.DEVNULL,  # watchdog 通过 tee 自己写 $LOG，不需要 stdout 捕获
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+    print(f"  watchdog: 已启动 (PID: {process.pid})")
+
+
+def _stop_watchdog():
+    """停止后台 watchdog"""
+    if not WATCHDOG_PID_FILE.exists():
+        return
+    try:
+        pid = int(WATCHDOG_PID_FILE.read_text().strip())
+        os.kill(pid, signal.SIGTERM)
+        print(f"  watchdog: 已停止 (PID: {pid})")
+    except (ProcessLookupError, ValueError, OSError):
+        pass
+    WATCHDOG_PID_FILE.unlink(missing_ok=True)
+
+
 def cmd_lark_start(args):
     """启动飞书客户端（守护进程）"""
     if is_lark_running():
@@ -296,6 +334,7 @@ def cmd_lark_start(args):
             print(f"  日志: {log_file}")
             print(f"\n使用 'python3 remote_claude.py lark status' 查看状态")
             print(f"使用 'python3 remote_claude.py lark stop' 停止")
+            _start_watchdog()
             return 0
         else:
             print("✗ 启动失败，请查看日志:")
@@ -342,6 +381,7 @@ def cmd_lark_stop(args):
         if not is_lark_running():
             print("✓ 飞书客户端已停止")
             cleanup_lark()
+            _stop_watchdog()
             return 0
         else:
             print("✗ 无法停止进程，请手动终止:")
@@ -351,6 +391,7 @@ def cmd_lark_stop(args):
     except ProcessLookupError:
         print("进程已不存在，清理残留文件")
         cleanup_lark()
+        _stop_watchdog()
         return 0
     except Exception as e:
         print(f"✗ 停止失败: {e}")
@@ -477,6 +518,198 @@ def cmd_update(args):
     return 0
 
 
+def cmd_deps(args):
+    """检查并安装依赖"""
+    import shutil
+
+    YELLOW = "\033[33m"
+    GREEN = "\033[32m"
+    RED = "\033[31m"
+    RESET = "\033[0m"
+
+    def print_ok(msg):
+        print(f"{GREEN}✓{RESET} {msg}")
+
+    def print_warn(msg):
+        print(f"{YELLOW}⚠{RESET} {msg}")
+
+    def print_err(msg):
+        print(f"{RED}✗{RESET} {msg}")
+
+    print(f"\n{GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━{RESET}")
+    print(f"{GREEN}  依赖检查{RESET}")
+    print(f"{GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━{RESET}\n")
+
+    # 检查 uv
+    uv_path = shutil.which("uv")
+    if uv_path:
+        r = subprocess.run(["uv", "--version"], capture_output=True, text=True)
+        print_ok(f"uv: {r.stdout.strip()}")
+    else:
+        print_err("uv: 未安装")
+
+    # 检查 claude CLI
+    claude_path = shutil.which("claude")
+    if claude_path:
+        print_ok("Claude CLI: 已安装")
+    else:
+        print_warn("Claude CLI: 未安装")
+
+    # 检查 codex CLI
+    codex_path = shutil.which("codex")
+    if codex_path:
+        print_ok("Codex CLI: 已安装")
+    else:
+        print_warn("Codex CLI: 未安装（可选）")
+
+    # 检查 tmux
+    REQUIRED_MAJOR = 3
+    REQUIRED_MINOR = 6
+
+    tmux_path = shutil.which("tmux")
+    tmux_ok = False
+    if tmux_path:
+        r = subprocess.run(["tmux", "-V"], capture_output=True, text=True)
+        ver_str = r.stdout.strip().split()[-1] if r.stdout.strip() else "0.0"
+        parts = ver_str.replace("a", "").replace("b", "").replace("c", "").split(".")
+        try:
+            major = int(parts[0])
+            minor = int(parts[1]) if len(parts) > 1 else 0
+        except ValueError:
+            major, minor = 0, 0
+        if major > REQUIRED_MAJOR or (major == REQUIRED_MAJOR and minor >= REQUIRED_MINOR):
+            print_ok(f"tmux: {r.stdout.strip()}（满足 >= {REQUIRED_MAJOR}.{REQUIRED_MINOR}）")
+            tmux_ok = True
+        else:
+            print_warn(f"tmux: {r.stdout.strip()}（需要 >= {REQUIRED_MAJOR}.{REQUIRED_MINOR}）")
+    else:
+        print_err("tmux: 未安装")
+
+    if tmux_ok:
+        print(f"\n{GREEN}所有关键依赖已满足。{RESET}")
+        return 0
+
+    # tmux 版本不满足，提供源码编译安装
+    print(f"\n{YELLOW}tmux 版本不满足要求，是否从源码编译安装 tmux 3.6a？{RESET}")
+    print(f"  安装位置: $HOME/.local（不需要 root 权限）")
+    print(f"  编译依赖安装可能需要 sudo 密码\n")
+
+    try:
+        answer = input("继续？[y/N]: ").strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        return 0
+
+    if answer not in ("y", "yes"):
+        print("已跳过 tmux 安装。")
+        return 0
+
+    # 安装编译依赖
+    print(f"\n{YELLOW}[1/4] 安装编译依赖...{RESET}")
+    os_name = os.uname().sysname
+    if os_name == "Darwin":
+        subprocess.run(["brew", "install", "libevent", "ncurses", "pkg-config", "bison"], check=False)
+    elif os_name == "Linux":
+        if shutil.which("apt-get"):
+            subprocess.run(["sudo", "apt-get", "update"], check=False)
+            subprocess.run(["sudo", "apt-get", "install", "-y",
+                          "build-essential", "libevent-dev", "libncurses5-dev",
+                          "libncursesw5-dev", "bison", "pkg-config"], check=False)
+        elif shutil.which("yum"):
+            subprocess.run(["sudo", "yum", "groupinstall", "-y", "Development Tools"], check=False)
+            subprocess.run(["sudo", "yum", "install", "-y",
+                          "libevent-devel", "ncurses-devel", "bison"], check=False)
+        else:
+            print_warn("无法识别包管理器，请手动安装编译依赖: libevent-dev ncurses-dev bison pkg-config")
+
+    # 下载源码
+    print(f"\n{YELLOW}[2/4] 下载 tmux 3.6a 源码...{RESET}")
+    import tempfile
+    tmpdir = tempfile.mkdtemp()
+    tarball = os.path.join(tmpdir, "tmux.tar.gz")
+    tmux_url = "https://github.com/tmux/tmux/releases/download/3.6a/tmux-3.6a.tar.gz"
+
+    r = subprocess.run(["curl", "-fsSL", tmux_url, "-o", tarball])
+    if r.returncode != 0:
+        print_err("下载失败，请检查网络连接。")
+        return 1
+
+    subprocess.run(["tar", "-xzf", tarball, "-C", tmpdir], check=True)
+    src_dir = os.path.join(tmpdir, "tmux-3.6a")
+
+    # 编译
+    prefix = os.path.join(os.path.expanduser("~"), ".local")
+    print(f"\n{YELLOW}[3/4] 编译 tmux（安装到 {prefix}）...{RESET}")
+
+    nproc = "2"
+    try:
+        r = subprocess.run(["nproc"], capture_output=True, text=True)
+        if r.returncode == 0:
+            nproc = r.stdout.strip()
+    except FileNotFoundError:
+        pass
+
+    r = subprocess.run(
+        f"./configure --prefix={prefix} && make -j{nproc} && make install",
+        shell=True, cwd=src_dir
+    )
+    if r.returncode != 0:
+        print_err("编译失败，请检查编译依赖是否已安装。")
+        return 1
+
+    # 清理临时目录
+    import shutil as _shutil
+    _shutil.rmtree(tmpdir, ignore_errors=True)
+
+    # 配置 PATH
+    print(f"\n{YELLOW}[4/4] 配置 PATH...{RESET}")
+    local_bin = os.path.join(prefix, "bin")
+    os.environ["PATH"] = f"{local_bin}:{os.environ.get('PATH', '')}"
+
+    if f"{local_bin}" not in os.environ.get("PATH", ""):
+        os.environ["PATH"] = f"{local_bin}:{os.environ['PATH']}"
+
+    # 写入 shell rc
+    shell_name = os.path.basename(os.environ.get("SHELL", "bash"))
+    rc_file = os.path.join(os.path.expanduser("~"), ".zshrc" if shell_name == "zsh" else ".bashrc")
+    path_line = 'export PATH="$HOME/.local/bin:$PATH"'
+    try:
+        rc_content = open(rc_file).read() if os.path.exists(rc_file) else ""
+        if "$HOME/.local/bin" not in rc_content:
+            with open(rc_file, "a") as f:
+                f.write(f"\n# remote-claude: tmux 路径\n{path_line}\n")
+            print_ok(f"已将 $HOME/.local/bin 写入 {rc_file}")
+    except Exception as e:
+        print_warn(f"无法写入 {rc_file}: {e}")
+
+    # 验证
+    tmux_bin = os.path.join(local_bin, "tmux")
+    if os.path.exists(tmux_bin):
+        r = subprocess.run([tmux_bin, "-V"], capture_output=True, text=True)
+        print(f"\n{GREEN}✓ tmux 安装成功: {r.stdout.strip()}{RESET}")
+        print(f"  路径: {tmux_bin}")
+        print(f"  请运行 source {rc_file} 或重新打开终端使 PATH 生效。")
+    else:
+        print_err("安装似乎未成功，请检查上方输出。")
+        return 1
+
+    return 0
+
+
+def cmd_lark_init(args):
+    """飞书机器人配置向导（扫码自动创建应用）"""
+    from lark_client.setup_wizard import SetupWizard
+    check_only = getattr(args, "check", False)
+    new_only = getattr(args, "new", False)
+    wizard = SetupWizard(check_only=check_only, new_only=new_only)
+    rc = wizard.run()
+    # 配置成功后自动重启飞书客户端（--check / --new 模式跳过）
+    if rc == 0 and not check_only and not new_only:
+        print("\n正在重启飞书客户端以应用新配置...")
+        cmd_lark_restart(args)
+    return rc
+
+
 def cmd_lark(args):
     """飞书客户端管理（兼容旧命令）"""
     # 如果没有子命令，默认显示状态或启动
@@ -485,6 +718,7 @@ def cmd_lark(args):
     else:
         print("飞书客户端未运行")
         print("\n可用命令:")
+        print("  python3 remote_claude.py lark init     - 配置向导（首次使用）")
         print("  python3 remote_claude.py lark start    - 启动客户端")
         print("  python3 remote_claude.py lark stop     - 停止客户端")
         print("  python3 remote_claude.py lark restart  - 重启客户端")
@@ -506,6 +740,9 @@ def main():
   %(prog)s status mywork             显示 mywork 会话状态
 
 飞书客户端:
+  %(prog)s lark init                 配置向导（首次使用，扫码自动创建应用）
+  %(prog)s lark init --check         检查当前配置状态
+  %(prog)s lark init --new           扫码创建新应用（不修改已有配置）
   %(prog)s lark start                启动飞书客户端
   %(prog)s lark stop                 停止飞书客户端
   %(prog)s lark restart              重启飞书客户端
@@ -529,6 +766,9 @@ def main():
 
 更新:
   %(prog)s update                    更新到最新版本
+
+依赖管理:
+  %(prog)s deps                      检查依赖并安装（含 tmux 源码编译）
 """
     )
 
@@ -605,6 +845,13 @@ def main():
     lark_status_parser = lark_subparsers.add_parser("status", help="查看飞书客户端状态")
     lark_status_parser.set_defaults(func=cmd_lark_status)
 
+    # lark init
+    lark_init_parser = lark_subparsers.add_parser("init", help="配置向导（扫码自动创建应用）")
+    lark_init_group = lark_init_parser.add_mutually_exclusive_group()
+    lark_init_group.add_argument("--check", action="store_true", help="仅检查当前配置状态")
+    lark_init_group.add_argument("--new", action="store_true", help="扫码创建新应用（不修改已有配置）")
+    lark_init_parser.set_defaults(func=cmd_lark_init)
+
     # 如果只输入 lark 没有子命令，使用默认处理
     lark_parser.set_defaults(func=cmd_lark)
 
@@ -636,6 +883,10 @@ def main():
     update_parser = subparsers.add_parser("update", help="更新 remote-claude 到最新版本")
     update_parser.set_defaults(func=cmd_update)
 
+    # deps 命令
+    deps_parser = subparsers.add_parser("deps", help="检查并安装依赖（tmux 源码编译等）")
+    deps_parser.set_defaults(func=cmd_deps)
+
     args, remaining = parser.parse_known_args()
 
     if args.command is None: