告别浏览器复制我把腾讯在线文档读取封装成了一个 Skill摘要腾讯在线表格通常还能按单元格读取但普通在线文档常被编辑器画布、登录态和虚拟渲染挡住。本文介绍一个可公开安装的 Codex 用户级 Skill优先调用腾讯文档原生 MCP分别读取完整正文、结构信息和 DOCX 资产再统一解析为 Markdown、JSON、图片和表格。文章给出安装命令、核心实现、失败分支与安全边界适合需要让 AI 稳定分析在线文档的开发者和自动化工程师。问题不在“能否打开”而在“能否稳定读取”很多 AI 自动化流程处理腾讯文档时第一反应是打开浏览器、模拟点击、复制全文。对于短文档这种方法偶尔可用一旦文档包含多页正文、标题层级、表格、图片和超链接问题就会集中出现编辑器正文可能由 Canvas 或虚拟列表渲染DOM 中没有完整文本CtrlA / CtrlC受编辑区焦点和无障碍模式影响浏览器只能拿到可见区域滚动加载后内容顺序可能变化表格复制后变成连续文本行列关系丢失图片只能看到占位隐藏超链接也容易消失登录态、窗口状态和浏览器扩展会影响复现。所以真正要解决的问题不是“让 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 下执行chmodx 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 TokenexportTENCENT_DOCS_MCP_TOKENyour-own-tokenToken 的获取入口取决于使用者所在的腾讯文档 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\--urlhttps://docs.qq.com/doc/EXAMPLE_FILE_ID需要 Markdown、JSON、DOCX 和图片资产~/.local/share/tencent-docs-reader/bin/tencent-doc parse\--urlhttps://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\--urlhttps://docs.qq.com/sheet/EXAMPLE_FILE_ID~/.local/share/tencent-docs-reader/bin/tencent-sheetread\--urlhttps://docs.qq.com/sheet/EXAMPLE_FILE_ID\--sheet-nameSheet1\--formatjson当直接单元格接口返回空数据或特定错误时脚本会切换到备用读取路径而不是让调用方重新实现一套浏览器自动化。失败分支要提前设计一条可公开复用的 Skill不能只写成功路径。现象判断处理提示缺少 MCP Token当前 shell 未授权设置自己的环境变量后自检返回无权限账号没有文档访问权限由文档所有者授权不绕过权限结构段落被截断使用了结构预览改用content获取完整正文Markdown 没有图片未走 DOCX 解析使用parse而不是contentSheet 读取为空页签或直接接口异常校验页签并启用自动回退导出超时腾讯导出任务未完成重试并保留超时上限AI 可以根据任务选择读取路径、总结内容、识别章节但权限判断、超时、文件大小、表格数量和资产存在性应由程序确定。不要让模型用“看起来成功”代替验证。为什么公开版默认只读底层 MCP 可能提供单元格写入、插入段落、修改样式等操作但公开版没有直接暴露这些命令。原因很简单写操作需要明确的目标文件、页签、范围、前置快照和回滚策略。读取失败最多得到空结果写错位置可能破坏团队文档。一个面向公众的初始版本合理边界应该是读取和导出默认开放写入必须单独设计确认机制不把浏览器登录态当成隐式授权不在日志和文章中暴露临时签名 URL。发布前检查清单如果你也准备把内部 Skill 做成公开工具可以复用这份清单删除个人绝对路径和默认账号 ID不打包.env、Cookie、Token Store 和真实文档使用环境变量或系统密钥管理工具注入凭据在全新的 HOME 目录完成安装测试同时验证成功路径、无 Token 和无权限路径对生成 ZIP 解压后再次扫描敏感信息明确第三方商标、非官方声明和开源许可证默认只读写入能力另行设计确认与回滚。结语浏览器自动化并不是错误方案但它更适合处理“必须在页面上完成”的交互。对于读取和分析在线文档原生接口加本地解析通常更稳定也更容易验证。tencent-docs-reader最重要的不是多封装了几个命令而是把完整文字、结构位置和高保真资产分成三条可验证链路。只要边界清楚AI 才能从“偶尔复制成功”走向可复用的文档分析能力。下载文件https://download.csdn.net/download/distantsky/93107009。