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.
Badge for your README
Markdown
[](/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
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)
- ---
- name: paper-format-agent
- 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.
- ---
- # Paper Format Agent
- 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`.
- ## Safety Defaults
- - Never upload private papers or format guides to external services unless the user explicitly asks for it.
- - Treat student papers, manuscripts, reviewer comments, and school templates as sensitive data.
- - Do not change academic content unless the user explicitly opts in. Default to formatting-only changes.
- - Keep reports and generated documents in a user-provided output directory.
- ## Standard Workflow
- 1. Confirm the input files:
- - `--format-file`: format guide or template text.
- - `--paper-file`: source paper, currently `.docx`.
- - `--out-dir`: output directory for reports and generated documents.
- 2. Run the CLI in formatting-only mode:
- ```bash
- python -m paper_format_agent.cli \
- --format-file "format_guide.docx" \
- --paper-file "paper.docx" \
- --out-dir "./output" \
- --engine auto \
- --strict-required-sections
- ```
- 3. Inspect generated artifacts:
- - `formatted_paper_v3.docx`: repaired document.
- - `format_rules.json`: extracted rules.
- - `format_report.json`: machine-readable score and checks.
- - `format_report.html`: human-readable report.
- - `modify_log.json`: formatting operations.
- - `engine_report.json`: post-processing engine result.
- 4. Check the content guard fields in `format_report.json`:
- - `content_changed` should normally be `false`.
- - `content_guard_enforced` should normally be `true`.
- 5. If a rule is wrong, update rule extraction or scoring logic and add a minimal test case.
- ## Validation
- Run these before handing work back:
- ```bash
- python tools/validate_skill.py
- python -m unittest discover -s tests -p "test_*.py"
- python tools/compile_check.py
- python tools/release_audit.py
- ```
- ## When Adding Template Support
- - Add the smallest representative rule text needed to reproduce the behavior.
- - Prefer deterministic rule extraction over LLM-only interpretation.
- - Add tests for extracted margins, font size, line spacing, required sections, headings, captions, or references.
- - Do not commit real student documents. Use synthetic text or anonymized fixtures.
- ## When Reviewing Output
- Read `format_report.json` first, then inspect `format_report.html` if the user needs a human-readable summary. Prioritize issues in this order:
- 1. Content changed unexpectedly.
- 2. Required sections or headings were misclassified.
- 3. Page setup, margins, fonts, or line spacing are wrong.
- 4. Captions, references, tables, or numbering look wrong.
- 5. Report wording or score explanation is unclear.
- ## Contribution-Friendly Tasks
- Good first PRs usually fit one of these buckets:
- - Add a synthetic test for a school, journal, or conference formatting rule.
- - Improve a rule extractor with a narrowly scoped regex or parser.
- - Improve report clarity without changing scoring semantics.
- - Add a regression case to `docs/regression_manifest.sample.json`.
- - 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)
- <!-- mcp-name: io.github.zxyasfas/paper-format-agent -->
- # Paper Format Agent
- [中文说明](README.zh-CN.md) | English
- 
- 
- 
- A local DOCX formatter for theses and papers.
- It changes fonts, spacing, indents, headings and captions to match a format
- guide. It does not rewrite the paper. Before saving, it compares a fingerprint
- of the body and table text from before and after the run. If the text changed,
- it aborts instead of writing the formatted file.
- Everything runs on your machine. Nothing is uploaded.
- ## the content check
- Report fields from a real run (`--engine python`):
- ```json
- {
- "content_fingerprint_before": "793e6533fd670418141d11fdcf014be19750408129ecff8b1b78a2641a3786db",
- "content_fingerprint_after": "793e6533fd670418141d11fdcf014be19750408129ecff8b1b78a2641a3786db",
- "content_changed": false,
- "content_guard_enforced": true
- }
- ```
- The two hashes should match. If they don't, the formatter exits with
- `content guard failed` and the formatted DOCX is not written.
- What the check covers: body paragraphs and tables, with whitespace and stray
- bullet characters normalized before comparing. Headers and footers are out of
- scope because the formatter sets those on purpose. Use `--engine python` when
- the fingerprint must cover the final saved DOCX; the other engines run a local
- post-processor after the check, e.g. to refresh the table of contents.
- To watch the guard trip, run `python tools/demo_content_guard.py`. It formats
- a synthetic paper, then repeats the run with the styling step patched to edit
- one sentence of the in-memory document. The second run aborts without writing
- the DOCX.
- [docs/BENCHMARK.md](docs/BENCHMARK.md) tracks which authored strings survive
- a run in small synthetic fixtures, and lists the known gaps.
- ## install and run
- ```bash
- 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).
- ## limits
- Early project. Ordinary paragraphs, headings and tables work better than
- equations, footnotes and complex layouts. With `--strict-required-sections`,
- checks may include `char_below_min` or `blank_page_risk`. Do not use it as the
- only check before a real submission. Keep your original file.
- Reference-list formatting is out of scope here: that part is mechanical
- rules, so it lives in a separate tool,
- [gbt7714_check](https://github.com/zxyasfas/gbt7714_check), which lints
- reference entries against GB/T 7714.
- ## why I made this
- I did not want to upload an unfinished thesis to a formatting website, and I
- wanted a way to check that formatting did not touch the text. So the default
- engine runs locally and refuses to save if the text changed.
- ## agents
- The repo doubles as an installable agent skill ([SKILL.md](SKILL.md)), and the
- same pipeline is available as an optional MCP server (Python 3.10+):
- ```bash
- pip install "paper-format-agent[mcp]"
- paper-format-agent-mcp
- ```
- Tools: `format_paper`, `extract_format_rules`, `score_paper`. Client config in
- [docs/MCP.md](docs/MCP.md).
- ## contributing
- Small PRs are welcome. Adding a synthetic test for a school or journal
- formatting rule is a good place to start:
- [docs/CONTRIBUTOR_TASKS.md](docs/CONTRIBUTOR_TASKS.md),
- [CONTRIBUTING.md](CONTRIBUTING.md). Notes on the pipeline are in
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
- Do not commit real papers, private school templates, reviewer comments, API
- keys or generated output. Synthetic fixtures only.
- ## license
- MIT. See [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.