By Jermine

☰

飞书文档和本地笔记能否打通？数据散落在飞书、Obsidian 各个平台，每个都是孤岛——想找一篇半年前写的东西，得在四个后台翻十分钟。

本文介绍 feishu-cli（riba2534/feishu-cli），一个把飞书开放平台封装为命令行工具的开源项目，让内容在飞书和 Obsidian 之间双向流动。

先说结论：为什么一定要打通？

知识工作者的普遍痛点：

  • 飞书有几篇写了一半的文章，Obsidian 里存了一堆笔记
  • 想从飞书归档文章到本地，只能手动复制粘贴
  • Obsidian 写的笔记想发到飞书协作，格式乱成一团
  • 飞书多维表格里的选题库想同步到本地管理

核心需求不是把东西搬到一个地方，而是需要的时候，数据能在两个世界自由流动。飞书适合协作和分享，Obsidian 适合沉淀和思考。

feishu-cli 的核心能力是 Markdown ↔ 飞书文档的双向无损转换。它支持 40+ 种块类型，导入再导出内容完整保留。加上 Mermaid/PlantUML 图表原生渲染、大文档三阶段并发管道等特性，是一个专门为"打通飞书内外"而设计的工具。

第一章：feishu-cli 到底是什么

feishu-cli 是 GitHub 用户 riba2534 开源的飞书命令行工具，Go 语言编写，MIT 许可证。

  • GitHub 地址：https://github.com/riba2534/feishu-cli
  • 安装方式：curl -fsSL https://raw.githubusercontent.com/riba2534/feishu-cli/main/install.sh | bash
  • 核心定位：Markdown ↔ 飞书文档双向转换，兼顾 AI Agent 操控飞书

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

为什么选择 feishu-cli

能力 说明
双向转换零损耗 40+ 种块类型，Markdown 导入飞书后再导出，内容完整保留
图表原生渲染 Mermaid 和 PlantUML 自动转换为飞书画板，可编辑矢量图，非截图
大规模文档处理 三阶段并发管道架构，实测 10000+ 行 / 127 个图表 / 170+ 个表格一次导入
AI Agent 原生 27 个技能文件覆盖飞书全功能，AI 助手即装即用
一个工具覆盖全平台 文档、知识库、表格、消息、邮箱、日历、任务、考勤、OKR、会议等

第二章：安装和授权

安装

一键安装（推荐）：

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

此命令会自动检测操作系统和架构，下载最新版本并安装到 /usr/local/bin。已安装的用户执行同样的命令即可更新。

其他安装方式：

1# go install
2go install github.com/riba2534/feishu-cli@latest
3
4# 从 Releases 页面下载
5# https://github.com/riba2534/feishu-cli/releases/latest
6tar -xzf feishu-cli_*_linux-amd64.tar.gz
7sudo mv feishu-cli_*/feishu-cli /usr/local/bin/

验证安装：

1feishu-cli --version

配置凭证

一键创建应用（推荐）：

1feishu-cli config create-app --save

这条命令会自动在飞书开放平台创建应用，获取 App ID 和 App Secret 并写入 ~/.feishu-cli/config.yaml。执行后终端会输出一个授权链接，用飞书扫码确认即可。

然后在飞书开放平台的应用权限管理页面，为新创建的应用开通所需权限。最快的方式是复制 feishu-cli 文档中的权限要求 JSON，在权限管理页面通过导入权限功能一次性申请全部。

手动配置（不推荐）：

如果已有飞书应用，也可以手动配置：

1# 方式一：环境变量
2export FEISHU_APP_ID="cli_xxx"
3export FEISHU_APP_SECRET="xxx"
4
5# 方式二：配置文件
6feishu-cli config init   # 生成模板后填入凭证

用户授权（可选）：

如果需要使用搜索、审批任务查询等需要用户身份的功能：

1feishu-cli auth login

多 App / 多账号配置

feishu-cli 支持多 profile 管理：

1feishu-cli profile add --name work    # 添加工作账号
2feishu-cli profile add --name personal  # 添加个人账号
3feishu-cli profile use work           # 切换到工作账号
4feishu-cli profile current            # 查看当前账号
5feishu-cli profile list               # 列出所有账号

第三章：核心操作

3.1 从飞书读取文档到本地

将飞书文档导出为本地 Markdown 文件：

1# 导出文档为 Markdown（含图片下载）
2feishu-cli doc export <document_id> -o doc.md --download-images
3
4# 导出知识库节点
5feishu-cli wiki node export <node_id> -o wiki-doc.md

3.2 把 Obsidian 文章上传到飞书

1# 导入 Markdown 文件为飞书文档
2feishu-cli doc import article.md --title "文章标题" --verbose
3
4# 带图片上传
5feishu-cli doc import article.md --title "文章标题" --upload-images

3.3 更新飞书文档

1feishu-cli doc update <document_id> --title "新标题" -f updated.md

3.4 搜索飞书文档

1# 搜索文档（需 User Token）
2feishu-cli search document --query "关键词"
3
4# 搜索消息
5feishu-cli search message --query "关键词"

3.5 操作飞书多维表格

1# 列出所有记录
2feishu-cli bitable record list --app-token xxx --table-id yyy
3
4# 新增记录
5feishu-cli bitable record create --app-token xxx --table-id yyy \
6  --fields '{"标题":"测试","状态":"进行中"}'
7
8# 批量获取
9feishu-cli bitable record batch-get --app-token xxx --table-id yyy

3.6 操作飞书知识库

 1# 列出知识库空间
 2feishu-cli wiki space list
 3
 4# 获取空间详情
 5feishu-cli wiki space get --space-id xxx
 6
 7# 获取节点内容
 8feishu-cli wiki node get --node-id xxx
 9
10# 导出知识库节点
11feishu-cli wiki node export --node-id xxx -o output.md

3.7 发消息

1# 发送文本消息到群聊
2feishu-cli msg send --chat-id xxx --msg-type text --content "Hello"
3
4# 查看私聊历史（通过邮箱搜用户自动反查 chat_id）
5feishu-cli msg history --user-email user@company.com
6
7# 查看群聊历史
8feishu-cli msg history --chat-id xxx

第四章：和 Obsidian 配合的工作流

场景一：飞书文档 → Obsidian 归档

定期将飞书上的协作文档批量归档到本地 Obsidian 知识库：

1# 导出单篇文档
2feishu-cli doc export <document_id> -o "obsidian-vault/归档/文档标题.md" --download-images
3
4# 批量导出知识库节点
5feishu-cli wiki node export --node-id xxx -o "obsidian-vault/归档/"

导出的 Markdown 文件可以直接放入 Obsidian vault 中，图片也会一并下载到本地。

场景二：Obsidian 文章 → 飞书协作

在 Obsidian 中写好的文档，一键上传到飞书分享给团队协作：

1# 导入 Markdown，自动处理 Mermaid 图表和图片
2feishu-cli doc import "obsidian-vault/文章.md" \
3  --title "$(head -1 "obsidian-vault/文章.md" | sed 's/^# //')" \
4  --upload-images --verbose

feishu-cli 会自动将 Markdown 中的 Mermaid 代码块转换为飞书画板（可编辑矢量图），图片上传至飞书图床。

场景三：用飞书多维表格管理选题和进度

在飞书多维表格中管理的选题列表，可以通过 CLI 读取到本地归档：

1# 读取多维表格记录
2feishu-cli bitable record list --app-token xxx --table-id yyy --format json > topics.json

也可以将本地的选题数据批量写入多维表格：

1feishu-cli bitable record create --app-token xxx --table-id yyy \
2  --fields "$(cat topic.json)"

第五章：进阶能力

Markdown ↔ 飞书文档双向转换

feishu-cli 的核心卖点是格式转换的完整性。它支持：

  • 40+ 种块类型：标题（6 级）、段落、列表（无限深度嵌套）、任务列表、代码块、引用、Callout（6 种类型）、表格（自动拆分）、分割线、图片、链接、公式、粗体/斜体/删除线/下划线/行内代码/高亮
  • 图表原生渲染：Mermaid（8 种图表类型）和 PlantUML 转换为飞书画板，不是截图，是可编辑的矢量图

Mermaid 支持类型：

图表类型 声明
流程图 flowchart TD / flowchart LR
时序图 sequenceDiagram
类图 classDiagram
状态图 stateDiagram-v2
ER 图 erDiagram
甘特图 gantt
饼图 pie
思维导图 mindmap

实测数据：88 个 Mermaid 图表导入成功率 93.2%，失败图表自动降级为代码块。

三阶段并发管道

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

  1. 阶段一（顺序） — 按文档顺序创建所有块，收集图表和表格任务
  2. 阶段二（并发） — 图表 worker 池 + 表格 worker 池并发处理
  3. 阶段三（逆序） — 处理失败图表，降级为代码块
1feishu-cli doc import large-doc.md --title "大文档" \
2  --upload-images --diagram-workers 5 --table-workers 3 --image-workers 2 --verbose

智能表格处理

  • 列宽自动计算（中英文字符区分宽度）
  • 支持自定义列宽注释 <!-- feishu-colwidth: 80,200,*,30% -->
  • 大表格保持单表连贯，超过 9 行限制时通过 API 追加行，而不是拆成多个表
  • 批量填充加速（batch_update API，每批 ≤30，文档级 3 QPS 节流）

AI Agent Skills

feishu-cli 提供了 27 个技能文件，让 AI Agent（如 Claude Code）可以直接操控飞书：

lark-calendar、lark-im、lark-doc、lark-sheets、lark-base、lark-task、lark-mail、lark-vc、lark-okr、lark-approval、lark-attendance、lark-event、lark-whiteboard、lark-minutes、lark-skill-maker 等。

附录：常见坑与解决方法

坑 1：CLI 返回 fetch failed

通常是网络问题或代理配置不对。确认：

  • 能访问 open.feishu.cn API 端点
  • 代理配置正确（如需）

坑 2：上传后飞书文档的引用块无法被 CLI 匹配

飞书文档的引用块在 Markdown 转换时可能走样。上传后可以在飞书 Web 端检查格式。

坑 3：update 必须带 –title

更新文档时 --title 参数是必填的，即使标题不变也要显式传入。

坑 4：上传后的格式有问题

代码块丢失、表格变形等问题多出现在 Markdown 到飞书富文本的转换过程。建议：

  • 代码块使用标准围栏格式 ```
  • 表格保持简洁，避免合并单元格
  • 上传后检查格式，必要时手动微调

坑 5：一次上传多个文件时被限流

飞书开放平台 API 有限频限制。批量操作时建议分批上传，使用 --diagram-workers 和 --table-workers 控制并发数。

附录：常用命令速查

 1# ===== 配置 =====
 2feishu-cli config init            # 初始化配置
 3feishu-cli config create-app --save  # 一键创建应用
 4feishu-cli profile add --name xxx    # 添加账号
 5feishu-cli profile use xxx           # 切换账号
 6
 7# ===== 认证 =====
 8feishu-cli auth login             # OAuth 用户登录
 9
10# ===== 文档 =====
11feishu-cli doc create --title "xxx" -f file.md  # 创建文档
12feishu-cli doc import file.md --title "xxx"     # 导入 Markdown
13feishu-cli doc export <doc_id> -o file.md       # 导出为 Markdown
14feishu-cli doc update <doc_id> --title "xxx" -f file.md  # 更新文档
15
16# ===== 知识库 =====
17feishu-cli wiki space list        # 列出知识库
18feishu-cli wiki node get --node-id xxx   # 获取节点
19feishu-cli wiki node export --node-id xxx -o file.md  # 导出节点
20
21# ===== 多维表格 =====
22feishu-cli bitable record list --app-token xxx --table-id yyy
23feishu-cli bitable record create --app-token xxx --table-id yyy --fields '{}'
24
25# ===== 消息 =====
26feishu-cli msg send --chat-id xxx --msg-type text --content "hello"
27feishu-cli msg history --user-email user@company.com
28
29# ===== 通用 =====
30feishu-cli api GET /open-apis/im/v1/messages  # 原始 API 调用
31feishu-cli doctor              # 健康检查
32--format json | pretty | table | ndjson | csv  # 输出格式

写在最后

数据不应该被困在孤岛里。feishu-cli 的价值在于，它让飞书不再是一个"进去才能用"的黑盒，而是一个可以通过命令行自由读写的开放平台。

对知识工作者来说，这意味着告别复制粘贴——飞书写协作，Obsidian 写思考，中间用 CLI 打通，各取所长。

工具的价值不在于功能多少，而在于它能不能融入你的工作流。

相关文章