用途:在需要读取、审阅、创建或编辑 .docx 文档,且对版式(表格、图表、分页)有要求时使用;也可在交付前校验视觉版式。
主要能力:以 python-docx 进行结构化编辑与创建(标题、样式、表格、列表);通过渲染进行视觉审阅,检查布局、表格与图表是否清晰、对齐正确。
使用方式:优先视觉审阅。若环境有 soffice 与 pdftoppm,可将 DOCX 转 PDF 再转 PNG;或使用 scripts/render_docx.py(依赖 pdf2image 与 Poppler)。依赖安装:uv pip install python-docx pdf2image;若 uv 不可用则 python3 -m pip install python-docx pdf2image。系统工具:macOS 用 brew install libreoffice poppler;Ubuntu/Debian 用 sudo apt-get install -y libreoffice poppler-utils。渲染命令:soffice -env:UserInstallation=file:///tmp/lo_profile_$$ --headless --convert-to pdf --outdir $OUTDIR $INPUT_DOCX;pdftoppm -png $OUTDIR/$BASENAME.pdf $OUTDIR/$BASENAME。也可用打包脚本:python3 scripts/render_docx.py /path/to/file.docx --output_dir /tmp/docx_pages。中途文件放 tmp/docs/ 并在完成后删除,最终产物放在 output/doc/,文件名保持稳定、描述性。无需环境变量。每次有意义的修改后重新渲染并检查页面。若无法视觉审阅,则用 python-docx 提取文本作为兜底,并说明版式风险。
质量与限制:交付客户可用文档,字体、间距、页边距与层次一致;避免文字裁剪重叠、表格断裂、乱码或默认模板样式;图表与视觉需清晰对齐。仅使用 ASCII 连字符,避免 U+2011 等 Unicode 破折号。引用需人类可读,不保留工具标记或占位符。最终交付前以 100% 缩放检查每页,修复间距、对齐或分页问题后重复渲染循环;清理临时文件与重复渲染,除非用户要求保留。若依赖无法安装,应告知缺失项及本地安装方法。资料未提供“When NOT to Use”的具体内容。