PaperclipOrg
Claude Agent Skill · by Riba2534

Feishu Cli Toolkit

Install Feishu Cli Toolkit skill for Claude Code from riba2534/feishu-cli.

Install
Terminal · npx
$npx skills add https://github.com/inferen-sh/skills --skill infsh-cli
Works with Paperclip

How Feishu Cli Toolkit fits into a Paperclip company.

Feishu Cli Toolkit drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.

S
SaaS FactoryPaired

Pre-configured AI company — 18 agents, 18 skills, one-time purchase.

$27$59
Explore pack
Source file
SKILL.md873 lines
Expand
---name: feishu-cli-toolkitdescription: >-  飞书综合工具箱，覆盖 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: trueallowed-tools: Bash, Read, Write--- # 飞书综合工具箱 覆盖 feishu-cli 的 14 个功能模块，提供命令速查和核心用法。复杂模块的详细参考文档在 `references/` 目录中。 > **feishu-cli**：如尚未安装，请前往 [riba2534/feishu-cli](https://github.com/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` || 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 5feishu-cli sheet add-cols <token> <sheet_id> --count 3feishu-cli sheet delete-rows <token> <sheet_id> --start 2 --end 5feishu-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` --- ## 2. 日历和日程 管理飞书日历、日程、参与人和忙闲查询。时间格式统一使用 RFC3339（如 `2024-01-01T10:00:00+08:00`）。 ### 常用命令 ```bash# 日历feishu-cli calendar list                    # 列出日历feishu-cli calendar get <calendar_id>       # 获取日历详情feishu-cli calendar primary                 # 获取主日历 # 日程 CRUDfeishu-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,id2feishu-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# 任务 CRUDfeishu-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/followerfeishu-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 listfeishu-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 jsonfeishu-cli approval get <approval_code> --output raw-json # 查询当前登录用户审批任务feishu-cli approval task query --topic todofeishu-cli approval task query --topic donefeishu-cli approval task query --topic started --output jsonfeishu-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 图、思维导图 ### 导入方式 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` | ### 常用命令 ```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.pdffeishu-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 docxfeishu-cli comment unresolve <file_token> <comment_id> --type docx # 回复管理feishu-cli comment reply list <file_token> <comment_id> --type docxfeishu-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. 知识库 查看知识空间、获取知识库节点、导出知识库文档、管理空间成员。 ### 常用命令 ```bash# 获取节点信息（支持 URL 或 token）feishu-cli wiki get <node_token> # 导出为 Markdownfeishu-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 adminfeishu-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. 搜索 > **推荐使用专项技能**：> - 搜索消息/群内搜索 → **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] # 通过邮箱/手机号查询用户 IDfeishu-cli user search --email user@example.comfeishu-cli user search --mobile 13800138000feishu-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` | **工作流程**：1. 导出文档为 Markdown → 2. 解析 `[filename](feishu://file/token)` 链接 → 3. 批量下载附件 ### 工作原理 1. **导出文档**：使用 `doc export` 或 `wiki export` 将文档转为 Markdown2. **解析附件**：从 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` | ### 使用步骤 ```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/bashINPUT="$1"                          # 文档 ID/URLOUTPUT_DIR="${2:-./attachments_$(echo "$INPUT" | tr '/' '_')}" # 提取文档 ID 或 Wiki TokenDOC_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 1fi # 导出并下载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 |