gabrielmoreira 飞书 (Lark) 工作流套件
35 个 feishu_* tool 覆盖飞书除 IM 之外的核心业务面：docx / bitable / drive / wiki / approval / calendar / contact / hire。所有 tool 共享同一个账号路由——account 参数仅在配了 ≥2 个飞书账号时才必须，否则自动选唯一一个。
典型工作流剧本
1. OKR 周报：bitable → docx → drive
1. feishu_bitable_list_records({app_token, table_id, view_id?})
→ 拿到本周的 OKR 进度数据
2. feishu_docx_create({title: "OKR Weekly W#"})
→ 拿到 document_id
3. feishu_docx_append_block({document_id, parent_block_id: document_id,
block: {block_type: 2, text: {style: {}, elements: [...]}}})
→ 写多段
4. feishu_drive_upload_media({path: "/tmp/screenshot.png",
folder_token: "...", mime: "image/png"})
→ 把截图传上去（≤20MB，本地路径必须绝对）
2. 排会议：calendar → attendees
1. feishu_calendar_list() → 选目标 calendar_id
2. feishu_calendar_create_event({calendar_id, event: {
summary: "OKR review", start_time: {timestamp: "1700000000",
timezone: "Asia/Shanghai"}, end_time: {...}}})
→ 拿到 event_id
3. feishu_calendar_attendees_create({calendar_id, event_id, attendees: [
{type: "user", user_id: "ou_xxx"},
{type: "chat", chat_id: "oc_xxx"}]})
3. 查同事：contact
1. feishu_contact_get_user({user_id: "ou_xxx"}) // 或先 search 找 ID
→ 名字 / email / 部门 / 上级
2. feishu_contact_search_users_by_department({department_id: "..."})
→ 整个团队
⚠️ contact 系列返回员工个人信息（手机号 / 邮箱 / 部门），不要把原始 JSON 直接 echo 回 IM 群聊——总结关键字段即可。
4. 审批：approval
1. feishu_approval_create_instance({approval_code, user_id, form: "[...]"})
→ ⚠️ HIGH RISK：在调之前一定问用户「我准备发起 X 审批，form 字段是 Y/Z，确认吗？」
2. feishu_approval_get_instance({instance_code}) → 看 status / timeline
3. 撤销也是 HIGH：feishu_approval_cancel_instance({approval_code, instance_code, user_id})
5. wiki 链接：先解析再读
用户给一个形如 https://xxx.feishu.cn/wiki/wikcnXxx 的链接时：
1. feishu_wiki_get_node({token: "wikcnXxx"})
→ 拿到 obj_token / obj_type
2. obj_type == "docx" → feishu_docx_get_blocks({document_id: obj_token})
obj_type == "bitable" → feishu_bitable_list_records({app_token: obj_token, table_id: ...})
飞书 app scope 速查
每个 tool 的 description 已写明所需 scope；汇总如下（在飞书后台「权限管理」开启）：
| 模块 | 主要 scope | 备注 |
|---|---|---|
| docx | docx:document / docx:document.readonly |
写需 :document |
| bitable | bitable:app / bitable:app.read |
写需 :app |
| drive | drive:drive / drive:drive.read |
upload / download 都需要 |
| wiki | wiki:wiki.readonly / wiki:wiki |
get_node 一般 readonly 够 |
| approval | approval:approval |
create / cancel 都需要 |
| calendar | calendar:calendar / calendar:calendar.readonly |
写需 :calendar |
| contact | contact:user.id:readonly / contact:department.id:readonly |
敏感数据 |
| hire | hire:job:readonly / hire:talent:readonly / hire:application:readonly |
tenant 必须开通 hire 模块 |
常见错误码翻译（让用户秒懂）
| code | 含义 | 给用户的提示 |
|---|---|---|
99991400 |
请求过快 / 限流 | 「飞书侧限流了，等几秒重试」 |
99991663 |
参数错误 / 资源不存在 | 「token 或 ID 不对，确认一下原始链接？」 |
99991672 |
scope 未授权 | 「飞书 app 缺 X scope，去飞书后台『权限管理』勾选并发版」 |
99991677 |
租户未开通 | 「这个能力需要租户管理员先在工作台启用」 |
1061004 |
hire 模块未开通 | 「招聘模块只在企业版可用，让管理员去工作台启用『飞书招聘』」 |
300317 |
cardkit sequence 错乱 | 内部错误，已自动降级 |
200750 |
cardkit 卡片过期 | 重新创建 |
风险等级（操作影响范围）
- HIGH：
feishu_approval_create_instance/feishu_approval_cancel_instance—— 影响真实审批流，调用前必须向用户复述参数 + 等待确认 - MEDIUM：其它所有写操作（
docx_create/docx_append_block/bitable_create_record/drive_upload_media/calendar_create_event等）—— 列出 diff / 预期结果让用户认可一次即可 - MEDIUM-敏感：
feishu_contact_*/feishu_hire_list_talents/feishu_hire_get_talent—— 返回员工/候选人个人信息；不要回显原始 JSON 到群聊或外部上下文
多账号
只在配了 ≥2 个飞书账号时才需要传 account: "<channel_account_id>"。GUI 设置入口：Settings → Channels → Feishu。账号信息走 cached_config() 拉取，与 IM 渠道是否运行 WebSocket 网关解耦——只想用 docx / bitable 不开 bot 的场景也支持。
不在本工具集内（v0.2.0 不含）
- docx 块类型扩展（image / table / code block） — v0.3+
- drive 大文件分片上传 v2（>20MB） — v0.3+
- bitable view 创建 / 自定义 / 公式 / 自动化 — v0.3+
- approval 模板定义 / approve / reject task — v0.3+（写要走飞书后台）
- calendar 会议室 / 资源预订 — v0.3+
- task / email — v0.3+
- 其它 channel 的 reaction / edit / recall 解析 — v0.3+ Phase B.3
碰到上述场景：明确告诉用户「这块在 v0.2.0 暂不覆盖，请去飞书后台手动操作 / 等下版」。