# word-format-adapter-skill

**Repository Path**: aken721/word-format-adapter-skill

## Basic Information

- **Project Name**: word-format-adapter-skill
- **Description**: Word文档格式自动适配Skill - 根据格式说明文档将原文档自动排版为规范docx
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-11
- **Last Updated**: 2026-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Word 文档格式自动适配 Skill

[English](#english) | 中文

---

## 概述

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

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

## 支持的文件格式

| 类型 | 支持的输入格式 | 输出格式 |
|------|-------------|---------|
| 格式规范文档 | .md / .docx / .doc / .wps / .pdf / .rtf / .png / .jpg / .jpeg / .bmp / .tiff | — |
| 源文档 | .md / .docx / .doc / .wps / .pdf / .rtf / .png / .jpg / .jpeg / .bmp / .tiff | .docx |

## 核心能力

- **格式规范解析**：从格式说明文档中自动提取页面设置、标题/正文/摘要/参考文献/图表/表格/公式格式
- **文档结构识别**：自动识别文档中的标题（1-4级）、摘要、关键词、正文、参考文献、图表标题、公式
- **格式应用**：通过 python-docx 修改字体、字号、行距、间距、对齐、缩进、页边距等
- **中英文字体分离**：通过底层 XML 操作分别设置中文字体和英文字体
- **复杂表格支持**：自动添加边框、表头加粗+底色、单元格垂直居中、跨页重复表头
- **公式支持**：识别 OMML/OLE 公式段落并保护其不被重新排版
- **公文标题模式**：支持 `（一）`/`1.`/`（1）` 等政府公文标题编号
- **多格式输入**：支持 Markdown、Word、PDF、WPS、RTF、图片等多种输入格式
- **图片 OCR 三层降级链**：Agent 视觉 → PaddleOCR PP-Structure → RapidOCR → 优雅失败

## 安装方式

### 方式一：拖入 Agent 对话框（推荐）

1. 从 [Gitee Release](https://gitee.com/aken721/word-format-adapter-skill/releases/tag/v1.3) 或 [SkillHub](https://skillhub.cn) 下载 `word-format-adapter-skill-v1.3.zip`
2. 将 zip 包拖入 Agent 对话框
3. 发送一句话即可安装，例如："安装该技能"

### 方式二：解压到 Agent skills 目录

1. 下载 zip 压缩包
2. 解压到 Agent 的 skills 目录（如 `~/.codeartsdoer/skills/word-format-adapter`）
3. 重启 Agent 或新建对话，技能自动加载

### 方式三：Git Clone

```bash
git clone https://gitee.com/aken721/word-format-adapter-skill.git
```

克隆后将目录拖入 Agent 对话框，或复制到 Agent 的 skills 目录即可。

## 快速开始

### 环境依赖

**核心依赖（必需）**：

```bash
pip install -r requirements.txt
```

**可选依赖（按需安装）**：

```bash
# 场景1: 仅用 .docx/.doc/.md/.wps → 无需可选依赖
# 场景2: 格式说明为图片/PDF → pip install rapidocr-onnxruntime pdfplumber
# 场景3: 源文档为图片 → pip install paddleocr
# 场景4: 扫描版PDF → pip install paddleocr PyMuPDF
# 场景5: 通用覆盖 → pip install rapidocr-onnxruntime pdfplumber pdf2docx

pip install -r requirements-optional.txt
```

### 使用方式

#### 方式一：在 Agent 对话框中使用（推荐）

上传格式规范文档和源文档，发送指令即可：

```
请将 [源文档.docx] 按照 [格式说明.docx] 的要求进行格式设置，输出到 /output/ 文件夹
```

Agent 自动完成：解析规范 → 转换文档 → 分析结构 → 应用格式 → 输出 .docx

#### 方式二：直接运行 Python 脚本

```bash
# 完整格式化
python src/main.py --spec 格式说明.docx --paper 文档.md --output 结果.docx

# 仅解析格式规范（生成可复用的 rules.json）
python src/main.py --spec 格式说明.docx --parse-only --rules-out rules.json

# 使用已有规则直接格式化
python src/main.py --paper 文档.docx --rules rules.json --output 结果.docx

# 预览文档结构分析（不实际修改）
python src/main.py --paper 文档.md --preview
```

## 项目结构

```
word-format-adapter-skill/
├── SKILL.md                          # 技能定义文件
├── README.md                         # 本文件
├── LICENSE                           # Apache 2.0 许可证
├── CHANGELOG.md                      # 版本变更记录
├── requirements.txt                  # 核心依赖
├── requirements-optional.txt         # 可选依赖
├── src/
│   ├── main.py                       # 主程序入口
│   ├── format_spec_parser.py         # 格式规范解析器
│   ├── doc_structure_analyzer.py     # 文档结构分析器
│   ├── format_applier.py             # 格式应用器
│   └── md_converter.py              # Markdown 转换器 + 多格式输入处理
├── references/
│   ├── usage-guide.md                # 使用指南
│   ├── faq.md                         # 常见问题与排错指南
│   ├── format-rules-schema.md        # JSON 规则 Schema
│   └── llm-parse-prompt.md           # LLM 解析 Prompt 模板
└── examples/
    ├── example_rules.json            # 通用示例规则
    ├── format_rules_jrjg.json        # 《金融监管研究》期刊规则
    ├── format_jrjg.py                # 期刊定制排版脚本
    └── before-after-comparison.md    # 格式化前后对比示例
```

## 许可证

本项目采用 [Apache License 2.0](LICENSE)。

### 依赖许可声明

| 依赖 | 许可证 | 用途 | 是否必需 |
|------|--------|------|---------|
| python-docx | MIT | Word 文档读写 | ✅ 必需 |
| rapidocr-onnxruntime | Apache 2.0 | 图片 OCR 文本提取 | 可选 |
| paddleocr | Apache 2.0 | 图片版面分析（PP-Structure） | 可选 |
| pdfplumber | MIT | PDF 文本提取 | 可选 |
| pdf2docx | GPL-3.0 | PDF 转 docx | 可选 |
| PyMuPDF (fitz) | AGPL-3.0 | PDF 渲染/扫描件检测 | 可选 |
| pytesseract | Apache 2.0 | 图片 OCR（Tesseract 封装） | 可选 |
| Pillow | HPND (MIT-like) | 图片处理 | 可选 |
| easyocr | Apache 2.0 | 图片 OCR（PyTorch 后端） | 可选 |
| pywin32 | PSF-2.0 | Windows COM 接口（RTF 转换） | 可选 |

> **注意**：`pdf2docx`（GPL-3.0）和 `PyMuPDF`（AGPL-3.0）为强 copyleft 许可证。若需在闭源项目中使用本 Skill，请避免安装这两个依赖，或改用其他 PDF 处理方案。核心功能（.docx/.doc/.md 输入）不依赖任何强 copyleft 库。

---

# English

## Overview

This Skill enables AI Agents to automatically adjust document Word formatting according to any format specification document. Works for papers, official documents, journal submissions, reports, etc.

**Core Value**: Automates the tedious work of "reading dozens of pages of format specs → manually adjusting Word formatting" into "upload two files → one-click completion".

## Supported File Formats

| Type | Supported Input Formats | Output Format |
|------|------------------------|---------------|
| Format Spec Document | .md / .docx / .doc / .wps / .pdf / .rtf / .png / .jpg / .jpeg / .bmp / .tiff | — |
| Source Document | .md / .docx / .doc / .wps / .pdf / .rtf / .png / .jpg / .jpeg / .bmp / .tiff | .docx |

## Installation

### Option 1: Drag into Agent Dialog (Recommended)

1. Download `word-format-adapter-skill-v1.3.zip` from [Gitee Release](https://gitee.com/aken721/word-format-adapter-skill/releases/tag/v1.3) or [SkillHub](https://skillhub.cn)
2. Drag the zip file into the Agent dialog
3. Send a message to install, e.g., "安装该技能"

### Option 2: Extract to Agent Skills Directory

1. Download the zip file
2. Extract to the Agent's skills directory (e.g., `~/.codeartsdoer/skills/word-format-adapter`)
3. Restart the Agent or start a new conversation; the skill loads automatically

### Option 3: Git Clone

```bash
git clone https://gitee.com/aken721/word-format-adapter-skill.git
```

Drag the directory into the Agent dialog, or copy it to the Agent's skills directory.

## Quick Start

```bash
# Install core dependency
pip install -r requirements.txt

# Install optional dependencies (as needed)
pip install -r requirements-optional.txt
```

### Usage

#### Option 1: In Agent Dialog (Recommended)

Upload the format spec document and source document, then send:

```
请将 [source.docx] 按照 [format_spec.docx] 的要求进行格式设置，输出到 /output/ 文件夹
```

The Agent automatically: parses spec → converts document → analyzes structure → applies formatting → outputs .docx

#### Option 2: Run Python Script Directly

```bash
# Full formatting
python src/main.py --spec format_spec.docx --paper paper.md --output result.docx

# Parse spec only (generate reusable rules.json)
python src/main.py --spec format_spec.docx --parse-only --rules-out rules.json

# Format with existing rules
python src/main.py --paper paper.docx --rules rules.json --output result.docx

# Preview structure analysis
python src/main.py --paper paper.md --preview
```

## License

This project is licensed under the [Apache License 2.0](LICENSE).

### Dependency License Declaration

| Dependency | License | Purpose | Required |
|------------|---------|---------|----------|
| python-docx | MIT | Word document I/O | ✅ Yes |
| rapidocr-onnxruntime | Apache 2.0 | Image OCR | Optional |
| paddleocr | Apache 2.0 | Image layout analysis | Optional |
| pdfplumber | MIT | PDF text extraction | Optional |
| pdf2docx | GPL-3.0 | PDF to docx | Optional |
| PyMuPDF (fitz) | AGPL-3.0 | PDF rendering | Optional |
| pytesseract | Apache 2.0 | Tesseract wrapper | Optional |
| Pillow | HPND | Image processing | Optional |
| easyocr | Apache 2.0 | OCR (PyTorch) | Optional |
| pywin32 | PSF-2.0 | Windows COM (RTF) | Optional |

> **Note**: `pdf2docx` (GPL-3.0) and `PyMuPDF` (AGPL-3.0) are strong copyleft licenses. For closed-source projects, avoid installing these dependencies. Core functionality (.docx/.doc/.md input) does not depend on any strong copyleft library.