让 AI 助手直接操控飞书文档的命令行工具（feishu-cli）

飞书把文档、表格、消息、日历、审批都装进了同一套系统，团队越大，堆在里面的东西越多。这些内容一旦要跟本地文件、代码仓库、脚本打通，官方给的入口就只有两个：网页上点鼠标，或者自己翻开放平台文档写代码。想做批量导出、批量建文档、定时拉数据，就得反复拼 API。

feishu-cli 是一个用 Go 写的飞书开放平台命令行工具，输入 Markdown 或命令参数，输出飞书文档、消息、表格等云端数据，也能反向导出为 Markdown。

仓库地址是 https://github.com/riba2534/feishu-cli，MIT 许可证，主要语言 Go（占比 93.2%），另有少量 Python、JavaScript 与 Shell。截取时 Star 1413、Fork 143、Watcher 3、开放 Issue 0，仓库体积 7125 KB，创建于 2026-01-21，最近一次提交在 2026-09-22。README 里有一句需要提前知道的话：这个项目主要面向 AI Agent（例如 Claude Code）使用，人类当然也能直接敲命令行，但多数场景下作者建议由 AI Agent 调用。

它和一般「调 API 的小脚本」的差别在规模上。命令面覆盖文档、知识库、电子表格、多维表格、消息、邮箱、日历、任务、视频会议、妙记、审批、考勤、OKR、权限、云盘、画板、Slides、评论、搜索、通讯录、实时事件等 20 多个模块，README 提到 503 个命令全部归属到 9 个领域技能里。对做飞书自动化的人来说，这意味着多数需求不用自己写胶水代码。

主要功能

Markdown 与飞书文档双向转换。这是项目的核心能力。导入把本地 Markdown 变成飞书云文档，导出把飞书文档拉回本地 Markdown。支持 40 多种块类型：6 级标题、无限深度嵌套列表、任务列表、代码块、引用、6 种 Callout、同步块、表格、分割线、图片、链接、公式，以及粗体、斜体、删除线、下划线、行内代码、高亮。跨文档引用的同步块读不出来时，Markdown 里会留一段带源标识的 WARNING，并在 stderr 输出诊断，不会静默导出成空。

feishu-cli doc import report.md --title "技术报告" --verbose
feishu-cli doc export <document_id> -o doc.md --download-images

图表转成飞书画板。Markdown 里的 Mermaid 和 PlantUML 代码块会自动转成飞书画板，产出的是可编辑矢量图，不是截图。Mermaid 支持 8 种类型：flowchart、sequenceDiagram、classDiagram、stateDiagram-v2、erDiagram、gantt、pie、mindmap。PlantUML 支持时序图、活动图、类图、用例图、组件图、ER 图、思维导图等类型，用 ```plantuml 或 ```puml 声明。README 说大规模实测导入成功率超过 90%，失败的图表降级为代码块并保留原文，不阻断整篇导入。

表格处理。列宽按内容自动计算，中文按 14px、英文按 8px 区分。v1.29 起可以自定义列宽，写在紧邻表格上方的注释里，或从命令行传 --table-column-width=auto|fixed|N1,N2,... 全局覆盖，注释优先级高于 flag。行数超过飞书 create_block 的 9 行限制时，先创建 9 行初始表，剩余行用 insert_table_row 追加到同一个 block，视觉上保持一张连贯的表。单元格填充走 batch_update，每批不超过 30 个，文档级节流 3 QPS。

三阶段并发管道。大文档导入分三步走：阶段一按文档顺序创建所有块，同时收集图表和表格任务；阶段二用图表 worker 池和表格 worker 池并发处理；阶段三逆序处理失败图表，降级为代码块。并发数在命令行控制。README 给出的实测场景是 10000+ 行、127 个图表、170 多个表格一次导入。

feishu-cli doc import large-doc.md --title "大文档" --upload-images --diagram-workers 5 --table-workers 3 --image-workers 2 --verbose

消息与私聊历史。发送和回复共用一套内容模型，涵盖 text、Markdown、post、image、file、audio、video、card，本地媒体自动上传，支持幂等键防重复发送。历史记录支持群聊和 P2P 私聊，用 --user-email 或 --user-id 可以自动反查到 p2p chat_id，输出顶层带 sender_names 映射，退群成员也能给出名字。邮箱模块同样在这一层：收件箱分类与搜索、邮件详情、发送（默认草稿）、草稿管理、批量改 label 或移动文件夹、批量软删进废纸篓。

覆盖面很宽的模块。文档之外还有知识库、电子表格（V2 基础读写加 V3 富文本 API）、多维表格（base/v3 与 bitable/v1）、群聊、日历、任务、视频会议、妙记、审批、考勤、OKR、权限、云盘、画板、Slides、评论、搜索、用户、通讯录、实时事件。v1.41.0 新增原生单元格图片批量写入 sheet image write-batch，支持文件、stdin 和行内 manifest 三种输入，并发下载、串行写入、自动回读验证；BMP/TIFF/WebP 自动转 PNG，无后缀图片自动补齐扩展名。

面向 AI Agent 的 9 个领域技能。仓库里带 skills/ 目录，为 Claude Code 这类编程助手提供 9 个开箱即用的技能，503 个命令全部有归属。这是作者推荐的主要用法。技能元数据和路由边界在 v1.41.0 做过统一，修正了多个技能的命令说明与脚本成功判定。

Raw API 兜底。碰到还没封装进命令的接口，可以用 api GET/POST/PUT/DELETE/PATCH <path> 直接裸调任意 OpenAPI 路径，工具负责自动鉴权和错误码处理，支持 dry-run、自定义超时和 jq 过滤。

安装与依赖

官方提供一键安装脚本，自动识别平台并做 sha256 完整性校验：

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

README 的徽章标注 Go 1.21+。仓库里有 install.sh、Makefile、go.mod 和 main.go，想从源码构建可以自己编译，仓库里没有把源码编译步骤单独写成一节。运行时依赖是飞书开放平台的一套应用凭证，另外需要网络能访问飞书开放域。

最短能跑通的用法

README 的三十秒上手给了三步，前两步如下：

# 1. 创建一个飞书应用并保存凭证（Device Flow，免手工建应用）
feishu-cli config create-app --save

# 2. 把 Markdown 导入为飞书文档
feishu-cli doc import README.md --title "我的第一篇文档"

搜索、审批、邮箱这类需要用户身份的能力，再执行一次 OAuth 授权。登录时可以指定 scope：

feishu-cli auth login --scopes "search:docs:read search:message offline_access"

授权模式上，早期版本只支持用 FEISHU_APP_ID 加 FEISHU_APP_SECRET 换 tenant_access_token（应用身份），后来加入了 User Access Token（OAuth 用户授权）与 device flow，才解决了「应用必须被显式加为文档协作者才能读文档」这个限制。

关键参数

多 Bot 身份支持是 v1.39.0 引入的，把「用哪个目录 / User Token」和「用哪套 App 凭证」拆成两条独立的解析链。优先级顺序是：

• 目录 / User Token：--profile > FEISHU_PROFILE > active-profile 指针 > 旧布局
• App 凭证：--bot-app-id / --bot-app-secret > FEISHU_APP_ID / FEISHU_APP_SECRET > 选中目录的 config.yaml

结构化输出统一走 --jq 和 --format。写操作可以先跑 --dry-run 看会发什么请求，--verbose 打印详细过程。导入大文档时用 --diagram-workers、--table-workers、--image-workers 控制并发。图片上传与下载由 --upload-images、--download-images 控制。

表格列宽参数 --table-column-width=auto|fixed|N1,N2,... 只在 doc import 和 doc add 上生效。README 明确说明 doc content-update 走官方原子更新协议，不支持自定义列宽，传非 auto 的 flag 或内容里含该注释都会报错。这一点容易踩，改动文档时换命令就会失效。

结果在哪里看

导入的文档落在飞书云文档里，命令会返回文档标识，可以直接在飞书里打开查看。导出结果写在本地，路径由 -o 指定，比如 -o doc.md，加上 --download-images 会把文档里的图片一并拉到本地。终端输出是结构化的 JSON，也可以用 --jq 过滤出想要的字段；出错信息走 stderr，例如跨文档同步块读不到时会输出 WARNING 占位和诊断。知识库导出支持整树递归镜像，云盘还提供本地镜像的 pull / push / status 子命令，适合需要把远端目录同步到本地的场景。

实际使用中的坑

仓库的 Issue 列表里能翻到一批真实踩坑记录，下面这些目前都标为已解决。

• 登录后 token.json 里的 refresh_token 为空（v1.17.0 时期）。用户用 feishu-cli auth login --scopes "search:docs:read search:message offline_access" 登录，拿到的凭证缺少刷新令牌，长时间运行的任务会中途失效。已解决。
• 多维表格记录搜索直接报错。执行 feishu-cli bitable record search --base-token xxx --table-id tblxxx 时返回 code=800010701，提示请求校验失败。已解决。
• 网页授权时重定向 URL 有误，feishu-cli auth login 在浏览器里显示重定向失败，无法完成授权。已解决。
• 写入命令用的是应用身份，编辑不了自己有权限但没把应用加成协作者的文档，报 code=1770032。涉及 doc update、doc add、doc delete、doc import --document-id 等命令，后来通过支持 User Access Token 解决。
• 导出含嵌入多维表格或电子表格的文档时，输出的是 XML 占位标签而不是可读的 Markdown 表格。已解决。

v1.40.0 那次发布的主题就是「深度 review + 实物验证」，修掉了一批静默出错的问题，比如 mail triage 此前 100% 失败、sheet write 写布尔值整批失败。如果用的是较早版本，遇到「命令没报错但结果不对」，先查一下是不是落在这些修复之前。

和同类放在一起看

如果要的是「人坐在电脑前，有个窗口能跟同事聊天」，feishu-cli 给不了，它没有图形界面，全部操作在终端里完成，这类需求应该去看 HuLa 那类客户端。另外它绑定飞书一家平台，同时还要求你手上有可用的开放平台应用凭证与授权流程，如果团队主要用微信或企业微信做开发对接，WxJava 那种按语言生态分发的 SDK 更顺手，接入方式也只是一条依赖声明。feishu-cli 的价值集中在飞书这一侧，尤其是把内容搬进搬出、再交给 AI Agent 批量执行的部分。

授权与合规前提

feishu-cli 能读取和写入的是组织内部的真实数据，包括文档内容、群聊与私聊历史、邮件、审批记录、考勤统计。这些能力只应当用在自己拥有账号权限的飞书租户，以及已经获得组织明确授权的资源上。

把应用凭证、User Access Token 或导出的聊天记录交到第三方，可能同时违反飞书开放平台的开发者协议和企业内部的数据安全规定。批量导出聊天记录、考勤数据这类行为，在国内还要考虑个人信息保护相关的法律要求。给这个工具挂上定时任务、让它自动读取全员数据之前，先确认你有这个权限。

适合谁

适合团队协作基本都在飞书上、需要把文档和表格批量搬进搬出的人，比如要定期把仓库里的 Markdown 发布成内部文档，或者把飞书里的会议纪要、周报汇总到本地。也适合已经用 Claude Code 这类编程助手工作、想让助手直接读文档、发消息、建表格的开发者，9 个技能装上就能用。

不适合想要图形界面的人，也不适合目标平台不在飞书生态的团队。如果你的需求只是偶尔手动导出几篇文档，飞书网页版本身就能完成，装一套命令行工具再配好应用凭证和授权，成本比收益高。仓库开放 Issue 为 0，出问题时能参考的主要是 CHANGELOG 和 Issue 历史，中文文档倒是齐全，README 就有 85 KB。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.3 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。