Feishu Toolkit (飞书工具箱)

一个面向 AI 代理的全面飞书（Lark）集成技能，涵盖六大核心功能：

1. 📄 文档操作 —— 读取、创建、编辑和追加飞书文档、表格、Bitable、Wiki
2. 💬 聊天历史 —— 获取并总结群聊消息
3. 📎 文件发送 —— 通过 REST API 上传并发送文件到飞书聊天
4. 📸 截图发送 —— 捕获 macOS 截图并发送至飞书
5. 🔐 权限管理 —— 列出、添加、移除文档协作者
6. ⏰ 定时提醒 —— 创建定时重复提醒并发送至飞书聊天

前置条件

飞书应用设置

1. 访问 [飞书开放平台](https://open.feishu.cn/app) 并创建应用
2. 启用以下权限：

- im:message:send_as_bot —— 发送消息

- im:resource —— 上传文件/图片

- docx:document —— 读写文档

- drive:permission —— 管理权限（可选）

1. 设置环境变量 FEISHU_APP_ID 和 FEISHU_APP_SECRET

认证方式

所有 API 调用使用飞书的租户访问令牌（tenant access token）：

import requests

def get_tenant_token(app_id, app_secret):
    r = requests.post(
        'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal',
        json={'app_id': app_id, 'app_secret': app_secret}
    )
    return r.json()['tenant_access_token']

1. 文档操作（读/写/创建/追加）

读取文档内容

# 获取文档内容（Markdown 格式）
# 支持类型：doc、docx、sheet、bitable、wiki
GET /open-apis/docx/v1/documents/{document_id}/raw_content

创建文档

POST /open-apis/docx/v1/documents
Body: {"title": "我的文档"}

编辑文档（覆盖写入）

# 使用 Markdown 内容覆盖整个文档
POST /open-apis/docx/v1/documents/{document_id}/blocks/batch_update

追加内容（长文档处理）

对于超出 LLM 输出限制的长文档，请按以下步骤操作：

1. 先创建文档以获取 doc_token
2. 将内容分块为逻辑段落
3. 逐块追加
4. 不要尝试一次性写入超长文档

Wiki URL 解析

Wiki 的链接需先转换为实际文档令牌：

POST /open-apis/wiki/v2/spaces/get_node
Body: {"token": "wiki_token"}
# 返回实际的 doc_token 和 doc_type

2. 聊天历史

从飞书群聊中获取并总结消息。

获取消息

# GET /open-apis/im/v1/messages
params = {
    'container_id_type': 'chat',
    'container_id': chat_id,
    'page_size': 50
}

消息类型处理

分页处理

若返回 has_more=true，请使用 page_token 获取下一页数据。默认每页最多 50 条消息。

3. 文件发送

通过 REST API 将文件发送至飞书聊天。

上传文件

# POST /open-apis/im/v1/files
headers = {'Authorization': f'Bearer {token}'}
data = {'file_type': 'stream', 'file_name': 'filename.ext'}
files = {'file': ('filename.ext', open(path, 'rb'), 'application/octet-stream')}

支持的 file_type：opus、mp4、pdf、doc、xls、ppt、stream（通用类型）

发送文件消息

# POST /open-apis/im/v1/messages
json = {
    'receive_id': chat_id,
    'msg_type': 'file',
    'content': json.dumps({'file_key': file_key})
}

4. 截图并发送

在 macOS 上捕获截图并发送至飞书。

# 1. 捕获截图
SCREENSHOT_PATH="$TMPDIR/screenshot_$(date +%s).png"
screencapture -x "$SCREENSHOT_PATH"

# 2. 上传图片
# POST /open-apis/im/v1/images
# data: image_type=message, file=screenshot

# 3. 发送图片消息
# POST /open-apis/im/v1/messages
# msg_type: image, content: {"image_key": "..."}

注意：macOS 上请使用 $TMPDIR，而非 /tmp。

5. 权限管理

管理文档或文件的访问权限。

可执行操作

支持的令牌类型

doc、docx、sheet、bitable、folder、file、wiki、mindnote

成员类型

email、openid、userid、unionid、openchat、opendepartmentid

权限级别

示例：共享文档

# POST /open-apis/drive/v1/permissions/{token}/members
params = {'type': 'docx'}
json = {
    'member_type': 'email',
    'member_id': 'user@company.com',
    'perm': 'edit'
}

注意：权限管理涉及敏感操作，请谨慎使用。

6. 定时提醒

创建定时重复提醒并发送至飞书聊天。

创建前确认

务必与用户确认以下信息：

1. 频率：多久一次？（例如：每 10 分钟、每小时、每天上午 9 点）
2. 目标：发送到哪里？（默认为当前即时消息会话）

使用模板

cron add \
  --name "<任务名称>" \
  --every "<间隔>" \
  --session main \
  --system-event "[CRON] <任务名称>。向飞书发送提醒：'<提醒内容>'"

间隔示例

管理命令

cron list          # 列出所有任务
cron edit <id>     # 编辑任务
cron rm <id>       # 删除任务（请先征询用户同意！）
cron runs --id <id> # 查看执行历史
cron run <id>      # 手动触发执行

API 参考

基础 URL：https://open.feishu.cn/open-apis

注意事项

• 所有 API 接口均需在 Authorization 头部中携带 tenant_access_token
• 文件上传使用 multipart/form-data 格式
• 消息发送使用 application/json 格式
• 机器人只能下载自己上传的文件
• 详细 API 文档请访问：https://open.feishu.cn/document