# Plugins Codex Feishu

> Feishu-native Codex plugin for project reports, Docs, Wiki, Bitable, private updates, and guarded local assistant workflows.

- **Type:** MCP server
- **Install:** `agentstack add mcp-aipmer-plugins-codex-feishu`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [aipmer](https://agentstack.voostack.com/s/aipmer)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [aipmer](https://github.com/aipmer)
- **Source:** https://github.com/aipmer/plugins-codex-feishu
- **Website:** https://github.com/aipmer/plugins-codex-feishu

## Install

```sh
agentstack add mcp-aipmer-plugins-codex-feishu
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 飞书里的 Codex 值班助理 (Codex Feishu Sentinel)

> 🤖 **《Codex 蓝皮书》Ch.08 官方参考工程**：专为 Codex 开发者打造的 24/7 全天候 AI 协作副驾驶。聚合 Git 日报推送、CI 巡检报警、手机端远程审批与云文档资产沉淀。

## 架构全景

```mermaid
flowchart LR
    subgraph Local["💻 本地 / CI 开发环境"]
        git["Git 提交 / Diff"]
        ci["CI 测试 / 构建流水线"]
    end

    subgraph Sentinel["🛡️ Codex 值班助理 (Sentinel)"]
        digest["智能日报汇总引擎"]
        watchdog["巡检熔断 & 权限守卫"]
        bridge["本地长连接 Bridge"]
    end

    subgraph Feishu["📱 飞书移动终端 / 团队协同"]
        msg["私人日报卡片 (1对1)"]
        alert["🚨 异常警报 & 远程审批"]
        docs["Docx 云文档 & 多维表格"]
    end

    git --> digest --> msg
    ci --> watchdog --> alert
    alert -. 手机回复 1(批准) / 0(回滚) .-> bridge
    digest --> docs
```

## 这是什么

这个项目将 Codex 智能体的能力全面接入飞书，打造全天候值班的私人助理：

- **极速入门**：给自己发送 Git 进展日报、周报或测试卡片（3 分钟即可跑通，最小成功闭环）
- **移动看护**：对齐《Codex 蓝皮书》Ch.08，CI 失败或触发部署审批时，手机端飞书弹窗，支持回复打字远程确认
- **进阶沉淀**：检索飞书 Docs / Wiki，将重构或项目进展自动写回飞书 Docx，并同步到 Bitable 多维表格
- **双向协同**：可选启用长连接消息机器人，飞书消息随时触发本地 Codex 完成协同编码

---

## 适合谁

- 使用 Codex、飞书和 GitHub 的独立开发者（解放双手，告别手动写日报）
- 希望把 AI 编码进展与构建状态自动发到移动端的小团队
- 想把项目进展与技术决策沉淀到飞书文档和多维表格的产品 / 工程团队

---

## 3 分钟跑通私人助理推送

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

### 1. 安装依赖

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

### 2. 创建并配置飞书应用

我们提供两种应用创建方式，强烈推荐 **方式 A（一键清单导入）**：

#### 方式 A：一键导入应用清单（推荐，10 秒就绪）

1. 登录 [飞书开放平台 - 开发者后台](https://open.feishu.cn/app)
2. 点击右上角 **「创建企业自建应用」** ➔ 选择 **「导入应用清单」**
3. 选择并上传本项目根目录下的 [`feishu_app_manifest.json`](./feishu_app_manifest.json)
4. 创建成功后，所有必要权限（消息、卡片、云文档）、机器人能力和长连接事件订阅将全自动配置完毕！
5. 在应用后台「凭证与基础信息」复制 `App ID` 和 `App Secret`，填入本地 `.env`（可先复制 `.env.example`）：
   ```env
   FEISHU_APP_ID=cli_xxx
   FEISHU_APP_SECRET=xxx
   FEISHU_DEFAULT_RECEIVE_ID=ou_xxx
   ```
6. 点击后台「版本管理与发布」➔ **发布最新版本**，确保可用范围包含你本人。

#### 方式 B：CLI 自动授权引导（Beta）

```bash
npm run feishu -- setup
```

命令会显示飞书授权链接。确认后会自动创建自建应用，预填消息、流式卡片、媒体和文档评论权限，以及 `im.message.receive_v1`、`drive.notice.comment_add_v1` 事件，并把 `App ID`、`App Secret`、owner `open_id` 写入本地 `.env`。

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

```bash
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. 检查配置

```bash
npm run feishu:doctor
```

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

### 4. 发送测试消息

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

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

```bash
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，再把文档链接发给你。

先完成用户授权：

```bash
npm run feishu -- auth
```

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

```env
FEISHU_USER_ACCESS_TOKEN=xxx
FEISHU_USER_REFRESH_TOKEN=xxx
```

预览报告：

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

写回 Docx 并发送私聊：

```bash
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 项目的更新，不建议让插件自动扫描整台电脑。更稳妥的方式是维护一个本地项目清单，只把你确认要汇总的仓库放进去。

先复制示例：

```bash
cp examples/projects.example.json projects.json
```

编辑 `projects.json`：

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

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

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

预览全部项目周报：

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

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

```bash
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 项目状态表

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

```bash
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`：

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

然后执行：

```bash
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 消息。

```env
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
FEISHU_BOT_DOCUMENT_CONTEXT_MAX_CHARS=100000
```

启动：

```bash
npm run feishu:bot
```

可直接在飞书中使用：

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

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

全文评论任务会读取 Docx 纯文本并注入 Codex prompt，默认最多 100000 字符，可通过 `FEISHU_BOT_DOCUMENT_CONTEXT_MAX_CHARS` 调整。应用需要 `docx:document:readonly`，目标文档仍需添加该文档应用。

详细示例见：[消息机器人快速接入](./plugins/feishu/skills/feishu/examples/quickstart-message-bot.md)。

### Webhook 事件订阅

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

```bash
npm run feishu -- webhook --self-test
```

详细说明见：[Webhook 配置](./plugins/feishu/skills/feishu/reference/webhook.md)。

### macOS 后台常驻

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

```bash
npm run feishu -- start
npm run feishu -- status
npm run feishu -- stop
```

## 常用命令

```bash
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 写入时，再运行：

```bash
npm run feishu -- auth
```

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

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

```env
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`

开发者本地同步：

```bash
./scripts/sync-local-plugin.sh
```

## 本地验证

修改插件后建议运行：

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

## 延伸阅读

- [CHANGELOG](./docs/Changelog.md)
- [贡献指南](./CONTRIBUTING.md)
- [开发任务记录](./docs/Dev_Task.md)
- [认证说明](./plugins/feishu/skills/feishu/reference/auth.md)
- [Bitable 指南](./plugins/feishu/skills/feishu/reference/bitable.md)
- [消息推送示例](./plugins/feishu/skills/feishu/examples/project-digest-push.md)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [aipmer](https://github.com/aipmer)
- **Source:** [aipmer/plugins-codex-feishu](https://github.com/aipmer/plugins-codex-feishu)
- **License:** Apache-2.0
- **Homepage:** https://github.com/aipmer/plugins-codex-feishu

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-aipmer-plugins-codex-feishu
- Seller: https://agentstack.voostack.com/s/aipmer
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.