告别浏览器复制：我把腾讯在线文档读取封装成了一个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 中保留相对路径：

![image_001.png](assets/image_001.png)

超链接要额外处理。腾讯文档导出的 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

安装器完成三件事：

  1. 把用户级 Skill 安装到~/.codex/skills/tencent-docs-reader；
  2. 把本地 helper 安装到~/.local/share/tencent-docs-reader；
  3. 创建独立 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。