飞书自动化脚本开发指南：从API集成到智能审批机器人实战

1. 项目概述：飞书自动化，从“手动”到“自动”的效能革命

如果你每天的工作，有超过30%的时间是在飞书里重复点击、复制粘贴、手动发送消息和整理表格，那么“cicbyte/feishu-atuo”这个项目，很可能就是你一直在寻找的“数字员工”。这是一个专注于飞书平台自动化操作的GitHub开源项目，其核心价值在于，通过编写脚本，将那些繁琐、重复、规则明确的飞书操作流程自动化，从而将你从枯燥的“人肉操作”中解放出来，专注于更有创造性的工作。

简单来说，它不是一个现成的软件，而是一个技术工具箱和一套方法论。它基于飞书开放平台提供的API，允许开发者（甚至是有一定编程基础的普通用户）用代码来“指挥”飞书，实现诸如自动发送消息、批量处理审批、智能同步文档数据、监控群消息并自动回复等一系列功能。想象一下，每天早上9点，一个机器人准时在项目群发送今日待办；每当有新的审批单提交，系统能自动根据规则进行预审并通知相关负责人；或者将飞书多维表格的数据与公司内部系统实时同步，无需人工介入——这些就是“feishu-atuo”能帮你实现的场景。

这个项目特别适合几类人：一是中小团队的开发者或技术负责人，希望低成本构建内部自动化流程；二是个人开发者或技术爱好者，想通过实战项目学习API集成与自动化技术；三是业务人员中的“效率达人”，虽然不写代码，但可以明确需求，与技术人员协作落地自动化方案。接下来，我将以一个多年实践者的角度，为你彻底拆解这个项目的核心思路、技术实现与避坑指南。

2. 核心思路与架构设计：为什么是“脚本化”自动化？

在深入代码之前，我们必须先理解这个项目背后的设计哲学。市面上也有不少RPA（机器人流程自动化）工具可以实现类似功能，那为什么还要选择基于代码的“feishu-atuo”呢？核心答案在于：灵活性、可控性与集成深度。

2.1 脚本化 vs 可视化工具：各有千秋的赛道

可视化RPA工具（如某些商业软件）的优势是上手快，通过拖拽就能设计流程。但其劣势也很明显：处理复杂逻辑时显得笨重；难以与自研系统深度集成；流程修改和维护成本可能随着复杂度上升而剧增；而且通常涉及许可费用。

“feishu-atuo”代表的脚本化方案，则把控制权完全交给了开发者。你可以用Python、JavaScript等熟悉的语言，精确控制每一个API调用的时机、参数和异常处理。这意味着：

1. 逻辑无限复杂：你可以轻松实现“如果审批人是A且金额大于X，则转发给B并@C，同时从数据库查询历史记录附加在评论中”这样的复杂逻辑，这是拖拽工具难以优雅实现的。
2. 无缝集成：自动化脚本可以和你现有的代码库、数据库、中间件、CI/CD流水线放在一起，成为公司技术栈的自然延伸。
3. 成本可控：核心依赖是飞书开放平台（基础功能免费）和一台可以运行脚本的服务器（甚至可以是免费的云函数），前期投入主要是开发时间。

因此，这个项目的定位非常清晰：为开发者提供一个高质量的、针对飞书API的代码范例和工具集，降低自动化脚本的开发门槛，而非做一个大而全的通用自动化平台。

2.2 项目核心架构猜想与模块划分

虽然我无法看到项目仓库内的具体代码结构，但根据其命名（feishu-atuo， auto拼写可能为笔误，意指自动化）和常见的最佳实践，一个成熟的飞书自动化项目通常会包含以下几个核心模块：

1. 认证与授权模块：这是所有操作的基石。负责处理App ID、App Secret，获取和管理tenant_access_token（企业授权令牌）或user_access_token（用户授权令牌）。这个模块必须妥善处理令牌的刷新机制，因为飞书的访问令牌有效期通常为2小时。
2. API客户端封装模块：将飞书开放平台繁杂的REST API封装成更易用的函数或类方法。例如，send_message(bot_id, content_type, content)、get_sheet_data(spreadsheet_token, range)等。好的封装能隐藏HTTP请求细节、统一错误处理，让业务逻辑更清晰。
3. 业务逻辑核心模块：这是实现具体自动化场景的地方。比如“每日站会提醒机器人”、“审批流程自动分发器”、“文档变更监听器”等。每个场景可能是一个独立的脚本或一个模块下的类。
4. 配置与数据管理模块：用于管理机器人密钥、目标群聊ID、模板内容、规则条件等配置信息。通常使用配置文件（如config.yaml）、环境变量或简单的数据库来存储。
5. 任务调度与执行模块：负责定时触发或事件驱动自动化任务。轻量级方案可以用操作系统的crontab（Linux）或Task Scheduler（Windows），更现代的方案是集成Celery、APScheduler或直接部署到云函数（如腾讯云SCF、阿里云FC）上，由云服务提供定时触发器。
6. 日志与监控模块：记录脚本的运行日志、成功/失败状态，对于排查问题和了解自动化运行健康度至关重要。可以简单输出到文件，也可以集成到公司的ELK（Elasticsearch, Logstash, Kibana）或Sentri等监控体系中。

一个典型的自动化流程是这样的：调度器触发->认证模块获取有效Token->业务逻辑模块调用封装好的API客户端->处理返回数据或执行操作->记录日志。整个架构清晰解耦，便于维护和扩展。

3. 从零开始：构建你的第一个飞书自动化机器人

理论讲完，我们动手实战。假设我们要实现一个最常见的场景：工作日早上10点，向指定的飞书群发送一条今日天气和待办事项提醒。

3.1 前期准备：获取“通行证”

在写代码之前，你需要先在飞书开放平台创建一个应用，并获取必要的凭证。这个过程就像为你即将创造的机器人办理入职手续。

1. 创建企业自建应用：

   • 访问 飞书开放平台 ，使用你的飞书账号登录（通常需要一个管理员账号或创建应用的权限）。
   • 进入“开发者后台”，点击“创建企业自建应用”。
   • 填写应用名称（如“每日提醒小助手”）、描述，并上传应用图标。

2. 获取关键凭证：

   • 应用创建成功后，在“凭证与基础信息”页面，你会找到至关重要的App ID和App Secret。请像保管密码一样保管好它们，后续代码中会用到。

3. 配置应用权限：

   • 在“权限管理”页面，为你的应用添加所需权限。对于“发送消息到群聊”这个功能，你至少需要添加im:message权限下的发送单聊、群组消息权限。请根据你的实际需求，仔细阅读并添加其他权限（如读取用户信息、操作云文档等）。

4. 发布与启用：

   • 在“版本管理与发布”中，创建一个版本并申请发布。通常需要由企业的超级管理员审核通过后，应用才能在企业内生效。
   • 重要步骤：将应用添加到机器人需要操作的群聊中。在群聊设置中，找到“群机器人”，点击“添加机器人”，选择你刚刚创建的应用。

注意：飞书的权限体系非常细致。务必遵循“最小权限原则”，只申请业务必需权限。权限申请后需要发布新版本才能生效。另外，机器人必须被添加到群聊中，才能向该群发送消息，否则会报“无权限”错误。

3.2 核心代码实现：让机器开口说话

我们使用Python语言，因为它语法简洁、生态丰富，是自动化脚本的首选。你需要先安装飞书官方SDK：pip install lark-oapi。

# config.py - 配置文件，用于存放敏感信息和常量 import os from dotenv import load_dotenv load_dotenv() # 从 .env 文件加载环境变量 class Config: APP_ID = os.getenv("FEISHU_APP_ID") APP_SECRET = os.getenv("FEISHU_APP_SECRET") # 你希望发送消息的群聊ID。获取方法：在飞书群中，点击群设置->群组ID GROUP_CHAT_ID = os.getenv("FEISHU_GROUP_CHAT_ID") # .env 文件内容示例 (切记不要提交到代码仓库！) # FEISHU_APP_ID=cli_xxxxxx # FEISHU_APP_SECRET=xxxxxx # FEISHU_GROUP_CHAT_ID=oc_xxxxxx

# feishu_client.py - 封装飞书API客户端 from lark_oapi import Client, logger from lark_oapi.api.im.v1 import * from config import Config class FeishuClient: def __init__(self): # 初始化客户端，自动处理token获取和刷新 self.client = Client.builder() \ .app_id(Config.APP_ID) \ .app_secret(Config.APP_SECRET) \ .log_level(logger.LogLevel.INFO) \ .build() def send_group_text_message(self, content, receive_id=None): """ 向群聊发送文本消息 :param content: 消息文本内容 :param receive_id: 群聊ID，默认为配置中的GROUP_CHAT_ID :return: 发送结果 """ if receive_id is None: receive_id = Config.GROUP_CHAT_ID # 构建请求对象 request = CreateMessageRequest.builder() \ .receive_id_type("chat_id") \ .request_body(CreateMessageRequestBody.builder() .receive_id(receive_id) .msg_type("text") .content(json.dumps({"text": content})) .build()) \ .build() try: # 发起API调用 response = self.client.im.v1.message.create(request) if response.code == 0: print(f"消息发送成功! Message ID: {response.data.message_id}") return response.data else: print(f"消息发送失败! Code: {response.code}, Msg: {response.msg}") return None except Exception as e: print(f"请求飞书API时发生异常: {e}") return None # 你可以继续在这里添加其他API封装方法，如发送富文本卡片、获取群成员等

# daily_reminder.py - 业务逻辑：组装消息并发送 import datetime from feishu_client import FeishuClient def get_today_info(): """获取今日信息，这里可以集成天气API、待办事项API等""" today = datetime.datetime.now() weekday = ["一", "二", "三", "四", "五", "六", "日"][today.weekday()] date_str = today.strftime("%Y年%m月%d日") # 模拟获取天气 (实际应调用天气API，如和风天气、心知天气) # 这里为了示例，使用一个固定文本。实际项目中，你可以用requests库调用第三方API。 weather_info = "晴， 18~26°C， 空气质量良" # 模拟从任务管理系统获取待办 (实际应调用内部API或读取数据库) todos = [ "完成项目周报撰写", "与设计团队评审UI方案", "跟进客户A的反馈", ] todo_text = "\n".join([f"• {item}" for item in todos]) return date_str, weekday, weather_info, todo_text def main(): """主函数：组装并发送每日提醒""" # 1. 获取今日信息 date_str, weekday, weather, todos = get_today_info() # 2. 组装消息内容 message_content = f"""各位同事，早上好！⏰ 今天是{date_str}，星期{weekday}。 【今日天气】{weather} 【今日重点待办】 {todos} 祝大家工作顺利，高效每一天！🚀 """ # 3. 发送消息 client = FeishuClient() result = client.send_group_text_message(message_content) if result: print("每日提醒发送任务执行成功！") else: print("每日提醒发送任务执行失败，请检查日志。") if __name__ == "__main__": main()

以上就是一个最精简但完全可运行的飞书群消息自动化发送脚本。你可以通过直接运行python daily_reminder.py来测试。但我们的目标是自动化，所以还需要最后一步：定时任务。

3.3 部署与调度：让机器人按时上班

让脚本定时运行有多种方式，这里介绍两种最常用的：

方案一：使用服务器Crontab（经典可靠）如果你的脚本部署在一台长期运行的Linux服务器上，crontab是最直接的选择。

1. 确保你的Python脚本有可执行权限，并且在脚本开头指定了解释器（#!/usr/bin/env python3）。
2. 编辑当前用户的crontab：crontab -e
3. 添加一行配置，表示每周一到周五的早上10点执行：

   0 10 * * 1-5 cd /path/to/your/script && /usr/bin/python3 /path/to/your/script/daily_reminder.py >> /tmp/feishu_bot.log 2>&1

   • 0 10 * * 1-5：分钟(0) 小时(10) 日 月 星期(1-5，周一到周五)。
   • cd /path/to/your/script：确保脚本在执行时位于正确的目录，以便读取相对路径的配置文件。
   • >> /tmp/feishu_bot.log 2>&1：将脚本的标准输出和错误输出都重定向到日志文件，便于排查问题。

方案二：使用云函数（Serverless，更现代）以腾讯云云函数（SCF）为例，你无需管理服务器。

1. 将你的代码（包括config.py,feishu_client.py,daily_reminder.py和.env文件中的值转为环境变量）打包成一个ZIP文件。
2. 在腾讯云SCF控制台创建一个新的函数，运行环境选择Python 3.7+。
3. 上传ZIP包，将执行方法设置为daily_reminder.main（假设你的入口函数是main）。
4. 在“触发管理”中，添加一个“定时触发”，使用Cron表达式0 0 10 ? * MON-FRI *（表示每周一到周五UTC时间10点，注意时区转换，北京时间为UTC+8，所以应设置为0 0 2 ? * MON-FRI *）。
5. 在“环境配置”中，设置FEISHU_APP_ID、FEISHU_APP_SECRET等环境变量。

云函数的优势是无需运维服务器，按实际运行次数计费，通常有充足的免费额度，非常适合这种轻量级定时任务。

4. 进阶实战：构建一个智能审批辅助机器人

发送固定消息只是开胃菜。自动化真正的威力在于处理业务流程。让我们实现一个更复杂的场景：监控飞书审批实例，当有“请假审批”提交时，自动根据请假天数和申请人所在部门，计算需要额外抄送的主管，并自动评论提醒。

这个场景涉及了事件订阅和主动API调用的结合，是自动化中非常典型的模式。

4.1 配置事件订阅：让飞书主动通知我们

飞书开放平台提供了“事件订阅”功能。当应用拥有相关权限后，飞书服务器会在特定事件（如审批实例状态变更、新消息、用户入职等）发生时，向你的服务器配置的一个URL（称为“回调地址”）发送HTTP POST请求。

1. 权限申请：在应用权限管理中添加approval:approval:read和approval:approval:update权限，用于读取审批详情和添加评论。
2. 配置事件：在开发者后台“事件订阅”页面，添加“审批事件”订阅。你需要填写：
   • 请求地址 URL：一个公网可访问的、由你开发的API接口地址。开发测试阶段，可以使用ngrok、localtunnel等工具将本地服务暴露到公网。
   • 加密密钥与验证令牌：飞书用于加密和验证请求的凭证，需要在你的服务端代码中配置，以确保请求来源的合法性。
3. 挑战验证：保存配置时，飞书会向你的URL发送一个携带challenge参数的GET请求，你的服务端必须原样返回这个challenge值，以验证URL的有效性。

4.2 服务端核心代码实现

我们需要一个简单的Web服务器来接收飞书的事件回调。这里使用轻量级的Flask框架。

# app.py - 事件订阅服务端 from flask import Flask, request, jsonify import json import hashlib import hmac import base64 from feishu_client import FeishuClient # 复用之前的客户端 from approval_handler import process_approval_event # 业务处理函数 app = Flask(__name__) # 从环境变量获取飞书事件订阅的验证凭证 VERIFICATION_TOKEN = os.getenv("FEISHU_VERIFICATION_TOKEN") ENCRYPT_KEY = os.getenv("FEISHU_ENCRYPT_KEY") def verify_signature(timestamp, nonce, body, signature): """验证飞书事件回调的签名""" content = f"{timestamp}\n{nonce}\n{body}\n" key = ENCRYPT_KEY.encode('utf-8') msg = content.encode('utf-8') h = hmac.new(key, msg, digestmod=hashlib.sha256) return base64.b64encode(h.digest()).decode('utf-8') == signature @app.route('/feishu/event', methods=['POST', 'GET']) def handle_event(): """处理飞书事件订阅回调""" if request.method == 'GET': # URL验证挑战 challenge = request.args.get('challenge') return jsonify({'challenge': challenge}) elif request.method == 'POST': # 处理事件推送 headers = request.headers timestamp = headers.get('X-Lark-Request-Timestamp') nonce = headers.get('X-Lark-Request-Nonce') signature = headers.get('X-Lark-Signature') body = request.get_data(as_text=True) # 1. 验证签名 if not verify_signature(timestamp, nonce, body, signature): return jsonify({'error': 'Invalid signature'}), 403 data = json.loads(body) # 2. 处理加密（如果配置了加密） if data.get('encrypt'): # 此处省略解密逻辑，官方SDK有提供工具类 pass # 3. 判断事件类型并处理 event_type = data.get('header', {}).get('event_type') if event_type == 'approval.updated': # 审批状态更新事件 event = data.get('event', {}) instance_code = event.get('instance_code') status = event.get('status') if status == 'PENDING': # 审批单提交，待审批 # 异步处理，避免超时 import threading thread = threading.Thread(target=process_approval_event, args=(instance_code,)) thread.start() return jsonify({'message': 'Event received and processing.'}), 200 # 返回成功响应，告知飞书服务器已收到 return jsonify({'message': 'Event received.'}), 200 if __name__ == '__main__': app.run(host='0.0.0.0', port=5000, debug=False)

# approval_handler.py - 审批事件业务处理逻辑 import json from feishu_client import FeishuClient from datetime import datetime client = FeishuClient() def process_approval_event(instance_code): """处理审批单提交事件""" print(f"开始处理审批实例: {instance_code}") # 1. 获取审批实例详情 # 这里需要调用飞书【获取审批实例详情】API，为简化示例，假设我们有一个封装好的方法 approval_detail = client.get_approval_instance(instance_code) if not approval_detail: return # 2. 解析审批信息 form_data = approval_detail.get('form', []) approval_name = approval_detail.get('approval_name') user_id = approval_detail.get('user_id') # 申请人ID # 假设这是一个“请假审批”，表单中有“请假类型”、“开始时间”、“结束时间”、“部门”等字段 # 我们需要从form_data这个列表中，根据字段名找到对应的值 leave_type = None start_time = None end_time = None department = None for item in form_data: if item.get('name') == '请假类型': leave_type = item.get('value') elif item.get('name') == '开始时间': start_time = int(item.get('value')) / 1000 # 时间戳转换 elif item.get('name') == '结束时间': end_time = int(item.get('value')) / 1000 elif item.get('name') == '部门': department = item.get('value') # 3. 业务规则判断：是否需要额外抄送？ extra_cc_users = [] comment = "" if leave_type and start_time and end_time: # 计算请假天数 from datetime import datetime days = (datetime.fromtimestamp(end_time) - datetime.fromtimestamp(start_time)).days + 1 # 规则示例：技术部员工请假超过3天，需要抄送技术总监 if department == "技术部" and days > 3: # 这里需要根据“技术总监”这个角色，去查找对应的用户ID。实际中可能需要维护一个部门-角色-用户ID的映射。 # 假设我们已经通过其他API查到了技术总监的ID是 `ou_xxxxxx` tech_director_id = "ou_xxxxxx" extra_cc_users.append(tech_director_id) comment += f"本次请假超过3天，已自动抄送技术总监。\n" # 规则示例：任何部门请假超过5天，需要抄送HRBP if days > 5: hrbp_id = "ou_yyyyyy" # HRBP的用户ID if hrbp_id not in extra_cc_users: extra_cc_users.append(hrbp_id) comment += f"本次请假超过5天，已自动抄送HRBP。\n" # 4. 执行操作：添加评论和抄送 if comment: # 添加评论 client.add_approval_comment(instance_code, comment) print(f"已为审批单 {instance_code} 添加评论: {comment}") if extra_cc_users: # 抄送人员 (飞书审批有专门的抄送字段或API，这里示意) # 实际可能需要调用【更新审批实例】API，或在添加评论时@相关人员。 # 一种常见做法是在评论中@用户，飞书会通知对方。 mention_text = " ".join([f"<at user_id=\"{uid}\"></at>" for uid in extra_cc_users]) final_comment = f"{comment}\n 请相关主管知悉：{mention_text}" client.add_approval_comment(instance_code, final_comment) print(f"已抄送相关人员: {extra_cc_users}") print(f"审批实例 {instance_code} 处理完毕。")

这个例子展示了自动化如何介入业务流程。它监听审批提交事件，获取详细信息，根据预设的业务规则（部门、时长）进行逻辑判断，并自动执行后续操作（添加评论、@相关人员）。这极大地减少了审批发起人和审批人的沟通成本，确保了公司制度的自动执行。

5. 避坑指南与最佳实践：来自一线的经验

在实际开发和运维飞书自动化脚本的过程中，我踩过不少坑，也总结了一些让项目更稳健、更易维护的经验。

5.1 高频问题与解决方案速查表

5.2 提升脚本健壮性的关键技巧

1. 令牌管理是生命线：绝对不要硬编码App Secret，务必使用环境变量或配置中心。利用官方SDK的Token管理机制，它帮你处理了缓存和刷新。如果是自实现，务必做好令牌的缓存（如存到Redis），并在每次API调用前检查有效期。

2. 异步处理与幂等性：对于事件回调，尤其是处理可能耗时的业务逻辑（如调用外部API、复杂计算），一定要在验证请求合法性后，立即返回成功响应给飞书服务器（避免超时），然后将实际处理逻辑放入消息队列或线程池异步执行。同时，确保你的处理逻辑是幂等的，即同一事件被重复推送（网络原因可能导致）时，不会产生副作用（如重复发送消息、重复更新数据库）。

3. 全面的日志与监控：日志是你的“黑匣子”。记录关键步骤（开始处理、调用哪个API、得到什么结果、遇到什么错误）、请求ID和上下文信息。不仅记录到文件，在条件允许下，可以接入像Sentry这样的错误监控平台，或推送到飞书群、钉钉群做实时告警。

4. 配置驱动，而非硬编码：群聊ID、规则阈值（如请假几天要抄送）、模板消息内容等，都应该抽离到配置文件或数据库中。这样当业务规则变化时，你不需要修改代码，只需更新配置，然后优雅地重启服务或让服务热加载配置。

5. 做好异常防御：网络会波动，API会限流，外部服务会宕机。你的代码必须对所有这些情况有预案。对飞书API的调用一定要有重试机制（特别是对于5xx错误），并设置合理的退避策略（如指数退避）。对于非核心逻辑，可以考虑使用try...except包裹并记录错误，让主流程继续，而不是整个脚本崩溃。

6. 版本控制与文档：将你的自动化脚本像正式项目一样用Git管理。清晰的README.md应该说明项目目的、环境搭建、配置方式、部署步骤。复杂的业务规则，应该在代码注释或独立文档中说明。这对自己日后维护和团队协作至关重要。

飞书自动化不是一个高不可攀的技术，它更像是一种“效率思维”的工程化实践。从一个小而美的定时提醒开始，逐步扩展到处理审批、同步数据、监控告警，你会发现团队协作的流程正在被无声地优化。关键在于开始动手，并在实践中不断迭代。当你看到那些重复性的工作被代码默默完成时，那种解放生产力的成就感，正是驱动我们不断探索自动化的最大动力。