report-to-google-doc

转换为 Google 文档

仅当用户明确需要从现有 HTML 分析报告生成可共享的 Google Drive 文档时，才使用此技能。源文件必须是 HTML 报告：本地文件、下载的托管于 blob 的报告，或由 $build-report HTML 模式生成的报告。此技能不会直接转换实时 MCP 应用报告。

预期流程为 HTML -> DOCX -> 上传到 Drive。Drive 可以将上传文件作为基于 DOCX 的查看器文件托管，而不必转换为原生 Google Docs MIME 类型。不要使用旧的 Google Docs 批量更新请求路径。

工作流

1. 确定 HTML 报告。

   使用绝对本地路径。如果用户提供远程报告，先下载，然后将本地 HTML 文件传递给辅助程序。如果文件是登录页面、重定向页面或很小的占位文件，请停止并获取真正的报告。

2. 运行捆绑的辅助程序。

   python3 <REPORT_TO_GOOGLE_DOC_SKILL_DIR>/scripts/report_to_google_doc_plan.py \
     /absolute/path/to/report.html \
     --out-dir /tmp/report_to_google_doc_plan
   

   正常情况下省略 --render-workers。只有在本地对同类报告进行基准测试后，才传入工作线程数量。如果缺少依赖项， 请使用包含 beautifulsoup4、pillow 和 python-docx 的本地虚拟环境；cairosvg 或无头 Playwright 是可选的渲染器。

3. 检查辅助程序的输出。

   必需的输出：

   • skeleton.txt：带有稳定占位符的源文本
   • manifest.json：解析后的标题、表格、提示框、列表、样式、链接 和渲染后的视觉内容清单
   • preflight_checks.json：源文件、宽度、DOCX 和渲染图像检查结果
   • report.docx：生成的本地 Word 文档
   • docx_upload_plan.json：精简的上传说明
   • placeholder_queries.json：源映射调试标签

   在 preflight_checks.json 的 status: "passed" 且错误数为零之前，不要上传。必须修复警告，或在交接时说明警告。

4. 上传 DOCX。

   mcp__codex_apps__google_drive._upload_file({
     "file_uri": "/tmp/report_to_google_doc_plan/report.docx",
     "file_name": "Report Name.docx",
     "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
   })
   

   将返回的 Drive URL 作为交付内容。不要尝试强制转换为原生 Google Docs 格式，也不要回退到 _batch_update_document。

5. 验证上传结果。

   确认上传的文件可读取且非空。将上传文本与源内容清单进行比较：标题、章节标题、执行摘要或答案提示框、注意事项、建议、来源说明和源链接。 如可用，检查本地 report.docx 的结构：标题数量、 列表、表格、超链接关系和图像关系应与 manifest.json 一致。

6. 交付链接。

   返回 Drive/Docs URL，并在有用时提供本地 DOCX 路径或源 HTML 路径。仅连接器成功并不足以完成交接；只有在根据源报告检查上传文件和本地 DOCX 结构后，交接才算完成。常规检查和预检详情保留在支持材料中。除非检查失败、无法执行或发现与用户相关的注意事项，否则不要在面向用户的交付内容中列出内部检查。

标准

• 保留 HTML 报告中的每个章节、标题主张、指标卡片、指标定义、 来源说明、图表要点、建议、注意事项和链接。
• 保留语义格式：标题、段落、行内粗体／强调、行内代码、正／负颜色、链接、列表、提示框、指标卡片网格、表格、注释、图注和图表。
• 尽可能使用 DOCX 原生结构：标题、段落、表格、项目符号／编号列表、链接、行内图片、段落底纹、表格单元格底纹和文本样式。
• 保持报告正文列易于阅读。表格、图表、渲染后的表格网格、屏幕截图和视觉区块不得超出 DOCX 页面文本宽度。
• 将图表保留为以内嵌图片形式呈现的源视觉内容，或使用包含相同数据的 SVG 后备图；图片应与文本和表格左边缘对齐。若图表缺少柱条、图例色块，或图形标记全黑／全白，即使 DOCX 中包含图片对象，也未通过验证。
• 保留多列报告区块。仅由带标题的小型表格组成的双列网格可以保留为宽度不超过文本栏的双列渲染图；包含叙述文本、标签、提示框或非表格面板的混合双列区块，应以原生方式保留这些内容，而不是将其丢弃。
• 不要泄露经过脱敏的报告中有意省略的客户级详情或敏感链接。
• 不要编写 Google Docs 批量更新产物，例如 seed_requests.json、 remote_write_plan.json 或 all_requests*.json。

修复

验证发现转换问题时，请使用以下修复方法：

问题	修复方法
标题为常规字重	修复 DOCX 写入器的标题样式，或显式设置文本运行加粗。
标题后有空白行	删除间隔段落；骨架应在标题后输出 \n，而不是 \n\n。
正文段落间距过大	删除字面空白段落，并设置适度的样式间距。
表格／图片过宽	将表格列宽或图片宽度设置为 DOCX 文本栏宽度。
图表有标签但缺少柱条	将 SVG 类样式内联，或在插入前使用无头浏览器截图。
双列表格组被压平	将网格视为一个布局区块，并保留小型表格标题。
缺少执行摘要、指标卡片或章节	在上传前修复解析器清单。
图表与表格重叠	在表格后的独立段落中插入图片。
图表重复	移除多余图片；按源文档顺序仅保留一份。
缺少行内粗体／代码／颜色	修复 DOCX 写入器中的清单范围拆分。
源链接显示为原始 URL	替换为原生链接标签，或使用 HTML 链接文本创建原生项目符号。

本地检查

python3 -m py_compile <REPORT_TO_GOOGLE_DOC_SKILL_DIR>/scripts/report_to_google_doc_plan.py
python3 <REPORT_TO_GOOGLE_DOC_SKILL_DIR>/scripts/report_to_google_doc_plan.py \
  /absolute/path/to/report.html \
  --out-dir /tmp/report_to_google_doc_plan_smoke
jq '.status, .summary' /tmp/report_to_google_doc_plan_smoke/preflight_checks.json
test -f /tmp/report_to_google_doc_plan_smoke/report.docx
test -f /tmp/report_to_google_doc_plan_smoke/docx_upload_plan.json
git diff --check -- plugins/data-analytics/skills/build-report/report-to-google-doc