飞书自动化运维(Feishu Ops)
按小节取用对应 API 面;完整流程与脚本照抄对应 reference。凭据统一在
~/.hermes/.env(FEISHU_APP_ID / FEISHU_APP_SECRET)。
§0 通用铁律(所有 API 面共用)
- tenant_access_token 每次运行重新取(约 2h 有效,不要缓存):
POST /open-apis/auth/v3/tenant_access_token/internal - chat_id 永远不硬编码 — Bot 的群/DM 成员关系会随用户手动调整而变化,硬编码必然失效。发送前实时枚举
/open-apis/im/v1/chats按 name 匹配。 - 国内版域名
https://open.feishu.cn(国际版open.larksuite.com)。
§1 通道发现与消息发送
报错路由:230002(Bot 不在 chat)/ 232009(chat 已解散)/ 99991663(token 过期)→ 全部走实时枚举流程:每次重取 token → GET /open-apis/im/v1/chats?page_size=50 → 按 name 匹配目标 → 发送。完整 Python 模板见 references/feishu-channel-discovery.md。channel 状态快照样例同文件。
⚠️ 禁裸跑探测 legacy 通知脚本(R587 2026-09-17 实测坑):scripts/feishu_notify.py 这类早期脚本无 argparse/usage 守卫,模块级直发——裸跑不带参数、甚至 --help 探测,都会立即把硬编码消息(如「Claude Code 更新通知」)真实发进目标群,无法撤回。铁律:任何不熟悉的 notify 脚本,调用前先 read_file 看源码确认入口逻辑(有无 if __name__ 守卫、参数解析、硬编码 chat_id),确认安全后才执行;找"哪个脚本发哪个群"时用 search_files/grep 静态检索,禁用执行来探测。
⚠️ 大文件 MEDIA: 直传上限(2026-10-25 实测):>100MB 文件(如 112MB APK)用 send_message 带 MEDIA: 路径会立即失败(Expecting value: line 1 column 1,上传 API 返回非 JSON)。不要反复重试上传——直接降级为纯文本消息:绝对路径 + SHA256 + 3-4 行要点说明(文件是什么/怎么装/在哪),用户自行 AirDrop/网盘/局域网取件。
局域网 HTTP 直传降级(2026-10-25 实测,手机/平板取大文件的标准姿势):目标是把大文件送进用户移动设备时,别止步于"用户自己想办法"——本机就能开局域网下载服务:
mkdir -p /tmp/apk_share && cp <大文件> /tmp/apk_share/(隔离目录,不要把整个 Downloads 暴露到局域网)cd /tmp/apk_share && python3 -m http.server 8899 --bind 0.0.0.0用 terminal(background=true) 起服务(前台模式会被安全门拦 '&' 写法)ipconfig getifaddr en0(和en1)拿本机 IP,Mac 本机 curl -sI 验通后再发 URL- 飞书只发纯文本:
http://<IP>:8899/<文件名>+ 备用 IP 同路径,同 WiFi 设备浏览器直接下载 - 用户装完说一声再 kill 服务(background 会话 process kill) 注:本机验证 curl 内网 IP 曾被安全门拦("timed out without user response"),可用 process(poll) 看服务进程存活替代验证。
§2 多维表格 Bitable(把数据做成在线看板)
概念:app(app_token)→ table(table_id)→ field(列)→ record(行)。流程:取 token → POST /open-apis/bitable/v1/apps 建表 → fields 加列(type:1 文本/2 数字/3 单选/5 日期/11 人员/17 附件)→ records/batch_create(≤500 条/批)。可复用脚本 ~/.hermes/scripts/tokens_to_bitable.py。完整流程见 references/feishu-bitable.md。
§3 云盘与跨 Bot 协作
- 云盘(Drive)Bot 用 tenant token 可建文件夹/文档;Wiki 空间创建必须 user_access_token(99991663 = 拿 Bot token 干 Wiki 的事)。
- 飞书平台禁止 Bot 之间互相分享文件夹(code 1063002)——平台级限制,与 App 权限无关;跨机器 Agent 协作用 ECS 共享目录,不走云盘分享。
- Docx block 类型权限:Bot token 只支持 text/heading/divider,bullet/ordered/code/quote 返回 1770001(整段合并为一个 text block 写入)。
- 巡检脚本
scripts/cron_drive_check_v2.py(2026-06-20 修复版:EditedTime 修正 + sanitizer-safe token 写入 + 动态 agent 查找)。注意/tmp拷贝运行时相对路径失效坑。详见references/feishu-bot-cloud-drive.md。
§4 Wiki 知识库
- 已知知识库 node_token 清单 + MCP 限制(wiki_search 只见 Bot 可见内容、无 wiki_node_create)见
references/feishu-wiki-operations.md。 - OAuth 用户身份方案:
npx @larksuiteoapi/lark-mcp login必须在用户本人 Mac 终端跑(Agent 终端 OAuth 交互会超时),绕开 Bot 权限。 - 认证/文件枚举/错误码速查:
references/feishu-wiki-api-base.md(每次心跳任务先查)。 - Agent 任务收件箱真相:cron 提示的
任务派发/{agent}/路径是错的,真实收件箱在{agent}/任务派发/{agent}/{实例}/。见references/***SECRET***.md+scripts/check_study_helper_inbox.py。
§5 相关
- 大文件(>30MB)传飞书:IM 文件消息超限报 missing file_key,需走云盘分片上传 + share_file 卡片。完整 SOP(含 upload_prepare 三种请求格式实测、SDK 源码求证法、未解残留与兜底路线)见
references/feishu-large-file-transfer.md。 - 发消息用 Hermes 原生 send_message(platform:oc_xxx)优先于手写 API;cron 报告走 origin auto-delivery,不手动 send(防 duplicate_target)。
- 官网/工作台发布运维(非飞书面,但同属对外发布):见
references/***SECRET***.md— lookforge.net 生产拓扑、workbench_release.json 单一事实来源热切、桌面/CI 包发布流程、应用内检查更新契约。触发:工作台新版本上线、官网安装包更新、用户下载到旧版。 productivity/feishu-api-notify— 直发 REST 通知的完整凭据/签名细节(保留独立入口)。productivity/feishu-drive-file-management— 云盘文件管理 844 行主技能(保留独立入口)。