Author: Produced by 43 COLLEGE 凯寓 (KAIYU) Version: v2.0
Implement operations for messages, docs, wiki, calendar, group chats, Bitable, mail, etc. through the Feishu Open API. Supports two running modes: when lark-cli is available, automatic proxying (zero configuration); when app_secret is available, direct API connection (faster).
First-Time Configuration
If a command errors out saying it cannot find config.json or app_id is empty, read the SETUP.md in this directory and guide the user through configuration according to the process in it.
Quick Start
Send a message to a colleague
- Read the
scripts/config.jsonfield inteam_members(name → open_id mapping) - Find the target colleague's open_id
- Execute the send-message command
python3 scripts/feishu_client.py send-message --type text --content "消息内容" --receive_id "ou_xxx" --receive_id_type open_id
Send a message to a group
- Read
scripts/config.jsonindefault_chat_id receive_id_typechange tochat_id
python3 scripts/feishu_client.py send-message --type text --content "消息内容" --receive_id "oc_xxx" --receive_id_type chat_id
Important: Before sending a message, first look up the target colleague's open_id from config.json in team_members .
Platform Notes (Cross-Platform Compatibility)
Python command: On macOS/Linux use python3, on Windows use python. Detect which one is available before calling.
Path format：
- macOS/Linux：
~/.claude/skills/feishu-assistant/ - Windows：
%USERPROFILE%\.claude\skills\feishu-assistant\
All commands are invoked through python3 scripts/feishu_client.py <command>(macOS/Linux) or python scripts\feishu_client.py <command>(Windows).
Before executing, you must first cd to the root directory of this skill.
Core Commands
Messages
# 发送文本消息（支持 text/post/interactive/image）
python3 scripts/feishu_client.py send-message --type text --content "内容" --receive_id "ou_xxx" --receive_id_type open_id
# 向群组发消息
python3 scripts/feishu_client.py send-message --type text --content "内容" --receive_id "oc_xxx" --receive_id_type chat_id
# 读取群消息
python3 scripts/feishu_client.py get-chat-messages --chat_id "oc_xxx" --page_size 20
Group Chat Management
# 创建群聊并拉入成员（members 为逗号分隔的 open_id）
python3 scripts/feishu_client.py create-chat --name "项目群" --members "ou_xxx,ou_yyy" --description "项目讨论群"
# 向已有群添加成员
python3 scripts/feishu_client.py add-chat-members --chat_id "oc_xxx" --members "ou_xxx,ou_yyy"
# 从群中移除成员
python3 scripts/feishu_client.py remove-chat-members --chat_id "oc_xxx" --members "ou_xxx"
# 获取群聊信息
python3 scripts/feishu_client.py get-chat-info --chat_id "oc_xxx"
# 修改群聊信息
python3 scripts/feishu_client.py update-chat --chat_id "oc_xxx" --name "新群名" --description "新描述"
# 列出群聊成员
python3 scripts/feishu_client.py list-chat-members --chat_id "oc_xxx"
# 解散群聊（不可恢复）
python3 scripts/feishu_client.py dissolve-chat --chat_id "oc_xxx"
Docs
# 创建文档
python3 scripts/feishu_client.py create-doc --title "标题" --content "内容"
# 更新文档
python3 scripts/feishu_client.py update-doc --doc_token "doxcxxx" --content "新内容"
Wiki
# 列出所有知识库空间
python3 scripts/feishu_client.py list-wiki-spaces
# 列出空间下的文章
python3 scripts/feishu_client.py list-wiki-nodes --space_id "xxx" --page_size 50
# 读取文章纯文本内容
python3 scripts/feishu_client.py read-wiki-node --node_token "xxx"
Contacts and Organization
# 显示团队通讯录（从缓存读取）
python3 scripts/feishu_client.py show-contacts
# 刷新通讯录缓存
python3 scripts/feishu_client.py refresh-contacts
# 显示知识库列表
python3 scripts/feishu_client.py show-spaces
# 刷新知识库缓存
python3 scripts/feishu_client.py refresh-spaces
# 显示组织信息
python3 scripts/feishu_client.py show-org
# 通过邮箱查用户
python3 scripts/feishu_client.py get-user --email "user@example.com"
File Upload
python3 scripts/feishu_client.py upload-file --file_path "path/to/file.pdf" --parent_node "fldxxx"
Calendar
# 查看我的日历列表
python3 scripts/feishu_client.py list-calendars
# 查看指定时间范围内的日程
python3 scripts/feishu_client.py list-events --calendar_id primary --start_time "2026-03-02 00:00" --end_time "2026-03-08 23:59"
# 创建日程
python3 scripts/feishu_client.py create-event --summary "周会" --start_time "2026-03-05 14:00" --end_time "2026-03-05 15:00" --description "每周例会" --attendees "ou_xxx,ou_yyy"
# 查看日程详情
python3 scripts/feishu_client.py get-event --calendar_id primary --event_id "xxx"
# 修改日程
python3 scripts/feishu_client.py update-event --calendar_id primary --event_id "xxx" --summary "新标题"
# 删除日程
python3 scripts/feishu_client.py delete-event --calendar_id primary --event_id "xxx"
# 查询忙闲信息（查自己）
python3 scripts/feishu_client.py query-freebusy --start_time "2026-03-29" --end_time "2026-03-30"
# 查询指定同事的忙闲信息
python3 scripts/feishu_client.py query-freebusy --start_time "2026-03-29 09:00" --end_time "2026-03-29 18:00" --user_id "ou_xxx"
# 推荐多人共同空闲时段（自动查询所有参会人的忙闲，计算交集）
python3 scripts/feishu_client.py suggest-meeting-time --start_time "2026-03-31 09:00" --end_time "2026-03-31 18:00" --attendees "ou_xxx,ou_yyy" --duration 30
Free/Busy Query vs Free-Time Recommendation：
query-freebusy: Query one person's list of busy periods (including RSVP status); only returns times, not schedule detailssuggest-meeting-time: Query multiple people, automatically calculate common free time, and return up to 5 recommended time slots
Task Management
# 创建任务
python3 scripts/feishu_client.py create-task --summary "完成周报" --due "2026-03-31 18:00" --description "整理本周工作内容"
# 创建无截止时间的简单任务
python3 scripts/feishu_client.py create-task --summary "回复客户邮件"
# 查看我的任务列表
python3 scripts/feishu_client.py list-tasks --page_size 20
# 获取任务详情
python3 scripts/feishu_client.py get-task --task_id "xxx"
# 更新任务标题或描述
python3 scripts/feishu_client.py update-task --task_id "xxx" --summary "新标题" --description "新描述"
# 标记任务为已完成
python3 scripts/feishu_client.py complete-task --task_id "xxx"
# 或通过 update-task 标记完成
python3 scripts/feishu_client.py update-task --task_id "xxx" --completed
Note: Task management uses the Feishu Task v2 API and requires user authorization (user_token).complete-task is a shortcut for update-task --completed .
Spreadsheets (Sheets)
# 创建电子表格
python3 scripts/feishu_client.py create-sheet --title "销售数据"
# 读取表格数据（token 从表格 URL 提取）
python3 scripts/feishu_client.py read-sheet --token "shtcnXXX" --range "Sheet1!A1:C10"
# 写入数据（二维数组 JSON）
python3 scripts/feishu_client.py write-sheet --token "shtcnXXX" --range "Sheet1!A1" --values '[["姓名","分数"],["张三","95"]]'
# 追加数据到表格末尾
python3 scripts/feishu_client.py append-sheet --token "shtcnXXX" --range "Sheet1" --values '[["李四","88"]]'
How to get token: Extract it from the spreadsheet URL, in the format https://xxx.feishu.cn/sheets/{token}
Difference from Bitable: Spreadsheets (Sheets) are traditional row-and-column tables, suitable for simple data entry and calculation; Bitable (Base) is a structured database that supports advanced features such as field types, views, and relations.
Bitable (Base)
# 列出数据表
python3 scripts/feishu_client.py list-base-tables --app_token "bascnXXX"
# 列出字段
python3 scripts/feishu_client.py list-base-fields --app_token "bascnXXX" --table_id "tblXXX"
# 列出记录
python3 scripts/feishu_client.py list-base-records --app_token "bascnXXX" --table_id "tblXXX" --page_size 50
# 获取单条记录
python3 scripts/feishu_client.py get-base-record --app_token "bascnXXX" --table_id "tblXXX" --record_id "recXXX"
# 创建记录（fields 为 JSON）
python3 scripts/feishu_client.py create-base-record --app_token "bascnXXX" --table_id "tblXXX" --fields '{"名称":"测试","状态":"进行中"}'
# 批量创建记录
python3 scripts/feishu_client.py batch-create-base-records --app_token "bascnXXX" --table_id "tblXXX" --records '[{"名称":"A"},{"名称":"B"}]'
# 更新记录
python3 scripts/feishu_client.py update-base-record --app_token "bascnXXX" --table_id "tblXXX" --record_id "recXXX" --fields '{"状态":"已完成"}'
# 删除记录
python3 scripts/feishu_client.py delete-base-record --app_token "bascnXXX" --table_id "tblXXX" --record_id "recXXX"
# 创建数据表
python3 scripts/feishu_client.py create-base-table --app_token "bascnXXX" --name "新表"
# 创建字段（field_type: 1=文本, 2=数字, 3=单选, 4=多选, 5=日期, 7=复选框, 11=人员, 15=超链接, 17=附件）
python3 scripts/feishu_client.py create-base-field --app_token "bascnXXX" --table_id "tblXXX" --field_name "优先级" --field_type 3
How to get app_token: Extract it from the Bitable URL, in the format https://xxx.feishu.cn/base/{app_token}
# 获取当前用户邮箱地址
python3 scripts/feishu_client.py mail-profile
# 查看收件箱
python3 scripts/feishu_client.py list-mail --folder INBOX --page_size 20
# 查看已发送
python3 scripts/feishu_client.py list-mail --folder SENT
# 读取邮件
python3 scripts/feishu_client.py read-mail --message_id "xxx"
# 搜索邮件
python3 scripts/feishu_client.py search-mail --query "关键词"
# 发送邮件（默认 HTML 格式）
python3 scripts/feishu_client.py send-mail --to "alice@example.com" --subject "标题" --body "<p>正文</p>"
# 发送纯文本 / 多收件人 / 带抄送
python3 scripts/feishu_client.py send-mail --to "a@x.com,b@x.com" --cc "c@x.com" --subject "标题" --body "正文" --plain_text
# 创建草稿（不发送）
python3 scripts/feishu_client.py draft-mail --to "alice@example.com" --subject "标题" --body "正文"
Important: Before sending an email, you must confirm the recipient and content.
Initialization
See the "First-Time Configuration" section and SETUP.md。
Cache Notes
- Contacts：
scripts/cache/contacts.json, format[{"name": "张三", "open_id": "ou_xxx", ...}] - Wiki list：
scripts/cache/wiki_spaces.json, format[{"name": "空间名", "space_id": "xxx", ...}] - Default group chat ID：
scripts/config.jsonindefault_chat_id - team_members：
scripts/config.jsoninteam_members(Name → open_id mapping)
If the cache does not exist, run refresh-contacts or refresh-spaces to generate it.
Dual-mode architecture
feishu_client.py supports two operating modes, selected automatically:
| Mode | Condition | Features |
|---|---|---|
| Direct mode | config.json has app_secret + cache/user_token.json | Calls the Feishu API directly, fastest |
| lark-cli proxy mode | No app_secret or no user_token, but lark-cli is available | Through lark-cli api proxy requests, zero configuration |
Existing users with a configured setup (app_secret + OAuth token) continue to use direct mode with no impact. After new users configure via lark-cli, all requests automatically go through the lark-cli proxy, with no need to manually manage tokens.
Troubleshooting
| Error | Cause | Fix |
|---|---|---|
| config.json does not exist | Installation guide not run | Run python3 scripts/setup.py |
| lark-cli not installed | No lark-cli and no app_secret | npm install -g @larksuite/cli && lark-cli config init --new && lark-cli auth login --domain all |
| lark-cli call failed | Token expired | lark-cli auth login --domain all reauthorize |
| Contacts/Knowledge Base cache is empty | Cache not refreshed | Run refresh-contacts or refresh-spaces |
| Bot has NO availability | The bot's availability scope does not include the target user | On the Feishu Open Platform, set the app's availability scope to "All employees" and republish |
| Insufficient permissions | Missing required scope | lark-cli auth login --domain all add authorization |
Feishu Open Platform backend:https://open.feishu.cn/app