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+002D）；禁止使用 U+2011（不可断开连字符）及其他 Unicode 破折号类字符。
• 引文与参考文献必须为人类可读形式；严禁保留工具生成的占位符、标记字符串或内部 token。

最终检查项

• 交付前须以 100% 缩放比例重新渲染并逐页审阅。
• 修复所有间距、对齐或分页问题，并重复渲染-检查循环直至达标。
• 确认无冗余残留（如临时文件、重复渲染产物），除非用户明确要求保留。