# Feishu Doc

> 飞书文档助手。读写飞书云文档和知识库，支持创建、导出、精确编辑、同步到知识库、群消息通知。当用户提到飞书文档、知识库、wiki，或发送 feishu.cn 链接时使用此 Skill。

- Skill: `0xranx/feishu-doc` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add 0xranx/feishu-doc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/0xranx/feishu-doc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: 0xranx (https://skillmd.com/u/0xranx)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/0xranx/feishu-doc

---


# 飞书文档助手

通过 `feishu_doc.py` 统一管理飞书文档的读取、写入、编辑和知识库操作。

## 前置条件

1. **Python >= 3.11**（feishu-docx 要求）。推荐使用 `uv run --python 3.12` 或确保系统 Python 版本满足要求
2. 安装依赖：`pip install feishu-docx markdown2feishu httpx pyyaml`
3. 配置凭证（二选一）：
   - 设置环境变量 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET`
   - 或编辑 `skills/feishu-doc/config.yaml`
4. 飞书应用需开通权限：`docx:document`（文档读写）、`wiki:wiki`（知识库）、`im:message`（群消息）

### 环境变量对照表

| 环境变量 | config.yaml 键 | 说明 |
|----------|----------------|------|
| `FEISHU_APP_ID` | `app_id` | 飞书应用 ID（必需） |
| `FEISHU_APP_SECRET` | `app_secret` | 飞书应用密钥（必需） |
| `FEISHU_WIKI_SPACE_ID` | `wiki_space_id` | 知识库 space_id（知识库写入必需，可通过 `wiki-spaces` 命令查看） |
| `FEISHU_DEFAULT_PARENT_NODE` | `default_parent_node` | 默认父节点 token |
| `FEISHU_NOTIFY_CHAT_ID` | `notify_chat_id` | 群消息通知的 chat_id |

环境变量优先于 config.yaml 中的配置。

验证连通性：
```bash
python skills/feishu-doc/feishu_doc.py test
```

## 触发条件

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

## 读取文档

当用户想查看飞书文档内容时：
```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  # 批量导出
```

## 创建文档

当用户说「写一篇飞书文档」「把这个同步到飞书」时：
```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>  # 创建到知识库
```

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

## 编辑已有文档

当用户说「改一下这个文档」「把第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              # 清空重写
```

## 知识库管理

```bash
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 <节点>              # 同步到知识库（幂等）
```

## 权限管理

```bash
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     # 关闭链接分享
```

## 群消息

当用户说「通知群里」「发到飞书群」时：
```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 条群消息
```

## 典型工作流

### 「帮我看看知识库里有什么」
1. `wiki-tree` 列出结构
2. 用 `read` 读取感兴趣的文档
3. 总结返回

### 「把这份报告写到知识库运营相关下面」
1. 整理内容为 Markdown，写入临时文件
2. `create --wiki <parent_node>` 创建
3. 如果权限不足，自动降级 `create`（云文档）→ 提示用 `wiki-move` 迁入
4. `notify` 通知群聊

### 「这个文档第二段数据错了，改成 XXX」
1. `list-blocks <URL>` 列出所有块和 block_id
2. 找到目标块
3. `update-block <URL> <block_id> "新内容"` 精确更新

### 「把这篇微信文章转成飞书文档」
1. `import-wechat <微信URL>` 抓取转换
2. 返回飞书文档链接

## 注意事项

- 知识库写入需要 Bot 被添加为空间「可编辑」成员；公开知识库需人工添加
- `wiki-move` 优先使用 tenant token（Bot 权限），失败后自动尝试 OAuth user token
- 飞书 API 有限流，工具内置 429 自动重试（指数退避）
- `wiki-sync` 有幂等保护，同名文档不会重复创建
- 表格超过 9 行会自动拆分成多个连续表格（飞书 API 限制）
- 卡片消息的内容支持飞书 Markdown（`**粗体**`、`[链接](url)`、`\n` 换行）