飞书开放平台对接 Skill

🆕 新增功能

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

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

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

快速使用：

# 自动检测新成员
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 分钟检查一次）：

# 编辑 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）
- ✅ 引用回复消息

快速使用：

# 解析消息
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 速率限制

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

写入大文档的最佳实践

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

# 连续快速追加，超过 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秒 - 触发限流！

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

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

批量写入脚本示例

#!/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 管理机制。

功能清单

Token 管理（核心）

获取 tenant_access_token

# 使用脚本获取（推荐）
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 调用规范

标准请求格式

# 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"

错误处理

常用操作速查

1. 文档操作

# 读取文档
feishu_doc_read "DOC_TOKEN"

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

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

2. 知识库操作

# 列出知识空间
feishu_wiki_spaces

# 列出空间节点
feishu_wiki_nodes "SPACE_ID"

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

3. Markdown 导入

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

4. 文件上传

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

5. 群欢迎机器人

# 自动检测新成员
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

扩展接口

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

# 在 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 设置应用信息：

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 小时，不要长期缓存
• 敏感操作（删除、权限修改）需二次确认