feishu

我们通过 curl + jq 调用飞书开放平台 API。用户的 OAuth user_access_token 位于 $FEISHU_TOKEN 中；每次调用都会将其作为 Authorization: Bearer $FEISHU_TOKEN 发送。所有端点都位于 https://open.feishu.cn/open-apis 下。

调用在用户的上下文中运行（用户的文档、日历和消息）——只能访问用户有权查看的数据，且仅限用户连接时授权的范围（文档 / 表格 / 多维表格 / 云盘 / 日历 / IM / 知识库 / 任务 / 联系人）。

响应格式与错误处理

每个飞书响应的格式都是 {"code": 0, "msg": "success", "data": {…}}。 code == 0 表示成功；任何非零 code 都表示错误——向用户显示 msg。务必检查：

resp=$(curl -sS … )
echo "$resp" | jq 'if .code == 0 then .data else error("Feishu \(.code): \(.msg)") end'

常见错误代码：

code	含义	处理方式
99991663 / 99991668	访问令牌无效 / 已过期	提示用户在连接设置中重新连接飞书
99991661	无权限（未授予范围）	缺少连接时授权的范围——重新连接并授予该范围
1254xxx	未找到资源 / 无权访问	用户无法查看该文档 / 表格 / 应用——仔细检查令牌 / ID

操作示例

验证身份验证（始终先运行）

curl -sS https://open.feishu.cn/open-apis/authen/v1/user_info \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq 'if .code == 0 then {name: .data.name, open_id: .data.open_id, email: .data.email} else . end'

文档（docx）

飞书文档 URL 的格式为 https://…feishu.cn/docx/<document_id>。document_id 是路径的最后一段。

读取文档的纯文本：

curl -sS "https://open.feishu.cn/open-apis/docx/v1/documents/DOCUMENT_ID/raw_content" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq -r 'if .code == 0 then .data.content else "ERR \(.code): \(.msg)" end'

列出文档的块（结构化内容）：

curl -sS "https://open.feishu.cn/open-apis/docx/v1/documents/DOCUMENT_ID/blocks?page_size=500" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq 'if .code == 0 then [.data.items[] | {block_id, block_type}] else . end'

创建新的空白文档（可选择放入文件夹）：

curl -sS -X POST "https://open.feishu.cn/open-apis/docx/v1/documents" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc --arg title "会议纪要 2026-07-01" '{title: $title}')" \
  | jq 'if .code == 0 then {document_id: .data.document.document_id} else . end'

向文档追加文本块（插入到文档正文末尾—— DOCUMENT_ID 也是根块 ID）：

curl -sS -X POST "https://open.feishu.cn/open-apis/docx/v1/documents/DOCUMENT_ID/blocks/DOCUMENT_ID/children" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc --arg text "由助手追加的一段内容。" '
    {children: [{block_type: 2, text: {elements: [{text_run: {content: $text}}]}}]}')" \
  | jq 'if .code == 0 then "appended" else . end'

电子表格（sheets v2）

表格 URL 的格式为 https://…feishu.cn/sheets/<spreadsheet_token>。 范围格式为 <sheetId>!<A1:range>，例如 abc123!A1:D10。如果还没有工作表 ID，请先通过元信息端点列出工作表 ID。

读取范围：

curl -sS "https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/SPREADSHEET_TOKEN/values/RANGE" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq 'if .code == 0 then .data.valueRange.values else . end'

在最后一个非空行之后追加行：

curl -sS -X POST "https://open.feishu.cn/open-apis/sheets/v2/spreadsheets/SPREADSHEET_TOKEN/values_append" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc '{valueRange: {range: "SHEET_ID!A1:B1", values: [["张三", 100], ["李四", 200]]}}')" \
  | jq 'if .code == 0 then .data.updates else . end'

多维表格（bitable v1）

多维表格 URL 的格式为 https://…feishu.cn/base/<app_token>。通过 …/bitable/v1/apps/APP_TOKEN/tables 获取 table_id。

列出记录：

curl -sS "https://open.feishu.cn/open-apis/bitable/v1/apps/APP_TOKEN/tables/TABLE_ID/records?page_size=100" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq 'if .code == 0 then [.data.items[] | {record_id, fields}] else . end'

创建记录：

curl -sS -X POST "https://open.feishu.cn/open-apis/bitable/v1/apps/APP_TOKEN/tables/TABLE_ID/records" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc '{fields: {"标题": "新任务", "状态": "待办"}}')" \
  | jq 'if .code == 0 then {record_id: .data.record.record_id} else . end'

云盘文件

列出文件夹中的文件（根目录则省略 folder_token）：

curl -sS "https://open.feishu.cn/open-apis/drive/v1/files?folder_token=FOLDER_TOKEN&page_size=50" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq 'if .code == 0 then [.data.files[] | {name, type, token, url}] else . end'

日历（v4）

列出用户的日历（主日历的 type: "primary"）：

curl -sS "https://open.feishu.cn/open-apis/calendar/v4/calendars?page_size=50" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq 'if .code == 0 then [.data.calendar_list[] | {calendar_id, summary, type}] else . end'

列出指定时间范围内的事件（纪元秒数字符串）：

curl -sS "https://open.feishu.cn/open-apis/calendar/v4/calendars/CALENDAR_ID/events?start_time=1751299200&end_time=1751385600&page_size=100" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq 'if .code == 0 then [.data.items[] | {summary, start: .start_time, end: .end_time, event_id}] else . end'

创建事件（时间为纪元秒数字符串）：

curl -sS -X POST "https://open.feishu.cn/open-apis/calendar/v4/calendars/CALENDAR_ID/events" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc '{summary: "项目评审", start_time: {timestamp: "1751302800"}, end_time: {timestamp: "1751306400"}}')" \
  | jq 'if .code == 0 then {event_id: .data.event.event_id} else . end'

任务（v2）

列出用户的任务：

curl -sS "https://open.feishu.cn/open-apis/task/v2/tasks?page_size=50" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq 'if .code == 0 then [.data.items[] | {summary, completed_at, task_guid: .guid}] else . end'

创建任务：

curl -sS -X POST "https://open.feishu.cn/open-apis/task/v2/tasks" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc '{summary: "准备周会材料"}')" \
  | jq 'if .code == 0 then {task_guid: .data.task.guid} else . end'

知识库

列出知识库空间，然后列出空间内的节点：

curl -sS "https://open.feishu.cn/open-apis/wiki/v2/spaces?page_size=50" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq 'if .code == 0 then [.data.items[] | {space_id, name}] else . end'

curl -sS "https://open.feishu.cn/open-apis/wiki/v2/spaces/SPACE_ID/nodes?page_size=50" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  | jq 'if .code == 0 then [.data.items[] | {title, node_token, obj_type}] else . end'

发送 IM 消息

通过 open_id 向用户发送消息（向群聊发送时使用 receive_id_type=chat_id）。content 必须是 JSON 字符串，因此需要双重编码：

curl -sS -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id" \
  -H "Authorization: Bearer $FEISHU_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc --arg rid "ou_xxx" --arg text "你好，这是助手发送的消息。" '
    {receive_id: $rid, msg_type: "text", content: ({text: $text} | tostring)}')" \
  | jq 'if .code == 0 then {message_id: .data.message_id} else . end'

注意事项

• 执行具有破坏性或会对外产生影响的操作前（发送消息、创建日历邀请、发布到共享文档），先向用户确认。
• 分页：列表端点会返回 data.page_token / data.has_more；传入 page_token=… 获取下一页。
• 用户粘贴飞书链接时，从 URL 路径中提取令牌 / ID，不要向用户索要。