feishu-doc

Feishu document assistant

Through feishu_doc.py uniformly manage the reading, writing, editing, and knowledge base operations of Feishu documents.

Prerequisites

1. Python >= 3.11(required by feishu-docx). Recommended to use uv run --python 3.12 or ensure the system Python version meets the requirements
2. Install dependencies:pip install feishu-docx markdown2feishu httpx pyyaml
3. Configure credentials (choose one of two):
   • Set environment variables FEISHU_APP_ID and FEISHU_APP_SECRET
   • or edit skills/feishu-doc/config.yaml
4. The Feishu app needs the following permissions enabled:docx:document(document read/write),wiki:wiki(knowledge base),im:message(group messages)

Environment variable comparison table

Environment variable	config.yaml key	Description
FEISHU_APP_ID	app_id	Feishu app ID (required)
FEISHU_APP_SECRET	app_secret	Feishu app secret (required)
FEISHU_WIKI_SPACE_ID	wiki_space_id	Knowledge base space_id (required for knowledge base writing; can be viewed via the wiki-spaces command)
FEISHU_DEFAULT_PARENT_NODE	default_parent_node	Default parent node token
FEISHU_NOTIFY_CHAT_ID	notify_chat_id	chat_id for group message notifications

Environment variables take precedence over the configuration in config.yaml.

Verify connectivity:

python skills/feishu-doc/feishu_doc.py test

Trigger conditions

Use this Skill in the following cases:

• The user sends a Feishu link (feishu.cn/docx/, feishu.cn/wiki/, feishu.cn/sheets/)
• The user says "write to Feishu", "sync to knowledge base", "look at the Feishu document", "send to the group"
• The user requests to export, edit, or compare Feishu document content

Read documents

When the user wants to view Feishu document content:

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

Supports all Feishu document URL formats:/docx/、/wiki/、/sheets/、/base/。

When the user wants to understand the knowledge base structure:

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  # 批量导出

Create documents

When the user says "write a Feishu document" or "sync this to Feishu":

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 creating in a knowledge base, if permissions are insufficient, it will automatically downgrade to a cloud document and prompt for manual moving in.

Edit existing documents

When the user says "change this document" or "update paragraph X to ...":

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

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

Output each block's block_id, type, and content summary.

Step 2 — Precise operations:

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              # 清空重写

Knowledge base management

python skills/feishu-doc/feishu_doc.py wiki-spaces                                    # 列出可访问的知识库（发现 space_id）
python skills/feishu-doc/feishu_doc.py wiki-tree <URL>                                # 查看知识库结构
python skills/feishu-doc/feishu_doc.py wiki-move <文档URL> <目标节点token>              # 云文档移入知识库
python skills/feishu-doc/feishu_doc.py wiki-move <文档URL> <目标节点token> --title "X"  # 移入并设置标题
python skills/feishu-doc/feishu_doc.py wiki-sync <md文件> --parent <节点>              # 同步到知识库（幂等）

Permission management

python skills/feishu-doc/feishu_doc.py permission <URL> editable   # 组织内可编辑
python skills/feishu-doc/feishu_doc.py permission <URL> viewable   # 组织内可查看
python skills/feishu-doc/feishu_doc.py permission <URL> public     # 互联网可查看
python skills/feishu-doc/feishu_doc.py permission <URL> closed     # 关闭链接分享

Group messages

When the user says "notify the group" or "send to the Feishu group":

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 条群消息

Typical workflows

"Help me see what is in the knowledge base"

1. wiki-tree List the structure
2. Use read to read documents of interest
3. Summarize and return

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

1. Organize the content as Markdown and write it to a temporary file
2. create --wiki <parent_node> Create
3. If permissions are insufficient, automatically downgrade create(cloud document) → prompt to use wiki-move to migrate in
4. notify Notify the group chat

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

1. list-blocks <URL> List all blocks and block_ids
2. Find the target block
3. update-block <URL> <block_id> "新内容" Precise update

"Convert this WeChat article into a Feishu document"

1. import-wechat <微信URL> Fetch and convert
2. Return the Feishu document link

Notes

• Writing to a knowledge base requires the Bot to be added as an "editable" member of the space; public knowledge bases must be added manually
• wiki-move Prefer using a tenant token (Bot permissions); if that fails, automatically try an OAuth user token
• The Feishu API has rate limits; the tool has built-in automatic retry on 429 (exponential backoff)
• wiki-sync Idempotency protection is in place, so documents with the same name will not be created repeatedly
• Tables with more than 9 rows are automatically split into multiple consecutive tables (Feishu API limitation)
• The content of card messages supports Feishu Markdown (**粗体**、[链接](url)、\n line breaks)