# Feishu Ops

> 飞书自动化运维类级技能（一个入口管全部飞书 API 面）— Bot 凭据与 token 获取、群/DM 通道实时发现（不硬编码 chat_id）、多维表格 Bitable 建表写数、云盘文件夹/上传/跨 Bot 共享限制、Wiki 知识库 Bot 权限限制与 OAuth 用户身份方案、任务收件箱巡检。触发：任何飞书机器人脚本/报告发送/云盘与知识库操作/多维表格监控/报错 230002、232009、1063002、99991663、1770001、1061044 时加载。核心铁律：chat_id 永远实时枚举不硬编码；token 每次重取不缓存；跨 Bot 分享用 ECS 共享目录不走云盘。

- Skill: `openclaw-cn-dev/feishu-ops` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx get-skill add openclaw-cn-dev/feishu-ops`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openclaw-cn-dev/feishu-ops/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: MIT
- Author: openclaw-cn-dev (https://skillmd.com/u/openclaw-cn-dev)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/openclaw-cn-dev/feishu-ops

---


# 飞书自动化运维（Feishu Ops）

> 按小节取用对应 API 面；完整流程与脚本照抄对应 reference。凭据统一在 `~/.hermes/.env`（FEISHU_APP_ID / FEISHU_APP_SECRET）。

## §0 通用铁律（所有 API 面共用）

1. **tenant_access_token 每次运行重新取**（约 2h 有效，不要缓存）：
   `POST /open-apis/auth/v3/tenant_access_token/internal`
2. **chat_id 永远不硬编码** — Bot 的群/DM 成员关系会随用户手动调整而变化，硬编码必然失效。发送前实时枚举 `/open-apis/im/v1/chats` 按 name 匹配。
3. 国内版域名 `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 实测，手机/平板取大文件的标准姿势）**：目标是把大文件送进用户移动设备时，别止步于"用户自己想办法"——本机就能开局域网下载服务：
1. `mkdir -p /tmp/apk_share && cp <大文件> /tmp/apk_share/`（隔离目录，不要把整个 Downloads 暴露到局域网）
2. `cd /tmp/apk_share && python3 -m http.server 8899 --bind 0.0.0.0` 用 terminal(background=true) 起服务（前台模式会被安全门拦 '&' 写法）
3. `ipconfig getifaddr en0`（和 `en1`）拿本机 IP，Mac 本机 curl -sI 验通后再发 URL
4. 飞书只发纯文本：`http://<IP>:8899/<文件名>` + 备用 IP 同路径，同 WiFi 设备浏览器直接下载
5. 用户装完说一声再 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 行主技能（保留独立入口）。

