minimax-docx
Professional DOCX document creation, editing, and formatting using OpenXML SDK (.NET). Three pipelines: (A) create new documents from scratch, (B) fill/edit content in existing documents, (C) apply template formatting with XSD validation gate-check. MUST use this skill whenever the user wants to produce, modify, or format a Word document — including when they say "write a report", "draft a proposal", "make a contract", "fill in this form", "reformat to match this template", or any task whose final output is a .docx file. Even if the user doesn't mention "docx" explicitly, if the task implies a printable/formal document, use this skill.
- License 许可
- MIT
- 最近更新
- 2026-09-29
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- minimax-docx
- license
- MIT
- metadata
- { "author": "MiniMaxAI", "sources": [ "ECMA-376 Office Open XML File Formats", "GB/T 9704-2012 Layout Standard for Official Documents", "IEEE / ACM / APA / MLA / Chicago / Turabian Style Guides", "Springer LNCS / Nature / HBR Document Templates" ], "version": "1.0.0", "category": "document-processing" }
- triggers
- [ "Word", "docx", "document", "文档", "Word文档", "报告", "合同", "公文", "排版", "套模板" ]
- description
- Professional DOCX document creation, editing, and formatting using OpenXML SDK (.NET). Three pipelines: (A) create new documents from scratch, (B) fill/edit content in existing documents, (C) apply template formatting with XSD validation gate-check. MUST use this skill whenever the user wants to produce, modify, or format a Word document — including when they say "write a report", "draft a proposal", "make a contract", "fill in this form", "reformat to match this template", or any task whose final output is a .docx file. Even if the user doesn't mention "docx" explicitly, if the task implies a printable/formal document, use this skill.
02 资源文件 74
- 其他.gitignore17 B
- 资产文件assets/styles/academic_styles.xml7.2 KB
- 资产文件assets/styles/corporate_styles.xml8.3 KB
- 资产文件assets/styles/default_styles.xml12.0 KB
- 资产文件assets/xsd/aesthetic-rules.xsd24.6 KB
- 资产文件assets/xsd/business-rules.xsd5.5 KB
- 资产文件assets/xsd/common-types.xsd5.1 KB
- 资产文件assets/xsd/wml-subset.xsd25.1 KB
- 许可证LICENSE1.0 KB
- 参考文档references/cjk_typography.md11.6 KB
- 参考文档references/cjk_university_template_guide.md7.7 KB
- 参考文档references/comments_guide.md6.4 KB
- 参考文档references/design_good_bad_examples.md30.1 KB
- 参考文档references/design_principles.md27.0 KB
- 参考文档references/openxml_element_order.md10.7 KB
- 参考文档references/openxml_encyclopedia_part1.md137.2 KB
- 参考文档references/openxml_encyclopedia_part2.md92.3 KB
- 参考文档references/openxml_encyclopedia_part3.md119.0 KB
- 参考文档references/openxml_namespaces.md5.4 KB
- 参考文档references/openxml_units.md2.3 KB
- 参考文档references/scenario_a_create.md7.7 KB
- 参考文档references/scenario_b_edit_content.md7.8 KB
- 参考文档references/scenario_c_apply_template.md18.0 KB
- 参考文档references/track_changes_guide.md5.2 KB
- 参考文档references/troubleshooting.md18.5 KB
- 参考文档references/typography_guide.md9.9 KB
- 参考文档references/xsd_validation_guide.md4.9 KB
- 脚本scripts/doc_to_docx.sh872 B
- 脚本scripts/docx_preview.sh836 B
- 脚本scripts/dotnet/MiniMaxAIDocx.Cli/MiniMaxAIDocx.Cli.csproj497 B
- 脚本scripts/dotnet/MiniMaxAIDocx.Cli/Program.cs591 B
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Commands/AnalyzeCommand.cs6.0 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Commands/ApplyTemplateCommand.cs12.7 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Commands/CreateCommand.cs14.2 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Commands/DiffCommand.cs6.0 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Commands/EditContentCommand.cs19.3 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Commands/FixOrderCommand.cs4.4 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Commands/MergeRunsCommand.cs4.7 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Commands/ValidateCommand.cs4.1 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/MiniMaxAIDocx.Core.csproj425 B
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/OpenXml/CommentSynchronizer.cs6.3 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/OpenXml/ElementOrder.cs4.1 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/OpenXml/NamespaceConstants.cs3.5 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/OpenXml/RunMerger.cs2.6 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/OpenXml/StyleAnalyzer.cs2.9 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/OpenXml/TrackChangesHelper.cs3.0 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/OpenXml/UnitConverter.cs1.0 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Samples/AestheticRecipeSamples_Batch1.cs37.9 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Samples/AestheticRecipeSamples_Batch2.cs42.4 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Samples/AestheticRecipeSamples_Batch3.cs44.3 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Samples/AestheticRecipeSamples_Batch4.cs47.1 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Samples/AestheticRecipeSamples.cs75.6 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Samples/CharacterFormattingSamples.cs46.1 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Samples/DocumentCreationSamples.cs52.1 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Samples/FieldAndTocSamples.cs26.3 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Samples/FootnoteAndCommentSamples.cs30.1 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Samples/HeaderFooterSamples.cs35.4 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Samples/ImageSamples.cs39.2 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Samples/ListAndNumberingSamples.cs34.3 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Samples/ParagraphFormattingSamples.cs55.5 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Samples/StyleSystemSamples.cs64.0 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Samples/TableSamples.cs50.6 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Samples/TrackChangesSamples.cs26.2 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Typography/CjkHelper.cs1.2 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Typography/FontDefaults.cs898 B
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Typography/PageSizes.cs979 B
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Validation/BusinessRuleValidator.cs9.0 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Validation/GateCheckValidator.cs5.8 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Validation/ValidationResult.cs651 B
- 脚本scripts/dotnet/MiniMaxAIDocx.Core/Validation/XsdValidator.cs2.1 KB
- 脚本scripts/dotnet/MiniMaxAIDocx.slnx153 B
- 脚本scripts/env_check.sh6.9 KB
- 脚本scripts/setup.ps19.9 KB
- 脚本scripts/setup.sh16.1 KB
03 SKILL.md 正文
minimax-docx
Create, edit, and format DOCX documents via CLI tools or direct C# scripts built on OpenXML SDK (.NET).
Setup
First time: bash scripts/setup.sh (or powershell scripts/setup.ps1 on Windows, --minimal to skip optional deps).
First operation in session: scripts/env_check.sh — do not proceed if NOT READY. (Skip on subsequent operations within the same session.)
Quick Start: Direct C# Path
When the task requires structural document manipulation (custom styles, complex tables, multi-section layouts, headers/footers, TOC, images), write C# directly instead of wrestling with CLI limitations. Use this scaffold:
// File: scripts/dotnet/task.csx (or a new .cs in a Console project)
// dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli -- run-script task.csx
#r "nuget: DocumentFormat.OpenXml, 3.2.0"
using DocumentFormat.OpenXml;
using DocumentFormat.OpenXml.Packaging;
using DocumentFormat.OpenXml.Wordprocessing;
using var doc = WordprocessingDocument.Create("output.docx", WordprocessingDocumentType.Document);
var mainPart = doc.AddMainDocumentPart();
mainPart.Document = new Document(new Body());
// --- Your logic here ---
// Read the relevant Samples/*.cs file FIRST for tested patterns.
// See Samples/ table in References section below.
Before writing any C#, read the relevant Samples/*.cs file — they contain compilable, SDK-version-verified patterns. The Samples table in the References section below maps topics to files.
CLI shorthand
All CLI commands below use $CLI as shorthand for:
dotnet run --project scripts/dotnet/MiniMaxAIDocx.Cli --
Pipeline routing
Route by checking: does the user have an input .docx file?
User task
├─ No input file → Pipeline A: CREATE
│ signals: "write", "create", "draft", "generate", "new", "make a report/proposal/memo"
│ → Read references/scenario_a_create.md
│
└─ Has input .docx
├─ Replace/fill/modify content → Pipeline B: FILL-EDIT
│ signals: "fill in", "replace", "update", "change text", "add section", "edit"
│ → Read references/scenario_b_edit_content.md
│
└─ Reformat/apply style/template → Pipeline C: FORMAT-APPLY
signals: "reformat", "apply template", "restyle", "match this format", "套模板", "排版"
├─ Template is pure style (no content) → C-1: OVERLAY (apply styles to source)
└─ Template has structure (cover/TOC/example sections) → C-2: BASE-REPLACE
(use template as base, replace example content with user content)
→ Read references/scenario_c_apply_template.md
If the request spans multiple pipelines, run them sequentially (e.g., Create then Format-Apply).
Pre-processing
Convert .doc → .docx if needed: scripts/doc_to_docx.sh input.doc output_dir/
Preview before editing (avoids reading raw XML): scripts/docx_preview.sh document.docx
Analyze structure for editing scenarios: $CLI analyze --input document.docx
Scenario A: Create
Read references/scenario_a_create.md, references/typography_guide.md, and references/design_principles.md first. Pick an aesthetic recipe from Samples/AestheticRecipeSamples.cs that matches the document type — do not invent formatting values. For CJK, also read references/cjk_typography.md.
Choose your path:
- Simple (plain text, minimal formatting): use CLI —
$CLI create --type report --output out.docx --config content.json - Structural (custom styles, multi-section, TOC, images, complex tables): write C# directly. Read the relevant
Samples/*.csfirst.
CLI options: --type (report|letter|memo|academic), --title, --author, --page-size (letter|a4|legal|a3), --margins (standard|narrow|wide), --header, --footer, --page-numbers, --toc, --content-json.
Then run the validation pipeline (below).
Scenario B: Edit / Fill
Read references/scenario_b_edit_content.md first. Preview → analyze → edit → validate.
Choose your path:
- Simple (text replacement, placeholder fill): use CLI subcommands.
- Structural (add/reorganize sections, modify styles, manipulate tables, insert images): write C# directly. Read
references/openxml_element_order.mdand the relevantSamples/*.cs.
Available CLI edit subcommands:
replace-text --find "X" --replace "Y"fill-placeholders --data '{"key":"value"}'fill-table --data table.jsoninsert-section,remove-section,update-header-footer
$CLI edit replace-text --input in.docx --output out.docx --find "OLD" --replace "NEW"
$CLI edit fill-placeholders --input in.docx --output out.docx --data '{"name":"John"}'
Then run the validation pipeline. Also run diff to verify minimal changes:
$CLI diff --before in.docx --after out.docx
Scenario C: Apply Template
Read references/scenario_c_apply_template.md first. Preview and analyze both source and template.
$CLI apply-template --input source.docx --template template.docx --output out.docx
For complex template operations (multi-template merge, per-section headers/footers, style merging), write C# directly — see Critical Rules below for required patterns.
Run the validation pipeline, then the hard gate-check:
$CLI validate --input out.docx --gate-check assets/xsd/business-rules.xsd
Gate-check is a hard requirement. Do NOT deliver until it passes. If it fails: diagnose, fix, re-run.
Also diff to verify content preservation: $CLI diff --before source.docx --after out.docx
Validation pipeline
Run after every write operation. For Scenario C the full pipeline is mandatory; for A/B it is recommended (skip only if the operation was trivially simple).
$CLI merge-runs --input doc.docx # 1. consolidate runs
$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd # 2. XSD structure
$CLI validate --input doc.docx --business # 3. business rules
If XSD fails, auto-repair and retry:
$CLI fix-order --input doc.docx
$CLI validate --input doc.docx --xsd assets/xsd/wml-subset.xsd
If XSD still fails, fall back to business rules + preview:
$CLI validate --input doc.docx --business
scripts/docx_preview.sh doc.docx
# Verify: font contamination=0, table count correct, drawing count correct, sectPr count correct
Final preview: scripts/docx_preview.sh doc.docx
Critical rules
These prevent file corruption — OpenXML is strict about element ordering.
Element order (properties always first):
| Parent | Order |
|---|---|
w:p |
pPr → runs |
w:r |
rPr → t/br/tab |
w:tbl |
tblPr → tblGrid → tr |
w:tr |
trPr → tc |
w:tc |
tcPr → p (min 1 <w:p/>) |
w:body |
block content → sectPr (LAST child) |
Direct format contamination: When copying content from a source document, inline rPr (fonts, color) and pPr (borders, shading, spacing) override template styles. Always strip direct formatting — keep only pStyle reference and t text. Clean tables too (including pPr/rPr inside cells).
Track changes: <w:del> uses <w:delText>, never <w:t>. <w:ins> uses <w:t>, never <w:delText>.
Font size: w:sz = points × 2 (12pt → sz="24"). Margins/spacing in DXA (1 inch = 1440, 1cm ≈ 567).
Heading styles MUST have OutlineLevel: When defining heading styles (Heading1, ThesisH1, etc.), always include new OutlineLevel { Val = N } in StyleParagraphProperties (H1→0, H2→1, H3→2). Without this, Word sees them as plain styled text — TOC and navigation pane won't work.
Multi-template merge: When given multiple template files (font, heading, breaks), read references/scenario_c_apply_template.md section "Multi-Template Merge" FIRST. Key rules:
- Merge styles from all templates into one styles.xml. Structure (sections/breaks) comes from the breaks template.
- Each content paragraph must appear exactly ONCE — never duplicate when inserting section breaks.
- NEVER insert empty/blank paragraphs as padding or section separators. Output paragraph count must equal input. Use section break properties (
w:sectPrinsidew:pPr) and style spacing (w:spacingbefore/after) for visual separation. - Insert oddPage section breaks before EVERY chapter heading, not just the first. Even if a chapter has dual-column content, it MUST start with oddPage; use a second continuous break after the heading for column switching.
- Dual-column chapters need THREE section breaks: (1) oddPage in preceding para's pPr, (2) continuous+cols=2 in the chapter HEADING's pPr, (3) continuous+cols=1 in the last body para's pPr to revert.
- Copy
titlePgsettings from the breaks template for EACH section. Abstract and TOC sections typically needtitlePg=true.
Multi-section headers/footers: Templates with 10+ sections (e.g., Chinese thesis) have DIFFERENT headers/footers per section (Roman vs Arabic page numbers, different header text per zone). Rules:
- Use C-2 Base-Replace: copy the TEMPLATE as output base, then replace body content. This preserves all sections, headers, footers, and titlePg settings automatically.
- NEVER recreate headers/footers from scratch — copy template header/footer XML byte-for-byte.
- NEVER add formatting (borders, alignment, font size) not present in the template header XML.
- Non-cover sections MUST have header/footer XML files (at least empty header + page number footer).
- See
references/scenario_c_apply_template.mdsection "Multi-Section Header/Footer Transfer".
References
Load as needed — don't load all at once. Pick the most relevant files for the task.
The C# samples and design references below are the project's knowledge base ("encyclopedia"). When writing OpenXML code, ALWAYS read the relevant sample file first — it contains compilable, SDK-version-verified patterns that prevent common errors. When making aesthetic decisions, read the design principles and recipe files — they encode tested, harmonious parameter sets from authoritative sources (IEEE, ACM, APA, Nature, etc.), not guesses.
Scenario guides (read first for each pipeline)
| File | When |
|---|---|
references/scenario_a_create.md |
Pipeline A: creating from scratch |
references/scenario_b_edit_content.md |
Pipeline B: editing existing content |
references/scenario_c_apply_template.md |
Pipeline C: applying template formatting |
C# code samples (compilable, heavily commented — read when writing code)
| File | Topic |
|---|---|
Samples/DocumentCreationSamples.cs |
Document lifecycle: create, open, save, streams, doc defaults, settings, properties, page setup, multi-section |
Samples/StyleSystemSamples.cs |
Styles: Normal/Heading chain, character/table/list styles, DocDefaults, latentStyles, CJK 公文, APA 7th, import, resolve inheritance |
Samples/CharacterFormattingSamples.cs |
RunProperties: fonts, size, bold/italic, all underlines, color, highlight, strike, sub/super, caps, spacing, shading, border, emphasis marks |
Samples/ParagraphFormattingSamples.cs |
ParagraphProperties: justification, indentation, line/paragraph spacing, keep/widow, outline level, borders, tabs, numbering, bidi, frame |
Samples/TableSamples.cs |
Tables: borders, grid, cell props, margins, row height, header repeat, merge (H+V), nested, floating, three-line 三线表, zebra striping |
Samples/HeaderFooterSamples.cs |
Headers/footers: page numbers, "Page X of Y", first/even/odd, logo image, table layout, 公文 "-X-", per-section |
Samples/ImageSamples.cs |
Images: inline, floating, text wrapping, border, alt text, in header/table, replace, SVG fallback, dimension calc |
Samples/ListAndNumberingSamples.cs |
Numbering: bullets, multi-level decimal, custom symbols, outline→headings, legal, Chinese 一/(一)/1./(1), restart/continue |
Samples/FieldAndTocSamples.cs |
Fields: TOC, SimpleField vs complex field, DATE/PAGE/REF/SEQ/MERGEFIELD/IF/STYLEREF, TOC styles |
Samples/FootnoteAndCommentSamples.cs |
Footnotes, endnotes, comments (4-file system), bookmarks, hyperlinks (internal + external) |
Samples/TrackChangesSamples.cs |
Revisions: insertions (w:t), deletions (w:delText!), formatting changes, accept/reject all, move tracking |
Samples/AestheticRecipeSamples.cs |
13 aesthetic recipes from authoritative sources: ModernCorporate, AcademicThesis, ExecutiveBrief, ChineseGovernment (GB/T 9704), MinimalModern, IEEE Conference, ACM sigconf, APA 7th, MLA 9th, Chicago/Turabian, Springer LNCS, Nature, HBR — each with exact values from official style guides |
Note: Samples/ path is relative to scripts/dotnet/MiniMaxAIDocx.Core/.
Markdown references (read when you need specifications or design rules)
| File | When |
|---|---|
references/openxml_element_order.md |
XML element ordering rules (prevents corruption) |
references/openxml_units.md |
Unit conversion: DXA, EMU, half-points, eighth-points |
references/openxml_encyclopedia_part1.md |
Detailed C# encyclopedia: document creation, styles, character & paragraph formatting |
references/openxml_encyclopedia_part2.md |
Detailed C# encyclopedia: page setup, tables, headers/footers, sections, doc properties |
references/openxml_encyclopedia_part3.md |
Detailed C# encyclopedia: TOC, footnotes, fields, track changes, comments, images, math, numbering, protection |
references/typography_guide.md |
Font pairing, sizes, spacing, page layout, table design, color schemes |
references/cjk_typography.md |
CJK fonts, 字号 sizes, RunFonts mapping, GB/T 9704 公文 standard |
references/cjk_university_template_guide.md |
Chinese university thesis templates: numeric styleIds (1/2/3 vs Heading1), document zone structure (cover→abstract→TOC→body→references), font expectations, common mistakes |
references/design_principles.md |
Aesthetic foundations: 6 design principles (white space, contrast/scale, proximity, alignment, repetition, hierarchy) — teaches WHY, not just WHAT |
references/design_good_bad_examples.md |
Good vs Bad comparisons: 10 categories of typography mistakes with OpenXML values, ASCII mockups, and fixes |
references/track_changes_guide.md |
Revision marks deep dive |
references/troubleshooting.md |
Symptom-driven fixes: 13 common problems indexed by what you SEE (headings wrong, images missing, TOC broken, etc.) — search by symptom, find the fix |
Cross-References & Best Practices
Related skills
| Skill | When to prefer it |
|---|---|
../docx/ |
Canonical Z.AI docx skill — JavaScript / docx (npm) pipeline with 7 cover recipes (R1–R7), scene router (academic/report/contract/resume/exam/official/copywriting), postcheck.py 14-rule validator. Use when you want the JS-based pipeline instead of .NET. |
../kimi-docx/ |
Kimi (Moonshot AI) C# OpenXML SDK + Python+lxml pipeline with native Word charts (editable, small file size), Morandi/ink-wash background generators, pre-compiled OpenXML validator binary, and the most complete Track Changes + Comments Python API (docx_lib.editing). Use when you need native editable charts, designer-quality Morandi backgrounds, or programmatic track-changes editing. |
../docx-generation/ |
Bidirectional Markdown ↔ DOCX conversion with the same design-system rules. |
../pandoc-docx-template/ |
Pandoc-based DOCX with bundled Chinese reference templates and Lua filters. |
../resume-builder/ |
Resume-specific DOCX/PDF generation with STAR rewrites and ATS keyword checks. |
Best practices cross-pollinated from the canonical docx skill
These rules are universal to DOCX production regardless of pipeline (C#/.NET here vs. JS/docx-js in the canonical skill). Apply them on top of the OpenXML rules above.
Cover page discipline
- Always use a validated cover recipe — never free-form cover code. The canonical
docxskill ships 7 recipes (R1–R7) withselectCoverRecipe(docType, industry)andcalcTitleLayout()/calcCoverSpacing()helpers; if you need design parity, port the recipe constants into your C#AestheticRecipeSamples.cs. - Cover content must not overflow: total height ≤ 15,638 twips for A4 with 1,200-twip safety margin. Use
rule: "exact"on the wrapper table row, never"atLeast"for tall covers. - Every
TextRunon a dark or colored cover background MUST have an explicitcolorset. Default black-on-dark is the #1 cover bug. - Cover section must have NO trailing PageBreak or empty paragraphs — that produces a blank page 2.
Line spacing & CJK typography
- Body line spacing = 1.3× (
w:spacing line="312"). Scene overrides: resume 1.15×, official doc 28pt fixed, copywritingline="400", contract 1.5×. - CJK body: justified + 2-character first-line indent (
firstLine: 480SimSun /420YaHei). - For CJK heading chains, always set
OutlineLevelon the style (H1→0, H2→1, H3→2). Without it, Word treats headings as plain styled text — TOC and navigation pane break.
Page-break & blank-page prevention
- When using
<w:sectPr w:type="nextPage"/>, the preceding section MUST NOT end with a PageBreak (double break = blank page). - A PageBreak paragraph SHOULD contain visible text. Exception: a section-ending empty para + PageBreak is allowed as a normal section separator (e.g., after the cover).
- Never more than 3 consecutive empty paragraphs — they create phantom blank pages.
TOC integrity
- TOC MUST live in its own section. Body section sets
pageNumbers: { start: 1, formatType: DECIMAL }so page numbers start at the first body page, not at the TOC. - 3-section page numbering: Cover (no page#) → Front matter (Roman i, ii, iii, start=1) → Body (Arabic 1, 2, 3, start=1).
- Footer instrText for Roman section:
PAGE \* ROMAN \* MERGEFORMAT; for Arabic section:PAGE \* arabic \* MERGEFORMAT. NEVER use\* decimal—decimalis a docx-js API enum, not a Word field switch; it renders as literal1decimal,2decimal. - Strip the empty
<w:pgNumType/>from the cover section — docx-js emits it empty and WPS misreads it. - Between the
TableOfContentselement and the PageBreak, insert an italic gray note paragraph telling the user to right-click → "Update Field" to refresh page numbers.
Quotation-mark escaping (the #1 silent bug)
CJK curly quotes (“” ‘’) inside C# string literals MUST use Unicode escapes (\u201c \u201d \u2018 \u2019); straight quotes use \" \' or alternate delimiters. CJK text frequently contains “” for emphasis or proper nouns (e.g., “双11”, “618”) — every occurrence must be escaped. Failure produces C# compile errors that silently break document generation.
Post-generation checklist (run every time)
After every write operation, run a structural + business-rule validation. The C# pipeline uses $CLI validate --xsd assets/xsd/wml-subset.xsd then $CLI validate --business; the JS pipeline uses postcheck.py (14 rules: blank pages, cover overflow, line-spacing consistency, table margins, cross-page control, image aspect ratio, font fallback, CJK indent, heading hierarchy, ShadingType misuse, TOC quality, document cleanliness, report content quality). Treat any ❌ as a hard blocker before delivery.
04 同仓库更多 Skills
webapp-testing
Web application testing principles. E2E, Playwright, deep audit strategies.
web-search
Implement web search capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to search for real-time information from the web, retrieve up-to-date content beyond the knowledge cutoff, or find the latest news and data. Returns structured search results with URLs, snippets, and metadata.
web-reader
Implement web page content extraction capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to scrape web pages, extract article content, retrieve page metadata, or build applications that process web content. Supports automatic content extraction with title, HTML, and publication time retrieval.
web-frameworks
Build modern full-stack web applications with Next.js 16 + React 19 (App Router, Server Components, RSC, PPR, cacheComponents, async params, SSR, SSG, ISR, standalone output), Turborepo (monorepo, task pipelines, remote caching, parallel execution), and RemixIcon (3100+ SVG icons). Use when creating React applications, implementing server-side rendering, setting up monorepos, optimizing build performance and caching, or working with TypeScript full-stack projects.
video-understand
Implement specialized video understanding capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to analyze video content, understand motion and temporal sequences, extract information from video frames, describe video scenes, or perform video-based AI analysis. Optimized for MP4, AVI, MOV, and other common video formats.
video-generation
Implement AI-powered video generation capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to generate videos from text prompts or images, create video content programmatically, or build applications that produce video outputs. Supports asynchronous task management with status polling and result retrieval.