飞书开放平台对接 Skill

🆕 新增功能

群欢迎机器人（2026-03-08）

自动检测并欢迎飞书群聊中的新成员，支持批量@和自定义欢迎语。

功能特性：

• - ✅ 自动检测新成员（对比群成员列表）
• ✅ 批量@功能（支持 39 人+，分批发送，每批 20 人）
• ✅ 欢迎语模板系统（8 种模板随机选择）
• ✅ 夜间模式（23:00-07:00 静默）
• ✅ 冷却机制（30 分钟内不重复欢迎）
• ✅ 分批发送逻辑

快速使用：
bash

自动检测新成员

python3 ~/mo-hub/skills/feishu-integration/scripts/group-welcome.py \
--chat-id oc_xxx \
--chat-name 我的群

手动欢迎指定用户（补欢迎）

python3 ~/mo-hub/skills/feishu-integration/scripts/group-welcome.py \ --chat-id oc_xxx \ --users ouuser1,ouuser2

强制发送（忽略夜间模式和冷却）

python3 ~/mo-hub/skills/feishu-integration/scripts/group-welcome.py \ --chat-id oc_xxx \ --force

定时任务配置（每 30 分钟检查一次）：
bash

编辑 crontab

crontab -e

添加定时任务

/30 * python3 /root/mo-hub/skills/feishu-integration/scripts/group-welcome.py --chat-id oc_xxx --chat-name 群名

消息解析模块（2026-03-02）

完整支持飞书消息解析，包括：

• - ✅ 富文本消息（post）- 支持 Markdown、代码块、@提及、链接
• ✅ 纯文本消息（text）
• ✅ 交互式卡片（interactive）
• ✅ 图片消息 + OCR 识别（image）
• ✅ 引用回复消息

快速使用：
bash

解析消息

source ~/mo-hub/skills/feishu-integration/scripts/feishu-auth.sh
TOKEN=$(getfeishutoken)

python3 ~/mo-hub/skills/feishu-integration/scripts/feishu-message-parser.py \
$TOKEN \
{msg_type:text,body:{content:{\text\:\Hello\}}}

OCR 识别图片

python3 ~/mo-hub/skills/feishu-integration/scripts/feishu-ocr.py \ imgv3xxx \ $TOKEN

详细文档：references/message-parsing.md

---

⚠️ 重要：API 速率限制

飞书开放平台有严格的频率限制，写入大文档时必须注意：

限制类型	数值	说明
QPS	5	每秒最多 5 次请求
日限额

10,000 | 每天最多 10,000 次请求 |
| 文档写入 | 需限速 | 大文档分批写入，每次请求间隔 200ms+ |

写入大文档的最佳实践

❌ 错误做法（会导致内容缺失）：
bash

连续快速追加，超过 5 QPS

feishudocappend TOKEN 内容1 # 第1秒
feishudocappend TOKEN 内容2 # 第1秒
feishudocappend TOKEN 内容3 # 第1秒
feishudocappend TOKEN 内容4 # 第1秒
feishudocappend TOKEN 内容5 # 第1秒
feishudocappend TOKEN 内容6 # 第1秒 - 触发限流！

✅ 正确做法（添加延迟）：
bash

每次追加间隔 200ms，确保不超过 5 QPS

feishudocappend TOKEN 内容1
sleep 0.2
feishudocappend TOKEN 内容2
sleep 0.2
feishudocappend TOKEN 内容3

...

批量写入脚本示例

bash
#!/bin/bash

批量写入飞书文档（带速率限制）

DOCTOKEN=yourdoc_token
CONTENT_FILE=content.txt # 每行一个段落

LINE_NUM=0
while IFS= read -r line; do
# 追加内容
feishudocappend $DOC_TOKEN $line

# 每5行暂停1秒（确保不超过 5 QPS）
LINENUM=$((LINENUM + 1))
if [ $((LINE_NUM % 5)) -eq 0 ]; then
sleep 1
else
sleep 0.2 # 200ms 间隔
fi
done < $CONTENT_FILE

echo 写入完成，共 $LINE_NUM 段内容

错误码 1061045 处理

如果收到 1061045 错误（频率限制）：

1. 1. 立即停止当前操作
2. 等待 1-2 秒
3. 降低请求频率后重试
4. 考虑使用 sleep 添加间隔

---

核心功能

本 Skill 封装了飞书开放平台的主要 API，提供统一的调用接口和 token 管理机制。

功能清单

功能	API 端点	说明
Token 管理	/auth/v3/tenantaccesstoken/internal	自动获取/刷新
文档操作

/docx/v1/documents/* | 创建、读取、写入、追加 | | 知识库 | /wiki/v2/* | 空间、节点管理 | | 云空间 | /drive/v1/files/* | 文件上传、文件夹管理 | | 素材上传 | /drive/v1/medias/* | 临时文件上传（用于导入） | | 导入任务 | /drive/v1/import_tasks/* | Markdown/Word/Excel 导入 | | 群成员管理 | /im/v1/chats/*/members | 获取群成员列表 | | 消息发送 | /im/v1/messages | 发送富文本消息、批量@ | | 群欢迎机器人 | - | 自动检测新成员、发送欢迎语 |

Token 管理（核心）

获取 tenantaccesstoken

bash

使用脚本获取（推荐）

source /root/mo-hub/skills/feishu-integration/scripts/feishu-auth.sh
TOKEN=$(getfeishutoken)

或直接调用

curl -X POST https://open.feishu.cn/open-apis/auth/v3/tenantaccesstoken/internal \ -H Content-Type: application/json \ -d { appid: clia90da2f009f8dbb3, appsecret: YOURSECRET }

Token 有效期处理

• - 有效期: 2 小时（7200 秒）
• 自动刷新: 使用 feishu-auth.sh 脚本会自动检查并刷新
• 安全存储: Token 不硬编码，动态获取

API 调用规范

标准请求格式

bash

GET 请求

curl -s -X GET https://open.feishu.cn/open-apis/{API_PATH} \
-H Authorization: Bearer ${TOKEN}

POST JSON

curl -s -X POST https://open.feishu.cn/open-apis/{API_PATH} \ -H Authorization: Bearer ${TOKEN} \ -H Content-Type: application/json \ -d {...}

POST FormData（文件上传）

curl -s -X POST https://open.feishu.cn/open-apis/{API_PATH} \ -H Authorization: Bearer ${TOKEN} \ -F param1=value1 \ -F file=@/path/to/file

错误处理

错误码	含义	处理建议
0	成功	-
1061045

频率限制 | 稍后重试 | | 1062009 | 文件大小不匹配 | 检查 size 参数 | | 99992402 | 参数验证失败 | 检查必填字段 | | 9499 | 参数类型错误 | 检查数据类型 |

常用操作速查

1. 文档操作