English | 中文
# feishu-inout
**一行命令，让 AI 编程助手操作你的飞书文档、消息、日历和多维表格**
Claude Code / Cursor / Codex / OpenCode / OpenClaw — 文档、消息、日历、多维表格，一个 skill 全搞定
[](LICENSE)
[](https://python.org)
[](#)
[](https://mcp.feishu.cn)
---
> **搜索、阅读、创建、编辑、追加、替换、插入、删除、收发消息、搜索消息、日历、多维表格** — 在 AI 编程助手中完成飞书文档、消息、日历和多维表格的一切操作。
>
> 基于飞书官方远程 MCP 服务 + Open API，零依赖，单文件，开箱即用。
## 亮点
- **搜索文档** — 按关键词、作者、时间范围搜索，快速定位
- **7 种编辑模式** — 追加、覆盖、定位替换、全文替换、前后插入、删除，精准编辑不丢内容
- **一步创建** — 标题 + Markdown 内容一次搞定，支持指定知识库/文件夹位置
- **全能消息** — 发送、阅读、回复、搜索消息，支持 Markdown、@提及、表情，私聊群聊全覆盖
- **零依赖** — 纯 Python 标准库，不需要 Node.js，不需要本地 MCP 服务器
- **评论管理** — 全文评论、划词评论分类查看，支持 @用户
- **用户搜索** — 查找同事的 open_id，配合 @提及 使用
- **文件获取** — 下载文档中的图片、附件、画板内容
- **"我的文档库"** — 无需 ID 直接浏览个人文档，逐层递归探索知识库
- **大文档分页** — offset + limit 分段读取，不怕文档太长
- **日历与会议** — 创建日程并自动生成视频会议链接，邀请参会人，查看今日日程
- **多维表格** — 读取、创建、更新多维表格记录
- **群组管理** — 创建群组、添加成员、查看群列表
- **自动续期** — OAuth token 自动刷新，登录一次长期使用
## 谁能用？
不只是开发者 — 所有用飞书的人都能受益：
- **产品** — 生成 PRD、更新需求、同步发布说明
- **运营** — 写活动方案、维护内容日历、更新 SOP
- **数据** — 分析报告直接写入文档、自动格式化周报
- **销售** — 创建提案、更新客户记录、生成报价单
- **HR** — 写 JD、更新入职指南、修订制度
只要你的工作涉及"打开飞书 → 找文档 → 编辑 → 通知别人"，现在一句话搞定。
## 支持的 AI 工具
| Claude Code |
Cursor |
Codex |
OpenCode |
OpenClaw |
| Gemini CLI |
GitHub Copilot |
Amp |
Windsurf |
Cline |
| Roo Code |
Clawd |
Trae |
Kiro |
Kilo |
| Goose |
Factory.ai |
Antigravity |
+ 所有兼容 skills 格式的 AI 编程助手 |
## 安装
```bash
npx skills add joe960913/feishu-inout
```
## 快速开始（5 分钟）
### 1. 创建飞书应用
打开 [飞书开放平台](https://open.feishu.cn/app) → 创建自建应用 → 记录 **App ID** 和 **App Secret**
### 2. 开通权限
进入应用 → 权限管理 → **批量导入/导出权限**，粘贴以下内容一键导入：
```
docx:document:readonly,search:docs:read,wiki:wiki:readonly,im:chat:read,task:task:read,docx:document,docx:document:create,docx:document:write_only,docs:document.media:upload,docs:document.media:download,wiki:node:read,wiki:node:create,docs:document.comment:read,docs:document.comment:create,contact:user:search,contact:contact.base:readonly,contact:user.base:readonly,board:whiteboard:node:read,drive:drive,im:message,im:message:send_as_bot,im:chat,search:message,im:message.send_as_user,im:message.p2p_msg:get_as_user,im:message.group_msg:get_as_user,calendar:calendar:readonly,calendar:calendar,bitable:app:readonly,bitable:app,im:chat:create
```
或者逐个搜索开通（点击展开查看完整列表）
#### 基础权限（必须）
| 权限 scope | 名称 |
|-----------|------|
| `docx:document:readonly` | 查看新版文档 |
| `search:docs:read` | 搜索云文档 |
| `wiki:wiki:readonly` | 查看知识库 |
| `im:chat:read` | 查看群信息 |
| `task:task:read` | 查看任务信息 |
#### 写入权限（编辑文档需要）
| 权限 scope | 名称 |
|-----------|------|
| `docx:document` | 编辑新版文档 |
| `docx:document:create` | 创建新版文档 |
| `docx:document:write_only` | 写入新版文档 |
| `docs:document.media:upload` | 上传图片 |
| `wiki:node:read` | 查看知识库节点 |
| `wiki:node:create` | 创建知识库节点 |
#### 评论 / 用户 / 文件权限（可选）
| 权限 scope | 名称 |
|-----------|------|
| `docs:document.comment:read` | 查看评论 |
| `docs:document.comment:create` | 创建评论 |
| `contact:user:search` | 搜索用户 |
| `contact:contact.base:readonly` | 通讯录基本信息 |
| `contact:user.base:readonly` | 用户基本信息 |
| `docs:document.media:download` | 下载图片/附件 |
| `board:whiteboard:node:read` | 查看画板 |
| `drive:drive` | 管理云空间文件 |
#### 消息权限（可选）
| 权限 scope | 名称 |
|-----------|------|
| `im:message` | 管理消息 |
| `im:message:send_as_bot` | 以机器人身份发消息 |
| `im:chat` | 访问群聊列表 |
| `search:message` | 搜索消息 |
| `im:message.send_as_user` | 以用户身份发消息 |
| `im:message.p2p_msg:get_as_user` | 以用户身份读取私聊消息 |
| `im:message.group_msg:get_as_user` | 以用户身份读取群聊消息 |
#### 日历权限（可选）
| 权限 scope | 名称 |
|-----------|------|
| `calendar:calendar:readonly` | 查看日历日程 |
| `calendar:calendar` | 管理日历日程 |
#### 多维表格权限（可选）
| 权限 scope | 名称 |
|-----------|------|
| `bitable:app:readonly` | 查看多维表格记录 |
| `bitable:app` | 管理多维表格记录 |
#### 群组管理权限（可选）
| 权限 scope | 名称 |
|-----------|------|
| `im:chat:create` | 创建群聊 |
### 3. 配置重定向 URL
应用 → 安全设置 → 重定向 URL → 添加：
```
http://localhost:9876/callback
```
### 4. 设置环境变量
自行设置凭证（**请勿将 App Secret 发送给 AI**）：
**macOS / Linux：**
```bash
echo 'export FEISHU_APP_ID="你的AppID"' >> ~/.zshrc
echo 'export FEISHU_APP_SECRET="你的AppSecret"' >> ~/.zshrc
source ~/.zshrc
```
**Windows (PowerShell)：**
```powershell
[System.Environment]::SetEnvironmentVariable('FEISHU_APP_ID', '你的AppID', 'User')
[System.Environment]::SetEnvironmentVariable('FEISHU_APP_SECRET', '你的AppSecret', 'User')
# 设置后重启终端
```
### 5. 登录授权
环境变量设好后，告诉 AI 助手帮你登录：
```
You: 帮我登录飞书
AI: 正在执行 OAuth 登录...
浏览器已打开，请点击授权 ✓
UAT 获取成功！现在可以操作你的飞书文档了。
```
Token 自动刷新，无需反复登录。
### 6. 消息功能（无需机器人）
消息功能现在通过飞书官方远程 MCP 服务，使用**你的用户身份 (UAT)** 收发消息，无需开启机器人能力。完成第 5 步登录后，即可以你自己的身份发送、阅读、回复和搜索消息。
> 消息功能**不需要**机器人能力。所有消息都以你自己的飞书身份发送和读取。
## 使用示例
安装配置好后，**直接用自然语言对话**，skill 自动触发：
### 搜索和浏览
```
You: 看看我飞书上有哪些文档
AI: 找到 20 篇文档：
1. Q2 产品规划 — 王明 (3/25)
2. 前端重构方案 — 李华 (3/24)
3. 新人入职指南 — 张伟 (3/23)
...
```
```
You: 搜索飞书文档：项目周报
AI: 搜索到 5 篇相关文档，要看哪篇？
```
### 阅读文档
```
You: 读一下这个飞书文档 https://xxx.feishu.cn/wiki/ABC123def
AI: ## 前端重构方案
### 目标
- 迁移至 React 18 + TypeScript
- 首屏加载时间 < 1.5s
### 进度
1. ✅ 组件库升级
2. ❌ 路由重构（进行中）
...
```
### 创建和编辑
```
You: 帮我在飞书创建一个"Q2 产品规划"文档，先写个大纲
AI: 文档已创建！
链接：https://xxx.feishu.cn/docx/xxx
已写入大纲：目标、时间线、里程碑、资源分配
```
```
You: 在第二章后面加一段关于竞品分析的内容
AI: 已在"时间线"章节后插入"竞品分析"段落。
```
```
You: 把文档里所有的"待定"替换成"已确认"
AI: 已替换 3 处。
```
### 追加内容
```
You: 在那个文档末尾追加今天的会议纪要
AI: 已追加"2026-03-26 会议纪要"到文档末尾。
```
### 评论和协作
```
You: 看看那篇文档有什么评论
AI: 共 3 条评论：
1. @张三: "第二章需要补充数据"
2. @李四: "时间线建议推迟一周"
...
```
```
You: 帮我回复一条评论："已更新，请再看看"
AI: 评论已添加。
```
### 消息 — 发送、阅读、搜索、回复
```
You: 产品群今天讨论了什么？
AI: 正在读取"产品团队"群今天的消息...
1. David (10:30): API v2 迁移完成
2. Sarah (11:15): QA 通过，准备上线
3. Mike (14:22): 已部署到生产环境
```
```
You: 给 David 发个消息：API 改动已经部署了
AI: 已以你的身份发送给 David。
```
```
You: 搜索本周关于"部署"的消息
AI: 在 3 个群聊中找到 5 条相关消息：
- "技术团队" — David: "部署流程已更新" (周一)
- "产品团队" — Sarah: "部署检查清单已审核" (周二)
...
```
```
You: 回复 Mike 的消息：辛苦了，谢谢！
AI: 已在 Mike 的消息下方回复。
```
```
You: 把刚才写好的文档发到产品群里
AI: 已将文档"Q2 产品规划"分享到群聊"产品团队"。
```
> 消息支持 Markdown 格式、通过 `` @提及用户、通过 `` @所有人，以及 `[SMILE]` 等表情。
### 日历与会议
```
You: 明天下午 2-3 点安排一个迭代评审会，邀请 David 和 Sarah
AI: 日程已创建，自动生成飞书视频会议！
链接：https://meetings.feishu.cn/...
已邀请：David、Sarah
```
```
You: 我今天有什么会议？
AI: 今天有 3 个日程：
1. 10:00-11:00 — 每日站会
2. 14:00-15:00 — 迭代评审
3. 16:00-16:30 — 与 Mike 1:1
```
### 多维表格
```
You: 看看这个多维表格里有什么 https://xxx.feishu.cn/base/ABC123
AI: 找到表格"任务追踪"，共 15 条记录...
```
```
You: 新增一行：任务="修复登录 bug"，状态="进行中"，负责人="David"
AI: 记录已创建。
```
### 更多对话场景
```
You: 帮我找一下 David 的 open_id，我要在文档里 @ 他
You: 下载那个文档里的图片
You: 浏览一下知识库里"产品文档"下面有哪些子文档
You: 把这段代码的运行结果写到飞书文档里
You: 写完文档后发到研发群，顺便 @一下张三
You: Sarah 昨天在技术群说了什么？
```
---
CLI 直接调用（高级用法）
```bash
S=scripts/feishu_mcp.py
# 文档
python3 $S search-doc "周报" # 搜索
python3 $S fetch-doc ABC123def # 读取
python3 $S list-docs # 我的文档库
python3 $S create-doc "会议纪要" "## 议题\n\n- 要点1" # 创建
python3 $S append ABC123def "## 补充\n\n追加内容" # 追加
python3 $S replace ABC123def "旧内容...结尾" "新内容" # 替换
python3 $S insert-after ABC123def "某段文字" "插入的内容" # 插入
python3 $S delete-range ABC123def "要删除的内容" # 删除
python3 $S get-comments ABC123def # 评论
python3 $S search-user "张三" # 搜索用户
python3 $S fetch-file filetoken123 # 获取文件
# 消息
python3 $S list-groups # 列出群组
python3 $S send-msg oc_xxx "消息内容" # 发群消息
python3 $S send-msg ou_xxx "消息内容" --user # 私聊消息
python3 $S send-card oc_xxx '{"type":"template","data":{}}' # 发送交互卡片
python3 $S get-msgs oc_xxx today # 读取今日消息
python3 $S get-msgs-user ou_xxx last_3_days # 读取近期私聊
python3 $S search-msgs "部署" # 搜索消息
python3 $S reply om_xxx "收到！" # 回复消息
python3 $S get-thread thread_xxx # 获取话题回复
# 日历
python3 $S list-events # 查看今日日程
python3 $S create-event "迭代评审" "2026-03-27T14:00" "2026-03-27T15:00" # 所有日程自动创建视频会议
python3 $S create-event "演示会" "2026-03-28T10:00" "2026-03-28T11:00" # 所有日程自动创建视频会议
# 多维表格
python3 $S list-tables appToken # 列出表格
python3 $S list-records appToken tableId # 列出记录
python3 $S create-record appToken tableId '{"任务":"修复bug"}' # 创建记录
python3 $S update-record appToken tableId recordId '{"状态":"完成"}' # 更新记录
# 群组管理
python3 $S create-group "项目团队" # 创建群组
python3 $S add-members oc_xxx '["ou_xxx1","ou_xxx2"]' # 添加成员
```
## 工作原理
```
┌─► 飞书云文档
AI Agent ──► feishu_mcp.py ──► ────┼─► 飞书消息 (MCP)
│ ├─► 日历与会议 (API)
├─ 官方 MCP ├─► 多维表格 (API)
├─ + Open API └─► 群组管理 (API)
└─ 零依赖
```
文档和消息通过飞书官方远程 MCP 服务，日历、多维表格、群组管理通过 Open API，不需要部署本地 MCP 服务器，不需要 Node.js，不需要机器人，一个 Python 脚本搞定所有事。
## 全部命令
| 命令 | 说明 |
|------|------|
| `login` | OAuth2 浏览器授权 |
| `whoami` | 查看当前 token 状态 |
| `fetch-doc [offset] [limit]` | 读取文档（支持分页） |
| `search-doc ` | 搜索文档 |
| `list-docs [id]` | 浏览文档库（不传 id = 我的文档库） |
| `create-doc [markdown] [location]` | 创建文档 |
| `append <id> <markdown>` | 追加内容 |
| `overwrite <id> <markdown>` | 覆盖文档 |
| `replace <id> <selection> <markdown>` | 定位替换 |
| `insert-after <id> <selection> <markdown>` | 后插入 |
| `insert-before <id> <selection> <markdown>` | 前插入 |
| `delete-range <id> <selection>` | 删除内容 |
| `get-comments <id> [all\|whole\|segment]` | 获取评论 |
| `add-comments <id> <text>` | 添加评论 |
| `get-user [open_id]` | 获取用户信息 |
| `search-user <keyword>` | 搜索用户 |
| `fetch-file <token> [media\|whiteboard]` | 获取文件/图片 |
| `list-groups` | 列出群组 |
| `send-msg <id> <text> [--user]` | 发送消息（群聊或私聊） |
| `send-card <id> '<json>' [--user]` | 发送交互卡片消息 |
| `get-msgs <chat_id> [time] [count]` | 读取群聊记录（today/yesterday/this_week/last_3_days 等） |
| `get-msgs-user <open_id> [time] [count]` | 读取私聊记录 |
| `search-msgs <keyword> [time]` | 跨群搜索消息 |
| `reply <msg_id> <text> [--thread]` | 回复消息（支持话题模式） |
| `get-thread <thread_id>` | 获取话题回复 |
| `list-events [date]` | 查看日程（默认今天） |
| `create-event <title> <start> <end> [attendees]` | 创建日程（自动创建视频会议） |
| `list-tables <app_token>` | 列出多维表格中的表格 |
| `list-records <app> <table> [page_size]` | 列出多维表格记录 |
| `create-record <app> <table> <json>` | 创建多维表格记录 |
| `update-record <app> <table> <record> <json>` | 更新多维表格记录 |
| `create-group <name> [members_json]` | 创建群组 |
| `add-members <chat_id> '<members_json>'` | 添加群成员 |
| `call <tool> <json>` | 调用任意 MCP 工具 |
## 常见问题
<details>
<summary><b>search-doc 报错 "search:docs:read"</b></summary>
这个权限是用户身份类型，需要 UAT。运行 `python3 scripts/feishu_mcp.py login` 重新授权。
</details>
<details>
<summary><b>fetch-doc 报错 "permission denied"</b></summary>
TAT 模式下应用需要被添加为文档协作者。用 UAT（`login` 后）可以访问你有权限的所有文档。
</details>
<details>
<summary><b>login 后浏览器没反应</b></summary>
检查是否在飞书应用的安全设置中添加了重定向 URL `http://localhost:9876/callback`。
</details>
<details>
<summary><b>Token 过期了怎么办</b></summary>
脚本自动用 refresh_token 续期。如果 refresh_token 也过期（30天），重新运行 `login` 即可。
</details>
## Security
- **凭证安全** — App Secret 通过环境变量传递，不会出现在对话记录或 AI 上下文中
- **官方服务** — 所有 API 调用通过飞书官方远程 MCP 服务 (`mcp.feishu.cn`)，非第三方代理
- **本地 Token** — OAuth token 存储在本地文件中，不上传到任何外部服务
- **第三方内容** — 读取的飞书文档内容来自用户自己有权限的文档，请注意文档中可能包含不可信内容
## Contributing
Issues and PRs welcome!
## License
MIT