riba2534/feishu-cli

feishu-cli

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

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

---

feishu-cli 是什么

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

除了传统的 CLI 用法，feishu-cli 还为 Claude Code 等 AI 编程助手提供了 9 个开箱即用的领域技能（Skill），让 AI Agent 能够直接创建文档、发送消息、管理权限——无需任何额外配置。

注意：feishu-cli 主要面向 AI Agent（如 Claude Code）使用，通过技能文件让 AI 直接操控飞书。虽然人类也可以直接使用命令行，但大多数场景下建议通过 AI Agent 调用，体验更佳。

为什么选择 feishu-cli

• 双向转换零损耗 — 支持 40+ 种块类型，Markdown 导入飞书后再导出，内容完整保留
• 图表原生渲染 — Mermaid（8 种图表类型）和 PlantUML 自动转换为飞书画板，不是截图，是可编辑的矢量图
• 大规模文档处理 — 三阶段并发管道架构，实测 10,000+ 行 / 127 个图表 / 170+ 个表格一次导入
• P2P 私聊原生可读 — msg history --user-email 一条命令打通「搜用户 → 反查 p2p chat_id → 读消息」，输出自动带 sender_names 映射，AI Agent 直接拿结构化带名消息流，无需额外查群成员
• AI Agent 原生 — 9 个领域技能覆盖飞书全功能（503 个命令全部归属），AI 助手即装即用
• 为脚本与 Agent 设计的健壮性 — 错拼命令/flag 报错并给拼写建议（绝不静默成功）、写操作 --dry-run、幂等键防重发、统一 --jq/--format 结构化输出
• 一个工具覆盖全平台 — 文档、知识库、表格、多维表格、消息、邮箱、日历、任务、考勤、OKR、视频会议、妙记、云盘、权限、画板、Slides、事件、Schema、Profile、健康检查

三十秒上手

# 1. 安装（自动识别平台，含 sha256 完整性校验）
curl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash

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

# 3. 把 Markdown 变成飞书文档
feishu-cli doc import README.md --title "我的第一篇文档"

需要用户身份的能力（搜索、审批、邮箱等）再执行 feishu-cli auth login 完成 OAuth 授权即可。详见快速开始。

核心能力

Markdown ↔ 飞书文档

将本地 Markdown 文件一键上传到飞书，或将飞书文档导出为 Markdown。支持完整语法转换：

# 导入：Markdown → 飞书文档
feishu-cli doc import report.md --title "技术报告" --verbose

# 导出：飞书文档 → Markdown
feishu-cli doc export  -o doc.md --download-images

支持的语法：标题（6 级）、段落、列表（无限深度嵌套）、任务列表、代码块、引用、Callout（6 种类型）、同步块（含跨文档引用）、表格（自动拆分）、分割线、图片、链接、公式、粗体 / 斜体 / 删除线 / 下划线 / 行内代码 / 高亮。跨文档同步块无法读取时会保留带源标识的 WARNING 占位并输出诊断，不会静默导出为空。

Mermaid / PlantUML 图表

Markdown 中的 Mermaid 和 PlantUML 代码块自动转换为飞书画板（可编辑矢量图，非截图）：

```mermaid
flowchart TD
    A[开始] --> B{判断}
    B -->|是| C[处理]
    B -->|否| D[结束]
```

PlantUML 同样支持：时序图、活动图、类图、用例图、组件图、ER 图、思维导图等全部类型（```plantuml 或 ```puml）。

大规模实测导入成功率 >90%，失败图表自动降级为代码块并保留原文，不阻断整篇导入。

智能表格处理

• 列宽自动计算 — 根据内容智能调整，中英文字符区分宽度（中文 14px，英文 8px）
• 列宽自定义（v1.29+，issue #156）— 支持紧邻表格上方注释 ``（单位 px / 百分比 / * 走 auto）或 CLI flag --table-column-width=auto|fixed|N1,N2,... 全局覆盖；注释优先级高于 flag。仅 doc import / doc add 支持——doc content-update 走官方原子更新协议不支持自定义列宽，传非 auto 的 flag 或内容含该注释都会报错
• 大表格保持单表连贯 — 行数超过飞书 create_block 9 行限制时，先创建 9 行初始表，剩余行通过 insert_table_row API 追加到同一个 block，视觉上为一张连贯的表，不再拆成多张独立表格
• 批量填充加速（v1.29+，issue #159）— 单元格填充改用 batch_update API（每批 ≤30）+ 文档级 3 QPS 节流，典型 4×6×8 表场景从 ~70s 降到 ~3s
• 单元格多块内容 — 支持 bullet / heading / text 混合内容

三阶段并发管道

导入大文档时，feishu-cli 使用三阶段并发管道最大化吞吐量：

1. 阶段一（顺序） — 按文档顺序创建所有块，收集图表和表格任务
2. 阶段二（并发） — 图表 worker 池 + 表格 worker 池并发处理
3. 阶段三（逆序） — 处理失败图表，降级为代码块

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

全功能 API 覆盖

快速开始

安装

一键安装（推荐）

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

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

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

配置凭证

一键创建应用（推荐）

无需手动访问飞书开放平台后台，一条命令自动完成应用注册：

# 自动创建飞书应用并保存凭证到 ~/.feishu-cli/config.yaml
feishu-cli config create-app --save

执行后终端会输出一个授权链接，用飞书扫码确认即可。CLI 自动获取 App ID 和 App Secret 并写入配置文件，后续命令直接可用。

然后在飞书开放平台的应用权限管理页面为新创建的应用开通所需 scope。最快的方式是复制 权限要求 章节的 JSON，在权限管理页面的 导入权限 入口粘贴即可一次性申请全部。

（可选）如果需要使用搜索、审批任务查询等需要用户身份的功能，还需完成 OAuth 用户授权：

feishu-cli auth login

验证安装

feishu-cli doc create --title "Hello Feishu"

如果返回文档 ID，说明配置成功。

命令参考

feishu-cli  [subcommand] [flags]

Commands:
  doc       文档操作（创建、导入、导出、编辑、异步导出/导入文件）
  wiki      知识库操作（节点增删改查、空间详情、成员管理）
  sheet     电子表格（读写、样式、batch-set-style、V3 富文本 API、导出 XLSX/CSV、image、filter-view + condition、dropdown）
  bitable   多维表格（base/v3 + bitable/v1：数据表/字段/记录/附件/视图/仪表盘/表单/角色/权限/聚合/工作流，88 命令）
  msg       消息操作（发送、转发、合并转发、回复、Pin、表情回复、书签、批量获取、资源下载）
  chat      群聊管理（创建、更新、删除、群列表、成员管理）
  mail      邮箱操作（分类/搜索、发送、草稿含发送、回复、转发、批量改 label/软删、CID 内联图片、模板、签名）
  drive     云盘增强（分块/覆盖上传、流式下载、异步导出/导入、移动、评论、镜像 pull/push、密级标签，15 命令）
  markdown  Drive 原生 Markdown 文件 CRUD（.md 整体读写、版本比对，不转换 docx 块）
  vc        视频会议（多维搜索、聚合详情、智能纪要 note、会议纪要、录制查询、机器人入会/离会/事件）
  minutes   妙记操作（详情 + AI 产物、搜索、权限申请、媒体批量下载）
  apps      妙搭（Miaoda）应用（创建、发布 HTML、修改、访问范围管理）
  file      文件管理（列出、移动、复制、删除、上传、下载、版本管理）
  media     素材操作（上传、下载）
  perm      权限管理（添加、删除、批量添加、公开权限、密码、转移所有权）
  calendar  日历操作（日程增删改查、搜索、参与者、忙闲查询、agenda、suggestion、room-find、rsvp）
  task      任务操作（增删改查、服务端搜索、子任务、成员、提醒、评论、附件、我的任务）
  tasklist  任务清单管理（CRUD、任务关联、成员管理）
  attendance 考勤操作（打卡记录查询、统计数据查询）
  okr       OKR 操作（周期列表/详情、进展记录 CRUD、进展图片上传、--as 身份）
  slides    Slides 演示文稿（创建、媒体上传）
  user      用户操作（获取信息、搜索、部门用户列表）
  dept      部门操作（详情、子部门列表）
  board     画板操作（精排绘图、图表导入、克隆、几何质检 lint、SVG 双向、图片上传、覆盖更新）
  comment   评论操作（列出、添加、解决/恢复、回复管理）
  approval  审批操作（定义/实例详情、已发起列表、任务查询、实例创建/撤回/抄送、任务通过/拒绝/转交；全部 User Token）
  search    搜索操作（消息、应用、文档）
  event     实时事件订阅（WebSocket 长连接、list/schema/consume/status/stop）
  schema    本地浏览飞书 OpenAPI 方法（无需 token）
  api       通用 OpenAPI 透传调用（任意 method/path，自动鉴权 + 错误码翻译，覆盖 2500+ 端点）
  profile   多 App / 多账号配置切换
  doctor    环境健康检查（config/user_token/endpoints/proxy/deps）
  auth      身份认证（OAuth 登录、状态、退出、scope 预检）
  config    配置管理

AI 技能集成

skills/ 目录包含 9 个领域 Skill。每个领域 Skill 在 references/workflows/ 下按需加载细粒度工作流，减少常驻上下文，同时覆盖完整 CLI 能力。

Skill 入口使用 Agent Skills 标准 frontmatter；按需加载的工作流和脚本随目录一起分发。 本版本技能与 feishu-cli v1.41.0+ 配套使用；聊天导出脚本需要 Python 3.10+， 可视化工作流按需使用 Node.js、whiteboard-cli 或 agent-browser，具体依赖见对应入口的 compatibility。 各宿主对工具授权字段的解释可能不同，不能把 allowed-tools 当作跨宿主的执行保证。

维护时从仓库根运行 make check-skills。它会重新编译 CLI，检查 YAML 元数据、引用、 命令归属和示例参数，再执行脚本回归与本地模拟 API 的二进制契约测试。 这些检查不等同于线上 API 验证或模型触发评测；后两者需要分别执行并记录模型、身份和实际结果。 skills/trigger-evals.json 保留各领域的 8 个正例，scripts/build_trigger_eval_set.py 为每个领域生成 8 正例加 8 个相邻领域负例；skills/trigger-boundary-evals.json 另存跨领域和不应触发的场景。

安装方法：

# 一键安装全部技能（推荐）
npx skills add riba2534/feishu-cli --global --yes --agent claude-code --copy

# 或手动复制
# 将 skills/ 目录复制到 ~/.claude/skills/

块类型映射

权限要求

💡 推荐做法：一键创建机器人

新用户不需要手动去飞书开放平台后台创建应用，feishu-cli 自带 Device Flow 协议的一键创建机器人工作流，在终端扫码确认即可自动注册「个人代理应用」：

# 1. 一键创建飞书应用（扫码确认后自动把 App ID / App Secret 写入 ~/.feishu-cli/config.yaml）
feishu-cli config create-app --save

# 2. OAuth 用户授权（搜索、审批等需要用户身份的功能）
feishu-cli auth login

关于权限：创建应用后，你需要在飞书开放平台的应用权限管理页面为应用开通所需 scope。下面的完整权限清单可以直接在权限管理页面粘贴 JSON 导入，一次性开通全部功能。

权限的开通是你自己的责任（飞书开放平台一般需要 tenant 管理员审批），feishu-cli 不做自动化。

完整权限清单

feishu-cli 涵盖文档、知识库、电子表格、多维表格、消息、群聊、日历、任务、审批、OKR、画板、权限管理、搜索、视频会议、妙记、邮件等全部功能。下面这份 JSON 可以直接在飞书开放平台的应用权限管理页面一次性导入（tenant 199 条 + user 237 条）：

技术栈

项目结构

feishu-cli/
├── cmd/                          # CLI 命令（每个子命令一个文件）
│   ├── root.go                   # 根命令、全局配置
│   ├── import_markdown.go        # Markdown 导入（三阶段并发管道）
│   ├── export_markdown.go        # 导出为 Markdown
│   └── ...
├── internal/
│   ├── client/                   # 飞书 API 封装
│   ├── converter/                # Markdown ↔ Block 转换器
│   └── config/                   # 配置管理
├── skills/                       # Claude Code AI 技能文件
├── main.go
├── Makefile
└── install.sh                    # 一键安装脚本

开发

# 克隆项目
git clone https://github.com/riba2534/feishu-cli.git
cd feishu-cli

# 安装依赖
go mod tidy

# 构建
make build              # 输出到 bin/feishu-cli
make build-all          # 多平台构建

# 测试
go test ./...
make check-skills       # 重新构建并校验 Skill 结构与命令归属

# 代码检查
go vet ./...

贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'feat: add amazing feature'
4. 推送分支：git push origin feature/amazing-feature
5. 提交 Pull Request

提交信息请遵循 Conventional Commits 规范。

FAQ

更新日志

每个版本的完整变更记录见 CHANGELOG.md，发布产物与安装包见 Releases。

Star History

图表由 star-history.dera.page 生成，若上方未加载出来（该服务偶发超时），可直接查看交互式 Star 增长曲线。

License

MIT

相关链接

• 飞书开放平台 — 创建应用、获取凭证
• 飞书 API 文档 — 接口参考
• Claude Code — AI 编程助手
• HappyClaw — 基于 Claude Agent SDK 的自托管多用户 AI Agent 系统