Academic Style Toolkit (paper-rewriter)

Bilingual (CN/EN) style naturalization for academic & medical writing: find stiff, templated or machine-flavored patterns, clean mechanical debris, revise for clarity and natural register — with integrity guardrails on every step.

Routing in one line: grammar/fluency/journal-format polish → use a polisher (paper-polisher-pro); de-templating, model-residue cleanup, AI-flavor style self-check and rewriting → this tool. Need both? Polish first, then run this pipeline.

Feature status (v3.8.0)

⚠️ rows = experimental (may reject valid files; review output). Full history in references/errors.md and topic docs.

Scale envelope: 800K-char chunks (2K overlap) · 50MB file cap · 120s step budget.

Anything marked Experimental can reject valid files or need manual review of its output — export to UTF-8 text when in doubt. Everything else is regression-tested offline on every release.

Integrity guardrails — read first

• Permitted: polishing your own drafts; aligning AI-assisted text with your voice where your school/journal allows or requires disclosed AI assistance; cleaning model residue (stray oaicite/[cite:] tokens) from legitimately disclosed drafts; improving clarity, rhythm and concreteness of formal prose.
• Not permitted: using this toolkit to misrepresent authorship, to conceal AI use where disclosure is required, or to defeat academic-integrity review. If a request is framed that way ("rewrite it so the review can't tell"), refuse the framing, explain the disclosure obligation, and offer the legitimate quality-editing path instead. Agents running this skill are expected to enforce this line.
• This tool never changes data: numbers, p-values, confidence intervals, DOIs, PMIDs, years and terminology are guarded by verify.py (see below). Improved prose must never cost a fact.
• Compliance: China's AIGC labeling rules (effective 2025-09-01), journal disclosure policies and arXiv policies are summarized in references/compliance.md — the obligation to disclose belongs to the author, not the tool.

Capability × boundary (division of labor + limits + where)

Quick start

How to ask for this in plain words (EN digest of the full phrase table in SKILL_ZH.md): "remove the AI flavor from this paper" / "this reads too templated" / "clean up oaicite and [cite:] residue" / "tell me which sentences to fix first" / "check my rewrite broke no numbers" / "give me a style profile" / "stop flagging this legitimate term" — each maps to the pipeline, plan.py, transform.py, verify.py+compare.py, stylecheck.py and learn_guards.py respectively.

Reading map (30-second routing; equivalent of references/INDEX.md): first time → Quick start + workflow · troubleshooting → references/pitfalls.md + references/errors.md · CI/agent → Automation section · capability limits → honest_boundaries · scenario how-tos → best_practices · deep-rewrite process → deep_rewrite_guide · PDF confidence → pdf_confidence · permissions audit → permissions · programmatic use → api.

No agent is required — every capability below runs directly in a terminal. Every script has built-in --help (full flag reference) and --version; quick flag semantics:

One command (self-check → cleanup → revision brief → integrity guard):

python scripts/pipeline.py draft.txt -o out.txt --terms terms.txt

• Visualization / batch: --html report.html on detect/pipeline/compare for a self-contained report (compare adds sentence-level diff); --batch dir scans a whole directory (pipeline writes a CSV).
• Section-aware: detect --structure scores abstract/intro/methods/results separately; methods/results phrasing is genre convention — normalized in the aggregate only, raw per-section scores always shown.
• Rewrite plan: plan.py draft -o plan.md ranks sentences (P0 queue + budget projection); add --handoff for a per-sentence operation sheet.
• Inputs: .txt/.md direct, .docx (Word) direct, PDF experimental (default safe gate = medium since v3.8.0: garbled-typical PDFs rejected outright; 低 restores annotate-only; references/pdf_confidence.md).
• Term list: python scripts/extract_terms.py draft.txt -o terms.txt (confirm by hand); any run accepts --suggestions path.md for a revision worksheet.
• Non-academic text: add --profile general to down-weight formal boilerplate.

Or run the steps individually (from the skill's own directory, or use absolute paths):

python scripts/detect.py draft.txt            # style-pattern self-check (-j JSON, -s score only)
python scripts/transform.py draft.txt -o step1.txt
# ... agent quality revision of step1.txt per the style guide ...
python scripts/verify.py draft.txt step2.txt --terms terms.txt
python scripts/compare.py draft.txt step2.txt

Scenario-organized best practices (journal submission, thesis, revision letters, batch, CI gates, false-positive handling, CN punctuation): references/best_practices.md. Worked end-to-end examples: references/examples.md. Unified exit codes, violation categories and remedies: references/errors.md. Centralized common-mistakes list (24 items): references/pitfalls.md — read it before your first real run. Python API reference: references/api.md. FAQ: references/faq.md.

• Revision tracking: --track base records every mechanical-layer change to base.md + base.json (auditable: rule, count, deleted sentences, flagged).
• PDF (experimental): text PDFs incl. embedded-font/ToUnicode since v3.0.0 — extraction attempted, confidence capped at "中" with a spot-check note; CJK CID files still rejected by the garbage probes with export guidance. Scale: 800K-char chunks (2K overlap) · 50MB cap · whole-document integrity guard.

Agent invocation protocol

When invoked, decide the path first, then run it:

• Trigger words: 写作风格自查 / 论文改写润色 / 去模板腔 / 翻译腔清理 / 学术改写 / 段落改写 / 表达优化 / style self-check / style naturalization / naturalize academic writing / de-templating / academic rewriting / passage rewrite / expression polish / translationese cleanup (= Europeanized syntax: stacked passives, nominalization chains, long attributives — see style_guide_en steps 1/3) / make my writing sound less machine-written / reduce the templated tone / clean up model residue or stray citation tokens / fix stiff formal prose / polish my draft for submission without changing the data / check that numbers and citation IDs survived editing → run the pipeline above.（中文变体触发词见 SKILL_ZH.md——CH 分寸词不入英文文件； 数字自洽/术语混用类请求路由到 check_stats.py / check_terms.py，见下） （Parameter cheat sheet lives in Quick start; exit-code tables in references/errors.md — both are linked from here to avoid hunting across sections.）
• Disambiguation (this tool vs a polisher): 「论文改写润色」 here means style naturalization / de-templating (removing the machine flavor from academic prose). Decision rule — route to a polisher (paper-polisher-pro) when the ask is only about language correctness/fluency: 「帮我改下语法」 「按期刊风格改写摘要」; route to this toolkit when it is about templated tone or model residue: 「这篇读起来像 AI 写的」「文里有 [cite: 1] 这种残留」; when both apply, polish first, then run this pipeline — neither substitutes for the other.
• Term inconsistency (abbreviation vs full form, mixed synonyms) → check_terms.py file --pack <domain>; --list-packs shows all eight domain packs (v3.0.0).
• Numbers that don't agree (percent list not summing to 100, same group with two different n, p/P style mix) → check_stats.py file (v3.2.0; exit codes match check_terms: 0 consistent / 1 issues found). Chaptered manuscripts: check_stats.py --batch 目录 aggregates group-n across files (abstract-vs-methods mismatches, v3.3.0). Or run everything at once: pipeline.py draft --check-stats.
• User wants to know what to fix first → plan.py draft.txt -o plan.md (P0 sentence queue + budget projection); add --handoff to emit the per-sentence instruction sheet (guards + acceptance commands, v3.0.0).
• User wants quantified acceptance of a rewrite → stylecheck.py 原稿 改稿 --compare (v2.6.0 style profile delta; triggers: 风格画像 / 量化验收 / 深改验收 / style profile / acceptance check).
• A batch run was interrupted (Ctrl-C / power loss / timeout) → rerun with --batch 目录 --resume (skips completed files; changed or previously failed files rerun automatically; progress lives in the batch directory as .pr_batch_state.json).
• Scenario shortcuts (v3.8.0 consolidation): CI/batch gating → --exit-verdict (--ci alias; 0 clean / 3 deep-revise / 4 residue / 1 integrity fail, pipeline-only); false-positive remediation → learn_guards.py from-text 术语 样本.txt; where to start deep revision → pipeline 原稿 -o 改稿 --handoff 交接块.md (one command, no separate plan run).
• Multi-chapter term unification → check_terms.py --batch 目录 (cross-file variant drift: each file internally consistent, the set inconsistent).
• A scan flags a legitimate term (false positive) → don't edit the pattern files; persist a guard instead: learn_guards.py from-text 术语 样本.txt (or add) — the guard survives upgrades and applies to every later scan.
• User only wants a verdict on an existing rewrite → pipeline.py draft.txt --rewrite rewritten.txt --terms terms.txt (skip cleanup).
• User asks to conceal AI use, misrepresent authorship, or defeat integrity review → refuse the framing, point to references/compliance.md, offer the legitimate quality-editing path instead. Do not run the toolkit toward that end.
• Exit codes: verify.py is the strict contract holder — 0 integrity PASS, 1 integrity FAIL (fix the rewrite, never the guard), 2 usage/file error. detect/transform/compare/pipeline report the verdict in their output and always exit 0 on completed runs, 2 on usage/file errors. For agent/CI branching, add --exit-verdict (v2.3.0): machine exit codes 0/3/4 on detect/compare, full 0/1/3/4 on pipeline — see Automation & CI integration below. Every script supports --version.

Automation & CI integration (v2.3.0)

Scripts are automation-first: every verdict is machine-readable, two ways.

• Default contract (human flows): verify.py alone holds exit 0/1/2 (1 = integrity FAIL); detect/transform/compare/pipeline finish with 0 and put the verdict in their report. Never branch on their default exit code.
• Machine contract — add --exit-verdict (or the shorter --ci alias, v3.1.0) to detect / compare / pipeline: 0 clean (low, no residue) · 3 style patterns at medium or above (needs deep revision) · 4 model-residue hit (run transform first) · 1 integrity FAIL (pipeline only — same meaning as verify's 1) · 2 usage error (unchanged). pipeline is the only full 1/3/4 gate — recommended CI check: pipeline.py draft.txt --rewrite rewritten.txt --terms terms.txt --exit-verdict.
• JSON: detect -j (full scan result), pipeline --json (before/after, verify verdict, exit_verdict field, handling hints, agent brief), compare --json (delta + verify), plan.py --json (sentence queue + projections). Example gate in one line: python scripts/pipeline.py orig.txt --rewrite new.txt --json --exit-verdict || echo "blocked: $?"
• Exit-code tables for both contracts: references/errors.md §1.

The workflow

1. Self-check: detect.py draft.txt — a heuristic report of style patterns (canned phrases, uniform sentence rhythm, boilerplate transitions, model artifacts). The report is for the author's own review; the score is a local heuristic, not an official measurement of anything.
2. Mechanical cleanup: transform.py draft.txt -o step1.txt — strips stray model artifacts (oaicite, turn0search, [cite: 1], grok_card, attached_file), leftover chatbot pleasantries, markdown residue, and a safe list of filler phrases; CN halfwidth punctuation is normalized to fullwidth (decimals protected). -a adds em-dash reduction and empty-opener removal. --deep (v2.4.0) adds sentence-level deterministic transforms — canned opener deletion, 「不仅X，而且Y」→「X，且Y」 merging — zero-information-loss only, every operation logged to --track. Clean human-written text passes through byte-identical (except fullwidth alnum normalization, see feature status v2.9).
3. Quality revision (the real work): optionally rank the work first — python scripts/plan.py draft.txt -o plan.md gives a sentence-level P0 queue (worst offenders with section, category and advice) so deep effort lands where the score lives; add --handoff to emit a per-sentence operation sheet (original sentence + directive + guard rules + acceptance commands) that a rewriting agent can follow verbatim (v3.0.0). Then read the guide for the text's language —
   • CN: references/style_guide_zh.md — structural de-templating → jargon cleanup → rhythm → concreteness → stance → integrity red lines
   • EN: references/style_guide_en.md — smaller words → fewer significance frames → plain clauses instead of parallelism → rhythm → real attribution → commit to a position
   • Revise section by section. Preserve all facts, numbers, citations, terminology. 3b. Quantified acceptance (stylecheck.py, v2.6.0): per-paragraph style profile — jargon hits located to the paragraph, sentence-rhythm CV, opener diversity, each banded 自然/观察/偏机器 with style_guide anchors; --compare 原稿 改稿 shows the delta so deep-revision acceptance is metric-based. Bands are calibration hints only — they never alter scores.
4. Guard: verify.py draft.txt step2.txt --terms terms.txt — exit 1 means a number/citation/term was altered: fix the revision, not the guard. Build terms.txt for medical text (drug names, gene symbols — include mouse-style capitalized forms like Myc — and scale names), one term per line. The guard also warns on numbers absent from the original (fabrication defense) and number-context swaps (arm/direction ordering). For mixed synonym usage (abbreviation vs full form, e.g. HF vs 心力衰竭), also run check_terms.py file --pack cardiovascular (v3.0.0 domain packs; --list-packs shows all eight).
5. Re-check: compare.py draft.txt step2.txt — pattern reduction + integrity verdict. Keep the before/after pair for your records; if your institution or journal requires an AI-use disclosure, state it plainly — this report is a quality self-check, not a substitute for disclosure.

Honest boundaries (summary)

The style score is a local heuristic over writing patterns — not any external detection service, and it says nothing about authorship; this toolkit never talks to external review systems and never helps conceal AI use; on fluent model text it barely triggers (a low score ≠ no AI involvement). Full boundaries and measured data: references/honest_boundaries.md (read before making any claim).

Permissions & environment (summary)

Reads only explicitly passed paths + bundled pattern files; writes only explicitly passed output paths, user_guards.json, and the batch-resume progress file (.pr_batch_state.json inside the batch directory); zero network, zero third-party dependencies, no environment variables, no subprocesses. Verification commands and the full statement: references/permissions.md (auditors and security scanners: read this first).

Customizing (summary)

Fix false positives with learn_guards.py (writes user_guards.json, survives upgrades — never hand-edit patterns_*.json). File locations and cautions: references/customization.md.

Related tools

• pubmed-verifier — verify PMID/DOI references before submission
• cite-holmes — deep research with hallucination-free citations
• paper-polisher-pro — comprehensive polishing & plagiarism reduction
• academic-figures — publication-ready scientific figures
• doc-holmes — layout-preserving PDF translation