Feishu for Codex

面向飞书用户的 Codex 项目协作插件：生成项目报告，检索 Docs / Wiki，写入 Docx / Bitable，并把结果推送到飞书。

这是什么

这个插件适合把 Codex 的工作结果沉淀到飞书：

给自己发送项目日报、周报或测试消息
检索飞书 Docs / Wiki，让 Codex 生成项目报告
将报告写回飞书 Docx，并把链接发到飞书
可选把项目状态同步到 Bitable / 多维表格
可选让飞书消息触发本地 Codex，并以流式卡片、附件或文档评论完成协作

最推荐先跑通「私人助理推送」。它需要的配置最少，也最容易验证：能收到测试消息，就说明应用身份、接收人 ID 和消息权限已经通了。

适合谁

使用 Codex、飞书和 GitHub 的独立开发者
希望把 AI 编码进展自动发到飞书的小团队
想把项目进展沉淀到飞书文档和多维表格的产品 / 工程团队

如果你需要多 profile 或更通用的跨平台 Agent Bridge，可以同时参考 lark-channel-bridge。本项目聚焦「Codex + 飞书原生项目协作」，并保留轻量、受访问控制保护的本地消息机器人。

5 分钟跑通私人助理推送

1. 安装

git clone https://github.com/aipmer/plugins-codex-feishu.git
cd plugins-codex-feishu
npm install

2. 创建并配置飞书应用（Beta）

npm run feishu -- setup

命令会显示飞书授权链接。确认后会创建新的自建应用，预填消息、流式卡片、媒体和文档评论权限，以及 im.message.receive_v1、drive.notice.comment_add_v1 事件，并把 App ID、App Secret、owner open_id 和默认 Codex runner 写入本地 .env。Secret 不会打印到终端。该能力依赖飞书 SDK 和开放平台灰度范围，请以授权确认页和开发者后台为准。

已有应用需要补充配置时，必须显式指定 App ID：

npm run feishu -- setup --app-id cli_xxx

随后在飞书开放平台确认：

事件接收方式为「使用长连接接收事件」
已添加 im.message.receive_v1 和 drive.notice.comment_add_v1
应用已发布，可用范围包含当前用户
群聊使用时，机器人已经加入目标群

注意：

FEISHU_APP_ID 是「哪个飞书应用发消息」
FEISHU_DEFAULT_RECEIVE_ID 是「消息发给谁」
私聊建议使用 open_id，不要把 App ID 当成接收人 ID
SDK 的增量配置能力可能受飞书灰度范围影响；以授权确认页和开发者后台最终显示为准
.env 只保留在本地，已经被 .gitignore 忽略

3. 检查配置

npm run feishu:doctor

如果只想先验证消息推送，FEISHU_USER_ACCESS_TOKEN 缺失可以暂时忽略。它只影响 Docs/Wiki、Docx 写回和 Bitable。

4. 发送测试消息

npm run feishu:project-update -- --test --send --confirm

收到飞书私聊消息后，再发送项目更新：

npm run feishu:project-update -- \
  --send \
  --confirm \
  --title "Codex 周报" \
  --file ./plugins/feishu/skills/feishu/examples/project-update-template.md

进阶：项目报告写回飞书文档

这条链路会读取 Git 项目进展和仓库内的 CHANGELOG.md，检索飞书 Docs / Wiki，让 Codex 生成产品更新报告，写回飞书 Docx，再把文档链接发给你。

先完成用户授权：

npm run feishu -- auth

打开命令输出的 AUTH_URL，授权成功后会写入本地：

FEISHU_USER_ACCESS_TOKEN=xxx
FEISHU_USER_REFRESH_TOKEN=xxx

预览报告：

npm run feishu -- report --preview \
  --mode weekly \
  --workspace /path/to/project \
  --query "项目名称"

写回 Docx 并发送私聊：

npm run feishu -- report \
  --mode weekly \
  --workspace /path/to/project \
  --query "项目名称" \
  --write-doc \
  --send \
  --confirm

说明：

--preview 是默认安全模式，不写飞书
所有真实写入都必须加 --confirm
用户 access token 过期时，会自动用 FEISHU_USER_REFRESH_TOKEN 续期并重试
默认标题为「Codex 项目更新｜YYYY-MM-DD」；概述后按「已完成 / 进行中 / 风险阻塞 / 下一步」展示项目表格
Git 提交只作为内部证据，报告不会展示 commit hash、分支、本机路径或工作区状态

进阶：全部项目总览

如果你想让飞书掌握多个 Codex 项目的更新，不建议让插件自动扫描整台电脑。更稳妥的方式是维护一个本地项目清单，只把你确认要汇总的仓库放进去。

先复制示例：

cp examples/projects.example.json projects.json

编辑 projects.json：

{
  "projects": [
    {
      "name": "your-project",
      "workspace": "/absolute/path/to/your-project",
      "owner": "Your Name",
      "enabled": true
    }
  ]
}

也可以在 .env 里固定路径：

FEISHU_PROJECTS_FILE=/absolute/path/to/projects.json

预览全部项目周报：

npm run feishu -- portfolio-report --preview \
  --projects-file ./projects.json \
  --mode weekly

写回 Docx、同步 Bitable 并发送私聊：

npm run feishu -- portfolio-report \
  --projects-file ./projects.json \
  --mode weekly \
  --write-doc \
  --bitable \
  --send \
  --confirm

说明：

默认读取每个仓库的 Git 元数据、diff stat 和可用的 CHANGELOG.md，不会读取完整源码
默认不会把本机完整路径写进飞书报告；本地调试需要时再加 --include-paths
如果只想看有变化的项目，加 --changed-only
报告开头先概述全部项目，随后用四张表按阶段汇总项目和产品更新内容

进阶：Bitable 项目状态表

如果你想把项目状态同步到飞书多维表格，先创建标准表：

npm run feishu -- bitable-bootstrap --preview --owner "Your Name"
npm run feishu -- bitable-bootstrap --confirm --owner "Your Name"

它会创建 Codex Project Operations Base 和 Project Status 表，并写入本地 .env：

FEISHU_PROJECT_NAME=Feishu for Codex
FEISHU_PROJECT_OWNER=Your Name
FEISHU_BITABLE_APP_TOKEN=bascn_xxxxx
FEISHU_BITABLE_TABLE_ID=tbl_xxxxx

然后执行：

npm run feishu -- report \
  --mode weekly \
  --workspace /path/to/project \
  --query "项目名称" \
  --write-doc \
  --bitable \
  --send \
  --confirm

可选能力

飞书消息机器人（Beta）

适合让飞书私聊或群消息触发本地 Codex。出于安全考虑，从 v1.1.0 开始必须配置 owner 或白名单，否则 bot 不会执行本地命令。

机器人使用飞书官方 Channel SDK，回复会关联原消息；话题中的消息会继续回复在原话题。Codex 输出默认使用飞书原生流式卡片，CardKit 权限不可用时自动回退为 Markdown 消息。

FEISHU_BOT_OWNER_OPEN_ID=ou_xxxxx
FEISHU_DEFAULT_WORKSPACE=/absolute/path/to/your/workspace
FEISHU_CODEX_COMMAND="node plugins/feishu/scripts/feishu-codex-runner.js"
FEISHU_RUNNER_COMMAND="codex exec"
FEISHU_BOT_STREAMING=true
FEISHU_BOT_MEDIA_ENABLED=true
FEISHU_BOT_DOCUMENT_COMMENTS=true

启动：

npm run feishu:bot

可直接在飞书中使用：

发送图片、文件、音频或视频：机器人会把附件下载到本机隔离目录，再把本地路径交给 Codex。
/send output/report.pdf：发送当前会话工作区内的文件；隐藏文件、目录外文件和超限文件会被拒绝。
在已添加该应用为文档协作者的云文档评论中 @机器人：Codex 会读取评论并回复原评论线程。

媒体默认单个最大 20 MB、单条消息最多 5 个，本地缓存默认保留 24 小时。可以通过 FEISHU_BOT_MEDIA_MAX_BYTES、FEISHU_BOT_MEDIA_MAX_ITEMS 和 FEISHU_BOT_MEDIA_RETENTION_HOURS 调整。

详细示例见：消息机器人快速接入。

Webhook 事件订阅

适合接收飞书开放平台事件回调，例如 url_verification、消息事件和加密事件体。

npm run feishu -- webhook --self-test

详细说明见：Webhook 配置。

macOS 后台常驻

当前 service 管理优先支持 macOS launchd：

npm run feishu -- start
npm run feishu -- status
npm run feishu -- stop

常用命令

npm run feishu -- help
npm run feishu -- setup
npm run feishu:doctor
npm run feishu:project-update -- --test --send --confirm
npm run feishu -- auth
npm run feishu -- report --preview --mode weekly --query "project name"
npm run feishu -- portfolio-report --preview --projects-file ./projects.json
npm run feishu -- bitable-bootstrap --preview --owner "Your Name"
npm run feishu -- webhook --self-test

常见问题

open_id 和 App ID 有什么区别？

FEISHU_APP_ID=cli_xxx：飞书应用身份，用来发消息、换 token
open_id=ou_xxxxx：飞书用户身份，用来指定消息接收人

两者不能混用。

为什么 `doctor` 提示缺少 `FEISHU_USER_ACCESS_TOKEN`？

只做私聊推送时可以先忽略。需要 Docs/Wiki 检索、Docx 写回或 Bitable 写入时，再运行：

npm run feishu -- auth

为什么 bot 不执行本地命令？

需要至少配置一项访问控制：

FEISHU_BOT_OWNER_OPEN_ID=ou_xxxxx
FEISHU_BOT_ADMINS=ou_xxxxx
FEISHU_BOT_ALLOWED_USERS=ou_xxxxx
FEISHU_BOT_ALLOWED_CHATS=oc_xxxxx

默认拒绝执行是为了避免飞书消息意外触发本地命令。

安装到 Codex

普通用户推荐直接在 Codex 里添加插件市场：

Source：https://github.com/aipmer/plugins-codex-feishu.git
Git reference：main
Sparse path：plugins/feishu

如果当前 Codex 版本需要 repo-local marketplace 文件：

Marketplace path：.agents/plugins/marketplace.json

开发者本地同步：

./scripts/sync-local-plugin.sh

本地验证

修改插件后建议运行：

bash scripts/smoke-test.sh
bash scripts/check-sensitive-values.sh

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
.agents/plugins		.agents/plugins
docs		docs
examples		examples
plugins/feishu		plugins/feishu
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Navigation Menu

Repository files navigation

Feishu for Codex

这是什么

适合谁

5 分钟跑通私人助理推送

1. 安装

2. 创建并配置飞书应用（Beta）

3. 检查配置

4. 发送测试消息

进阶：项目报告写回飞书文档

进阶：全部项目总览

进阶：Bitable 项目状态表

可选能力

飞书消息机器人（Beta）

Webhook 事件订阅

macOS 后台常驻

常用命令

常见问题

open_id 和 App ID 有什么区别？

为什么 `doctor` 提示缺少 `FEISHU_USER_ACCESS_TOKEN`？

为什么 bot 不执行本地命令？

安装到 Codex

本地验证

延伸阅读

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Feishu for Codex

这是什么

适合谁

5 分钟跑通私人助理推送

1. 安装

2. 创建并配置飞书应用（Beta）

3. 检查配置

4. 发送测试消息

进阶：项目报告写回飞书文档

进阶：全部项目总览

进阶：Bitable 项目状态表

可选能力

飞书消息机器人（Beta）

Webhook 事件订阅

macOS 后台常驻

常用命令

常见问题

open_id 和 App ID 有什么区别？

为什么 doctor 提示缺少 FEISHU_USER_ACCESS_TOKEN？

为什么 bot 不执行本地命令？

安装到 Codex

本地验证

延伸阅读

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

为什么 `doctor` 提示缺少 `FEISHU_USER_ACCESS_TOKEN`？