# DOCX Layout Repair

> 基于已有 DOCX 或文本稿修复标题层级、段落、列表和分页，交付可继续编辑的 Word 文档。用户要统一文档格式、修复目录、整理凌乱报告时使用。

- Skill: `luyu2026/docx-layout-repair` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx get-skill add luyu2026/docx-layout-repair`
- Raw SKILL.md: https://api.skillmd.com/api/skills/luyu2026/docx-layout-repair/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: luyu2026 (https://skillmd.com/u/luyu2026)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/luyu2026/docx-layout-repair

---


# Word 文档结构与排版修复

## 一句话主餐

普通聊天给排版建议却留下手工劳动；这里直接将现有报告修成有层级、可编辑、可核验的 DOCX。

## 输入

优先读取用户已经给出的材料，不要求为本 Skill 重新抄写。

- 原始 DOCX 或完整正文，已有模板优先
- 文档用途、接收者和必须遵守的版式要求
- 不可改写段落、签章、表格、脚注及修订保留要求

没有模板时采用明确标注的简洁报告样式；不补写事实、不擅自接受修订，不伪造签章。

输入识别要求：
- 保留原始材料和来源定位，生成文件默认另存。
- 区分真实用户材料、待确认项与明确模拟输入。
- 用户目标明确时直接制作；只有影响结果的歧义才提出具体问题。
- 一次只解决本轮目标，不顺手扩展为其他业务流程。

## 核心判断

- 结构修复与内容改写分开；只排版时保留原句和数据。
- 标题使用真正的段落样式，不能只放大加粗。
- 列表编号、正文数字与章节号分开，避免把数据变成序号。
- 分页通过段落和节属性控制，不用连续空行挤位置。
- 目录字段需要 Word 等应用更新；生成字段不代表页码已验证。
- 批注、修订、文本框、域和嵌入对象可能被简单库遗漏，编辑前盘点。

比较 python-docx 样式修改与 Word/LibreOffice 排版引擎：前者可验证结构，后者用于分页与字段刷新，两者验收分别记录。
参考 PDF 页序映射机制核对导出版面，但不能用导出 PDF 替代用户要求的可编辑 DOCX。

### 容易误判的边界

- 不要对含超链接、域或混合字符样式的整段直接赋值 paragraph.text，这会重建 runs；只改段落样式或精确修改目标 run。
- 盘点 zip 包中的 comments、footnotes、embeddings、签章图片与修订标签；不能仅看 document.paragraphs 推断对象齐全。
- 合并段落前先核对超链接、书签及批注锚点；无法安全迁移时保留段落边界。
- 复杂对象无法保真时保留源件并交局部排版补丁；不可悄悄重建整篇。

## 编号工作流

### 1. 识别文档对象

- 盘点段落、表格、页眉页脚、分节、批注和修订。
- 记录原始正文和关键数字用于后续对照。
- 复杂域或签章附近区域先圈定保留范围。
- 产出结构清单与可编辑区域。

### 2. 建立标题树

- 从编号、内容和上下文判断标题级别。
- 同层标题使用一致样式，修复无依据的跳级。
- 不能确定的短句保留正文，不全凭字体大小判断。
- 产出标题树并将原段落映射到层级。

### 3. 映射样式

- 优先继承用户模板的字体、颜色与段落样式。
- 无模板时给出正文、一级标题、二级标题和说明文字样式。
- python-docx 使用内置样式英文名，例如 Heading 1。
- 产出样式映射，避免逐段手工重复设置。

### 4. 修复段落与列表

- 合并仅由错误换行切断的同一段，保留真正的段落边界。
- 列表使用列表语义，数字、日期与版本号维持正文。
- 设置行距、段前后距和首行缩进，清除用于对齐的空格。
- 产出连续可编辑的正文与列表。

### 5. 整理表格与分页

- 表头可跨页重复，单元格内容不截断。
- 标题与后段保持同页，长表按内容自然分页。
- 横向宽表必要时独立分节，恢复后续正文方向。
- 产出页面布局，记录必须人工确认的复杂对象。

### 6. 生成目录与导航

- 只在用户需要目录且文档规模适合时插入目录字段。
- 目录来自标题样式，不能手写虚假的页码。
- 保留页码与页眉字段；注明是否已在排版引擎更新。
- 产出导航结构与字段更新说明。

### 7. 核对内容和版面

- 比较段落正文、表格文本与关键数字，解释必要的合并变化。
- 重新打开 DOCX 验证结构及样式引用有效。
- 可渲染时检查首尾页、长表、分节与目录；不能渲染则明确范围。
- 产出内容核对与版面检查记录。

### 8. 交付可继续编辑版本

- 另存 formatted.docx，不覆盖源文件。
- 只列影响使用的变化及需要用户确认的版面点。
- 用户提供目标软件截图后只修相应页面问题。
- 完成条件为正文无误、标题可导航、对象保留状态清楚。

## 直接交付与下一步

默认交付以下成果；按用户目标裁剪，不为凑齐数量生成无关附件。

- formatted.docx：可编辑的排版成品
- 标题树、样式映射和变更说明
- 内容核对结果与目录字段更新状态

交接规则：
- 先给可使用的成品入口，再说明仍影响使用的缺口。
- 核验必须写明执行了什么、结果如何、哪些能力没有执行。
- 本轮能完成的一次性交付到此结束，不附加通用调研作业。
- 需要继续时，只要求用户交回具体异常位置、确认口径或新材料。
- 复交后沿用已确认事实，检查本次修复及其影响的原有部分。

工具不可用时：

无 DOCX 编辑库时交付逐项样式操作单：选定段落→Word“开始/样式”设标题级别→段落设置段前后距与“与下段同页”→更新目录。正文另交 Markdown，仅称内容版；没有 Word/LibreOffice 时明确分页与页码未验收。

### 外部参考与延展

- 遇到跨节页码、修订保留或目录刷新问题时启动研究。
- 查 python-docx 官方样式文档、Microsoft Word 字段与 Open XML 文档。
- 比较样式驱动与逐段格式化，观察导航、继承和后续编辑的稳定性。
- 对复杂对象比较局部 XML 修改与整篇重建的保真代价。
- 用包含同类对象的副本验证，再把方法接入对应步骤。
- 研究不扩大到内容代写；无法保真的对象保留原件并说明。

官方资料入口：[Word 文档结构与排版修复相关资料](https://python-docx.readthedocs.io/en/stable/user/styles-using.html)。
已有材料足够时直接交付；研究只围绕当前失败点，不重复搜集无关项目。
实际采用外部内容时保留必要许可与来源；仅比较机制不复制正文。

### 验收用例与演示

先读 [本批边界案例与可用交付](references/review-cases.md)，再读 [演示成品](demo.md) 可看到明确模拟输入、成品和下一步。
演示是固定案例的执行结果，不代表所有真实文件和环境都通过验证。
运行当前任务时必须重新核对用户材料，不把演示数据混入用户输出。

复审案例记录仅使用明确模拟输入；运行用户任务时重新生成结果，不复用模拟事实。

