Skip to content
Back to search

feishu-cli

feishu-cli 是一个功能完整的飞书开放平台命令行工具。它将飞书文档、知识库、电子表格、消息、日历、任务等操作封装为简洁的命令行接口,核心能力是 Markdown ↔ 飞书文档双向无损转换。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/riba2534/feishu-cli with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/riba2534/feishu-cli'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/riba2534-feishu-cli/badge.svg)](/listings/riba2534-feishu-cli)

HTML

<a href="/listings/riba2534-feishu-cli"><img src="/api/listings/riba2534-feishu-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

**一键安装(推荐)**

自动检测平台,下载最新版本并安装到 `/usr/local/bin`:

curl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash

已安装的用户执行同样的命令即可更新到最新版本。

<details> <summary>其他安装方式</summary>

**手动下载**

从 [Releases](https://github.com/riba2534/feishu-cli/releases/latest) 页面下载对应平台的压缩包:

| 平台 | 文件 | |------|------| | Linux x64 | `feishu-cli_*_linux-amd64.tar.gz` | | Linux ARM64 | `feishu-cli_*_linux-arm64.tar.gz` | | macOS Intel | `feishu-cli_*_darwin-amd64.tar.gz` | | macOS Apple Silicon | `feishu-cli_*_darwin-arm64.tar.gz` | | Windows x64 | `feishu-cli_*_windows-amd64.tar.gz` |

tar -xzf feishu-cli_*_linux-amd64.tar.gz
sudo mv feishu-cli_*/feishu-cli /usr/local/bin/

**使用 go install**

go install github.com/riba2534/feishu-cli@latest

**从源码编译**

git clone https://github.com/riba2534/feishu-cli.git
cd feishu-cli && make build
# 二进制文件输出到 bin/feishu-cli

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,885 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="docs/logo-transparent.png" alt="feishu-cli Logo" width="140" />
  3. </p>
  4. <h1 align="center">feishu-cli</h1>
  5. <p align="center">
  6. <b>飞书开放平台命令行工具</b> — Markdown 与飞书文档双向转换,AI Agent 的飞书操控引擎
  7. </p>
  8. <p align="center">
  9. <a href="https://github.com/riba2534/feishu-cli/releases"><img src="https://img.shields.io/github/v/release/riba2534/feishu-cli?style=for-the-badge&color=00ADD8" alt="Release" /></a>
  10. <a href="https://go.dev/"><img src="https://img.shields.io/badge/Go-1.21+-00ADD8?style=for-the-badge&logo=go&logoColor=white" alt="Go" /></a>
  11. <a href="https://github.com/riba2534/feishu-cli/releases"><img src="https://img.shields.io/github/downloads/riba2534/feishu-cli/total?style=for-the-badge&color=2ea44f" alt="Downloads" /></a>
  12. <a href="https://goreportcard.com/report/github.com/riba2534/feishu-cli"><img src="https://goreportcard.com/badge/github.com/riba2534/feishu-cli?style=for-the-badge" alt="Go Report Card" /></a>
  13. <a href="https://github.com/riba2534/feishu-cli/stargazers"><img src="https://img.shields.io/github/stars/riba2534/feishu-cli?style=for-the-badge&color=f5a623" alt="Stars" /></a>
  14. <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-teal.svg?style=for-the-badge" alt="License" /></a>
  15. </p>
  16. <p align="center">
  17. <a href="#feishu-cli-是什么">介绍</a> · <a href="#三十秒上手">30 秒上手</a> · <a href="#核心能力">核心能力</a> · <a href="#快速开始">快速开始</a> · <a href="#命令参考">命令参考</a> · <a href="#ai-技能集成">AI 技能</a> · <a href="#faq">FAQ</a> · <a href="CHANGELOG.md">更新日志</a>
  18. </p>
  19. <p align="center">
  20. <img src="docs/demo.svg" alt="feishu-cli 演示:Markdown 一键导入为飞书文档" width="760" />
  21. </p>
  22. ---
  23. ## feishu-cli 是什么
  24. feishu-cli 是一个功能完整的飞书开放平台命令行工具。它将飞书文档、知识库、电子表格、消息、日历、任务等操作封装为简洁的命令行接口,**核心能力是 Markdown ↔ 飞书文档双向无损转换**。
  25. 除了传统的 CLI 用法,feishu-cli 还为 [Claude Code](https://claude.ai/claude-code) 等 AI 编程助手提供了 **9 个开箱即用的领域技能(Skill)**,让 AI Agent 能够直接创建文档、发送消息、管理权限——无需任何额外配置。
  26. > **注意**:feishu-cli 主要面向 AI Agent(如 Claude Code)使用,通过技能文件让 AI 直接操控飞书。虽然人类也可以直接使用命令行,但大多数场景下建议通过 AI Agent 调用,体验更佳。
  27. ### 为什么选择 feishu-cli
  28. - **双向转换零损耗** — 支持 40+ 种块类型,Markdown 导入飞书后再导出,内容完整保留
  29. - **图表原生渲染** — Mermaid(8 种图表类型)和 PlantUML 自动转换为飞书画板,不是截图,是可编辑的矢量图
  30. - **大规模文档处理** — 三阶段并发管道架构,实测 10,000+ 行 / 127 个图表 / 170+ 个表格一次导入
  31. - **P2P 私聊原生可读** — `msg history --user-email` 一条命令打通「搜用户 → 反查 p2p chat_id → 读消息」,输出自动带 `sender_names` 映射,AI Agent 直接拿结构化带名消息流,无需额外查群成员
  32. - **AI Agent 原生** — 9 个领域技能覆盖飞书全功能(503 个命令全部归属),AI 助手即装即用
  33. - **为脚本与 Agent 设计的健壮性** — 错拼命令/flag 报错并给拼写建议(绝不静默成功)、写操作 `--dry-run`、幂等键防重发、统一 `--jq`/`--format` 结构化输出
  34. - **一个工具覆盖全平台** — 文档、知识库、表格、多维表格、消息、邮箱、日历、任务、考勤、OKR、视频会议、妙记、云盘、权限、画板、Slides、事件、Schema、Profile、健康检查
  35. ## 三十秒上手
  36. ```bash
  37. # 1. 安装(自动识别平台,含 sha256 完整性校验)
  38. curl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash
  39. # 2. 一键创建飞书应用并保存凭证(Device Flow,免手工建应用)
  40. feishu-cli config create-app --save
  41. # 3. 把 Markdown 变成飞书文档
  42. feishu-cli doc import README.md --title "我的第一篇文档"
  43. ```
  44. 需要用户身份的能力(搜索、审批、邮箱等)再执行 `feishu-cli auth login` 完成 OAuth 授权即可。详见[快速开始](#快速开始)。
  45. ## 核心能力
  46. ### Markdown ↔ 飞书文档
  47. 将本地 Markdown 文件一键上传到飞书,或将飞书文档导出为 Markdown。支持完整语法转换:
  48. ```bash
  49. # 导入:Markdown → 飞书文档
  50. feishu-cli doc import report.md --title "技术报告" --verbose
  51. # 导出:飞书文档 → Markdown
  52. feishu-cli doc export <document_id> -o doc.md --download-images
  53. ```
  54. **支持的语法**:标题(6 级)、段落、列表(无限深度嵌套)、任务列表、代码块、引用、Callout(6 种类型)、同步块(含跨文档引用)、表格(自动拆分)、分割线、图片、链接、公式、粗体 / 斜体 / 删除线 / 下划线 / 行内代码(`<mark>` 高亮暂以下划线近似)。跨文档同步块无法读取时会保留带源标识的 WARNING 占位并输出诊断,不会静默导出为空。
  55. ### Mermaid / PlantUML 图表
  56. Markdown 中的 Mermaid 和 PlantUML 代码块**自动转换为飞书画板**(可编辑矢量图,非截图):
  57. ````markdown
  58. ```mermaid
  59. flowchart TD
  60. A[开始] --> B{判断}
  61. B -->|是| C[处理]
  62. B -->|否| D[结束]
  63. ```
  64. ````
  65. | 图表类型 | 声明 | 说明 |
  66. |---------|------|------|
  67. | 流程图 | `flowchart TD` / `flowchart LR` | 支持 subgraph |
  68. | 时序图 | `sequenceDiagram` | 参与者建议 ≤ 8 |
  69. | 类图 | `classDiagram` | |
  70. | 状态图 | `stateDiagram-v2` | 必须用 v2 |
  71. | ER 图 | `erDiagram` | |
  72. | 甘特图 | `gantt` | |
  73. | 饼图 | `pie` | |
  74. | 思维导图 | `mindmap` | |
  75. PlantUML 同样支持:时序图、活动图、类图、用例图、组件图、ER 图、思维导图等全部类型(` ```plantuml ` 或 ` ```puml `)。
  76. > 大规模实测导入成功率 **>90%**,失败图表自动降级为代码块并保留原文,不阻断整篇导入。
  77. ### 智能表格处理
  78. - **列宽自动计算** — 根据内容智能调整,中英文字符区分宽度(中文 14px,英文 8px)
  79. - **列宽自定义**(v1.29+,issue #156)— 支持紧邻表格上方注释 `<!-- feishu-colwidth: 80,200,*,30% -->`(单位 px / 百分比 / `*` 走 auto)或 CLI flag `--table-column-width=auto|fixed|N1,N2,...` 全局覆盖;注释优先级高于 flag。**仅 `doc import` / `doc add` 支持**——`doc content-update` 走官方原子更新协议不支持自定义列宽,传非 `auto` 的 flag 或内容含该注释都会报错
  80. - **大表格保持单表连贯** — 行数超过飞书 `create_block` 9 行限制时,先创建 9 行初始表,剩余行通过 `insert_table_row` API 追加到同一个 block,视觉上为一张连贯的表,不再拆成多张独立表格
  81. - **批量填充加速**(v1.29+,issue #159)— 单元格填充改用 `batch_update` API(每批 ≤30)+ 文档级 3 QPS 节流,典型 4×6×8 表场景从 ~70s 降到 ~3s
  82. - **单元格多块内容** — 支持 bullet / heading / text 混合内容
  83. ### 三阶段并发管道
  84. 导入大文档时,feishu-cli 使用三阶段并发管道最大化吞吐量:
  85. 1. **阶段一(顺序)** — 按文档顺序创建所有块,收集图表和表格任务
  86. 2. **阶段二(并发)** — 图表 worker 池 + 表格 worker 池并发处理
  87. 3. **阶段三(逆序)** — 处理失败图表,降级为代码块
  88. ```bash
  89. feishu-cli doc import large-doc.md --title "大文档" \
  90. --upload-images --diagram-workers 5 --table-workers 3 --image-workers 2 --verbose
  91. ```
  92. ### 全功能 API 覆盖
  93. <details>
  94. <summary><b>展开 20+ 模块能力总览表</b></summary>
  95. | 模块 | 能力 |
  96. |------|------|
  97. | **文档** | 创建(**带本地图片/附件/HTML 块/画板源文件**)、导入、导出、**大文档选择性读取(doc read:大纲/按标题取节/关键词定位,可转成直接发 IM 的 Markdown)**、编辑、批量更新、Callout、画板、**文档封面**、素材插入/下载/预览、**写作草稿与 DocxXML 预检(doc script)**、异步导出/导入文件 |
  98. | **思维笔记** | 读取已有思维笔记的节点、新增子节点或更新节点(mindnote nodes list/create) |
  99. | **知识库** | 空间列表、节点增删改查、导出(含整树递归镜像)、**移出知识库到云盘(move-to-drive)**、空间详情、成员管理 |
  100. | **电子表格** | V2 基础读写 + V3 富文本 API,行列操作、样式、批量样式、合并、查找替换、导出 XLSX/CSV、浮动图片读写、素材上传、单元格写图、筛选视图与筛选条件 CRUD、下拉菜单数据验证、**类型保真整表读写 table-get/table-put(数字/日期/布尔 dtype 保真,支持 get→改→put round-trip)** |
  101. | **多维表格** | base/v3 + bitable/v1 全覆盖:数据表/字段/记录 CRUD(含批量获取)、记录附件上传/下载/移除、视图配置(filter/sort/group/visible-fields/timebar/card)、仪表盘 CRUD 与智能排版、仪表盘块 CRUD、表单 CRUD 与分享详情/提交、表单问题 CRUD、角色 CRUD 与协作者管理、高级权限、数据聚合、工作流 CRUD、多维表格重命名与权限设置 |
  102. | **消息** | 发送与回复共用 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` 映射,覆盖退群成员) |
  103. | **群聊** | 创建、获取、更新、删除、分享链接、成员管理、**群列表(chat list,--page-all 全量拉取 + 安全截断告警)** |
  104. | **邮箱** | 收件箱分类/搜索、邮件详情(单条/批量/线程)、发送(默认草稿,支持 CID 内联图片自动扫描)、草稿管理(创建/编辑/**发送已有草稿**)、回复/全部回复/转发、**批量改 label/移动文件夹、批量软删进废纸篓**、邮件模板 create/list、邮箱签名查看(需 User Token) |
  105. | **日历** | 日历列表、主日历、日程增删改查、搜索、回复邀请、参与者管理、忙闲查询、日程视图(agenda)、智能时段建议、会议室查找、RSVP |
  106. | **任务** | 创建、查看、完成、重新打开、**服务端搜索(按创建者/执行者/关注者/完成态/截止时间)**、子任务、成员管理、提醒、评论、附件上传、我的任务、任务清单(CRUD + 任务关联 + 成员管理) |
  107. | **视频会议** | 多维搜索(query/主持人/参会者/会议室)、**聚合详情(vc detail:会议信息 + note_id + minute_token 一次拿齐,支持会议号反查)**、**智能纪要(vc note:详情 / 统一逐字稿导出)**、会议纪要(三路径批量获取 + AI 产物 + 逐字稿下载)、录制查询、会议机器人入会/离会/会议事件(`--as bot\|user\|auto`) |
  108. | **妙记** | 详情 + AI 产物、**关键词搜索、权限申请、等待转写就绪(--wait-ready)**、媒体批量下载 |
  109. | **审批** | 审批定义与实例详情查询、当前登录用户审批任务查询(待办 / 已办 / 已发起 / 抄送)、发起/撤回/抄送审批实例、通过/拒绝/转交审批任务 |
  110. | **考勤** | 查询用户打卡记录与日/月度考勤统计(tenant token,日期范围最长 31 天) |
  111. | **OKR** | 周期列表/**详情(目标 + 关键结果)**、进展记录 **CRUD**、**进展图片上传**、`--as bot|user|auto` 身份切换 |
  112. | **权限** | 添加 / 更新 / 删除协作者、批量添加、公开权限管理、分享密码、权限检查、转移所有权 |
  113. | **云盘增强** | 大文件分块上传(>20MB 自动分片)、**原地覆盖上传(--file-token)**、流式下载、异步导出(docx→markdown 快捷路径 + sheet/bitable CSV)、异步导入、文件夹移动(自动轮询)、富文本评论(wiki URL 解析)、异步任务查询、URL 解析 inspect、权限申请、本地镜像 pull/push/status、v2 搜索、**密级标签查询/设置** |
  114. | **原生 Markdown 文件** | Drive `.md` 文件 create/fetch/overwrite,整体保留 Markdown 源码,不转换为飞书 docx 块;本地比对远端最新与历史版本 |
  115. | **文件** | 云空间文件列表、创建、移动、复制、删除、上传、下载、版本管理(**含回滚到历史版本**)、元数据、统计 |
  116. | **素材** | 上传 / 下载(图片、文件、音视频) |
  117. | **画板** | 精排绘图(create-notes)、Mermaid / PlantUML 导入、**克隆(connector 重映射)、几何质检 lint、SVG 双向(svg-import / svg-export / export-code)、图片上传、覆盖更新(含快照)**、截图下载、节点管理 |
  118. | **Slides** | 创建空白演示文稿、上传媒体到演示文稿 |
  119. | **评论** | 列出、添加、解决/恢复评论、回复管理 |
  120. | **搜索** | 消息搜索(默认返回消息 ID,`--enrich` 补全内容/发送者/群名/时间)、应用搜索、文档搜索(需 User Access Token) |
  121. | **用户** | 获取用户信息、用户搜索、部门用户列表 |
  122. | **通讯录** | 部门详情、子部门列表 |
  123. | **实时事件** | WebSocket 长连接订阅应用事件(EventKey 列表/schema/consume/status/stop),**卡片按钮/表单回调(card.action.trigger)**、**审批 v4 事件(自动注册服务端订阅)**、**VC participant/note/recording 事件(User pre-consume,握手后 ready)**、Bot 菜单事件 |
  124. | **Raw API** | `api GET/POST/PUT/DELETE/PATCH <path>` 裸调任意未封装的 OpenAPI 接口,自动鉴权与错误码处理,支持 dry-run、自定义超时、jq 过滤与 json/pretty/table/ndjson/csv 多格式输出 |
  125. | **OpenAPI Schema** | 本地查询内置 OpenAPI service/resource/method、路径、参数和 scope,无需 token |
  126. | **Profile 多配置** | 多 App / 多账号配置 add/list/use/current/rename/remove/migrate;`profile list --json` 列出可操作 Bot;全局 `--profile` / `FEISHU_PROFILE` 单次切换目录与 User Token(`FEISHU_APP_ID/SECRET` 仍可覆盖 App 凭证) |
  127. | **健康检查** | `doctor` 一次检查配置、User Token、端点、代理和本地依赖 |
  128. </details>
  129. ## 快速开始
  130. ### 安装
  131. **一键安装(推荐)**
  132. 自动检测平台,下载最新版本并安装到 `/usr/local/bin`:
  133. ```bash
  134. curl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash
  135. ```
  136. 已安装的用户执行同样的命令即可更新到最新版本。
  137. <details>
  138. <summary>其他安装方式</summary>
  139. **手动下载**
  140. 从 [Releases](https://github.com/riba2534/feishu-cli/releases/latest) 页面下载对应平台的压缩包:
  141. | 平台 | 文件 |
  142. |------|------|
  143. | Linux x64 | `feishu-cli_*_linux-amd64.tar.gz` |
  144. | Linux ARM64 | `feishu-cli_*_linux-arm64.tar.gz` |
  145. | macOS Intel | `feishu-cli_*_darwin-amd64.tar.gz` |
  146. | macOS Apple Silicon | `feishu-cli_*_darwin-arm64.tar.gz` |
  147. | Windows x64 | `feishu-cli_*_windows-amd64.tar.gz` |
  148. ```bash
  149. tar -xzf feishu-cli_*_linux-amd64.tar.gz
  150. sudo mv feishu-cli_*/feishu-cli /usr/local/bin/
  151. ```
  152. **使用 go install**
  153. ```bash
  154. go install github.com/riba2534/feishu-cli@latest
  155. ```
  156. **从源码编译**
  157. ```bash
  158. git clone https://github.com/riba2534/feishu-cli.git
  159. cd feishu-cli && make build
  160. # 二进制文件输出到 bin/feishu-cli
  161. ```
  162. </details>
  163. ### 配置凭证
  164. **一键创建应用(推荐)**
  165. 无需手动访问飞书开放平台后台,一条命令自动完成应用注册:
  166. ```bash
  167. # 自动创建飞书应用并保存凭证到 ~/.feishu-cli/config.yaml
  168. feishu-cli config create-app --save
  169. ```
  170. 执行后终端会输出一个授权链接,用飞书扫码确认即可。CLI 自动获取 App ID 和 App Secret 并写入配置文件,后续命令直接可用。
  171. 然后在飞书开放平台的**应用权限管理**页面为新创建的应用开通所需 scope。最快的方式是复制 [权限要求](#权限要求) 章节的 JSON,在权限管理页面的 **导入权限** 入口粘贴即可一次性申请全部。
  172. <details>
  173. <summary>手动配置(不推荐)</summary>
  174. 如果你有特殊需求(如企业应用、自定义应用类型),也可以手动配置:
  175. 1. 在 [飞书开放平台](https://open.feishu.cn/app) 创建应用,获取 App ID 和 App Secret
  176. 2. 给应用添加所需权限(参见[权限要求](#权限要求))
  177. 3. 配置凭证(二选一):
  178. ```bash
  179. # 方式一:环境变量
  180. export FEISHU_APP_ID="cli_xxx"
  181. export FEISHU_APP_SECRET="xxx"
  182. # 方式二:配置文件
  183. feishu-cli config init # 生成模板后手动编辑填入凭证
  184. ```
  185. </details>
  186. (可选)如果需要使用搜索、审批任务查询等需要用户身份的功能,还需完成 OAuth 用户授权:
  187. ```bash
  188. feishu-cli auth login
  189. ```
  190. ### 验证安装
  191. ```bash
  192. feishu-cli doc create --title "Hello Feishu"
  193. ```
  194. 如果返回文档 ID,说明配置成功。
  195. ## 命令参考
  196. ```
  197. feishu-cli <command> [subcommand] [flags]
  198. Commands:
  199. doc 文档操作(创建、导入、导出、文本级/块级编辑、docs_ai 读取与创建、历史版本、异步导出/导入文件)
  200. wiki 知识库操作(节点增删改查、空间详情、成员管理)
  201. sheet 电子表格(读写、子表名寻址、样式、行列结构/冻结/隐藏、V3 富文本 API、table-get/put、导出 XLSX/CSV、image、filter、dropdown、条件格式、--as)
  202. bitable 多维表格(base/v3 + bitable/v1:数据表/字段/记录/附件/视图/仪表盘/表单/角色/权限/聚合/工作流/字段 AI 扩展/按钮绑定/表复制/模板中心/顶层块,110 命令)
  203. msg 消息操作(发送、转发(含话题)、合并转发、回复、Pin、表情回复、书签、批量获取、已读状态、资源下载)
  204. chat 群聊管理(创建、更新、删除、群列表、成员管理)
  205. mail 邮箱操作(分类/搜索、发送与定时发送、草稿含发送、回复、转发、分享到会话、已读回执、批量改 label/软删、CID 内联图片、模板、签名)
  206. drive 云盘增强(分块/原地覆盖上传、流式断点续传下载、异步导出/导入、移动、重命名、版本、评论、镜像 pull/push/status 与差集预览、时间窗搜索、预览产物与封面、密级标签)
  207. markdown Drive 原生 Markdown 文件 CRUD(.md 整体读写、版本比对,不转换 docx 块)
  208. vc 视频会议(多维搜索、聚合详情、智能纪要 note、会议纪要、录制查询、机器人入会/离会/事件、会中倒计时/消息/截图/邀请/结束)
  209. minutes 妙记操作(详情 + AI 产物、搜索、权限申请、媒体批量下载、上传生成、改标题/摘要/待办、说话人与词替换)
  210. apps 妙搭(Miaoda)应用(创建、发布 HTML 或按分支发布并等待构建结果、发布记录、修改(含图标)、删除、功能开关、访问范围管理)
  211. file 文件管理(列出、移动、复制、删除、上传、下载、版本管理)
  212. media 素材操作(上传、下载)
  213. perm 权限管理(添加、删除、批量添加、公开权限、密码、转移所有权)
  214. calendar 日历操作(日程增删改查、搜索、参与者、忙闲查询、agenda、suggestion、room-find、rsvp)
  215. task 任务操作(增删改查、服务端搜索、子任务、成员、提醒、评论、附件、我的任务)
  216. tasklist 任务清单管理(CRUD、任务关联、成员管理)
  217. attendance 考勤操作(打卡记录查询、统计数据查询)
  218. okr OKR 操作(周期列表/详情、目标批量创建、权重/排序/指标、进展记录 CRUD、评论、进展图片上传、--as 身份)
  219. slides Slides 演示文稿(创建带页面、加页/删页/替换、按页读取 XML、截图、媒体上传、历史版本与回滚)
  220. user 用户操作(获取信息、搜索、部门用户列表)
  221. dept 部门操作(详情、子部门列表)
  222. board 画板操作(精排绘图、图表导入、克隆、几何质检 lint、SVG 双向、图片上传、覆盖更新)
  223. comment 评论操作(列出含正文与分页、批量获取、添加、解决/恢复、回复编辑与表情)
  224. approval 审批操作(定义/实例详情、已发起列表、任务查询、实例创建/撤回/抄送、任务通过/拒绝/转交;全部 User Token)
  225. search 搜索操作(消息、应用、文档)
  226. event 实时事件订阅(WebSocket 长连接、list/schema/consume/status/stop、--param/--as/--dry-run)
  227. schema 本地浏览飞书 OpenAPI 方法(无需 token)
  228. api 通用 OpenAPI 透传调用(任意 method/path,自动鉴权 + 错误码翻译,覆盖 2500+ 端点)
  229. profile 多 App / 多账号配置切换
  230. doctor 环境健康检查(config/user_token/endpoints/proxy/deps/catalog/skills 等)
  231. auth 身份认证(OAuth 登录、状态、退出、scope 预检)
  232. config 配置管理
  233. skills 内嵌 AI 技能(list/read/install,与 CLI 版本严格配套)
  234. update 检查并安装最新版本(sha256 校验后原子替换)
  235. ```
  236. **通用约定**:
  237. - 全局 `--yes` 跳过删除类操作的确认;非交互环境(stdin 不是终端)执行这类操作时必须显式带上,否则以退出码 10 退出且不执行。
  238. - 退出码:0 成功 / 1 一般错误 / 2 用法错误 / 3 鉴权或权限 / 4 网络 / 10 需要确认 / 130 中断。参数在读取凭据之前校验,参数写错时无论是否登录都返回 2。
  239. - 写命令的 `--dry-run` 只做本地预览,不联网、不需要凭据(`board clone`、`drive push/pull` 等需要读取远端才能算出计划的命令除外,见其 `--help`)。
  240. - 全局 `--error-format json`:错误以一行 JSON 信封输出到 stderr(`{"error":{"message","exit_code","kind","code","log_id","missing_scopes","retryable","hint"}}`),便于脚本与 AI Agent 解析;默认 text 输出不变。
  241. - 接受 token 的参数大多也接受飞书链接(docx/sheets/base/slides/wiki 等,wiki 链接自动解析到底层文档)。
  242. <details>
  243. <summary>文档操作</summary>
  244. ```bash
  245. # 创建文档
  246. feishu-cli doc create --title "新文档"
  247. # 导入 Markdown(核心功能,默认上传图片)
  248. feishu-cli doc import doc.md --title "文档标题" --upload-images --verbose
  249. # 导出为 Markdown
  250. feishu-cli doc export <doc_id> -o output.md --download-images
  251. # 大文档选择性读取(大纲 / 按标题取节 / 关键词定位)
  252. feishu-cli doc read <doc_id> --outline
  253. feishu-cli doc read <doc_id> --heading "性能优化"
  254. feishu-cli doc read <doc_id> --keyword "QPS|限流" --context 5
  255. # 导出他人文档(自动从 auth login 读取 User Token,或手动指定)
  256. feishu-cli doc export <doc_id> -o output.md --user-access-token <token>
  257. # 获取文档信息
  258. feishu-cli doc get <doc_id>
  259. # 获取所有块
  260. feishu-cli doc blocks <doc_id> --all
  261. # 添加内容(JSON 格式)
  262. feishu-cli doc add <doc_id> -c '<JSON>'
  263. # 添加内容(Markdown 格式)
  264. feishu-cli doc add <doc_id> README.md --content-type markdown
  265. # 原子更新(docs_ai):纯文本选择器为文本级替换,段落其余内容与样式保留
  266. feishu-cli doc content-update <doc_id> --mode replace_all --selection-with-ellipsis "旧文本" --markdown "新文本"
  267. # 按 block id 精确更新(block id 由 doc read --engine docs_ai --with-ids 获得)
  268. feishu-cli doc read <doc_id> --engine docs_ai --with-ids --scope keyword --keyword "性能"
  269. feishu-cli doc content-update <doc_id> --mode block_replace --block-id <block_id> --markdown "新段落"
  270. # 历史版本
  271. feishu-cli doc history list <doc_id>
  272. # 带内容建文档:内容里的本地资源在建文档后自动上传绑定(<img href="https://..."> 由服务端下载)
  273. feishu-cli doc create --doc-format xml --content-file draft.xml --dry-run # 先预览请求与上传计划
  274. feishu-cli doc create --doc-format xml --content-file draft.xml # draft.xml 可含 <img path="@./a.png"/>、<source path="@./f.pdf"/>、
  275. # <whiteboard type="mermaid" path="@./x.mmd"/>、<html5-block path="@./w.html"/>
  276. # 转成可直接发到 IM 的 Markdown
  277. feishu-cli doc read <doc_id> --doc-format im-markdown --lang en-US
  278. # 文档封面
  279. feishu-cli doc resource update <doc_id> --type cover --file cover.png --offset-ratio-y -0.2
  280. feishu-cli doc resource download <doc_id> --type cover -o ./cover
  281. feishu-cli doc resource delete <doc_id> --type cover
  282. # 写作草稿:初始化工作区 → 写 DocxXML → 解析预检(字数、块分布、资源)
  283. feishu-cli doc script --command init-draft --presentation-decision '{}'
  284. feishu-cli doc script --command parse --content @draft_xxxxxxxx_folder/draft.xml
  285. # 思维笔记节点(需要应用开通 mindnote:node:read / mindnote:node:create)
  286. feishu-cli mindnote nodes list <mindnote_token_or_url>
  287. feishu-cli mindnote nodes create <mindnote_token_or_url> --data @nodes.json --dry-run
  288. # 添加高亮块
  289. feishu-cli doc add-callout <doc_id> "提示内容" --callout-type info
  290. # 批量更新
  291. feishu-cli doc batch-update <doc_id> '[...]' --source-type content
  292. # 异步导出为文件(PDF/DOCX/XLSX)
  293. feishu-cli doc export-file <doc_token> --type pdf -o output.pdf
  294. # 异步导入本地文件为飞书文档
  295. feishu-cli doc import-file local_file.docx --type docx --name "文档名"
  296. ```
  297. </details>
  298. <details>
  299. <summary>知识库操作</summary>
  300. ```bash
  301. feishu-cli wiki spaces # 列出知识空间
  302. feishu-cli wiki get <node_token> # 获取节点
  303. feishu-cli wiki nodes <space_id> # 列出节点
  304. feishu-cli wiki export <node_token> -o doc.md # 导出为 Markdown
  305. feishu-cli wiki export-tree <node_token> -o ./backup # 递归导出知识库子树
  306. feishu-cli wiki create --space-id <id> --title "新节点"
  307. feishu-cli wiki create --space-id <id> --title "快捷方式" --node-type shortcut --origin-node-token <token>
  308. feishu-cli wiki delete <node_token> # 删除节点(官方 API,支持异步任务自动轮询)
  309. feishu-cli wiki move-docs <obj_token> --space-id <id> # 移动云空间文档至知识空间
  310. feishu-cli wiki move-to-drive --node-token wikcnXXX --folder-token fldcnYYY # 反向:移出知识库到云盘
  311. feishu-cli wiki space-get <space_id> # 获取知识空间详情
  312. feishu-cli wiki space-create --name "新知识库" # 创建知识库(v1.29+)
  313. feishu-cli wiki space-list --page-all -o json # 列出所有可见知识库(v1.29+)
  314. feishu-cli wiki node-copy --space-id <src> --node-token <node> --target-space-id <dst> # 复制节点(v1.29+)
  315. feishu-cli wiki delete-space <space_id> --yes # 删除整个知识空间(异步任务自动轮询)
  316. # 知识空间成员管理
  317. feishu-cli wiki member add <space_id> --member-type userid --member-id USER_ID --role admin
  318. feishu-cli wiki member list <space_id>
  319. feishu-cli wiki member remove <space_id> --member-type userid --member-id USER_ID --role admin
  320. ```
  321. </details>
  322. <details>
  323. <summary>电子表格操作</summary>
  324. ```bash
  325. # V2 API - 基础读写
  326. feishu-cli sheet read <token> "Sheet1!A1:C10"
  327. feishu-cli sheet write <token> "Sheet1!A1:B2" --data '[["姓名","年龄"],["张三",25]]'
  328. # V3 API - 富文本支持
  329. feishu-cli sheet read-rich <token> <sheet_id> "sheet!A1:C10"
  330. # 类型保真整表读写(DataFrame 形状,数字/日期/布尔 dtype 保真,支持 get→改→put round-trip)
  331. feishu-cli sheet table-get <token> <sheet_id> [--range A1:D50]
  332. feishu-cli sheet table-put <token> <sheet_id> --sheets-file table.json
  333. feishu-cli sheet write-rich <token> <sheet_id> --data-file data.json
  334. # 行列操作(--start 从 0 开始、--end 不含;或用 --range "3:5"/"B:D",1 起始两端包含)
  335. feishu-cli sheet add-rows <token> <sheet_id> --count 5
  336. feishu-cli sheet add-cols <token> <sheet_id> --count 3
  337. feishu-cli sheet delete-rows <token> <sheet_id> --range "3:5" --dry-run
  338. feishu-cli sheet freeze <token> <sheet_id> --rows 1 --cols 1
  339. feishu-cli sheet update-dimension <token> <sheet_id> --range "B:D" --hidden
  340. # 身份:默认 User 优先、Tenant 兜底;--as bot 强制以应用身份访问应用自己的表格
  341. feishu-cli sheet list-sheets <token> --as bot
  342. # 样式与合并
  343. feishu-cli sheet style <token> "Sheet1!A1:C3" --bold --font-size 14
  344. feishu-cli sheet merge <token> "Sheet1!A1:C1"
  345. # 条件格式(delete 带确认门禁)
  346. feishu-cli sheet cond-format list <token> <sheet_id>
  347. feishu-cli sheet cond-format create <token> <sheet_id> --range C2:C100 --rule-type cellIs \
  348. --operator between --formula 1 --formula 10 --back-color "#d9f5d6" --dry-run
  349. feishu-cli sheet cond-format delete <token> <sheet_id> <cf_id> --yes
  350. ```
  351. </details>
  352. <details>
  353. <summary>消息操作</summary>
  354. ```bash
  355. # 发送文本消息
  356. feishu-cli msg send --receive-id-type email --receive-id user@example.com --text "Hello"
  357. feishu-cli msg send --receive-id-type email --receive-id user@example.com --text "对账" --idempotency-key "bill-001" # 幂等防重发(≤50 字符)
  358. # 发送富文本消息
  359. feishu-cli msg send --receive-id-type email --receive-id user@example.com \
  360. --msg-type post --content-file msg.json
  361. # 搜索群聊(Bot 身份,仅返回 Bot 所在的群)
  362. feishu-cli msg search-chats --query "关键词"
  363. # 搜索群聊(User 身份,可搜到用户所在的群)
  364. feishu-cli msg search-chats --query "关键词" --user-access-token <token>
  365. # 获取群聊历史消息(已 auth login 时自动用 User Token;未登录回落 Bot Token,要求 Bot 在群里)
  366. feishu-cli msg history --container-id <chat_id> --container-id-type chat
  367. # 获取和某人的私聊记录(邮箱入口,自动搜用户 + 反查 p2p chat_id)
  368. feishu-cli msg history --user-email user@example.com --page-size 50 -o json
  369. # 已知 open_id 时直接传
  370. feishu-cli msg history --user-id ou_xxx --page-size 50 -o json
  371. # 输出 JSON 自动携带顶层 sender_names 映射(open_id → 姓名),AI Agent 可直接引用
  372. # {"items":[...], "sender_names":{"ou_abc":"张三","ou_def":"李四"}}
  373. # 转发消息
  374. feishu-cli msg forward <message_id> --receive-id <id> --receive-id-type email
  375. # 回复消息
  376. feishu-cli msg reply <message_id> --text "回复内容"
  377. feishu-cli msg reply <message_id> --image /path/to/photo.png --idempotency-key "photo-reply-001"
  378. # 回复到既有话题:传话题内 om_xxx 消息 ID,不要把 omt_xxx 传给 msg send
  379. feishu-cli msg reply om_xxx --file /path/to/report.pdf
  380. # 合并转发
  381. feishu-cli msg merge-forward --receive-id user@example.com --receive-id-type email --message-ids id1,id2
  382. # 消息加急
  383. feishu-cli msg urgent <message_id> --user-id-type open_id --user-ids ou_xxx,ou_yyy
  384. feishu-cli msg urgent <message_id> --urgent-type phone --user-id-type user_id --user-ids u_123,u_456
  385. feishu-cli msg urgent <message_id> --urgent-type sms --user-id-type union_id --user-ids on_xxx,on_yyy
  386. # 表情回复
  387. feishu-cli msg reaction add <message_id> --emoji-type THUMBSUP
  388. feishu-cli msg reaction remove <message_id> --reaction-id REACTION_ID
  389. feishu-cli msg reaction list <message_id>
  390. # Pin 消息
  391. feishu-cli msg pin <message_id>
  392. feishu-cli msg unpin <message_id>
  393. feishu-cli msg pins --chat-id CHAT_ID
  394. # 本人对消息的已读状态(仅 User,1–50 个)
  395. feishu-cli msg read-status om_xxx om_yyy -o json
  396. # 紧凑 Markdown 视图(与 -o json 互斥)
  397. feishu-cli msg history --container-id oc_xxx --concise
  398. feishu-cli msg thread-messages omt_xxx --concise
  399. # 转发整个话题
  400. feishu-cli msg forward omt_xxx --receive-id oc_xxx --receive-id-type chat_id --dry-run
  401. ```
  402. </details>
  403. <details>
  404. <summary>权限管理</summary>
  405. ```bash
  406. # 添加 / 更新协作者
  407. feishu-cli perm add <doc_id> --doc-type docx --member-type email \
  408. --member-id user@example.com --perm full_access --notification
  409. feishu-cli perm update <doc_id> --doc-type docx --member-type email \
  410. --member-id user@example.com --perm edit
  411. # 查看 / 删除协作者
  412. feishu-cli perm list <doc_token> --doc-type docx
  413. feishu-cli perm delete <doc_token> --doc-type docx --member-type email --member-id user@example.com
  414. # 公开权限管理
  415. feishu-cli perm public-get <doc_token>
  416. feishu-cli perm public-update <doc_token> --external-access --link-share-entity anyone_readable
  417. # 分享密码
  418. feishu-cli perm password create <doc_token>
  419. feishu-cli perm password delete <doc_token>
  420. # 批量添加协作者
  421. feishu-cli perm batch-add <doc_token> --members-file members.json --notification
  422. # 权限检查
  423. feishu-cli perm auth <doc_token> --action view
  424. # 转移所有权
  425. feishu-cli perm transfer-owner <doc_token> --member-type email --member-id user@example.com
  426. # 直接传文档链接;知识空间成员组
  427. feishu-cli perm list https://example.feishu.cn/wiki/wikcnxxx
  428. feishu-cli perm add <doc_token> --member-type wikispaceid --member-id <space_id> \
  429. --member-kind wiki_space_viewer --perm view --dry-run
  430. ```
  431. </details>
  432. <details>
  433. <summary>群聊管理</summary>
  434. ```bash
  435. # 群聊 CRUD
  436. feishu-cli chat create --name "群聊名" --user-ids id1,id2
  437. feishu-cli chat get <chat_id>
  438. feishu-cli chat update <chat_id> --name "新群名"
  439. feishu-cli chat delete <chat_id>
  440. feishu-cli chat link <chat_id>
  441. # 群成员管理
  442. feishu-cli chat member list <chat_id>
  443. feishu-cli chat list --page-all # 列出当前身份加入的全部群
  444. feishu-cli chat member list <chat_id> --page-all # 全量成员(安全截断时告警)
  445. feishu-cli chat member add <chat_id> --id-list id1,id2
  446. feishu-cli chat member remove <chat_id> --id-list id1,id2
  447. ```
  448. </details>
  449. <details>
  450. <summary>文件管理</summary>
  451. ```bash
  452. # 基础操作
  453. feishu-cli file list [folder_token]
  454. feishu-cli file mkdir "新文件夹" --parent <folder_token>
  455. # 上传 / 下载
  456. feishu-cli file upload local_file.pdf --parent FOLDER_TOKEN
  457. feishu-cli file download <file_token> -o output.pdf
  458. feishu-cli file download <file_token> -o large.zip --user-access-token u-xxx --timeout 30m # 大文件自动 Range 分片兜底
  459. # 版本管理
  460. feishu-cli file version list <doc_token> --doc-type docx
  461. feishu-cli file version revert <file_token> <version> # 回滚到历史版本
  462. feishu-cli file version create <doc_token> --doc-type docx --name "v1.0"
  463. feishu-cli file version get <doc_token> <version_id> --doc-type docx
  464. feishu-cli file version delete <doc_token> <version_id> --doc-type docx
  465. # 元数据与统计
  466. feishu-cli file meta TOKEN1 TOKEN2 --doc-type docx
  467. feishu-cli file stats <file_token> --doc-type docx
  468. ```
  469. </details>
  470. <details>
  471. <summary>搜索操作</summary>
  472. 搜索 API 需要 User Access Token。推荐使用 `auth login` 一键获取(Token 自动保存和刷新),也可通过 `--user-access-token` 参数或环境变量手动指定。
  473. ```bash
  474. # 获取 User Access Token(推荐,一次登录自动刷新)
  475. feishu-cli auth login
  476. # 搜索消息(默认返回消息 ID,-o json 输出 {MessageIDs,HasMore,PageToken})
  477. feishu-cli search messages "关键词"
  478. feishu-cli search messages "会议" --chat-ids oc_xxx,oc_yyy
  479. feishu-cli search messages "你好" --chat-type p2p_chat # 搜索私聊消息
  480. feishu-cli search messages "会议" --enrich # 补全内容/发送者/群名/时间
  481. # 搜索应用
  482. feishu-cli search apps "审批"
  483. # 搜索文档和 Wiki
  484. feishu-cli search docs "产品需求"
  485. feishu-cli search docs "季度报告" --docs-types doc,sheet
  486. feishu-cli search docs "技术方案" --count 10
  487. feishu-cli search docs "技术方案" --count 10 --page-token <上一页输出的 page_token> # 翻页(--offset 已不支持)
  488. # 也可以手动指定 Token
  489. feishu-cli search docs "产品需求" --user-access-token <token>
  490. export FEISHU_USER_ACCESS_TOKEN="u-xxx"
  491. feishu-cli search docs "产品需求"
  492. ```
  493. </details>
  494. <details>
  495. <summary>审批操作</summary>
  496. 全部当前审批 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`。
  497. 输出说明:
  498. - 不传 `--output`:输出便于阅读的文本摘要
  499. - `--output json`:输出 CLI 归一化后的 JSON,部分字段会做拍平和字符串化处理
  500. - `--output raw-json`:输出飞书 API 原始**成功**响应;HTTP 200 但业务 `code != 0` 时非零退出
  501. ```bash
  502. # 查询审批定义详情(User Token)
  503. feishu-cli approval get <approval_code>
  504. # 输出完整 JSON
  505. feishu-cli approval get <approval_code> --output json
  506. # 输出飞书 API 原始响应
  507. feishu-cli approval get <approval_code> --output raw-json
  508. # 查询审批实例详情(User Token)
  509. feishu-cli approval instance get --instance-code <instance_code>
  510. feishu-cli approval instances get --instance-code <instance_code> --output raw-json
  511. # 查询我发起的审批实例
  512. feishu-cli approval instance initiated
  513. feishu-cli approval instance initiated --output json
  514. # 查询当前登录用户的待我审批
  515. feishu-cli approval task query --topic todo
  516. # 查询我已审批的任务
  517. feishu-cli approval task query --topic done
  518. # 查询抄送给我的(未读 / 已读)
  519. feishu-cli approval task query --topic cc-unread --output json
  520. feishu-cli approval task query --topic cc-read
  521. # 输出飞书 API 原始响应
  522. feishu-cli approval task query --topic todo --output raw-json
  523. # 注:--topic 仅接受 todo / done / cc-unread / cc-read(服务端 options 为 1/2/17/18)。
  524. # started(topic=3)已被官方下线,查「我发起的」请用上面的 approval instance initiated
  525. # 翻页查询
  526. feishu-cli approval task query --topic todo --page-size 20 --page-token <token>
  527. # 显式指定 User Access Token
  528. feishu-cli approval task query --topic cc-unread --user-access-token <token>
  529. # 发起审批实例(身份取当前 User Token;form.json 为飞书审批表单 JSON 数组)
  530. feishu-cli approval instance create --approval-code <code> --form-file form.json
  531. # 撤回 / 抄送审批实例
  532. feishu-cli approval instance cancel --instance-code <instance_code>
  533. feishu-cli approval instance cc --instance-code <instance_code> --cc-user-ids ou_a,ou_b
  534. # 通过 / 拒绝审批任务
  535. feishu-cli approval task approve --instance-code <instance_code> --task-id <task_id> --comment "同意"
  536. feishu-cli approval task reject --instance-code <instance_code> --task-id <task_id> --comment "信息不完整"
  537. # 转交审批任务(User Token)
  538. feishu-cli approval task transfer --instance-code <instance_code> --task-id <task_id> --transfer-user-id ou_target --comment "请代审"
  539. ```
  540. </details>
  541. <details>
  542. <summary>身份认证(Device Flow)</summary>
  543. 通过 **OAuth 2.0 Device Flow(RFC 8628)** 获取 User Access Token,用于搜索、审批待办查询等需要用户授权的功能。**无需在飞书开放平台配置任何重定向 URL 白名单**。
  544. > **v1.18+ 变更**:Authorization Code Flow(`--print-url` / `auth callback` / `--manual` / `--port` / `--method` / `--scopes`)已全部删除,只保留 Device Flow。
  545. ```bash
  546. # 按业务域申请推荐权限(推荐)
  547. feishu-cli auth login --domain search --recommend
  548. # 显式申请某组 scope
  549. feishu-cli auth login --scope "minutes:minutes.basic:read minutes:minutes.transcript:export"
  550. # JSON 事件流输出(AI Agent 推荐,配合 run_in_background 使用)
  551. feishu-cli auth login --domain search --recommend --json
  552. # 两步模式:先立即输出 device_code,不启动轮询
  553. feishu-cli auth login --domain vc --domain minutes --recommend --no-wait --json
  554. # 两步模式:用已有 device_code 继续轮询
  555. feishu-cli auth login --device-code <device_code> --json
  556. # 预检 token 是否包含所需 scope(AI Agent 推荐在执行业务命令前调用)
  557. feishu-cli auth check --scope "search:docs:read"
  558. feishu-cli auth check --scope "search:docs:read im:message:readonly"
  559. # 查看当前授权状态
  560. feishu-cli auth status
  561. feishu-cli auth status -o json # JSON 格式输出
  562. # 退出登录(清除本地 token)
  563. feishu-cli auth logout
  564. ```
  565. 登录时 CLI 在 stderr 打印验证链接和 user_code,用户在任意设备(电脑、手机)浏览器打开链接完成授权即可。本地桌面会尝试自动打开浏览器,SSH 远程失败静默忽略。
  566. **授权范围策略**:
  567. - CLI 会显式声明本次请求的 scope,不再依赖“后台开了什么就全量返回”
  568. - 推荐先用 `auth check --scope "REQ_SCOPES"` 预检,再用 `auth login --scope "..."` 或 `auth login --domain ... --recommend` 补授权
  569. - 即使显式请求业务 scope,CLI 也会自动追加最小核心 scope(如 `auth:user.id:read`)用于识别当前登录用户
  570. - 要真正拿到某个 scope,仍然必须先在飞书开放平台应用权限管理页面开通它
  571. **Token 管理**:
  572. - Token 保存在 `~/.feishu-cli/token.json`(0600,原子写入),Access Token 有效期约 2 小时
  573. - Access Token 过期时自动使用 Refresh Token 刷新(跨进程锁,避免两个进程消耗同一 refresh token)
  574. - 新登录写入的 `token.json` 带 `app_id` 绑定;与当前 App 不一致或旧文件未绑定时,**一律拒绝使用**(即使 access 仍有效)。迁移:`feishu-cli auth token --bind-legacy-app --as user`(不更换 token;不可与 `--as bot` / `--user-access-token` 同时用)或重新 `auth login`
  575. - `auth token --as bot` 走官方 Accounts OAuth v3 `client_credentials`;不可与 `--user-access-token` 同时使用
  576. - `offline_access` 由 CLI 自动追加,无需手动声明
  577. - Token 优先级:`--user-access-token` 参数 > `FEISHU_USER_ACCESS_TOKEN` 环境变量 > `token.json` > `config.yaml`
  578. - 审批任务查询会缓存当前登录用户资料到 `~/.feishu-cli/user_profile.json`,登录态变化或执行 `auth logout` 时会自动清理
  579. - `base_url` 默认仅官方 HTTPS。自定义远端 / 明文 HTTP / 带 body 跨源重定向需显式 opt-in(`FEISHU_ALLOW_CUSTOM_BASE_URL`、`FEISHU_ALLOW_INSECURE_HTTP`、`FEISHU_ALLOW_CROSS_ORIGIN_REDIRECT`)
  580. </details>
  581. <details>
  582. <summary>更多命令</summary>
  583. ```bash
  584. # 文档异步导出/导入
  585. feishu-cli doc export-file <doc_token> --type pdf -o output.pdf
  586. feishu-cli doc import-file local_file.docx --type docx --name "文档名"
  587. # 素材上传
  588. feishu-cli media upload image.png --parent-type docx_image --parent-node <doc_id>
  589. # 日历
  590. feishu-cli calendar list
  591. feishu-cli calendar get <calendar_id>
  592. feishu-cli calendar primary
  593. feishu-cli calendar create-event --calendar-id <id> --summary "会议" \
  594. --start "2024-01-01T10:00:00+08:00" --end "2024-01-01T11:00:00+08:00"
  595. feishu-cli calendar event-search --calendar-id <id> --query "关键词"
  596. feishu-cli calendar event-reply <calendar_id> <event_id> --status accept
  597. feishu-cli calendar attendee add <calendar_id> <event_id> --user-ids id1,id2
  598. feishu-cli calendar attendee list <calendar_id> <event_id>
  599. feishu-cli calendar freebusy --start "2024-01-01T00:00:00+08:00" \
  600. --end "2024-01-02T00:00:00+08:00" --user-ids id1,id2
  601. # 任务
  602. feishu-cli task create --summary "待办事项"
  603. feishu-cli task complete <task_id>
  604. feishu-cli task subtask create <task_guid> --summary "子任务"
  605. feishu-cli task subtask list <task_guid>
  606. feishu-cli task member add <task_guid> --members id1,id2 --role assignee
  607. feishu-cli task reminder add <task_guid> --minutes 30
  608. feishu-cli task upload-attachment --task-guid <task_guid> --file ./report.pdf
  609. # 任务列表
  610. feishu-cli tasklist create --name "任务列表"
  611. feishu-cli tasklist list
  612. feishu-cli tasklist get <tasklist_guid>
  613. feishu-cli tasklist delete <tasklist_guid>
  614. # 画板(v1.25+ 新增 5 个子命令 + Mermaid 本地引擎 + Markdown ```svg fence 自动识别)
  615. feishu-cli board create-notes <whiteboard_id> nodes.json -o json # 精排绘图(JSON 控制坐标、颜色、连线)
  616. feishu-cli board import <whiteboard_id> "graph TD; A-->B" --source-type content --syntax mermaid --diagram-type flowchart # 服务端渲染
  617. feishu-cli board import <whiteboard_id> diagram.mmd --syntax mermaid --engine local # 本地引擎(whiteboard-cli 翻译,每个节点可单独编辑)
  618. feishu-cli board import <whiteboard_id> diagram.puml --syntax plantuml # 导入 PlantUML
  619. feishu-cli board svg-import <whiteboard_id> drawing.svg # 单 svg 节点装饰(图标/印章 < 2KB)
  620. feishu-cli board svg-export <whiteboard_id> -o board.svg # 服务端 SVG 导出
  621. feishu-cli board clone <source_id> <target_id> --batch-size 10 # 克隆画板(含 connector ID 重映射 + 分批节流)
  622. feishu-cli board upload-image <whiteboard_id> photo.png # 上传本地图片为 image 节点(自动推断像素尺寸)
  623. feishu-cli board lint <whiteboard_id> # 几何质检(重叠/字号一致性/容量/综合评分)
  624. feishu-cli board export-code <whiteboard_id> --merge --output-path design.svg # 反向导出 SVG(按 z_index 排序)
  625. feishu-cli board update <whiteboard_id> nodes.json --overwrite --snapshot old.json # 覆盖更新+快照备份
  626. feishu-cli board nodes <whiteboard_id> # 获取画板所有节点
  627. feishu-cli board image <whiteboard_id> output # 下载画板截图(自动按实际格式补扩展名,通常 JPEG)
  628. feishu-cli board delete <whiteboard_id> --node-ids a,b --dry-run # 先预览要删的节点
  629. # ⭐ AI 自由作图(飞轮/鱼骨/Dashboard/插画/周期表/赛博朋克等):用 skill 的一键脚本,每个矢量元素都可单独点击编辑
  630. python3 skills/feishu-cli-visual/references/workflows/board/scripts/svg_to_board.py drawing.svg <whiteboard_id>
  631. # 内置 5 步管道:whiteboard-cli 翻译 → 修 z_index → 修剪 viewBox 溢出 → 分批 create-notes → 验证
  632. # 评论
  633. feishu-cli comment list <file_token> --type docx
  634. feishu-cli comment add <file_token> --type docx --text "评论内容"
  635. feishu-cli comment resolve <file_token> <comment_id> --type docx
  636. feishu-cli comment unresolve <file_token> <comment_id> --type docx
  637. feishu-cli comment reply list <file_token> <comment_id> --type docx
  638. feishu-cli comment reply delete <file_token> <comment_id> <reply_id> --type docx
  639. # 多维表格(base/v3 API)
  640. feishu-cli bitable create --name "项目管理" --time-zone Asia/Shanghai
  641. feishu-cli bitable table list --base-token bscnxxxx
  642. feishu-cli bitable table create --base-token bscnxxxx --name "任务"
  643. feishu-cli bitable field list --base-token bscnxxxx --table-id tblxxx
  644. feishu-cli bitable field create --base-token bscnxxxx --table-id tblxxx --config '{"name":"状态","type":"select"}'
  645. feishu-cli bitable record upsert --base-token bscnxxxx --table-id tblxxx --config '{"fields":{"名称":"测试"}}'
  646. feishu-cli bitable record upsert --base-token bscnxxxx --table-id tblxxx --record-id recxxx --config '{"fields":{"状态":"完成"}}'
  647. feishu-cli bitable record batch-create --base-token bscnxxxx --table-id tblxxx --config '{"create_records":[{"fld1":"val1"},{"fld1":"val2"}]}'
  648. feishu-cli bitable record batch-delete --base-token bscnxxxx --table-id tblxxx --record-ids rec_1,rec_2,rec_3
  649. feishu-cli bitable record batch-get --base-token bscnxxxx --table-id tblxxx --record-ids rec_1,rec_2 # 批量获取记录
  650. feishu-cli bitable record share-link --base-token bscnxxxx --table-id tblxxx --record-ids rec_1,rec_2 # 批量共享链接(v1.29+)
  651. feishu-cli bitable record list --base-token bscnxxxx --table-id tblxxx
  652. # 结构化过滤/排序(tuple DSL,无需关键词)
  653. feishu-cli bitable record list --base-token bscnxxxx --table-id tblxxx \
  654. --filter-json '{"logic":"and","conditions":[["状态","==",["Doing"]],["分数",">=",70]]}' \
  655. --sort-json '[{"field":"分数","desc":true}]'
  656. feishu-cli bitable view list --base-token bscnxxxx --table-id tblxxx
  657. feishu-cli bitable view view-filter-get --base-token bscnxxxx --table-id tblxxx --view-id vewxxx
  658. feishu-cli bitable role list --base-token bscnxxxx
  659. # 记录附件(上传 / 下载 / 移除)
  660. feishu-cli bitable record upload-attachment --base-token bscnxxxx --table-id tblxxx \
  661. --record-id recxxx --field-id fldxxx --file ./report.pdf --file ./shot.png
  662. feishu-cli bitable record download-attachment --base-token bscnxxxx --table-id tblxxx \
  663. --record-id recxxx --output ./downloads/
  664. feishu-cli bitable record remove-attachment --base-token bscnxxxx --table-id tblxxx \
  665. --record-id recxxx --field-id fldxxx --file-token boxcnxxxx
  666. # 仪表盘(CRUD + 智能排版 + 仪表盘块)
  667. feishu-cli bitable dashboard create --base-token bscnxxxx --name "运营看板"
  668. feishu-cli bitable dashboard block create --base-token bscnxxxx --dashboard-id dsbxxxx \
  669. --type column --name "按月统计" --data-config '{"table_name":"任务","group_by":"月份"}'
  670. feishu-cli bitable dashboard arrange --base-token bscnxxxx --dashboard-id dsbxxxx
  671. # 表单(CRUD + 分享 token 详情/提交 + 表单问题)
  672. feishu-cli bitable form create --base-token bscnxxxx --table-id tblxxx --name "报名表"
  673. feishu-cli bitable form field create --base-token bscnxxxx --table-id tblxxx --form-id vewxxx \
  674. --questions '[{"type":"text","title":"你的名字","required":true}]'
  675. feishu-cli bitable form detail --share-token shrcnxxxx # 无需 base_token
  676. feishu-cli bitable form submit --share-token shrcnxxxx --content '{"评分":5,"评价":"很好"}'
  677. # 角色协作者(member list/create/delete/batch-create/batch-delete)
  678. feishu-cli bitable role member list --base-token bscnxxxx --role-id rolxxxx
  679. feishu-cli bitable role member create --base-token bscnxxxx --role-id rolxxxx --member-id ou_xxx --member-id-type open_id
  680. feishu-cli bitable role member delete --base-token bscnxxxx --role-id rolxxxx --member-id ou_xxx --member-id-type open_id
  681. feishu-cli bitable role member batch-create --base-token bscnxxxx --role-id rolxxxx --member-ids ou_a,ou_b --member-id-type open_id
  682. # 多维表格元信息更新(重命名 / 高级权限开关)
  683. feishu-cli bitable update --base-token bscnxxxx --name "新表名" # 重命名
  684. feishu-cli bitable update --base-token bscnxxxx --is-advanced # 开启高级权限(--is-advanced=false 关闭)
  685. # 工作流(list/get/create/update/enable/disable;update 为整体替换 PUT)
  686. feishu-cli bitable workflow list --base-token bscnxxxx
  687. feishu-cli bitable workflow get --base-token bscnxxxx --workflow-id wkfxxxx
  688. feishu-cli bitable workflow update --base-token bscnxxxx --workflow-id wkfxxxx --config-file wf.json
  689. feishu-cli bitable workflow enable --base-token bscnxxxx --workflow-id wkfxxxx
  690. feishu-cli bitable workflow disable --base-token bscnxxxx --workflow-id wkfxxxx
  691. # 字段 AI 扩展 / 按钮绑定工作流 / 复制数据表 / 模板中心 / 顶层块
  692. feishu-cli bitable field extension get --base-token bscnxxxx --table-id tblxxx --field-id fldxxx
  693. feishu-cli bitable field button-rule bind --base-token bscnxxxx --table-id tblxxx --field-id 按钮 --workflow-id wkfxxxx
  694. feishu-cli bitable table copy --base-token bscnxxxx --table-id tblxxx --name "任务副本" --range all --wait
  695. feishu-cli bitable template search --keyword 项目管理
  696. feishu-cli bitable block create --base-token bscnxxxx --type folder --name "归档"
  697. # 云盘增强(drive)
  698. feishu-cli drive upload --file big.zip --folder-token fldxxx
  699. feishu-cli drive upload --file new.zip --file-token boxcnXXX # 原地覆盖上传新版本
  700. feishu-cli drive secure-label list --lang zh # 密级标签查询 / set 设置
  701. feishu-cli drive download --file-token boxxxx --output ./downloads/ --overwrite
  702. feishu-cli drive download --file-token boxxxx --output ./big.zip --timeout 30m # 大文件自动 Range 分片兜底
  703. feishu-cli drive export --token docxxxx --doc-type docx --file-extension markdown --output-dir ./exports
  704. feishu-cli drive export --token sheetxxxx --doc-type sheet --file-extension csv --sub-id sheet_1 --output-dir ./out
  705. feishu-cli drive export --token sldxxxx --doc-type slides --file-extension pptx --output-dir ./out
  706. feishu-cli drive import --file report.docx --type docx --folder-token fldxxx
  707. feishu-cli drive import --file deck.pptx --type slides
  708. feishu-cli drive move --file-token fldxxx --type folder --folder-token fldyyy
  709. feishu-cli drive move --file-token boxxxx --type file # 省略目标时先取真实 root token
  710. feishu-cli drive add-comment --doc docxxx --content '[{"type":"text","text":"评论"}]'
  711. # v1.29+ 新增 ⭐
  712. feishu-cli drive inspect --url "https://xxx.feishu.cn/docx/doxxxx" # 解析 URL → type/title/token
  713. feishu-cli drive apply-permission --token "<url|token>" --perm view --remark "申请理由" # 向 owner 发申请
  714. # 云盘 ↔ 本地单向镜像(pull/push/status)
  715. feishu-cli drive status --folder-token fldxxx --local-dir ./mirror
  716. feishu-cli drive pull --folder-token fldxxx --local-dir ./mirror --if-exists overwrite
  717. feishu-cli drive push --folder-token fldxxx --local-dir ./mirror --if-exists skip
  718. feishu-cli drive pull --folder-token fldxxx --local-dir ./mirror --delete-local --yes # 高危:双确认
  719. # 云盘 v2 搜索(与 search docs 同一 Search v2 端点,drive search 暴露更多 filter 与排序)
  720. feishu-cli drive search --query "季度报告" --doc-types DOC,SHEET --sort edit_time # 关键字也可写成唯一位置参数
  721. feishu-cli drive search --folder-tokens fldxxx --only-title
  722. feishu-cli drive search --created-since 7d --created-by-me # 时间窗:--edited/--commented/--opened/--created-since|until
  723. feishu-cli drive search --opened-since 1m --mine # --mine 按所有者,--created-by-me 按原始创建者
  724. feishu-cli drive push --folder-token fldxxx --local-dir ./mirror --delete-remote --dry-run # 差集计划,不删除
  725. # 上传文件的预览产物与封面
  726. feishu-cli drive preview boxcnxxx --list-only
  727. feishu-cli drive preview boxcnxxx --type source_file -o ./file.bin
  728. feishu-cli drive cover boxcnxxx --spec default -o cover.png
  729. # 邮箱(mail,需 User Token)
  730. feishu-cli mail triage --folder INBOX --unread-only --page-size 20
  731. feishu-cli mail triage --query "周会"
  732. feishu-cli mail message --message-id msg_xxx
  733. feishu-cli mail send --to user@example.com --subject "测试" --body "hi" # 默认存草稿
  734. feishu-cli mail send --to user@example.com --subject "测试" --body "hi" --confirm-send # 立即发送
  735. feishu-cli mail message-modify --message-ids id1,id2 --add-label-ids FLAGGED # 批量改 label/移文件夹
  736. feishu-cli mail message-trash --message-ids id1,id2 --yes # 批量软删进废纸篓
  737. feishu-cli mail draft-send --draft-id <id> --confirm-send # 发送已有草稿
  738. feishu-cli mail send --to user@example.com --subject "周报" --body "$(cat report.html)" \
  739. --html --inline-images-auto-scan --confirm-send
  740. feishu-cli mail template create --name "周报模板" --subject "本周进度" --body "$(cat template.html)"
  741. feishu-cli mail template list
  742. feishu-cli mail reply --message-id msg_xxx --body "收到" --confirm-send
  743. feishu-cli mail forward --message-id msg_xxx --to team@example.com --body "请关注"
  744. feishu-cli mail signature # 列出邮箱签名
  745. feishu-cli mail signature --detail 7012345678901234567 -o json # 单个签名详情
  746. feishu-cli mail send --to user@example.com --subject "周报" --body "hi" --confirm-send --send-time 1793000000 # 定时发送(Unix 秒,≥5 分钟)
  747. feishu-cli mail send --to user@example.com --subject "确认" --body "hi" --request-receipt # 请求已读回执
  748. feishu-cli mail share-to-chat --message-id msg_xxx --receive-id oc_xxx --dry-run # 邮件卡片分享到会话
  749. # 视频会议(vc):search/notes/recording 默认 User,可 `--as bot`;bot meeting-join/leave 默认 Bot/Tenant 身份
  750. feishu-cli vc search --query "周会" --start 2026-03-20 --end 2026-03-28
  751. feishu-cli vc detail <meeting_id|会议号> # 聚合会议信息 + note_id + minute_token
  752. feishu-cli vc note detail <note_id> # 智能纪要详情
  753. feishu-cli vc note transcript <note_id> --output t.md # 统一逐字稿导出
  754. feishu-cli vc notes --meeting-ids 69xxxx,70xxxx
  755. feishu-cli vc notes --minute-tokens obcnxxxx --with-artifacts --download-transcript --output-dir ./notes
  756. feishu-cli vc recording --meeting-ids 69xxxx
  757. feishu-cli vc bot meeting-join --meeting-number 123456789 # 机器人入会(Bot/Tenant 身份)
  758. feishu-cli vc bot meeting-leave --meeting-id 6911188411932033028 # 机器人离会(Bot/Tenant 身份)
  759. feishu-cli vc bot meeting-events --meeting-id 6911188411932033028 --as user --start 2026-03-01 --end 2026-03-31
  760. feishu-cli vc bot meeting-events --meeting-id 6911188411932033028 --as bot --dry-run # 与 meeting_id 来源身份一致;禁止静默回落
  761. # 会中控制:countdown/message-send/screenshot 默认 --as auto;invite/end 仅 Bot,end 带确认门禁
  762. feishu-cli vc bot meeting-countdown --meeting-id 6911188411932033028 --action set --duration 10
  763. feishu-cli vc bot meeting-message-send --meeting-id 6911188411932033028 --text "五分钟后开始"
  764. feishu-cli vc bot meeting-screenshot --meeting-id 6911188411932033028 --output shot.jpg
  765. feishu-cli vc bot meeting-invite --meeting-id 6911188411932033028 --type selected --open-ids ou_xxx
  766. feishu-cli vc bot meeting-end --meeting-id 6911188411932033028 --yes
  767. # 妙记(minutes,默认 User,可 `--as bot`)
  768. feishu-cli minutes get <minute_token> --with-artifacts
  769. feishu-cli minutes get <minute_token> --wait-ready # 轮询等待妙记转写就绪
  770. feishu-cli minutes search --query "周会" # 搜索妙记
  771. feishu-cli minutes apply-permission --minute-token <token> --perm view # 申请妙记权限
  772. feishu-cli minutes download --minute-tokens obcnxxxx --output ./media
  773. feishu-cli minutes download --minute-tokens obcnxxxx --url-only
  774. # 妙记编辑(仅 User,均支持 --dry-run)
  775. feishu-cli minutes upload --file-token boxcnxxx # 用云盘音视频生成妙记
  776. feishu-cli minutes update obcnxxxx --topic "新标题"
  777. feishu-cli minutes summary obcnxxxx --summary @summary.md
  778. feishu-cli minutes todo obcnxxxx --operation add --todo "补充数据" --is-done=false
  779. feishu-cli minutes speaker-replace obcnxxxx --from-speaker-id <speaker_id> --to-user-id ou_xxx
  780. feishu-cli minutes word-replace obcnxxxx --replace-words '[{"source_word":"a","target_word":"b"}]'
  781. # 妙搭(Miaoda)应用 —— 一份 HTML 秒级发布成可分享的飞书应用(需 User Token + spark scope)
  782. feishu-cli auth login --scope "spark:app:read spark:app:write" # ⚠️ --scope 是替换不是合并,需并入你完整 scope 串
  783. feishu-cli apps create --name "我的页面" --app-type HTML # 拿 app_id(jq .app.app_id,CLI 已剥掉 data 外层)
  784. feishu-cli apps html-publish --app-id app_xxx --path ./dist # 三段协议发布,返回 release_id(jq .release_id)
  785. feishu-cli apps html-publish --app-id app_xxx --path ./index.html # 单文件形态(文件名必须 index.html)
  786. feishu-cli apps html-publish --app-id app_xxx --path ./dist --dry-run # 只看三段计划 + 打包清单,零网络
  787. feishu-cli apps access-scope-set --app-id app_xxx --scope tenant # 组织内可见
  788. feishu-cli apps access-scope-set --app-id app_xxx --scope public --require-login=true
  789. feishu-cli apps access-scope-set --app-id app_xxx --scope specific \
  790. --targets '[{"type":"user","id":"ou_xxx"},{"type":"chat","id":"oc_xxx"}]'
  791. feishu-cli apps access-scope-get --app-id app_xxx # 查看当前访问范围
  792. feishu-cli apps update --app-id app_xxx --name "新名字"
  793. feishu-cli apps update --app-id app_xxx --icon-file ./icon.png # 改图标(png/jpeg ≤2MB,或 --icon-url)
  794. feishu-cli apps list --owner-id ou_xxx
  795. feishu-cli apps release create --app-id app_xxx --branch main --wait # 按分支发布并等待结果
  796. feishu-cli apps features --app-id app_xxx # 功能开关(只读)
  797. feishu-cli apps delete --app-id app_xxx --confirm-name "我的页面" --yes # 名称校验 + 确认门禁
  798. # 日历增强
  799. feishu-cli calendar agenda # 查看今日日程
  800. feishu-cli calendar agenda --start-date 2026-03-28 --end-date 2026-03-29
  801. feishu-cli calendar suggestion --attendee-ids ou_aaa,ou_bbb --duration 30m
  802. feishu-cli calendar room-find --slot 2026-03-28T14:00:00+08:00~2026-03-28T15:00:00+08:00 \
  803. --city "北京" --min-capacity 6
  804. feishu-cli calendar rsvp --event-id EVENT_xxx --action accept
  805. feishu-cli calendar create-event --summary "评审" --start 2026-11-10T14:00:00+08:00 --end 2026-11-10T15:00:00+08:00 \
  806. --description "**议程**" --description-format markdown --dry-run # 富文本描述,当前目录内本地图片自动上传
  807. # 任务增强
  808. feishu-cli task my # 查看我的任务
  809. feishu-cli task search --keyword 评审 --uncompleted --due-before 2026-12-31 # 服务端搜索(--enrich=false 免详情补全)
  810. feishu-cli task reopen <task_guid> # 重新打开
  811. feishu-cli task comment add <task_guid> --content "评论"
  812. feishu-cli tasklist task-add <tasklist_guid> --task-ids guid1,guid2
  813. feishu-cli tasklist member add <tasklist_guid> --members ou_xxx
  814. feishu-cli task create -s "整理周报" --assignee ou_xxx --tasklist-id <guid> --idempotency-key weekly-01 --dry-run
  815. feishu-cli task comment update <comment_id> --content "已更新" # 另有 get / delete(delete 带确认门禁)
  816. feishu-cli tasklist task-add <tasklist_guid> --task-ids guid1 --section-guid <section_guid>
  817. # 消息增强
  818. feishu-cli msg mget --message-ids om_xxx,om_yyy
  819. feishu-cli msg resource-download <message_id> <file_key> --type image -o photo.png
  820. feishu-cli msg resource-download <message_id> <file_key> --type file --user-access-token u-xxx -o attachment.bin # 用户可见但 Bot 不可见的资源
  821. feishu-cli msg resource-download <message_id> <file_key> --type file --user-access-token u-xxx -o large.bin --timeout 30m # 大文件自动 Range 分片兜底
  822. feishu-cli msg thread-messages <thread_id> --page-size 20
  823. feishu-cli msg flag create om_xxx # 收藏消息
  824. feishu-cli msg flag create om_xxx --flag-type feed # feed 层自动识别 thread/msg_thread
  825. feishu-cli msg flag list --page-size 50
  826. feishu-cli msg flag cancel om_xxx # 尽量取消消息层 + feed 层
  827. # interactive 卡片返回原始 schema(不再返回渲染后的 <card title> 文本)
  828. feishu-cli msg get om_xxx --card-content-type user # userDSL(开发者视角的 schema 2.0 JSON)
  829. feishu-cli msg get om_xxx --card-content-type raw # cardDSL(平台内部完整描述)
  830. feishu-cli msg mget --message-ids om_xxx,om_yyy --card-content-type user
  831. feishu-cli msg list --container-id oc_xxx --card-content-type user
  832. # 文档增强(采用 docs_ai 单操作原子更新协议,彻底避免先删后写破坏窗口;支持 --revision-id 并发保护)
  833. feishu-cli doc content-update <doc_id> --mode append --markdown "## 新内容"
  834. feishu-cli doc content-update <doc_id> --mode overwrite --markdown "# 全新文档" [--revision-id 42]
  835. feishu-cli doc content-update <doc_id> --mode replace_range --selection-by-title "章节标题" --markdown "## 新章节"
  836. feishu-cli doc media-insert <doc_id> --file photo.png --type image --align center
  837. feishu-cli doc media-insert <doc_id> --from-clipboard --type image # 从剪贴板插图(Linux 需 xclip / wl-paste / xsel)
  838. feishu-cli doc media-insert <doc_id> --file report.pdf --type file --file-view preview
  839. feishu-cli doc media-download <file_token> -o image.png
  840. feishu-cli doc media-preview <file_token> -o ./preview # 预览接口下载素材或评论图片
  841. feishu-cli doc media-download <file_token> --doc-token DOC_TOKEN --doc-type docx -o image.png
  842. # 妙笔BOX HTML 小组件(文档里跑动画 / ECharts / 可交互图表,唯一能"动"的载体)
  843. feishu-cli doc htmlbox create <doc_id> --html-file widget.html
  844. feishu-cli doc htmlbox update <doc_id> <block_id> --html-file widget-v2.html
  845. feishu-cli doc htmlbox get <doc_id> <block_id> --raw > current.html
  846. feishu-cli doc htmlbox delete <doc_id> <block_id>
  847. # 电子表格导出
  848. feishu-cli sheet export <token> -o output.xlsx
  849. feishu-cli sheet export <token> --format csv --sheet-id SHEET_ID -o output.csv
  850. feishu-cli sheet export <token_or_url> --format markdown -o output.md
  851. feishu-cli sheet filter-view create --spreadsheet-token shtcnxxxx --sheet-id SHEET_ID \
  852. --range "SHEET_ID!A1:H100" --name "P0 高优"
  853. feishu-cli sheet filter-view list --spreadsheet-token shtcnxxxx --sheet-id SHEET_ID
  854. feishu-cli sheet filter-view update --token shtcnxxxx --sheet-id SHEET_ID \
  855. --filter-view-id pH9xxxx --name "新名字"
  856. # 筛选条件(按列字母定位)
  857. feishu-cli sheet filter-view condition create --token shtcnxxxx --sheet-id SHEET_ID \
  858. --filter-view-id pH9xxxx --condition-id E --filter-type number --compare-type less --expected '["6"]'
  859. feishu-cli sheet filter-view condition list --token shtcnxxxx --sheet-id SHEET_ID --filter-view-id pH9xxxx
  860. feishu-cli sheet dropdown set --token shtcnxxxx --range "SHEET_ID!B2:B100" \
  861. --options "待办,处理中,已完成"
  862. feishu-cli sheet dropdown update --token shtcnxxxx --sheet-id SHEET_ID \
  863. --ranges "SHEET_ID!A1:A100" --options "P0,P1,P2" --multiple --colors "#FF4D4F,#FAAD14,#52C41A"
  864. feishu-cli sheet dropdown get --token shtcnxxxx --range "SHEET_ID!A1:A100"
  865. feishu-cli sheet dropdown delete --token shtcnxxxx --ranges "SHEET_ID!A1:A100"
  866. # 浮动图片 / 单元格写图 / 批量样式
  867. feishu-cli sheet image media-upload shtcnxxxx ./logo.png # 返回 file_token
  868. feishu-cli sheet image write-image shtcnxxxx SHEET_ID --range "A1" --image https://example.com/logo.png # 支持 HTTPS URL / 本地路径并回读校验
  869. feishu-cli sheet image write-batch shtcnxxxx SHEET_ID --manifest images.json # 批量写入并回读校验(支持文件、stdin '-' 或行内 JSON)
  870. feishu-cli sheet batch-set-style shtcnxxxx \
  871. --data '[{"ranges":["SHEET_ID!A1:A2"],"style":{"font":{"bold":true},"backColor":"#FF0000"}}]'
  872. # Drive 原生 Markdown 文件(不做 docx 块转换)
  873. feishu-cli markdown create --name README.md --content-file ./README.md --folder-token fldxxx
  874. feishu-cli markdown create --file ./README.md --wiki-token wikcnxxx --as bot --dry-run
  875. feishu-cli markdown fetch --file-token boxcnxxx --output-path ./remote.md
  876. feishu-cli markdown overwrite --file-token boxcnxxx --file ./remote.md
  877. feishu-cli markdown patch --file-token boxcnxxx --pattern "TODO" --content "DONE"
  878. feishu-cli markdown diff --file-token boxcnxxx --file ./local.md # 远端最新 vs 本地
  879. feishu-cli markdown diff --file-token boxcnxxx --from-version 2 --to-version 5 # 远端版本 A vs B
  880. # 用户
  881. feishu-cli user info <user_id>
  882. feishu-cli user search --email user@example.com # 邮箱查 user_id;带 User Token 时自动补 open_id + 姓名
  883. feishu-cli user search --mobile 13800138000
  884. feishu-cli user search --query "张三" # 按姓名/关键词模糊搜索,需 User Token
  885. feishu-cli user list --department-id DEPT_ID
  886. # 部门
  887. feishu-cli dept get <department_id>
  888. feishu-cli dept children <department_id>
  889. # 考勤(支持 User/Tenant Token,未传 --user-ids 自动走本人自查)
  890. feishu-cli attendance user-task query --start 2026-03-01 --end 2026-03-31
  891. feishu-cli attendance user-task query --employee-type employee_id --user-ids 2847xxxx \
  892. --start 2026-03-01 --end 2026-03-31
  893. feishu-cli attendance user-stats query --employee-type employee_no --user-ids 10001 \
  894. --start 2026-03-01 --end 2026-03-31
  895. # OKR(cycle list 默认查询 v2 用户周期,与 cycle detail / 目标创建使用同一套 ID;--tenant 查租户周期)
  896. feishu-cli okr cycle list
  897. feishu-cli okr progress list --objective-id 7xxx
  898. feishu-cli okr cycle detail <cycle_id> # 周期下全部目标+关键结果
  899. feishu-cli okr progress get/update/delete <progress_id> # 进展记录全生命周期
  900. feishu-cli okr upload-image --file chart.png --objective-id 7xxx # 进展图片素材
  901. feishu-cli okr progress create --key-result-id 7xxx --content "本周完成核心模块联调"
  902. feishu-cli okr objective batch-create --cycle-id <cycle_id> --input @okr.json --dry-run # 失败回滚
  903. feishu-cli okr weight --level key-result --objective-id <objective_id> --weights '[{"id":"<kr_id_1>","weight":0.6},{"id":"<kr_id_2>","weight":0.4}]'
  904. feishu-cli okr reorder --level objective --cycle-id <cycle_id> --ops '[{"id":"<objective_id>","position":1}]'
  905. feishu-cli okr indicator update --level key-result --id <key_result_id> --value 80 # ID 均为数字
  906. feishu-cli okr comment update <comment_id> --content "已同步" # 另有 get / delete;update/delete 需 User
  907. # Slides 演示文稿
  908. feishu-cli slides create --title "Q2 OKR" --slide @page1.xml --output json # 创建时带页面,@./img.png 自动上传
  909. feishu-cli slides add-slide <presentation> --slide @page2.xml
  910. feishu-cli slides get <presentation_or_url> --slide-number 2 --output-file page2.xml
  911. feishu-cli slides screenshot <presentation> --slide-number 1 --output cover
  912. feishu-cli slides media-upload --file ./cover.png --presentation-token <xml_presentation_id>
  913. feishu-cli slides history list <presentation> # 历史版本
  914. feishu-cli slides history revert <presentation> --history-version-id 3 --wait --yes # 回滚:只轮询不重放,≤5 分钟
  915. feishu-cli slides add-slide <presentation> --slide @page3.xml --as user # slides/board 写命令默认 Bot,可 --as user|auto
  916. # 实时事件订阅
  917. feishu-cli event list
  918. feishu-cli event schema im.message.receive_v1
  919. feishu-cli event consume im.message.receive_v1 --max-events 5 --timeout 60s
  920. feishu-cli event consume card.action.trigger # 卡片按钮/表单回调(交互式 Bot)
  921. feishu-cli event consume approval.instance.status_changed_v4 # 审批事件(自动注册服务端订阅)
  922. feishu-cli event consume vc.meeting.participant_meeting_ended_v1 # VC:User pre-consume,握手后才发 ready
  923. feishu-cli event consume approval.instance.status_changed_v4 --dry-run # 预览订阅计划(身份、订阅请求、需勾选的事件),不联网
  924. feishu-cli event consume board.whiteboard.updated_v1 --param whiteboard_id=<id> # 带参数的 EventKey,见 event schema <key>
  925. feishu-cli event status
  926. feishu-cli event stop --all
  927. # OpenAPI schema / 健康检查 / 多配置
  928. feishu-cli schema list --service im
  929. feishu-cli schema status --format json
  930. feishu-cli schema im.messages.delete --format json
  931. feishu-cli doctor --json
  932. feishu-cli doctor --only catalog --offline --json
  933. feishu-cli profile list --json
  934. feishu-cli profile current --json
  935. feishu-cli profile migrate
  936. feishu-cli profile add work --app-id cli_xxx --app-secret secret_xxx --use
  937. feishu-cli --profile work auth status -o json
  938. feishu-cli --bot-app-id cli_xxx --bot-app-secret xxx profile list --json # 单次覆盖 App 凭证,不切换 token.json
  939. feishu-cli profile use -
  940. # 通用 OpenAPI 透传(v1.29+)⭐ 覆盖 2500+ 未封装端点
  941. feishu-cli api GET /open-apis/authen/v1/user_info --as user
  942. feishu-cli api GET /open-apis/im/v1/chats --params '{"page_size":10}' --as user
  943. feishu-cli api GET /open-apis/im/v1/chats --page-all --page-limit 10 --as user
  944. feishu-cli api POST /open-apis/im/v1/messages --params '{"receive_id_type":"email"}' \
  945. --data '{"receive_id":"u@example.com","msg_type":"text","content":"{\"text\":\"hi\"}"}' --as bot
  946. feishu-cli api DELETE /open-apis/im/v1/messages/om_xxx --as bot --dry-run # 预览
  947. feishu-cli api POST /open-apis/im/v1/files --as bot --file file=./report.pdf \
  948. --data '{"file_type":"pdf","file_name":"report.pdf"}' --dry-run # multipart 上传
  949. feishu-cli --error-format json api GET /open-apis/im/v1/chats --as bot # 错误以一行 JSON 输出到 stderr
  950. feishu-cli auth token --as user # 导出 token 给其他工具用(如果需要)
  951. ```
  952. </details>
  953. ## AI 技能集成
  954. `skills/` 目录包含 **9 个领域 Skill**。每个领域 Skill 在 `references/workflows/` 下按需加载细粒度工作流,减少常驻上下文,同时覆盖完整 CLI 能力。
  955. | 技能 | 功能 | 触发示例 |
  956. |------|------|---------|
  957. | `feishu-cli-platform` | 认证、配置、Profile、doctor、API/schema、搜索、通讯录 | "登录飞书"、"查这个 API 参数" |
  958. | `feishu-cli-docs` | 文档读取/编辑、Markdown 导入、导出、原生 `.md` CRUD | "把这个 md 导入飞书" |
  959. | `feishu-cli-storage` | Drive、file/media、wiki、评论和权限 | "上传文件并给同事权限" |
  960. | `feishu-cli-messaging` | 消息发送、聊天历史、群管理、卡片和事件订阅 | "做张卡片发到群里" |
  961. | `feishu-cli-data` | Sheet 与 Bitable/Base 全功能 | "给表格加下拉框" |
  962. | `feishu-cli-visual` | dataviz、画板、Slides、妙笔BOX 和妙搭应用 | "在飞书里画交互图表" |
  963. | `feishu-cli-work` | 日历、任务、审批、考勤和 OKR | "找时间开会并创建任务" |
  964. | `feishu-cli-mail` | 飞书邮箱读取、草稿、发送、回复和转发 | "回复这封飞书邮件" |
  965. | `feishu-cli-meetings` | 视频会议、妙记、录制、逐字稿和会议机器人 | "下载会议纪要" |
  966. Skill 入口使用 Agent Skills 标准 frontmatter;按需加载的工作流和脚本随目录一起分发。
  967. 本版本技能与 `feishu-cli v1.43.0+` 配套使用;聊天导出脚本需要 Python 3.10+,
  968. 可视化工作流按需使用 Node.js、whiteboard-cli 或 agent-browser,具体依赖见对应入口的 `compatibility`。
  969. 各宿主对工具授权字段的解释可能不同,不能把 `allowed-tools` 当作跨宿主的执行保证。
  970. 维护时从仓库根运行 `make check-skills`。它会重新编译 CLI,检查 YAML 元数据、引用、
  971. 命令归属和示例参数,再执行脚本回归与本地模拟 API 的二进制契约测试。
  972. 这些检查不等同于线上 API 验证或模型触发评测;后两者需要分别执行并记录模型、身份和实际结果。
  973. `skills/trigger-evals.json` 保留各领域的 8 个正例,`scripts/build_trigger_eval_set.py`
  974. 为每个领域生成 8 正例加 8 个相邻领域负例;`skills/trigger-boundary-evals.json` 另存跨领域和不应触发的场景。
  975. <details>
  976. <summary>旧 Skill 名称迁移对照(v1.35 前的 29 个技能 → 9 个领域)</summary>
  977. | 新 Skill | 合并的旧 Skill |
  978. |---|---|
  979. | `feishu-cli-platform` | api、auth、schema、search,以及 toolkit 的 user/dept/search 参考资料 |
  980. | `feishu-cli-docs` | read、write、import、export、markdown |
  981. | `feishu-cli-storage` | drive、perm,以及 toolkit 的 file/media/wiki/comment |
  982. | `feishu-cli-messaging` | msg、chat、card、event,以及 toolkit 的 chat 参考资料 |
  983. | `feishu-cli-data` | sheet、bitable,以及 toolkit 的 sheet 参考资料 |
  984. | `feishu-cli-visual` | dataviz、board、slides、htmlbox、apps,以及 toolkit 的 board 参考资料 |
  985. | `feishu-cli-work` | calendar、approval、attendance、okr,以及 toolkit 的 calendar/task/tasklist |
  986. | `feishu-cli-mail` | mail(名称不变) |
  987. | `feishu-cli-meetings` | vc、minutes |
  988. </details>
  989. **安装方法**:
  990. 技能随二进制内嵌,内容与当前 `feishu-cli` 版本严格配套,推荐用内置命令安装:
  991. ```bash
  992. # 先预览,再安装到 ~/.claude/skills(--dir 或 FEISHU_CLI_SKILLS_DIR 可指定其他目录)
  993. feishu-cli skills install --dry-run
  994. feishu-cli skills install
  995. # 升级 CLI 后同步技能;doctor 会检查本地技能是否与 CLI 版本漂移
  996. feishu-cli update
  997. feishu-cli skills install
  998. feishu-cli doctor --only skills
  999. # 不安装也可以直接读取当前版本的技能内容
  1000. feishu-cli skills list
  1001. feishu-cli skills read feishu-cli-docs
  1002. ```
  1003. `skills install` 写入前会解析符号链接并打印真实路径;只覆盖上次由它写入且未被修改的文件,
  1004. 发现本地修改(或目录来自 npx/手动复制且内容不同)时不带 `--force` 拒绝写入;旧版 29 个技能目录默认只列出,
  1005. 加 `--prune-legacy` 才删除确认属于 feishu-cli 的旧目录。
  1006. 备选:`npx skills add riba2534/feishu-cli --global --yes --agent claude-code --copy` 拉取的是 GitHub main 分支的技能,
  1007. 可能与本地 CLI 版本不一致;或手动把 `skills/` 下 9 个领域目录复制到 `~/.claude/skills/`。
  1008. ## 块类型映射
  1009. <details>
  1010. <summary>Markdown ↔ 飞书块类型完整对照表</summary>
  1011. | Markdown | 飞书块类型 | block_type | 说明 |
  1012. |----------|-----------|------------|------|
  1013. | `# 标题` | Heading 1-9 | 3-11 | 支持 9 级标题(Markdown 规范 6 级) |
  1014. | 段落文本 | Text | 2 | 普通文本 |
  1015. | `- 列表` | Bullet | 12 | 无序列表(支持无限深度嵌套) |
  1016. | `1. 列表` | Ordered | 13 | 有序列表(支持无限深度嵌套) |
  1017. | `- [ ] 任务` | Todo | 17 | 任务列表 |
  1018. | ` ```lang``` ` | Code | 14 | 代码块 |
  1019. | ` ```mermaid``` ` | Board (Diagram) | 21 → 43 | 自动转画板 |
  1020. | ` ```plantuml``` ` | Board (Diagram) | 21 → 43 | 自动转画板 |
  1021. | ` ```svg``` ` | Board (Diagram) | 43 | 转为可编辑画板节点 |
  1022. | `> 引用` | QuoteContainer | 34 | 引用容器 |
  1023. | `> [!NOTE]` | Callout | 19 | 6 种类型(NOTE/WARNING/TIP/CAUTION/IMPORTANT/SUCCESS) |
  1024. | `---` | Divider | 22 | 分割线 |
  1025. | `\| 表格 \|` | Table | 31 | 大表格自动拆分 |
  1026. | `![](url)` | Image | 27 | 图片(API 限制,创建占位块) |
  1027. | `$$公式$$` | Equation | 16 | 块级公式(降级为行内) |
  1028. | 附件 | File | 23 | 文件块 |
  1029. | `<iframe>` | Iframe | 26 | 内嵌网页 |
  1030. </details>
  1031. ## 权限要求
  1032. > **💡 推荐做法:一键创建机器人**
  1033. >
  1034. > 新用户不需要手动去飞书开放平台后台创建应用,feishu-cli 自带 Device Flow 协议的**一键创建机器人**工作流,在终端扫码确认即可自动注册「个人代理应用」:
  1035. >
  1036. > ```bash
  1037. > # 1. 一键创建飞书应用(扫码确认后自动把 App ID / App Secret 写入 ~/.feishu-cli/config.yaml)
  1038. > feishu-cli config create-app --save
  1039. >
  1040. > # 2. OAuth 用户授权(搜索、审批等需要用户身份的功能)
  1041. > feishu-cli auth login
  1042. > ```
  1043. >
  1044. > **关于权限**:创建应用后,你需要在飞书开放平台的**应用权限管理**页面为应用开通所需 scope。下面的完整权限清单可以**直接在权限管理页面粘贴 JSON 导入**,一次性开通全部功能。
  1045. >
  1046. > 权限的开通是你自己的责任(飞书开放平台一般需要 tenant 管理员审批),feishu-cli 不做自动化。
  1047. ### 完整权限清单
  1048. feishu-cli 涵盖文档、知识库、电子表格、多维表格、消息、群聊、日历、任务、审批、OKR、画板、权限管理、搜索、视频会议、妙记、邮件等全部功能。下面这份 JSON 可以直接在飞书开放平台的应用权限管理页面**一次性导入**(tenant 199 条 + user 237 条):
  1049. <details>
  1050. <summary><b>展开完整 scope JSON(复制后到 开放平台 → 权限管理 → 批量导入 粘贴即可)</b></summary>
  1051. ```json
  1052. {
  1053. "scopes": {
  1054. "tenant": [
  1055. "aily:run:write",
  1056. "aily:session:read",
  1057. "aily:session:write",
  1058. "aily:skill:read",
  1059. "aily:skill:write",
  1060. "aily:table:read",
  1061. "app_engine:application.event:read",
  1062. "app_engine:application.log:read",
  1063. "app_engine:application.metric:read",
  1064. "application:application.app_message_stats.overview:readonly",
  1065. "application:application.app_version:readonly",
  1066. "application:application.bot.operator_name:readonly",
  1067. "application:application.feedback.feedback_info",
  1068. "application:application:self_manage",
  1069. "application:bot.menu:readonly",
  1070. "application:bot.menu:write",
  1071. "approval:approval:readonly",
  1072. "base:app:copy",
  1073. "base:app:create",
  1074. "base:app:read",
  1075. "base:app:update",
  1076. "base:collaborator:create",
  1077. "base:collaborator:delete",
  1078. "base:collaborator:read",
  1079. "base:dashboard:copy",
  1080. "base:dashboard:read",
  1081. "base:field:create",
  1082. "base:field:delete",
  1083. "base:field:read",
  1084. "base:field:update",
  1085. "base:field_group:create",
  1086. "base:form:read",
  1087. "base:form:update",
  1088. "base:record:create",
  1089. "base:record:delete",
  1090. "base:record:read",
  1091. "base:record:retrieve",
  1092. "base:record:update",
  1093. "base:role:create",
  1094. "base:role:delete",
  1095. "base:role:read",
  1096. "base:role:update",
  1097. "base:table:create",
  1098. "base:table:delete",
  1099. "base:table:read",
  1100. "base:table:update",
  1101. "base:view:read",
  1102. "base:view:write_only",
  1103. "base:workflow:read",
  1104. "base:workflow:write",
  1105. "block:message",
  1106. "board:whiteboard:node:create",
  1107. "board:whiteboard:node:read",
  1108. "board:whiteboard:node:update",
  1109. "calendar:calendar.free_busy:read",
  1110. "cardkit:card:read",
  1111. "cardkit:card:write",
  1112. "comment_sdk:comment_sdk",
  1113. "component:url_preview",
  1114. "contact:user.employee_id:readonly",
  1115. "contact:user.id:readonly",
  1116. "directory:department.external_id:read",
  1117. "directory:employee.base.external_id:read",
  1118. "directory:employee.idconvert:read",
  1119. "directory:employee.work.job_number:read",
  1120. "directory:job_title.status:read",
  1121. "docs:document.comment:create",
  1122. "docs:document.comment:read",
  1123. "docs:document.comment:update",
  1124. "docs:document.comment:write_only",
  1125. "docs:document.content:read",
  1126. "docs:document.media:download",
  1127. "docs:document.media:upload",
  1128. "docs:document.subscription",
  1129. "docs:document.subscription:read",
  1130. "docs:document:copy",
  1131. "docs:document:export",
  1132. "docs:document:import",
  1133. "docs:event.document_deleted:read",
  1134. "docs:event.document_edited:read",
  1135. "docs:event.document_opened:read",
  1136. "docs:event:subscribe",
  1137. "docs:permission.member:auth",
  1138. "docs:permission.member:create",
  1139. "docs:permission.member:delete",
  1140. "docs:permission.member:retrieve",
  1141. "docs:permission.member:transfer",
  1142. "docs:permission.member:update",
  1143. "docs:permission.setting:read",
  1144. "docs:permission.setting:readonly",
  1145. "docs:permission.setting:write_only",
  1146. "docs_tool:docs_tool",
  1147. "docx:document.block:convert",
  1148. "docx:document:create",
  1149. "docx:document:readonly",
  1150. "docx:document:write_only",
  1151. "drive:drive.metadata:readonly",
  1152. "drive:drive.search:readonly",
  1153. "drive:drive:version",
  1154. "drive:drive:version:readonly",
  1155. "drive:file.like:readonly",
  1156. "drive:file.meta.sec_label.read_only",
  1157. "drive:file:download",
  1158. "drive:file:favorite",
  1159. "drive:file:favorite:readonly",
  1160. "drive:file:upload",
  1161. "drive:file:view_record:readonly",
  1162. "event:failed_event:readonly",
  1163. "event:ip_list",
  1164. "im:app_feed_card:write",
  1165. "im:chat.access_event.bot_p2p_chat:read",
  1166. "im:chat.announcement:read",
  1167. "im:chat.announcement:write_only",
  1168. "im:chat.chat_pins:read",
  1169. "im:chat.chat_pins:write_only",
  1170. "im:chat.collab_plugins:read",
  1171. "im:chat.collab_plugins:write_only",
  1172. "im:chat.managers:write_only",
  1173. "im:chat.members:bot_access",
  1174. "im:chat.members:read",
  1175. "im:chat.members:write_only",
  1176. "im:chat.menu_tree:read",
  1177. "im:chat.menu_tree:write_only",
  1178. "im:chat.moderation:read",
  1179. "im:chat.tabs:read",
  1180. "im:chat.tabs:write_only",
  1181. "im:chat.top_notice:write_only",
  1182. "im:chat.widgets:read",
  1183. "im:chat.widgets:write_only",
  1184. "im:chat:create",
  1185. "im:chat:delete",
  1186. "im:chat:moderation:write_only",
  1187. "im:chat:operate_as_owner",
  1188. "im:chat:read",
  1189. "im:chat:update",
  1190. "im:message",
  1191. "im:message.group_at_msg:readonly",
  1192. "im:message.group_msg",
  1193. "im:message.p2p_msg:readonly",
  1194. "im:message.pins:read",
  1195. "im:message.pins:write_only",
  1196. "im:message.reactions:read",
  1197. "im:message.reactions:write_only",
  1198. "im:message.urgent",
  1199. "im:message.urgent.status:write",
  1200. "im:message.urgent:phone",
  1201. "im:message.urgent:sms",
  1202. "im:message:readonly",
  1203. "im:message:recall",
  1204. "im:message:send_as_bot",
  1205. "im:message:send_multi_depts",
  1206. "im:message:send_multi_users",
  1207. "im:message:send_sys_msg",
  1208. "im:message:update",
  1209. "im:resource",
  1210. "im:url_preview.update",
  1211. "im:user_agent:read",
  1212. "llpp:model:write",
  1213. "llpp:resource",
  1214. "minutes:minute:download",
  1215. "minutes:minutes",
  1216. "minutes:minutes.basic:read",
  1217. "minutes:minutes.media:export",
  1218. "minutes:minutes.statistics:read",
  1219. "minutes:minutes.transcript:export",
  1220. "minutes:minutes:readonly",
  1221. "myai:message:read",
  1222. "sheets:spreadsheet.meta:read",
  1223. "sheets:spreadsheet.meta:write_only",
  1224. "sheets:spreadsheet:create",
  1225. "sheets:spreadsheet:read",
  1226. "sheets:spreadsheet:write_only",
  1227. "space:document.event:read",
  1228. "space:document:create",
  1229. "space:document:delete",
  1230. "space:document:move",
  1231. "space:document:retrieve",
  1232. "space:document:shortcut",
  1233. "space:folder:create",
  1234. "task:comment:write",
  1235. "task:task:read",
  1236. "task:task:write",
  1237. "task:tasklist:read",
  1238. "task:tasklist:write",
  1239. "wiki:member:create",
  1240. "wiki:member:retrieve",
  1241. "wiki:member:update",
  1242. "wiki:node:copy",
  1243. "wiki:node:create",
  1244. "wiki:node:move",
  1245. "wiki:node:read",
  1246. "wiki:node:retrieve",
  1247. "wiki:node:update",
  1248. "wiki:setting:read",
  1249. "wiki:setting:write_only",
  1250. "wiki:space:read",
  1251. "wiki:space:retrieve",
  1252. "wiki:space:write_only",
  1253. "wiki:wiki:readonly"
  1254. ],
  1255. "user": [
  1256. "aily:run:read",
  1257. "aily:run:write",
  1258. "aily:session:read",
  1259. "aily:session:write",
  1260. "aily:skill:read",
  1261. "aily:skill:write",
  1262. "aily:table:read",
  1263. "app_engine:application.event_subscriber:read",
  1264. "approval:approval:read",
  1265. "approval:instance:read",
  1266. "approval:instance:write",
  1267. "approval:task:read",
  1268. "approval:task:write",
  1269. "base:app:copy",
  1270. "base:app:create",
  1271. "base:app:read",
  1272. "base:app:update",
  1273. "base:collaborator:create",
  1274. "base:collaborator:delete",
  1275. "base:collaborator:read",
  1276. "base:dashboard:create",
  1277. "base:dashboard:delete",
  1278. "base:dashboard:read",
  1279. "base:dashboard:update",
  1280. "base:field:create",
  1281. "base:field:delete",
  1282. "base:field:read",
  1283. "base:field:update",
  1284. "base:field_group:create",
  1285. "base:form:create",
  1286. "base:form:delete",
  1287. "base:form:read",
  1288. "base:form:update",
  1289. "base:record:create",
  1290. "base:record:delete",
  1291. "base:record:read",
  1292. "base:record:retrieve",
  1293. "base:record:update",
  1294. "base:role:create",
  1295. "base:role:delete",
  1296. "base:role:read",
  1297. "base:role:update",
  1298. "base:table:create",
  1299. "base:table:delete",
  1300. "base:table:read",
  1301. "base:table:update",
  1302. "base:view:read",
  1303. "base:view:write_only",
  1304. "base:workflow:create",
  1305. "base:workflow:delete",
  1306. "base:workflow:read",
  1307. "base:workflow:update",
  1308. "base:workflow:write",
  1309. "base:workspace:list",
  1310. "board:whiteboard:node:create",
  1311. "board:whiteboard:node:delete",
  1312. "board:whiteboard:node:read",
  1313. "board:whiteboard:node:update",
  1314. "calendar:calendar.acl:create",
  1315. "calendar:calendar.acl:delete",
  1316. "calendar:calendar.acl:read",
  1317. "calendar:calendar.event:create",
  1318. "calendar:calendar.event:delete",
  1319. "calendar:calendar.event:read",
  1320. "calendar:calendar.event:reply",
  1321. "calendar:calendar.event:update",
  1322. "calendar:calendar.free_busy:read",
  1323. "calendar:calendar:create",
  1324. "calendar:calendar:delete",
  1325. "calendar:calendar:read",
  1326. "calendar:calendar:subscribe",
  1327. "calendar:calendar:update",
  1328. "calendar:time_off:create",
  1329. "calendar:time_off:delete",
  1330. "cardkit:card:read",
  1331. "cardkit:card:write",
  1332. "comment_sdk:comment_sdk",
  1333. "component:user_profile",
  1334. "contact:contact.base:readonly",
  1335. "contact:user.base:readonly",
  1336. "contact:user.basic_profile:readonly",
  1337. "contact:user.email:readonly",
  1338. "contact:user.employee_id:readonly",
  1339. "contact:user.id:readonly",
  1340. "contact:user:search",
  1341. "directory:department.external_id:read",
  1342. "directory:employee.base.external_id:read",
  1343. "directory:employee.idconvert:read",
  1344. "directory:employee.work.job_number:read",
  1345. "docs:component",
  1346. "docs:document.comment:create",
  1347. "docs:document.comment:delete",
  1348. "docs:document.comment:read",
  1349. "docs:document.comment:update",
  1350. "docs:document.comment:write_only",
  1351. "docs:document.content:read",
  1352. "docs:document.media:download",
  1353. "docs:document.media:upload",
  1354. "docs:document.subscription",
  1355. "docs:document.subscription:read",
  1356. "docs:document:copy",
  1357. "docs:document:export",
  1358. "docs:document:import",
  1359. "docs:event.document_deleted:read",
  1360. "docs:event.document_edited:read",
  1361. "docs:event.document_opened:read",
  1362. "docs:event:subscribe",
  1363. "docs:permission.member:apply",
  1364. "docs:permission.member:auth",
  1365. "docs:permission.member:create",
  1366. "docs:permission.member:delete",
  1367. "docs:permission.member:retrieve",
  1368. "docs:permission.member:transfer",
  1369. "docs:permission.member:update",
  1370. "docs:permission.setting:read",
  1371. "docs:permission.setting:readonly",
  1372. "docs:permission.setting:write_only",
  1373. "docs_tool:docs_tool",
  1374. "docx:document.block:convert",
  1375. "docx:document:create",
  1376. "docx:document:readonly",
  1377. "docx:document:write_only",
  1378. "drive:drive.metadata:readonly",
  1379. "drive:drive.search:readonly",
  1380. "drive:drive:version",
  1381. "drive:drive:version:readonly",
  1382. "drive:file.like:readonly",
  1383. "drive:file.meta.sec_label.read_only",
  1384. "drive:file:download",
  1385. "drive:file:favorite",
  1386. "drive:file:favorite:readonly",
  1387. "drive:file:upload",
  1388. "drive:file:view_record:readonly",
  1389. "event:ip_list",
  1390. "im:chat.access_event.bot_p2p_chat:read",
  1391. "im:chat.announcement:read",
  1392. "im:chat.announcement:write_only",
  1393. "im:chat.chat_pins:read",
  1394. "im:chat.chat_pins:write_only",
  1395. "im:chat.collab_plugins:read",
  1396. "im:chat.collab_plugins:write_only",
  1397. "im:chat.managers:write_only",
  1398. "im:chat.members:read",
  1399. "im:chat.members:write_only",
  1400. "im:chat.moderation:read",
  1401. "im:chat.tabs:read",
  1402. "im:chat.tabs:write_only",
  1403. "im:chat.top_notice:write_only",
  1404. "im:chat:delete",
  1405. "im:chat:moderation:write_only",
  1406. "im:chat:read",
  1407. "im:chat:update",
  1408. "im:message",
  1409. "im:message.group_msg:get_as_user",
  1410. "im:message.p2p_msg:get_as_user",
  1411. "im:message.pins:read",
  1412. "im:message.pins:write_only",
  1413. "im:message.reactions:read",
  1414. "im:message.reactions:write_only",
  1415. "im:message.urgent.status:write",
  1416. "im:message:readonly",
  1417. "im:message:recall",
  1418. "im:message:update",
  1419. "im:special_focus",
  1420. "llpp:model:write",
  1421. "llpp:resource",
  1422. "mail:event",
  1423. "mail:user_mailbox.mail_contact:read",
  1424. "mail:user_mailbox.mail_contact:write",
  1425. "mail:user_mailbox.message.address:read",
  1426. "mail:user_mailbox.message.body:read",
  1427. "mail:user_mailbox.message.subject:read",
  1428. "mail:user_mailbox:readonly",
  1429. "minutes:minute:download",
  1430. "minutes:minutes",
  1431. "minutes:minutes.artifacts:read",
  1432. "minutes:minutes.basic:read",
  1433. "minutes:minutes.media:export",
  1434. "minutes:minutes.search:read",
  1435. "minutes:minutes.statistics:read",
  1436. "minutes:minutes.transcript:export",
  1437. "minutes:minutes:readonly",
  1438. "offline_access",
  1439. "search:docs:read",
  1440. "search:message",
  1441. "sheets:spreadsheet.meta:read",
  1442. "sheets:spreadsheet.meta:write_only",
  1443. "sheets:spreadsheet:create",
  1444. "sheets:spreadsheet:read",
  1445. "sheets:spreadsheet:write_only",
  1446. "slides:presentation:create",
  1447. "slides:presentation:read",
  1448. "slides:presentation:update",
  1449. "slides:presentation:write_only",
  1450. "space:document.event:read",
  1451. "space:document:create",
  1452. "space:document:delete",
  1453. "space:document:move",
  1454. "space:document:retrieve",
  1455. "space:document:shortcut",
  1456. "space:folder:create",
  1457. "spark:app:read",
  1458. "spark:app:write",
  1459. "task:comment:write",
  1460. "task:task:read",
  1461. "task:task:write",
  1462. "task:tasklist:read",
  1463. "task:tasklist:write",
  1464. "vc:meeting",
  1465. "vc:meeting.bot.join:write",
  1466. "vc:meeting.meetingevent:read",
  1467. "vc:recording:read",
  1468. "vc:meeting.meetingid:read",
  1469. "vc:meeting.participant:write",
  1470. "vc:meeting.search:read",
  1471. "vc:meeting:export",
  1472. "vc:meeting:readonly",
  1473. "vc:note:read",
  1474. "vc:record",
  1475. "vc:record:readonly",
  1476. "vc:reserve",
  1477. "vc:reserve:readonly",
  1478. "wiki:member:create",
  1479. "wiki:member:retrieve",
  1480. "wiki:member:update",
  1481. "wiki:node:copy",
  1482. "wiki:node:create",
  1483. "wiki:node:move",
  1484. "wiki:node:read",
  1485. "wiki:node:retrieve",
  1486. "wiki:node:update",
  1487. "wiki:setting:read",
  1488. "wiki:setting:write_only",
  1489. "wiki:space:read",
  1490. "wiki:space:retrieve",
  1491. "wiki:space:write_only",
  1492. "wiki:wiki:readonly"
  1493. ]
  1494. }
  1495. }
  1496. ```
  1497. </details>
  1498. ## 技术栈
  1499. | 组件 | 选型 | 说明 |
  1500. |------|------|------|
  1501. | 语言 | [Go](https://go.dev/) 1.21+ | |
  1502. | CLI 框架 | [cobra](https://github.com/spf13/cobra) | 子命令、自动补全 |
  1503. | 飞书 SDK | [oapi-sdk-go/v3](https://github.com/larksuite/oapi-sdk-go) | 官方 SDK |
  1504. | 配置管理 | [viper](https://github.com/spf13/viper) | YAML / 环境变量 |
  1505. | Markdown | [goldmark](https://github.com/yuin/goldmark) | GFM 扩展支持 |
  1506. ## 项目结构
  1507. ```
  1508. feishu-cli/
  1509. ├── cmd/ # CLI 命令(每个子命令一个文件)
  1510. │ ├── root.go # 根命令、全局配置
  1511. │ ├── import_markdown.go # Markdown 导入(三阶段并发管道)
  1512. │ ├── export_markdown.go # 导出为 Markdown
  1513. │ └── ...
  1514. ├── internal/
  1515. │ ├── client/ # 飞书 API 封装(含资源 URL 解析、业务错误解析、流式下载)
  1516. │ ├── converter/ # Markdown ↔ Block 转换器
  1517. │ ├── config/ # 配置管理与受控 HTTP 客户端
  1518. │ ├── auth/ # OAuth Device Flow、Token 存储与刷新
  1519. │ ├── clierr/ apidiag/ # 退出码分类、API 错误诊断(log_id / 缺失 scope)
  1520. │ ├── safefile/ textutil/ # 本地路径安全与原子写、UTF-8 安全截断
  1521. │ ├── skillbundle/ skillinstall/ # 内嵌技能的读取与安装
  1522. │ └── selfupdate/ # feishu-cli update
  1523. ├── skills/ # Claude Code AI 技能文件
  1524. ├── main.go
  1525. ├── Makefile
  1526. └── install.sh # 一键安装脚本
  1527. ```
  1528. ## 开发
  1529. ```bash
  1530. # 克隆项目
  1531. git clone https://github.com/riba2534/feishu-cli.git
  1532. cd feishu-cli
  1533. # 安装依赖
  1534. go mod tidy
  1535. # 构建
  1536. make build # 输出到 bin/feishu-cli
  1537. make build-all # 多平台构建
  1538. # 测试
  1539. go test ./...
  1540. make check-skills # 重新构建并校验 Skill 结构与命令归属
  1541. make check-privacy # 隐私扫描(内部邮箱、企业前缀域名、疑似真实 token)
  1542. # 代码检查
  1543. go vet ./...
  1544. # 发版打包(规范命名 tar.gz + checksums.txt,输出到 dist/)
  1545. make release-package VERSION=vX.Y.Z
  1546. ```
  1547. ## 贡献
  1548. 欢迎提交 Issue 和 Pull Request!
  1549. 1. Fork 本仓库
  1550. 2. 创建特性分支:`git checkout -b feature/amazing-feature`
  1551. 3. 提交更改:`git commit -m 'feat: add amazing feature'`
  1552. 4. 推送分支:`git push origin feature/amazing-feature`
  1553. 5. 提交 Pull Request
  1554. 提交信息请遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范。
  1555. ## FAQ
  1556. <details>
  1557. <summary><b>什么时候需要 <code>auth login</code>?App Token 和 User Token 有什么区别?</b></summary>
  1558. 大部分读写操作用 **App(Bot)身份** 即可(只需 App ID/Secret)。以下能力必须 **User Token**(`feishu-cli auth login` 一次即可,token 自动刷新):搜索(docs/messages/apps)、审批任务操作、邮箱全部、vc/minutes 全部、`drive upload/download/add-comment/task-result/search/secure-label` 等。`markdown create/fetch/overwrite/patch/diff` 与 `drive import/export/export-download/move` 支持 `--as bot|user|auto`(默认 auto:User 优先;未配置回退 Bot;已配置但刷新失败 fail-closed,不会静默切 Bot)。命令级要求见各命令 `--help`;`feishu-cli auth check --scope "..."` 可在执行前预检。
  1559. </details>
  1560. <details>
  1561. <summary><b>操作外部群报 <code>232033</code> 怎么办?</b></summary>
  1562. 外部群(跨租户)的「群信息/成员/配置」类 API 默认拒绝,需要:① App 开启「对外共享能力」;② 该 App 的 Bot 已加入此群。临时切换:`FEISHU_APP_ID=cli_xxx FEISHU_APP_SECRET=xxx feishu-cli <命令> --as bot`。注意 `msg history` / `msg send` 等消息侧 API 不受此限制。
  1563. </details>
  1564. <details>
  1565. <summary><b>bitable 操作报 <code>91403 no permission</code>?</b></summary>
  1566. 不是 token 问题,是 Bot 还不是这张多维表格的协作者。执行 `feishu-cli perm add <base_token> --doc-type bitable --member-type open_id --member-id <bot_open_id> --perm full_access`,或将文档可见性调整为组织内可见。
  1567. </details>
  1568. <details>
  1569. <summary><b>用 CLI 导入的文档,自己在飞书里看不到?</b></summary>
  1570. `doc import` 默认以 Bot 身份建档,文档归属于应用。已 `auth login` 时,CLI 会在 Bot 创建文档、表格、多维表格、文件夹、知识库节点、演示文稿后自动给当前登录用户授予 `full_access`(输出中的 `permission_grant` 字段给出结果);未登录时会在 stderr 提示。也可手动授权:`feishu-cli perm add <doc_id> --doc-type docx --member-type email --member-id you@example.com --perm full_access`,或配置 `owner_email` 让技能流程转移所有权(见 AI 技能集成)。
  1571. </details>
  1572. <details>
  1573. <summary><b>报 <code>99991672</code> / <code>99991679</code> scope 不足?</b></summary>
  1574. `99991672` 是应用(tenant)权限未开通,重新登录无法解决——按错误信息里的开放平台链接为应用开通并发布版本,或直接导入上方[完整权限清单](#完整权限清单);`99991679` 是用户授权缺 scope——`feishu-cli auth login --scope "<所需 scope>"` 增量授权即可。两者都以退出码 3 结束,错误信息附带缺失的 scope 与 log_id。`feishu-cli auth scopes --scope "<scope>"` 可以逐项诊断是应用未开通还是用户未授权。
  1575. </details>
  1576. ## 更新日志
  1577. 每个版本的完整变更记录见 [CHANGELOG.md](CHANGELOG.md),发布产物与安装包见 [Releases](https://github.com/riba2534/feishu-cli/releases)。
  1578. ## Star History
  1579. <a href="https://star-history.dera.page/#riba2534/feishu-cli&Date">
  1580. <picture>
  1581. <source media="(prefers-color-scheme: dark)" srcset="https://star-history.dera.page/svg?repos=riba2534/feishu-cli&type=Date&theme=dark" />
  1582. <source media="(prefers-color-scheme: light)" srcset="https://star-history.dera.page/svg?repos=riba2534/feishu-cli&type=Date" />
  1583. <img alt="Star History Chart" src="https://star-history.dera.page/svg?repos=riba2534/feishu-cli&type=Date" />
  1584. </picture>
  1585. </a>
  1586. > 图表由 star-history.dera.page 生成,若上方未加载出来(该服务偶发超时),可直接[查看交互式 Star 增长曲线](https://star-history.dera.page/#riba2534/feishu-cli&Date)。
  1587. ## License
  1588. [MIT](LICENSE)。部分实现与技能文档改编自 [larksuite/cli](https://github.com/larksuite/cli)(MIT),版权与许可声明见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
  1589. ## 相关链接
  1590. - [飞书开放平台](https://open.feishu.cn/) — 创建应用、获取凭证
  1591. - [飞书 API 文档](https://open.feishu.cn/document/) — 接口参考
  1592. - [Claude Code](https://claude.ai/claude-code) — AI 编程助手
  1593. - [HappyClaw](https://github.com/riba2534/happyclaw) — 基于 Claude Agent SDK 的自托管多用户 AI Agent 系统

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.