飞书 CLI 授权与 AI 生成飞书文档完整教程

本教程面向第一次接触 lark-cli、Claude Code / AI Agent、飞书云文档自动化的同学。

你将学会：

• 为什么 AI 工具需要飞书授权。
• bot-only 和 user-default 两种身份模式有什么区别。
• 如何处理 lark-cli 提示“缺少飞书凭证”的情况。
• 如何通过浏览器完成飞书账号授权。
• 如何检查授权是否成功。
• 如何把本地 Markdown 文档生成到飞书云文档中。

本教程中的截图来自一次真实配置过程。截图中的授权链接、App ID、文档链接仅用于说明流程，不需要照抄。

---

一、你最终会完成什么

完成本教程后，你可以实现这样的工作流：

写好 Markdown 文档
        ↓
使用 lark-cli 登录飞书
        ↓
完成浏览器授权
        ↓
检查授权状态
        ↓
把 Markdown 自动创建为飞书云文档
        ↓
在浏览器中打开并分享文档

简单说，就是让 AI 或命令行工具帮助你把内容直接变成飞书云文档。

---

二、开始前需要知道的几个概念

1. 什么是 lark-cli

lark-cli 是一个命令行工具，可以通过命令操作飞书能力，例如：

• 查看日程。
• 创建云文档。
• 搜索云空间文件。
• 发送消息。
• 操作任务。

它不是聊天软件，而是一个“通过命令调用飞书功能”的工具。

---

2. 什么是 AI Agent

AI Agent 可以理解为“会帮你操作工具的 AI 助手”。

普通聊天 AI 只能回答你问题，而 AI Agent 可以进一步帮你：

• 运行命令。
• 读取文件。
• 生成文档。
• 调用工具。
• 把结果写入系统。

在本教程中，AI Agent 会通过 lark-cli 连接飞书。

---

3. 为什么需要授权

飞书里的日程、文档、邮箱、任务都属于账号数据。

如果 AI 或命令行工具想访问这些数据，必须经过你的授权。

这就像手机 App 第一次访问相册、通讯录时，需要你点击“允许”一样。

所以整个流程里最重要的一点是：

只有你明确授权后，工具才能访问对应的飞书资源。

---

三、第一步：先看清楚授权规则

图中显示，在继续操作之前，AI 明确提出了几条要求：

• 不要自己猜授权链接。
• 不要跳过浏览器授权。
• 如果命令输出授权链接，要把完整链接交给用户。
• 授权完成后，要检查状态。
• 最后先执行只读测试命令。

截图里出现了三个重要命令。

1. 发起登录授权

lark-cli auth login --recommend

作用：
让 lark-cli 开始登录飞书，并推荐当前环境适合的授权方式。

执行后，终端通常会输出一个飞书授权链接。

---

2. 检查授权状态

lark-cli auth status

作用：
查看当前是否已经成功登录飞书。

如果没有登录成功，后续创建文档、读取日程等操作都会失败。

---

3. 执行只读测试

lark-cli calendar +agenda

作用：
读取你的日程安排，用来测试飞书访问是否正常。

为什么先用这个测试？

因为它是只读操作，不会修改你的飞书数据。

---

本步骤要记住

不要先做写入操作。
先登录，再检查，再只读测试。

---

四、第二步：选择身份模式

这一步中，lark-cli 检测到当前运行在 AI Agent 环境里，所以要求你选择身份模式。

界面中有两个选项：

模式	含义	适合什么场景
bot-only	只使用机器人身份	发群通知、机器人自动任务
user-default	使用你授权后的用户身份	查看个人日程、创建个人云文档、访问个人云空间

---

bot-only 是什么

bot-only 可以理解为：

只让飞书机器人去工作。

它更安全，权限范围更小，但通常不能访问你的个人资源。

适合：

• 机器人发消息。
• 自动通知。
• 服务端任务。
• 不需要读取你个人数据的操作。

---

user-default 是什么

user-default 可以理解为：

你本人授权工具代表你访问飞书资源。

它能访问更多个人资源，例如：

• 你的日程。
• 你的云文档。
• 你的云空间文件。
• 你的任务。
• 你的邮箱。

但也因为权限更接近本人账号，所以要更加注意隐私和授权范围。

---

本教程应该选哪个

因为本教程的目标是创建飞书云文档，所以通常选择：

user-default

如果你只是做机器人通知，不访问个人文档或个人日程，可以选择：

bot-only

---

本步骤要记住

访问个人资源，选 user-default。
只做机器人任务，选 bot-only。

---

五、第三步：理解配置失败提示

这张图中出现了配置失败提示。

关键意思是：

lark-cli 检测到 hermes 环境存在，
但这个环境里没有配置飞书凭证。

这不是账号密码错误，也不是网络一定有问题，而是当前环境还缺少飞书应用凭证。

---

什么是飞书凭证

飞书凭证可以理解为：

让 lark-cli 调用飞书 API 的应用身份证明。

没有凭证时，lark-cli 不知道该用哪个飞书应用去发起授权。

---

图中给出的两个解决方案

方案 1：已有环境，只是需要补凭证

hermes setup

适合情况：

• 你的 AI Studio / Claude Code 已经配置过飞书应用。
• 只是当前环境里没有补全飞书 credentials。

---

方案 2：创建一个新的飞书应用配置

lark-cli config init --new --force-init

适合情况：

• 你不确定之前有没有配置过。
• 你想单独创建一个新配置。
• 你不想影响旧环境。
• 你是在课堂或测试环境里演示。

本次截图中选择的是方案 2。

---

本步骤要记住

看到失败提示时，不要急着重装。

先看它到底在说什么：

提示	意思	下一步
有 hermes 环境	当前运行在 AI Agent 集成环境	正常
没有飞书凭证	还不能调用飞书 API	配置凭证
已有应用	可用 hermes setup	补充配置
需要新配置	可用 config init --new --force-init	新建配置

---

六、第四步：初始化新的飞书应用配置

图中选择了第 2 个方案，也就是创建新的应用配置。

终端执行了：

lark-cli config init --new --force-init

执行成功后，会看到类似提示：

应用配置成功！App ID: cli_xxx

这说明飞书应用配置已经生成。

---

命令拆解

lark-cli

表示使用飞书命令行工具。

config init

表示初始化配置。

--new

表示创建一个新的配置。

--force-init

表示强制初始化，避免被旧配置卡住。

---

初始化后要做什么

配置完成后，还不能直接访问你的飞书资源。

下一步还要登录授权：

lark-cli auth login --recommend

图中也展示了这一步。

---

本步骤要记住

config init 只是配置应用。
auth login 才是让你的飞书账号授权。

---

七、第五步：浏览器完成飞书授权

当执行：

lark-cli auth login --recommend

终端会输出一个飞书授权链接。

你需要把这个链接复制到浏览器中打开。

---

授权操作步骤

1. 在终端中找到 https://accounts.feishu.cn/... 开头的授权链接。
2. 完整复制链接。
3. 打开浏览器。
4. 粘贴链接并访问。
5. 使用飞书账号登录。
6. 根据页面提示确认授权。
7. 回到终端等待命令继续执行。

---

注意事项

授权链接通常有时间限制。

如果你太久没有打开，可能会过期。

如果过期了，可以重新执行：

lark-cli auth login --recommend

重新获取新的授权链接。

---

不要做这些事

不要把授权链接发到公开群。
不要截图传播完整授权链接。
不要手动修改链接里的参数。
不要同时打开多个旧授权链接。

授权链接是当前登录流程的一部分，必须完整、原样使用。

---

本步骤要记住

命令行生成链接，浏览器完成授权，终端等待结果。

---

八、第六步：检查是否授权成功

浏览器授权完成后，建议先执行：

lark-cli auth status

如果状态正常，再执行一个只读测试：

lark-cli calendar +agenda

---

为什么一定要检查

因为浏览器里点了授权，不代表本地命令行一定已经正确保存状态。

检查可以帮助你确认：

• 当前账号是否已经登录。
• 权限是否生效。
• lark-cli 是否能正常连接飞书。
• 后续创建文档是否有基础条件。

---

什么是只读测试

只读测试就是只读取数据，不修改数据。

例如：

lark-cli calendar +agenda

它只是读取日程，不会创建、删除或修改内容。

---

本步骤要记住

授权完成后，不要直接写入。
先 auth status，再只读测试。

---

九、第七步：准备 Markdown 文档

创建飞书云文档之前，你需要有一个 Markdown 文件。

Markdown 是一种简单的文本格式，常用于写说明文档。

文件名示例：

deepseek-pricing-doc.md

---

一个最简单的 Markdown 示例

# 我的第一篇飞书自动化文档

## 一、文档说明

这是一篇通过 lark-cli 创建的飞书云文档。

## 二、操作步骤

1. 准备 Markdown 文件。
2. 完成飞书授权。
3. 使用命令创建云文档。

## 三、示例表格

| 项目 | 说明 |
|---|---|
| 工具 | lark-cli |
| 平台 | 飞书 |
| 输出 | 云文档 |

## 四、命令示例

```bash
lark-cli docs +create --title "我的第一篇飞书自动化文档" --markdown @./demo.md

五、注意事项

请先确认已经完成飞书授权。

---

### Markdown 常用语法

| 写法 | 效果 |
|---|---|
| `# 标题` | 一级标题 |
| `## 标题` | 二级标题 |
| `- 内容` | 无序列表 |
| `1. 内容` | 有序列表 |
| `**文字**` | 加粗 |
| `` `命令` `` | 行内代码 |
| 三个反引号 | 多行代码块 |
| 表格语法 | 表格 |

---

## 十、第八步：创建飞书云文档

![图 6：创建飞书云文档](./image/03-06.png)

图中展示了把 Markdown 创建为飞书云文档的过程。

命令结构如下：

```bash
lark-cli docs +create --title "DeepSeek-V4 模型调用费用估算说明" --markdown @./deepseek-pricing-doc.md

---

命令拆解

lark-cli docs +create

表示创建飞书文档。

--title "DeepSeek-V4 模型调用费用估算说明"

表示指定飞书文档标题。

--markdown @./deepseek-pricing-doc.md

表示把本地 Markdown 文件作为正文内容导入。

注意这里的 @ 很重要。

@./deepseek-pricing-doc.md

表示读取这个文件的内容，而不是把文件名当成普通文字。

---

执行成功后会看到什么

如果创建成功，终端会返回类似信息：

文档已创建成功！
文档已保存至云文档：
DeepSeek-V4 模型调用费用估算说明
https://www.feishu.cn/docx/...

这说明飞书文档已经创建完成。

你可以复制返回的链接，在浏览器中打开。

---

本步骤要记住

docs +create 用来创建文档。
--title 设置标题。
--markdown @文件路径 导入 Markdown 内容。

---

十一、第九步：查看最终生成的文档

图中展示了最终生成的飞书云文档。

可以看到：

• 顶部有文档标题。
• 左侧自动生成目录。
• 正文有清晰的章节。
• 内容中包含代码块。
• 下方还有表格内容。

这说明 Markdown 已经被转换成了飞书文档格式。

---

为什么左侧会有目录

因为 Markdown 中使用了标题层级：

# 一级标题
## 二级标题
### 三级标题

飞书会根据这些标题自动生成目录。

所以写 Markdown 时，标题层级要清楚。

---

什么样的 Markdown 更适合生成文档

建议包含：

• 清楚的一级标题。
• 多个二级标题。
• 简洁的段落。
• 结构化表格。
• 必要的代码块。
• 注意事项或结论。

不建议：

• 全文没有标题。
• 表格太宽。
• 列表层级过深。
• 一段文字特别长。
• 代码块没有结束符号。

---

十二、完整命令清单

下面是本教程涉及的核心命令。

1. 初始化新配置

lark-cli config init --new --force-init

2. 发起登录授权

lark-cli auth login --recommend

3. 检查登录状态

lark-cli auth status

4. 只读测试日程

lark-cli calendar +agenda

5. 创建飞书云文档

lark-cli docs +create --title "文档标题" --markdown @./你的文件.md

---

十三、推荐操作顺序

如果你从零开始，建议按这个顺序操作：

1. 选择身份模式 user-default
2. 初始化配置
3. 发起登录授权
4. 浏览器完成飞书授权
5. 检查 auth status
6. 执行只读测试 calendar +agenda
7. 准备 Markdown 文件
8. 执行 docs +create
9. 打开返回链接检查文档

---

十四、常见问题

Q1：我应该选择 bot-only 还是 user-default

如果你要访问自己的日程、文档、云空间，选：

user-default

如果你只做机器人自动任务，选：

bot-only

---

Q2：提示没有飞书凭证怎么办

如果你已经有配置好的环境，可以尝试：

hermes setup

如果你想新建一套配置，可以尝试：

lark-cli config init --new --force-init

---

Q3：授权链接打不开怎么办

可以检查：

• 链接是否复制完整。
• 浏览器是否能访问飞书。
• 是否登录了正确的飞书账号。
• 链接是否已经过期。

如果链接过期，重新执行：

lark-cli auth login --recommend

---

Q4：浏览器授权后终端没反应怎么办

可以先等待几秒钟。

如果一直没有反应，可能是授权超时或终端没有接收到结果。

可以重新执行：

lark-cli auth login --recommend

---

Q5：创建文档失败怎么办

按顺序检查：

1. 是否执行过 lark-cli auth login --recommend。
2. lark-cli auth status 是否正常。
3. Markdown 文件路径是否正确。
4. --markdown @./文件.md 中是否有 @。
5. 当前账号是否有创建云文档权限。
6. 命令是否拼写错误。

---

Q6：生成的文档格式乱怎么办

优先检查 Markdown 文件：

• 标题层级是否正确。
• 表格格式是否完整。
• 代码块是否有开始和结束。
• 列表前后是否留有空行。
• 是否有特别长的表格或段落。

---

十五、课堂练习

练习 1：判断身份模式

请判断下面场景应该选择哪种模式。

场景	推荐模式
创建自己的飞书云文档	user-default
查看自己的今日日程	user-default
机器人向群里发通知	bot-only
搜索自己的云空间文件	user-default
服务端定时发送系统提醒	bot-only

---

练习 2：写一个 Markdown 文件

请新建一个 Markdown 文件，文件名可以叫：

my-ai-plan.md

内容主题：

我的 AI 学习计划

要求：

• 至少有 1 个一级标题。
• 至少有 3 个二级标题。
• 至少有 1 个表格。
• 至少有 1 个代码块。
• 至少有 1 段注意事项。

---

练习 3：把 Markdown 创建为飞书文档

如果你的环境已经完成授权，可以执行：

lark-cli docs +create --title "我的 AI 学习计划" --markdown @./my-ai-plan.md

创建完成后，打开返回的飞书链接，检查：

• 标题是否正确。
• 目录是否生成。
• 表格是否正常。
• 代码块是否保留。
• 内容是否适合分享。

---

十六、学习小结

本教程的重点不是记住所有命令，而是理解一条完整的自动化办公流程：

配置环境
  ↓
选择身份
  ↓
浏览器授权
  ↓
状态检查
  ↓
只读验证
  ↓
Markdown 生成飞书文档

请记住三个原则：

1. 访问个人资源前，必须先授权。
2. 授权完成后，先检查状态和只读测试。
3. 文档自动化生成前，先写好结构清晰的 Markdown。

---

十七、速查卡片

# 初始化新配置
lark-cli config init --new --force-init

# 登录授权
lark-cli auth login --recommend

# 检查授权状态
lark-cli auth status

# 只读测试
lark-cli calendar +agenda

# 创建飞书文档
lark-cli docs +create --title "文档标题" --markdown @./文件.md

---

十八、课后任务

请完成以下任务：

1. 写一篇 Markdown 文档，题目为《我的 AI 学习计划》。
2. 尝试把它创建为飞书云文档。
3. 截图保存最终文档页面。
4. 记录你遇到的问题，以及你是如何解决的。

完成后，你应该能独立说清楚：

• 为什么需要飞书授权。
• 什么时候选择 user-default。
• auth status 的作用是什么。
• --markdown @文件.md 中的 @ 有什么用。
• 为什么 Markdown 标题会影响飞书文档目录。