做智能体这件事我踩过最大的坑不是模型不够聪明而是“好不容易写出来的智能体根本没人用”。你把它做成一个命令行工具自己爽同事不用你把它做成网页又要考虑登录、权限、部署。后来我把智能体全部接到飞书上群里 一下就能用表格直接推送到聊天窗口审批结果自动回填多维表格整个团队才真正把“智能体”用起来。这篇就是 copaw 实战系列的第四章重点讲清楚如何基于 copaw 把飞书集成成自动化办公智能体覆盖机器人消息收发、表格文件推送、多维表格读写、事件订阅和定时任务适合正在用飞书办公、又想把 AI 能力落到具体工作流里的朋友直接参考。1. 项目概述为什么要把智能体接进飞书先说清楚 copaw 是什么。它是我用一个开源智能体框架自己搭的一套工具层核心思路是把“大模型 工具调用 任务调度”包成一个可复用的 Agent 服务。前面三章我们分别解决了模型接入、工具注册和任务编排的问题这一章的难点不在智能体本身而在“最后一公里”怎么让智能体长在办公软件里。1.1 copaw 能干什么这章要解决什么问题copaw 本身做的事情其实很朴素你给它定义一批工具它用大模型判断该调哪个工具、传什么参数再把结果组织成人话返回。比如你给它一个“查销售数据”的工具和一个“发送飞书消息”的工具它就能自己完成“查数据→算汇总→发到群”的完整动作。这一章要解决的就是最后那段链路。飞书提供了很完整的开放 API但直接调 API 和把它封装成智能体工具中间还隔着不少脏活token 要缓存和续期消息要区分文本、富文本、卡片表格文件要先生成再上传多维表格要处理字段类型和批量写入事件回调要防重放、要做鉴权。这些脏活我全部在 copaw 内封装好让上层 Agent 只关心“该发什么内容”不关心“怎么发出去”。1.2 选飞书而不自建后台的三个理由我也考虑过自建一个 Web 后台做成类似“内部 AI 助手”的页面但对比下来还是飞书更合适。第一零安装成本。国内办公场景里飞书的普及度已经很高员工本来就在群里多一个机器人不需要任何学习成本。你建一个网页用户要收藏、要登录、要记得打开但你在群里发一个“机器人 汇总今天日志”所有人天然就会用。第二通知天然闭环。智能体的价值一半在“主动触发”比如定时推送日报、逾期提醒、审批催办。飞书消息可以直接触达手机通知栏而自建网页做不到这种渗透力。第三数据结构化。飞书多维表格本质上就是一个轻量数据库智能体可以把执行结果直接写入多维表格业务同学能自己筛、自己看不需要我给你专门做一个可视化页面。三个方案我简单做过对比列在下面供参考对比项自建 Web 后台飞书机器人备注用户学习成本高极低群里 即可主动通知能力需额外做推送自带通知体系手机端体验完整数据持久化需自己写存储多维表格现成业务方可自助分析开发成本高中等主要成本在 API 适配权限管理自己维护飞书通讯录体系企业内天然隔离2. 环境准备与整体架构设计动手写代码之前先把两边的环境准备好。一边是 copaw 运行环境一边是飞书开放平台。很多人在这一步就开始懵主要是飞书那边的概念有点多我按顺序理一遍。2.1 copaw 环境与依赖安装我用的是 copaw 的 v0.4.x 分支这个版本的工具注册和事件处理已经比较稳定。环境方面就是常规的 Python 3.10建议直接用 venv 隔离别把依赖装进系统 Python后面升级包的时候会哭。# 假设你已经 clone 了 copaw 仓库 cd copaw python3.10 -m venv .venv source .venv/bin/activate pip install -r requirements.txt # 额外安装飞书相关依赖 pip install lark-oapi requests openpyxl apscheduler这里的依赖分三块lark-oapi是飞书官方 Python SDK处理事件长连接和 API 调用最省事openpyxl用来生成 Excel 表格文件apscheduler用来做定时任务。注意copaw 每个版本对工具注册的写法略有调整我文中的代码以 v0.4.2 为准。你用新版遇到tool装饰器参数变化直接去copaw/tools/registry.py里翻一下注册逻辑就行。2.2 飞书开放平台侧准备应用、机器人、权限进入飞书开放平台创建一个“企业自建应用”名字随便起比如“办公智能体”。创建完成后主要做三件事。第一开启机器人能力。在“应用能力”里找到“机器人”启用它。启用后应用会自动获得一个机器人可以拉进群里。第二配置权限。飞书的权限模型是“先申请、后使用”你调用哪个 API 就要给应用开对应权限。我常用的一组权限列在下面实际按你的场景勾选不要全选权限过宽在审核时容易被驳回权限标识权限名称用途im:message获取群组中所有消息接收用户消息事件im:message:send_as_bot获取与发送单聊、群组消息机器人发消息im:chat获取群组信息列出群列表、获取 chat_idim:file上传获取文件上传表格文件bitable:app查看、评论、编辑和管理多维表格读写多维表格docx:document查看、评论、编辑和管理云文档读写云文档扩展用第三发布版本。企业自建应用有“创建版本并发布”的流程发布后管理员审核通过应用才能拿到真实权限。这一步很多人会漏代码写好了但一直报权限错误先检查应用版本是否已经审核通过。2.3 整体架构智能体如何调用飞书 API把整条链路的路径理清楚后面写代码才不会迷路。我的方案是三层结构飞书侧飞书开放平台提供 API 和事件推送机器人在群里接收消息。copaw 侧把飞书 API 封装成工具函数注册给 Agent同时用事件监听接收消息把用户输入交给大模型处理。业务侧业务数据放在多维表格、MySQL、内部接口里Agent 根据用户指令决定读写哪些数据。一次完整的交互长这样用户在群里发“机器人 汇总近七天销售”飞书把这条消息通过长连接推送到我们的服务copaw 拆出文本内容并交给大模型大模型决定调用“查销售数据”和“发送飞书消息”两个工具最后机器人把结果发回群里。3. 核心细节与实操要点这一节是全文最硬核的部分。飞书开放 API 本身不复杂但有不少细节藏得很深直接跑会碰一鼻子灰。我把核心能力一个个拆开讲。3.1 封装飞书客户端token 管理是第一道门槛飞书所有 API 都要求带tenant_access_token获取方式是调用一个内部接口把 App ID 和 App Secret 换成临时凭证。这个 token 有效期是 7200 秒也就是 2 小时过期后要重新获取。第一次写的时候最容易犯的错是“每次调用都重新获取 token”不仅慢而且高频调用容易触发限流。正确做法是做缓存token 在过期前一直复用过期后再刷新。我封装了一个简单的客户端类import time import requests class FeishuClient: def __init__(self, app_id: str, app_secret: str): self.app_id app_id self.app_secret app_secret self._token self._expire_at 0 def _get_token(self) - str: # token 未过期就直接复用避免频繁请求 if self._token and self._expire_at time.time() 60: return self._token resp requests.post( https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal, json{ app_id: self.app_id, app_secret: self.app_secret, }, ) data resp.json() if data.get(code) ! 0: raise RuntimeError(f获取 token 失败: {data}) self._token data[tenant_access_token] self._expire_at time.time() data[expire] return self._token def _headers(self) - dict: return { Authorization: fBearer {self._get_token()}, Content-Type: application/json; charsetutf-8, } def send_text(self, receive_id: str, text: str, receive_id_type: str chat_id) - dict: resp requests.post( https://open.feishu.cn/open-apis/im/v1/messages, params{receive_id_type: receive_id_type}, headersself._headers(), json{ receive_id: receive_id, msg_type: text, content: {\text\: \%s\} % text.replace(\, \\\), }, ) data resp.json() if data.get(code) ! 0: raise RuntimeError(f发送消息失败: {data}) return data注意receive_id_type可以是chat_id群、open_id用户、user_id用户等。在群机器人场景里我最常用的是chat_id因为不管谁 机器人消息都会落在同一个群回同一个群最符合用户预期。3.2 消息收发从文本到富文本再到卡片文本消息只适合简单通知真正好用的是消息卡片。卡片本质是一段 JSON 结构可以呈现标题、字段、按钮按钮还能触发回调这是做审批类智能体的关键能力。先明确消息类型text是纯文本post是富文本可以带标题和多行interactive是消息卡片file是文件消息image是图片。我用得最多的是text和interactive。卡片长这样一个带标题、两个字段、一个按钮的结构{ config: {wide_screen_mode: true}, header: { title: {tag: plain_text, content: 审批待办提醒}, template: orange }, elements: [ { tag: div, text: {tag: lark_md, content: **申请人**: 张三\n**金额**: 12,500 元} }, { tag: action, actions: [ { tag: button, text: {tag: plain_text, content: 去审批}, type: primary, value: {approval_id: A-202406-001} } ] } ] }发送卡片时把msg_type设为interactivecontent字段传这段 JSON 的字符串形式。按钮点击后飞书会向你的应用推送card.action.trigger事件携带value里的自定义数据。我把它注册成智能体的一个事件入口用户点“去审批”就会自动触发后续流程。注意value里只能放简单类型别放长文本或敏感信息。按钮回调的完整上下文建议用 ID 关联服务端数据而不是把全部数据塞进卡片。3.3 上传并发送表格文件群里发表格是老板最喜欢的功能。飞书不能直接“用文本生成一个 xlsx 文件再发到聊天”这种高级操作需要我们自己在本地生成表格文件然后调用上传接口拿到file_key最后发一条file类型消息。生成表格我用openpyxl按业务需求写入数据和样式from openpyxl import Workbook def build_report_xlsx(path: str, headers: list, rows: list[list]) - str: wb Workbook() ws wb.active ws.append(headers) for row in rows: ws.append(row) # 简单美化表头加粗、加底色 for cell in ws[1]: cell.font cell.font.copy(boldTrue) cell.fill FFFF00 # 实际上这里要设置 PatternFill演示略 for col in ws.columns: width max(len(str(cell.value)) for cell in col if cell.value) 2 ws.column_dimensions[col[0].column_letter].width width wb.save(path) return path上传文件要特别注意请求格式它是multipart/form-data不是 JSONdef upload_and_send_file(self, receive_id: str, file_path: str, file_name: str): with open(file_path, rb) as f: resp requests.post( https://open.feishu.cn/open-apis/im/v1/files, headers{Authorization: fBearer {self._get_token()}}, data{file_type: xlsx, file_name: file_name}, files{file: (file_name, f)}, ) data resp.json() file_key data[data][file_key] # 发送文件消息 content {\file_key\: \%s\} % file_key return self.send_msg(receive_id, file, content)文件大小限制是 30MB一般报表远达不到。如果表格特别大优先考虑拆分成多个 sheet 或者只推送汇总摘要避免文件过大导致发送超时。3.4 多维表格读写把智能体变成“数据管道”多维表格是飞书最有价值的能力相当于“给人看的 Excel 给机器人用的数据库”。我在智能体里最常用的操作是新增记录、更新记录、查询记录。先拿到app_token和table_id。在多维表格的网址里就能看到格式是https://xxx.feishu.cn/base/{app_token}?table{table_id}。然后在飞书开放平台把应用添加为这个多维表格的协作者否则没有读写权限。新增一条记录def add_record(self, app_token: str, table_id: str, fields: dict): resp requests.post( fhttps://open.feishu.cn/open-apis/bitable/v1/apps/{app_token}/tables/{table_id}/records, headersself._headers(), json{fields: fields}, ) data resp.json() if data.get(code) ! 0: raise RuntimeError(f新增记录失败: {data}) return data[data][record]这里的fields字段名必须与多维表格的列名完全一致包括空格和括号。最常见的坑是把列名写错飞书不会直接告诉你“字段不存在”而是报一个含糊的params error排查半天才发现是列名多了一个空格。批量写入时飞书单次接口最多支持灵活控制如果是几百条数据建议分批写入每批 50~100 条并在中间加一个很小的 sleep防止触发并发限制。写入前可以先调用“列出字段”接口核对一遍字段 ID 和类型这一步能省很多调试时间。4. 实战构建自动化办公智能体基础知识都点到了下面搭一个完整场景。我给一个比较有代表性的组合定时推送日报 群聊指令响应 表格自动生成与发送 审批卡片提醒。这套流程几乎覆盖了办公室最常见的四类需求。4.1 场景设计日报提醒、数据汇总、待办催办先说业务目标。场景一每天早上 9 点 30 分智能体自动从多维表格读取当天的销售明细汇总成一张报表推送到管理群。场景二员工在群里 机器人说“查一下上周的请假记录”智能体自动查询多维表格并把结果整理成摘要回复。场景三审批流程中有超时未处理的单据智能体主动推送一张卡片提醒审批人。这三个场景在工程上是同一套底座定时任务触发 工具调用 消息发送。区别只在于触发源不同一个来自 cron一个来自群消息。4.2 接入大模型与工具调用在 copaw 里我先把前面封装好的飞书客户端注册成工具这样大模型才知道“有这个能力可用”。工具注册的核心是给每个函数写清楚参数描述模型是靠描述来选工具的描述写得不清楚它就会选错。from copaw.agent import Agent from copaw.tools import tool tool(send_feishu_text, 发送飞书文本消息receive_id 是群聊 IDtext 是内容) def send_feishu_text(receive_id: str, text: str) - str: client feishu_client() return str(client.send_text(receive_id, text)) tool(query_bitable, 查询多维表格中的记录app_token 是表格应用 IDtable_id 是表 IDfilter 是过滤条件) def query_bitable(app_token: str, table_id: str, filter: str ) - str: client feishu_client() records client.list_records(app_token, table_id, filter_strfilter) return str(records) agent Agent(tools[send_feishu_text, query_bitable, send_feishu_file])然后配置好大模型 API这一步在 copaw 的配置文件里完成和前面几章一致。实际运行时用户在群里发“汇总一下销售数据并发到群里”大模型就会按顺序调用“查多维表格”和“发送消息”两个工具。4.3 定时任务与服务启动的完整示例定时任务我用apscheduler。把每天 9 点 30 分推送日报定义成一个 job再把飞书事件监听器跑起来整个服务就是一个“常驻进程”。from apscheduler.schedulers.blocking import BlockingScheduler from lark_oapi.ws import Client as WsClient def daily_report_job(): app_token bascnxxxxx table_id tblxxxxx records feishu_client().list_records(app_token, table_id, page_size200) summary summarize(records) # 业务侧逻辑 headers [日期, 销售额, 订单数, 转化率] rows [summary] build_rows_from_records(records) file_path daily_report.xlsx build_report_xlsx(file_path, headers, rows) feishu_client().upload_and_send_file(oc_xxxxx, file_path, 日报_20240701.xlsx) if __name__ __main__: scheduler BlockingScheduler(timezoneAsia/Shanghai) scheduler.add_job(daily_report_job, cron, hour9, minute30) scheduler.start()事件监听部分用官方 SDK 的长连接模式不用暴露公网地址本地调试非常方便from lark_oapi.ws import Client as WsClient def handle_message(data): # data 里包含 chat_id、open_id、text 等 text extract_text(data) reply agent.run(text) # 交给 copaw 智能体处理 feishu_client().send_text(data.chat_id, reply) ws_client WsClient( app_id, app_secret, event_handlerhandle_message, ) ws_client.start()注意长连接模式不需要公网回调地址适合开发环境。生产环境如果要上多实例我建议改成 Webhook 模式配合回调 URL 和加解密策略但代码逻辑基本通用。5. 常见问题与排查技巧实录写集成的时候我几乎把飞书开放平台的报错都踩了一遍。这里挑最典型的问题整理成速查表并附上排查思路能帮你少走半天弯路。5.1 鉴权与权限类问题这类问题占了我早期调试八成的时间核心特征是接口报错 code 不是 0或者直接返回 403、401。错误现象可能原因排查方法code 99991672tenant_access_token 无效检查 token 是否过期、是否手动拼错code 99991663app 未开启机器人能力到飞书开放平台确认机器人已启用code 91663权限不足到权限管理里勾选对应权限并重新发布版本403 无权限访问应用不是多维表格协作者在多维表格共享设置里添加应用为协作者我最想强调的一点改完权限一定要“创建版本 → 申请发布 → 管理员审核通过”只在后台勾选权限没有用必须发布新版本才会真正生效。5.2 消息发送与文件上传类问题错误现象可能原因排查方法receive_id 无效chat_id 是旧的或来自别的租户通过事件数据重新获取 chat_id别用拼出来的字符串文件上传成功但消息为空file_key 用错或文件已过期文件要在同一租户下、短时间内发送消息内容里有引号导致 JSON 解析失败content 是 JSON 字符串转义没做好用 json.dumps 而不是手工拼字符串卡片按钮点击无反应value 里带中文或特殊字符只放 ID 等纯字母数字内容卡片按钮回调是我遇到过比较隐蔽的问题。飞书卡片按钮的value只支持字符串、数字、布尔值我一开始把整个审批对象塞进去结果点击后事件里 value 为空。改成只传approval_id再在服务端查详情问题就消失。5.3 事件订阅与长连接问题长连接模式在本地调试很好用但也有人卡在“连不上”或“收不到事件”上。第一确保应用已经开启“事件订阅”并且订阅了对应事件。机器人要接收消息至少订阅im.message.receive_v1。订阅后要等待几分钟才能生效。第二长连接模式需要确保网络可以访问飞书 WebSocket 网关。在办公网内一般没问题但有些严格限制外联的网络环境会连不上这种情况可以临时把事件转发到本机调试。第三消息事件里拿到的chat_id在机器人被移出群后会失效重进群会生成新的chat_id。如果你把 chat_id 写死在配置里注意机器人重新入群后要更新。5.4 我的避坑清单所有发送给飞书的消息内容如果包含用户输入的文本务必做转义否则含引号、换行的内容会直接报错。在真实企业里建议所有写操作比如新增多维表格记录先走“预览确认”或“二次确认”流程避免智能体误操作。不要把app_secret写死在代码仓库里。用环境变量或密钥管理服务安全意识要有。调试时多打印飞书返回的原始 JSON很多问题的答案都藏在msg字段里而不是表面错误码。6. 扩展思路与个人体会飞书集成能做的东西远不止发消息和查表格。顺着这条链路往下走能演化出很多实用玩法但每一步都有取舍我说说自己的想法。6.1 从被动回复到主动智能的四个进阶方向第一个方向是“审批自动化”。机器人收到审批卡片按钮回调后自动读取单据详情调用 LLM 生成审批摘要和风险提示帮审批人快速做决策。这个场景不追求 AI 替你审批而是替你把阅读成本降到最低。第二个方向是“知识库问答”。飞书文档、知识库里沉淀了大量公司资料把这些内容做向量化让智能体在群里回答问题。难点是文档权限控制和切片策略但价值非常直接能明显减少办公群里的重复提问。第三个方向是“定时报表中心”。我们目前的日报还是固定的一张大表再往前一步可以让智能体每天早上根据前一天的异常自动生成“哪些指标异常、需要关注什么”推送一段带结论的文字而不是一张单纯的数据表。第四个方向是“多智能体协作”。让一个智能体负责访问多维表格另一个负责生成图表另一个负责发送消息它们之间通过 copaw 的任务编排协作。每个智能体只维护一小块能力整体可控性强出了故障也好排查。6.2 我踩过坑之后的几条心得从“能跑 demo”到“能长期稳定跑”之间隔着大量工程细节。我实际用了三个月最大的体会是不要一开始就追求“全自动”先做“半自动”更稳妥。比如多维表格写入先让智能体生成预览用户确认后再落库。又比如文件推送先只推摘要用户需要明细时再生成完整 Excel。这样既不会因为模型误操作造成数据问题也更容易让团队接受。还有一点日志要做好。飞书事件是无状态的一旦服务重启、消息丢失用户重新 一次可能就没事但如果是定时报表漏发一整天没人发现。我后来给每个 job 都加了执行日志记录“触发时间、执行结果、异常堆栈”每天早上顺手看一眼日志比事后被问“报表呢”舒服太多。最后再说一个小技巧。飞书机器人的名字其实就是用户感知的产品品牌我见过很多团队把机器人直接沿用应用名但更好的做法是给人格化命名比如“小助”。机器人在群里回复时开头直接说“我帮你查到了……”用户的接受度和使用频率会明显好于冷冰冰的接口回复。这个细节不影响功能但影响着智能体是否真的能被团队用起来。