paper-format-agent

论文格式 Agent

中文说明 | English

用于论文和学术文章的本地 DOCX 格式整理工具。

它会调整字体、间距、缩进、标题和题注，使其符合格式指南。它不会改写论文。保存前，它会比较运行前后的正文和表格文本指纹。如果文本发生变化，它会中止，而不是写入格式整理后的文件。

所有操作都在你的设备上运行。不会上传任何内容。

内容检查

真实运行（--engine python）的报告字段：

{
  "content_fingerprint_before": "793e6533fd670418141d11fdcf014be19750408129ecff8b1b78a2641a3786db",
  "content_fingerprint_after":  "793e6533fd670418141d11fdcf014be19750408129ecff8b1b78a2641a3786db",
  "content_changed": false,
  "content_guard_enforced": true
}

两个哈希值应当一致。如果不一致，格式整理工具会退出并显示 content guard failed，且不会写入格式整理后的 DOCX。

检查范围：正文段落和表格；比较前会规范空白字符和多余的项目符号。页眉和页脚不在检查范围内，因为格式整理工具会有意设置它们。如果指纹必须涵盖最终保存的 DOCX，请使用 --engine python；其他引擎会在检查后运行本地后处理程序，例如刷新目录。

要观察保护机制触发的过程，请运行 python tools/demo_content_guard.py。它会格式整理一篇合成论文，然后再次运行，并将样式处理步骤修改为编辑内存文档中的一个句子。第二次运行会中止，且不会写入 DOCX。

docs/BENCHMARK.md 记录了小型合成样例中运行后仍保留的原始字符串，并列出了已知缺口。

安装和运行

pip install -r requirements.txt

python -m paper_format_agent.cli \
  --format-file "format_guide.docx" \
  --paper-file "paper.docx" \
  --out-dir "./output" \
  --engine python

此外还提供 GUI（python run_gui.py）、批处理模式，以及适用于中文学位论文、期刊和 IEEE 风格格式的 JSON 模板包。请参阅 docs/USAGE.md。

局限

这是一个早期项目。普通段落、标题和表格的处理效果好于公式、脚注和复杂版式。使用 --strict-required-sections 时，检查结果可能包括 char_below_min 或 blank_page_risk。正式提交前，不要只依赖它进行检查。请保留原始文件。

本项目不负责格式化参考文献列表：这部分属于机械规则，因此由单独的工具 gbt7714_check 负责，它会根据 GB/T 7714 检查参考文献条目。

制作初衷

我不想把未完成的论文上传到格式整理网站，也想要一种方法来确认格式整理没有改动文本。因此，默认引擎会在本地运行，并在文本发生变化时拒绝保存。

Agent

此代码库也可作为可安装的 Agent 技能（SKILL.md），同一条处理流水线还可作为可选的 MCP 服务使用（Python 3.10+）：

pip install "paper-format-agent[mcp]"
paper-format-agent-mcp

工具：format_paper、extract_format_rules、score_paper。客户端配置见 docs/MCP.md。

参与贡献

欢迎提交小型 PR。为学校或期刊格式规则添加合成测试，是很好的起点： docs/CONTRIBUTOR_TASKS.md， CONTRIBUTING.md。流水线说明见 docs/ARCHITECTURE.md。

请勿提交真实论文、学校的私有模板、审稿意见、API 密钥或生成的输出文件。仅使用合成样例。

许可证

MIT。请参阅 LICENSE。