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
2. 💬 Chat History — Fetch and summarize group chat messages
3. 📎 File Sending — Upload and send files to Feishu chats via REST API
4. 📸 Screenshot — Capture macOS screenshots and send to Feishu
5. 🔐 Permission Management — List, add, remove document collaborators
6. ⏰ Cron Reminders — Create scheduled recurring reminders to Feishu chats

Prerequisites

Feishu App Setup

1. Go to Feishu Open Platform and create an app
2. 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

# Fetch document content as Markdown
# Supports: doc, docx, sheet, bitable, wiki
GET /open-apis/docx/v1/documents/{document_id}/raw_content

Create a Document

POST /open-apis/docx/v1/documents
Body: {"title": "My Document"}

Write (Overwrite) a Document

# Overwrite entire document content with Markdown
POST /open-apis/docx/v1/documents/{document_id}/blocks/batch_update

Append Content (Long Documents)

For documents exceeding LLM output limits:
1. Create the document first to get a doc_token
2. Chunk content into logical sections
3. Append each chunk sequentially
4. 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

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

Message Types

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

# 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')}

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.

# 1. Capture screenshot
SCREENSHOT_PATH="$TMPDIR/screenshot_$(date +%s).png"
screencapture -x "$SCREENSHOT_PATH"

# 2. Upload image
# POST /open-apis/im/v1/images
# data: image_type=message, file=screenshot

# 3. Send image message
# POST /open-apis/im/v1/messages
# msg_type: image, content: {"image_key": "..."}

> Note: Use $TMPDIR not /tmp on macOS.

5. Permission Management

Manage document/file permissions.

Actions

Token Types

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

Member Types

email, openid, userid, unionid, openchat, opendepartmentid

Permission Levels

Example: Share document

# POST /open-apis/drive/v1/permissions/{token}/members
params = {'type': 'docx'}
json = {
    'member_type': 'email',
    'member_id': '[email protected]',
    'perm': 'edit'
}

> 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)
2. Target: Where to send? (default: current IM conversation)

Template

cron add \
  --name "<task_name>" \
  --every "<interval>" \
  --session main \
  --system-event "[CRON] <task_name>. Send message to Feishu: '<reminder_content>'"

Interval Examples

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

Base URL: https://open.feishu.cn/open-apis

Notes

• All APIs require tenant_access_token in the Authorization header
• File upload uses multipart/form-data
• Message sending uses application/json
• Bot can only download files it uploaded itself
• For detailed API docs, visit: https://open.feishu.cn/document