Skill v1.0.1

currentAutomated scan100/100

riba2534/feishu-cli/feishu-cli-toolkit

11 files

──Details

PublishedMay 14, 2026 at 08:56 PM

Content Hashsha256:701bccf094fc60f1...

Git SHA288473f03d1e

Bump Typepatch

Compare with v1.0.0

──Files

Files (1 file, 35.3 KB)

SKILL.md35.3 KBactive

SKILL.md · 962 lines · 35.3 KB

version: "1.0.1" name: feishu-cli-toolkit description: >- 飞书综合工具箱，覆盖 14 个模块：电子表格（含导出 XLSX/CSV）、日历日程（含 agenda）、任务管理（task/subtask/member/reminder）、任务清单、审批查询（我的任务/重新打开/评论）、画板操作、PlantUML 图表、文件管理、素材上传下载、文档评论、知识库、用户通讯录、文档附件下载。当用户请求操作飞书表格、查看日历/日程、创建或查询任务、查询审批任务、操作画板、生成 PlantUML、管理文件、上传素材、查看评论、查看知识库、查询用户或部门、下载文档附件时使用。边界分诊：群聊管理 → feishu-cli-chat；搜索文档/消息/应用 → feishu-cli-search；发消息/回复/转发 → feishu-cli-msg；构造 interactive 卡片 → feishu-cli-card；邮箱收发 → feishu-cli-mail；云盘增强（分块上传/markdown 快捷导出/ 异步 resume/富文本评论）→ feishu-cli-drive；多维表格 → feishu-cli-bitable；视频会议/妙记 → feishu-cli-vc；文档读/写/导入/导出 → feishu-cli-{read,write,import,export}；权限管理 → feishu-cli-perm；OAuth 登录/Token → feishu-cli-auth。 argument-hint: <module> <command> [args] user-invocable: true allowed-tools: Bash, Read, Write

飞书综合工具箱

覆盖 feishu-cli 的 14 个功能模块，提供命令速查和核心用法。复杂模块的详细参考文档在 references/ 目录中。

feishu-cli：如尚未安装，请前往 riba2534/feishu-cli 获取安装方式。

路由到其他 skill：
- 📧 邮箱（发/读/回复/转发/草稿/搜索）→ feishu-cli-mail
- 💾 云盘增强（分块上传/markdown 快捷导出/异步 resume/富文本评论/wiki 解析）→ feishu-cli-drive
（基础的 file list/delete/mkdir 等仍在本 toolkit 的"文件管理"段落）
- 📊 多维表格（base/v3 API，含视图写配置/upsert/history/角色 CRUD）→ feishu-cli-bitable
- 🎥 视频会议 / 妙记（三路径纪要/录制查询/媒体下载）→ feishu-cli-vc
- 💬 群聊管理 → feishu-cli-chat
- 🔍 搜索（文档/消息/应用）→ feishu-cli-search
- 📨 发送消息 → feishu-cli-msg
- 📄 创建/写入文档 → feishu-cli-write
- 📖 读取文档 → feishu-cli-read
- ⬇️ 导出文档 → feishu-cli-export
- ⬆️ Markdown 导入 → feishu-cli-import
- 🔒 权限管理 → feishu-cli-perm
- 🔑 OAuth 登录 / Token 管理 → feishu-cli-auth

模块速查表

#	模块	核心命令	详细参考
1	电子表格	`sheet create/get/read/write/append` + V3 富文本	`references/sheet-commands.md`
1.5	文档表格	`doc table insert-row/column/delete-rows/columns/merge-cells/unmerge-cells`	详见 `feishu-cli-write`
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/link`（App Token，群信息/成员/消息互动请用 feishu-cli-chat）	`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	审批	`approval get` + `approval task query`	—
12	搜索	请使用 feishu-cli-search（文档/应用）或 feishu-cli-chat（消息/群聊）	`references/search-commands.md`
13	用户和部门	`user info/search/list` + `dept get/children`	—
14	附件下载	`doc export` + `media download` 批量下载文档附件	—

1. 电子表格

支持 V2（简单二维数组）和 V3（富文本三维数组）两套 API。

常用命令

bash

# 创建表格
feishu-cli sheet create --title "新表格"
 
# 获取表格信息
feishu-cli sheet get <token>
 
# 列出工作表
feishu-cli sheet list-sheets <token>
 
# V2 读写（二维数组）
feishu-cli sheet read <token> "Sheet1!A1:C10"
feishu-cli sheet write <token> "Sheet1!A1:B2" --data '[["姓名","年龄"],["张三",25]]'
feishu-cli sheet append <token> "Sheet1!A:B" --data '[["新行1","新行2"]]'
 
# V3 富文本读写（三维数组）
feishu-cli sheet read-plain <token> <sheet_id> "Sheet1!A1:C10"
feishu-cli sheet read-rich <token> <sheet_id> "Sheet1!A1:C10"
feishu-cli sheet write-rich <token> <sheet_id> --data-file data.json
 
# 行列操作
feishu-cli sheet add-rows <token> <sheet_id> --count 5
feishu-cli sheet add-cols <token> <sheet_id> --count 3
feishu-cli sheet delete-rows <token> <sheet_id> --start 2 --end 5
feishu-cli sheet delete-cols <token> <sheet_id> --start 1 --end 3
 
# 样式和格式
feishu-cli sheet merge <token> "Sheet1!A1:B2"
feishu-cli sheet unmerge <token> "Sheet1!A1:B2"
feishu-cli sheet style <token> "Sheet1!A1:C3" --bold --bg-color "#FF0000"
 
# 查找替换（--range 必填，范围不要超出实际数据区域）
feishu-cli sheet find <token> <sheet_id> "关键词" --range "A1:C10"
feishu-cli sheet replace <token> <sheet_id> "查找词" "替换词" --range "A1:C10"

API 限制

单次写入最多 5000 个单元格，单元格最大 50000 字符
V2 范围格式：SheetID!A1:C10，支持整列 A:C 和整行 1:3
V3 写入限制：单次最多 10 个范围

导出为 XLSX/CSV

bash

# 导出为 XLSX（默认格式）
feishu-cli sheet export <spreadsheet_token> -o /tmp/report.xlsx
 
# 导出为 CSV（需指定工作表 ID）
feishu-cli sheet export <spreadsheet_token> -f csv --sheet-id <sheet_id> -o /tmp/data.csv
 
# 自定义轮询次数
feishu-cli sheet export <spreadsheet_token> -o /tmp/report.xlsx --max-retries 50

参数	说明	默认值
`<spreadsheet_token>`	电子表格 Token	必填
`-f, --format`	导出格式 `xlsx`/`csv`	`xlsx`
`--sheet-id`	工作表 ID（CSV 格式必填）	—
`-o, --output`	输出文件路径	—
`--max-retries`	最大轮询次数	30

注意：导出为 CSV 时必须指定 --sheet-id，因为 CSV 只能导出单个工作表。

User Access Token 支持

所有 30 个 sheet 命令均支持 --user-access-token 参数，用于以用户身份访问无 App 权限但用户有权限的表格。Token 读取优先级：--user-access-token 参数 > FEISHU_USER_ACCESS_TOKEN 环境变量 > ~/.feishu-cli/token.json > 配置文件。未指定时自动回退到 App Token（租户身份）。

详细参考：读取 references/sheet-commands.md 获取 V3 富文本格式、工作表管理、单元格图片等完整说明。

权限要求：sheets:spreadsheet

1.5. 文档表格（内嵌表格）

定义：文档内嵌表格（Block 类型 31），嵌入在飞书文档中的表格，与电子表格（Sheet）不同。

与电子表格的区别：

维度	文档表格（Table Block）	电子表格（Sheet）
位置	嵌入在文档中	独立的云文档
行列限制	最多 9 行 × 9 列（API 限制）	无限制
操作方式	`doc table` 命令	`sheet` 命令
合并单元格	支持	支持

常用命令

bash

# 插入行（-1 表示末尾）
feishu-cli doc table insert-row DOC_ID TABLE_BLOCK_ID --index -1
 
# 插入列
feishu-cli doc table insert-column DOC_ID TABLE_BLOCK_ID --index 2
 
# 删除行（左闭右开区间）
feishu-cli doc table delete-rows DOC_ID TABLE_BLOCK_ID --start 1 --end 3
 
# 删除列（左闭右开区间）
feishu-cli doc table delete-columns DOC_ID TABLE_BLOCK_ID --start 0 --end 2
 
# 合并单元格（左闭右开区间）
feishu-cli doc table merge-cells DOC_ID TABLE_BLOCK_ID \
  --row-start 0 --row-end 2 --col-start 0 --col-end 3
 
# 取消合并
feishu-cli doc table unmerge-cells DOC_ID TABLE_BLOCK_ID --row 0 --col 0

参数说明

命令	参数	说明
insert-row	`--index`	插入位置，-1 表示末尾
insert-column	`--index`	插入位置，-1 表示末尾
delete-rows	`--start`, `--end`	行范围（左闭右开）
delete-columns	`--start`, `--end`	列范围（左闭右开）
merge-cells	`--row-start/end`, `--col-start/end`	合并范围（左闭右开）
unmerge-cells	`--row`, `--col`	单元格位置

获取表格块 ID

bash

# 查看文档结构，找到 block_type=31 的表格块
feishu-cli doc blocks DOC_ID

权限要求：docx:document

2. 日历和日程

管理飞书日历、日程、参与人和忙闲查询。时间格式统一使用 RFC3339（如 2024-01-01T10:00:00+08:00）。

常用命令

bash

# 日历
feishu-cli calendar list                    # 列出日历
feishu-cli calendar get <calendar_id>       # 获取日历详情
feishu-cli calendar primary                 # 获取主日历
 
# 日程 CRUD
feishu-cli calendar create-event \
  --calendar-id <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 <RFC3339> --end-time <RFC3339>
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 <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>

日程列表（展开重复日程）

bash

# 查看今天的日程
feishu-cli calendar agenda [calendar_id]
 
# 指定日期范围
feishu-cli calendar agenda <calendar_id> \
  --start-date 2024-01-21 \
  --end-date 2024-01-28
 
# 分页
feishu-cli calendar agenda <calendar_id> --page-size 20 --page-token <token>

参数	说明	默认值
`[calendar_id]`	日历 ID	主日历
`--start-date`	起始日期 YYYY-MM-DD	今天
`--end-date`	结束日期 YYYY-MM-DD	start + 1 天
`--page-size`	每页数量	—
`--page-token`	分页标记	—

与 list-events 的区别：agenda 会展开重复日程为独立实例，适合查看某段时间内所有实际发生的日程。

详细参考：读取 references/calendar-commands.md 获取完整参数说明。

权限要求：calendar:calendar:readonly（读取），calendar:calendar（写操作，需单独申请）

3. 任务管理

管理飞书任务（V2 API），包括子任务、成员、提醒和任务清单。任务 ID 为 UUID 格式。

常用命令

bash

# 任务 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>
 
# 附件直传（一行命令，省去 drive upload + 手动关联两步）
feishu-cli task upload-attachment --task-guid <task_guid> --file ./report.pdf       # 默认 task
feishu-cli task upload-attachment --task-guid <task_guid> --file ./img.png --resource-type task_delivery
# 注意：单文件 ≤ 50MB；scope 需 task:attachment:write 或 task:attachment:upload
 
# 子任务
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>

我的任务

bash

# 查看我的所有任务（需 User Token）
feishu-cli task my
 
# 只显示未完成的任务
feishu-cli task my --uncompleted
 
# 只显示已完成的任务
feishu-cli task my --completed
 
# 指定每页数量
feishu-cli task my --page-size 20

参数	说明	默认值
`--completed`	只显示已完成	—
`--uncompleted`	只显示未完成	—
`--page-size`	每页数量	50

注意：task my 需要 User Token，请先通过 auth login 授权。

重新打开任务

bash

# 重新打开已完成的任务
feishu-cli task reopen <task_guid>

任务评论

bash

# 添加评论
feishu-cli task comment add <task_guid> --content "评论内容"
 
# 添加回复评论
feishu-cli task comment add <task_guid> --content "回复内容" --reply-to <comment_id>
 
# 列出任务评论
feishu-cli task comment list <task_guid>
 
# 分页列出
feishu-cli task comment list <task_guid> --page-size 20

参数	说明	默认值
`--content`	评论内容	必填
`--reply-to`	回复某评论 ID	—
`--page-size`	每页数量	—

任务清单：任务关联

bash

# 将任务添加到清单
feishu-cli tasklist task-add <tasklist_guid> --task-ids id1,id2,id3
 
# 从清单移除任务
feishu-cli tasklist task-remove <tasklist_guid> --task-ids id1,id2
 
# 列出清单中的任务
feishu-cli tasklist tasks <tasklist_guid>
 
# 只显示已完成的任务
feishu-cli tasklist tasks <tasklist_guid> --completed
 
# 指定每页数量
feishu-cli tasklist tasks <tasklist_guid> --page-size 20

参数	说明	默认值
`--task-ids`	任务 ID 列表（逗号分隔）	必填
`--completed`	只显示已完成	—
`--page-size`	每页数量	—

任务清单：成员管理

bash

# 添加清单成员
feishu-cli tasklist member add <tasklist_guid> --members id1,id2 --role editor
 
# 移除清单成员
feishu-cli tasklist member remove <tasklist_guid> --members id1,id2 --role editor

参数	说明	默认值
`--members`	成员 ID 列表（逗号分隔）	必填
`--role`	角色 `editor`/`viewer`	`editor`

详细参考：读取 references/task-commands.md 获取完整参数说明。

权限要求：task:task:read、task:task:write、task:tasklist:read、task:tasklist:write（需单独申请）

4. 群聊管理

推荐使用 feishu-cli-chat 技能，提供完整的群聊浏览、消息历史、成员管理等功能，且默认使用 User Token。

以下仅列出 App Token 专属命令（feishu-cli-chat 不覆盖的）：

bash

# 创建群聊（仅 App Token）
feishu-cli chat create --name "项目群" --user-ids id1,id2 [--chat-type private|public]
 
# 获取群分享链接（仅 App Token）
feishu-cli chat link <chat_id> [--validity-period week|year|permanently]

详细参考：读取 references/chat-commands.md 获取完整参数和示例。

5. 审批查询

查询审批定义详情（审批模板/流程定义），以及当前登录用户的审批待办、已办、已发起或抄送任务。approval get 和 approval task query 都支持 --output raw-json 查看飞书 API 原始响应；其中 approval task query 依赖 auth login 的当前登录态。

常用命令

bash

# 查询审批定义详情（审批模板/流程定义）
feishu-cli approval get <approval_code>
feishu-cli approval get <approval_code> --output json
feishu-cli approval get <approval_code> --output raw-json
 
# 查询当前登录用户审批任务
feishu-cli approval task query --topic todo
feishu-cli approval task query --topic done
feishu-cli approval task query --topic started --output json
feishu-cli approval task query --topic started --output raw-json

权限要求：approval:approval:readonly、approval:task

6. 画板操作

下载画板图片、导入 Mermaid/PlantUML 图表到画板。

常用命令

bash

# 下载画板为 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`

常用命令

bash

# 列出文件
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 <type> [--name "新名"]
feishu-cli file delete <file_token> --type <type>    # 移到回收站，30 天可恢复
 
# 下载/上传（≤20MB 单步上传，>20MB 自动分片上传）
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.metadata:readonly（读取元数据）、drive:drive（写操作）

8. 素材管理（Media）

定义：管理飞书素材系统中的临时文件，包括上传到文档/消息的图片和附件，以及下载已上传的素材。

适用场景：

上传图片或文件到飞书素材库（用于插入文档、发送消息）
下载已上传的素材（通过 file_token）
管理文档内嵌的图片和附件资源

与云空间文件/文档附件的区别：

维度	素材（Media）	云空间文件（File）	文档附件
用途	文档/消息插入	独立文件存储	文档内嵌附件
生命周期	依附于父资源	独立管理	随文档存在
Token 来源	上传返回 / 文档解析	云空间列表	导出文档解析
典型命令	`media upload/download`	`file list/download`	`doc export` + `media download`

常用命令

bash

# 上传素材（用于文档中的图片/附件）
feishu-cli media upload image.png \
  --parent-type docx_image \
  --parent-node <doc_id>
 
# 下载素材
feishu-cli media download <file_token> -o output.png
 
# 下载大文件，设置更长超时时间（默认 5m）
feishu-cli media download <file_token> -o output.png --timeout 10m

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:file:download（下载）、drive:file:upload（上传）

9. 评论管理

管理飞书云文档的评论，包括全文评论、评论解决/取消解决、回复管理。

常用命令

bash

# 列出评论
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
 
# 添加回复（推荐先 auth login，以用户身份发布）
feishu-cli comment reply add <file_token> <comment_id> --text "已处理" --type docx
 
feishu-cli comment reply delete <file_token> <comment_id> <reply_id> --type docx

User Token 提示：reply add 建议使用 User Token（登录态），以用户身份发出；
App/Bot 身份添加的回复只能被同一 App 自己删除，且经常收到 1069303 forbidden。
reply delete 同理——飞书 Open API 只允许回复作者本人删除。

支持的文件类型

--type 参数支持：docx、doc、sheet、bitable

权限要求：drive:drive.comment:readonly（读取）、drive:drive.comment:write（写入）

10. 知识库

查看知识空间、获取知识库节点、导出知识库文档、管理空间成员。

常用命令

bash

# 获取节点信息（支持 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 delete-space <space_id> --yes        # 高危且不可逆，必须加 --yes
# 同步完成时直接返回 ready=true；后端转异步时自动轮询 wiki/v2/tasks 直到 success/failure/超时
 
# 空间成员管理
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
 
# 将云空间文档迁入知识库（docx/doc/sheet/mindnote/bitable/file）
feishu-cli wiki move-docs <obj_token> --space-id <space_id> [--obj-type docx] \
  [--parent-node <node_token>] [--apply] [--user-access-token u-xxx]

重要概念

知识库使用 node_token（区别于普通文档的 document_id）
目录节点导出内容为 [Wiki 目录...]，需用 wiki nodes 获取子节点
成员角色：admin（管理员）、member（成员）
成员类型：openchat、userid、email、opendepartmentid、openid

move-docs 关键点

移动后文档从「我的空间 / 共享空间 / 快速访问」入口消失，权限默认继承父页面
大文档异步执行，返回 task_id 供查询；无权限且传 --apply 时会提交迁入申请
调用方须同时是源文档编辑者 + 目标空间成员（或父节点容器编辑者）
企业版知识空间不接受 app 作为成员——此时必须传 --user-access-token 走用户身份
--obj-type 默认 docx，挂载电子表格/多维表格需显式指定 sheet/bitable

权限要求：wiki:wiki:readonly（读取）、wiki:wiki（空间成员管理）、wiki:node:move 或 wiki:wiki（move-docs）

11. 搜索

推荐使用专项技能：
- 搜索消息/群内搜索 → feishu-cli-chat（含群聊浏览，auth login 后自动使用 User Token）
- 搜索文档/应用/跨模块搜索 → feishu-cli-search（含完整的 Token 前置检查和排错流程）

搜索参数详细参考：读取 references/search-commands.md 获取完整筛选参数说明。

12. 用户和部门

查询用户信息、通过邮箱/手机号查找用户、列出部门成员和子部门。

常用命令

bash

# 获取用户信息
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](feishu://file/token) 链接 → 3. 批量下载附件

工作原理

导出文档：使用 doc export 或 wiki export 将文档转为 Markdown
解析附件：从 Markdown 中提取 [filename](feishu://file/token) 格式的附件链接
批量下载：使用 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`

使用步骤

bash

# 步骤 1: 导出文档
feishu-cli doc export <document_id> -o /tmp/doc.md
 
# 步骤 2: 解析附件链接（用 tab 分隔文件名和 token，避免文件名含空格时出错）
grep -oE '\[[^]]+\]\(feishu://file/[^)]+\)' /tmp/doc.md | \
  sed $'s/^\\[//;s/\\](feishu:\\/\\/file\\//\t/;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

完整脚本示例

bash

#!/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/\\](feishu:\\/\\/file\\//\t/;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（完整云空间权限）

文件下载功能选择指南

根据你的需求选择合适的下载方式：

如果你需要...	使用模块	命令示例
下载云空间中的文件（PDF、Word 等）	7. 文件管理	`file download <token> -o output.pdf`
上传/下载文档图片或附件	8. 素材管理	`media download <token> -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.metadata:readonly`、`drive:file:download`、`drive:file:upload`
素材	`drive:drive`、`drive:file:download`、`drive:file:upload`
评论	`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

← v1.0.0 All versions