feishu-lark-agent

Feishu Lark Agent

Run

source ~/.zshrc && python3 ~/.claude/skills/feishu-lark-agent/feishu.py <category> <action> [--key value ...]

---

ID format quick reference (key)

Prefix	Type	Purpose
ou_	open_id	User ID, used for --to
oc_	chat_id	Group chat ID, used for --chat
Email	email	Used for --email, automatically resolved to open_id
docx/xxx URL latter part	document_id	Feishu document ID
base/xxx URL latter part	app_token	Bitable App Token

If you only have the name: first user search --name "张三" get the open_id, then perform the target operation.

---

Command quick reference

Message msg

msg send  --to <open_id|chat_id>   --text "..."     # open_id → ou_, chat_id → oc_
msg send  --email <email>          --text "..."     # 用邮箱发
msg send  --chat <chat_id>         --text "..."     # 发群
msg send  --to <open_id>           --file /path     # 发文件内容
msg reply --to <message_id>        --text "..."
msg history --chat <chat_id>      [--limit 20]
msg search  --query "关键词"       [--limit 20]
msg chats  [--limit 50]                             # 列出所有群聊

User user

user search --name "张三"          # 模糊搜索，返回 open_id
user get    --email <email>        # 精确查询
user get    --id <open_id>

Document doc

doc create  --title "标题"  [--content "markdown内容"]  [--file /path.md]
doc get     --id <document_id>     # 从 URL feishu.cn/docx/DOC_ID 取
doc list   [--folder <token>]     [--limit 50]

Automatically grant FEISHU_OWNER_OPEN_ID edit permission after creation.

Bitable table

table tables  --app <token>                         # 先列出所有 table
table fields  --app <token>  --table <id>           # 必须先查字段！
table records --app <token>  --table <id>  [--filter 'AND(CurrentValue.[状态]="进行中")']  [--limit 100]
table add     --app <token>  --table <id>  --data '{"字段名":"值"}'
table update  --app <token>  --table <id>  --record <recXXX>  --data '{"字段名":"新值"}'
table delete  --app <token>  --table <id>  --record <recXXX>

App token is in the URL：feishu.cn/base/APP_TOKEN

Calendar cal

cal calendars                                    # ⚠️ 第一步：列出 Bot 可访问的日历，获取 cal_id
cal list   --calendar <cal_id>   [--days 7]
cal add    --calendar <cal_id>   --title "..." --start "YYYY-MM-DD HH:MM" --end "YYYY-MM-DD HH:MM"  [--location "..."]  [--attendees "a@x.com,b@x.com"]
cal delete --calendar <cal_id>   --id <event_id>

⚠️ Important: Bot cannot access personal calendars (primary will report an error). You must first cal calendars get the Bot's own calendar ID, then use that ID to operate.

Task task

task list  [--completed true]  [--limit 50]
task add   --title "..."  [--due "YYYY-MM-DD"]  [--note "..."]
task done  --id <task_guid>
task delete --id <task_guid>

---

High-frequency scenarios (copy and execute directly)

1. Send message by name

# step1 获取 open_id
python3 feishu.py user search --name "张三"
# step2 发消息
python3 feishu.py msg send --to ou_xxx --text "你好"

2. Send message to a group(known group name → look up chat_id first)

python3 feishu.py msg chats        # 找到目标群的 chat_id (oc_xxx)
python3 feishu.py msg send --chat oc_xxx --text "通知内容"

3. Add a Bitable record(look up fields first to avoid misspelling field names)

python3 feishu.py table fields --app APP_TOKEN --table TABLE_ID
python3 feishu.py table add --app APP_TOKEN --table TABLE_ID --data '{"标题":"xxx","状态":"进行中"}'

4. Create a document and write content

python3 feishu.py doc create --title "会议记录" --content "# 会议记录\n\n## 议题\n- 内容"

5. View recent schedules(look up available calendars first)

python3 feishu.py cal calendars                  # 获取 Bot 的日历 ID
python3 feishu.py cal list --calendar <cal_id> --days 7

6. Create a schedule(look up calendar ID first)

python3 feishu.py cal calendars                  # 先获取 cal_id
python3 feishu.py cal add --calendar <cal_id> --title "周会" --start "2026-03-20 10:00" --end "2026-03-20 11:00"

---

Error quick reference

Error code	Cause	Solution
99991671	Permission not enabled	Add permission in Feishu Open Platform
230006	Calendar permission missing	Enable calendar:calendar
1254043	Bitable not found	Check the app_token in the URL
191001	Incorrect calendar ID	Cannot use primary, use the real cal_id
Missing FEISHU_APP_ID	Environment variable not loaded	source ~/.zshrc