飞书开放平台对接 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 ou_user1,ou_user2

# 强制发送（忽略夜间模式和冷却）
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=$(get_feishu_token)

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 \
  "img_v3_xxx" \
  "$TOKEN"

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

---

⚠️ 重要：API 速率限制#

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

限制类型数值说明QPS5每秒最多 5 次请求日限额10,000每天最多 10,000 次请求文档写入需限速大文档分批写入，每次请求间隔 200ms+

写入大文档的最佳实践#

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

bash

# 连续快速追加，超过 5 QPS
feishu_doc_append "TOKEN" "内容1"  # 第1秒
feishu_doc_append "TOKEN" "内容2"  # 第1秒
feishu_doc_append "TOKEN" "内容3"  # 第1秒
feishu_doc_append "TOKEN" "内容4"  # 第1秒
feishu_doc_append "TOKEN" "内容5"  # 第1秒
feishu_doc_append "TOKEN" "内容6"  # 第1秒 - 触发限流！

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

bash

# 每次追加间隔 200ms，确保不超过 5 QPS
feishu_doc_append "TOKEN" "内容1"
sleep 0.2
feishu_doc_append "TOKEN" "内容2"
sleep 0.2
feishu_doc_append "TOKEN" "内容3"
# ...

批量写入脚本示例#

bash

#!/bin/bash
# 批量写入飞书文档（带速率限制）

DOC_TOKEN="your_doc_token"
CONTENT_FILE="content.txt"  # 每行一个段落

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

    # 每5行暂停1秒（确保不超过 5 QPS）
    LINE_NUM=$((LINE_NUM + 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. 立即停止当前操作
2. 等待 1-2 秒
3. 降低请求频率后重试
4. 考虑使用 sleep 添加间隔

---

核心功能#

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

功能清单#

功能API 端点说明Token 管理/auth/v3/tenant_access_token/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 管理（核心）#

获取 tenant_access_token#

bash

# 使用脚本获取（推荐）
source /root/mo-hub/skills/feishu-integration/scripts/feishu-auth.sh
TOKEN=$(get_feishu_token)

# 或直接调用
curl -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "cli_a90da2f009f8dbb3",
    "app_secret": "YOUR_SECRET"
  }'

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. 文档操作#

bash

# 读取文档
feishu_doc_read "DOC_TOKEN"

# 写入文档（替换全部内容）
feishu_doc_write "DOC_TOKEN" "## 标题\n\n内容"

# 追加内容（逐个块，保证顺序）
feishu_doc_append "DOC_TOKEN" "### 新标题"
feishu_doc_append "DOC_TOKEN" "- 列表项"

2. 知识库操作#

bash

# 列出知识空间
feishu_wiki_spaces

# 列出空间节点
feishu_wiki_nodes "SPACE_ID"

# 创建文档
feishu_wiki_create_doc "SPACE_ID" "文档标题"

3. Markdown 导入#

bash

# 导入 MD 到飞书文档
feishu_import_md "/path/to/file.md" "FOLDER_TOKEN"

4. 文件上传#

bash

# 上传文件到云空间
feishu_upload_file "/path/to/file" "FOLDER_TOKEN"

5. 群欢迎机器人#

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 ou_user1,ou_user2

扩展接口#

如需添加新接口，按以下模式扩展：

bash

# 在 scripts/feishu-api.sh 中添加
feishu_new_api() {
  local param1=$1
  local param2=$2

  local token=$(get_feishu_token)

  curl -s -X POST "https://open.feishu.cn/open-apis/NEW_API_PATH" \
    -H "Authorization: Bearer ${token}" \
    -H "Content-Type: application/json" \
    -d "{
      \"param1\": \"${param1}\",
      \"param2\": \"${param2}\"
    }"
}

配置文件#

编辑 config/feishu.env 设置应用信息：

bash

FEISHU_APP_ID=cli_a90da2f009f8dbb3
FEISHU_APP_SECRET=your_secret_here

参考文档#

详细 API 文档见 references/ 目录：

• api-reference.md - 完整 API 参考
• token-management.md - Token 管理详解
• import-workflow.md - 文件导入流程

依赖#

• curl - HTTP 请求
• jq - JSON 处理（可选，用于格式化输出）

安全提醒#

• app_secret 不要提交到代码仓库
• Token 有效期 2 小时，不要长期缓存
• 敏感操作（删除、权限修改）需二次确认