1. 为什么浏览器复制腾讯在线文档总是不靠谱腾讯在线文档读取这件事表面上看是「打开网页、全选、复制」三步但只要你把它放进自动化流程里很快就会崩。我最早的做法就是用无头浏览器打开docs.qq.com/doc/...等页面加载完模拟 CtrlA、CtrlC再把剪贴板内容塞给模型。短文档偶尔能跑通一旦文档超过两三屏问题就集中爆发。核心矛盾在于腾讯文档的正文并不是老老实实躺在 DOM 里的静态文本。编辑器大量使用 Canvas 或虚拟列表渲染你document.body.innerText拿到的可能只有当前视口那几百字。滚动加载之后段落顺序还可能因为懒加载而错位。表格更麻烦复制出来是一坨连续文本行列关系直接丢失图片只剩一个占位符隐藏超链接也一起消失。再加上登录态、窗口焦点、浏览器扩展的干扰同一份文档今天能读、明天就失败根本没法做稳定校验。所以真正要解决的不是「让 AI 看见网页」而是建立一条可校验、可复用、可跨项目调用的数据链路。这也是我把腾讯在线文档读取封装成 Codex Skill 的出发点一次配置之后在 Codex 里用统一入口拉取文档内容彻底告别浏览器复制。这篇会给出 Skill 的目录结构、config.toml与settings.json可复制骨架并用一份真实在线文档做 Markdown 导出验证最后接上 TaoToken 统一 Key/API 通道让模型调用和文档读取走同一条链路。适合谁看用 Codex 做自动化的开发者、需要批量分析腾讯在线文档的测试与运维同学以及任何被「复制粘贴」折磨过的文档处理场景。2. 前置准备TaoToken 统一 Key 与 Codex 环境在写 Skill 之前先把调用通道理顺。我试过把文档读取和模型调用分成两套凭证管理结果就是环境变量满天飞、换台机器就崩。TaoToken 的价值在于把模型对话、Coding Plan、API Key 收敛到一个控制台里Codex 侧只需要认一个 base_url 和一个 key。你需要先拿到自己的 API Key。入口在控制台的 API Keys 页面创建后复制保存注意它只显示一次https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapikeys拿到 key 之后Codex 的接入地址统一用https://taotoken.net/api注意这个 API 地址后面不加任何 UTM 参数保持干净。模型对话能力可以在模型对话页先验证一下通道是否通https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodels如果你打算长期跑编码和 Agent 任务Coding Plan 会更划算额度模型和按量计费不一样适合高频调用https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcodingplan环境变量建议这样设置把模型通道和文档读取的凭证分开命名避免混淆# TaoToken 模型通道 export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api # 腾讯文档 MCP Token你自己的授权不要提交到仓库 export TENCENT_DOCS_MCP_TOKEN你的腾讯文档token注意TENCENT_DOCS_MCP_TOKEN必须是你本机自己的授权凭证公开包里不会带任何账号、Cookie 或 Token。不要把这两个变量写进.env后一起打包发布。3. Skill 目录结构与可复制配置骨架Codex 的用户级 Skill 放在~/.codex/skills/下每个 Skill 一个目录。我把它命名为tencent-docs-reader结构如下~/.codex/skills/tencent-docs-reader/ ├── SKILL.md # Skill 描述与触发说明 ├── config.toml # Skill 级配置 ├── settings.json # 运行时参数 ├── bin/ │ ├── tencent-doc # 文档读取入口 │ ├── tencent-sheet # 在线表格读取入口 │ └── tencent-docs-self-check └── lib/ └── parser.py # DOCX 解析与 Markdown 生成SKILL.md是 Codex 识别这个 Skill 的关键写清楚它能做什么、什么时候触发--- name: tencent-docs-reader description: 读取腾讯在线文档与在线表格输出 Markdown、JSON、图片和表格。当用户提供 docs.qq.com 链接并需要提取正文、标题层级、表格或超链接时使用。 --- # tencent-docs-reader 优先调用腾讯文档原生 MCP 接口按任务选择最轻的读取路径 - 只要完整正文get_content - 需要标题层级与位置索引doc.resolve_document_structure - 需要图片、表格、超链接manage.export_file 导出 DOCX 后本地解析config.toml放 Skill 级默认值比如输出目录、超时上限、是否保留 DOCX[reader] output_dir ./output keep_docx false timeout_seconds 60 [reader.paths] content get_content structure doc.resolve_document_structure export manage.export_file [reader.limits] max_file_mb 50 max_tables 200settings.json放运行时可变参数比如默认页签、是否启用表格回退{ sheet: { default_sheet_name: Sheet1, enable_fallback: true }, markdown: { image_dir: assets, keep_relative_path: true }, safety: { read_only: true, log_token: false } }这里read_only默认true是刻意的。底层 MCP 可能提供写入单元格、插入段落的能力但写操作需要明确的目标文件、页签、范围、前置快照和回滚策略。读取失败最多得到空结果写错位置可能破坏团队文档所以公开版默认只读。4. 三条读取路径正文、结构、DOCX 资产普通 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 本质是 OOXML 压缩包。解析器按正文真实顺序遍历段落和表格生成统一 Block{ type: paragraph, text: 示例正文, style: Heading 2, heading_level: 2, links: [], images: [] }表格保存为二维数组{ type: table, number: 1, rows: [ [指标, 当前值, 状态], [接口成功率, 99.9%, 正常] ] }超链接要额外处理。腾讯文档导出的 Word 里一部分链接是标准w:hyperlink另一部分是字段代码HYPERLINK https://example.com/document。如果只读paragraph.text真实 URL 会丢失。解析器要同时扫描标准关系和w:instrText再把链接写进 JSON 并恢复为 Markdown。5. 验证请求把一份在线文档导出为 Markdown配置好之后用一份真实文档跑通全流程。先做在线自检确认 Token 存在且 MCP 连通~/.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 里可以直接用自然语言触发 Skill使用 $tencent-docs-reader 读取这个腾讯文档 提取标题、表格、图片和超链接 https://docs.qq.com/doc/EXAMPLE_FILE_ID在线表格走另一套接口先查页签再读范围~/.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-sheet read \ --url https://docs.qq.com/sheet/EXAMPLE_FILE_ID \ --sheet-name Sheet1 \ --format json当直接单元格接口返回空数据或特定错误时脚本会切到备用读取路径而不是让调用方重新实现浏览器自动化。验证成功的标志是document.md里标题层级正确、表格是 Markdown 表格、图片以相对路径引用、超链接可点击。如果这四项都对说明链路通了。6. 常见报错排查与安全边界一条可复用的 Skill 不能只写成功路径。下面是我实际遇到过的失败分支和对应处理现象判断处理缺少 MCP Token当前 shell 未授权设置自己的环境变量后重新自检自检返回无权限账号没有文档访问权限由文档所有者授权不绕过权限结构段落被截断使用了结构预览改用 content 获取完整正文Markdown 没有图片未走 DOCX 解析使用 parse 而不是 contentSheet 读取为空页签或直接接口异常校验页签并启用自动回退导出超时腾讯导出任务未完成重试并保留超时上限AI 可以根据任务选择读取路径、总结内容、识别章节但权限判断、超时、文件大小、表格数量和资产存在性应由程序确定。不要让模型用「看起来成功」代替验证。安全边界上公开版默认只读。读取和导出默认开放写入必须单独设计确认机制不把浏览器登录态当成隐式授权不在日志和文章里暴露临时签名 URL。如果你也准备把内部 Skill 做成公开工具发布前检查清单可以复用删除个人绝对路径和默认账号 ID不打包.env、Cookie、Token Store 和真实文档用环境变量或系统密钥管理工具注入凭据在全新的 HOME 目录完成安装测试同时验证成功路径、无 Token 和无权限路径对生成 ZIP 解压后再次扫描敏感信息明确第三方商标和非官方声明默认只读。7. 接入文档与后续调用入口Skill 跑通之后模型调用和文档读取就收敛到同一条通道了。Codex 侧认 TaoToken 的 base_url 和 key文档侧认你自己的腾讯文档 MCP Token两者互不干扰。后续要扩展能力比如让 Agent 自动分析文档并生成报告直接复用这套配置即可。接入文档和 API 细节在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc如果你用 Claude Code 或 Anthropic 风格的调用接入说明单独有一页https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaudecode需要新建或轮换 Key 时回到控制台https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapikeys长期跑编码和 Agent 任务Coding Plan 的额度模型更适合高频场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcodingplan浏览器自动化不是错误方案但它更适合处理「必须在页面上完成」的交互。对于读取和分析在线文档原生接口加本地解析通常更稳定也更容易验证。把完整文字、结构位置和高保真资产分成三条可验证链路边界清楚之后AI 才能从「偶尔复制成功」走向可复用的文档分析能力。