{ "markdown": "

\n \"feishu-cli\n

\n\n

feishu-cli

\n\n

\n 飞书开放平台命令行工具 — Markdown 与飞书文档双向转换，AI Agent 的飞书操控引擎\n

\n\n

\n \"Release\"\n \"Go\"\n \"Downloads\"\n \"Go\n \"Stars\"\n \"License\"\n

\n\n

\n 介绍 · 30 秒上手 · 核心能力 · 快速开始 · 命令参考 · AI 技能 · FAQ · 更新日志\n

\n\n

\n \"feishu-cli\n

\n\n---\n\n## feishu-cli 是什么\n\nfeishu-cli 是一个功能完整的飞书开放平台命令行工具。它将飞书文档、知识库、电子表格、消息、日历、任务等操作封装为简洁的命令行接口，**核心能力是 Markdown ↔ 飞书文档双向无损转换**。\n\n除了传统的 CLI 用法，feishu-cli 还为 [Claude Code](https://claude.ai/claude-code) 等 AI 编程助手提供了 **9 个开箱即用的领域技能（Skill）**，让 AI Agent 能够直接创建文档、发送消息、管理权限——无需任何额外配置。\n\n> **注意**：feishu-cli 主要面向 AI Agent（如 Claude Code）使用，通过技能文件让 AI 直接操控飞书。虽然人类也可以直接使用命令行，但大多数场景下建议通过 AI Agent 调用，体验更佳。\n\n### 为什么选择 feishu-cli\n\n- **双向转换零损耗** — 支持 40+ 种块类型，Markdown 导入飞书后再导出，内容完整保留\n- **图表原生渲染** — Mermaid（8 种图表类型）和 PlantUML 自动转换为飞书画板，不是截图，是可编辑的矢量图\n- **大规模文档处理** — 三阶段并发管道架构，实测 10,000+ 行 / 127 个图表 / 170+ 个表格一次导入\n- **P2P 私聊原生可读** — `msg history --user-email` 一条命令打通「搜用户 → 反查 p2p chat_id → 读消息」，输出自动带 `sender_names` 映射，AI Agent 直接拿结构化带名消息流，无需额外查群成员\n- **AI Agent 原生** — 9 个领域技能覆盖飞书全功能（503 个命令全部归属），AI 助手即装即用\n- **为脚本与 Agent 设计的健壮性** — 错拼命令/flag 报错并给拼写建议（绝不静默成功）、写操作 `--dry-run`、幂等键防重发、统一 `--jq`/`--format` 结构化输出\n- **一个工具覆盖全平台** — 文档、知识库、表格、多维表格、消息、邮箱、日历、任务、考勤、OKR、视频会议、妙记、云盘、权限、画板、Slides、事件、Schema、Profile、健康检查\n\n## 三十秒上手\n\n```bash\n# 1. 安装（自动识别平台，含 sha256 完整性校验）\ncurl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash\n\n# 2. 一键创建飞书应用并保存凭证（Device Flow，免手工建应用）\nfeishu-cli config create-app --save\n\n# 3. 把 Markdown 变成飞书文档\nfeishu-cli doc import README.md --title \"我的第一篇文档\"\n```\n\n需要用户身份的能力（搜索、审批、邮箱等）再执行 `feishu-cli auth login` 完成 OAuth 授权即可。详见[快速开始](#快速开始)。\n\n## 核心能力\n\n### Markdown ↔ 飞书文档\n\n将本地 Markdown 文件一键上传到飞书，或将飞书文档导出为 Markdown。支持完整语法转换：\n\n```bash\n# 导入：Markdown → 飞书文档\nfeishu-cli doc import report.md --title \"技术报告\" --verbose\n\n# 导出：飞书文档 → Markdown\nfeishu-cli doc export -o doc.md --download-images\n```\n\n**支持的语法**：标题（6 级）、段落、列表（无限深度嵌套）、任务列表、代码块、引用、Callout（6 种类型）、同步块（含跨文档引用）、表格（自动拆分）、分割线、图片、链接、公式、粗体 / 斜体 / 删除线 / 下划线 / 行内代码 / 高亮。跨文档同步块无法读取时会保留带源标识的 WARNING 占位并输出诊断，不会静默导出为空。\n\n### Mermaid / PlantUML 图表\n\nMarkdown 中的 Mermaid 和 PlantUML 代码块**自动转换为飞书画板**（可编辑矢量图，非截图）：\n\n````markdown\n```mermaid\nflowchart TD\n A[开始] --> B{判断}\n B -->|是| C[处理]\n B -->|否| D[结束]\n```\n````\n\n| 图表类型 | 声明 | 说明 |\n|---------|------|------|\n| 流程图 | `flowchart TD` / `flowchart LR` | 支持 subgraph |\n| 时序图 | `sequenceDiagram` | 参与者建议 ≤ 8 |\n| 类图 | `classDiagram` | |\n| 状态图 | `stateDiagram-v2` | 必须用 v2 |\n| ER 图 | `erDiagram` | |\n| 甘特图 | `gantt` | |\n| 饼图 | `pie` | |\n| 思维导图 | `mindmap` | |\n\nPlantUML 同样支持：时序图、活动图、类图、用例图、组件图、ER 图、思维导图等全部类型（` ```plantuml ` 或 ` ```puml `）。\n\n> 大规模实测导入成功率 **>90%**，失败图表自动降级为代码块并保留原文，不阻断整篇导入。\n\n### 智能表格处理\n\n- **列宽自动计算** — 根据内容智能调整，中英文字符区分宽度（中文 14px，英文 8px）\n- **列宽自定义**（v1.29+，issue #156）— 支持紧邻表格上方注释 ``（单位 px / 百分比 / `*` 走 auto）或 CLI flag `--table-column-width=auto|fixed|N1,N2,...` 全局覆盖；注释优先级高于 flag。**仅 `doc import` / `doc add` 支持**——`doc content-update` 走官方原子更新协议不支持自定义列宽，传非 `auto` 的 flag 或内容含该注释都会报错\n- **大表格保持单表连贯** — 行数超过飞书 `create_block` 9 行限制时，先创建 9 行初始表，剩余行通过 `insert_table_row` API 追加到同一个 block，视觉上为一张连贯的表，不再拆成多张独立表格\n- **批量填充加速**（v1.29+，issue #159）— 单元格填充改用 `batch_update` API（每批 ≤30）+ 文档级 3 QPS 节流，典型 4×6×8 表场景从 ~70s 降到 ~3s\n- **单元格多块内容** — 支持 bullet / heading / text 混合内容\n\n### 三阶段并发管道\n\n导入大文档时，feishu-cli 使用三阶段并发管道最大化吞吐量：\n\n1. **阶段一（顺序）** — 按文档顺序创建所有块，收集图表和表格任务\n2. **阶段二（并发）** — 图表 worker 池 + 表格 worker 池并发处理\n3. **阶段三（逆序）** — 处理失败图表，降级为代码块\n\n```bash\nfeishu-cli doc import large-doc.md --title \"大文档\" \\\n --upload-images --diagram-workers 5 --table-workers 3 --image-workers 2 --verbose\n```\n\n### 全功能 API 覆盖\n\n
\n展开 20+ 模块能力总览表\n\n| 模块 | 能力 |\n|------|------|\n| **文档** | 创建、导入、导出、**大文档选择性读取（doc read：大纲/按标题取节/关键词定位）**、编辑、批量更新、Callout、画板、异步导出/导入文件 |\n| **知识库** | 空间列表、节点增删改查、导出（含整树递归镜像）、**移出知识库到云盘（move-to-drive）**、空间详情、成员管理 |\n| **电子表格** | V2 基础读写 + V3 富文本 API，行列操作、样式、批量样式、合并、查找替换、导出 XLSX/CSV、浮动图片读写、素材上传、单元格写图、筛选视图与筛选条件 CRUD、下拉菜单数据验证、**类型保真整表读写 table-get/table-put（数字/日期/布尔 dtype 保真，支持 get→改→put round-trip）** |\n| **多维表格** | base/v3 + bitable/v1 全覆盖：数据表/字段/记录 CRUD（含批量获取）、记录附件上传/下载/移除、视图配置（filter/sort/group/visible-fields/timebar/card）、仪表盘 CRUD 与智能排版、仪表盘块 CRUD、表单 CRUD 与分享详情/提交、表单问题 CRUD、角色 CRUD 与协作者管理、高级权限、数据聚合、工作流 CRUD、多维表格重命名与权限设置 |\n| **消息** | 发送与回复共用 text/Markdown/post/image/file/audio/video/card 内容模型（本地媒体自动上传、幂等键）、转发、合并转发、Pin、表情回复、消息书签（flag create/list/cancel）、搜索群聊（Bot/User 双身份）、历史记录（群聊 / P2P 私聊，支持 `--user-email` / `--user-id` 自动反查 p2p chat_id）、批量获取、资源下载、话题回复、**发送者名字自动解析**（输出顶层 `sender_names` 映射，覆盖退群成员） |\n| **群聊** | 创建、获取、更新、删除、分享链接、成员管理、**群列表（chat list，--page-all 全量拉取 + 安全截断告警）** |\n| **邮箱** | 收件箱分类/搜索、邮件详情（单条/批量/线程）、发送（默认草稿，支持 CID 内联图片自动扫描）、草稿管理（创建/编辑/**发送已有草稿**）、回复/全部回复/转发、**批量改 label/移动文件夹、批量软删进废纸篓**、邮件模板 create/list、邮箱签名查看（需 User Token） |\n| **日历** | 日历列表、主日历、日程增删改查、搜索、回复邀请、参与者管理、忙闲查询、日程视图（agenda）、智能时段建议、会议室查找、RSVP |\n| **任务** | 创建、查看、完成、重新打开、**服务端搜索（按创建者/执行者/关注者/完成态/截止时间）**、子任务、成员管理、提醒、评论、附件上传、我的任务、任务清单（CRUD + 任务关联 + 成员管理） |\n| **视频会议** | 多维搜索（query/主持人/参会者/会议室）、**聚合详情（vc detail：会议信息 + note_id + minute_token 一次拿齐，支持会议号反查）**、**智能纪要（vc note：详情 / 统一逐字稿导出）**、会议纪要（三路径批量获取 + AI 产物 + 逐字稿下载）、录制查询、会议机器人入会/离会/会议事件（`--as bot\\|user\\|auto`） |\n| **妙记** | 详情 + AI 产物、**关键词搜索、权限申请、等待转写就绪（--wait-ready）**、媒体批量下载 |\n| **审批** | 审批定义与实例详情查询、当前登录用户审批任务查询（待办 / 已办 / 已发起 / 抄送）、发起/撤回/抄送审批实例、通过/拒绝/转交审批任务 |\n| **考勤** | 查询用户打卡记录与日/月度考勤统计（tenant token，日期范围最长 31 天） |\n| **OKR** | 周期列表/**详情（目标 + 关键结果）**、进展记录 **CRUD**、**进展图片上传**、`--as bot|user|auto` 身份切换 |\n| **权限** | 添加 / 更新 / 删除协作者、批量添加、公开权限管理、分享密码、权限检查、转移所有权 |\n| **云盘增强** | 大文件分块上传（>20MB 自动分片）、**原地覆盖上传（--file-token）**、流式下载、异步导出（docx→markdown 快捷路径 + sheet/bitable CSV）、异步导入、文件夹移动（自动轮询）、富文本评论（wiki URL 解析）、异步任务查询、URL 解析 inspect、权限申请、本地镜像 pull/push/status、v2 搜索、**密级标签查询/设置** |\n| **原生 Markdown 文件** | Drive `.md` 文件 create/fetch/overwrite，整体保留 Markdown 源码，不转换为飞书 docx 块；本地比对远端最新与历史版本 |\n| **文件** | 云空间文件列表、创建、移动、复制、删除、上传、下载、版本管理（**含回滚到历史版本**）、元数据、统计 |\n| **素材** | 上传 / 下载（图片、文件、音视频） |\n| **画板** | 精排绘图（create-notes）、Mermaid / PlantUML 导入、**克隆（connector 重映射）、几何质检 lint、SVG 双向（svg-import / svg-export / export-code）、图片上传、覆盖更新（含快照）**、截图下载、节点管理 |\n| **Slides** | 创建空白演示文稿、上传媒体到演示文稿 |\n| **评论** | 列出、添加、解决/恢复评论、回复管理 |\n| **搜索** | 消息搜索（默认返回消息 ID，`--enrich` 补全内容/发送者/群名/时间）、应用搜索、文档搜索（需 User Access Token） |\n| **用户** | 获取用户信息、用户搜索、部门用户列表 |\n| **通讯录** | 部门详情、子部门列表 |\n| **实时事件** | WebSocket 长连接订阅应用事件（EventKey 列表/schema/consume/status/stop），**卡片按钮/表单回调（card.action.trigger）**、**审批 v4 事件（自动注册服务端订阅）**、**VC participant/note/recording 事件（User pre-consume，握手后 ready）**、Bot 菜单事件 |\n| **Raw API** | `api GET/POST/PUT/DELETE/PATCH ` 裸调任意未封装的 OpenAPI 接口，自动鉴权与错误码处理，支持 dry-run、自定义超时、jq 过滤与 json/pretty/table/ndjson/csv 多格式输出 |\n| **OpenAPI Schema** | 本地查询内置 OpenAPI service/resource/method、路径、参数和 scope，无需 token |\n| **Profile 多配置** | 多 App / 多账号配置 add/list/use/current/rename/remove/migrate；`profile list --json` 列出可操作 Bot；全局 `--profile` / `FEISHU_PROFILE` 单次切换目录与 User Token（`FEISHU_APP_ID/SECRET` 仍可覆盖 App 凭证） |\n| **健康检查** | `doctor` 一次检查配置、User Token、端点、代理和本地依赖 |\n\n
\n\n## 快速开始\n\n### 安装\n\n**一键安装（推荐）**\n\n自动检测平台，下载最新版本并安装到 `/usr/local/bin`：\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash\n```\n\n已安装的用户执行同样的命令即可更新到最新版本。\n\n
\n其他安装方式\n\n**手动下载**\n\n从 [Releases](https://github.com/riba2534/feishu-cli/releases/latest) 页面下载对应平台的压缩包：\n\n| 平台 | 文件 |\n|------|------|\n| Linux x64 | `feishu-cli_*_linux-amd64.tar.gz` |\n| Linux ARM64 | `feishu-cli_*_linux-arm64.tar.gz` |\n| macOS Intel | `feishu-cli_*_darwin-amd64.tar.gz` |\n| macOS Apple Silicon | `feishu-cli_*_darwin-arm64.tar.gz` |\n| Windows x64 | `feishu-cli_*_windows-amd64.tar.gz` |\n\n```bash\ntar -xzf feishu-cli_*_linux-amd64.tar.gz\nsudo mv feishu-cli_*/feishu-cli /usr/local/bin/\n```\n\n**使用 go install**\n\n```bash\ngo install github.com/riba2534/feishu-cli@latest\n```\n\n**从源码编译**\n\n```bash\ngit clone https://github.com/riba2534/feishu-cli.git\ncd feishu-cli && make build\n# 二进制文件输出到 bin/feishu-cli\n```\n\n
\n\n### 配置凭证\n\n**一键创建应用（推荐）**\n\n无需手动访问飞书开放平台后台，一条命令自动完成应用注册：\n\n```bash\n# 自动创建飞书应用并保存凭证到 ~/.feishu-cli/config.yaml\nfeishu-cli config create-app --save\n```\n\n执行后终端会输出一个授权链接，用飞书扫码确认即可。CLI 自动获取 App ID 和 App Secret 并写入配置文件，后续命令直接可用。\n\n然后在飞书开放平台的**应用权限管理**页面为新创建的应用开通所需 scope。最快的方式是复制 [权限要求](#权限要求) 章节的 JSON，在权限管理页面的 **导入权限** 入口粘贴即可一次性申请全部。\n\n
\n手动配置（不推荐）\n\n如果你有特殊需求（如企业应用、自定义应用类型），也可以手动配置：\n\n1. 在 [飞书开放平台](https://open.feishu.cn/app) 创建应用，获取 App ID 和 App Secret\n2. 给应用添加所需权限（参见[权限要求](#权限要求)）\n3. 配置凭证（二选一）：\n\n```bash\n# 方式一：环境变量\nexport FEISHU_APP_ID=\"cli_xxx\"\nexport FEISHU_APP_SECRET=\"xxx\"\n\n# 方式二：配置文件\nfeishu-cli config init # 生成模板后手动编辑填入凭证\n```\n\n
\n\n（可选）如果需要使用搜索、审批任务查询等需要用户身份的功能，还需完成 OAuth 用户授权：\n\n```bash\nfeishu-cli auth login\n```\n\n### 验证安装\n\n```bash\nfeishu-cli doc create --title \"Hello Feishu\"\n```\n\n如果返回文档 ID，说明配置成功。\n\n## 命令参考\n\n```\nfeishu-cli [subcommand] [flags]\n\nCommands:\n doc 文档操作（创建、导入、导出、编辑、异步导出/导入文件）\n wiki 知识库操作（节点增删改查、空间详情、成员管理）\n sheet 电子表格（读写、样式、batch-set-style、V3 富文本 API、导出 XLSX/CSV、image、filter-view + condition、dropdown）\n bitable 多维表格（base/v3 + bitable/v1：数据表/字段/记录/附件/视图/仪表盘/表单/角色/权限/聚合/工作流，88 命令）\n msg 消息操作（发送、转发、合并转发、回复、Pin、表情回复、书签、批量获取、资源下载）\n chat 群聊管理（创建、更新、删除、群列表、成员管理）\n mail 邮箱操作（分类/搜索、发送、草稿含发送、回复、转发、批量改 label/软删、CID 内联图片、模板、签名）\n drive 云盘增强（分块/覆盖上传、流式下载、异步导出/导入、移动、评论、镜像 pull/push、密级标签，15 命令）\n markdown Drive 原生 Markdown 文件 CRUD（.md 整体读写、版本比对，不转换 docx 块）\n vc 视频会议（多维搜索、聚合详情、智能纪要 note、会议纪要、录制查询、机器人入会/离会/事件）\n minutes 妙记操作（详情 + AI 产物、搜索、权限申请、媒体批量下载）\n apps 妙搭（Miaoda）应用（创建、发布 HTML、修改、访问范围管理）\n file 文件管理（列出、移动、复制、删除、上传、下载、版本管理）\n media 素材操作（上传、下载）\n perm 权限管理（添加、删除、批量添加、公开权限、密码、转移所有权）\n calendar 日历操作（日程增删改查、搜索、参与者、忙闲查询、agenda、suggestion、room-find、rsvp）\n task 任务操作（增删改查、服务端搜索、子任务、成员、提醒、评论、附件、我的任务）\n tasklist 任务清单管理（CRUD、任务关联、成员管理）\n attendance 考勤操作（打卡记录查询、统计数据查询）\n okr OKR 操作（周期列表/详情、进展记录 CRUD、进展图片上传、--as 身份）\n slides Slides 演示文稿（创建、媒体上传）\n user 用户操作（获取信息、搜索、部门用户列表）\n dept 部门操作（详情、子部门列表）\n board 画板操作（精排绘图、图表导入、克隆、几何质检 lint、SVG 双向、图片上传、覆盖更新）\n comment 评论操作（列出、添加、解决/恢复、回复管理）\n approval 审批操作（定义/实例详情、已发起列表、任务查询、实例创建/撤回/抄送、任务通过/拒绝/转交；全部 User Token）\n search 搜索操作（消息、应用、文档）\n event 实时事件订阅（WebSocket 长连接、list/schema/consume/status/stop）\n schema 本地浏览飞书 OpenAPI 方法（无需 token）\n api 通用 OpenAPI 透传调用（任意 method/path，自动鉴权 + 错误码翻译，覆盖 2500+ 端点）\n profile 多 App / 多账号配置切换\n doctor 环境健康检查（config/user_token/endpoints/proxy/deps）\n auth 身份认证（OAuth 登录、状态、退出、scope 预检）\n config 配置管理\n```\n\n
\n文档操作\n\n```bash\n# 创建文档\nfeishu-cli doc create --title \"新文档\"\n\n# 导入 Markdown（核心功能，默认上传图片）\nfeishu-cli doc import doc.md --title \"文档标题\" --upload-images --verbose\n\n# 导出为 Markdown\nfeishu-cli doc export -o output.md --download-images\n# 大文档选择性读取（大纲 / 按标题取节 / 关键词定位）\nfeishu-cli doc read --outline\nfeishu-cli doc read --heading \"性能优化\"\nfeishu-cli doc read --keyword \"QPS|限流\" --context 5\n# 导出他人文档（自动从 auth login 读取 User Token，或手动指定）\nfeishu-cli doc export -o output.md --user-access-token \n\n# 获取文档信息\nfeishu-cli doc get \n\n# 获取所有块\nfeishu-cli doc blocks --all\n\n# 添加内容（JSON 格式）\nfeishu-cli doc add -c ''\n\n# 添加内容（Markdown 格式）\nfeishu-cli doc add README.md --content-type markdown\n\n# 添加高亮块\nfeishu-cli doc add-callout \"提示内容\" --callout-type info\n\n# 批量更新\nfeishu-cli doc batch-update '[...]' --source-type content\n\n# 异步导出为文件（PDF/DOCX/XLSX）\nfeishu-cli doc export-file --type pdf -o output.pdf\n\n# 异步导入本地文件为飞书文档\nfeishu-cli doc import-file local_file.docx --type docx --name \"文档名\"\n```\n\n
\n\n
\n知识库操作\n\n```bash\nfeishu-cli wiki spaces # 列出知识空间\nfeishu-cli wiki get # 获取节点\nfeishu-cli wiki nodes # 列出节点\nfeishu-cli wiki export -o doc.md # 导出为 Markdown\nfeishu-cli wiki export-tree -o ./backup # 递归导出知识库子树\nfeishu-cli wiki create --space-id --title \"新节点\"\nfeishu-cli wiki create --space-id --title \"快捷方式\" --node-type shortcut --origin-node-token \nfeishu-cli wiki delete # 删除节点（官方 API，支持异步任务自动轮询）\nfeishu-cli wiki move-docs --space-id # 移动云空间文档至知识空间\nfeishu-cli wiki move-to-drive --node-token wikcnXXX --folder-token fldcnYYY # 反向：移出知识库到云盘\nfeishu-cli wiki space-get # 获取知识空间详情\nfeishu-cli wiki space-create --name \"新知识库\" # 创建知识库（v1.29+）\nfeishu-cli wiki space-list --page-all -o json # 列出所有可见知识库（v1.29+）\nfeishu-cli wiki node-copy --space-id --node-token --target-space-id # 复制节点（v1.29+）\nfeishu-cli wiki delete-space --yes # 删除整个知识空间（异步任务自动轮询）\n\n# 知识空间成员管理\nfeishu-cli wiki member add --member-type userid --member-id USER_ID --role admin\nfeishu-cli wiki member list \nfeishu-cli wiki member remove --member-type userid --member-id USER_ID --role admin\n```\n\n
\n\n
\n电子表格操作\n\n```bash\n# V2 API - 基础读写\nfeishu-cli sheet read \"Sheet1!A1:C10\"\nfeishu-cli sheet write \"Sheet1!A1:B2\" --data '[[\"姓名\",\"年龄\"],[\"张三\",25]]'\n\n# V3 API - 富文本支持\nfeishu-cli sheet read-rich \"sheet!A1:C10\"\n# 类型保真整表读写（DataFrame 形状，数字/日期/布尔 dtype 保真，支持 get→改→put round-trip）\nfeishu-cli sheet table-get [--range A1:D50]\nfeishu-cli sheet table-put --sheets-file table.json\nfeishu-cli sheet write-rich --data-file data.json\n\n# 行列操作\nfeishu-cli sheet add-rows --count 5\nfeishu-cli sheet add-cols --count 3\n\n# 样式与合并\nfeishu-cli sheet style \"Sheet1!A1:C3\" --bold --font-size 14\nfeishu-cli sheet merge \"Sheet1!A1:C1\"\n```\n\n
\n\n
\n消息操作\n\n```bash\n# 发送文本消息\nfeishu-cli msg send --receive-id-type email --receive-id user@example.com --text \"Hello\"\nfeishu-cli msg send --receive-id-type email --receive-id user@example.com --text \"对账\" --idempotency-key \"bill-001\" # 幂等防重发（≤50 字符）\n\n# 发送富文本消息\nfeishu-cli msg send --receive-id-type email --receive-id user@example.com \\\n --msg-type post --content-file msg.json\n\n# 搜索群聊（Bot 身份，仅返回 Bot 所在的群）\nfeishu-cli msg search-chats --query \"关键词\"\n\n# 搜索群聊（User 身份，可搜到用户所在的群）\nfeishu-cli msg search-chats --query \"关键词\" --user-access-token \n\n# 获取群聊历史消息（已 auth login 时自动用 User Token；未登录回落 Bot Token，要求 Bot 在群里）\nfeishu-cli msg history --container-id --container-id-type chat\n\n# 获取和某人的私聊记录（邮箱入口，自动搜用户 + 反查 p2p chat_id）\nfeishu-cli msg history --user-email user@example.com --page-size 50 -o json\n\n# 已知 open_id 时直接传\nfeishu-cli msg history --user-id ou_xxx --page-size 50 -o json\n\n# 输出 JSON 自动携带顶层 sender_names 映射（open_id → 姓名），AI Agent 可直接引用\n# {\"items\":[...], \"sender_names\":{\"ou_abc\":\"张三\",\"ou_def\":\"李四\"}}\n\n# 转发消息\nfeishu-cli msg forward --receive-id --receive-id-type email\n\n# 回复消息\nfeishu-cli msg reply --text \"回复内容\"\nfeishu-cli msg reply --image /path/to/photo.png --idempotency-key \"photo-reply-001\"\n\n# 回复到既有话题：传话题内 om_xxx 消息 ID，不要把 omt_xxx 传给 msg send\nfeishu-cli msg reply om_xxx --file /path/to/report.pdf\n\n# 合并转发\nfeishu-cli msg merge-forward --receive-id user@example.com --receive-id-type email --message-ids id1,id2\n\n# 消息加急\nfeishu-cli msg urgent --user-id-type open_id --user-ids ou_xxx,ou_yyy\nfeishu-cli msg urgent --urgent-type phone --user-id-type user_id --user-ids u_123,u_456\nfeishu-cli msg urgent --urgent-type sms --user-id-type union_id --user-ids on_xxx,on_yyy\n\n# 表情回复\nfeishu-cli msg reaction add --emoji-type THUMBSUP\nfeishu-cli msg reaction remove --reaction-id REACTION_ID\nfeishu-cli msg reaction list \n\n# Pin 消息\nfeishu-cli msg pin \nfeishu-cli msg unpin \nfeishu-cli msg pins --chat-id CHAT_ID\n```\n\n
\n\n
\n权限管理\n\n```bash\n# 添加 / 更新协作者\nfeishu-cli perm add --doc-type docx --member-type email \\\n --member-id user@example.com --perm full_access --notification\nfeishu-cli perm update --doc-type docx --member-type email \\\n --member-id user@example.com --perm edit\n\n# 查看 / 删除协作者\nfeishu-cli perm list --doc-type docx\nfeishu-cli perm delete --doc-type docx --member-type email --member-id user@example.com\n\n# 公开权限管理\nfeishu-cli perm public-get \nfeishu-cli perm public-update --external-access --link-share-entity anyone_readable\n\n# 分享密码\nfeishu-cli perm password create \nfeishu-cli perm password delete \n\n# 批量添加协作者\nfeishu-cli perm batch-add --members-file members.json --notification\n\n# 权限检查\nfeishu-cli perm auth --action view\n\n# 转移所有权\nfeishu-cli perm transfer-owner --member-type email --member-id user@example.com\n```\n\n
\n\n
\n群聊管理\n\n```bash\n# 群聊 CRUD\nfeishu-cli chat create --name \"群聊名\" --user-ids id1,id2\nfeishu-cli chat get \nfeishu-cli chat update --name \"新群名\"\nfeishu-cli chat delete \nfeishu-cli chat link \n\n# 群成员管理\nfeishu-cli chat member list \nfeishu-cli chat list --page-all # 列出当前身份加入的全部群\nfeishu-cli chat member list --page-all # 全量成员（安全截断时告警）\nfeishu-cli chat member add --id-list id1,id2\nfeishu-cli chat member remove --id-list id1,id2\n```\n\n
\n\n
\n文件管理\n\n```bash\n# 基础操作\nfeishu-cli file list [folder_token]\nfeishu-cli file mkdir \"新文件夹\" --parent \n\n# 上传 / 下载\nfeishu-cli file upload local_file.pdf --parent FOLDER_TOKEN\nfeishu-cli file download -o output.pdf\nfeishu-cli file download -o large.zip --user-access-token u-xxx --timeout 30m # 大文件自动 Range 分片兜底\n\n# 版本管理\nfeishu-cli file version list --doc-type docx\nfeishu-cli file version revert # 回滚到历史版本\nfeishu-cli file version create --doc-type docx --name \"v1.0\"\nfeishu-cli file version get --doc-type docx\nfeishu-cli file version delete --doc-type docx\n\n# 元数据与统计\nfeishu-cli file meta TOKEN1 TOKEN2 --doc-type docx\nfeishu-cli file stats --doc-type docx\n```\n\n
\n\n
\n搜索操作\n\n搜索 API 需要 User Access Token。推荐使用 `auth login` 一键获取（Token 自动保存和刷新），也可通过 `--user-access-token` 参数或环境变量手动指定。\n\n```bash\n# 获取 User Access Token（推荐，一次登录自动刷新）\nfeishu-cli auth login\n\n# 搜索消息（默认返回消息 ID，-o json 输出 {MessageIDs,HasMore,PageToken}）\nfeishu-cli search messages \"关键词\"\nfeishu-cli search messages \"会议\" --chat-ids oc_xxx,oc_yyy\nfeishu-cli search messages \"你好\" --chat-type p2p_chat # 搜索私聊消息\nfeishu-cli search messages \"会议\" --enrich # 补全内容/发送者/群名/时间\n\n# 搜索应用\nfeishu-cli search apps \"审批\"\n\n# 搜索文档和 Wiki\nfeishu-cli search docs \"产品需求\"\nfeishu-cli search docs \"季度报告\" --docs-types doc,sheet\nfeishu-cli search docs \"技术方案\" --count 10 --offset 0\n\n# 也可以手动指定 Token\nfeishu-cli search docs \"产品需求\" --user-access-token \nexport FEISHU_USER_ACCESS_TOKEN=\"u-xxx\"\nfeishu-cli search docs \"产品需求\"\n```\n\n
\n\n
\n审批操作\n\n全部当前审批 API 使用 User Token。`approval get` 走 `GET /open-apis/approval/v4/approvals/{approval_code}/detail`，需要 `approval:approval:read`；`approval instance get` 走 `GET .../instances/detail`，需要 `approval:instance:read`；`approval instance initiated` 走 `GET .../instances/initiated`；`approval task query` 走 `GET .../tasks`（不传 `user_id` query），需要 `approval:task:read`。写流程：`instance create` → `POST .../instances/initiate`（`approval:instance:write`，发起人取当前登录用户）；`instance cancel` → `POST .../instances/recall`；`instance cc` → `POST .../instances/add_cc`；`task approve/reject/transfer` → `POST .../tasks/pass|refuse|forward`。\n\n输出说明：\n- 不传 `--output`：输出便于阅读的文本摘要\n- `--output json`：输出 CLI 归一化后的 JSON，部分字段会做拍平和字符串化处理\n- `--output raw-json`：输出飞书 API 原始**成功**响应；HTTP 200 但业务 `code != 0` 时非零退出\n\n```bash\n# 查询审批定义详情（User Token）\nfeishu-cli approval get \n\n# 输出完整 JSON\nfeishu-cli approval get --output json\n\n# 输出飞书 API 原始响应\nfeishu-cli approval get --output raw-json\n\n# 查询审批实例详情（User Token）\nfeishu-cli approval instance get --instance-code \nfeishu-cli approval instances get --instance-code --output raw-json\n\n# 查询我发起的审批实例\nfeishu-cli approval instance initiated\nfeishu-cli approval instance initiated --output json\n\n# 查询当前登录用户的待我审批\nfeishu-cli approval task query --topic todo\n\n# 查询我已审批的任务\nfeishu-cli approval task query --topic done\n\n# 查询抄送给我的（未读 / 已读）\nfeishu-cli approval task query --topic cc-unread --output json\nfeishu-cli approval task query --topic cc-read\n\n# 输出飞书 API 原始响应\nfeishu-cli approval task query --topic todo --output raw-json\n\n# 注：--topic 仅接受 todo / done / cc-unread / cc-read（服务端 options 为 1/2/17/18）。\n# started（topic=3）已被官方下线，查「我发起的」请用上面的 approval instance initiated\n\n# 翻页查询\nfeishu-cli approval task query --topic todo --page-size 20 --page-token \n\n# 显式指定 User Access Token\nfeishu-cli approval task query --topic cc-unread --user-access-token \n\n# 发起审批实例（身份取当前 User Token；form.json 为飞书审批表单 JSON 数组）\nfeishu-cli approval instance create --approval-code --form-file form.json\n\n# 撤回 / 抄送审批实例\nfeishu-cli approval instance cancel --instance-code \nfeishu-cli approval instance cc --instance-code --cc-user-ids ou_a,ou_b\n\n# 通过 / 拒绝审批任务\nfeishu-cli approval task approve --instance-code --task-id --comment \"同意\"\nfeishu-cli approval task reject --instance-code --task-id --comment \"信息不完整\"\n\n# 转交审批任务（User Token）\nfeishu-cli approval task transfer --instance-code --task-id --transfer-user-id ou_target --comment \"请代审\"\n```\n\n
\n\n
\n身份认证（Device Flow）\n\n通过 **OAuth 2.0 Device Flow（RFC 8628）** 获取 User Access Token，用于搜索、审批待办查询等需要用户授权的功能。**无需在飞书开放平台配置任何重定向 URL 白名单**。\n\n> **v1.18+ 变更**：Authorization Code Flow（`--print-url` / `auth callback` / `--manual` / `--port` / `--method` / `--scopes`）已全部删除，只保留 Device Flow。\n\n```bash\n# 按业务域申请推荐权限（推荐）\nfeishu-cli auth login --domain search --recommend\n\n# 显式申请某组 scope\nfeishu-cli auth login --scope \"minutes:minutes.basic:read minutes:minutes.transcript:export\"\n\n# JSON 事件流输出（AI Agent 推荐，配合 run_in_background 使用）\nfeishu-cli auth login --domain search --recommend --json\n\n# 两步模式：先立即输出 device_code，不启动轮询\nfeishu-cli auth login --domain vc --domain minutes --recommend --no-wait --json\n\n# 两步模式：用已有 device_code 继续轮询\nfeishu-cli auth login --device-code --json\n\n# 预检 token 是否包含所需 scope（AI Agent 推荐在执行业务命令前调用）\nfeishu-cli auth check --scope \"search:docs:read\"\nfeishu-cli auth check --scope \"search:docs:read im:message:readonly\"\n\n# 查看当前授权状态\nfeishu-cli auth status\nfeishu-cli auth status -o json # JSON 格式输出\n\n# 退出登录（清除本地 token）\nfeishu-cli auth logout\n```\n\n登录时 CLI 在 stderr 打印验证链接和 user_code，用户在任意设备（电脑、手机）浏览器打开链接完成授权即可。本地桌面会尝试自动打开浏览器，SSH 远程失败静默忽略。\n\n**授权范围策略**：\n- CLI 会显式声明本次请求的 scope，不再依赖“后台开了什么就全量返回”\n- 推荐先用 `auth check --scope \"REQ_SCOPES\"` 预检，再用 `auth login --scope \"...\"` 或 `auth login --domain ... --recommend` 补授权\n- 即使显式请求业务 scope，CLI 也会自动追加最小核心 scope（如 `auth:user.id:read`）用于识别当前登录用户\n- 要真正拿到某个 scope，仍然必须先在飞书开放平台应用权限管理页面开通它\n\n**Token 管理**：\n- Token 保存在 `~/.feishu-cli/token.json`（0600，原子写入），Access Token 有效期约 2 小时\n- Access Token 过期时自动使用 Refresh Token 刷新（跨进程锁，避免两个进程消耗同一 refresh token）\n- 新登录写入的 `token.json` 带 `app_id` 绑定；与当前 App 不一致或旧文件未绑定时，**一律拒绝使用**（即使 access 仍有效）。迁移：`feishu-cli auth token --bind-legacy-app --as user`（不更换 token；不可与 `--as bot` / `--user-access-token` 同时用）或重新 `auth login`\n- `auth token --as bot` 走官方 Accounts OAuth v3 `client_credentials`；不可与 `--user-access-token` 同时使用\n- `offline_access` 由 CLI 自动追加，无需手动声明\n- Token 优先级：`--user-access-token` 参数 > `FEISHU_USER_ACCESS_TOKEN` 环境变量 > `token.json` > `config.yaml`\n- 审批任务查询会缓存当前登录用户资料到 `~/.feishu-cli/user_profile.json`，登录态变化或执行 `auth logout` 时会自动清理\n- `base_url` 默认仅官方 HTTPS。自定义远端 / 明文 HTTP / 带 body 跨源重定向需显式 opt-in（`FEISHU_ALLOW_CUSTOM_BASE_URL`、`FEISHU_ALLOW_INSECURE_HTTP`、`FEISHU_ALLOW_CROSS_ORIGIN_REDIRECT`）\n\n
\n\n
\n更多命令\n\n```bash\n# 文档异步导出/导入\nfeishu-cli doc export-file --type pdf -o output.pdf\nfeishu-cli doc import-file local_file.docx --type docx --name \"文档名\"\n\n# 素材上传\nfeishu-cli media upload image.png --parent-type docx_image --parent-node \n\n# 日历\nfeishu-cli calendar list\nfeishu-cli calendar get \nfeishu-cli calendar primary\nfeishu-cli calendar create-event --calendar-id --summary \"会议\" \\\n --start \"2024-01-01T10:00:00+08:00\" --end \"2024-01-01T11:00:00+08:00\"\nfeishu-cli calendar event-search --calendar-id --query \"关键词\"\nfeishu-cli calendar event-reply --status accept\nfeishu-cli calendar attendee add --user-ids id1,id2\nfeishu-cli calendar attendee list \nfeishu-cli calendar freebusy --start \"2024-01-01T00:00:00+08:00\" \\\n --end \"2024-01-02T00:00:00+08:00\" --user-ids id1,id2\n\n# 任务\nfeishu-cli task create --summary \"待办事项\"\nfeishu-cli task complete \nfeishu-cli task subtask create --summary \"子任务\"\nfeishu-cli task subtask list \nfeishu-cli task member add --members id1,id2 --role assignee\nfeishu-cli task reminder add --minutes 30\nfeishu-cli task upload-attachment --task-guid --file ./report.pdf\n\n# 任务列表\nfeishu-cli tasklist create --name \"任务列表\"\nfeishu-cli tasklist list\nfeishu-cli tasklist get \nfeishu-cli tasklist delete \n\n# 画板（v1.25+ 新增 5 个子命令 + Mermaid 本地引擎 + Markdown ```svg fence 自动识别）\nfeishu-cli board create-notes nodes.json -o json # 精排绘图（JSON 控制坐标、颜色、连线）\nfeishu-cli board import \"graph TD; A-->B\" --source-type content --syntax mermaid --diagram-type flowchart # 服务端渲染\nfeishu-cli board import diagram.mmd --syntax mermaid --engine local # 本地引擎（whiteboard-cli 翻译，每个节点可单独编辑）\nfeishu-cli board import diagram.puml --syntax plantuml # 导入 PlantUML\nfeishu-cli board svg-import drawing.svg # 单 svg 节点装饰（图标/印章 < 2KB）\nfeishu-cli board svg-export -o board.svg # 服务端 SVG 导出\nfeishu-cli board clone --batch-size 10 # 克隆画板（含 connector ID 重映射 + 分批节流）\nfeishu-cli board upload-image photo.png # 上传本地图片为 image 节点（自动推断像素尺寸）\nfeishu-cli board lint # 几何质检（重叠/字号一致性/容量/综合评分）\nfeishu-cli board export-code --merge --output-path design.svg # 反向导出 SVG（按 z_index 排序）\nfeishu-cli board update nodes.json --overwrite --snapshot old.json # 覆盖更新+快照备份\nfeishu-cli board nodes # 获取画板所有节点\nfeishu-cli board image output # 下载画板截图（自动按实际格式补扩展名，通常 JPEG）\n# ⭐ AI 自由作图（飞轮/鱼骨/Dashboard/插画/周期表/赛博朋克等）：用 skill 的一键脚本，每个矢量元素都可单独点击编辑\npython3 skills/feishu-cli-visual/references/workflows/board/scripts/svg_to_board.py drawing.svg \n# 内置 5 步管道：whiteboard-cli 翻译 → 修 z_index → 修剪 viewBox 溢出 → 分批 create-notes → 验证\n\n# 评论\nfeishu-cli comment list --type docx\nfeishu-cli comment add --type docx --text \"评论内容\"\nfeishu-cli comment resolve --type docx\nfeishu-cli comment unresolve --type docx\nfeishu-cli comment reply list --type docx\nfeishu-cli comment reply delete --type docx\n\n# 多维表格（base/v3 API）\nfeishu-cli bitable create --name \"项目管理\" --time-zone Asia/Shanghai\nfeishu-cli bitable table list --base-token bscnxxxx\nfeishu-cli bitable table create --base-token bscnxxxx --name \"任务\"\nfeishu-cli bitable field list --base-token bscnxxxx --table-id tblxxx\nfeishu-cli bitable field create --base-token bscnxxxx --table-id tblxxx --config '{\"name\":\"状态\",\"type\":\"select\"}'\nfeishu-cli bitable record upsert --base-token bscnxxxx --table-id tblxxx --config '{\"fields\":{\"名称\":\"测试\"}}'\nfeishu-cli bitable record upsert --base-token bscnxxxx --table-id tblxxx --record-id recxxx --config '{\"fields\":{\"状态\":\"完成\"}}'\nfeishu-cli bitable record batch-create --base-token bscnxxxx --table-id tblxxx --config '{\"create_records\":[{\"fld1\":\"val1\"},{\"fld1\":\"val2\"}]}'\nfeishu-cli bitable record batch-delete --base-token bscnxxxx --table-id tblxxx --record-ids rec_1,rec_2,rec_3\nfeishu-cli bitable record batch-get --base-token bscnxxxx --table-id tblxxx --record-ids rec_1,rec_2 # 批量获取记录\nfeishu-cli bitable record share-link --base-token bscnxxxx --table-id tblxxx --record-ids rec_1,rec_2 # 批量共享链接（v1.29+）\nfeishu-cli bitable record list --base-token bscnxxxx --table-id tblxxx\n# 结构化过滤/排序（tuple DSL，无需关键词）\nfeishu-cli bitable record list --base-token bscnxxxx --table-id tblxxx \\\n --filter-json '{\"logic\":\"and\",\"conditions\":[[\"状态\",\"==\",[\"Doing\"]],[\"分数\",\">=\",70]]}' \\\n --sort-json '[{\"field\":\"分数\",\"desc\":true}]'\nfeishu-cli bitable view list --base-token bscnxxxx --table-id tblxxx\nfeishu-cli bitable view view-filter-get --base-token bscnxxxx --table-id tblxxx --view-id vewxxx\nfeishu-cli bitable role list --base-token bscnxxxx\n\n# 记录附件（上传 / 下载 / 移除）\nfeishu-cli bitable record upload-attachment --base-token bscnxxxx --table-id tblxxx \\\n --record-id recxxx --field-id fldxxx --file ./report.pdf --file ./shot.png\nfeishu-cli bitable record download-attachment --base-token bscnxxxx --table-id tblxxx \\\n --record-id recxxx --output ./downloads/\nfeishu-cli bitable record remove-attachment --base-token bscnxxxx --table-id tblxxx \\\n --record-id recxxx --field-id fldxxx --file-token boxcnxxxx\n\n# 仪表盘（CRUD + 智能排版 + 仪表盘块）\nfeishu-cli bitable dashboard create --base-token bscnxxxx --name \"运营看板\"\nfeishu-cli bitable dashboard block create --base-token bscnxxxx --dashboard-id dsbxxxx \\\n --type column --name \"按月统计\" --data-config '{\"table_name\":\"任务\",\"group_by\":\"月份\"}'\nfeishu-cli bitable dashboard arrange --base-token bscnxxxx --dashboard-id dsbxxxx\n\n# 表单（CRUD + 分享 token 详情/提交 + 表单问题）\nfeishu-cli bitable form create --base-token bscnxxxx --table-id tblxxx --name \"报名表\"\nfeishu-cli bitable form field create --base-token bscnxxxx --table-id tblxxx --form-id vewxxx \\\n --questions '[{\"type\":\"text\",\"title\":\"你的名字\",\"required\":true}]'\nfeishu-cli bitable form detail --share-token shrcnxxxx # 无需 base_token\nfeishu-cli bitable form submit --share-token shrcnxxxx --content '{\"评分\":5,\"评价\":\"很好\"}'\n\n# 角色协作者（member list/create/delete/batch-create/batch-delete）\nfeishu-cli bitable role member list --base-token bscnxxxx --role-id rolxxxx\nfeishu-cli bitable role member create --base-token bscnxxxx --role-id rolxxxx --member-id ou_xxx --member-id-type open_id\nfeishu-cli bitable role member delete --base-token bscnxxxx --role-id rolxxxx --member-id ou_xxx --member-id-type open_id\nfeishu-cli bitable role member batch-create --base-token bscnxxxx --role-id rolxxxx --member-ids ou_a,ou_b --member-id-type open_id\n\n# 多维表格元信息更新（重命名 / 高级权限开关）\nfeishu-cli bitable update --base-token bscnxxxx --name \"新表名\" # 重命名\nfeishu-cli bitable update --base-token bscnxxxx --is-advanced # 开启高级权限（--is-advanced=false 关闭）\n\n# 工作流（list/get/create/update/enable/disable；update 为整体替换 PUT）\nfeishu-cli bitable workflow list --base-token bscnxxxx\nfeishu-cli bitable workflow get --base-token bscnxxxx --workflow-id wkfxxxx\nfeishu-cli bitable workflow update --base-token bscnxxxx --workflow-id wkfxxxx --config-file wf.json\nfeishu-cli bitable workflow enable --base-token bscnxxxx --workflow-id wkfxxxx\nfeishu-cli bitable workflow disable --base-token bscnxxxx --workflow-id wkfxxxx\n\n# 云盘增强（drive）\nfeishu-cli drive upload --file big.zip --folder-token fldxxx\nfeishu-cli drive upload --file new.zip --file-token boxcnXXX # 原地覆盖上传新版本\nfeishu-cli drive secure-label list --lang zh # 密级标签查询 / set 设置\nfeishu-cli drive download --file-token boxxxx --output ./downloads/ --overwrite\nfeishu-cli drive download --file-token boxxxx --output ./big.zip --timeout 30m # 大文件自动 Range 分片兜底\nfeishu-cli drive export --token docxxxx --doc-type docx --file-extension markdown --output-dir ./exports\nfeishu-cli drive export --token sheetxxxx --doc-type sheet --file-extension csv --sub-id sheet_1 --output-dir ./out\nfeishu-cli drive export --token sldxxxx --doc-type slides --file-extension pptx --output-dir ./out\nfeishu-cli drive import --file report.docx --type docx --folder-token fldxxx\nfeishu-cli drive import --file deck.pptx --type slides\nfeishu-cli drive move --file-token fldxxx --type folder --folder-token fldyyy\nfeishu-cli drive move --file-token boxxxx --type file # 省略目标时先取真实 root token\nfeishu-cli drive add-comment --doc docxxx --content '[{\"type\":\"text\",\"text\":\"评论\"}]'\n\n# v1.29+ 新增 ⭐\nfeishu-cli drive inspect --url \"https://xxx.feishu.cn/docx/doxxxx\" # 解析 URL → type/title/token\nfeishu-cli drive apply-permission --token \"\" --perm view --remark \"申请理由\" # 向 owner 发申请\n\n# 云盘 ↔ 本地单向镜像（pull/push/status）\nfeishu-cli drive status --folder-token fldxxx --local-dir ./mirror\nfeishu-cli drive pull --folder-token fldxxx --local-dir ./mirror --if-exists overwrite\nfeishu-cli drive push --folder-token fldxxx --local-dir ./mirror --if-exists skip\nfeishu-cli drive pull --folder-token fldxxx --local-dir ./mirror --delete-local --yes # 高危：双确认\n\n# 云盘 v2 搜索（扁平 filter；search docs 走 v1，drive search 走 v2）\nfeishu-cli drive search --query \"季度报告\" --doc-types DOC,SHEET --sort edit_time\nfeishu-cli drive search --folder-tokens fldxxx --only-title\n\n# 邮箱（mail，需 User Token）\nfeishu-cli mail triage --folder INBOX --unread-only --page-size 20\nfeishu-cli mail triage --query \"周会\"\nfeishu-cli mail message --message-id msg_xxx\nfeishu-cli mail send --to user@example.com --subject \"测试\" --body \"hi\" # 默认存草稿\nfeishu-cli mail send --to user@example.com --subject \"测试\" --body \"hi\" --confirm-send # 立即发送\nfeishu-cli mail message-modify --message-ids id1,id2 --add-label-ids FLAGGED # 批量改 label/移文件夹\nfeishu-cli mail message-trash --message-ids id1,id2 --yes # 批量软删进废纸篓\nfeishu-cli mail draft-send --draft-id --confirm-send # 发送已有草稿\nfeishu-cli mail send --to user@example.com --subject \"周报\" --body \"$(cat report.html)\" \\\n --html --inline-images-auto-scan --confirm-send\nfeishu-cli mail template create --name \"周报模板\" --subject \"本周进度\" --body \"$(cat template.html)\"\nfeishu-cli mail template list\nfeishu-cli mail reply --message-id msg_xxx --body \"收到\" --confirm-send\nfeishu-cli mail forward --message-id msg_xxx --to team@example.com --body \"请关注\"\nfeishu-cli mail signature # 列出邮箱签名\nfeishu-cli mail signature --detail 7012345678901234567 -o json # 单个签名详情\n\n# 视频会议（vc）：search/notes/recording 需 User Token；bot meeting-join/leave 默认 Bot/Tenant 身份\nfeishu-cli vc search --query \"周会\" --start 2026-03-20 --end 2026-03-28\nfeishu-cli vc detail # 聚合会议信息 + note_id + minute_token\nfeishu-cli vc note detail # 智能纪要详情\nfeishu-cli vc note transcript --output t.md # 统一逐字稿导出\nfeishu-cli vc notes --meeting-ids 69xxxx,70xxxx\nfeishu-cli vc notes --minute-tokens obcnxxxx --with-artifacts --download-transcript --output-dir ./notes\nfeishu-cli vc recording --meeting-ids 69xxxx\nfeishu-cli vc bot meeting-join --meeting-number 123456789 # 机器人入会（Bot/Tenant 身份）\nfeishu-cli vc bot meeting-leave --meeting-id 6911188411932033028 # 机器人离会（Bot/Tenant 身份）\nfeishu-cli vc bot meeting-events --meeting-id 6911188411932033028 --as user --start 2026-03-01 --end 2026-03-31\nfeishu-cli vc bot meeting-events --meeting-id 6911188411932033028 --as bot --dry-run # 与 meeting_id 来源身份一致；禁止静默回落\n\n# 妙记（minutes，需 User Token）\nfeishu-cli minutes get --with-artifacts\nfeishu-cli minutes get --wait-ready # 轮询等待妙记转写就绪\nfeishu-cli minutes search --query \"周会\" # 搜索妙记\nfeishu-cli minutes apply-permission --minute-token --perm view # 申请妙记权限\nfeishu-cli minutes download --minute-tokens obcnxxxx --output ./media\nfeishu-cli minutes download --minute-tokens obcnxxxx --url-only\n\n# 妙搭（Miaoda）应用 —— 一份 HTML 秒级发布成可分享的飞书应用（需 User Token + spark scope）\nfeishu-cli auth login --scope \"spark:app:read spark:app:write\" # ⚠️ --scope 是替换不是合并，需并入你完整 scope 串\nfeishu-cli apps create --name \"我的页面\" --app-type HTML # 拿 app_id（jq .app.app_id，CLI 已剥掉 data 外层）\nfeishu-cli apps html-publish --app-id app_xxx --path ./dist # 三段协议发布，返回 release_id（jq .release_id）\nfeishu-cli apps html-publish --app-id app_xxx --path ./index.html # 单文件形态（文件名必须 index.html）\nfeishu-cli apps html-publish --app-id app_xxx --path ./dist --dry-run # 只看三段计划 + 打包清单，零网络\nfeishu-cli apps access-scope-set --app-id app_xxx --scope tenant # 组织内可见\nfeishu-cli apps access-scope-set --app-id app_xxx --scope public --require-login=true\nfeishu-cli apps access-scope-set --app-id app_xxx --scope specific \\\n --targets '[{\"type\":\"user\",\"id\":\"ou_xxx\"},{\"type\":\"chat\",\"id\":\"oc_xxx\"}]'\nfeishu-cli apps access-scope-get --app-id app_xxx # 查看当前访问范围\nfeishu-cli apps update --app-id app_xxx --name \"新名字\"\n\n# 日历增强\nfeishu-cli calendar agenda # 查看今日日程\nfeishu-cli calendar agenda --start-date 2026-03-28 --end-date 2026-03-29\nfeishu-cli calendar suggestion --attendee-ids ou_aaa,ou_bbb --duration 30m\nfeishu-cli calendar room-find --slot 2026-03-28T14:00:00+08:00~2026-03-28T15:00:00+08:00 \\\n --city \"北京\" --min-capacity 6\nfeishu-cli calendar rsvp --event-id EVENT_xxx --action accept\n\n# 任务增强\nfeishu-cli task my # 查看我的任务\nfeishu-cli task search --keyword 评审 --uncompleted --due-before 2026-12-31 # 服务端搜索（--enrich=false 免详情补全）\nfeishu-cli task reopen # 重新打开\nfeishu-cli task comment add --content \"评论\"\nfeishu-cli tasklist task-add --task-ids guid1,guid2\nfeishu-cli tasklist member add --members ou_xxx\n\n# 消息增强\nfeishu-cli msg mget --message-ids om_xxx,om_yyy\nfeishu-cli msg resource-download --type image -o photo.png\nfeishu-cli msg resource-download --type file --user-access-token u-xxx -o attachment.bin # 用户可见但 Bot 不可见的资源\nfeishu-cli msg resource-download --type file --user-access-token u-xxx -o large.bin --timeout 30m # 大文件自动 Range 分片兜底\nfeishu-cli msg thread-messages --page-size 20\nfeishu-cli msg flag create om_xxx # 收藏消息\nfeishu-cli msg flag create om_xxx --flag-type feed # feed 层自动识别 thread/msg_thread\nfeishu-cli msg flag list --page-size 50\nfeishu-cli msg flag cancel om_xxx # 尽量取消消息层 + feed 层\n\n# interactive 卡片返回原始 schema（不再返回渲染后的 文本）\nfeishu-cli msg get om_xxx --card-content-type user # userDSL（开发者视角的 schema 2.0 JSON）\nfeishu-cli msg get om_xxx --card-content-type raw # cardDSL（平台内部完整描述）\nfeishu-cli msg mget --message-ids om_xxx,om_yyy --card-content-type user\nfeishu-cli msg list --container-id oc_xxx --card-content-type user\n\n# 文档增强（采用 docs_ai 单操作原子更新协议，彻底避免先删后写破坏窗口；支持 --revision-id 并发保护）\nfeishu-cli doc content-update --mode append --markdown \"## 新内容\"\nfeishu-cli doc content-update --mode overwrite --markdown \"# 全新文档\" [--revision-id 42]\nfeishu-cli doc content-update --mode replace_range --selection-by-title \"章节标题\" --markdown \"## 新章节\"\nfeishu-cli doc media-insert --file photo.png --type image --align center\nfeishu-cli doc media-download -o image.png\nfeishu-cli doc media-download --doc-token DOC_TOKEN --doc-type docx -o image.png\n\n# 妙笔BOX HTML 小组件（文档里跑动画 / ECharts / 可交互图表，唯一能\"动\"的载体）\nfeishu-cli doc htmlbox create --html-file widget.html\nfeishu-cli doc htmlbox update --html-file widget-v2.html\nfeishu-cli doc htmlbox get --raw > current.html\nfeishu-cli doc htmlbox delete \n\n# 电子表格导出\nfeishu-cli sheet export -o output.xlsx\nfeishu-cli sheet export --format csv --sheet-id SHEET_ID -o output.csv\nfeishu-cli sheet export --format markdown -o output.md\nfeishu-cli sheet filter-view create --spreadsheet-token shtcnxxxx --sheet-id SHEET_ID \\\n --range \"SHEET_ID!A1:H100\" --name \"P0 高优\"\nfeishu-cli sheet filter-view list --spreadsheet-token shtcnxxxx --sheet-id SHEET_ID\nfeishu-cli sheet filter-view update --token shtcnxxxx --sheet-id SHEET_ID \\\n --filter-view-id pH9xxxx --name \"新名字\"\n# 筛选条件（按列字母定位）\nfeishu-cli sheet filter-view condition create --token shtcnxxxx --sheet-id SHEET_ID \\\n --filter-view-id pH9xxxx --condition-id E --filter-type number --compare-type less --expected '[\"6\"]'\nfeishu-cli sheet filter-view condition list --token shtcnxxxx --sheet-id SHEET_ID --filter-view-id pH9xxxx\nfeishu-cli sheet dropdown set --token shtcnxxxx --range \"SHEET_ID!B2:B100\" \\\n --options \"待办,处理中,已完成\"\nfeishu-cli sheet dropdown update --token shtcnxxxx --sheet-id SHEET_ID \\\n --ranges \"SHEET_ID!A1:A100\" --options \"P0,P1,P2\" --multiple --colors \"#FF4D4F,#FAAD14,#52C41A\"\nfeishu-cli sheet dropdown get --token shtcnxxxx --range \"SHEET_ID!A1:A100\"\nfeishu-cli sheet dropdown delete --token shtcnxxxx --ranges \"SHEET_ID!A1:A100\"\n# 浮动图片 / 单元格写图 / 批量样式\nfeishu-cli sheet image media-upload shtcnxxxx ./logo.png # 返回 file_token\nfeishu-cli sheet image write-image shtcnxxxx SHEET_ID --range \"A1\" --image ./logo.png\nfeishu-cli sheet batch-set-style shtcnxxxx \\\n --data '[{\"ranges\":[\"SHEET_ID!A1:A2\"],\"style\":{\"font\":{\"bold\":true},\"backColor\":\"#FF0000\"}}]'\n\n# Drive 原生 Markdown 文件（不做 docx 块转换）\nfeishu-cli markdown create --name README.md --content-file ./README.md --folder-token fldxxx\nfeishu-cli markdown create --file ./README.md --wiki-token wikcnxxx --as bot --dry-run\nfeishu-cli markdown fetch --file-token boxcnxxx --output-path ./remote.md\nfeishu-cli markdown overwrite --file-token boxcnxxx --file ./remote.md\nfeishu-cli markdown patch --file-token boxcnxxx --pattern \"TODO\" --content \"DONE\"\nfeishu-cli markdown diff --file-token boxcnxxx --file ./local.md # 远端最新 vs 本地\nfeishu-cli markdown diff --file-token boxcnxxx --from-version 2 --to-version 5 # 远端版本 A vs B\n\n# 用户\nfeishu-cli user info \nfeishu-cli user search --email user@example.com # 邮箱查 user_id；带 User Token 时自动补 open_id + 姓名\nfeishu-cli user search --mobile 13800138000\nfeishu-cli user search --query \"张三\" # 按姓名/关键词模糊搜索，需 User Token\nfeishu-cli user list --department-id DEPT_ID\n\n# 部门\nfeishu-cli dept get \nfeishu-cli dept children \n\n# 考勤（支持 User/Tenant Token，未传 --user-ids 自动走本人自查）\nfeishu-cli attendance user-task query --start 2026-03-01 --end 2026-03-31\nfeishu-cli attendance user-task query --employee-type employee_id --user-ids 2847xxxx \\\n --start 2026-03-01 --end 2026-03-31\nfeishu-cli attendance user-stats query --employee-type employee_no --user-ids 10001 \\\n --start 2026-03-01 --end 2026-03-31\n\n# OKR\nfeishu-cli okr cycle list\nfeishu-cli okr progress list --objective-id 7xxx\nfeishu-cli okr cycle detail # 周期下全部目标+关键结果\nfeishu-cli okr progress get/update/delete # 进展记录全生命周期\nfeishu-cli okr upload-image --file chart.png --objective-id 7xxx # 进展图片素材\nfeishu-cli okr progress create --key-result-id 7xxx --content \"本周完成核心模块联调\"\n\n# Slides 演示文稿\nfeishu-cli slides create --title \"Q2 OKR\" --output json\nfeishu-cli slides media-upload --file ./cover.png --presentation-token \n\n# 实时事件订阅\nfeishu-cli event list\nfeishu-cli event schema im.message.receive_v1\nfeishu-cli event consume im.message.receive_v1 --max-events 5 --timeout 60s\nfeishu-cli event consume card.action.trigger # 卡片按钮/表单回调（交互式 Bot）\nfeishu-cli event consume approval.instance.status_changed_v4 # 审批事件（自动注册服务端订阅）\nfeishu-cli event consume vc.meeting.participant_meeting_ended_v1 # VC：User pre-consume，握手后才发 ready\nfeishu-cli event status\nfeishu-cli event stop --all\n\n# OpenAPI schema / 健康检查 / 多配置\nfeishu-cli schema list --service im\nfeishu-cli schema status --format json\nfeishu-cli schema im.messages.delete --format json\nfeishu-cli doctor --json\nfeishu-cli doctor --only catalog --offline --json\nfeishu-cli profile list --json\nfeishu-cli profile current --json\nfeishu-cli profile migrate\nfeishu-cli profile add work --app-id cli_xxx --app-secret secret_xxx --use\nfeishu-cli --profile work auth status -o json\nfeishu-cli --bot-app-id cli_xxx --bot-app-secret xxx profile list --json # 单次覆盖 App 凭证，不切换 token.json\nfeishu-cli profile use -\n\n# 通用 OpenAPI 透传（v1.29+）⭐ 覆盖 2500+ 未封装端点\nfeishu-cli api GET /open-apis/authen/v1/user_info --as user\nfeishu-cli api GET /open-apis/im/v1/chats --params '{\"page_size\":10}' --as user\nfeishu-cli api GET /open-apis/im/v1/chats --page-all --page-limit 10 --as user\nfeishu-cli api POST /open-apis/im/v1/messages --params '{\"receive_id_type\":\"email\"}' \\\n --data '{\"receive_id\":\"u@example.com\",\"msg_type\":\"text\",\"content\":\"{\\\"text\\\":\\\"hi\\\"}\"}' --as bot\nfeishu-cli api DELETE /open-apis/im/v1/messages/om_xxx --as bot --dry-run # 预览\nfeishu-cli auth token --as user # 导出 token 给其他工具用（如果需要）\n```\n\n
\n\n## AI 技能集成\n\n`skills/` 目录包含 **9 个领域 Skill**。每个领域 Skill 在 `references/workflows/` 下按需加载细粒度工作流，减少常驻上下文，同时覆盖完整 CLI 能力。\n\n| 技能 | 功能 | 触发示例 |\n|------|------|---------|\n| `feishu-cli-platform` | 认证、配置、Profile、doctor、API/schema、搜索、通讯录 | \"登录飞书\"、\"查这个 API 参数\" |\n| `feishu-cli-docs` | 文档读取/编辑、Markdown 导入、导出、原生 `.md` CRUD | \"把这个 md 导入飞书\" |\n| `feishu-cli-storage` | Drive、file/media、wiki、评论和权限 | \"上传文件并给同事权限\" |\n| `feishu-cli-messaging` | 消息发送、聊天历史、群管理、卡片和事件订阅 | \"做张卡片发到群里\" |\n| `feishu-cli-data` | Sheet 与 Bitable/Base 全功能 | \"给表格加下拉框\" |\n| `feishu-cli-visual` | dataviz、画板、Slides、妙笔BOX 和妙搭应用 | \"在飞书里画交互图表\" |\n| `feishu-cli-work` | 日历、任务、审批、考勤和 OKR | \"找时间开会并创建任务\" |\n| `feishu-cli-mail` | 飞书邮箱读取、草稿、发送、回复和转发 | \"回复这封飞书邮件\" |\n| `feishu-cli-meetings` | 视频会议、妙记、录制、逐字稿和会议机器人 | \"下载会议纪要\" |\n\n
\n旧 Skill 名称迁移对照（v1.35 前的 29 个技能 → 9 个领域）\n\n| 新 Skill | 合并的旧 Skill |\n|---|---|\n| `feishu-cli-platform` | api、auth、schema、search，以及 toolkit 的 user/dept/search 参考资料 |\n| `feishu-cli-docs` | read、write、import、export、markdown |\n| `feishu-cli-storage` | drive、perm，以及 toolkit 的 file/media/wiki/comment |\n| `feishu-cli-messaging` | msg、chat、card、event，以及 toolkit 的 chat 参考资料 |\n| `feishu-cli-data` | sheet、bitable，以及 toolkit 的 sheet 参考资料 |\n| `feishu-cli-visual` | dataviz、board、slides、htmlbox、apps，以及 toolkit 的 board 参考资料 |\n| `feishu-cli-work` | calendar、approval、attendance、okr，以及 toolkit 的 calendar/task/tasklist |\n| `feishu-cli-mail` | mail（名称不变） |\n| `feishu-cli-meetings` | vc、minutes |\n\n
\n\n**安装方法**：\n\n```bash\n# 一键安装全部技能（推荐）\nnpx skills add riba2534/feishu-cli --global --yes --agent claude-code --copy\n\n# 或手动复制\n# 将 skills/ 目录复制到 ~/.claude/skills/\n```\n\n## 块类型映射\n\n
\nMarkdown ↔ 飞书块类型完整对照表\n\n| Markdown | 飞书块类型 | block_type | 说明 |\n|----------|-----------|------------|------|\n| `# 标题` | Heading 1-9 | 3-11 | 支持 9 级标题（Markdown 规范 6 级） |\n| 段落文本 | Text | 2 | 普通文本 |\n| `- 列表` | Bullet | 12 | 无序列表（支持无限深度嵌套） |\n| `1. 列表` | Ordered | 13 | 有序列表（支持无限深度嵌套） |\n| `- [ ] 任务` | Todo | 17 | 任务列表 |\n| ` ```lang``` ` | Code | 14 | 代码块 |\n| ` ```mermaid``` ` | Board (Diagram) | 21 → 43 | 自动转画板 |\n| ` ```plantuml``` ` | Board (Diagram) | 21 → 43 | 自动转画板 |\n| ` ```svg``` ` | Board (Diagram) | 43 | 转为可编辑画板节点 |\n| `> 引用` | QuoteContainer | 34 | 引用容器 |\n| `> [!NOTE]` | Callout | 19 | 6 种类型（NOTE/WARNING/TIP/CAUTION/IMPORTANT/SUCCESS） |\n| `---` | Divider | 22 | 分割线 |\n| `\\| 表格 \\|` | Table | 31 | 大表格自动拆分 |\n| `![](url)` | Image | 27 | 图片（API 限制，创建占位块） |\n| `$$公式$$` | Equation | 16 | 块级公式（降级为行内） |\n| 附件 | File | 23 | 文件块 |\n| `