Skip to content
Back to search

paper_format_agent

DOCX formatter for academic papers with a content-fingerprint guard: proves your text is never altered, only the formatting. Also installable as an agent skill. 毕业论文、学位论文的 Word 自动排版:按格式要求改字体字号、行距、缩进、标题和题注;指纹校验保证只改格式、不动正文,也可做格式检查评分。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zxyasfas--paper-format-agent/badge.svg)](/listings/zxyasfas--paper-format-agent)

HTML

<a href="/listings/zxyasfas--paper-format-agent"><img src="/api/listings/zxyasfas--paper-format-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

There is also a GUI (`python run_gui.py`), a batch mode, and JSON template packs for Chinese thesis, journal and IEEE-style formats. See [docs/USAGE.md](docs/USAGE.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 82 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: paper-format-agent
  3. description: Use this skill when a user needs to inspect, score, repair, or regression-test academic paper formatting in DOCX files, especially thesis, journal, or conference documents with a separate format specification. The skill guides Codex through local-first document handling, rule extraction, formatting repair, report review, and contribution-safe validation.
  4. ---
  5. # Paper Format Agent
  6. Use this skill for local-first academic document formatting work. It is designed for `.docx` papers and a separate format specification in `.docx`, `.doc`, or `.txt`.
  7. ## Safety Defaults
  8. - Never upload private papers or format guides to external services unless the user explicitly asks for it.
  9. - Treat student papers, manuscripts, reviewer comments, and school templates as sensitive data.
  10. - Do not change academic content unless the user explicitly opts in. Default to formatting-only changes.
  11. - Keep reports and generated documents in a user-provided output directory.
  12. ## Standard Workflow
  13. 1. Confirm the input files:
  14. - `--format-file`: format guide or template text.
  15. - `--paper-file`: source paper, currently `.docx`.
  16. - `--out-dir`: output directory for reports and generated documents.
  17. 2. Run the CLI in formatting-only mode:
  18. ```bash
  19. python -m paper_format_agent.cli \
  20. --format-file "format_guide.docx" \
  21. --paper-file "paper.docx" \
  22. --out-dir "./output" \
  23. --engine auto \
  24. --strict-required-sections
  25. ```
  26. 3. Inspect generated artifacts:
  27. - `formatted_paper_v3.docx`: repaired document.
  28. - `format_rules.json`: extracted rules.
  29. - `format_report.json`: machine-readable score and checks.
  30. - `format_report.html`: human-readable report.
  31. - `modify_log.json`: formatting operations.
  32. - `engine_report.json`: post-processing engine result.
  33. 4. Check the content guard fields in `format_report.json`:
  34. - `content_changed` should normally be `false`.
  35. - `content_guard_enforced` should normally be `true`.
  36. 5. If a rule is wrong, update rule extraction or scoring logic and add a minimal test case.
  37. ## Validation
  38. Run these before handing work back:
  39. ```bash
  40. python tools/validate_skill.py
  41. python -m unittest discover -s tests -p "test_*.py"
  42. python tools/compile_check.py
  43. python tools/release_audit.py
  44. ```
  45. ## When Adding Template Support
  46. - Add the smallest representative rule text needed to reproduce the behavior.
  47. - Prefer deterministic rule extraction over LLM-only interpretation.
  48. - Add tests for extracted margins, font size, line spacing, required sections, headings, captions, or references.
  49. - Do not commit real student documents. Use synthetic text or anonymized fixtures.
  50. ## When Reviewing Output
  51. Read `format_report.json` first, then inspect `format_report.html` if the user needs a human-readable summary. Prioritize issues in this order:
  52. 1. Content changed unexpectedly.
  53. 2. Required sections or headings were misclassified.
  54. 3. Page setup, margins, fonts, or line spacing are wrong.
  55. 4. Captions, references, tables, or numbering look wrong.
  56. 5. Report wording or score explanation is unclear.
  57. ## Contribution-Friendly Tasks
  58. Good first PRs usually fit one of these buckets:
  59. - Add a synthetic test for a school, journal, or conference formatting rule.
  60. - Improve a rule extractor with a narrowly scoped regex or parser.
  61. - Improve report clarity without changing scoring semantics.
  62. - Add a regression case to `docs/regression_manifest.sample.json`.
  63. - Improve this skill workflow or `agents/openai.yaml` metadata.
README.md · README · 110 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <!-- mcp-name: io.github.zxyasfas/paper-format-agent -->
  2. # Paper Format Agent
  3. [中文说明](README.zh-CN.md) | English
  4. ![CI](https://github.com/zxyasfas/paper_format_agent/actions/workflows/ci.yml/badge.svg)
  5. ![Python](https://img.shields.io/badge/python-3.9%2B-3776AB)
  6. ![License](https://img.shields.io/badge/license-MIT-lightgrey)
  7. A local DOCX formatter for theses and papers.
  8. It changes fonts, spacing, indents, headings and captions to match a format
  9. guide. It does not rewrite the paper. Before saving, it compares a fingerprint
  10. of the body and table text from before and after the run. If the text changed,
  11. it aborts instead of writing the formatted file.
  12. Everything runs on your machine. Nothing is uploaded.
  13. ## the content check
  14. Report fields from a real run (`--engine python`):
  15. ```json
  16. {
  17. "content_fingerprint_before": "793e6533fd670418141d11fdcf014be19750408129ecff8b1b78a2641a3786db",
  18. "content_fingerprint_after": "793e6533fd670418141d11fdcf014be19750408129ecff8b1b78a2641a3786db",
  19. "content_changed": false,
  20. "content_guard_enforced": true
  21. }
  22. ```
  23. The two hashes should match. If they don't, the formatter exits with
  24. `content guard failed` and the formatted DOCX is not written.
  25. What the check covers: body paragraphs and tables, with whitespace and stray
  26. bullet characters normalized before comparing. Headers and footers are out of
  27. scope because the formatter sets those on purpose. Use `--engine python` when
  28. the fingerprint must cover the final saved DOCX; the other engines run a local
  29. post-processor after the check, e.g. to refresh the table of contents.
  30. To watch the guard trip, run `python tools/demo_content_guard.py`. It formats
  31. a synthetic paper, then repeats the run with the styling step patched to edit
  32. one sentence of the in-memory document. The second run aborts without writing
  33. the DOCX.
  34. [docs/BENCHMARK.md](docs/BENCHMARK.md) tracks which authored strings survive
  35. a run in small synthetic fixtures, and lists the known gaps.
  36. ## install and run
  37. ```bash
  38. pip install -r requirements.txt
  39. python -m paper_format_agent.cli \
  40. --format-file "format_guide.docx" \
  41. --paper-file "paper.docx" \
  42. --out-dir "./output" \
  43. --engine python
  44. ```
  45. There is also a GUI (`python run_gui.py`), a batch mode, and JSON template
  46. packs for Chinese thesis, journal and IEEE-style formats. See
  47. [docs/USAGE.md](docs/USAGE.md).
  48. ## limits
  49. Early project. Ordinary paragraphs, headings and tables work better than
  50. equations, footnotes and complex layouts. With `--strict-required-sections`,
  51. checks may include `char_below_min` or `blank_page_risk`. Do not use it as the
  52. only check before a real submission. Keep your original file.
  53. Reference-list formatting is out of scope here: that part is mechanical
  54. rules, so it lives in a separate tool,
  55. [gbt7714_check](https://github.com/zxyasfas/gbt7714_check), which lints
  56. reference entries against GB/T 7714.
  57. ## why I made this
  58. I did not want to upload an unfinished thesis to a formatting website, and I
  59. wanted a way to check that formatting did not touch the text. So the default
  60. engine runs locally and refuses to save if the text changed.
  61. ## agents
  62. The repo doubles as an installable agent skill ([SKILL.md](SKILL.md)), and the
  63. same pipeline is available as an optional MCP server (Python 3.10+):
  64. ```bash
  65. pip install "paper-format-agent[mcp]"
  66. paper-format-agent-mcp
  67. ```
  68. Tools: `format_paper`, `extract_format_rules`, `score_paper`. Client config in
  69. [docs/MCP.md](docs/MCP.md).
  70. ## contributing
  71. Small PRs are welcome. Adding a synthetic test for a school or journal
  72. formatting rule is a good place to start:
  73. [docs/CONTRIBUTOR_TASKS.md](docs/CONTRIBUTOR_TASKS.md),
  74. [CONTRIBUTING.md](CONTRIBUTING.md). Notes on the pipeline are in
  75. [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
  76. Do not commit real papers, private school templates, reviewer comments, API
  77. keys or generated output. Synthetic fixtures only.
  78. ## license
  79. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.