feishu-cli-toolkit

飞书综合工具箱 覆盖 feishu-cli 的 13 个功能模块，提供命令速查和核心用法。复杂模块的详细参考文档在 references/ 目录中。 模块速查表 # 模块 核心命令 详细参考 1 电子表格 sheet create/get/read/write/append + V3 富文本 references/sheet-commands.md 2 日历日程 calendar list/get/primary/create-event/event-search/freebusy references/calendar-commands.md 3 任务管理 task create/complete/delete + subtask/member/reminder + tasklist references/task-commands.md 4 群聊管理 chat create/get/update/delete/link + chat member references/chat-commands.md 5 画板操作 board image/import/nodes + doc add-board references/board-commands.md 6 PlantUML 飞书画板安全子集语法 references/plantuml-safe-subset.md 7 文件管理 file list/mkdir/move/copy/delete/download/upload/version/meta/stats — 8 素材管理 media upload/download — 9 评论管理 comment list/add/delete/resolve/unresolve + comment reply — 10 知识库 wiki get/export/spaces/nodes/space-get + wiki member — 11 搜索 search messages/apps/docs（需 User Access Token，推荐使用 feishu-cli-search 技能） references/search-commands.md 12 用户和部门 user info/search/list + dept get/children — 13 附件下载 doc export + media download 批量下载文档附件 — 1. 电子表格 支持 V2（简单二维数组）和 V3（富文本三维数组）两套 API。 常用命令 # 创建表格 feishu-cli sheet create --title "新表格" # 获取表格信息 feishu-cli sheet get # 列出工作表 feishu-cli sheet list-sheets # V2 读写（二维数组） feishu-cli sheet read "Sheet1!A1:C10" feishu-cli sheet write "Sheet1!A1:B2" --data '[["姓名","年龄"],["张三",25]]' feishu-cli sheet append "Sheet1!A:B" --data '[["新行1","新行2"]]' # V3 富文本读写（三维数组） feishu-cli sheet read-plain <sheet_id> "Sheet1!A1:C10" feishu-cli sheet read-rich <sheet_id> "Sheet1!A1:C10" feishu-cli sheet write-rich <sheet_id> --data-file data.json # 行列操作 feishu-cli sheet add-rows <sheet_id> --count 5 feishu-cli sheet add-cols <sheet_id> --count 3 feishu-cli sheet delete-rows <sheet_id> --start 2 --end 5 feishu-cli sheet delete-cols <sheet_id> --start 1 --end 3 # 样式和格式 feishu-cli sheet merge "Sheet1!A1:B2" feishu-cli sheet unmerge "Sheet1!A1:B2" feishu-cli sheet style "Sheet1!A1:C3" --bold --bg-color "#FF0000" # 查找替换（--range 必填，范围不要超出实际数据区域） feishu-cli sheet find <sheet_id> "关键词" --range "A1:C10" feishu-cli sheet replace <sheet_id> "查找词" "替换词" --range "A1:C10" API 限制 单次写入最多 5000 个单元格，单元格最大 50000 字符 V2 范围格式：SheetID!A1:C10，支持整列 A:C 和整行 1:3 V3 写入限制：单次最多 10 个范围 详细参考：读取 references/sheet-commands.md 获取 V3 富文本格式、工作表管理、单元格图片等完整说明。 权限要求：sheets:spreadsheet 2. 日历和日程 管理飞书日历、日程、参与人和忙闲查询。时间格式统一使用 RFC3339（如 2024-01-01T10:00:00+08:00）。 常用命令 # 日历 feishu-cli calendar list # 列出日历 feishu-cli calendar get <calendar_id> # 获取日历详情 feishu-cli calendar primary # 获取主日历 # 日程 CRUD feishu-cli calendar create-event \ --calendar-id \ --summary "团队周会" \ --start "2024-01-21T14:00:00+08:00" \ --end "2024-01-21T15:00:00+08:00" \ --description "讨论本周进展" feishu-cli calendar list-events <calendar_id> --start-time --end-time feishu-cli calendar get-event <calendar_id> <event_id> feishu-cli calendar update-event <calendar_id> <event_id> --summary "新标题" feishu-cli calendar delete-event <calendar_id> <event_id> # 搜索日程 feishu-cli calendar event-search --calendar-id --query "周会" # 回复日程邀请 feishu-cli calendar event-reply <calendar_id> <event_id> --status accept # accept/decline/tentative # 参与人管理 feishu-cli calendar attendee add <calendar_id> <event_id> --user-ids id1,id2 feishu-cli calendar attendee list <calendar_id> <event_id> # 忙闲查询 feishu-cli calendar freebusy \ --start "2024-01-01T00:00:00+08:00" \ --end "2024-01-02T00:00:00+08:00" \ --user-id <user_id> 详细参考：读取 references/calendar-commands.md 获取完整参数说明。 权限要求：calendar:calendar:readonly（读取），calendar:calendar（写操作，需单独申请） 3. 任务管理 管理飞书任务（V2 API），包括子任务、成员、提醒和任务清单。任务 ID 为 UUID 格式。 常用命令 # 任务 CRUD feishu-cli task create --summary "完成代码审查" --description "详细描述" --due "2024-02-01" feishu-cli task list [--completed | --uncompleted] feishu-cli task get <task_id> feishu-cli task update <task_id> --summary "新标题" feishu-cli task complete <task_id> feishu-cli task delete <task_id> # 子任务 feishu-cli task subtask create <task_guid> --summary "子任务标题" feishu-cli task subtask list <task_guid> # 成员管理 feishu-cli task member add <task_guid> --members id1,id2 --role assignee # assignee/follower feishu-cli task member remove <task_guid> --members id1,id2 --role assignee # 提醒 feishu-cli task reminder add <task_guid> --minutes 30 # 提前 30 分钟提醒，0=截止时 feishu-cli task reminder remove <task_guid> --ids id1,id2 # 任务清单 feishu-cli tasklist create --name "Sprint 计划" feishu-cli tasklist list feishu-cli tasklist get <tasklist_guid> feishu-cli tasklist delete <tasklist_guid> 详细参考：读取 references/task-commands.md 获取完整参数说明。 权限要求：task:task:read、task:task:write、task:tasklist:read、task:tasklist:write（需单独申请） 4. 群聊管理 创建/管理群聊，管理群成员。 常用命令 # 群聊 CRUD feishu-cli chat create --name "项目群" --user-ids id1,id2 [--chat-type private|public] feishu-cli chat get <chat_id> feishu-cli chat update <chat_id> --name "新群名" [--description "新描述"] feishu-cli chat delete <chat_id> # 获取群分享链接 feishu-cli chat link <chat_id> [--validity-period week|year|permanently] # 群成员管理 feishu-cli chat member list <chat_id> [--member-id-type open_id|user_id|union_id] feishu-cli chat member add <chat_id> --id-list id1,id2 [--member-id-type open_id] feishu-cli chat member remove <chat_id> --id-list id1,id2 [--member-id-type open_id] 详细参考：读取 references/chat-commands.md 获取完整参数和示例。 权限要求：im:chat（群聊管理）、im:chat:read（读取）、im:chat:member（成员操作） 5. 画板操作 下载画板图片、导入 Mermaid/PlantUML 图表到画板。 常用命令 # 下载画板为 PNG 图片 feishu-cli board image <whiteboard_id> output.png # 导入图表到画板 feishu-cli board import <whiteboard_id> diagram.puml # PlantUML 文件 feishu-cli board import <whiteboard_id> diagram.mmd --syntax mermaid # Mermaid 文件 feishu-cli board import <whiteboard_id> --source-type content -c "graph TD; A-->B" --syntax mermaid # 内容直接导入 # 获取画板节点列表 feishu-cli board nodes <whiteboard_id> # 在文档中添加空白画板 feishu-cli doc add-board <document_id> [--parent-id <block_id> --index 0] 图表导入参数 参数 说明 --syntax plantuml（默认）或 mermaid --diagram-type 0=auto, 1=mindmap, 2=sequence, 3=activity, 4=class, 5=er, 6=flowchart, 7=state, 8=component --style board（默认）或 classic --source-type file（默认）或 content -c, --content 当 source-type=content 时的图表内容 支持的 Mermaid 类型（8 种，全部已验证） flowchart、sequenceDiagram、classDiagram、stateDiagram-v2、erDiagram、gantt、pie、mindmap 详细参考：读取 references/board-commands.md 获取完整说明。 权限要求：board:board（画板操作）、docx:document（文档画板） 6. PlantUML 图表生成 生成适配飞书画板的 PlantUML 图表。默认推荐 Mermaid（飞书原生支持更好），仅在 Mermaid 不支持的图类型（用例图、组件图、复杂活动图）时才用 PlantUML。 安全子集核心规则 必须使用 @startuml/@enduml 包裹（思维导图用 @startmindmap/@endmindmap） 不要使用行首缩进（飞书画板将缩进行视为独立行） 避免 skinparam、!define、颜色/字体/对齐控制、方向控制指令 类图避免可见性标记（+ - # ~），用 field : type 或 method() 格式 支持的图类型 活动图/流程图、时序图、类图、用例图、组件图、ER 图、思维导图 导入方式 在 Markdown 中使用 ```plantuml 代码块，通过 feishu-cli doc import 导入 直接通过 board import 命令导入到画板 详细参考：读取 references/plantuml-safe-subset.md 获取每种图类型的安全语法规范。 7. 文件管理（云空间文件） 定义：管理飞书云空间（Drive）中的文件和文件夹，包括文档、表格、本地文件等的 CRUD、版本管理、元数据和统计。 适用场景： 管理云空间文件夹结构（创建文件夹、移动/复制文件） 下载云空间中的独立文件（如 PDF、Word、Excel 等） 管理文件版本和元数据 与素材/附件的区别： 维度 云空间文件 素材（media） 文档附件 存储位置 云空间（Drive） 临时素材库 文档内嵌 管理方式 独立文件管理 依附于文档/消息 依附于文档 下载命令 file download media download doc export + media download 权限 drive:drive drive:drive docx:document + drive:file:download 常用命令 # 列出文件 feishu-cli file list [folder_token] # 创建文件夹 feishu-cli file mkdir "文件夹名" [--parent <folder_token>] # 移动/复制/删除 feishu-cli file move <file_token> --target <folder_token> --type <docx|sheet|file|...> feishu-cli file copy <file_token> --target <folder_token> --type [--name "新名"] feishu-cli file delete <file_token> --type # 移到回收站，30 天可恢复 # 下载/上传 feishu-cli file download <file_token> -o output.pdf feishu-cli file upload local_file.pdf --parent <FOLDER_TOKEN> [--name "自定义名"] # 版本管理 feishu-cli file version list <file_token> [--obj-type docx] feishu-cli file version create <file_token> --name "v1.0" [--obj-type docx] feishu-cli file version get <file_token> <version_id> feishu-cli file version delete <file_token> <version_id> # 元数据和统计 feishu-cli file meta TOKEN1 TOKEN2 --doc-type docx # 批量获取元数据 feishu-cli file stats <file_token> --doc-type docx # 获取统计信息 文件类型 docx、doc、sheet、bitable、mindnote、folder、file 权限要求：drive:drive:readonly（读取）、drive:drive（写操作） 8. 素材管理（Media） 定义：管理飞书素材系统中的临时文件，包括上传到文档/消息的图片和附件，以及下载已上传的素材。 适用场景： 上传图片或文件到飞书素材库（用于插入文档、发送消息） 下载已上传的素材（通过 file_token） 管理文档内嵌的图片和附件资源 与云空间文件/文档附件的区别： 维度 素材（Media） 云空间文件（File） 文档附件 用途 文档/消息插入 独立文件存储 文档内嵌附件 生命周期 依附于父资源 独立管理 随文档存在 Token 来源 上传返回 / 文档解析 云空间列表 导出文档解析 典型命令 media upload/download file list/download doc export + media download 常用命令 # 上传素材（用于文档中的图片/附件） feishu-cli media upload image.png \ --parent-type docx_image \ --parent-node <doc_id> # 下载素材 feishu-cli media download <file_token> -o output.png parent-type 参数说明 值 说明 docx_image 新版文档图片（默认） docx_file 新版文档附件 doc_image 旧版文档图片 doc_file 旧版文档附件 sheet_image 电子表格图片 comment_image 评论图片 限制 图片最大 20MB，支持 PNG/JPG/JPEG/GIF/BMP/SVG/WEBP 文件最大 512MB，支持 PDF/DOC/DOCX/XLS/XLSX/PPT/PPTX/ZIP 等 权限要求：drive:drive:readonly（下载）、drive:drive（上传） 9. 评论管理 管理飞书云文档的评论，包括全文评论、评论解决/取消解决、回复管理。 常用命令 # 列出评论 feishu-cli comment list <file_token> --type docx # 添加全文评论 feishu-cli comment add <file_token> --type docx --text "评论内容" # 删除评论（不可逆） feishu-cli comment delete <file_token> <comment_id> --type docx # 解决/取消解决评论 feishu-cli comment resolve <file_token> <comment_id> --type docx feishu-cli comment unresolve <file_token> <comment_id> --type docx # 回复管理 feishu-cli comment reply list <file_token> <comment_id> --type docx feishu-cli comment reply delete <file_token> <comment_id> <reply_id> --type docx 支持的文件类型 --type 参数支持：docx、doc、sheet、bitable 权限要求：drive:drive.comment:readonly（读取）、drive:drive.comment:write（写入） 10. 知识库 查看知识空间、获取知识库节点、导出知识库文档、管理空间成员。 常用命令 # 获取节点信息（支持 URL 或 token） feishu-cli wiki get <node_token> # 导出为 Markdown feishu-cli wiki export <node_token> -o doc.md [--download-images --assets-dir ./assets] # 列出知识空间 feishu-cli wiki spaces [--page-size 20] # 列出空间下的节点 feishu-cli wiki nodes <space_id> [--parent <node_token>] # 获取空间详情 feishu-cli wiki space-get <space_id> # 空间成员管理 feishu-cli wiki member add <space_id> --member-type userid --member-id <USER_ID> --role admin feishu-cli wiki member list <space_id> feishu-cli wiki member remove <space_id> --member-type userid --member-id <USER_ID> --role admin 重要概念 知识库使用 node_token（区别于普通文档的 document_id） 目录节点导出内容为 [Wiki 目录...]，需用 wiki nodes 获取子节点 成员角色：admin（管理员）、member（成员） 成员类型：openchat、userid、email、opendepartmentid、openid 权限要求：wiki:wiki:readonly（读取）、wiki:wiki（空间成员管理） 11. 搜索 搜索飞书消息、应用和文档。重要：需要 User Access Token（非 App Access Token）。 常用命令 # 搜索消息 feishu-cli search messages "关键词" \ --user-access-token \ [--chat-ids oc_xxx] \ [--message-type file|image|media] \ [--chat-type group_chat|p2p_chat] \ [--from-type bot|user] \ [--start-time 1704067200] \ [--end-time 1704153600] # 搜索应用 feishu-cli search apps "应用名" --user-access-token # 搜索文档和 Wiki feishu-cli search docs "关键词" \ --user-access-token \ [--docs-types doc,sheet,wiki] \ [--owner-ids ou_xxx] \ [--chat-ids oc_xxx] \ [--count 20] \ [--offset 0] 文档搜索要点 文档类型使用小写：doc, docx, sheet, slides, bitable, mindnote, file, wiki, shortcut 搜索范围：可按所有者、群聊筛选 分页：通过 --count 和 --offset 控制（offset + count < 200） User Access Token 说明 搜索 API 必须使用 User Access Token。完整的认证流程、scope 配置、排错指南请参考 feishu-cli-auth 技能。 快速参考： 推荐 scope：search:docs:read search:message offline_access AI Agent 使用两步式非交互登录：auth login --print-url + auth callback Token 有效期 2 小时，Refresh Token 30 天（需 offline_access scope） 登录后无需手动传 Token，过期自动刷新 搜索参数详细参考：读取 references/search-commands.md 获取完整筛选参数说明。 12. 用户和部门 查询用户信息、通过邮箱/手机号查找用户、列出部门成员和子部门。 常用命令 # 获取用户信息 feishu-cli user info <user_id> [--user-id-type open_id|union_id|user_id] # 通过邮箱/手机号查询用户 ID feishu-cli user search --email user@example.com feishu-cli user search --mobile 13800138000 feishu-cli user search --email "a@example.com,b@example.com" # 批量查询 # 列出部门下的用户 feishu-cli user list --department-id <dept_id> [--user-id-type open_id] # 获取部门详情 feishu-cli dept get <department_id> [--department-id-type open_department_id] # 获取子部门列表（根部门使用 "0"） feishu-cli dept children <department_id> [--department-id-type open_department_id] 权限要求：contact:user.base:readonly（用户信息）、contact:department.base:readonly（部门查询） 13. 文档附件下载（Document Attachments） 定义：从飞书文档（Docx）或知识库（Wiki）页面中批量提取并下载内嵌的附件文件。 适用场景： 文档中包含多个附件需要批量下载（如资料包、压缩包、PDF 等） 需要备份文档中的所有附件资源 文档转发后需要获取其中的附件 与云空间文件/素材的区别： 维度 文档附件 云空间文件（File） 素材（Media） 存储方式 文档内嵌（File Block） 云空间独立文件 临时素材库 获取方式 先导出文档解析链接 直接通过 file_token 下载 通过 token 下载 批量能力 支持批量下载文档内所有附件 单文件操作 单文件操作 依赖权限 docx:document + drive:file:download drive:drive drive:drive 工作流程： 导出文档为 Markdown → 2. 解析 filename 链接 → 3. 批量下载附件 工作原理 导出文档：使用 doc export 或 wiki export 将文档转为 Markdown 解析附件：从 Markdown 中提取 filename 格式的附件链接 批量下载：使用 media download 下载每个附件 冲突处理：自动为同名文件添加序号后缀（如 file (1).pdf） 支持的输入格式 格式 示例 文档 URL https://xxx.feishu.cn/docx/T1McdFgZcoEtHQxfadicXwwCn6e 知识库 URL https://xxx.feishu.cn/wiki/AbCdEfGhIjKlMnOp 纯文档 ID T1McdFgZcoEtHQxfadicXwwCn6e docx ID docxT1McdFgZcoEtHQxfadicXwwCn6e wiki Token wikiAbCdEfGhIjKlMnOp 使用步骤 # 步骤 1: 导出文档 feishu-cli doc export <document_id> -o /tmp/doc.md # 步骤 2: 解析附件链接（用 tab 分隔文件名和 token，避免文件名含空格时出错） grep -oE '[[^]]+](feishu://file/[^)]+)' /tmp/doc.md | \ sed $'s/^\//;s/\$//' > /tmp/attachments.txt # 步骤 3: 创建输出目录 mkdir -p ./attachments_<doc_id> # 步骤 4: 批量下载 while IFS=$'\t' read -r filename token; do feishu-cli media download "$token" -o "./attachments_<doc_id>/$filename" done < /tmp/attachments.txt 完整脚本示例 #!/bin/bash INPUT="$1" # 文档 ID/URL OUTPUT_DIR="${2:-./attachments_$(echo "$INPUT" | tr '/' '')}" # 提取文档 ID 或 Wiki Token DOC_ID="" WIKI_TOKEN="" if echo "$INPUT" | grep -qE 'wiki/[A-Za-z0-9]+'; then WIKI_TOKEN=$(echo "$INPUT" | grep -oP 'wiki/\K[A-Za-z0-9]+' 2>/dev/null) elif echo "$INPUT" | grep -qE '^wiki[A-Z]'; then WIKI_TOKEN=$(echo "$INPUT" | grep -oE '^wiki[A-Z][A-Za-z0-9]+') elif echo "$INPUT" | grep -qE 'docx/[A-Za-z0-9]+'; then DOC_ID=$(echo "$INPUT" | grep -oP 'docx/\K[A-Za-z0-9]+' 2>/dev/null) elif echo "$INPUT" | grep -qE 'docx[A-Z]'; then DOC_ID=$(echo "$INPUT" | grep -oE 'docx[A-Z][A-Za-z0-9]+' | head -1) elif echo "$INPUT" | grep -qE '^[A-Z][A-Za-z0-9]+$'; then DOC_ID="$INPUT" fi if [ -z "$DOC_ID" ] && [ -z "$WIKI_TOKEN" ]; then echo "无法识别的文档标识符" exit 1 fi # 导出并下载 if [ -n "$WIKI_TOKEN" ]; then TMP_MD="/tmp/wiki${WIKI_TOKEN}.md" feishu-cli wiki export "$WIKI_TOKEN" -o "$TMP_MD" else TMP_MD="/tmp/doc_${DOC_ID}.md" feishu-cli doc export "$DOC_ID" -o "$TMP_MD" fi mkdir -p "$OUTPUT_DIR" grep -oE '[[^]]+](feishu://file/[^)]+)' "$TMP_MD" 2>/dev/null | \ sed $'s/^\//;s/\$//' | \ while IFS=$'\t' read -r filename token; do [ -z "$filename" ] && continue # 处理文件名冲突 output_file="$OUTPUT_DIR/$filename" counter=1 while [ -e "$output_file" ]; do ext="${filename##.}" name="${filename%.}" if [ "$name" = "$filename" ]; then output_file="$OUTPUT_DIR/${filename} (${counter})" else output_file="$OUTPUT_DIR/${name} (${counter}).${ext}" fi ((counter++)) done feishu-cli media download "$token" -o "$output_file" done rm -f "$TMP_MD" 注意事项 附件 vs 图片：只下载文件块（block_type=23），不处理图片块 文件大小限制：单个文件最大 100MB 跨租户文件：如果附件来自其他租户，可能无法下载（403 错误） 临时文件：导出过程中会在 /tmp 创建临时 Markdown 文件 权限要求： docx:document（导出文档内容） drive:file:download（下载文件附件，必需） 或 drive:drive / drive:drive:readonly（云空间权限） 文件下载功能选择指南 根据你的需求选择合适的下载方式： 如果你需要... 使用模块 命令示例 下载云空间中的文件（PDF、Word 等） 7. 文件管理 file download -o output.pdf 上传/下载文档图片或附件 8. 素材管理 media download -o file.zip 批量下载文档中的所有附件 13. 文档附件下载 导出文档 → 解析 → media download 关键区别总结 云空间文件（File）： 存储在飞书云空间（Drive） 有独立的 file_token 通过 file list 获取，用 file download 下载 素材（Media）： 上传后用于插入文档/消息 通过 media upload 上传，返回 file_token 用 media download 下载 文档附件（Attachment）： 嵌入在文档内容中的文件块 需要先用 doc export 导出文档解析链接 提取 file_token 后用 media download 下载 通用注意事项 权限要求汇总 模块 权限 电子表格 sheets:spreadsheet 日历 calendar:calendar:readonly、calendar:calendar 任务 task:task:read、task:task:write、task:tasklist:read、task:tasklist:write 群聊 im:chat、im:chat:read、im:chat:member 画板 board:board 文件 drive:drive、drive:drive:readonly 素材 drive:drive、drive:drive:readonly 评论 drive:drive.comment:readonly、drive:drive.comment:write 知识库 wiki:wiki:readonly、wiki:wiki 搜索 需要 User Access Token 用户/部门 contact:user.base:readonly、contact:department.base:readonly 附件下载 docx:document、drive:file:download（或 drive:drive） 错误处理 错误 原因 解决 rate limit exceeded / 429 API 频率限制 等待几秒后重试 no permission 应用权限不足 检查应用权限配置 invalid parameter 参数格式错误 检查参数类型和格式 not found 资源不存在 检查 ID/Token 是否正确 已知问题（v1.7.0） 模块 问题 说明 文件 file version create BUG JSON 反序列化错误（status 字段类型不匹配），无法创建版本 文档 doc import-file 需要 --folder 不提供 --folder 时报 field validation failed（API 的 mount point 实际必填） 表格 sheet find/replace 需要 --range 不提供 --range 参数会报 field validation failed 表格 sheet protect API 限制 即使参数正确也可能返回 invalid operation 日历 freebusy --user-id 实际必填 帮助文档标记为可选，但不提供会报 invalid parameters 权限 perm password 需要企业版 创建/更新/删除分享密码可能返回 Permission denied Weekly Installs195Repositoryriba2534/feishu-cliGitHub Stars342First SeenFeb 28, 2026Security AuditsGen Agent Trust HubPassSocketPassSnykFailInstalled oncodex146kimi-cli143gemini-cli143github-copilot143cursor143opencode143