kimi-docx

What this skill does

# Part 1: Goals

## ⚠️ When to Unzip vs Read

**To preserve ANY formatting from the source document, MUST unzip and parse XML.**

Read tool returns plain text only — fonts, colors, alignment, borders, styles are lost.

| Need | Method |
|------|--------|
| Text content only (summarize, analyze, translate) | Read tool is fine |
| Formatting info (copy styles, preserve layout, template filling) | Unzip and parse XML |
| Structure + comments/track changes | `pandoc input.docx -t markdown` |

## Core Principles

1. **Preserve formatting** — When editing existing documents, retain original formatting. Clone and modify, never recreate.

2. **Correct feature implementation** — Comments need multi-file sync. Track Changes need revision marks. Use the right structure.

**Never use python-docx/docx-js as fallback.** These libraries produce lower quality output than direct XML manipulation.

## Source Principle

**Template provided = Act as form-filler, not designer.**
- Format is the user's decision
- Task: replace placeholders, not redesign
- Like filling a PDF form—do not redesign

**No template = Act as designer.** Design freely based on scenario.

For .doc (legacy format), first convert with `libreoffice --headless --convert-to docx`.

---

# Part 2: Execution

## File Structure

```
docx/
├── SKILL.md                      ← This file (entry point + reference)
├── references/
│   └── EditingGuide.md           → Complete Python editing tutorial (comments, track changes, 5-file sync)
├── scripts/
│   ├── docx                      → Unified entry (the only script to call)
│   ├── fix_element_order.py      → Auto-fix XML element ordering
│   ├── validate_docx.py          → Business rule validation
│   ├── generate_backgrounds.py       → Morandi style backgrounds
│   ├── generate_inkwash_backgrounds.py → Ink-wash style backgrounds
│   └── generate_chart.py         → matplotlib (only for heatmaps/3D/radar; simple charts must use native)
├── assets/
│   └── templates/
│       ├── KimiDocx.csproj       → Project file template (for creating new docs)
│       ├── Program.cs            → Program entry template
│       ├── Example.cs            → Complete example (cover+TOC+charts+back cover)
│       ├── CJKExample.cs         → CJK content patterns (quote escaping, fonts)
│       └── xml/                  → XML templates for comments infrastructure
└── validator/                    → OpenXML validator (pre-compiled binary, AI does not modify)
```

**Creating new documents**: Use C# SDK with `./scripts/docx build` → See `Example.cs` for patterns, `CJKExample.cs` for CJK content
**Editing existing documents**: Use Python + lxml → See `references/EditingGuide.md` for complete tutorial

⚠️ **Do NOT mix these approaches.** C# SDK for creation, Python for editing. Never use python-docx/docx-js.

## Environment Setup

First time, execute in the SKILL directory:

```bash
cd /app/.kimi/skills/kimi-docx/
./scripts/docx init
```

**Fixed Path Conventions** (cannot be changed):

| Path | Purpose |
|------|---------|
| `/app/.kimi/skills/kimi-docx/` | SKILL directory, where commands are executed |
| `/tmp/docx-work/` | Working directory, edit `Program.cs` here |
| `/mnt/okcomputer/output/` | Output directory, final deliverables |
| `/mnt/okcomputer/upload/` | User upload location (input files) |

**Script Commands** (`./scripts/docx <cmd>`):

| Command | Purpose |
|---------|---------|
| `env` | Show environment status (no changes) |
| `init` | Setup dependencies + workspace |
| `build [out]` | Compile, run, validate (default: output/output.docx) |
| `validate FILE` | Validate existing docx |

The script automatically handles:
- Detects dotnet/python3 (required), pandoc/playwright/matplotlib (optional)
- Installed → use directly; Not installed → auto-install; Broken → repair
- Initializes working directory, copies template files

## Build Process

**Must use `./scripts/docx build`**, do not execute `dotnet build && dotnet run` separately (skips validation).

### Program.cs Output Path Convention (Critical)

**Program.cs must get output path from command line arguments**, otherwise build script cannot find the generated file:

```csharp
// Correct - get output path from command line arguments
string outputFile = args.Length > 0 ? args[0] : "/mnt/okcomputer/output/output.docx";

// Wrong - hardcoded path causes build failure
string outputFile = "my_document.docx";  // Script can't find file!
```

| Step | Action | Notes |
|------|--------|-------|
| 1. Compile | `dotnet build` | Provides fix suggestions on failure |
| 2. Generate | `dotnet run -- <output path>` | Path passed via command line args |
| 3. Auto-fix | `fix_element_order.py` | Fixes XML element ordering issues |
| 4. OpenXML validation | `validator/` | Mandatory |
| 5. Business rules | `validate_docx.py` | Mandatory |
| 6. Statistics | Character + word count | Optional (requires pandoc) |

**Validation is mandatory**: On failure, file is kept but warnings are shown. Check error messages to fix issues.

### Standalone Validation

```bash
cd /app/.kimi/skills/kimi-docx/
./scripts/docx validate /mnt/okcomputer/output/report.docx
```

### Content Verification (Mandatory)

**pandoc is the SOURCE OF TRUTH.** OpenXML validator checks structure; pandoc shows actual content.

Before delivery, verify with pandoc:
- `pandoc output.docx -t plain` — check text completeness
- For revisions/comments: add `--track-changes=all` to verify marker positions

**⚠️ Critical**: `comments.xml` exists ≠ comments visible. Count mismatch = `doc_tree` not saved. See `references/EditingGuide.md` §5.3.

---

# Part 3: Quality Standards

## Delivery Standard

**Generic styling and mediocre aesthetics = mediocre delivery.**

Deliver studio-quality Word documents with deep thought on content, functionality, and styling. Users often don't explicitly request advanced features (covers, TOC, backgrounds, back covers, footnotes, charts)—deeply understand needs and proactively extend.

## Language Consistency

**Document language = User conversation language** (including filename, body text, headings, headers, TOC hints, chart labels, and all other text).

## Headers and Footers - REQUIRED BY DEFAULT

Most documents **MUST** include headers and footers. The specific style (alignment, format, content) should match the document's overall design.

- **Header**: Typically document title, company name, or chapter name
- **Footer**: Typically page numbers (format flexible: "X / Y", "Page X", "— X —", etc.)
- **Cover/Back cover**: Use `TitlePage` setting to hide header/footer on first page

## Professional Elements (Critical)

Create documents that exceed user expectations, proactively add professional elements, don't wait for users to ask. **Delivery standard: Visual quality of a top designer in 2024.**

**Cover & Visual:**
- Formal documents (proposals, reports, financials, bids, contracts) / creative documents (invitations, greeting cards) must have **cover and back cover**
- Covers must have designer-quality background images
- Body pages can optionally include backgrounds to enhance visual appeal

**Structure:**
- Long documents (3+ sections) add TOC, must add refresh hint after TOC

**Data Presentation:**
- When comparing data or showing trends, use charts instead of plain text lists
- Tables use light gray headers or three-line style, avoid Word default blue

**Links & References:**
- URLs must be clickable hyperlinks
- Multiple figures/tables add numbering and cross-references ("see Figure 1", "as shown in Table 2")
- Academic/legal/data analysis citation scenarios implement correct in-text click-to-jump references with corresponding footnotes/endnotes

### TOC Refresh Hint

Word TOC is field code, page numbers may be inaccurate when generated. **Must add gray hint text after TOC**, informing users to manually refresh:

```
Table of Contents
─────────────────
Chapter 1 Overview .......................... 1
Chapter 2 Methods ........................... 3
.