工作原理

Bridge 是一座跑在你自己电脑上的桥：一端通过长连接接住飞书 / Lark 的群消息，另一端把任务交给本机的 Codex 或 Claude Code 去执行，再把过程与结果以流式 Markdown 卡片发回群里。

架构一图流

换成一行字：飞书群消息 ──长连接──▶ bridge ──▶ Codex app-server / Claude Agent SDK（每会话一独立后端），流式卡片沿原路返回。

两种后端可以在同一台机器上混用：建项目时按需选，不同项目各用各的。

心智模型：一个群 = 一个项目，一条会话 = 一段上下文

• 群 = 项目 = 固定工作目录（cwd）。每个群绑定一个本地目录，群里 @ 机器人，agent 就在该目录里跑。
• 话题（thread）= 一个会话（session）。对某条消息开话题，就是开了一条独立连续会话——上下文隔离、可以并行；话题关掉之后，发 /resume 还能把历史会话原样接回。
• 平时不用每句都 @ 它。话题内和单会话群里可以直接说话；/goal <目标> 能让它自主多轮干到完成。

群 ↔ 目录绑定机制

1. 发起。私聊机器人，在弹出的控制台菜单里点「新建项目」。
2. 绑定目录。选择一个本机目录作为这个项目的固定工作目录（cwd）。
3. 选后端。Codex 或 Claude，同一台机器可混用，各项目独立。
4. 机器人建群。机器人自动建好群、置顶命令说明、把你拉进去。之后这个群里的所有任务都在绑定目录里执行。

需要拉更多人？直接往群里加人即可；每个人在多话题群里开自己的话题，各自的会话互不干扰。给外部群用时记得先看权限分档。

一条消息的生命周期

1. 你在群里 @ 机器人（或在话题 / 单会话群里直接说话），也可以发图片、文件附件、合并转发。
2. Bridge 通过长连接收到消息，找到这个群绑定的项目目录与所选后端，将上下文交给该会话对应的独立后端进程。
3. agent 在本机目录里干活：读写文件、跑命令（受项目权限档约束）。
4. 过程流式回群：推理 / 命令 / 文件改动 / 结果实时刷新到一张可折叠卡片；⏹ 随时终止。卡死有 watchdog 自动回收，异常不波及其他群。

反向桥：☕ 咖啡一下

除了「飞书群 → 本机 agent」，Bridge 还有反方向：你在本机终端里直接跑的 Claude Code / Codex CLI，离座时把「需要审批 / 提问 / 任务完成」的时刻接管到你的飞书私聊——手机上点确认 / 回答，它就继续跑，机器保持不睡；回到电脑自动交还终端。详见场景手册与 v0.6.0 更新说明。

双控制台与常用命令

• 私聊控制台：私聊机器人弹交互菜单（新建项目 / 设置 / 用量 / 诊断 / 重连）。
• 网页控制台：feishu-codex-bridge web（默认端口 51847，只绑 127.0.0.1 + 随机 token 鉴权）——扫码加机器人、权限 checklist、启停 / 重启 / 更新后台服务、看所有 bot / 项目 / 话题 / 实时日志。
• 群内斜杠命令：/goal、/model、/resume、/compact、/context、/settings 等，按所选后端能力自适应裁剪。

feishu-codex-bridge run [--bot <名>]            前台启动（没配置先扫码 init；Ctrl+C 优雅退出）
feishu-codex-bridge start                       后台 daemon：装系统服务、开机/登录自启、崩溃自动拉起
feishu-codex-bridge status|logs|restart|stop    daemon 生命周期（logs -f 跟随日志）
feishu-codex-bridge update [--check]            更新到最新版（npm i -g）并自动重启 daemon
feishu-codex-bridge web [--port <端口>]          打开本机网页控制台（默认端口 51847）
feishu-codex-bridge bot init|list|use|rm        多机器人：注册 / 列表 / 选要连接的 / 移除
feishu-codex-bridge doctor                      本地自检：后端 / 登录 / 当前机器人

一台机器可以注册多个飞书机器人并同时连接，各自项目 / 会话独立。所有本地状态都在 ~/.feishu-codex-bridge/。