当前位置：首页 > news >正文

告别浏览器复制：我把腾讯在线文档读取封装成了一个Skill

news 2026/7/12 6:29:50

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

安装器完成三件事：

把用户级 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 读取为空	页签或直接接口异常	校验页签，并启用自动回退
导出超时	腾讯导出任务未完成	重试并保留超时上限