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/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 | 搜索 | 请使用 feishu-cli-search（文档/应用）或 feishu-cli-chat（消息/群聊） | 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   "Sheet1!A1:C10"
feishu-cli sheet read-rich   "Sheet1!A1:C10"
feishu-cli sheet write-rich   --data-file data.json

# 行列操作
feishu-cli sheet add-rows   --count 5
feishu-cli sheet add-cols   --count 3
feishu-cli sheet delete-rows   --start 2 --end 5
feishu-cli sheet delete-cols   --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   "关键词" --range "A1:C10"
feishu-cli sheet replace   "查找词" "替换词" --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        # 获取日历详情
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  --start-time  --end-time 
feishu-cli calendar get-event  
feishu-cli calendar update-event   --summary "新标题"
feishu-cli calendar delete-event  

# 搜索日程
feishu-cli calendar event-search --calendar-id  --query "周会"

# 回复日程邀请
feishu-cli calendar event-reply   --status accept   # accept/decline/tentative

# 参与人管理
feishu-cli calendar attendee add   --user-ids id1,id2
feishu-cli calendar attendee list  

# 忙闲查询
feishu-cli calendar freebusy \
  --start "2024-01-01T00:00:00+08:00" \
  --end "2024-01-02T00:00:00+08:00" \
  --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 
feishu-cli task update  --summary "新标题"
feishu-cli task complete 
feishu-cli task delete 

# 子任务
feishu-cli task subtask create  --summary "子任务标题"
feishu-cli task subtask list 

# 成员管理
feishu-cli task member add  --members id1,id2 --role assignee    # assignee/follower
feishu-cli task member remove  --members id1,id2 --role assignee

# 提醒
feishu-cli task reminder add  --minutes 30     # 提前 30 分钟提醒，0=截止时
feishu-cli task reminder remove  --ids id1,id2

# 任务清单
feishu-cli tasklist create --name "Sprint 计划"
feishu-cli tasklist list
feishu-cli tasklist get 
feishu-cli tasklist delete 

详细参考：读取 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 不覆盖的）：

# 创建群聊（仅 App Token）
feishu-cli chat create --name "项目群" --user-ids id1,id2 [--chat-type private|public]

# 获取群分享链接（仅 App Token）
feishu-cli chat link  [--validity-period week|year|permanently]

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

---

5. 画板操作

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

常用命令

# 下载画板为 PNG 图片
feishu-cli board image  output.png

# 导入图表到画板
feishu-cli board import  diagram.puml                              # PlantUML 文件
feishu-cli board import  diagram.mmd --syntax mermaid              # Mermaid 文件
feishu-cli board import  --source-type content -c "graph TD; A-->B" --syntax mermaid  # 内容直接导入

# 获取画板节点列表
feishu-cli board nodes 

# 在文档中添加空白画板
feishu-cli doc add-board  [--parent-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 图、思维导图

导入方式

1. 在 Markdown 中使用 `plantuml 代码块，通过 feishu-cli doc import 导入
2. 直接通过 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 ]

# 移动/复制/删除
feishu-cli file move  --target  --type 
feishu-cli file copy  --target  --type  [--name "新名"]
feishu-cli file delete  --type     # 移到回收站，30 天可恢复

# 下载/上传（≤20MB 单步上传，>20MB 自动分片上传）
feishu-cli file download  -o output.pdf
feishu-cli file upload local_file.pdf --parent  [--name "自定义名"]

# 版本管理
feishu-cli file version list  [--obj-type docx]
feishu-cli file version create  --name "v1.0" [--obj-type docx]
feishu-cli file version get  
feishu-cli file version delete  

# 元数据和统计
feishu-cli file meta TOKEN1 TOKEN2 --doc-type docx       # 批量获取元数据
feishu-cli file stats  --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 

# 下载素材
feishu-cli media download  -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  --type docx

# 添加全文评论
feishu-cli comment add  --type docx --text "评论内容"

# 删除评论（不可逆）
feishu-cli comment delete   --type docx

# 解决/取消解决评论
feishu-cli comment resolve   --type docx
feishu-cli comment unresolve   --type docx

# 回复管理
feishu-cli comment reply list   --type docx
feishu-cli comment reply delete    --type docx

支持的文件类型

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

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

---

10. 知识库

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

常用命令

# 获取节点信息（支持 URL 或 token）
feishu-cli wiki get 

# 导出为 Markdown
feishu-cli wiki export  -o doc.md [--download-images --assets-dir ./assets]

# 列出知识空间
feishu-cli wiki spaces [--page-size 20]

# 列出空间下的节点
feishu-cli wiki nodes  [--parent ]

# 获取空间详情
feishu-cli wiki space-get 

# 空间成员管理
feishu-cli wiki member add  --member-type userid --member-id  --role admin
feishu-cli wiki member list 
feishu-cli wiki member remove  --member-type userid --member-id  --role admin

重要概念

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

权限要求：wiki:wiki:readonly（读取）、wiki:wiki（空间成员管理）

---

11. 搜索

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

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

---

12. 用户和部门

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

常用命令

# 获取用户信息
feishu-cli user info  [--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  [--user-id-type open_id]

# 获取部门详情
feishu-cli dept get  [--department-id-type open_department_id]

# 获取子部门列表（根部门使用 "0"）
feishu-cli dept children  [--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 |

工作流程：

1. 导出文档为 Markdown → 2. 解析 [filename](feishu://file/token) 链接 → 3. 批量下载附件

工作原理

1. 导出文档：使用 doc export 或 wiki export 将文档转为 Markdown
2. 解析附件：从 Markdown 中提取 [filename](feishu://file/token) 格式的附件链接
3. 批量下载：使用 media download 下载每个附件
4. 冲突处理：自动为同名文件添加序号后缀（如 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  -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_

# 步骤 4: 批量下载
while IFS=$'\t' read -r filename token; do
  feishu-cli media download "$token" -o "./attachments_/$filename"
done /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 / 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 | 参数格式错误 | 检查参数类型

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ejjcc
• Source: ejjcc/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.