Metadata-Version: 2.4
Name: feishu-docx-blocks
Version: 3.2.2
Summary: 飞书文档 MCP Server — 帮助 AI Agent 读取飞书文档富文本、图片与表格内容
License: MIT
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25.0
Requires-Dist: mcp>=0.9.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# FeishuMCP - 飞书文档 Block 内容获取 MCP 服务器

**版本**: v3.2.2 | **更新日期**: 2026-04-16 | **核心升级**: 显式应用凭证配置 + 统一 8082 回调端口 + uvx 一键安装 + 智能图片位置关联 + 智能层级搜索

这是一个基于 Python 和 MCP（Model Context Protocol）实现的飞书文档 Block 内容获取服务器。它提供了获取飞书文档中富文本块（Block）内容的功能，支持图片自动提取、表格转换、画板导出等特性。

> 💡 **推荐搭配使用**：本项目专注于文档内容深度解析和媒体处理，建议与 [飞书官方 MCP](https://open.feishu.cn/page/mcp/) 配合使用，以获得完整的飞书 API 能力（如多维表格操作、云文档搜索等）。

## ✨ 功能特性

### 核心功能
- 🆕 **一键获取增强内容** (`get_document_with_media`) - **推荐首选！** 只需提供URL，自动完成链接解析、获取文档、下载图片画板（支持 `max_text_chars` 控制文本截断，`0` 表示不截断）
- 🔥 **智能图片位置关联** (v2.1) - **文件路径作为唯一标识**，精准关联图片和文档内容
  - 文本中插入 `[📷 图片: feishu_images/xxx.png - 所属章节]` 标记
  - 自动提取图片所属章节、前后文本、位置索引
  - 容错处理：某张图片下载失败不影响其他图片
  - Cursor 可通过文件路径直接读取图片，结合上下文分析
- 🆕 **文档内容搜索** (`search_document_content`) - 在大文档中搜索关键词，**v2.2 返回标题层级上下文**（H1/H2/H3），让 AI 决定读取范围
- 🆕 **读取电子表格** (`get_sheet_content`) - 读取文档中嵌入的电子表格内容，支持 Markdown 表格格式输出
- ✅ **获取文档所有块** (`get_document_blocks`) - 获取文档中所有块的富文本内容，支持分页查询，**支持缓存（10分钟）**
- 🧩 **增强文本长度可控** (`get_document_with_media.max_text_chars`) - 默认返回前10000字符，设为 `0` 可返回完整增强文本
- ✅ **获取单个块详情** (`get_block_detail`) - 获取指定块的详细信息，包括类型、内容、样式等
- ✅ **获取块的子块** (`get_block_children`) - 获取指定块的所有子块列表，支持分页查询
- 🔗 **解析文档链接** (`parse_document_id`) - 从飞书文档链接中自动解析 document_id，支持 docx 和 wiki 链接
- 🖼️ **下载图片块** (`download_image_blocks`) - 下载指定的图片块到工作区，支持批量下载，**v2.1 新增上下文信息**
- 🎨 **下载画板为图片** (`download_board_as_image`) - 将画板导出为图片，支持视觉理解

### v3.0 新增工具 ⭐

#### 通用文档分析工具（3个）
- 🆕 **预览表格表头** (`preview_document_tables`) - 智能识别文档中所有表格类型，辅助决策该解析哪个表格
- 🆕 **提取文档标题树** (`extract_document_structure`) - 提取H1/H2/H3/H4标题，构建树状结构，适用于任何文档的结构分析
- 🆕 **按标题拆解文档** (`get_document_section_digests`) - 按标题层级拆解文档，生成章节摘要和结构化信号（图片/表格/代码/接口），供模块归因决策

#### 测试用例生成专用工具（特定需求）
- ⭐ **解析排期表格** (`parse_schedule_table`) - 解析任务排期表格，自动提取模块划分，**专用于测试用例生成**
- ✅ **生成模块索引** (`generate_module_index`) - 为测试用例生成提供章节索引（v3.0优化支持 `chapter_hints`）

**v3.0 工具统计**：
- **新增工具总数**：4个（3个通用 + 1个专用）
- **工具总数**：19个（14个文档工具 + 1个辅助工具 + 4个授权工具）

**专用工具的核心价值**（测试用例生成场景）：
- 🌟 **100%准确的模块定义**：基于排期表格的权威数据
- 🌟 **完整兜底策略**：无排期表格时使用标题树自动推断
- 🌟 **零人工干预**：端到端自动化，6秒完成42个模块提取
- 🌟 **精准章节定位**：chapter_hints替代关键词搜索

> 📌 **说明**：`parse_schedule_table` 和 `generate_module_index` 是为"根据飞书云文档生成测试用例"这一特定需求设计的工具。而 `preview_document_tables`、`extract_document_structure` 和 `get_document_section_digests` 是通用工具，适用范围更广。

### 授权管理
- 🔍 **查看 Token 信息** (`get_current_token`) - 查看当前使用的 user_access_token 信息，包括有效期、剩余时间等
- 🔄 **重新授权** (`reauthorize`) - 手动触发重新授权流程，获取新的 token
- 🔌 **端口检查** (`check_auth_port`) - 检查授权回调端口占用情况
- 🧹 **端口清理** (`cleanup_auth_port`) - 清理占用授权回调端口的进程

### 数据处理
- 🖼️ **图片元数据提取** - 自动识别图片块，提取图片的 block_id、token、尺寸等元数据
- 📊 **表格内容转换** - 自动将表格块转换为 Markdown 格式，便于 Cursor 理解和处理
- 📝 **文本内容提取** - 自动提取 Block 中的纯文本内容，包括标题、列表、代码块等结构化文本
- 🎨 **画板识别** - 自动识别画板块并提取元数据

### 🔥 v2.1 核心能力：智能图片位置关联（BlockProcessor）

**核心方法**：`extract_text_with_media_markers()`

**功能说明**：
从文档块中提取文本内容，并在媒体位置插入带有文件路径的标记，使 Cursor 能够精准关联图片和文档内容。

**关键特性**：
- **文件路径作为唯一标识**：`feishu_images/xxx.png`（基于 block_id + token）
- **文件路径在下载前就能确定**：不受下载顺序影响
- **容错处理**：某张图片下载失败不影响其他图片的关联
- **自动章节定位**：提取所属章节路径、前后文本、最近标题
- **Cursor 友好**：可以通过文件路径直接读取图片文件

**使用示例**：
```python
text, media_list = BlockProcessor.extract_text_with_media_markers(blocks)
# 文本中包含：[📷 图片: feishu_images/doxcn123_abc456.png - 需求背景]
# media_list 包含：文件路径、所属章节、上下文等元数据
```

---

### 表格处理能力（BlockProcessor）
项目提供完整的表格处理方法链，支持多种表格操作场景：

| 方法 | 职责 | 使用场景 |
|------|------|----------|
| `extract_table_info()` | 提取表格结构元信息 | 了解表格行列数、单元格ID等 |
| `extract_table_summary()` | 生成表格摘要描述 | 快速展示表格概况 |
| `build_cell_content_map()` | 构建单元格ID→内容映射 | 表格内容提取的预处理 |
| `table_to_matrix()` | 转换为二维字符串矩阵 | 自定义格式化或数据分析 |
| `table_to_text()` | 转换为纯文本格式 | 文本搜索、日志输出 |
| `table_to_markdown()` | 转换为Markdown格式 | 导出文档、生成报告 |

### 画板处理能力（BlockProcessor）
项目支持将画板导出为图片，便于 Cursor 使用视觉能力理解画板内容：

| 方法 | 职责 | 使用场景 |
|------|------|----------|
| `extract_board_info()` | 提取画板结构元信息 | 了解画板token等元数据 |
| `extract_board_summary()` | 生成画板摘要描述 | 快速展示画板标识 |
| `get_board_download_token()` | 获取导出图片用token | 供 download_board_as_image 使用 |

### 系统特性
- 🔄 **Token 自动管理** - 支持 user_access_token 的自动获取、刷新和过期检测，提前 5 分钟自动刷新，无需手动维护
- 🚀 **开箱即用** - 支持 `uvx` 直接安装；配置应用凭证后即可完成浏览器授权并开始使用
- 🏗️ **模块化架构** - 工具采用模块化设计，易于维护和扩展
- 🐛 **完善的调试支持** - 详细的日志输出和错误处理，便于问题排查

> 📖 **详细工具文档**：查看 [MCPTOOLS.md](./MCPTOOLS.md) 了解每个工具的详细使用方法

## 🚀 快速开始

### 方式一：uvx 一键安装（推荐，无需 clone 仓库）

在 MCP 配置文件中添加：

- **Cursor**：`~/.cursor/mcp.json`
- **Claude Code 用户级**：`~/.claude.json`
- **Claude Code 项目级**：项目根目录的 `.mcp.json`

```json
{
  "mcpServers": {
    "feishu-docx-blocks": {
      "command": "uvx",
      "args": ["feishu-docx-blocks@latest"],
      "env": {
        "FEISHU_APP_ID": "<your_app_id>",
        "FEISHU_APP_SECRET": "<your_app_secret>"
      }
    }
  }
}
```

> ⚠️ **`env` 字段必需**：`FEISHU_APP_ID` / `FEISHU_APP_SECRET` 由分发方通过内部渠道发给团队成员（不再内置在代码中）。
>
> 也可以把凭证写入 `~/.config/feishu-docx-blocks/.env` 文件，`env` 字段留空即可。

重启 Cursor / Claude Code，首次使用工具时会自动弹出浏览器完成飞书授权，之后的 token 会保存到 `~/.config/feishu-docx-blocks/.env`。

> 需要先安装 [uv](https://docs.astral.sh/uv/getting-started/installation/)（`curl -LsSf https://astral.sh/uv/install.sh | sh`）

### 方式二：从源码安装（开发者）

1. `git clone` 本仓库
2. 安装依赖：`pip install -e .`
3. 把 `FEISHU_APP_ID` / `FEISHU_APP_SECRET` 写入 `~/.config/feishu-docx-blocks/.env`
4. 运行授权脚本：`python auto_auth_and_setup.py`
5. 在浏览器中完成授权
6. 重启 Cursor，开始使用！

## 🎯 搭配官方 MCP 使用（推荐）

本项目专注于**文档内容深度解析和媒体处理**，建议与飞书官方 MCP 配合使用，形成完整的飞书 API 能力：

| 能力 | feishu-docx-blocks（本项目） | feishu-mcp（官方） | 推荐优先级 |
|------|------------------------------|-------------------|-----------|
| 读取文档内容 | ✅ 富文本+图表元数据+缓存 | ⚠️ 仅纯文本（`docx_v1_document_rawContent`） | 🥇 **优先本项目** |
| 下载图片/画板 | ✅ 封装完善，一键下载 | ⚠️ 可用 `drive_v1_media_batchGetTmpDownloadUrl` 手动下载 | 🥇 **优先本项目** |
| 读取电子表格 | ✅ 文档内嵌入Sheet | ❌ 不支持 | 🥇 **仅本项目** |
| 文档内容搜索 | ✅ 关键词定位+上下文 | ❌ 不支持 | 🥇 **仅本项目** |
| 一键获取完整内容 | ✅ URL→文本+图片+画板 | ❌ 需多步调用 | 🥇 **仅本项目** |
| 操作多维表格 | ❌ 不支持 | ✅ `bitable_v1_*` 系列 | 🥈 **仅官方** |
| 全局搜索云文档 | ❌ 不支持 | ✅ `docx_builtin_search` | 🥈 **仅官方** |
| 创建/编辑文档 | ❌ 只读 | ✅ `docx_v1_document_create` 等 | 🥈 **仅官方** |
| 知识库管理 | ⚠️ 仅解析链接 | ✅ `wiki_v2_*` 系列 | 🥈 **仅官方** |
| Token 管理 | ✅ 完整支持 | ❌ 不支持 | 🥇 **仅本项目** |

### 工具选择原则

1. **📖 读取文档内容**：优先使用本项目的 `get_document_blocks` 或 `get_document_with_media`
   - ✅ 本项目优势：缓存机制、图表元数据提取、Markdown表格转换
   - ⚠️ 官方兜底：如果本项目失败，可使用 `docx_v1_documentBlock_list`（无缓存）

2. **🖼️ 下载图片/画板**：优先使用本项目的 `download_image_blocks` 和 `download_board_as_image`
   - ✅ 本项目优势：一键下载、自动保存、返回ImageContent、支持批量处理
   - ⚠️ 官方兜底：如果本项目失败，可以通过以下步骤手动实现：
     1. 使用 `drive_v1_media_batchGetTmpDownloadUrl` 获取临时下载链接
     2. 使用代码下载图片到本地
     3. 但此方法需要更多步骤，封装不如本项目完善

3. **🔍 搜索内容**：
   - **文档内搜索**：仅本项目支持 `search_document_content`
   - **全局搜索**：仅官方支持 `docx_builtin_search`（跨文件夹搜索）

4. **✏️ 创建/编辑**：仅官方支持，本项目为只读工具

5. **📊 多维表格**：
   - **文档内嵌入Sheet**：使用本项目 `get_sheet_content`
   - **独立Bitable**：使用官方 `bitable_v1_*` 系列工具

### 配置双 MCP 服务

在 `~/.cursor/mcp.json` 中同时配置两个服务：

```json
{
  "mcpServers": {
    "feishu-docx-blocks": {
      "command": "uvx",
      "args": ["feishu-docx-blocks@latest"],
      "env": {
        "FEISHU_APP_ID": "<your_app_id>",
        "FEISHU_APP_SECRET": "<your_app_secret>"
      }
    },
    "feishu-mcp": {
      "url": "https://open.feishu.cn/mcp/stream/your_private_key",
      "headers": {}
    }
  }
}
```

> 📖 飞书官方 MCP 安装说明：https://open.feishu.cn/page/mcp/

## 📋 添加 Project Rules（强烈推荐）

为了帮助 Cursor 更高效地选择正确的工具，项目提供了 `.cursorrules` 文件，包含两个 MCP 服务的工具选择指南。

### 启用方法

`.cursorrules` 文件已包含在项目中，Cursor 会自动读取。文件内容包括：
- 两个 MCP 服务的能力对比
- 不同场景下的工具选择决策表
- 常见错误处理方案
- 最佳实践工作流程

### 核心规则摘要

```
📌 获取文档内容 → 优先使用 feishu-docx-blocks 的 get_document_blocks
📌 下载图片/画板 → 只能使用 feishu-docx-blocks
📌 操作多维表格 → 只能使用 feishu-mcp
📌 Wiki链接解析 → parse_document_id，失败则用 wiki_v2_space_getNode
📌 Token问题排查 → 使用 get_current_token 和 reauthorize
```

## 💬 使用 Prompt 模板

项目在 `prompts/` 目录下提供了常用任务的提示词模板，帮助您快速开始。

### 目录结构

```
prompts/
└── 飞书文档分析.md    # 文档分析相关的 Prompt 模板
```

### 使用方法

**方法一：直接复制使用**

打开 `prompts/飞书文档分析.md`，复制所需的模板，替换其中的占位符（如 `[文档URL]`、`【关键词】`）后发送给 Cursor。

**方法二：在对话中引用**

在 Cursor 对话中使用 `@prompts/飞书文档分析.md` 引用模板文件，然后告诉 AI 使用哪个模板。

### 模板示例

```markdown
# 获取文档特定章节内容
请帮我获取飞书文档 https://xxx.feishu.cn/wiki/XXX 中与【青少年模式】相关的内容，包括：
1. 相关章节的文字描述
2. 该章节中的图片和画板（如有）
3. 对图表内容的分析
```

```markdown
# 技术文档分析
请分析这个技术文档 https://xxx.feishu.cn/docx/XXX：
1. 提取所有接口定义（找到相关表格）
2. 下载并分析流程图/架构图
3. 总结核心实现逻辑
```

## 📦 安装

### 方式一：uvx 一键安装（推荐）

> **前提**：已安装 [uv](https://docs.astral.sh/uv/getting-started/installation/)
> ```bash
> curl -LsSf https://astral.sh/uv/install.sh | sh
> ```

在 MCP 配置文件中添加（路径见上文"快速开始"）：

```json
{
  "mcpServers": {
    "feishu-docx-blocks": {
      "command": "uvx",
      "args": ["feishu-docx-blocks@latest"],
      "env": {
        "FEISHU_APP_ID": "<your_app_id>",
        "FEISHU_APP_SECRET": "<your_app_secret>"
      }
    }
  }
}
```

> ⚠️ `FEISHU_APP_ID` / `FEISHU_APP_SECRET` 由分发方提供（团队内部渠道），或在[飞书开发者后台](https://open.feishu.cn/app)自建应用获取。

重启 Cursor / Claude Code，**首次调用任意工具时会自动弹出浏览器完成飞书授权**。

授权后 token 自动保存到 `~/.config/feishu-docx-blocks/.env`，后续启动自动读取，长期有效（自动刷新）。

### 方式二：从源码安装（开发者）

```bash
git clone https://github.com/your-org/FeishuMCP.git
cd FeishuMCP
pip install -e .
# 先把 FEISHU_APP_ID / FEISHU_APP_SECRET 写入 ~/.config/feishu-docx-blocks/.env
python auto_auth_and_setup.py  # 授权并自动写入 mcp.json
```

**自建飞书应用需要配置：**
- 重定向 URL：`http://localhost:8082/callback`
- 权限：`docx:document:readonly` 等（详见 `docs/权限申请指南.md`）

**说明：**
- 应用凭证由用户显式提供（`env` 字段或 `.env` 文件），不再内置默认值
- **Token 配置**：token 统一保存在 `~/.config/feishu-docx-blocks/.env`，不要将 token 放入 `mcp.json`

## 🚀 使用

### 在 Cursor 中使用

配置完成后，重启 Cursor，即可在对话中使用 MCP 工具。

**快速开始示例：**

```python
# 场景1：获取文档内容
# 1. 解析文档链接获取 document_id
parse_document_id(url="https://xxx.feishu.cn/docx/VQdXdKssaognlrxD5CIcaA7OnDf")

# 2. 获取文档的所有块
get_document_blocks(document_id="VQdXdKssaognlrxD5CIcaA7OnDf")

# 3. 下载图片
download_image_blocks(
    document_id="VQdXdKssaognlrxD5CIcaA7OnDf",
    image_block_ids=["block_id_1", "block_id_2"]
)
```

**v3.0 智能模块提取示例：** ⭐

```python
# 场景2：自动提取模块划分（v3.0推荐）
# 1. 并行调用工具获取结构化数据
schedule = parse_schedule_table(document_id="排期文档ID")
# → 返回：42个模块，包含优先级、测试点等

structure = extract_document_structure(document_id="需求文档ID")
# → 返回：910个标题，树状结构+扁平列表

# 2. Cursor智能提炼（自动执行）
# - 在标题树中查找与表格模块匹配的章节
# - 生成chapter_hints（精准章节定位）
# - 标注置信度（high/medium/low）
# → 输出：modules-list.json（100%准确）

# 3. 逐模块生成索引（使用chapter_hints）
generate_module_index(
    module_id="M25",
    module_name="首页-发现-专栏",
    document_id="需求文档ID",
    keywords=["专栏", "发现页"],
    chapter_hints=["2.3 发现Tab", "专栏模块"]  # ⭐ 精准定位
)
# → 输出：module-M25-index.md（只包含相关章节，节省60-80% token）
```

> 📖 **详细使用说明**：查看 [MCPTOOLS.md](./MCPTOOLS.md) 了解每个工具的详细使用方法、参数说明和使用场景。
> 
> 🚀 **v3.0 快速开始**：查看 [快速开始指南-v3.0.md](../快速开始指南-v3.0.md) 了解智能模块提取完整流程。

### 获取文档 ID

文档 ID 可以通过以下方式获取：

1. **使用解析工具**（推荐）：使用 `parse_document_id` 工具从文档链接中自动解析
2. **从文档 URL 获取**：对于云文档，URL 中的 token 即为 document_id（27 字符）
3. **从 Wiki URL 获取**：对于 Wiki 文档，推荐使用两步法：
   - 步骤1：使用 `wiki_v2_space_getNode` MCP 工具获取节点信息，提取 `obj_token`（即 document_id）
   - 步骤2：使用 `get_document_blocks` 工具获取文档内容
   - 或者：使用 `parse_document_id` 工具解析 Wiki URL（需要有效的 token）

## 🔧 配置说明

### 环境变量

可以通过环境变量配置以下参数：

- `FEISHU_APP_ID` - 飞书应用 ID（**必需**，由分发方在内部渠道提供）
- `FEISHU_APP_SECRET` - 飞书应用密钥（**必需**，由分发方在内部渠道提供）
- `FEISHU_ACCESS_TOKEN` - 用户访问令牌（可选，会自动获取）
- `FEISHU_REFRESH_TOKEN` - 刷新令牌（首次启动时通过浏览器授权获取）
- `FEISHU_REDIRECT_URI` - 重定向 URI（默认：`http://localhost:8082/callback`）

**配置方式：**
- **推荐**：在 MCP 配置的 `env` 字段中传入 `FEISHU_APP_ID` / `FEISHU_APP_SECRET`
- **备选**：写入 `~/.config/feishu-docx-blocks/.env` 文件
- Token（`FEISHU_ACCESS_TOKEN` / `FEISHU_REFRESH_TOKEN`）由程序自动管理，首次启动会弹出浏览器授权，授权后持久化到 `~/.config/feishu-docx-blocks/.env`
- 每个用户需要单独完成浏览器授权（用户级 token，不能跨人共享）

### Token 管理

#### 自动刷新机制

- **提前刷新**：系统会在 token 剩余有效期少于 5 分钟时自动刷新，避免过期
- **过期检测**：每次调用 API 时自动检测 token 是否过期
- **自动刷新**：如果配置了 `FEISHU_REFRESH_TOKEN`，系统会自动刷新过期的 token
- **失败处理**：如果 refresh_token 也过期，系统会清除无效 token 并提示重新授权

#### Token 有效期

- **user_access_token**：默认有效期 2 小时
- **refresh_token**：如果应用申请了 `offline_access` 权限，refresh_token 长期有效
- **自动刷新**：系统会在 token 剩余时间少于 5 分钟时自动刷新

#### Token 管理工具

- **查看 Token 信息**：使用 `get_current_token` 工具查看当前 token 状态
- **手动重新授权**：使用 `reauthorize` 工具手动触发重新授权流程
- **自动授权**：如果 token 无效且没有 refresh_token，系统会自动启动授权流程

#### Token 存储

- **统一使用 .env 文件**：所有 token 统一存储在 `~/.config/feishu-docx-blocks/.env` 中
  - `FEISHU_ACCESS_TOKEN`：访问令牌
  - `FEISHU_REFRESH_TOKEN`：刷新令牌（用于自动刷新）
  - `FEISHU_APP_ID`：应用 ID（必需，来自 MCP `env` 字段或用户级 `.env`）
  - `FEISHU_APP_SECRET`：应用密钥（必需，来自 MCP `env` 字段或用户级 `.env`）
- **TokenManager**：仅作为内存缓存使用，实际持久化存储统一使用 `.env` 文件
- **不再使用 JSON 文件**：已移除对 `~/.feishu_mcp_tokens.json` 的依赖

## 📊 版本历史

### v3.2.2 (2026-04-16) - 凭证与回调链路修正
**核心升级**：
- 🔐 **移除内置应用凭证**：`FEISHU_APP_ID` / `FEISHU_APP_SECRET` 必须通过 MCP `env` 字段或用户级 `.env` 显式提供
- 🧭 **统一回调端口**：默认 OAuth 回调地址统一为 `http://localhost:8082/callback`
- 🧰 **uvx 启动检查**：启动时 fail-fast 提示缺失凭证，并将 `.env` 读取到的凭证同步给下游模块
- 🛠️ **源码入口对齐**：`run_server.py` 启动前也会校验并传播应用凭证，行为与 `uvx` 入口一致

---

### v3.1 (2026-03-20) - uvx 一键安装 🚀
**核心升级**：
- 🚀 **uvx 一键安装**：无需 clone 仓库，`uvx feishu-docx-blocks@latest` 即可运行
- 🔧 **用户配置目录**：token 存储迁移到 `~/.config/feishu-docx-blocks/.env`，升级包不丢失 token
- 🖼️ **图片路径修复**：`feishu_images/` 保存至调用方工作目录而非包安装目录
- 🐛 **BUG-04 修复**：`get_media_context` section_path 章节路径计算错误（只保留真实父级标题）

---

### v2.2 (2026-01-27) - 智能层级搜索 🔥
**核心升级**：
- 🔥 **不再粗暴返回前后 N 个块**：返回关键词的**标题层级上下文**
- ✅ 返回上一个 H1/H2/H3 标题及其位置和范围
- ✅ 返回建议的读取范围（narrow/medium/wide）
- ✅ AI 可以根据层级决定读取多大范围的内容

**效果提升**：
- 信息精准度：❌ 可能多余或缺少 → ✅ 按层级精准控制
- AI 决策能力：❌ 无法选择范围 → ✅ 可选 narrow/medium/wide
- Token 消耗：❌ 返回大量内容 → ✅ 只返回位置信息

**核心设计**：
```python
# v2.1 前（粗暴方案）：
返回关键词前后 5 个块
问题：可能包含无关内容或缺少完整章节

# v2.2 后（智能层级方案）：
返回：
H1 [  10] 功能需求      → wide 范围 [10-100]
  H2 [  30] 账号安全    → medium 范围 [30-80]
    H3 [  40] 青少年保护 → narrow 范围 [40-60]
      >>> [  45] 关键词匹配位置

AI 可以决定：读取 narrow/medium/wide 哪个范围？
```

---

### v2.1 (2026-01-27) - 智能图片位置关联 🔥
**核心升级**：
- 🔥 **文件路径作为唯一标识**：每张图片都有确定的文件路径，不会混淆
- ✅ 新增 `extract_text_with_media_markers()` - 在文本中插入媒体位置标记
- ✅ 优化 `download_image_blocks` - 返回图片的上下文信息（章节、前后文本）
- ✅ 优化 `get_document_with_media` - 返回媒体位置索引表
- ✅ 容错处理：某张图片下载失败不影响其他图片的关联

**效果提升**：
- 图片关联准确率：序号方案 70% → **文件路径方案 100%**
- 容错能力：❌ 一张失败全部错位 → ✅ 单张失败不影响
- Cursor 使用体验：⚠️ 需要猜测图片对应关系 → ✅ 通过文件路径精准读取

**核心设计**：
```python
# v2.1 前（序号方案）：
文本：这是功能1的图 [图片 #1] 这是功能2的图 [图片 #2]
问题：如果图片1下载失败，图片2会被标记为#1，导致错位

# v2.1 后（文件路径方案）：
文本：这是功能1的图 [📷 图片: feishu_images/doxcn123_abc.png - 功能1]
     这是功能2的图 [📷 图片: feishu_images/doxcn456_def.png - 功能2]
优势：文件路径唯一，即使图片1失败，图片2的路径不变
```

---

### v3.0 (2026-01-26) - 智能模块提取 ⭐
**核心升级**：
- ✅ 新增 `preview_document_tables` - 预览表格表头，智能识别表格类型（300+行）
- ✅ 新增 `extract_document_structure` - 提取文档标题树（462行）
- ✅ 新增 `parse_schedule_table` - 解析排期表格（516行）
- ✅ 新增 `get_document_section_digests` - 按标题拆解文档生成章节摘要（315行）
- ✅ 优化 `generate_module_index` - 支持 chapter_hints 精准定位
- ✅ 智能图片处理规则 - 防止模块错位

**效果提升**：
- 模块划分准确率：70% → **100%**
- 人工干预时间：30分钟 → **0秒（自动化）**
- Token消耗：降低 60-80%

### v2.0 (2026-01-19) - 模块化架构
**核心升级**：
- ✅ 重构为模块化工具架构
- ✅ 新增 `get_document_with_media` - 一键获取完整内容
- ✅ 新增 `search_document_content` - 文档内容搜索
- ✅ 完整的表格处理能力（Markdown转换）

### v1.0 (2026-01-18) - 基础功能
**初始版本**：
- ✅ 基础的文档块获取
- ✅ 图片元数据提取
- ✅ Token自动管理

---

## 📁 项目结构

```
FeishuMCP/
├── feishu_docx_blocks/    # uvx 入口包
│   ├── __init__.py
│   └── server.py          # 入口函数 run()
├── pyproject.toml         # 包构建配置（hatchling）
├── .cursorrules           # 🆕 Cursor 工具选择规则（Project Rules）
├── prompts/               # 🆕 常用 Prompt 模板
│   └── 飞书文档分析.md    #     文档分析任务模板
├── src/                    # 核心代码
│   ├── mcp_server.py      # MCP 服务器主文件（约 380 行，已重构优化）
│   ├── feishu_client.py   # 飞书 API 客户端
│   ├── block_processor.py # Block 内容处理器
│   ├── token_manager.py   # Token 管理器
│   ├── auto_auth.py       # 自动授权模块
│   └── tools/             # 工具包（模块化架构）
│       ├── __init__.py    # 工具注册和导出
│       ├── base.py        # 工具基类
│       ├── document/      # 文档相关工具（14个）⭐ v3.0新增4个
│       │   ├── get_document_with_media.py  # 🆕 一键获取完整内容
│       │   ├── search_document_content.py  # 🆕 文档内容搜索
│       │   ├── get_document_blocks.py
│       │   ├── get_document_section_digests.py  # ⭐ v3.0新增：按标题拆解文档
│       │   ├── get_block_detail.py
│       │   ├── get_block_children.py
│       │   ├── download_image_blocks.py
│       │   ├── download_board_as_image.py
│       │   ├── extract_document_structure.py  # ⭐ v3.0新增：提取标题树
│       │   ├── parse_schedule_table.py        # ⭐ v3.0新增：解析排期表格
│       │   ├── preview_document_tables.py     # ⭐ v3.0新增：预览表格表头
│       │   └── generate_module_index.py       # ⭐ v3.0优化：支持chapter_hints
│       ├── utils/         # 辅助工具（1个）
│       │   └── parse_document_id.py
│       └── auth/          # 授权管理工具（4个）
│           ├── get_current_token.py
│           ├── reauthorize.py
│           ├── check_auth_port.py
│           └── cleanup_auth_port.py
├── docs/                   # 文档目录
│   ├── 权限申请指南.md    #     权限配置说明
│   └── 未来增强建议.md    #     功能增强计划
├── feishu_images/         # 下载的图片存放目录
├── run_server.py          # 服务器启动脚本
├── auto_auth_and_setup.py # 自动授权和配置脚本
├── requirements.txt       # Python 依赖
├── README.md             # 本文档
├── MCPTOOLS.md           # 工具详细文档
├── 架构优化分析.md        # 架构重构分析文档
└── 代码改进说明.md        # 代码改进说明文档
```

### 架构说明

项目采用**模块化工具架构**，具有以下优势：

- ✅ **可维护性**：每个工具独立文件（50-500行），职责清晰
- ✅ **可扩展性**：添加新工具只需创建文件并注册，无需修改核心代码
- ✅ **可读性**：工具按功能分类（document/utils/auth），结构清晰
- ✅ **便于调试**：详细的日志输出，便于追踪问题
- ✅ **测试友好**：可以单独测试每个工具

详细架构说明请参考 [架构优化分析.md](./架构优化分析.md)

### v3.0 架构升级 ⭐

**新增智能模块提取能力**：

```
前端（Cursor）- 智能分析
    ↓ 调用MCP工具
后端（FeishuMCP）- 数据提取
    ├─ parse_schedule_table     → 权威模块定义（100%准确）
    ├─ extract_document_structure → 标题树（兜底保障）
    └─ generate_module_index    → 精准章节定位（chapter_hints）
    ↓ 返回结构化数据
前端（Cursor）- 智能提炼
    ├─ 数据融合（表格+标题树）
    ├─ 标题匹配算法（语义理解）
    ├─ chapter_hints自动生成
    └─ 置信度标注
    ↓
输出：modules-list.json（42个模块，100%准确）
```

**工具数量统计**：
- v2.0: 15个工具
- v3.0: **19个工具**（新增4个核心工具）

**代码行数**（v3.0新增）：
- `preview_document_tables.py`: ~300行
- `extract_document_structure.py`: 462行
- `parse_schedule_table.py`: 516行
- `get_document_section_digests.py`: 315行
- `generate_module_index.py`: 已有（优化支持chapter_hints）
- **总计新增**: ~1593行

## 💡 使用技巧

### Cursor 对话技巧

| 技巧 | 说明 |
|------|------|
| **@ 引用规则文件** | 在对话中使用 `@.cursorrules` 快速提醒 AI 遵循工具选择规则 |
| **@ 引用模板文件** | 使用 `@prompts/飞书文档分析.md` 引用 Prompt 模板 |
| **明确指定工具** | 如 "使用 `get_document_blocks` 获取..." 可避免工具选择歧义 |
| **直接粘贴URL** | AI 会自动识别并解析飞书文档链接 |

### 推荐的对话开场白

```markdown
# 获取文档完整内容
请帮我获取飞书文档 https://xxx.feishu.cn/wiki/XXX 的完整内容，包括所有图片和画板

# 分析技术方案
分析这个技术文档中关于【XXX功能】的实现方案，重点关注流程图和接口定义

# 创建多维表格记录
在多维表格 app_token=XXX 的 table_id=YYY 中新增一条记录：...

# 排查授权问题
检查当前飞书 Token 状态，如果有问题请重新授权
```

### 常见问题快速解决

```
❌ 问题：画板下载失败（权限不足）
✅ 解决：使用 reauthorize 重新授权

❌ 问题：Wiki链接解析失败
✅ 解决：使用 wiki_v2_space_getNode 获取节点信息

❌ 问题：文档内容不完整
✅ 解决：使用 get_document_blocks 并设置 fetch_all=true
```

## 🐛 调试和日志

### 日志输出

所有工具执行都会输出详细的日志到 `stderr`，包括：

- **工具调用日志**：工具名称、参数、执行状态
- **API 调用日志**：API 请求和响应信息
- **错误日志**：异常堆栈和错误详情
- **Token 管理日志**：Token 获取、刷新、过期等信息

**示例日志**：
```
[CALL_TOOL] 调用工具: get_document_blocks, 参数: {...}
[CALL_TOOL] ✅ 工具 'get_document_blocks' 已实例化
[CALL_TOOL] 工具 'get_document_blocks' 需要 token，正在获取...
[TOKEN] ✅ Token已就绪，剩余有效期: 115分钟
[CALL_TOOL] ✅ Token 已获取，FeishuClient 已创建
[get_document_blocks] 获取文档块: document_id=...
[get_document_blocks] ✅ 成功获取 10 个块
[CALL_TOOL] ✅ 工具 'get_document_blocks' 执行成功，返回 1 个内容项
```

### 调试工具

- **`get_current_token`** - 查看当前 token 状态、有效期、来源等信息
- **`check_auth_port`** - 检查授权回调端口占用情况
- **`reauthorize`** - 手动触发重新授权流程

### 错误排查

如果工具执行失败，错误响应会包含：
- 错误类型和详细消息
- 工具名称和传入参数
- 异常堆栈（如果适用）
- API 错误码和响应（如果是 API 调用失败）

详细调试方法请参考 [代码改进说明.md](./代码改进说明.md)

## 🔍 常见问题

### Q: v3.0 相比之前版本有什么优势？

A: 
v3.0新增了**智能模块提取能力**，核心优势：
- ✅ **100%准确**：基于排期表格的权威模块定义
- ✅ **零干预**：6秒自动完成42个模块提取，无需人工整理
- ✅ **兜底保障**：无排期表格时使用标题树自动推断
- ✅ **精准定位**：chapter_hints替代关键词搜索，token降低60-80%
- ✅ **图片智能处理**：防止模块错位

**推荐场景**：大型复杂需求的测试用例生成

**使用方法**：查看 [快速开始指南-v3.0.md](../快速开始指南-v3.0.md)

---

### Q: 如何使用v3.0的智能模块提取？

A:
**最简单方式**（自动执行）：
```
告诉AI：请生成XXX的测试用例
- 排期: https://...
- 需求: https://...
- 技术: https://...
```

AI会自动：
1. 调用 `parse_schedule_table` + `extract_document_structure`
2. 智能提炼模块列表
3. 生成 `modules-list.json`
4. 展示给你确认
5. 逐模块生成用例

**详细文档**：
- 工具文档: [MCPTOOLS.md](./MCPTOOLS.md#文档结构分析工具)
- 规则文档: `../.cursor/rules/case-module-extraction.mdc`
- 技术细节: `../optimize-scheme/v3.0实施总结报告.md`

---

### Q: 没有排期文档怎么办？

A:
完全没问题！v3.0支持兜底策略：
```python
# AI会自动使用标题树提取
extract_document_structure(document_id="需求文档ID")
# → 基于H1/H2/H3层级推断模块
# → 置信度标记为"medium"，建议人工review
```

**提示**：AI会提示"基于标题划分，请确认"

---

### Q: 应用凭证怎么获取？

A:
- 本包不再内置默认应用凭证。团队成员请向**分发方**索取 `FEISHU_APP_ID` / `FEISHU_APP_SECRET`
- 凭证放在 MCP 配置的 `env` 字段里（见上文"快速开始"的 JSON 示例）
- 每个人还需要用自己的飞书账号完成浏览器授权，获取各自的 `user_access_token` 和 `refresh_token`
- 每个人的权限是独立的，只能访问自己有权限的文档
- 如果要自建飞书应用，登录 [飞书开发者后台](https://open.feishu.cn/app) 创建应用，将 `app_id` 和 `app_secret` 填入 MCP 配置

### Q: Token 过期怎么办？

A: 
- **自动刷新**：如果配置了 `FEISHU_REFRESH_TOKEN`，系统会在 token 剩余时间少于 5 分钟时自动刷新
- **查看状态**：使用 `get_current_token` 工具查看当前 token 状态和剩余有效期
- **手动重新授权**：使用 `reauthorize` 工具手动触发重新授权流程
- **脚本重新授权**：也可以运行 `python auto_auth_and_setup.py` 重新授权

### Q: 如何查看当前使用的 token 信息？

A: 在 Cursor 中使用 `get_current_token` 工具，可以查看：
- Token 来源（环境变量或缓存）
- Token 有效性状态
- 过期时间和剩余有效期
- 是否配置了 refresh_token

### Q: Token 失效后没有提示怎么办？

A: 
- 系统会在 token 过期时自动检测并尝试刷新
- 如果刷新失败，会在错误信息中提示需要重新授权
- 可以使用 `get_current_token` 工具主动检查 token 状态
- 如果发现 token 已过期，使用 `reauthorize` 工具重新授权

### Q: 授权时提示 redirect_uri 错误？

A: 
- **团队分发应用**：确认分发方提供的应用已在飞书开发者后台配置重定向 URL：`http://localhost:8082/callback`
- **自建应用**：在飞书开发者后台的 **安全设置** → **重定向 URL** 中添加 `http://localhost:8082/callback`

### Q: 如何获取文档的 document_id？

A: 
- **推荐方式**：使用 `parse_document_id` 工具从文档链接中自动解析
- **手动方式**：从文档 URL 中提取 token（27 字符）
- **Wiki 文档**：使用 `parse_document_id` 工具会自动调用 API 获取，或使用 `wiki_v2_space_getNode` 工具获取 `obj_token`（即 document_id）

### Q: 图片无法显示？

A: 确保：
1. 授权时包含了 `docx:document:readonly` 权限
2. `include_images` 参数设置为 `true`
3. Token 有效且有访问文档的权限

### Q: 工具调用没有输出怎么办？

A: 
- **查看日志**：所有工具执行都会输出详细日志到 `stderr`，查看日志可以了解执行过程
- **检查参数**：确保传入的参数符合要求，特别是必需参数
- **检查 Token**：使用 `get_current_token` 工具检查 token 状态
- **查看错误信息**：工具执行失败时会返回详细的错误信息，包括错误类型、消息和参数
- **参考文档**：查看 [代码改进说明.md](./代码改进说明.md) 了解调试方法

### Q: 如何调试工具执行问题？

A: 
1. **查看执行日志**：工具执行时会输出详细日志，包括：
   - 工具名称和参数
   - 执行状态（开始、成功、失败）
   - API 调用结果
   - 错误信息和堆栈
2. **使用调试工具**：
   - `get_current_token` - 检查 token 状态
   - `check_auth_port` - 检查授权端口
3. **查看错误响应**：工具返回的错误信息包含：
   - 错误类型和消息
   - 工具名称和参数
   - 异常堆栈（如果适用）

## 🎉 v3.0 新增能力 ⭐

### 核心升级

v3.0版本新增了**4个核心工具**，包括：
- **3个通用工具**：适用于任何文档分析场景（`preview_document_tables`、`extract_document_structure`、`get_document_section_digests`）
- **1个专用工具**：专门用于"测试用例生成"这一特定需求（`parse_schedule_table`）

### 新增工具（4个）

| 工具 | 功能 | 代码行数 | 测试状态 |
|------|------|---------|---------|
| `preview_document_tables` | 预览表格表头 | 300+行 | ✅ 已验证 |
| `extract_document_structure` | 提取文档标题树 | 462行 | ✅ 已验证 |
| `parse_schedule_table` | 解析排期表格 | 516行 | ✅ 已验证 |
| `get_document_section_digests` | 按标题拆解文档生成摘要 | 315行 | ✅ 已验证 |

### 核心特性

#### 1. 权威模块定义 ⭐⭐⭐
```python
parse_schedule_table(document_id="排期文档ID")
# → 从表格自动提取42个模块
# → 100%准确的模块定义
# → 包含：优先级、测试点、功能描述、工时等
# → 自动处理合并单元格
```

#### 2. 完整兜底策略 ⭐⭐⭐
```python
extract_document_structure(document_id="需求文档ID")
# → 提取910个标题（H1/H2/H3/H4）
# → 树状结构 + 扁平列表
# → 无排期表格时作为模块划分依据
# → 与表格交叉验证
```

#### 3. 精准章节定位 ⭐⭐⭐
```python
generate_module_index(
    module_id="M25",
    chapter_hints=["2.3 发现Tab", "专栏模块"]  # ⭐ 精准定位
)
# → 替代关键词搜索
# → 100%准确定位
# → 节省60-80% token
```

### 工作流程

```
用户提供文档链接
  ↓
并行调用MCP工具
  ├─ parse_schedule_table（排期文档）
  └─ extract_document_structure（需求文档）
  ↓ 返回结构化数据
Cursor智能提炼
  ├─ 数据融合（表格+标题树）
  ├─ 智能标题匹配
  ├─ chapter_hints自动生成
  └─ 置信度标注
  ↓
modules-list.json（42个模块）
  ↓
逐模块生成索引（chapter_hints精准定位）
  ↓
生成测试用例
```

### 效果对比

| 维度 | v2.0（旧方案） | v3.0（新方案） |
|------|---------------|---------------|
| 模块来源 | AI推理 | **表格+标题树** |
| 准确率 | ~70% | **100%** ⭐ |
| 兜底策略 | ❌ 无 | ✅ 标题树兜底 ⭐ |
| chapter_hints | 手动编写 | **自动生成** ⭐ |
| Token消耗 | 高 | 降低60-80% ⭐ |
| 人工干预 | 需30分钟 | **零干预（6秒）** ⭐ |
| 置信度标注 | ❌ 无 | ✅ high/medium/low |

### 技术突破

#### 1. Cell内容提取方案 ⭐
**问题**：调用 `get_block_detail(cell_id)` 失败（400错误）

**发现**：Cell block（type=32）本身没有文本，Cell的children才是真正的文本blocks

**解决方案**：从 `all_blocks` 中查找cell的children，避免额外API调用

#### 2. 合并单元格处理 ⭐
**问题**：排期表格的"所属系统"列使用合并单元格

**解决方案**：检测空单元格，自动继承上一行的值

#### 3. 智能标题匹配算法 ⭐
**问题**：如何从910个标题中找到与模块相关的章节？

**解决方案**：
```python
1. 从表格字段提取关键词（page、function_module）
2. 在标题中查找包含这些关键词的标题
3. 计算匹配分数（精确匹配10分，部分匹配3分）
4. 返回最佳匹配（100%成功率）
```

### 使用指南

详细使用方法请参考：
- **工具文档**: [MCPTOOLS.md](./MCPTOOLS.md#文档结构分析工具)
- **规则文档**: `../.cursor/rules/case-module-extraction.mdc`
- **快速开始**: `../快速开始指南-v3.0.md`
- **技术细节**: `../optimize-scheme/v3.0实施总结报告.md`

---

## 📝 许可证

本项目基于 MIT 许可证开源。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

**版本**: v3.0 (v2.2)  
**更新日期**: 2026-01-27  
**核心升级**: 智能模块提取 + 图片位置关联 + 智能层级搜索 ⭐
