告别浏览器复制：我把腾讯在线文档读取封装成了一个Skill
告别浏览器复制：我把腾讯在线文档读取封装成了一个 Skill
摘要
腾讯在线表格通常还能按单元格读取，但普通在线文档常被编辑器画布、登录态和虚拟渲染挡住。本文介绍一个可公开安装的 Codex 用户级 Skill：优先调用腾讯文档原生 MCP，分别读取完整正文、结构信息和 DOCX 资产，再统一解析为 Markdown、JSON、图片和表格。文章给出安装命令、核心实现、失败分支与安全边界，适合需要让 AI 稳定分析在线文档的开发者和自动化工程师。
问题不在“能否打开”，而在“能否稳定读取”
很多 AI 自动化流程处理腾讯文档时，第一反应是打开浏览器、模拟点击、复制全文。对于短文档，这种方法偶尔可用；一旦文档包含多页正文、标题层级、表格、图片和超链接，问题就会集中出现：
- 编辑器正文可能由 Canvas 或虚拟列表渲染，DOM 中没有完整文本；
Ctrl+A / Ctrl+C受编辑区焦点和无障碍模式影响；- 浏览器只能拿到可见区域，滚动加载后内容顺序可能变化；
- 表格复制后变成连续文本，行列关系丢失；
- 图片只能看到占位，隐藏超链接也容易消失；
- 登录态、窗口状态和浏览器扩展会影响复现。
所以真正要解决的问题不是“让 AI 看见网页”，而是建立一条可以校验、可以复用、可以在不同项目中调用的数据链路。
这也是tencent-docs-reader的目标读者：使用 Codex 的开发者、测试与运维自动化工程师，以及需要批量分析腾讯在线文档的团队。
整体方案：同一份文档走三条读取路径
普通 DOC 的完整解析不能依赖一个接口完成。公开版采用三条职责明确的路径：
腾讯文档 URL │ ├─ get_content │ └─ 完整纯文本：总结、检索、问答 │ ├─ doc.resolve_document_structure │ └─ 标题、段落位置、表格行列、编辑索引 │ └─ manage.export_file → DOCX └─ Markdown、JSON、图片、表格、超链接三条路径不能互相替代。
get_content返回的是完整正文，但不负责精确样式和表格结构；resolve_document_structure能返回标题层级和位置索引，但长段落预览存在长度上限；DOCX 导出最适合恢复图片、表格及 Word 的HYPERLINK字段，但成本比纯文本读取更高。
因此，Skill 会根据任务选择最轻的路径：只做摘要时读取全文，需要分章节分析时增加结构接口，需要生成本地资料包时再导出 DOCX。
为什么结构预览不能冒充全文
这是实现过程中最容易踩的坑。
结构接口返回的节点大致如下：
{"type":"Heading","heading_level":2,"start_index":79,"end_index":100,"text_preview":"（一）示例章节"}它非常适合回答下面这些问题：
- 文档有哪些标题？
- 某个章节从哪里开始？
- 第几张表有多少行、多少列？
- 修改前应该使用哪个位置索引？
但text_preview是“预览”，不是全文。即使选择 full 模式，单个长段落仍可能被限制在固定长度内。如果直接把所有预览拼接起来做总结，模型得到的其实是一份被静默截断的文档。
公开版明确规定：
- 完整文字以
get_content为准； - 结构与位置以
resolve_document_structure为准； - 表格、图片和链接以导出的 DOCX 为准。
这是一条确定性规则，不交给模型临场猜测。
从 DOCX 恢复表格、图片与隐藏链接
DOCX 本质上是一个 OOXML 压缩包。导出当前在线版本后，解析器按正文中的真实顺序遍历段落和表格，并生成统一 Block：
{"type":"paragraph","text":"示例正文","style":"Heading 2","heading_level":2,"links":[],"images":[]}表格则保存为二维数组：
{"type":"table","number":1,"rows":[["指标","当前值","状态"],["接口成功率","99.9%","正常"]]}图片按关系 ID 找到二进制资源，计算哈希去重后写入assets/。Markdown 中保留相对路径：
超链接要额外处理。腾讯文档导出的 Word 中，一部分链接是标准<w:hyperlink>，另一部分是字段代码：
HYPERLINK https://example.com/document如果只读取paragraph.text，通常只能得到显示文字，真实 URL 会丢失。解析器会同时扫描标准关系和w:instrText，再把链接写入 JSON，并尽量恢复为 Markdown：
[查看示例文档](https://example.com/document)安装公开版
下载并解压tencent-docs-reader-public-v1.0.0.zip，在 macOS 或 Linux 下执行：
chmod+x install.sh uninstall.sh bin/* ./install.sh安装器完成三件事：
- 把用户级 Skill 安装到
~/.codex/skills/tencent-docs-reader； - 把本地 helper 安装到
~/.local/share/tencent-docs-reader； - 创建独立 Python 虚拟环境，安装
python-docx和openpyxl。
安装过程不会要求输入 Token，也不会修改 shell 配置。
配置自己的授权
公开包不包含任何账号、Cookie 或 Token。使用者需要在本机设置自己的腾讯文档 MCP Token：
exportTENCENT_DOCS_MCP_TOKEN="<your-own-token>"Token 的获取入口取决于使用者所在的腾讯文档 MCP/OpenAPI 接入环境，因此项目不虚构统一申请页面，也不把 Token 写进命令示例。
在线自检：
~/.local/share/tencent-docs-reader/bin/tencent-docs-self-check--online自检只报告 Token 是否存在和 MCP 是否连通，不打印 Token 内容。
读取普通腾讯文档
只需要完整正文：
~/.local/share/tencent-docs-reader/bin/tencent-doc content\--url"https://docs.qq.com/doc/EXAMPLE_FILE_ID"需要 Markdown、JSON、DOCX 和图片资产：
~/.local/share/tencent-docs-reader/bin/tencent-doc parse\--url"https://docs.qq.com/doc/EXAMPLE_FILE_ID"\--output-dir ./output/example-doc\--keep-docx输出目录如下：
output/example-doc/ ├── document.md ├── document.json ├── EXAMPLE_FILE_ID.docx └── assets/ └── image_001.png在 Codex 中也可以直接使用：
使用 $tencent-docs-reader 读取这个腾讯文档， 提取标题、表格、图片和超链接： https://docs.qq.com/doc/EXAMPLE_FILE_ID在线表格仍然走单元格接口
普通 DOC 和在线 Sheet 不应共用一套解析方法。对于docs.qq.com/sheet/...，Skill 会先查询页签，再读取指定范围：
~/.local/share/tencent-docs-reader/bin/tencent-sheet info\--url"https://docs.qq.com/sheet/EXAMPLE_FILE_ID"~/.local/share/tencent-docs-reader/bin/tencent-sheetread\--url"https://docs.qq.com/sheet/EXAMPLE_FILE_ID"\--sheet-name"Sheet1"\--formatjson当直接单元格接口返回空数据或特定错误时，脚本会切换到备用读取路径，而不是让调用方重新实现一套浏览器自动化。
失败分支要提前设计
一条可公开复用的 Skill，不能只写成功路径。
| 现象 | 判断 | 处理 |
|---|---|---|
| 提示缺少 MCP Token | 当前 shell 未授权 | 设置自己的环境变量后自检 |
| 返回无权限 | 账号没有文档访问权限 | 由文档所有者授权，不绕过权限 |
| 结构段落被截断 | 使用了结构预览 | 改用content获取完整正文 |
| Markdown 没有图片 | 未走 DOCX 解析 | 使用parse而不是content |
| Sheet 读取为空 | 页签或直接接口异常 | 校验页签，并启用自动回退 |
| 导出超时 | 腾讯导出任务未完成 | 重试并保留超时上限 |
AI 可以根据任务选择读取路径、总结内容、识别章节；但权限判断、超时、文件大小、表格数量和资产存在性应由程序确定。不要让模型用“看起来成功”代替验证。
为什么公开版默认只读
底层 MCP 可能提供单元格写入、插入段落、修改样式等操作，但公开版没有直接暴露这些命令。原因很简单：写操作需要明确的目标文件、页签、范围、前置快照和回滚策略。
读取失败最多得到空结果；写错位置可能破坏团队文档。一个面向公众的初始版本，合理边界应该是：
- 读取和导出默认开放；
- 写入必须单独设计确认机制；
- 不把浏览器登录态当成隐式授权；
- 不在日志和文章中暴露临时签名 URL。
发布前检查清单
如果你也准备把内部 Skill 做成公开工具，可以复用这份清单：
- 删除个人绝对路径和默认账号 ID；
- 不打包
.env、Cookie、Token Store 和真实文档； - 使用环境变量或系统密钥管理工具注入凭据；
- 在全新的 HOME 目录完成安装测试；
- 同时验证成功路径、无 Token 和无权限路径；
- 对生成 ZIP 解压后再次扫描敏感信息；
- 明确第三方商标、非官方声明和开源许可证；
- 默认只读，写入能力另行设计确认与回滚。
结语
浏览器自动化并不是错误方案，但它更适合处理“必须在页面上完成”的交互。对于读取和分析在线文档，原生接口加本地解析通常更稳定，也更容易验证。
tencent-docs-reader最重要的不是多封装了几个命令，而是把完整文字、结构位置和高保真资产分成三条可验证链路。只要边界清楚，AI 才能从“偶尔复制成功”走向可复用的文档分析能力。
下载文件：https://download.csdn.net/download/distantsky/93107009。