Feishu Integration

提供飞书开放平台API统一调用与token管理，支持文档、知识库、文件操作，Markdown导入，消息解析及群欢迎机器人功能。

Security Scan

技能本身实现了飞书对接功能，但清单/元数据与代码不一致并且仓库包含明文应用密钥与本地 token 缓存逻辑——这构成明显的安全与透明性问题，建议在信任并修复之前不要安装或投入生产使用。

Purpose & Capability

技能的名称与说明与其代码库（文档管理、消息解析、群欢迎、token 管理等）一致——功能上合理。但注册表元数据宣称“无需环境变量/凭证”，与大量代码和示例中显式依赖 FEISHU_APP_ID / FEISHU_APP_SECRET（以及 config/feishu.env）矛盾，说明元数据不可信或不完整。

Instruction Scope

SKILL.md 指示运行本地脚本（bash/python/node），获取并缓存 tenant_access_token，读取/写入本地配置和缓存文件，并建议将脚本放到 /root/ 路径并以 cron 定时运行。读取/写入 .env 或 config/feishu.env、在示例中展示将 app_secret 以明文发送到 curl，都扩大了运行时对本地敏感数据的访问与暴露风险。总体功能在预期范围内，但指令包含将敏感凭证以明文形式存放/使用且写入本地缓存的实践，值得警惕。

Install Mechanism

没有外部下载或远程安装步骤（instruction-only + 本地文件集合）。这降低了供应链注入风险。但代码依赖 Node/Python 运行时与若干 npm 包（package.json/lockfile 已包含），用户需要在受控环境中安装这些依赖并审计它们。

Credentials

尽管元数据列出“无需环境变量”，代码与示例广泛依赖 FEISHU_APP_ID 和 FEISHU_APP_SECRET（config/feishu.env 中甚至包含明文 FEISHU_APP_SECRET）。技能会写入 token 缓存 memory/feishu_token.json。请求的权限（应用ID/密钥）与功能一致，但将密钥包含在仓库中且未在元数据中声明是严重的不成比例/透明性问题。

Persistence & Privilege

技能未请求 always: true，也未修改其它技能配置。它会在运行时创建/写入本地 token 缓存文件并可被 crontab 定时调用，还会通过 spawn/exec 调用本地脚本（index.js）。这些都是合理的实现选项，但会在本地留下凭证缓存和可被定时执行的行为，建议审慎管理文件权限与定时任务。

What to consider before installing

要点和建议： 1) 不要直接在生产环境安装或运行——先确认发布者与来源。仓库包含 config/feishu.env 并且其中有明文 FEISHU_APP_SECRET，视为已泄露的凭证；如果这是你的应用，立即在飞书后台撤销/重置该 secret。 2) 元数据与实际代码不一致：注册表显示无需环境变量，但脚本/示例依赖 FEISHU_APP_ID/FEISHU_APP_SECRET/.env，说明元数据不可信或发布不当。要求发布者修正清单并明确说明所需凭证。 3) 在受控/隔离环境（临时测试账号、沙箱）中审计并运行脚本。检查 scripts/* 和 python/node 文件中是否有任何指向未知/外部主机的网络请求或隐蔽上报逻辑（当前未发现明显外部上报，但应人工复查）。 4) 不要使用仓库内的 config/feishu.env：将凭证放到受管理的密钥存储（环境变量、vault），并从代码中删除硬编码凭证或示例中的真实 secret。 5) 若你受影响（secret 来自你的组织），立即轮换凭证并检查是否有异常 token 使用记录（调用日志、webhook、创建的 chat 等）。 6) 要求作者/发布者：更新 registry 元数据以声明所需环境变量、移除或重写示例中明文凭证、并提供明确的安装/依赖步骤与最小权限说明。 如果你想，我可以：提取并列出仓库中所有写入/网络调用的位置、或帮助生成一个更安全的安装/运行清单（如何用临时凭证测试、如何安全存储 token、如何限制文件权限）。

飞书开放平台对接 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 速率限制

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

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

写入大文档的最佳实践

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

# 连续快速追加，超过 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 管理机制。

功能清单

功能	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

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

错误处理

错误码	含义	处理建议
0	成功	-
1061045	频率限制	稍后重试
1062009	文件大小不匹配	检查 size 参数
99992402	参数验证失败	检查必填字段
9499	参数类型错误	检查数据类型

常用操作速查

1. 文档操作

# 读取文档
feishu_doc_read "DOC_TOKEN"

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

# 追加内容（逐个块，保证顺序）
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 小时，不要长期缓存
• 敏感操作（删除、权限修改）需二次确认