wordformat

name	wordformat
description	论文格式自动化处理工具。在处理 Word 论文文档格式校验、格式修正、文档结构识别场景时激活，具备使用 AI 模型智能识别文档结构并根据 YAML 配置文件自动校验或修正论文格式的专业能力。 Use when this capability is needed.
metadata	{"author":"AfishInLake"}

WordFormat - 论文格式自动化处理工具

安装

pip install wordformat -i https://pypi.tuna.tsinghua.edu.cn/simple  # 国内
pip install wordformat  # 海外

验证：wordf --help

功能速查

CLI 命令

命令	功能	输入	输出
wordf config	查看所有可配置字段及默认值	无	终端输出
wordf config -o config.yaml	输出完整配置模板	无	config.yaml
wordf gj	AI 识别文档结构	.docx + config.yaml	output/xxx.json
wordf tree	查看结构树	.json	终端树形图
wordf cf	检查格式（批注）	.docx + config.yaml + .json	--标注版.docx
wordf af	修正格式（直接改）	.docx + config.yaml + .json	--修改版.docx
wordf startapi	Web 界面	无	http://127.0.0.1:8000

辅助脚本

脚本	功能
setup_config.py	验证/保存 YAML 配置
validate_json.py	校验 JSON category，显示统计

JSON 字段（wordf gj 输出，可手动编辑）

字段	说明
category	段落类型（16种），改这里修正分类
replace	可选，填入新文本直接替换段落内容
fingerprint	段落指纹（不要改）
score	AI 置信度

格式检查范围

段落（对齐/间距/行距/缩进）、字符（字体/字号/颜色/粗斜体/下划线）、标题自动编号、题注编号校验、关键词数量、表格内容。

不支持

页眉页脚、目录生成、封面排版、图片尺寸、Word 域代码。需提前告知用户手动处理。

---

工作流程

两个独立任务，先任务一再任务二。每个任务完成后必须将产物复制到用户工作目录。

---

任务一：准备配置文件

🚨 用户已提供 .yaml 配置 → 直接跳到步骤 1.2 验证，禁止新建。 🚨 用户说"用上次的配置"/"和上次一样" → 复用已有配置，禁止新建。

步骤 1.0 查找已有配置

优先级：用户提供的 > 工作目录已有 > 预设库 > 新建

# 扫描工作目录下所有 .yaml 文件
ls *.yaml 2>/dev/null || echo "无 .yaml 文件"

找到文件后逐个验证：

for f in *.yaml; do
  echo "--- 验证: $f ---"
  python ${CLAUDE_SKILL_DIR}/scripts/setup_config.py --validate --config "$f" 2>&1 \
    && echo "✅ 合法" || echo "❌ 非配置文件"
done

找到合法配置 → 询问用户确认，不要新建或覆盖。用户确认后跳到步骤 1.2。

没有 .yaml 文件时尝试预设库：

python ${CLAUDE_SKILL_DIR}/scripts/setup_config.py --list-presets
python ${CLAUDE_SKILL_DIR}/scripts/setup_config.py --use "清华大学_计算机学院_本科" --output config.yaml

预设也找不到时，继续步骤 1.1 新建。

步骤 1.1 新建配置

运行 wordf config 查看所有字段和默认值，wordf config -o config.yaml 生成模板。

先完整读完格式要求文件，再编辑。 编辑原则：只改值、不增减字段、不动 YAML 锚点语法。

步骤 1.2 验证

python ${CLAUDE_SKILL_DIR}/scripts/setup_config.py --validate --config config.yaml

失败则根据提示修正，直到通过。

步骤 1.3 保存预设（首次生成时可选）

python ${CLAUDE_SKILL_DIR}/scripts/setup_config.py --save --config config.yaml --name "XX大学_XX学院_本科"

步骤 1.4 交付

cp config.yaml <用户工作目录>/

询问用户确认配置，提醒页眉页脚、目录等无法自动处理。任务一完成。

---

任务二：执行格式化

前提：有 config.yaml 和 .docx 论文。

步骤 2.1 生成 JSON

wordf gj -d $ARGUMENTS -c config.yaml

记住输出的 JSON 路径（output/论文_xxx.json）。

步骤 2.2 检查结构

wordf tree -f <JSON路径>
wordf tree -f <JSON路径> --confidence  # 看低置信度段落

步骤 2.3 校验并修正 JSON

先读 data/category_reference.md。

python ${CLAUDE_SKILL_DIR}/scripts/validate_json.py --json <JSON路径> --stats --show-all --threshold 0.8

常见修正：

误识别	改为
"摘要" → heading_level_1	abstract_chinese_title
"关键词：..." → body_text	keywords_chinese
"参考文献" → heading_level_1	references_title
摘要标题+正文同一段	abstract_chinese_title_content
目录/封面/页眉页脚	other（跳过格式化）

⚠️ 不修改的 body_text：摘要标题后的正文（自动升级为摘要正文）、参考文献标题后的条目（自动升级为参考文献条目）。

用 replace 修正文本：添加 "replace": "正确文本"，格式化时自动替换。

修正后重新验证确认无误。

步骤 2.4 格式化

wordf cf -d 论文.docx -c config.yaml -f <JSON路径>  # 检查（批注，不改原文）
wordf af -d 论文.docx -c config.yaml -f <JSON路径>  # 修正（直接改）

numbering.enabled: true 时，af 模式会自动清除手动编号并应用 Word 自动编号。

步骤 2.5 交付

cp output/论文--标注版.docx <用户工作目录>/   # cf 模式
cp output/论文--修改版.docx <用户工作目录>/   # af 模式

询问用户检查结果，提醒手动补充。任务二完成。

---

Python 调用

from wordformat.set_tag import set_tag_main
from wordformat.set_style import auto_format_thesis_document

data = set_tag_main(docx_path="论文.docx", configpath="config.yaml")
auto_format_thesis_document(jsonpath=data, docxpath="论文.docx",
                            configpath="config.yaml", savepath="output/", check=True)

注意事项

• 仅 .docx，Python ≥ 3.10
• AI 分类非 100% 准确，务必检查 JSON
• 产物必须复制到用户工作目录
• 每个任务完成后询问用户确认

---

Source: AfishInLake/WordFormat — distributed by TomeVault.