Word文档格式自动适配 Skill

概述

本Skill使Agent具备根据任意格式规范说明文档，自动调整源文档Word格式的能力。适用于论文、公文、期刊发文、报告等各类有格式要求的文档场景。

核心价值：将"阅读几十页格式规范→手动逐项调整Word格式"的繁琐工作，自动化为"上传两个文件→一键完成"。

v1.1 增强能力（较初版）：
- 复杂表格：自动添加边框、表头加粗+底色、单元格垂直居中、单元格内边距、跨页重复表头、表格整体对齐。规则见 table 字段。
- 公式支持：自动识别 OMML/OLE 公式段落并保护其不被重新排版；设置文档默认公式字体；Markdown 输入的 $x^2$/$x_i$ 可转换为带上下标的公式文本。
- 版本管理：SKILL.md 增加 version 字段，并新增 CHANGELOG.md 记录各版本变更。

支持的文件格式：

> 注：
> - .md 文件会自动转换为 .docx 后再进行格式处理。
> - .pdf 文件需安装可选依赖（pdfplumber/pdf2docx），见下方「环境依赖」。
> - 图片文件需安装可选 OCR 依赖（推荐 rapidocr-onnxruntime），或由 Agent 视觉能力直接提取。
> - .wps 文件通常可被 python-docx 直接读取。
> - .rtf 文件通过纯文本剥离或 pywin32（Windows）转换。

能力边界

本Skill擅长根据格式规范自动调整文档排版，但以下场景不在处理范围内：

兜底方案：当格式说明文档语义复杂导致自动解析不准确时：
1. 使用 --parse-only 先查看解析结果，手动修正规则 JSON
2. 使用 --llm-parse 生成 Prompt，借助大模型解析复杂规范
3. 在 Agent 对话中要求修正："一级标题字号应该是14不是16"

> 遇到问题？请查阅 references/faq.md 常见问题排错指南。

环境依赖

本Skill的Python工具核心依赖 python-docx，可选依赖用于图片/PDF/RTF支持。

核心依赖（必需）：

python -c "import docx" 2>/dev/null || python -m pip install -r requirements.txt

可选依赖（按需安装）：

# 图片 OCR + PDF + RTF 支持（一键安装）
python -m pip install -r requirements-optional.txt

# 或单独安装：
# 图片 OCR（推荐 RapidOCR，轻量~50MB，中文优秀）
python -m pip install rapidocr-onnxruntime
# PDF 文本提取 + PDF转docx
python -m pip install pdfplumber pdf2docx

• 依赖清单见根目录 requirements.txt（核心）和 requirements-optional.txt（可选）。
• 建议使用 python -m pip（而非裸 pip），避免装到错误解释器。
• 公式处理依赖Word内置公式字体（默认 Cambria Math），系统通常已自带。

图片输入处理协议

当格式规范文档或源文档为图片格式(.png/.jpg/.jpeg/.bmp/.tiff)时，按以下三层降级链处理：

角色A — 图片作为格式说明文档（仅需提取文本）：

1. 第1层 — Agent 视觉能力（推荐，零代码）：
   - Agent 自检是否具备图片识别能力（如 analyzeImage 工具或多模态理解）
   - 若具备：提取图片中的文本内容 → 保存为临时 .md 文件 → 用该 .md 路径替代原图片路径 → 走标准流程
   - OCR 质量最高（多模态 LLM 远超传统 OCR）

2. 第2层 — Python OCR 引擎（代码自动降级）：
   - 若 Agent 无视觉能力，将图片路径传给 Python 脚本
   - 脚本按优先级尝试以下 OCR 引擎：

   • RapidOCR (rapidocr-onnxruntime)：首选，轻量~50MB，中文优秀，pip install 即可
   • Tesseract (pytesseract + Pillow)：备选，通用，需额外安装 Tesseract + chi_sim 语言包
   • EasyOCR (easyocr)：末选，质量好但依赖 PyTorch ~500MB

3. 第3层 — 优雅失败：
   - 若以上均不可用，返回明确的错误信息和安装指引
   - 提示用户可手动将图片内容转为 .md 文件后重试

角色B — 图片作为源文档（需识别结构：标题/段落/表格/插图）：

1. 第1层 — Agent 视觉能力（推荐，零代码）：
   - Agent 用视觉能力分析图片中的文档版面结构
   - 按 Markdown 格式输出结构化文本（关键步骤）：

   • # = 文档标题
   • ## = 一级标题（1. / 一、 / 第一章）
   • ### = 二级标题（1.1 / （一））
   • #### = 三级标题（1.1.1 / 1.）
   • 普通段落 = 正文
   • | col | col | = 表格
   • 保存为 .md 文件 → 走标准 Markdown 管道（md_converter → DocumentStructureAnalyzer → FormatApplier）
   • 此方案结构识别质量最高（多模态 LLM 理解版面语义）

2. 第2层 — PaddleOCR PP-Structure（Python 版面分析 fallback）：
   - 若 Agent 无视觉能力，脚本自动尝试 PaddleOCR PP-Structure
   - PP-Structure 一体化识别：标题(title)、正文(text)、表格(table)、图片(figure) 区域
   - 按区域类型构建 docx（title→Heading, text→Paragraph, table→Table）
   - 需安装：pip install paddleocr（约1GB）

3. 第3层 — RapidOCR 带坐标启发式推断：
   - 若 PP-Structure 不可用，用 RapidOCR 带坐标结果
   - 按文本行高度启发式推断标题（高于中位数1.5倍→H1, 1.2倍→H2）
   - 结构识别质量中等

4. 第4层 — 纯 OCR 文本：
   - 以上均不可用时，提取纯文本构建全 Normal 段落的 docx
   - 结构识别差，仅靠后续 DocumentStructureAnalyzer 的编号正则识别标题

PDF 源文档处理协议

文本版 PDF（正常 PDF）：
- 使用 pdf2docx 转换为 docx，保留段落/表格结构
- 标题样式通常丢失，但 DocumentStructureAnalyzer 可通过编号正则识别

扫描版 PDF（实为图片）：
- 脚本自动检测是否为扫描件（文本量极少 + 含图片）
- 若为扫描件：每页渲染为图片(200dpi) → 走图片源文档处理协议（上述角色B）
- 需安装 PyMuPDF(fitz) 用于渲染：pip install PyMuPDF

安装说明

当用户将本Skill包拖入对话框并说"安装该技能"时：

1. 读取 SKILL.md 理解能力范围
2. 读取 src/ 目录下的Python工具代码（如环境支持Python执行）
3. 读取 references/llm-parse-prompt.md 获取LLM解析模板
4. 读取 references/format-rules-schema.md 理解JSON规则格式
5. 检测Python环境依赖（见上方「环境依赖」），必要时安装 python-docx
6. 运行 check_optional_capabilities() 检测可选依赖，记录可用能力
7. 向用户确认安装结果，并根据用户预期用途给出可选依赖安装建议（见下方「可选依赖安装决策指引」）

可选依赖安装决策指引

安装时 Agent 应询问用户预期输入格式，按需推荐安装：

问用户："您的格式说明文档和源文档主要是什么格式？"

关键区分：
- 格式说明文档为图片 → 只需 rapidocr-onnxruntime（提取文本即可，无需版面分析）
- 源文档为图片 → 需 paddleocr（必须识别标题/段落/表格等结构）
- Agent 有视觉能力 → 图片源文档无需安装任何 OCR 库（Agent 直接输出结构化 Markdown）

使用流程（安装后）

标准指令模板

用户安装后，使用以下标准指令触发：

> "将 [源文档.docx/.md] 按照 [格式说明.docx/.md] 的要求，进行完整的格式设置，并输出修改后的标准格式文档到 [指定路径/文件夹]"

执行步骤

Agent收到上述指令后，按以下步骤执行：

Step 1: 读取并理解格式规范

• 读取用户上传的格式规范文档（.docx/.doc/.md）
• 如为 .md 文件，直接读取文本内容
• 如为 .docx/.doc 文件，提取文档中所有段落文本
• 使用 references/llm-parse-prompt.md 中的Prompt模板，将规范文本输入LLM进行解析
• LLM输出结构化的JSON格式规则
• 输出: format_rules.json（保存到工作目录）

Step 2: 读取并转换源文档

• 读取用户上传的源文档（.docx/.doc/.md）
• 如为 .md 文件，调用 src/md_converter.py 转换为临时 .docx 文件
• 如为 .doc 文件，尝试用 python-docx 读取并另存为 .docx
• 如为 .docx 文件，直接使用
• 输出: 转换后的 .docx 文件路径

Step 3: 分析文档结构

• 使用 src/doc_structure_analyzer.py 的逻辑分析文档结构
• 识别：文档标题、作者、摘要、关键词、各级标题（1-4级）、正文、参考文献、图表标题
• 输出: 结构分析报告（文本形式展示给用户）

Step 4: 应用格式规则

• 加载Step 1生成的JSON规则
• 根据Step 3识别的结构，逐段落应用格式
• 修改内容：页面设置、字体、字号、行距、间距、对齐、缩进
• 输出: 格式化后的Word文档（.docx）

Step 5: 保存并交付

• 将格式化后的文档保存到用户指定的路径/文件夹
• 如用户未指定路径，保存到默认输出目录，命名为 {原文件名}_formatted.docx
• 如原文档是 .md 转换而来，输出文件名基于原 md 文件名
• 向用户展示：
• 格式化完成确认
• 应用的规则摘要（如"一级标题：黑体16pt加粗居中"）
• 识别的结构统计（如"识别到3级标题共12个，正文段落45个"）
• 输出文件路径

分步模式

如果用户只上传了规范文档：

> "请解析这个格式规范，输出一个可以复用的规则文件"

Agent执行Step 1，输出JSON规则文件，告知用户保存后可在后续格式化中复用。

核心能力详解

1. 格式规范解析（LLM驱动）

格式规范文档可以是 .docx/.doc/.md 格式。Agent：

• .docx/.doc: 用 python-docx 提取所有段落文本
• .md: 直接读取文件文本内容

然后使用 references/llm-parse-prompt.md 中的标准化Prompt，让LLM提取以下要素：

关键：LLM解析后，Agent必须向用户展示提取的规则摘要，让用户确认或修改。

2. Markdown 到 Word 转换

当源文档为 .md 格式时，使用 src/md_converter.py 进行轻量级转换：

转换后，再按照格式规则统一调整字体和段落格式。

3. 文档结构识别（规则驱动）

使用 src/doc_structure_analyzer.py 中的识别逻辑：

4. 格式应用（python-docx驱动）

使用 src/format_applier.py 中的逻辑，通过python-docx库修改Word文档：

• 页面设置：修改Section的page_width、page_height、margins
• 段落格式：alignment、line_spacing、space_before/after、indentation
• 字体格式：name、size、bold、italic、color
• 中英文字体分离：通过底层XML操作（w:rFonts节点的w:eastAsia属性）分别设置中文字体和英文字体
• 样式修改：同步修改文档内置样式（Normal、Heading 1-4）

输入输出规范

输入

输出

跨Agent适配

本Skill的核心是标准化JSON规则 + Python工具脚本，可在任何环境中使用：

限制与注意事项

1. .doc 格式兼容性：python-docx 对 .doc 格式的读取能力有限，复杂 .doc 文件可能无法正确读取，建议先转换为 .docx
2. Markdown 转换：轻量级转换器仅支持基本 Markdown 语法，复杂表格、数学公式、嵌套列表等可能转换不完美
3. 复杂页眉页脚：奇偶页不同、分节符控制等需手动调整
4. 公式对象：MathType/OMML公式格式修改能力有限
5. 参考文献排序：仅调整格式，不重新排序引用
6. 字体依赖：需确保系统安装规则中指定的字体
7. 表格格式：支持表格边框、表头加粗+底色、单元格垂直居中、单元格内边距、跨页重复表头、表格整体对齐；但不支持合并单元格的修改
8. 标题识别：无编号标题的识别准确率较低，建议用户确认结构分析结果

错误处理

示例对话

示例1：完整格式化流程（docx输入）

User: 安装该技能

Agent: ✅ Word格式适配技能已安装。我可以帮您：
1. 解析期刊/学校/机关单位的格式规范文档（支持 .docx/.doc/.md）
2. 自动识别文档结构（标题、摘要、正文、参考文献等）
3. 一键应用格式规则，生成标准格式 .docx 文档

请上传您的格式规范文档和源文档，我会帮您完成格式化。

User: 将我的文档.docx按照计算机学报格式说明.docx的要求，进行完整的格式设置，并输出到 /papers/ 文件夹

Agent:
好的，开始执行格式化流程：

Step 1/5: 解析格式规范...
已从《计算机学报格式说明》中提取以下规则：
- 页面：A4，页边距上下2.54cm，左右3.17cm
- 一级标题：黑体16pt，居中，段前12磅段后6磅
- 二级标题：黑体14pt，左对齐，段前6磅段后6磅
- 正文：宋体12pt，Times New Roman英文，1.5倍行距，首行缩进2字符
- 摘要：楷体12pt，1.5倍行距
- 参考文献：宋体10.5pt，单倍行距

Step 2/5: 读取源文档...
文档格式：.docx，直接使用。

Step 3/5: 分析文档结构...
识别结果：
- 文档标题：1个
- 作者信息：1个
- 摘要：1个（长度约200字）
- 关键词：1个
- 一级标题：4个（1.引言 2.相关工作 3.方法 4.实验）
- 二级标题：8个
- 三级标题：3个
- 正文段落：42个
- 参考文献：15条
- 图表标题：6个

结构识别是否正确？如有误请指出，我将修正。

Step 4/5: 应用格式规则...
正在应用格式...
✅ 页面设置已调整
✅ 标题格式已应用（4个一级标题、8个二级标题、3个三级标题）
✅ 正文格式已应用（42个段落）
✅ 摘要/关键词格式已应用
✅ 参考文献格式已应用（15条）
✅ 图表标题格式已应用（6个）

Step 5/5: 保存文档...
格式化完成！文档已保存至：/papers/文档_formatted.docx

示例2：Markdown文档输入

User: 我的文档是 markdown 格式的，格式说明是 word 文档，能处理吗？

Agent:
可以处理！本Skill支持 .md 格式的源文档输入，会自动将其转换为 .docx 后再进行格式调整。

请上传：
1. 格式说明文档（.docx/.doc/.md）
2. 源文档（.md）

我将：
1. 解析格式规范
2. 将您的 .md 文档转换为 .docx（保留标题、粗体、斜体、列表等格式）
3. 按照规范应用格式
4. 输出标准格式的 .docx 文件

User: [上传 format_spec.docx 和 paper.md]

Agent:
收到两个文件，开始处理：

Step 1/5: 解析格式规范...
已从 format_spec.docx 中提取规则...

Step 2/5: 转换源文档...
正在将 paper.md 转换为 Word 文档...
- 识别到 Heading 1: 4个
- 识别到 Heading 2: 6个
- 识别到正文段落：38个
- 识别到粗体文本：12处
- 识别到代码块：3个
转换完成：paper_converted.docx

Step 3/5: 分析文档结构...
[结构分析结果...]

Step 4/5: 应用格式规则...
[格式应用结果...]

Step 5/5: 保存文档...
格式化完成！文档已保存至：paper_formatted.docx

示例3：仅解析规范

User: 请帮我解析这个学位论文格式规范（.md），我要保存规则以后用

Agent:
正在解析格式规范（.md）...

提取的规则摘要：
- 页面：A4，页边距上下2.5cm，左右3cm
- 一级标题：黑体三号（16pt），居中
- 二级标题：黑体四号（14pt），左对齐
- 正文：宋体小四（12pt），英文Times New Roman，1.5倍行距
- 摘要：楷体小四（12pt）
- 参考文献：宋体五号（10.5pt）

规则JSON已生成，是否保存？
[输出 format_rules.json 供下载]

您可以保存此JSON文件，以后格式化文档时直接上传规则和源文档即可，无需重复解析规范。