gongwen-gbt9704-skill: A GB/T 9704-2012 DOCX Formatter for Chinese Official Documents

What gongwen-gbt9704-skill actually solves

Many AI tools will set headings to 黑体 and body text to 仿宋 and call the result a 公文. The README states this is exactly the failure mode the project targets: the differences that matter are page margins, the 版心, heading levels, the document number, page numbers, attachments and the 版记, and those are the parts that get lost when a model rewrites a file. The author's own account in the README describes reading Word files in and writing Word files out while the original heading hierarchy, spacing before and after paragraphs, indentation and footers did not survive the round trip.

The intended user is narrow. It is someone in a 事业单位 or 国企, or anyone else producing Chinese formal material where a few millimetres or a missing page-number rule blocks the document from moving forward. The README notes that GB/T 9704-2012 applies to documents issued by party and government organs, and that other organs and units may refer to it. If your output is a blog post or an internal note in English, this project has nothing to offer you.

How the generator and verifier split the work

The repository has two scripts that matter: scripts/generate_gongwen_docx.mjs builds the DOCX from a Markdown input, and scripts/verify_gongwen_docx.mjs inspects the result against a profile. That separation is the most useful design decision in the project, because it means the layout claims are checkable rather than asserted. The verifier checks what the generator can promise; the README points to references/gbt9704-audit-matrix.md for the per-clause record of what is generated automatically, what is structurally validated, and what still requires a human.

Format selection is explicit. Ordinary reports default to ordinary and do not pick up a red header just because an organisation name is present. Formal issuance requires formal, and the default there is preprinted letterhead paper: the first page leaves the area where the printed emblem and red line already sit, and the DOCX does not redraw them. Only formal --letterhead digital draws the letterhead elements into the file. The README also describes a --letterhead-reserve-mm value, default 72, measured from the top edge of the paper to the start of the preprinted emblem area, which the generator then follows with two 28-pound blank lines before placing the variable document number, and two more blank lines below the red line before the title.

Special branches exist for letter, command, minutes and horizontal-table, and joint issuance uses --joint-org with the host organ first. Attachments that cannot be bound with the body use --attachment-detached, which adds the document number and attachment sequence on the first line. The 版记, when there is a copy list or printing information, is anchored to the bottom of the 版心 on the last page.

Installing the Skill across editors and running a first document

The project uses a SKILL.md directory structure and the README lists Codex, Claude Code, OpenCode, Trae Code, Trae CLI, Kimi Code CLI, Kimi Code, TraeWork, WorkBuddy and ZCode as supported. On macOS and Linux the installer links the same source directory into each platform's user-level skill directory:

scripts/install.sh --all

On Windows the installer defaults to copying rather than linking, because of symbolic-link permission issues:

.\scripts\install.ps1 -All

Two platforms take an import package instead of the installer. TraeWork uses dist/traework-gongwen-skill.zip, and Tencent WorkBuddy takes dist/workbuddy-gongwen-skill-v2.0.0.zip, which the README says places SKILL.md at the ZIP root, uses first-level scripts/, references/ and assets/ directories, and is about 1.2 MB against a 3 MB platform limit.

A first real run is a generate-then-verify pair. The README gives this ordinary example, which writes a DOCX and then checks it against the ordinary profile:

node scripts/generate_gongwen_docx.mjs --input tests/fixture.md --output /tmp/gongwen.docx --format ordinary --title "公文格式回归测试"
node scripts/verify_gongwen_docx.mjs --input /tmp/gongwen.docx --profile ordinary

For formal issuance the format must be stated, and the preprinted variant adds the organisation, document number and reserve height:

node scripts/generate_gongwen_docx.mjs --input tests/fixture.md --output /tmp/formal.docx --format formal --letterhead preprinted --letterhead-reserve-mm 72 --org "示例单位文件" --doc-no "示例发〔2026〕1号" --title "公文格式回归测试"
node scripts/verify_gongwen_docx.mjs --input /tmp/formal.docx --profile formal --letterhead preprinted

After opening the file, the README says Word or WPS can build and update a table of contents through 引用 then 目录 against 标题1 to 标题4, with the fourth level shown or hidden in the table-of-contents settings. The repository also ships tests/run_tests.sh, which the README describes as covering centred and odd/even page-number generation, DOCX package structure and PDF conversion.

Font substitution is the failure mode to plan for

The generator does not ship fonts. The README states that when 小标宋体 or 仿宋体 are missing, the generator prints an explicit warning in the terminal and writes a substitute font into the DOCX. If you need the run to stop instead of substituting, --require-standard-fonts is the flag. This is the single most likely way for a document to look correct on the machine that generated it and wrong on the machine that prints it, and the README's own account of the project's origin describes exactly that class of problem: WPS and Word do not always agree on font naming, and some environments recognise the Chinese font name while others recognise the English one, so size, line spacing and line breaks can shift between machines.

There is a second boundary around the document number. The README states that the formal layout rejects a document number that clearly does not follow the year, hexagonal-bracket, sequence-number and 号 rules. That is a guard, not a validator for every local convention, and it will not tell you whether the issuing authority is correct.

The README is explicit that the Skill does not judge whether a file may be made public. It handles conversion and layout only. If your decision is whether a document can enter a given processing environment, this project does not answer it, and the README instead directs the reader to their organisation's information-security, classification, secrecy and authorisation requirements, and notes that a locally or intranet-deployed model can host the Skill with the deploying unit handling access control, storage, logs, transmission and output-file management.

Where CEB ends and this project begins

The companion project is CEB, at github.com/mizzlelover/CEB, and the README describes the division of labour plainly: CEB converts already-verified Founder CEB files into PDF, Markdown and TXT, while gongwen-gbt9704-skill turns Chinese formal material into GB/T 9704-2012 DOCX. Chained, they form a read, organise, deliver workflow. The difference in approach is a difference in direction. CEB is an extraction tool: it takes a legacy binary format and produces readable output. This project is a generation tool: it takes Markdown and produces a layout-constrained DOCX. If your problem is that your source material is locked in Founder files, CEB is the piece you need, and the formatter is downstream of it. If your source is already text and your problem is presentation, you can use this project alone.

The README notes that the two are separate repositories and separate Skills, so adopting one does not pull in the other. The homepage field on the repository points at the CEB repository rather than a documentation site, which is worth knowing before you go looking for one.

Maintenance, licence and what the repository does not document

The repository is not archived, and its last push was on 2026-09-13, four days before this article's reference point. That is recent enough that the code is moving, but the README's 2.0 update section is the more useful signal for adopters: it describes re-verifying red-header scenarios, first-page reservation, title spacing under the red line, Word and WPS heading styles, table-of-contents references, special formats and cross-platform installation, and states that 18 DOCX files, 37 PNG pages and header-coordinate measurements were completed. The repository keeps references/gbt9704-visual-audit.md and references/gbt9704-screenshot-evidence.md, the latter described as binding each clause of GB/T 9704-2012 to an actual screenshot and stating which items the screenshots cannot prove. That last file is the honest part of the documentation and the first thing to read if you are deciding how much to trust the generator.

The licence is MIT. In practical terms that permits commercial and internal use, modification and redistribution provided the copyright notice and permission notice are retained, and it comes with no warranty. Nothing here is legal advice, and the GB/T 9704-2012 standard itself is a separate document from the National Standards Information Public Service Platform, not part of this repository.

Upgrade cost is mostly compatibility drift, not migration. The installer links one source directory into each platform's user-level skill directory, so a pull updates every editor at once on macOS and Linux, while Windows copies and needs the installer re-run. The README does not document a rollback path for the installer, and it does not document a versioned changelog beyond the 2.0 update articles under marketing/. If you pin a version, pin it by commit.

Editorial conclusion

Adopt it if you already produce Chinese formal material in Word or WPS and you want the page, font, heading, document-number and page-number rules written into the file instead of re-typed each time; the verifier is what makes that promise checkable. Do not adopt it if you need the tool to decide whether a document may leave your network, or if you expect a fully drawn electronic letterhead by default: that requires --letterhead digital. Before relying on it, run the ordinary generate-and-verify pair on your own input, then check the generated DOCX on the machine that will print it, because the README states the generator warns and substitutes fonts when 小标宋体 or 仿宋体 are missing.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mizzlelover/gongwen-gbt9704-skill on GitHub
4. Project website
5. README