5.9 KiB
5.9 KiB
title, type, tags, date
| title | type | tags | date |
|---|---|---|---|
| Feishu Integration Developer Agent Personality | source | 2026-05-01 |
Source File
Summary（用中文描述）
- 核心主题：飞书（Feishu/Lark）开放平台全栈集成专家，专注于企业 OA 审批、数据管理、团队协作和业务通知在飞书生态内的实现。
- 问题域：企业级飞书生态集成开发，包括自定义机器人、交互式消息卡片、审批流自动化、Bitable 多维表格、SSO/OIDC 认证和飞书小程序。
- 方法/机制：通过官方 SDK（
oapi-sdk-nodejs/oapi-sdk-python）调用飞书 API；TokenManager 实现 tenant/user_access_token 缓存；EventDispatcher 处理事件订阅签名验证；CardBuilder 构建交互式卡片 JSON；BitableClient 实现表格记录的 CRUD 与批量同步。 - 结论/价值：提供企业级协作自动化解决方案，核心理念是"飞书集成不只是调用 API"，涉及权限模型、事件幂等性、多租户架构和与内部系统的深度集成。交付物涵盖完整项目结构、Token 管理、卡片构建、事件分发、审批流、Bitable 操作和 OAuth 登录六大模块。
Key Claims（用中文描述）
- 飞书集成工程师必须区分
tenant_access_token和user_access_token的适用场景——前者用于应用级别操作，后者用于用户个人数据和授权操作。 - 所有 API 响应必须检查
code字段，code != 0时执行错误处理和日志记录，而非默认成功。 - 事件处理必须实现幂等性——飞书可能重复投递同一事件（网络重试机制），重复处理会导致数据不一致。
- 消息卡片 JSON 必须在本地验证后再发送，飞书对格式敏感，渲染失败会阻塞业务流程。
- Bitable 批量写入每请求最多 500 条记录，超出必须分批并建议批次间添加 200ms 延迟以避免限流。
app_secret和encrypt_key必须存放在环境变量或密钥管理服务中，前端代码禁止硬编码。
Key Quotes
"Feishu integration is not just 'calling APIs' — it involves permission models, event subscriptions, data security, multi-tenant architecture, and deep integration with enterprise internal systems." — 核心身份定义
"Don't do heavy processing inside the event callback — return 200 first, then handle asynchronously. Feishu will retry if it doesn't get a response within 3 seconds, and you might receive duplicate events." — 事件处理最佳实践
"Bitable batch writes are limited to 500 records per request — anything over that needs to be batched. Also watch out for concurrent writes triggering rate limits; I recommend adding a 200ms delay between batches." — 数据同步性能警告
Key Concepts
- Tenant-Access-Token：应用级别访问令牌，用于不涉及特定用户的操作，需缓存并提前5分钟刷新以避免边界问题。
- User-Access-Token：用户级别 OAuth 令牌，通过授权码流程获取，代表用户身份执行操作，需安全存储和刷新。
- Message-Card：飞书交互式卡片，基于 JSON 结构定义，支持按钮、日期选择器、下拉菜单等交互元素，通过
message_id可更新已发送卡片内容。 - Event-Subscription：飞书事件订阅机制，支持 Bot 消息接收、审批状态变更等事件，必须验证签名或解密 encrypt key，返回 200 状态码避免重试。
- Bitable：飞书多维表格，支持表格记录的增删改查、字段管理、视图切换和数据双向同步，适合作为企业数据的中转层。
- OAuth-2-0-Feishu：飞书网页应用自动登录授权流程，包含 authorize 重定向 → callback code 交换 → user_info 获取三步，必须验证 state 参数防止 CSRF。
- Idempotency：事件处理幂等性设计——飞书可能重复投递同一事件（超时重试），处理逻辑必须能正确处理重复消息而不产生副作用。
Key Entities
- LarkSuite-API-SDK（
@larksuiteoapi/node-sdk/oapi-sdk-python）：飞书官方 SDK，推荐使用而非手动构造 HTTP 请求，内置 token 缓存。 - Feishu-Open-Platform：飞书开放平台，提供 Bot、审批、Bitable、小程序、SSO 等企业集成能力，需在平台创建应用并配置权限范围。
- Feishu-Card-Builder：飞书官方卡片构建工具，支持可视化预览交互式卡片 JSON，发布前必须通过工具验证卡片渲染。
Connections
- Engineering-Backend-Architect ← 依赖 → Feishu-Integration-Developer：后端架构师设计系统拓扑，飞书集成开发者在其架构内实现消息通知和数据同步模块。
- Engineering-Software-Architect ← extends → Feishu-Integration-Developer：软件架构师定义系统边界和集成模式，飞书集成开发者遵循其架构决策构建具体集成模块。
- Testing-API-Tester ← 验证 → Feishu-Integration-Developer：API 测试专家验证飞书 API 调用的正确性、限流处理和错误恢复能力。
- Engineering-SRE ← 监控 → Feishu-Integration-Developer：SRE 工程师配置 token 获取失败、API 调用错误、事件处理超时等监控告警。
Contradictions
- 与 Engineering-Rapid-Prototyper 存在速度哲学张力：
- 冲突点：Rapid Prototyper 追求"3天交付 MVP"的速度优先哲学，允许技术债；飞书集成要求"必须实现幂等性、必须检查 code 字段、必须缓存 token"等严格工程标准。
- 当前观点：生产级企业集成必须遵守飞书 API 规范（幂等性/错误处理/token 缓存），否则在事件重试和高并发场景下会产生数据不一致。
- 对方观点：原型阶段可简化 token 管理和错误处理以加快交付速度。
- 协调方式：在原型验证阶段使用 Rapid Prototyper 快速验证业务假设，生产化阶段再由飞书集成开发者补充完整错误处理和幂等性保障。