Feishu Bridge
feir/feishu-bridge
IA programadora com rastreamento de tasks e controle Feishu em cartões ricos
Ver no GitHubAgent que integra Claude Code CLI e outros modelos de IA directamente no Feishu (plataforma chinesa similar a Slack), renderizando fluxo em tempo real, rastreamento de tarefas e estado de múltiplos agents em cartões ricos. Permite que agents controlem remotamente documentos, tabelas, calendários e tarefas do Feishu via CLI, criando uma experiência bidirecional completa de programação assistida por IA.
Instalação
npx convez-ai feir/feishu-bridge1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Executar análise e code review via Claude Code dentro do Feishu com progresso em tempo real
- Automatizar criação de tarefas, documentos e eventos no Feishu a partir de directives de IA
- Gerenciar múltiplos agents paralelos (Claude Code, Codex, OMP, Alma, Pi) com rastreamento visual unificado
Veredito

Solução sofisticada de automação e integração que traz a experiência de um assistente de programação full-featured direto para dentro do Feishu, com streaming, monitoramento de contexto e controle bidirecional de recursos. Implementação técnica robusta, mas limitada ao ecossistema Feishu (popular na China, menos usado globalmente).
README
A tradução para o português deste README ainda está na fila.
Feishu Bridge
在飞书中获得完整的 AI 编程助手体验 — 不只是聊天,而是流式输出、任务追踪、多 Agent 调度、上下文管理的全功能呈现。
普通 AI Bot 只转发文本。Feishu Bridge 不同:它将 AI 编程助手(Claude Code / Codex / OMP / Alma / Pi)的每一项能力——实时流式输出、todo 进度追踪、Agent 分发状态、context 用量监控、配额告警——原生渲染到飞书消息卡片中,同时利用飞书的交互按钮、内联链接、Markdown 排版增强体验。AI Agent 还能通过飞书 CLI 工具反向管理你的文档、表格、日历、任务等资源。
信息卡片
每条回复都是一张富信息卡片,而非纯文本:
┌──────────────────────────────────────────────────┐
│ 已完成代码审查,发现 2 个问题并修复。 │
│ │
│ 1. `worker.py:128` — 重复 join 表达式... │
│ 2. `ui.py:727` — 冗余注释... │
│ │
│ ◉ Code review (Explore) ← Agent 进度 │
│ ~~☑ Search patterns~~ │
│ ☑ Fix lint errors (3/3) ← Todo 追踪 │
│ ◻ Run tests (0/2) │
│ │
│ [📎 Open PR] [✅ Confirm] [❌ Cancel] ← 交互按钮│
│ │
│ ────────────────────────────────────── footer ─── │
│ ✅ 3/5 tasks · opus-4-6 · 2m15s · 45k tokens · feishu-bridge │
│ 🟡 Context 72% — 可考虑 /compact 压缩上下文 │
│ ⬆ v2026.3.25.1 已就绪,/restart 部署 │
└──────────────────────────────────────────────────┘
卡片内包含的实时信息:
| 区域 | 内容 | 来源 |
|---|---|---|
| 主体 | 流式 Markdown 输出(100ms 级增量更新) | Claude Code stdout |
| Agent 进度 | 多 Agent 并行分发的启动/完成状态 | stream-json tool_use 事件 |
| Todo 追踪 | 任务列表实时进度(☑/◻) | TodoWrite 回调 |
| 交互按钮 | 确认/取消/选择,点击即响应 | Action markers 解析 |
| 内联链接 | URL 自动提取为侧边栏按钮 | 正则匹配 + 按钮渲染 |
| Footer | 状态图标 · 任务数 · 模型 · 耗时 · token 数 · 项目(/project 绑定的 project_id,未绑定时为默认 workspace 目录名) | CLI result 元数据 + thread-projects 绑定 |
| Footer | Context 用量告警(70%/85% 阈值) | input_tokens / context_window |
| Footer | 版本更新提醒 | 后台 auto-update 检测 |
它能做什么
通过飞书操控 AI Agent
"帮我 review 一下这个 PR" → Claude Code 读代码、跑测试、给反馈
"/status" → 查看 context 用量、token 费用、配额
"/model sonnet" → 切换到 Sonnet 模型
让 AI Agent 管理飞书资源
"把上周会议纪要里的待办项创建为飞书任务" → 读取文档 + 提取待办 + 批量创建
"对比这两个表格的数据差异,结果写入新文档" → 读取表格 + 分析 + 创建文档
"查一下明天下午有没有空,帮我约个会" → 查询日历空闲 + 创建事件 + 添加参会人
链接即上下文 — 消息中的飞书链接自动识别并抓取内容,发链接即可开始工作。
核心特性
实时流式渲染
CardKit v2 流式卡片 — 打字指示器 → loading 动画 → 100ms 级增量更新 → 完成后切换为静态卡片。自动适配飞书 Markdown 渲染限制(标题降级、代码块优化),体验接近原生 CLI 终端。
任务与 Agent 追踪
Claude Code 的 TodoWrite 进度和多 Agent 分发状态实时渲染到卡片中。单 Agent、多 Agent 并行分发、Agent Teams 协作三种模式均支持,完成自动标记。
会话与上下文管理
跨消息维持完整上下文,bridge 重启自动恢复会话。Context 用量实时监控(70%/85% 阈值告警),支持 /compact 压缩。空闲会话在 prompt cache TTL 到期前自动触发 compact(idle auto-compact),降低冷启动成本。每个聊天独立任务队列(单聊串行、多聊天 4 workers 并行),/btw 可在不中断当前任务的情况下侧问(仅 Claude)。
交互增强
- Action buttons — Claude 需要确认/选择时,卡片内直接渲染交互按钮,点击即响应
- 内联 URL 按钮 — 回复中的链接自动提取为侧边栏快捷按钮
- Rich footer — 每张卡片底部显示状态、模型、耗时、token、项目(
/project绑定)、context 告警、版本更新
飞书 CLI 工具
feishu-cli 负责 bot 消息发送(文本、图片、音频),lark(larksuite/cli)覆盖 20+ 飞书服务(文档、表格、多维表格、Wiki、日历、任务、邮件、云盘、审批等)。Agent 自动按需调用,也可作为独立 CLI 工具使用。
多 Agent 后端
| 特性 | Claude Code | Codex | OMP | Alma | Pi |
|---|---|---|---|---|---|
| 流式输出 | 增量实时更新 | 流式输出 | 增量实时更新 | 增量实时更新 | 增量实时更新 |
/compact | ✅ | ❌ | ✅ | ✅ | ❌ |
/btw | ✅ | ❌ | ❌ | ❌ | ❌ |
/status | ✅ | ✅ | ✅ | ✅ | ✅ |
| 会话持久化 | session_id | thread_id | RPC 进程 | WS thread_id | session 文件 |
| 空闲 auto-compact | ✅ | ❌ | ✅ | ✅ | ❌ |
| 默认模型 | 由 Claude CLI 决定 | 由 Codex CLI 决定 | ~/.omp/agent/config.yml | Alma 配置 | ~/.pi/models.json |
安全
- Token 加密 — AES-256-GCM,密钥绑定 app_id + user_id + machine_id
- 沙盒限制 — 内置权限规则拦截高危命令(
systemctl *feishu-bridge*、shutdown、curl等) - 删除二次确认 — 所有删除命令需
--confirm <prefix>校验
Bridge 命令
在飞书聊天中直接使用:
| 命令 | 说明 |
|---|---|
/new /reset /clear | 重置会话(清除上下文) |
/stop /cancel | 取消当前任务(排队消息继续处理) |
/stop all | 取消当前任务并清空待处理队列 |
/btw <问题> | 侧问(fork 会话,不中断当前任务;仅 Claude) |
/compact [指令] | 压缩上下文(仅 Claude / OMP / Alma) |
/model [模型名] | 查看或切换模型 |
/agent [类型] | 查看或切换后端(claude / codex / pi / omp / alma) |
/provider [名称] | 查看或切换当前后端配置 |
/status | 查看会话状态(context / 费用 / 配额) |
/update | 拉取最新版本并重启(若已是最新则仅提示) |
/plan [目标] | 生成实施计划草稿(bridge 工作流) |
/done [摘要] | 归档当前会话(bridge 工作流) |
/memory-gc | 清理和整理 memory(bridge 工作流) |
/confirm | 确认待执行的工作流草稿 |
/feishu-tasks [命令] | 飞书任务管理(list/get/subtasks/add-subtask/complete) |
/feishu-doc | 云文档读写(Markdown) |
/feishu-sheet | 电子表格读写 |
/feishu-bitable | 多维表格操作 |
/restart | 重启 Bridge 进程 |
/restart-all | 重启所有 bot 实例 |
/help | 显示帮助 |
工作流命令(
/plan/done/memory-gc)由 bridge 内置工作流引擎执行,不经过 Agent CLI。需要在~/.agents/skills/下安装对应 skill。工作流产出草稿后需/confirm确认,或/stop取消。
快速开始
1. 创建飞书机器人
访问 OpenClaw 多智能体创建页,按引导创建 bot 并获取 App ID / App Secret。
2. 安装
pipx install feishu-bridge # 推荐(隔离环境)
# 或从源码
git clone https://github.com/feir/feishu-bridge.git
cd feishu-bridge && pip install -e '.[dev]'
升级
Bridge 会在后台自动检测新版本并拉取更新(每 6 小时),更新就绪后在回复卡片底部显示提醒。发送 /restart 即可部署。也可手动操作:
# PyPI 安装
pipx upgrade feishu-bridge
# 源码安装(纯代码变更 pull 即生效,依赖变更需重装)
cd feishu-bridge && git pull
pip install -e '.[dev]' # 仅 pyproject.toml 依赖变更时需要
使用 /update 可手动触发版本检查并自动重启部署。
3. 配置并运行
首次运行自动启动配置向导:
$ feishu-bridge --bot my-bot
# 交互式输入 App ID、Secret、Agent 类型、工作目录
# → 凭证写入 ~/.config/feishu-bridge/.env
# → 配置写入 ~/.config/feishu-bridge/config.json
手动配置 ~/.config/feishu-bridge/config.json:
{
"bots": [{
"name": "my-bot",
"app_id": "${FEISHU_APP_ID}", // 从 .env 加载
"app_secret": "${FEISHU_APP_SECRET}",
"workspace": "/path/to/workspace",
"allowed_users": ["*"], // ["*"] = 所有人
"allowed_chats": ["oc_xxx"], // 可选:限定群聊
"model": "claude-opus-4-6", // 可选:透传给 CLI;未设则由 CLI 决定
"group_policy": { ... } // 可选:群聊响应策略
}],
"agent": {
"type": "claude", // claude | codex | pi | omp | alma
"command": "claude",
"commands": { // 可选:为热切换指定命令
"claude": "claude",
"codex": "codex",
"pi": "pi",
"omp": "omp",
"alma": null
},
"args": ["--verbose"], // 可选:当前 agent 的额外 CLI 参数
"env": { // 可选:当前 agent 的固定环境变量
"ANTHROPIC_BASE_URL": "http://127.0.0.1:11434"
},
"args_by_type": { // 可选:按 agent 类型区分参数
"codex": ["--oss", "--local-provider", "ollama"]
},
"env_by_type": { // 可选:按 agent 类型区分环境变量
"codex": {
"OPENAI_BASE_URL": "http://127.0.0.1:11434/v1"
}
},
"prompt": { // 可选:控制 bridge 固定注入的 prompt
"safety": "full", // full | minimal | off
"feishu_cli": true,
"cron_mgr": true
},
"timeout_seconds": 300
}
}
发送 /agent claude、/agent codex、/agent pi、/agent omp 或 /agent alma 可在当前 bot 进程内热切换后端。切换会清空旧会话映射,避免复用不兼容的 session_id / thread_id;该切换仅影响当前运行实例,重启后仍以配置文件中的 agent.type 为准。
agent.args / agent.env 是当前 agent.type 的简写;如需给热切换目标预置不同参数,使用 args_by_type / env_by_type。
如需在 bridge 内热切换 provider,而不是手改配置文件,可定义 agent.providers:
"agent": {
"type": "claude",
"provider": "default",
"command": "claude",
"providers": {
"default": {},
"ollama": {
"env_by_type": {
"claude": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:11434"
},
"codex": {
"OPENAI_BASE_URL": "http://127.0.0.1:11434/v1"
}
},
"args_by_type": {
"codex": ["--oss", "--local-provider", "ollama"]
},
"models": {
"claude": "qwen3.5",
"codex": "gpt-oss:120b"
},
"prompt": {
"safety": "minimal",
"feishu_cli": false,
"cron_mgr": false
}
}
}
}
随后可在飞书内直接发送:
/provider ollama
/provider default
agent.prompt 用于控制 bridge 自己追加的 system prompt 片段;provider 下的 prompt 会覆盖全局设置。对本地 Ollama,通常建议关闭 feishu_cli / cron_mgr,并把 safety 降到 minimal,这样可以显著减少每次启动时固定注入的 token。
切换 provider 会像 /agent 一样清空旧会话映射,避免复用不兼容的 session。
从 type=local 迁移(2026-04-19 起)
LocalHTTPRunner 已于 2026-04-19 移除。之前直接对接 OpenAI-compatible 端点的 agent.type=local 配置会在启动时 sys.exit(1) 并提示迁移路径。
替换方案:改用 agent.type=codex + Codex OSS 本地 provider(--oss 等价于 -c model_provider=oss),由 Codex CLI 自己管理 Ollama / LM Studio 等本地端点。
| 旧配置(type=local) | 新配置(type=codex + Codex OSS) |
|---|---|
"type": "local""endpoint": "http://127.0.0.1:11434/v1""model": "gpt-oss:120b" | "type": "codex""args_by_type": { "codex": ["--oss", "--local-provider", "ollama"] }"model": "gpt-oss:120b"(透传给 Codex CLI) |
迁移后 bridge 不再直连 HTTP 端点,所有请求经 Codex CLI 转发,保留 Codex 的事件流卡片渲染。LM Studio 用户把 --local-provider 值改为 lmstudio 即可。
连接本地 Ollama
可以继续使用现有 claude / codex runner,只把底层 CLI 指到本地 Ollama。这样仍能保留 bridge 对 Claude Code / Codex 事件流的卡片渲染能力。
Claude Code → Ollama
"agent": {
"type": "claude",
"command": "claude",
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:11434"
}
}
模型名由 CLI 决定:bridge 只透传 "model" 字段(或 /model 命令参数)给 CLI,不内置任何默认模型。本地已安装的模型名由 Ollama/oMLX/Pi 等下游 CLI 管理。
Codex → Ollama
"agent": {
"type": "codex",
"command": "codex",
"args": ["--oss", "--local-provider", "ollama"],
"env": {
"OPENAI_BASE_URL": "http://127.0.0.1:11434/v1"
}
}
同样可以通过 bot 配置里的 "model" 或 /model gpt-oss:120b 指定具体模型(bridge 只透传)。若你已在 ~/.codex/config.toml 配好 profile,也可以改用:
"agent": {
"type": "codex",
"command": "codex",
"args": ["--profile", "ollama-launch"]
}
连接 Pi / oMLX
Pi runner 适合把本机 pi 作为 bridge 后端,再由 Pi 连接本地 oMLX。推荐先以只读工具启用,确认 Feishu 端 smoke 后再显式加入写入或 shell 工具。
前置条件:
pi已在 PATH 中,或在agent.commands.pi中使用绝对路径。~/.pi/agent/models.json已配置 oMLX provider,例如baseUrl: "http://127.0.0.1:8000/v1"。- oMLX 服务已监听本机端口。
示例配置:
"agent": {
"type": "claude",
"provider": "default",
"commands": {
"claude": "claude",
"codex": "codex",
"pi": "/Users/feir/.local/bin/pi"
},
"providers": {
"default": {},
"pi-local": {
"workspace": "/Users/feir/.claude",
"models": {
"pi": "Qwen3.6-35B-A3B-mxfp4"
},
"model_aliases": {
"pi": "Qwen3.6-35B-A3B-mxfp4",
"qwen": "Qwen3.6-35B-A3B-mxfp4",
"gemma": "gemma-4-26b-a4b-it-mxfp4"
},
"args_by_type": {
"pi": [
"--provider", "omlx",
"--no-context-files",
"--no-extensions",
"--no-skills",
"--no-prompt-templates",
"--no-themes"
]
},
"prompt": {
"safety": "minimal",
"feishu_cli": false,
"cron_mgr": false
}
}
}
}
飞书内切换顺序:
/agent pi
/provider pi-local
默认情况下,PiRunner 会自动注入只读工具 read,grep,find,ls。如果配置里显式传入 --tools 或 --no-tools,bridge 会尊重该设置,不再追加默认工具。
Pi 当前不支持 bridge 触发的 /compact;当当前 runner 是 Pi 时,/compact 会返回“不支持”,context 告警也会提示使用 /new 开始新会话。Pi 的 token 使用量来自 Pi JSON 事件中的 usage 字段,bridge 会把它映射到 /status 和消息 footer。
Pi 支持按会话持久记忆:scope 为 (bot, chat, thread),bridge 每个 turn 只读注入 <bridge_home>/feishu-bridge/pi-memory/<hash>.md 的内容到系统提示,并指示 agent 在需要记住持久事实时用 read/edit 维护该文件。bridge 只读、绝不写该文件,pi 是唯一写者(避免并发写竞争)。
为避免本地模型自动吃进过多 Claude Code 上下文,推荐 staging/生产先保留 --no-context-files --no-extensions --no-skills --no-prompt-templates --no-themes。如果要给 Pi 增加规则,优先使用短上下文:
- 全局:
~/.pi/agent/AGENTS.md - 项目:
<workspace>/.pi/APPEND_SYSTEM.md
写入或 shell 工具不建议直接加入生产配置。若确实要测试,应先在一次性目录里显式覆盖 args_by_type.pi 的 --tools,完成安全审查和 disposable-file smoke test 后再扩大范围。
连接 OMP
OMP runner 使用持久化 JSON-RPC 2.0 进程(persistent RPC mode),每个 session 对应一个长驻 omp 进程,通过 stdin/stdout 通信。进程跨 turn 复用,crash 后从 session 文件自动恢复。
前置条件:
omp已在 PATH 中,或在agent.commands.omp中指定路径。~/.omp/agent/config.yml已配置(包含modelRoles.default等)。
示例配置:
"agent": {
"type": "omp",
"command": "omp"
}
OMP 支持 /compact、/status,不支持 /btw。空闲 auto-compact 同样生效。
连接 Alma
Alma runner 通过本地 WebSocket API(localhost:23001)与 Alma 桌面应用通信,而非启动子进程。Bridge 保持 Feishu 卡片渲染能力;LLM 调用、工具执行、memory 和 compaction 由 Alma 处理。
前置条件:
- Alma 桌面应用已运行并监听
localhost:23001。
示例配置:
"agent": {
"type": "alma"
}
Alma 支持 /compact、/status,不支持 /btw。模型可通过内置别名切换:/model opus、/model sonnet、/model haiku。
配置查找顺序:--config <path> → $FEISHU_BRIDGE_CONFIG → ~/.config/feishu-bridge/config.json
模型相关配置归属 CLI
Bridge 只做透传,不内置任何模型名、context window、别名默认值。所有模型相关配置由下游 CLI 自己管理:
| 下游 | 模型来源 | context window 来源 |
|---|---|---|
| Claude CLI | --model 参数或 CLI 默认 | CLI 自带(Anthropic SDK) |
| Codex CLI | ~/.codex/config.toml 里的 model + profile | Codex 自带 |
| Pi CLI | ~/.pi/models.json(每模型 contextWindow)+ ~/.pi/settings.json | Pi 自带 |
| OMP | ~/.omp/agent/config.yml 里的 modelRoles.default | OMP 自带 |
| Alma | Alma 桌面应用配置 | Alma 自带 |
Bridge 行为:
bot.model、/model <name>— 直接透传给下游 CLI;未设则由 CLI 自己决定agent.providers.<name>.model_aliases— 飞书端别名解析(/model qwen→/model Qwen3.6-35B-A3B-mxfp4),解析后再透传/status与消息 footer:若流事件未上报contextWindow(或上报为 0),显示 "上下文窗口:未知(由 CLI 决定)",跳过百分比告警
最小配置(只配 agent.type,其他全部交给 CLI):
"agent": { "type": "claude" }
// 等效于 claude CLI 自己的默认模型 + context window
群聊响应策略
通过 bot 的 group_policy 字段配置群聊响应行为,不配置时响应所有消息(兼容模式)。私聊不受影响。
| 模式 | 行为 | 适用场景 |
|---|---|---|
owner-only | 仅 owner @bot 时响应 | 个人专属 bot |
mention-all | 任何人 @bot 时响应 | 团队共享 bot |
auto-reply | 响应所有消息(无需 @) | 专用工作群 |
disabled | 不响应 | 配合 groups 做白名单 |
"group_policy": {
"default_mode": "mention-all", // 全局默认
"owner": "ou_xxx", // owner-only 时必填
"groups": { // 可选:按群覆盖
"oc_group_1": { "mode": "auto-reply" },
"oc_group_2": { "mode": "disabled" }
}
}
注意:
mention-all/auto-reply需配合allowed_users: "*",否则非白名单用户被前置过滤。设为"*"时私聊也对所有人开放。群内破坏性命令(/restart、/stop)仅 owner 可执行。
CLI 工具
Bridge 安装后提供三个 CLI 入口:
| 命令 | 说明 |
|---|---|
feishu-bridge | 主进程入口 |
feishu-cli | Bot 消息发送(send-message / send-image / send-audio) |
bridge-cli | Bridge 管理工具(后台任务等) |
飞书服务 API 操作(文档、表格、日历、任务、邮件等)使用独立的 lark CLI:
lark docs +fetch --doc doxcnXXX # 读取文档
lark docs +create --title "报告" --body "..." # 创建文档
lark sheets +read --token xxx --range A1:C10 # 读取表格
lark calendar events +list # 查看日历
lark tasks +list # 查看任务
lark mail +search --query "季度报告" # 搜索邮件
后台任务
bridge-cli bg 用于把耗时命令交给 bridge 后台执行,完成后由 bridge 注入一条 bg_task_completion 合成 turn 回到原会话。已启动的 wrapper 运行在独立 session;bridge 主进程崩溃或重启不会中断已经 launch 的任务,重启时 reconciler 会从 SQLite 和 manifest 补投完成通知。
bridge-cli bg enqueue \
--chat-id oc_xxx \
--session-id sess_xxx \
--on-done-prompt "done" \
-- sleep 10
bridge-cli bg status <task_id>
bridge-cli bg list --chat-id oc_xxx --state running
bridge-cli bg cancel <task_id>
命令必须以 argv 形式传入:优先使用 -- 分隔真实命令,或使用 --cmd-json '["python3","script.py"]'。bridge 始终用 shell=False 启动用户命令,不接受裸 shell 字符串;需要 shell 语义时显式写成 -- bash -lc '...'。
运行状态默认保存在 ~/.feishu-bridge/bg_tasks.db,任务文件默认保存在 ~/.feishu-bridge/bg_tasks/。同一台机器运行多个 bridge(例如 production + staging)时,必须给每个实例设置不同的 FEISHU_BRIDGE_BG_HOME,例如 ~/.feishu-bridge-staging,否则多个 bot 会竞争同一个 SQLite 队列和 wake.sock。完成任务会写入 completed/<task_id>/task.json.done,manifest 主要字段如下:
{
"schema_version": 2,
"task_id": "uuid4_hex",
"state": "completed",
"exit_code": 0,
"signal": null,
"duration_seconds": 1.2,
"command_argv": ["sleep", "10"],
"stdout_tail_b64": "",
"stderr_tail_b64": "",
"output_paths": [],
"on_done_prompt": "done",
"chat_id": "oc_xxx",
"session_id": "sess_xxx"
}
升级到包含后台任务的版本后,首次启动会自动创建 ~/.feishu-bridge/、bg_tasks.db、wake.sock 和 bg_tasks/ 子目录;已有目录不会被覆盖。若 bg_tasks.db 损坏,启动 reconciler 会把旧文件重命名为 bg_tasks.db.quarantine.<ts>,再从已提交的 task.json.done manifest 重建可恢复行。
部署
# systemd(Linux)
cp contrib/feishu-bridge@.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now feishu-bridge@my-bot
# launchd(macOS)
bash contrib/feishu-bridge-launcher.sh
异常退出后自动重启,editable install 下代码修改即时生效。
开发
pip install -e '.[dev]'
pytest tests/unit/ -v
License
MIT