doc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DOCX Skill

When to use

适用场景

Read or review DOCX content where layout matters (tables, diagrams, pagination).
Create or edit DOCX files with professional formatting.
Validate visual layout before delivery.

读取或审查对布局有要求的DOCX内容（如表格、图表、分页）。
创建或编辑具有专业格式的DOCX文件。
交付前验证视觉布局。

Workflow

工作流程

Prefer visual review (layout, tables, diagrams).
- If
```
soffice
```
  and
```
pdftoppm
```
  are available, convert DOCX -> PDF -> PNGs.
- Or use
```
scripts/render_docx.py
```
  (requires
```
pdf2image
```
  and Poppler).
- If these tools are missing, install them or ask the user to review rendered pages locally.
Use
```
python-docx
```
for edits and structured creation (headings, styles, tables, lists).
After each meaningful change, re-render and inspect the pages.
If visual review is not possible, extract text with
```
python-docx
```
as a fallback and call out layout risk.
Keep intermediate outputs organized and clean up after final approval.

优先进行视觉审查（布局、表格、图表）。
- 如果已安装
```
soffice
```
  和
```
pdftoppm
```
  ，将DOCX转换为PDF再转成PNG图片。
- 或者使用
```
scripts/render_docx.py
```
  （需要依赖
```
pdf2image
```
  和Poppler）。
- 如果缺少这些工具，请安装它们或让用户在本地审查渲染后的页面。
使用
```
python-docx
```
进行编辑和结构化创建（如标题、样式、表格、列表）。
每次完成重要修改后，重新渲染并检查页面。
如果无法进行视觉审查，可作为备选方案使用
```
python-docx
```
提取文本，并标注布局风险。
整理好中间输出文件，在最终确认后清理临时文件。

Temp and output conventions

临时文件与输出规范

Use
```
tmp/docs/
```
for intermediate files; delete when done.
Write final artifacts under
```
output/doc/
```
when working in this repo.
Keep filenames stable and descriptive.

中间文件存放在
```
tmp/docs/
```
目录下；使用完成后删除。
在本仓库中工作时，最终产物请保存至
```
output/doc/
```
目录。
文件名需保持稳定且具有描述性。

Dependencies (install if missing)

依赖项（缺失时请安装）

Prefer

uv

for dependency management.

Python packages:

uv pip install python-docx pdf2image

uv

is unavailable:

python3 -m pip install python-docx pdf2image

System tools (for rendering):

undefined

优先使用

uv

进行依赖管理。

Python包：

uv pip install python-docx pdf2image

如果

uv

不可用：

python3 -m pip install python-docx pdf2image

系统工具（用于渲染）：

undefined

macOS (Homebrew)

macOS（Homebrew）

brew install libreoffice poppler

Ubuntu/Debian

sudo apt-get install -y libreoffice poppler-utils


If installation isn't possible in this environment, tell the user which dependency is missing and how to install it locally.

sudo apt-get install -y libreoffice poppler-utils


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

Environment

环境要求

No required environment variables.

无必需的环境变量。

Rendering commands

渲染命令

DOCX -> PDF:

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

PDF -> PNGs:

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

Bundled helper:

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

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

Quality expectations

质量要求

Deliver a client-ready document: consistent typography, spacing, margins, and clear hierarchy.
Avoid formatting defects: clipped/overlapping text, broken tables, unreadable characters, or default-template styling.
Charts, tables, and visuals must be legible in rendered pages with correct alignment.
Use ASCII hyphens only. Avoid U+2011 (non-breaking hyphen) and other Unicode dashes.
Citations and references must be human-readable; never leave tool tokens or placeholder strings.

交付客户就绪的文档：排版一致、间距合理、边距规范、层级清晰。
避免格式缺陷：文本被裁剪/重叠、表格破损、字符无法读取或使用默认模板样式。
图表、表格和视觉元素在渲染页面中必须清晰可读，对齐正确。
仅使用ASCII连字符。避免使用U+2011（非断字连字符）及其他Unicode破折号。
引用和参考文献必须易于人类阅读；绝对不能留下工具标记或占位符字符串。

Final checks

最终检查

Re-render and inspect every page at 100% zoom before final delivery.
Fix any spacing, alignment, or pagination issues and repeat the render loop.
Confirm there are no leftovers (temp files, duplicate renders) unless the user asks to keep them.

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