Feishu Toolkit (飞书工具箱)
A comprehensive Feishu (Lark) integration skill for AI agents. Covers 6 major capabilities:
- 1. 📄 Document Operations — Read, create, write, and append Feishu Docs, Sheets, Bitable, Wiki
- 💬 Chat History — Fetch and summarize group chat messages
- 📎 File Sending — Upload and send files to Feishu chats via REST API
- 📸 Screenshot — Capture macOS screenshots and send to Feishu
- 🔐 Permission Management — List, add, remove document collaborators
- ⏰ Cron Reminders — Create scheduled recurring reminders to Feishu chats
Prerequisites
Feishu App Setup
- 1. Go to Feishu Open Platform and create an app
- Enable required permissions:
-
im:message:send_as_bot — Send messages
-
im:resource — Upload files/images
-
docx:document — Read/write documents
-
drive:permission — Manage permissions (optional)
- 3. Set
FEISHU_APP_ID and FEISHU_APP_SECRET environment variables
Authentication
All API calls use Feishu's 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. Document Operations (Read/Write/Create/Append)
Read a Document
CODEBLOCK1
Create a Document
CODEBLOCK2
Write (Overwrite) a Document
CODEBLOCK3
Append Content (Long Documents)
For documents exceeding LLM output limits:
- 1. Create the document first to get a INLINECODE6
- Chunk content into logical sections
- Append each chunk sequentially
- Do NOT try to write the entire document in one call if it is very long
Wiki URL Resolution
Wiki URLs need to be resolved to actual document tokens first:
POST /open-apis/wiki/v2/spaces/get_node
Body: {"token": "wiki_token"}
# Returns the actual doc_token and doc_type
2. Chat History
Fetch and summarize messages from a Feishu group chat.
Fetch Messages
CODEBLOCK5
Message Types
| Type | Handling |
|---|
| INLINECODE7 | Extract .body.content JSON → text field |
| INLINECODE10 |
Extract text nodes from
elements array |
|
image | Note as
[图片] |
|
system | Filter out unless relevant |
Pagination
If
has_more=true, fetch more pages using
page_token. Default: 50 messages per page.
3. File Sending
Send files to Feishu chats via REST API.
Upload File
CODEBLOCK6
Supported file_type: opus, mp4, pdf, doc, xls, ppt, stream (generic)
Send File Message
# POST /open-apis/im/v1/messages
json = {
'receive_id': chat_id,
'msg_type': 'file',
'content': json.dumps({'file_key': file_key})
}
4. Screenshot & Send
Capture macOS screenshots and send to Feishu.
CODEBLOCK8
Note: Use $TMPDIR not /tmp on macOS.
5. Permission Management
Manage document/file permissions.
Actions
| Action | Description |
|---|
| INLINECODE27 | List all collaborators |
| INLINECODE28 |
Add collaborator with permission level |
|
remove | Remove a collaborator |
Token Types
doc,
docx,
sheet,
bitable,
folder,
file,
wiki, INLINECODE37
Member Types
email,
openid,
userid,
unionid,
openchat, INLINECODE43
Permission Levels
| Level | Description |
|---|
| INLINECODE44 | View only |
| INLINECODE45 |
Can edit |
|
full_access | Full access (can manage permissions) |
Example: Share document
CODEBLOCK9
Note: Permission management is sensitive. Use with caution.
6. Cron Reminders
Create recurring scheduled reminders to Feishu chats.
Before Creating
Always confirm with the user:
- 1. Frequency: How often? (e.g., every 10 min, every hour, daily at 9am)
- Target: Where to send? (default: current IM conversation)
Template
CODEBLOCK10
Interval Examples
| Interval | Description |
|---|
| INLINECODE47 | Every minute |
| INLINECODE48 |
Every 5 minutes |
|
30m | Every 30 minutes |
|
1h | Every hour |
|
*/30 * * * * | Cron expression (with
--tz) |
Management
cron list # List all tasks
cron edit <id> # Edit task
cron rm <id> # Delete (ask user first!)
cron runs --id <id> # View execution history
cron run <id> # Manual trigger
API Reference
| API | Method | Path |
|---|
| Tenant Token | POST | INLINECODE53 |
| Read Document |
GET |
/docx/v1/documents/{id}/raw_content |
| Create Document | POST |
/docx/v1/documents |
| Send Message | POST |
/im/v1/messages |
| Upload File | POST |
/im/v1/files |
| Upload Image | POST |
/im/v1/images |
| List Messages | GET |
/im/v1/messages |
| Manage Permissions | POST |
/drive/v1/permissions/{token}/members |
| Resolve Wiki | POST |
/wiki/v2/spaces/get_node |
Base URL: https://open.feishu.cn/open-apis
Notes
- - All APIs require
tenant_access_token in the Authorization header - File upload uses INLINECODE65
- Message sending uses INLINECODE66
- Bot can only download files it uploaded itself
- For detailed API docs, visit: https://open.feishu.cn/document
Feishu Toolkit (飞书工具箱)
面向AI代理的综合性飞书集成技能。涵盖6大核心能力：
- 1. 📄 文档操作 — 读取、创建、写入和追加飞书文档、表格、多维表格、知识库
- 💬 聊天记录 — 获取和总结群聊消息
- 📎 文件发送 — 通过REST API上传和发送文件到飞书聊天
- 📸 截图 — 截取macOS屏幕截图并发送到飞书
- 🔐 权限管理 — 列出、添加、删除文档协作者
- ⏰ 定时提醒 — 创建周期性定时提醒发送到飞书聊天
前置条件
飞书应用设置
- 1. 前往飞书开放平台创建应用
- 启用所需权限：
- im:message:send
asbot — 发送消息
- im:resource — 上传文件/图片
- docx:document — 读写文档
- drive:permission — 管理权限（可选）
- 3. 设置FEISHUAPPID和FEISHUAPPSECRET环境变量
认证
所有API调用使用飞书的租户访问令牌：
python
import requests
def gettenanttoken(appid, appsecret):
r = requests.post(
https://open.feishu.cn/open-apis/auth/v3/tenantaccesstoken/internal,
json={appid: appid, appsecret: appsecret}
)
return r.json()[tenantaccesstoken]
1. 文档操作（读取/写入/创建/追加）
读取文档
bash
获取文档内容为Markdown格式
支持：doc、docx、sheet、bitable、wiki
GET /open-apis/docx/v1/documents/{document
id}/rawcontent
创建文档
bash
POST /open-apis/docx/v1/documents
Body: {title: 我的文档}
写入（覆盖）文档
bash
用Markdown内容覆盖整个文档
POST /open-apis/docx/v1/documents/{document
id}/blocks/batchupdate
追加内容（长文档）
对于超出LLM输出限制的文档：
- 1. 创建文档以获取doc_token
- 将内容分块为逻辑段落
- 依次追加每个分块
- 如果文档非常长，不要尝试一次调用写入整个文档
知识库URL解析
知识库URL需要先解析为实际的文档令牌：
bash
POST /open-apis/wiki/v2/spaces/get_node
Body: {token: wiki_token}
返回实际的doctoken和doctype
2. 聊天记录
获取和总结飞书群聊中的消息。
获取消息
python
GET /open-apis/im/v1/messages
params = {
container
idtype: chat,
container
id: chatid,
page_size: 50
}
消息类型
| 类型 | 处理方式 |
|---|
| text | 提取.body.content JSON → text字段 |
| interactive |
从elements数组中提取文本节点 |
| image | 标记为[图片] |
| system | 除非相关，否则过滤掉 |
分页
如果has
more=true，使用pagetoken获取更多页面。默认：每页50条消息。
3. 文件发送
通过REST API发送文件到飞书聊天。
上传文件
python
POST /open-apis/im/v1/files
headers = {Authorization: fBearer {token}}
data = {file
type: stream, filename: filename.ext}
files = {file: (filename.ext, open(path, rb), application/octet-stream)}
支持的file_type：opus、mp4、pdf、doc、xls、ppt、stream（通用）
发送文件消息
python
POST /open-apis/im/v1/messages
json = {
receive
id: chatid,
msg_type: file,
content: json.dumps({file
key: filekey})
}
4. 截图与发送
截取macOS屏幕截图并发送到飞书。
bash
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
msgtype: image, content: {imagekey: ...}
注意：在macOS上使用$TMPDIR而非/tmp。
5. 权限管理
管理文档/文件的权限。
操作
删除协作者 |
| add | 添加协作者并设置权限级别 |
令牌类型
doc、docx、sheet、bitable、folder、file、wiki、mindnote
成员类型
email、openid、userid、unionid、openchat、opendepartmentid
权限级别
可编辑 |
| full_access | 完全访问（可管理权限） |
示例：分享文档
python
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点）
- 目标：发送到哪里？（默认：当前IM对话）
模板
bash
cron add \
--name <任务名称> \
--every <间隔> \
--session main \
--system-event [CRON] <任务名称>. 发送消息到飞书：<提醒内容>
间隔示例
每5分钟 |
| 30m | 每30分钟 |
| 1h | 每小时 |
|
/30 * | Cron表达式（配合--tz） |
管理
bash
cron list # 列出所有任务
cron edit
# 编辑任务
cron rm # 删除（先询问用户！）
cron runs --id # 查看执行历史
cron run # 手动触发
API参考
| API | 方法 | 路径 |
|---|
| 租户令牌 | POST | /auth/v3/tenantaccesstoken/internal |
| 读取文档 |
GET | /docx/v1/documents/{id}/raw_content |
| 创建文档 | POST | /docx/v1/documents |
| 发送消息 | POST | /im/v1/messages |
| 上传文件 | POST | /im/v1/files |
| 上传图片 | POST | /im/v1/images |
| 列出消息 | GET | /im/v1/messages |
| 管理权限 | POST | /drive/v1/permissions/{token}/members |
| 解析知识库 | POST | /wiki/v2/spaces/get_node |
基础URL：https://open.feishu.cn/open-apis
注意事项
- - 所有API需要在Authorization头中携带tenantaccesstoken
- 文件上传使用multipart/form-data
- 消息发送使用application/json
- 机器人只能下载自己上传的文件
- 详细API文档请访问：https://open.feishu.cn/document
