doc

DOCX 技能

使用场景

• 在布局很重要（表格、图表、分页）的情况下阅读或审阅 DOCX 内容。
• 创建或编辑格式专业的 DOCX 文件。
• 交付前验证视觉布局。

工作流

1. 优先进行视觉审阅（布局、表格、图表）。
   • 如果有 soffice 和 pdftoppm，将 DOCX 转换为 PDF，再转换为 PNG。
   • 或使用 scripts/render_docx.py（需要 pdf2image 和 Poppler）。
   • 如果缺少这些工具，请安装它们，或请用户在本地审阅渲染后的页面。
2. 使用 python-docx 进行编辑和结构化创建（标题、样式、表格、列表）。
3. 每次进行有意义的更改后，重新渲染并检查页面。
4. 如果无法进行视觉审阅，则使用 python-docx 提取文本作为备用方案，并指出布局风险。
5. 整理好中间输出，并在最终获批后清理。

临时文件和输出规范

• 中间文件使用 tmp/docs/；完成后删除。
• 在此代码库中工作时，将最终产物写入 output/doc/。
• 文件名应稳定且具有描述性。

依赖项（缺少时安装）

依赖管理优先使用 uv。

Python 包：

uv pip install python-docx pdf2image

如果没有 uv：

python3 -m pip install python-docx pdf2image

系统工具（用于渲染）：

# macOS (Homebrew)
brew install libreoffice poppler

# Ubuntu/Debian
sudo apt-get install -y libreoffice poppler-utils

如果无法在此环境中安装，请告知用户缺少哪项依赖，以及如何在本地安装。

环境

无需设置环境变量。

渲染命令

DOCX -> PDF：

soffice -env:UserInstallation=file:///tmp/lo_profile_$$ --headless --convert-to pdf --outdir $OUTDIR $INPUT_DOCX

PDF -> PNG：

pdftoppm -png $OUTDIR/$BASENAME.pdf $OUTDIR/$BASENAME

捆绑的辅助工具：

python3 scripts/render_docx.py /path/to/file.docx --output_dir /tmp/docx_pages

质量要求

• 交付可直接提供给客户的文档：字体、间距、页边距保持一致，层级清晰。
• 避免格式缺陷：文本被裁切或重叠、表格错乱、字符无法辨认或使用默认模板样式。
• 图表、表格和视觉内容在渲染后的页面中必须清晰易读且对齐正确。
• 仅使用 ASCII 连字符。避免使用 U+2011（不换行连字符）及其他 Unicode 破折号。
• 引文和参考资料必须易于阅读；绝不可保留工具标记或占位字符串。

最终检查

• 最终交付前，以 100% 缩放比例重新渲染并检查每一页。
• 修复间距、对齐或分页问题，并重复渲染流程。
• 确认没有残留文件（临时文件、重复渲染文件），除非用户要求保留。