# 飞书 MCP 工具使用指南

本项目配置了两个飞书相关的 MCP 服务，它们各有侧重，需要根据任务类型选择合适的工具。

## 🔧 MCP 服务概览

### feishu-docx-blocks（自定义服务，优先使用）
专注于**文档内容深度解析和媒体处理**，适用于：
- 获取文档块结构和富文本内容（支持缓存、元数据提取）
- 下载图片和画板（返回 ImageContent，支持视觉分析，封装完善）
- 文档内容搜索（关键词定位+上下文）
- 读取文档内嵌入的电子表格
- Token 管理和授权操作

### feishu-mcp（飞书官方服务，补充和兜底）
提供**飞书全产品线 API**，适用于：
- 多维表格（Bitable）的增删改查
- 文档的创建、编辑、删除
- 知识库节点信息获取和管理
- 云文档全局搜索和创建
- 作为本项目工具失败时的兜底方案

---

## 🎯 工具选择优先级原则

**核心原则：优先使用 feishu-docx-blocks，官方工具作为补充和兜底**

1. ✅ **本项目有且封装更好的功能** → 优先使用本项目
2. ⚠️ **本项目工具失败** → 使用官方工具作为兜底
3. ❌ **本项目没有的功能**（如创建文档、多维表格） → 使用官方工具

---

## 📋 工具选择决策表

### 场景1：获取飞书文档内容

| 需求 | 推荐工具（优先级） | 服务 | 兜底方案 |
|------|-------------------|------|---------|
| 🆕 一键获取完整内容（含图片画板） | `get_document_with_media` 🥇 | feishu-docx-blocks | 无（仅本项目支持） |
| 🆕 搜索文档中的特定内容 | `search_document_content` 🥇 | feishu-docx-blocks | 手动用 `get_document_blocks` + 文本搜索 |
| 🆕 读取电子表格内容 | `get_sheet_content` 🥇 | feishu-docx-blocks | 无（仅本项目支持） |
| 获取文档块结构、富文本、图表元数据 | `get_document_blocks` 🥇 | feishu-docx-blocks | `docx_v1_documentBlock_list`（无缓存） |
| 仅获取纯文本（无格式） | `docx_v1_document_rawContent` 🥈 | feishu-mcp | `get_document_blocks` 提取文本 |
| 获取超长文档（>500块） | `get_document_blocks` + `fetch_all=true` 🥇 | feishu-docx-blocks | `docx_v1_documentBlock_list` 分页 |

**🆕 新增工具说明**：
- `get_document_with_media`：**推荐首选**！只需提供URL，自动完成链接解析+获取文档+下载图片画板
- `search_document_content`：**🆕 v2.2 智能层级搜索**，返回关键词的**标题层级上下文**（H1/H2/H3），让 AI 决定读取范围
- `get_sheet_content`：读取文档中嵌入的电子表格内容，支持 Markdown 表格格式输出
- `get_document_blocks` 现已支持**缓存机制**（默认开启，10分钟过期），可用 `force_refresh=true` 强制刷新

**⚠️ 重要**：
- 读取文档内容时，**优先使用本项目工具**（有缓存、元数据提取、更友好的格式）
- 仅当本项目工具失败时，才使用官方工具作为兜底
- 如果用户需要查看图片或画板，**必须使用** `feishu-docx-blocks` 的工具！

### 场景2：解析文档链接

| 链接类型 | 第一步（优先） | 第二步（兜底） |
|----------|---------------|---------------|
| docx 链接 | `parse_document_id` 🥇 → 直接获取 document_id | 手动从URL提取（27字符） |
| wiki 链接 | `parse_document_id` 🥇 → 尝试自动获取 | `wiki_v2_space_getNode` 🥈 获取 obj_token |

**Wiki 链接处理流程**：
```
1. 调用 parse_document_id(url="https://xxx.feishu.cn/wiki/TOKEN") [优先]
2. 如果返回 success=true → 使用 document_id
3. 如果返回 success=false 且有 fallback_tool → 调用 wiki_v2_space_getNode [兜底]
4. 从返回的 node.obj_token 获取 document_id
```

### 场景3：下载媒体内容

| 内容类型 | 推荐工具（优先级） | 说明 | 兜底方案 |
|---------|-------------------|------|---------|
| 图片块 | `download_image_blocks` 🥇 | 需要 document_id 和 image_block_ids，一键下载返回ImageContent | `drive_v1_media_batchGetTmpDownloadUrl` + 手动下载 |
| 画板（Board） | `download_board_as_image` 🥇 | 需要画板的 **token**（不是 block_id），导出为图片 | `drive_v1_media_batchGetTmpDownloadUrl` + 手动下载 |

**⚠️ 重要说明**：
- **优先使用本项目工具**：封装完善，一键下载，自动保存到工作区，返回 ImageContent 便于视觉分析
- **官方兜底方案**：如果本项目工具失败，可以使用以下步骤手动实现：
  1. 调用 `drive_v1_media_batchGetTmpDownloadUrl` 获取临时下载链接
  2. 使用代码从返回的 URL 下载图片到本地
  3. 但此方法需要更多步骤且封装不完善，不推荐作为首选

**获取画板 token 的方法**：
1. 调用 `get_document_blocks` 获取文档块
2. 在返回的"图表元数据信息"中找到类型为"画板"的项
3. 使用其 `token` 字段（如 `HCXEwkQOmh6CpEbVfRccAC1SnHd`）

### 场景4：操作多维表格

| 操作 | 推荐工具 | 服务 | 说明 |
|------|----------|------|------|
| 读取文档内嵌入Sheet | `get_sheet_content` 🥇 | feishu-docx-blocks | 提取文档中的电子表格 |
| 创建独立Bitable | `bitable_v1_app_create` | feishu-mcp | 仅官方支持 |
| 查询Bitable记录 | `bitable_v1_appTableRecord_search` | feishu-mcp | 仅官方支持 |
| 新增Bitable记录 | `bitable_v1_appTableRecord_create` | feishu-mcp | 仅官方支持 |
| 批量操作Bitable | `bitable_v1_appTableRecord_batch*` | feishu-mcp | 仅官方支持 |

**说明**：
- **文档内嵌入的Sheet**：使用本项目 `get_sheet_content`
- **独立的多维表格（Bitable）**：使用官方 `bitable_v1_*` 系列工具

### 场景5：搜索文档

| 搜索范围 | 推荐工具 | 服务 | 说明 |
|---------|---------|------|------|
| 文档内搜索关键词 | `search_document_content` 🥇 | feishu-docx-blocks | **🆕 v2.2 智能层级搜索**：返回 H1/H2/H3 层级上下文，AI 可选 narrow/medium/wide 范围 |
| 全局搜索云文档 | `docx_builtin_search` | feishu-mcp | 跨文件夹搜索 |
| 知识库内搜索 | `wiki_v1_node_search` | feishu-mcp | 知识库范围搜索 |

### 场景6：创建/编辑文档

| 操作 | 推荐工具 | 服务 | 说明 |
|------|---------|------|------|
| 创建文档 | `docx_v1_document_create` | feishu-mcp | 本项目不支持（只读） |
| 添加文档内容 | `docx_v1_documentBlockChildren_create` | feishu-mcp | 本项目不支持（只读） |
| 更新文档块 | `docx_v1_documentBlock_patch` | feishu-mcp | 本项目不支持（只读） |
| 批量更新块 | `docx_v1_documentBlock_batchUpdate` | feishu-mcp | 本项目不支持（只读） |
| 删除文档内容 | `docx_v1_documentBlockChildren_batchDelete` | feishu-mcp | 本项目不支持（只读） |

### 场景7：授权和 Token 管理

| 操作 | 推荐工具 | 服务 | 说明 |
|------|----------|------|------|
| 查看 Token 状态 | `get_current_token` 🥇 | feishu-docx-blocks | 检查有效期和权限 |
| 重新授权 | `reauthorize` 🥇 | feishu-docx-blocks | Token 过期或权限不足时使用 |
| 检查端口占用 | `check_auth_port` 🥇 | feishu-docx-blocks | 授权失败时诊断 |
| 清理端口 | `cleanup_auth_port` 🥇 | feishu-docx-blocks | 端口被占用时使用 |

**说明**：Token 管理功能仅本项目提供，官方不支持。

---

## 🚨 常见错误处理

### 错误1：权限不足（99991679）
```
错误信息：应用未获取所需的用户授权：[board:whiteboard:node:read]
```
**解决方案**：
1. 在飞书开放平台申请相应权限
2. 调用 `reauthorize` 重新授权

### 错误2：Token 缺失（99991661）
```
错误信息：Missing access token for authorization
```
**解决方案**：
1. 调用 `get_current_token` 检查 Token 状态
2. 调用 `reauthorize` 重新授权

### 错误3：Wiki 文档无法解析
**解决方案**：
1. 优先使用 `parse_document_id` 尝试自动解析
2. 如果失败，使用 `wiki_v2_space_getNode` 获取节点信息
3. 从返回的 `node.obj_token` 获取 document_id

### 错误4：本项目工具失败
**解决方案（兜底策略）**：
1. **获取文档内容失败** → 使用 `docx_v1_documentBlock_list`（官方）
2. **下载图片失败** → 使用 `drive_v1_media_batchGetTmpDownloadUrl` 获取链接后手动下载
3. **解析链接失败** → 使用 `wiki_v2_space_getNode` 或手动从URL提取ID

---

## 📌 工具调用最佳实践

### 🆕 最简方式：一键获取完整内容

```
只需一步：get_document_with_media(url="https://xxx.feishu.cn/wiki/TOKEN")
         → 自动解析链接
         → 自动获取文档块
         → 自动下载图片和画板
         → 返回文本内容 + ImageContent
         
⚠️ 如果失败：
  兜底方案1：使用 parse_document_id + get_document_blocks + download_image_blocks
  兜底方案2：使用官方 docx_v1_documentBlock_list（无图片）
```

### 🆕 搜索特定主题（如"青少年模式"）- v2.2 智能层级搜索

```
步骤1: search_document_content(document_id, keywords=["青少年模式"]) [优先]
       → 🆕 v2.2 返回标题层级上下文：
         H1 [  10] 功能需求      → wide 范围 [10-100]
           H2 [  30] 账号安全    → medium 范围 [30-80]
             H3 [  40] 青少年保护 → narrow 范围 [40-60]
               >>> [  45] 关键词匹配位置
       → 返回建议的读取范围（narrow/medium/wide）
       → 返回附近的图片/画板元数据

步骤2: AI 根据需要选择读取范围
       → 只需精准内容 → 读取 narrow (H3) 范围
       → 需要更多上下文 → 读取 medium (H2) 范围
       → 需要完整章节 → 读取 wide (H1) 范围

步骤3: get_document_blocks(document_id, start_position=X, end_position=Y)
       → 读取选定范围的详细内容

步骤4: download_image_blocks / download_board_as_image
       → 根据步骤1返回的元数据下载需要的媒体

⚠️ 如果失败：
  兜底方案：使用 get_document_blocks 获取全文，手动搜索关键词
```

### 优先级策略（读取文档内容）

```
第1优先级：get_document_with_media (本项目) 
          → 一键获取，含图片画板，最省心
          
第2优先级：get_document_blocks (本项目)
          → 有缓存，有元数据，格式友好
          
第3优先级：docx_v1_documentBlock_list (官方，兜底)
          → 无缓存，无元数据，但可用
```

### 优先级策略（下载图片）

```
第1优先级：download_image_blocks (本项目)
          → 一键下载，自动保存，返回ImageContent
          
第2优先级：drive_v1_media_batchGetTmpDownloadUrl (官方，兜底)
          → 获取下载链接后需手动下载，步骤较多
```

---

## 🔑 关键区分和决策树

### 决策树：我应该使用哪个服务？

```
问题：需要做什么？
│
├─ 📖 读取文档内容
│  ├─ 需要图片/画板？
│  │  ├─ 是 → feishu-docx-blocks (get_document_with_media) 🥇
│  │  └─ 否 → feishu-docx-blocks (get_document_blocks) 🥇，失败则用官方 🥈
│  │
│  ├─ 需要搜索特定内容？
│  │  ├─ 文档内搜索 → feishu-docx-blocks (search_document_content) 🥇
│  │  └─ 全局搜索 → feishu-mcp (docx_builtin_search)
│  │
│  └─ 需要读取表格？
│     ├─ 文档内嵌入Sheet → feishu-docx-blocks (get_sheet_content) 🥇
│     └─ 独立Bitable → feishu-mcp (sheets_v3_* / bitable_v1_*)
│
├─ 🖼️ 下载图片/画板
│  └─ feishu-docx-blocks (download_image_blocks / download_board_as_image) 🥇
│     失败则用官方 drive_v1_media_batchGetTmpDownloadUrl + 手动下载 🥈
│
├─ ✏️ 创建/编辑文档
│  └─ feishu-mcp (docx_v1_document_create / docx_v1_documentBlock_*) (仅官方)
│
├─ 📊 操作多维表格（Bitable）
│  └─ feishu-mcp (bitable_v1_*) (仅官方)
│
├─ 🗂️ 知识库管理
│  └─ feishu-mcp (wiki_v2_*) (仅官方)
│
├─ 🔍 云空间文件管理
│  └─ feishu-mcp (drive_v1_*) (仅官方)
│
└─ 🔐 Token 管理/授权问题
   └─ feishu-docx-blocks (get_current_token / reauthorize) (仅本项目)
```

### 功能对比表

| 场景 | 使用 feishu-docx-blocks | 使用 feishu-mcp | 优先级 |
|------|------------------------|-----------------|--------|
| 读取文档内容 | ✅ 优先使用（缓存+元数据） | ⚠️ 兜底（仅纯文本，无缓存） | 🥇 本项目优先 |
| 下载图片/画板 | ✅ 优先使用（一键下载） | ⚠️ 兜底（需手动下载） | 🥇 本项目优先 |
| 读取电子表格 | ✅ 唯一选择 | ❌ 不支持 | 🥇 仅本项目 |
| 文档内容搜索 | ✅ 唯一选择（🆕 v2.2 智能层级搜索） | ❌ 不支持 | 🥇 仅本项目 |
| 一键获取完整内容 | ✅ 唯一选择 | ❌ 不支持 | 🥇 仅本项目 |
| 操作多维表格（Bitable） | ❌ 不支持 | ✅ 唯一选择 | 🥈 仅官方 |
| 全局搜索云文档 | ❌ 不支持 | ✅ 唯一选择 | 🥈 仅官方 |
| 创建/编辑文档 | ❌ 只读 | ✅ 唯一选择 | 🥈 仅官方 |
| 获取wiki节点 | ⚠️ 可能失败 | ✅ 更可靠 | 🥈 官方优先 |
| Token管理/授权 | ✅ 唯一选择 | ❌ 不支持 | 🥇 仅本项目 |

---

## 📝 重要提示

### 核心原则（必须遵守）

1. **📖 读取文档** → **优先本项目**，失败才用官方兜底
   - 原因：本项目有缓存、元数据提取、Markdown表格转换
   - 兜底：官方 `docx_v1_documentBlock_list`（功能较少但可用）

2. **🖼️ 下载图片/画板** → **优先本项目**，失败才用官方兜底
   - 原因：本项目封装完善，一键下载，自动保存
   - 兜底：官方 `drive_v1_media_batchGetTmpDownloadUrl` + 手动下载代码

3. **📊 多维表格/创建编辑** → **仅官方支持**
   - 原因：本项目只读，不支持写入操作

4. **🔍 全局搜索/知识库管理** → **仅官方支持**
   - 原因：本项目专注于单文档深度解析

5. **🔐 Token 问题排查** → **仅本项目支持**
   - 原因：官方不提供 Token 管理工具

### 常见误区（避免）

❌ **错误**：直接使用官方 `docx_v1_documentBlock_list` 读取文档
✅ **正确**：优先使用本项目 `get_document_blocks`（有缓存、元数据）

❌ **错误**：用官方 `drive_v1_media_batchGetTmpDownloadUrl` 作为下载图片首选
✅ **正确**：优先使用本项目 `download_image_blocks`（封装完善）

❌ **错误**：用本项目读取独立的多维表格（Bitable）
✅ **正确**：使用官方 `bitable_v1_*` 系列（本项目只支持文档内嵌入Sheet）

### 兜底策略（工具失败时）

当本项目工具失败时，按以下优先级尝试：

```
1. 读取文档内容失败
   → 兜底：docx_v1_documentBlock_list (官方)
   
2. 下载图片失败
   → 兜底：drive_v1_media_batchGetTmpDownloadUrl + 手动下载 (官方)
   
3. 解析链接失败
   → 兜底：wiki_v2_space_getNode 或手动提取ID (官方)
   
4. 搜索文档内容失败
   → 兜底：get_document_blocks + 手动文本搜索
   → 或使用 extract_document_structure 获取标题树，手动定位章节
```

### 性能优化建议

- ✅ 利用本项目的**缓存机制**（10分钟），避免重复调用 API
- ✅ 批量下载图片时，每批最多 5 个（API 限制）
- ✅ 超长文档使用 `fetch_all=true` 参数获取完整内容
- ✅ Token 自动刷新机制（剩余5分钟自动刷新）
- ✅ 🆕 **v2.2 智能层级搜索**：先搜索获取层级上下文，再精准读取所需范围，大幅节省 Token

