feishu-agent-bridge · 自助排查

自助排查

用 Bridge 的人有个天然优势：你本机就装着 Codex / Claude Code。遇到问题别自己翻日志——把下面的诊断提示词直接丢给它，让 AI 替你排查、替你修。

第一招：让 AI 替你排查

在本机终端打开 codex 或 claude，把这段贴进去：

我的 feishu-codex-bridge（飞书 ↔ 本机 agent 的桥）不太对劲，症状是：
【一句话描述你的症状，例如：群里 @ 机器人没反应 / 装不上 / 服务起不来】

请你替我排查并修复，按这个思路来：
1) node -v 确认 Node ≥ 20；
2) feishu-codex-bridge doctor 跑内置自检，看后端 / 登录 / 机器人状态；
3) feishu-codex-bridge status 看后台服务是否在跑，
   不在就 feishu-codex-bridge start 拉起来；
4) feishu-codex-bridge logs 里找我刚才复现问题时间段的报错；
5) 本地状态都在 ~/.feishu-codex-bridge/（配置、项目注册表、日志），
   需要时可以去里面看，但别动加密密钥库；
6) 如果像是版本问题，feishu-codex-bridge update 升到最新再试；
7) 最后告诉我：原因是什么、你改了什么、我还需要做什么。

群里的机器人行为不对（回复怪、权限报错、卡片异常）时，还有个更顺手的入口：私聊机器人 → 管理台 → 诊断——诊断卡里有日志路径、权限自检，还有一段可复制的诊断提示词，直接贴给本机 agent 就能查。

想自己动手？四条命令

feishu-codex-bridge doctor    # 本地自检：后端 / 登录 / 当前机器人
feishu-codex-bridge status    # daemon 是否在跑
feishu-codex-bridge logs -f   # 跟随实时日志（复现一次问题）
feishu-codex-bridge update    # 升级到最新版并自动重启 daemon

网页控制台（feishu-codex-bridge web）里也有宿主机体检、后端环境检测和实时日志；飞书私聊控制台里有「诊断」和「重连」。消息收不到时先点「重连」，再考虑 restart。

易踩的坑

用 npx 起后台服务后，服务莫名失效

后台服务必须全局安装（npm i -g），别用 npx——服务里硬编码了 CLI 路径，npx 临时缓存会被清理。前台 run 用 npx 没问题（单次进程）。

会话卡住不动

先点卡片上的 ⏹ 终止当前轮再重发。卡死的会话有 watchdog 自动回收，异常不会波及其他群；若整个机器人无响应，跑一遍 feishu-codex-bridge restart。

启动时提示缺飞书权限

v0.3.7 起启动不再被权限检查拦住：缺权限时会列出缺什么、影响哪些功能、去哪开通，可以先跑起来、稍后在管理台「诊断」里补齐。

还是没解决？带上这些来反馈

  • 操作系统与版本（macOS / Windows）；
  • node -v 与 feishu-codex-bridge doctor 的输出；
  • 复现步骤和 logs 里相应时间段的日志片段（注意先抹掉敏感信息）——上面那段 AI 排查提示词跑完，这些材料它都替你整理好了。

反馈渠道：GitHub Issues，或飞书交流群直接问——群里有作者和一个用 Bridge 跑起来的答疑机器人。