feishu-codex-cli-bridge

一个轻量的 Feishu/Lark 到本地 Codex CLI 的桥接器。

它让你可以在飞书单聊或群聊里和本机 Codex 对话：飞书收到消息，bridge 在本机调用 codex exec，再把结果回复回飞书。

Status: Developer Preview. 适合个人使用和小范围内测。复杂飞书文档表格写入仍是 experimental。

功能

• 飞书官方 WebSocket 长连接，无需公网回调 URL
• 私聊直接响应，群聊默认需要 @ 机器人
• 每个聊天独立 Codex session 记忆
• 连续消息 2 秒合并，减少碎片请求
• 同一聊天新请求会停止旧运行
• 文本回复和飞书卡片回复可切换
• 图片下载后作为 Codex image input
• 文件、音频、视频下载后作为本地路径注入 prompt
• 引用消息内容注入 prompt
• 读取飞书新版文档 /docx/ 和知识库 /wiki/
• 追加内容到飞书新版文档
• 群聊总结 /sum
• 工作空间别名 /ws
• 本机 bridge 进程查看和停止

安全提醒

不要提交以下内容到 GitHub：

• Feishu App Secret
• .env
• 真实 config.json / app-*.json
• ~/.feishu-codex-cli-bridge/ 里的本地状态文件
• 下载的飞书消息附件

本项目提供了示例配置：

• examples/config.example.json
• examples/.env.example

要求

• Node.js 20+
• 已登录的本机 Codex CLI
• 一个飞书/飞书国际版 Lark 自建应用
• 飞书应用启用机器人和长连接事件订阅

检查 Codex：

codex --version
codex exec --json "hello"

安装

开发模式：

npm install
npm run build

全局链接到本机：

npm link
feishu-codex --version

未来发布到 npm 后，可以使用：

npm install -g feishu-codex-cli-bridge

飞书开放平台配置

简版步骤：

1. 创建企业自建应用。
2. 启用机器人能力。
3. 事件订阅选择「使用长连接接收事件」。
4. 订阅 im.message.receive_v1。
5. 按需开通消息、文件、云文档权限。
6. 把机器人添加到单聊或群聊。

详细说明见：docs/飞书开放平台配置.md。

初始化配置

默认配置：

feishu-codex init \
  --app-id cli_xxx \
  --app-secret xxx \
  --cwd /absolute/path/to/workspace

开发模式也可以：

npm run dev -- init \
  --app-id cli_xxx \
  --app-secret xxx \
  --cwd /absolute/path/to/workspace

第二个飞书 App 使用独立配置：

feishu-codex init \
  --config ~/.feishu-codex-cli-bridge/app-b.json \
  --app-id cli_xxx \
  --app-secret xxx \
  --cwd /absolute/path/to/workspace

启动

默认配置：

feishu-codex run

或直接运行构建产物：

node dist/cli.js run

第二个 App：

node dist/cli.js run --config ~/.feishu-codex-cli-bridge/app-b.json

看到 ws client ready 表示长连接已连接。

飞书里怎么用

单聊：直接发消息。

群聊：默认必须 @ 机器人。

@石钰 帮我总结一下刚才大家讨论的重点

查看命令：

@石钰 /help

完整手册见：docs/机器人使用手册.md。

常用命令

/help       查看命令
/new        重置当前聊天的 Codex session
/cd <path>  切换当前聊天工作目录并重置 session
/mode       查看当前聊天回复模式
/mode text  使用普通文本回复
/mode card  使用飞书卡片回复
/text <prompt>  本条强制普通文本回复
/card <prompt>  本条强制卡片回复
/sum [N]    总结最近 N 条群聊消息，默认 30
/sum @名字 [N]  尽量总结某个人最近 N 条观点
/doc append <url> <content>  追加内容到飞书文档
/doc sum <url> [N]  总结最近 N 条消息并追加到文档
/ws list    查看工作空间别名
/ws save <name>  保存当前工作目录
/ws use <name>   切换到工作空间
/ws remove <name> 删除工作空间
/status     查看当前 cwd、session 和进程
/stop       停止当前聊天正在运行的 Codex
/ps         查看本机 bridge 进程
/exit       停止当前 bridge
/exit <id>  停止指定 bridge

文档能力

读取：

• 支持新版 /docx/
• 支持 /wiki/，如果背后是 docx 文档

写入：

• 默认追加到文档末尾
• 不覆盖、不删除原文档
• 纯文本和基础 Markdown 较稳定
• 复杂富文本、表格 block 仍是 experimental

建议先用短文本测试权限：

@石钰 /doc append https://xxx.feishu.cn/docx/xxxx 测试写入 hello

本地数据

默认目录：

~/.feishu-codex-cli-bridge/

常见文件：

config.json      默认 App 配置，含 secret
app-b.json       第二个 App 配置，含 secret
sessions.json    聊天 session 记忆
processes.json   bridge 进程注册
workspaces.json  工作空间别名
media/           下载的消息资源

这些文件不应该提交到 GitHub。

调试

类型检查：

npm run typecheck

构建：

npm run build

检查 npm 包内容：

npm pack --dry-run

故障排查见：docs/故障排查.md。

发布前检查见：docs/发布检查清单.md。

License

MIT