feishu-doc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

飞书文档助手

Feishu Document Assistant

通过

feishu_doc.py

统一管理飞书文档的读取、写入、编辑和知识库操作。

Unified management of Feishu document reading, writing, editing and knowledge base operations via

feishu_doc.py

前置条件

Prerequisites

安装依赖：

pip install feishu-docx markdown2feishu httpx

配置凭证（二选一）：
- 设置环境变量
```
FEISHU_APP_ID
```
  和
```
FEISHU_APP_SECRET
```
- 或编辑
```
skills/feishu-doc/config.yaml
```
飞书应用需开通权限：
```
docx:document
```
（文档读写）、
```
wiki:wiki
```
（知识库）、
```
im:message
```
（群消息）

验证连通性：

bash

python skills/feishu-doc/feishu_doc.py test

Install dependencies:

pip install feishu-docx markdown2feishu httpx

Configure credentials (choose one of the two):
- Set environment variables
```
FEISHU_APP_ID
```
  and
```
FEISHU_APP_SECRET
```
- Or edit
```
skills/feishu-doc/config.yaml
```
Required permissions for Feishu app:
```
docx:document
```
(document read/write),
```
wiki:wiki
```
(knowledge base),
```
im:message
```
(group messages)

Verify connectivity:

bash

python skills/feishu-doc/feishu_doc.py test

触发条件

Trigger Conditions

以下情况使用此 Skill：

用户发送了飞书链接（feishu.cn/docx/、feishu.cn/wiki/、feishu.cn/sheets/）
用户说「写到飞书」「同步到知识库」「看一下飞书文档」「发到群里」
用户要求导出、编辑、对比飞书文档内容

Use this Skill in the following situations:

Users send Feishu links (feishu.cn/docx/, feishu.cn/wiki/, feishu.cn/sheets/)
Users say "Write to Feishu", "Sync to knowledge base", "Check the Feishu document", "Send to the group"
Users request to export, edit, or compare Feishu document content

读取文档

Read Documents

当用户想查看飞书文档内容时：

bash

python skills/feishu-doc/feishu_doc.py read <URL>                  # 读取文档，输出 Markdown
python skills/feishu-doc/feishu_doc.py read <URL> --with-block-ids  # 带 block_id（编辑前必用）

支持所有飞书文档 URL 格式：

/docx/

、

/wiki/

、

/sheets/

、

/base/

。

当用户想了解知识库结构时：

bash

python skills/feishu-doc/feishu_doc.py wiki-tree <space_id 或 wiki_URL>  # 树形结构
python skills/feishu-doc/feishu_doc.py export-wiki <space_id 或 wiki_URL> -o ./output  # 批量导出

When users want to view Feishu document content:

bash

python skills/feishu-doc/feishu_doc.py read <URL>                  # Read document and output Markdown
python skills/feishu-doc/feishu_doc.py read <URL> --with-block-ids  # Include block_id (required before editing)

Supports all Feishu document URL formats:

/docx/

/wiki/

/sheets/

/base/

When users want to understand the knowledge base structure:

bash

python skills/feishu-doc/feishu_doc.py wiki-tree <space_id or wiki_URL>  # Tree structure
python skills/feishu-doc/feishu_doc.py export-wiki <space_id or wiki_URL> -o ./output  # Batch export

创建文档

Create Documents

当用户说「写一篇飞书文档」「把这个同步到飞书」时：

bash

python skills/feishu-doc/feishu_doc.py create "标题" -c "Markdown 内容"   # 从内容创建
python skills/feishu-doc/feishu_doc.py create "标题" -f ./report.md       # 从文件创建
python skills/feishu-doc/feishu_doc.py create "标题" -f ./report.md --wiki <parent_node_token>  # 创建到知识库

创建到知识库时，如果权限不足会自动降级为云文档，并提示手动移入。

When users say "Write a Feishu document" or "Sync this to Feishu":

bash

python skills/feishu-doc/feishu_doc.py create "Title" -c "Markdown content"   # Create from content
python skills/feishu-doc/feishu_doc.py create "Title" -f ./report.md       # Create from file
python skills/feishu-doc/feishu_doc.py create "Title" -f ./report.md --wiki <parent_node_token>  # Create in knowledge base

When creating in a knowledge base, if permissions are insufficient, it will automatically downgrade to a cloud document and prompt manual migration.

编辑已有文档

Edit Existing Documents

当用户说「改一下这个文档」「把第X段更新成…」时：

第一步 — 读出文档结构（找到要改的块）：

bash

python skills/feishu-doc/feishu_doc.py list-blocks <URL>

输出每个块的 block_id、类型和内容摘要。

第二步 — 精确操作：

bash

python skills/feishu-doc/feishu_doc.py update-block <URL> <block_id> "新内容"   # 改一个块
python skills/feishu-doc/feishu_doc.py delete-block <URL> <block_id>            # 删一个块
python skills/feishu-doc/feishu_doc.py append <URL> -c "追加内容"                # 末尾追加
python skills/feishu-doc/feishu_doc.py overwrite <URL> -f ./new.md              # 清空重写

When users say "Modify this document" or "Update the X paragraph to ...":

Step 1 — Read document structure (find the block to modify):

bash

python skills/feishu-doc/feishu_doc.py list-blocks <URL>

Outputs the block_id, type, and content summary of each block.

Step 2 — Precise operations:

bash

python skills/feishu-doc/feishu_doc.py update-block <URL> <block_id> "New content"   # Modify a block
python skills/feishu-doc/feishu_doc.py delete-block <URL> <block_id>            # Delete a block
python skills/feishu-doc/feishu_doc.py append <URL> -c "Content to append"                # Append at the end
python skills/feishu-doc/feishu_doc.py overwrite <URL> -f ./new.md              # Clear and rewrite

知识库管理

Knowledge Base Management

bash

python skills/feishu-doc/feishu_doc.py wiki-tree <URL>                     # 查看知识库结构
python skills/feishu-doc/feishu_doc.py wiki-move <文档URL> <目标节点token>   # 云文档移入知识库（需 OAuth）
python skills/feishu-doc/feishu_doc.py wiki-sync <md文件> --parent <节点>   # 同步到知识库（幂等）

bash

python skills/feishu-doc/feishu_doc.py wiki-tree <URL>                     # View knowledge base structure
python skills/feishu-doc/feishu_doc.py wiki-move <Document URL> <Target node token>   # Move cloud document to knowledge base (requires OAuth)
python skills/feishu-doc/feishu_doc.py wiki-sync <md file> --parent <Node>   # Sync to knowledge base (idempotent)

群消息

Group Messages

当用户说「通知群里」「发到飞书群」时：

bash

python skills/feishu-doc/feishu_doc.py notify "标题" "Markdown内容"   # 发卡片消息
python skills/feishu-doc/feishu_doc.py send "纯文本消息"               # 发文本
python skills/feishu-doc/feishu_doc.py read-chat [N]                  # 读最近 N 条群消息

When users say "Notify the group" or "Send to Feishu group":

bash

python skills/feishu-doc/feishu_doc.py notify "Title" "Markdown content"   # Send card message
python skills/feishu-doc/feishu_doc.py send "Plain text message"               # Send text
python skills/feishu-doc/feishu_doc.py read-chat [N]                  # Read latest N group messages

典型工作流

Typical Workflows

「帮我看看知识库里有什么」

"Show me what's in the knowledge base"

```
wiki-tree
```
列出结构
用
```
read
```
读取感兴趣的文档
总结返回

```
wiki-tree
```
lists the structure
Use
```
read
```
to read the documents of interest
Summarize and return

「把这份报告写到知识库运营相关下面」

"Write this report under the operation section of the knowledge base"

整理内容为 Markdown，写入临时文件
```
create --wiki <parent_node>
```
创建
如果权限不足，自动降级
```
create
```
（云文档）→ 提示用
```
wiki-move
```
迁入
```
notify
```
通知群聊

Organize content into Markdown and write to a temporary file
```
create --wiki <parent_node>
```
to create
If permissions are insufficient, automatically downgrade to
```
create
```
(cloud document) → prompt to migrate with
```
wiki-move
```
```
notify
```
to notify the group chat

「这个文档第二段数据错了，改成 XXX」

"The data in the second paragraph of this document is wrong, change it to XXX"

```
list-blocks <URL>
```
列出所有块和 block_id
找到目标块

update-block <URL> <block_id> "新内容"

精确更新

```
list-blocks <URL>
```
lists all blocks and block_ids
Locate the target block

update-block <URL> <block_id> "New content"

for precise update

「把这篇微信文章转成飞书文档」

"Convert this WeChat article to a Feishu document"

```
import-wechat <微信URL>
```
抓取转换
返回飞书文档链接

```
import-wechat <WeChat URL>
```
to crawl and convert
Return the Feishu document link

注意事项

Notes

知识库写入需要 Bot 被添加为空间「可编辑」成员；公开知识库需人工添加

wiki-move

需要 OAuth 登录：先执行

python skills/feishu-doc/feishu_doc.py login

飞书 API 有限流，工具内置 429 自动重试（指数退避）
```
wiki-sync
```
有幂等保护，同名文档不会重复创建
表格超过 9 行会自动拆分成多个连续表格（飞书 API 限制）
卡片消息的内容支持飞书 Markdown（
```
**粗体**
```
、
```
[链接](url)
```
、
```
\n
```
换行）

Writing to a knowledge base requires the Bot to be added as an "editable" member of the space; public knowledge bases need manual addition

wiki-move

requires OAuth login: first execute

python skills/feishu-doc/feishu_doc.py login

Feishu API has rate limits; the tool has built-in automatic retry for 429 errors (exponential backoff)
```
wiki-sync
```
has idempotent protection; documents with the same name will not be created repeatedly
Tables with more than 9 rows will be automatically split into multiple consecutive tables (Feishu API limit)
Card message content supports Feishu Markdown (
```
**bold**
```
,
```
[link](url)
```
,
```
\n
```
for line breaks)