飞书 (Lark / Feishu) 集成

能力全景

Rendering diagram…

能力总览

能力分类	覆盖	典型用法
即时通讯（IM）	群聊 / 单聊发消息 / 接收 / 历史搜索	Channel 入口、结果回推、通知
云文档（Docx）	创建 / 读取 / 增量更新 / 图片上传	Agent 输出成文
多维表格（Base）	建表、字段、记录、视图、工作流	工单 / 看板 / KPI 记分卡
电子表格（Sheet）	批量读写、公式、导出	测试矩阵、覆盖率报表
幻灯片（Slides）	创建、按页更新	周报、评审材料
画板（Whiteboard）	PlantUML / Mermaid / DSL 生图	架构图、时间线
日历	日程 / 闲忙 / 会议室	会议自动安排
审批	实例 / 任务	流程自动化
妙记 / 视频会议	查询、下载、纪要 AI 产物	周报/会议纪要整理
通讯录	员工查询	身份映射
邮件 / OKR / Wiki	全量封装	细分场景

前置条件

开放平台侧：管理员在 open.feishu.cn 创建自建应用。

**需要的权限（scope）**按使用场景勾选。常用套餐：

套餐	需要的 scope
IM 对话 + Docx	`im:`, `docx:`, `drive:drive:readonly`
多维表格	`bitable:*`
日历 + 会议	`calendar:`, `vc:`
全家桶	以上全部 + `contact:user.base:readonly` 等

配置步骤

步骤 1：创建凭据

管理台 → 集成 → 飞书 → 新增：

App ID：开放平台 → 凭证与基础信息
App Secret：同上
App Type：self_hosted（自建）或 isv（ISV 应用）
Encrypt Key / Verification Token：如果订阅事件，必须填

或 CLI：

lark-cli config init
lark-cli auth login         # 用户身份
lark-cli auth login --as bot  # 机器人身份

步骤 2：订阅事件（需要 Channel 能力时）

在开放平台 → 事件与回调 → 设置 Webhook URL：

https://<combo-agent>/v1/webhook/lark

勾选要订阅的事件：

im.message.receive_v1（收消息）
im.chat.member.user.added_v1（入群）
按需勾选

步骤 3：绑定到 Agent

channels:
  - type: lark
    credential_id: <cred_id>
    bot_name: "combo-agent"
    chat_filter:
      # 只处理特定群或 @bot 的消息
      mention_only: true
      chat_ids: ["oc_xxx", "oc_yyy"]

身份：User vs Bot

模式	适用	限制
Bot（应用身份）	群里统一机器人、回群消息	只能访问机器人被加入的群 / 有权限的文档
User（OAuth 用户）	代用户操作：查我的日程、读我的邮件	需要用户 OAuth 授权；作用域受限于该用户权限

多数"办公助手"型场景是两者混用：群聊交互用 Bot，涉及"我的 XX"查询走 User。

文件 / 图片 / 附件

发送图片：先 upload_image 拿到 image_key，再带在消息里
发送文件：upload_file，得到 file_key
下载消息里的文件：get_message_resource

常见坑位

问题	解决
`99991663` Permission denied	检查 scope 是否勾选 + 应用是否已发布
机器人收不到消息	检查事件订阅 URL 是否回调成功（面板里看"事件回调历史"）
OAuth 授权后仍然 401	Token 过期；走 `user_access_token` refresh 流程
文档无权限读	机器人要被拉进文档的协作者，或把文档所在知识库分享给它
回调 URL 验签失败	`Encrypt Key` / `Verification Token` 要同时填对