docx

# Part 1: Routing `read file` / `cat` only extracts plain text from `.docx` — all formatting is lost. If the task involves appearance or structure, use WIR engine's `session.read()` instead. ## Route = What You Have **1. WIR** (`references/wir-reference.md`) — A .docx exists whose **format/style matters** to the output. The user provides a template, a document to edit/modify/review/annotate, or any file whose formatting should be preserved or referenced. This file is your output foundation — read it, modify it, fill it. If the .docx is merely a content/data source (e.g., reference papers, raw data exports) and its formatting is irrelevant, just `read file` to extract text — that is NOT a WIR case. `.doc` format → convert first: `libreoffice --headless --convert-to docx` **2. md2docx** (`references/md2docx-reference.md`) — When you are the Orchestrator (you have `create_subagent` and dispatch `task`) and your sub-agents have returned `.md` files. Convert their output to a formatted Word document using the md2docx pipeline. If you do NOT have `create_subagent` / `task` tools, you are not an Orchestrator and md2docx does not apply. Do not write markdown yourself and convert with pandoc — the result is mediocre. Use Create (C#) for high-quality output. **3. Create** (`references/openxml-sdk-reference.md`) — Neither of the above. No target .docx, no upstream .md. Build the document from scratch using C# + OpenXML SDK via `./scripts/docx build`. --- # Part 2: Execution ## File Structure ``` docx/ ├── SKILL.md ← This file (routing + rules) ├── references/ │ ├── openxml-sdk-reference.md → Creation: patterns, traps, all you need │ ├── wir-reference.md → WIR editing interface + patterns │ ├── md2docx-reference.md → Citation pipeline → Word conversion │ ├── chart-reference.md → Native Word charts (pie, bar, line) │ ├── omml-reference.md → OMML math equation patterns │ └── matplotlib-guide.md → Charts Word can't do natively ├── scripts/ │ ├── docx → Unified entry point (the only script to call) │ ├── engine/ → WIR engine (editing core) │ ├── md2docx/ → Citation → Word pipeline │ ├── generate_backgrounds.py → Style reference: Morandi curves (read for technique, don't call directly) │ ├── generate_inkwash_backgrounds.py → Style reference: ink wash │ ├── generate_swiss_backgrounds.py → Style reference: Swiss grid │ ├── generate_geometric_backgrounds.py → Style reference: geometric blocks │ ├── generate_gradient_backgrounds.py → Style reference: gradient ribbons │ └── generate_formal_backgrounds.py → Style reference: formal double border └── assets/templates/ ├── Example.cs → English document demo (conditional required) └── CJKExample.cs → Chinese/CJK document demo (conditional required) ``` ## Validation - **Creation**: `./scripts/docx build` runs the full pipeline (compile → generate → auto-fix element order → OpenXML validate → business rules) - **Editing**: The engine validates internally; after saving, spot-check high-risk areas ## Hard Rules 1. **No manual markdown-to-docx.** Do not write markdown then convert with pandoc. If you are the Orchestrator with upstream .md from sub-agents, use md2docx. Otherwise, always Create (C#). 2. **Target .docx exists (template, document to edit, format reference) → always WIR**, never rewrite from scratch. 3. Clean up iteration artifacts — no `v1`/`v2`/`final` clutter in the output directory. Deliver clean, clearly named files only. 4. Name output files by topic and match the user's language (e.g., Chinese query → `储能电站分析报告.docx`, English query → `Energy_Storage_Report.docx`). Never `output.docx`. 5. Language consistency — user's conversation language across all elements (body, headings, headers/footers, TOC, chart labels, filenames). 6. Default to the skill's own toolchain; avoid external libraries unless necessary. 7. After choosing a route, read the corresponding reference file **in full** before writing any code. Do not skim or skip sections — traps and required patterns appear throughout. ## Quality Standards **Low-saturation color palette.** Pick ONE hue direction, build 3 tiers: Primary (headings) / Dark (body text) / Light (captions). Never pure #FF0000/#0000FF. Cover text color must contrast with its background AND be visually distinct from body text (larger size, different weight, generous spacing). **Cover/backcover backgrounds.** If the document needs a cover, generate a unique background from scratch — read one of the `generate_*.py` scripts to learn the Playwright + SVG technique, then write your own HTML/SVG with original shapes and colors matching the document's palette. Never reuse or directly call existing background scripts. Cover text must feel like a separate visual space from the body, not just a bigger first paragraph. **Content constraints.** Word count target "X字左右" means ±20% is acceptable. **Delivery checklist** (verify before delivering): 1. Document opens without errors 2. OpenXML + business rule validation passes 3. Headers, footers, page numbers present and correctly positioned 4. No placeholder text remains (`[Company Name]`, `TODO`, etc.) 5. All images render (build output shows `X images` — if 0, images were not inserted) 6. Cover/backcover text visibly contrasts with background