---
name: tx-doc-large-reader
description: 读取超大腾讯文档（传统 doc 类型）的完整流程与避坑指南。当 get_content 超时或文档超过 10 万字时，使用 doc.resolve_document_structure 替代方案提取全文。
---

# 超大腾讯文档读取流程

## 问题背景

腾讯文档 MCP 提供 `get_content` 作为通用读取接口，但对于**超大文档**（实践验证：85 万字/2.8 万段落）存在两个问题：

1. **`get_content` 后端 TCP 超时**（5 秒固定超时），返回 `code:101, tcp client transport ReadFrame, i/o timeout`
2. **文档类型不同，读取工具不同**：
   - smartcanvas 类型 → `smartcanvas.read`（支持分页）
   - 传统 tencentdoc 类型 → `doc.resolve_document_structure`（返回全文结构）

## 快速判断

当 `get_content` 超时时，先确定文档类型：

```bash
# 用 smartcanvas.read 测试文档类型（即使文档是 tencentdoc 也不会报网络错误）
mcporter call tencent-docs smartcanvas.read file_id=<FILE_ID> size=10

# 错误返回示例（说明是 tencentdoc 类型）：
# type:business, code:400008, msg:file is tencentdoc, not smartcanvas

# 正确返回示例（说明是 smartcanvas 类型）：
# 正常返回 JSON 内容
```

## tencentdoc 类型读取流程

### 第一步：获取文档结构

```bash
mcporter call tencent-docs doc.resolve_document_structure file_id=<FILE_ID>
```

- 返回完整的 JSON 结构，包含 `nodes` 数组
- 每个 node 包含：`text_preview`（文本预览）、`heading_level`（标题层级）、`start_index`/`end_index`、`type`（段落类型）
- 文档越大返回数据越大（85 万字 → 8MB JSON）

### 第二步：提取文本内容

用 Python 从 JSON 中抽取所有 `text_preview`：

```bash
python -X utf8 -c "
import json

# 读取上一步保存的 JSON
with open('doc_structure.json', 'r', encoding='utf-8') as f:
    data = json.load(f)

nodes = data.get('nodes', [])
texts = []
for n in nodes:
    preview = n.get('text_preview', '')
    hl = n.get('heading_level', 0)
    if preview:
        if hl > 0:
            texts.append('#' * hl + ' ' + preview)
        else:
            texts.append(preview)

full_text = '\n'.join(texts)
with open('doc_content.txt', 'w', encoding='utf-8') as f:
    f.write(full_text)

print(f'Total paragraphs: {len(texts)}')
print(f'Total characters: {len(full_text)}')
"
```

### 第三步：查看内容

```bash
# 看开头部分
head -200 doc_content.txt

# 或者用 Read 工具
```

## smartcanvas 类型读取流程

smartcanvas 类型支持分页读取，适合超大文档：

```bash
# 首次读取（指定每页条数）
mcporter call tencent-docs smartcanvas.read file_id=<FILE_ID> size=50

# 获取下一页（用上一页返回的 next_token）
mcporter call tencent-docs smartcanvas.read file_id=<FILE_ID> next_token=<NEXT_TOKEN> size=50
```

参数说明：
- `size`：每页返回的 block 数量（建议 20-50）
- `next_token`：分页游标，首次调用不传，后续从上次结果获取
- `page_id`：可选，指定页面 ID

## 注意事项

### 1. 编码问题

Windows 环境下 Python 默认编码为 GBK，写入包含 emoji 的文件会报错：
```
UnicodeEncodeError: 'gbk' codec can't encode character
```

**解决**：使用 `python -X utf8` 参数或显式指定 `encoding='utf-8'`

### 2. 工具选择依据

| 文档类型 | 读取工具 | 特点 |
|---------|---------|------|
| tencentdoc | `doc.resolve_document_structure` | 一次性返回全部结构，数据量大 |
| smartcanvas | `smartcanvas.read` | 支持分页，推荐 |
| 任意类型 | `get_content` | 通用接口，大文档可能超时 |

### 3. 文档类型判断方法

- `get_content` 不区分类型，但大文档可能超时
- `smartcanvas.read` 对 tencentdoc 返回明确的业务错误码 `400008`
- `doc.*` 工具对 smartcanvas 也会返回类型错误

### 4. 链接文本处理

`text_preview` 中的链接会显示为以下格式：
```
[普通链接: https://xxx]
[腾讯文档链接: https://docs.qq.com/...]
HYPERLINK "url"
```
无需额外处理，直接保留原样即可。

### 5. 资源消耗

- 85 万字文档 → 8MB JSON 响应 → 提取后约 850KB 纯文本
- 建议提取后及时清理中间 JSON 文件
- `doc.resolve_document_structure` 对超大文档可能耗时较长（实测 3-5 秒），但能正常返回不超时

### 6. 保存到本地

提取的内容建议立即写入文件，避免因 MCP 连接不稳定导致数据丢失。

## 完整示例（tencentdoc）

```bash
# 1. 获取文档结构并保存
mcporter call tencent-docs doc.resolve_document_structure file_id=DR2xUcFdrSVhJTkZu > doc_structure.json

# 2. 提取文本
python -X utf8 -c "
import json
with open('doc_structure.json', 'r', encoding='utf-8') as f:
    data = json.load(f)
texts = []
for n in data.get('nodes', []):
    p = n.get('text_preview', '')
    hl = n.get('heading_level', 0)
    if p:
        texts.append(('#' * hl + ' ' + p) if hl > 0 else p)
with open('doc_content.txt', 'w', encoding='utf-8') as f:
    f.write('\n'.join(texts))
print(f'Done: {len(texts)} paragraphs')
"

# 3. 清理中间文件（可选）
rm doc_structure.json
```