文档创建者
- 作者仓库星标 0
- 作者更新于 2026年8月24日 07:33
- 作者仓库 claude-code-skills
- 领域
- 数据
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @daymade · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# 1. Stage the generator beside your markdown
mkdir -p _docxgen && cp <skill-dir>/scripts/Program.cs <skill-dir>/scripts/mmdocx-gen.csproj \
<skill-dir>/scripts/.gitignore _docxgen/
# 2. Generate (first run restores DocumentFormat.OpenXml + Markdig, ~20s)
dotnet run --project _docxgen -- your-doc.md your-doc.docx
# 3. Structural validation via the engine's XSD validator (note the roll-forward env — ISSUE-003)
DOTNET_ROLL_FORWARD=Major dotnet run \
--project ~/.claude/plugins/marketplaces/minimax-skills/skills/minimax-docx/scripts/dotnet/MiniMaxAIDocx.Cli \
-- validate --input your-doc.docx
# 4. MANDATORY visual verification — never skip, never substitute qlmanage
soffice --headless --convert-to pdf --outdir /tmp/docxcheck your-doc.docx
pdftoppm -png -r 100 /tmp/docxcheck/your-doc.pdf /tmp/docxcheck/page
# then Read every /tmp/docxcheck/page-NN.png
# 5. MANDATORY if Microsoft Word.app is installed — LibreOffice cannot see ISSUE-012
open -a "Microsoft Word" your-doc.docx # check the title bar for "兼容性模式", check every page
# DOCX Creator
Thin incremental layer over **`minimax-skills:minimax-docx`**. Not a document engine.
> **Read this first.** The OpenXML SDK capability lives in `minimax-docx`. This skill contains
> zero engine code. What it contains is the part that took a full debugging session to learn:
> where that engine's CLI stops being usable, how to drive its SDK correctly for Chinese formal
> documents, and how to verify the output so you don't ship a file that looks fine to you and
> broken in Word.
## Division of labor
| Layer | Owner | What lives there |
|---|---|---|
| OpenXML SDK (`DocumentFormat.OpenXml`), `WordprocessingDocument` API, XSD validator, style templates, OpenXML encyclopedia | **`minimax-skills:minimax-docx`** | Engine + reference docs. Never duplicated here. |
| Where the CLI's expressiveness ceiling is, and when to abandon it for C# | **this skill** | ISSUE-001, ISSUE-002 |
| A verified markdown-to-docx generator for Chinese formal documents | **this skill** | `scripts/Program.cs` |
| Chinese formal-document typography rules that OpenXML lets you get wrong | **this skill** | Hard rules below + ISSUE-004…007 |
| Real end-to-end visual verification chain | **this skill** | `references/verification_protocol.md` |
Locate the engine at the marketplace install path, typically
`~/.claude/plugins/marketplaces/minimax-skills/skills/minimax-docx/`.
**Go read minimax-docx directly** for anything structural this skill does not cover — images,
track changes, comments, TOC, multi-section layouts, template application. Its
`minimax-docx/references/` folder (`cjk_typography.md`, `openxml_element_order.md`,
`openxml_units.md`, `troubleshooting.md`) and its `Samples/*.cs` are the authority for SDK
patterns. Do not reinvent them here.
## Routing: which path for this document?
| Situation | Path |
|---|---|
| Chinese contract / agreement / 公文 / any doc with 甲乙方 info blocks, numbered clauses, signature block, tables | **C# OpenXML via `scripts/Program.cs`** (this skill) |
| Plain prose, headings and paragraphs only, no bold / lists / tables | minimax-docx CLI `create --content-json` is enough |
| Fill or edit an **existing** .docx | minimax-docx pipeline B (`edit-content`) — this skill has nothing to add |
| Match an existing .docx's formatting | minimax-docx pipeline C (`apply-template`) |
| Output should be a **PDF**, not Word | `daymade-docs:pdf-creator` — wrong skill, stop here |
Rule of thumb: the CLI's `--content-json` understands exactly three block types
(`heading`, `paragraph`, `pagebreak`). Bold, lists, tables, borders, footers, fonts,
alignment — none of it is expressible. A Chinese contract needs all of them. See ISSUE-001.
## Quick start
The generator reads markdown and writes a formatted .docx. Copy it next to your document so
build artifacts stay out of the skill directory:
```bash
# 1. Stage the generator beside your markdown
mkdir -p _docxgen && cp <skill-dir>/scripts/Program.cs <skill-dir>/scripts/mmdocx-gen.csproj \
<skill-dir>/scripts/.gitignore _docxgen/
# 2. Generate (first run restores DocumentFormat.OpenXml + Markdig, ~20s)
dotnet run --project _docxgen -- your-doc.md your-doc.docx
# 3. Structural validation via the engine's XSD validator (note the roll-forward env — ISSUE-003)
DOTNET_ROLL_FORWARD=Major dotnet run \
--project ~/.claude/plugins/marketplaces/minimax-skills/skills/minimax-docx/scripts/dotnet/MiniMaxAIDocx.Cli \
-- validate --input your-doc.docx
# 4. MANDATORY visual verification — never skip, never substitute qlmanage
soffice --headless --convert-to pdf --outdir /tmp/docxcheck your-doc.docx
pdftoppm -png -r 100 /tmp/docxcheck/your-doc.pdf /tmp/docxcheck/page
# then Read every /tmp/docxcheck/page-NN.png
# 5. MANDATORY if Microsoft Word.app is installed — LibreOffice cannot see ISSUE-012
open -a "Microsoft Word" your-doc.docx # check the title bar for "兼容性模式", check every page
```
Full command details and troubleshooting: `scripts/README.md`.
Full verification steps and pass/fail criteria: `references/verification_protocol.md`.
## Hard rules (violating these means rework)
### 1. Alignment is layered — this is the expensive one
Never justify the whole document. Three layers, three alignments:
| Content | Alignment | Why |
|---|---|---|
| Document title (H1) | Center | Convention |
| Clause headings (H2+) | Left | Convention |
| **Info blocks and signature blocks** — 甲方/乙方/统一社会信用代码/法定代表人/日期, i.e. any paragraph whose lines are joined by markdown soft or hard line breaks | **Left** | Justification stretches **every line except the paragraph's last**. A multi-line info block is *one* paragraph, so all but its final line get blown out into huge inter-character gaps. |
| Ordinary body prose | Justified (`Both`) | Clean right edge |
The rule is machine-checkable, so do not eyeball it: if the markdown paragraph's inline tree
contains a `LineBreakInline`, left-align that paragraph; otherwise justify it. Implemented in
the `case ParagraphBlock p:` arm of `Main`'s block-dispatch switch, with the break detection in
`InlineRuns`. (Line numbers are deliberately not given here — they drift every time the file
grows; see `scripts/README.md`'s function-name lookup table instead.) Full write-up: ISSUE-004.
### 2. Every list restarts at 1
Each markdown list must get its **own** `NumId` plus a `LevelOverride` carrying
`StartOverrideNumberingValue = 1`. Reuse one `NumId` across clauses and clause 3's list
silently continues from 4. Implemented across the `case ListBlock lb:` arm and the
`NumberingDefinitionsPart` setup — see `scripts/README.md`'s lookup table for both.
Two SDK traps come with it (wrong class name, wrong element order) — ISSUE-005, ISSUE-006.
### 3. CJK fonts need both slots
A run must set `RunFonts { Ascii, HighAnsi, EastAsia }`. Setting only the Latin slots leaves
Chinese characters to Word's fallback, and the document renders in whatever the reader's
machine picks. Shipped defaults: Latin `Times New Roman`; East Asian 宋体 for body, 黑体 for
headings. Chinese **bold runs switch family to 黑体** — 宋体 has no true bold weight and
renderer-synthesized bold smears multi-stroke characters (ISSUE-014). Sizes are OpenXML
half-points — body 21 (10.5pt, the common Chinese manuscript size), H1 36 (18pt), clause
heading 28 (14pt). Body paragraphs also get a 2-character first-line indent (`420` twips at
10.5pt — change it in lockstep with the body size). ISSUE-007.
### 4. Page and table basics
A4 is 11906 × 16838 twips with 1440 twip margins; page number goes in a centered footer
`PAGE` field. Tables need all six borders (`top`/`bottom`/`left`/`right`/`insideH`/`insideV`,
in that ECMA-376 order — ISSUE-013) and a `tblGrid` (ISSUE-012) — set fewer borders and cells
look unruled in print; omit `tblGrid` and the file fails strict validation even though
LibreOffice hides it. Implemented in `BuildTable` and the `SectionProperties`/`FooterPart`
setup in `Main` — see `scripts/README.md`'s lookup table.
## Verification is not optional
**Banned: `qlmanage` thumbnails as visual proof.** macOS Quick Look renders with a different
engine than Word and will happily show a clean-looking page for a document whose info blocks
are stretched apart. A document was declared "verified perfect" on qlmanage evidence and
opened broken in Word — that is the origin of this rule. ISSUE-008.
**Required chain:** generate → XSD validate → `soffice --headless --convert-to pdf` →
`pdftoppm -png` → `Read` every page image → check the five failure modes
(info blocks not stretched / each list restarting at 1 / table borders present / signature
block intact / no orphaned pagination) → **if Microsoft Word.app is installed, open the actual
file in it and check the title bar for "兼容性模式" plus every page**. Details, prerequisites
and the "what counts as failure" list: `references/verification_protocol.md`.
**LibreOffice rendering clean is not the same claim as "Word renders this correctly."**
ISSUE-012 is a real, reproduced case where a file passed every LibreOffice-based check in this
chain — clean info blocks, correct numbering, intact tables — and still opened in real Word
with "兼容性模式" in the title bar and phantom bullet markers on paragraphs that were never
given any numbering. LibreOffice has no equivalent fallback path and is structurally unable to
surface that class of defect. This is ISSUE-008's own lesson (a lenient renderer hides what
Word does) recurring one layer up; treat LibreOffice-only verification as incomplete whenever
Word is available to check against directly.
**Before overwriting a delivered .docx**, check for a sibling `~$<name>.docx` — that is Word's
owner lock, meaning the recipient has the old version open. Overwriting works, but they will
keep seeing the stale document until they close and reopen it. Tell them. ISSUE-011.
## Customizing
`scripts/Program.cs` is ~260 lines of straightforward OpenXML. Edit it directly for fonts,
sizes, spacing, borders, or new block types — that is the intended workflow. Before adding a
structural feature (images, TOC, headers, track changes), read the corresponding
`Samples/*.cs` in minimax-docx first; those patterns are SDK-version-verified and will save
you a compile-error loop.
**If you append a new property to `RunProperties`, `ParagraphProperties`, `TableProperties`,
`TableCellProperties`, or `TableBorders`: it must go in ECMA-376's child-element order for
that parent, not wherever `.Append()` reads naturally in the C#.** This is not a style
preference — get it wrong and you reproduce ISSUE-012/ISSUE-013: `minimax-docx validate` still
reports `PASSED`, LibreOffice still renders the file cleanly, and real Word still opens it in
Compatibility Mode with unrequested formatting scattered across the document. The current code
already carries a schema-order comment at each construction site (`RunProps`, `Para`,
`BuildTable`) — extend the existing property list in place rather than appending after it, and
if you add a genuinely new element, look up its position in `openxml_element_order.md`
(minimax-docx) before deciding where the `.Append()` call goes. Re-run Step 3a of the
verification protocol (real Word, not just LibreOffice) after any such change — that is the
only check in the whole chain that would have caught this class of bug.
## References
- `references/known_issues.md` — ISSUE-001…013: symptom / root cause / fix / verification for
every trap hit while building this pipeline. Read before debugging anything.
- `references/verification_protocol.md` — the full end-to-end verification chain, its
prerequisites, its pass criteria, and the substitutions that are forbidden.
- `scripts/README.md` — how to run the generator, what markdown it supports, environment
requirements.
章节与文件索引
按说明文件中的顺序排列。
分工
路由:这个文件的路径是什么?
快速启动
1. 对齐是分层的——这是最昂贵的
2. 每个列表都从 1 重新开始
文件/命令 -> minimax-skills:minimax-docx · minimax-docx · DocumentFormat.OpenXml · WordprocessingDocument · scripts/Program.cs · references/verification_protocol.md · ~/.claude/plugins/marketplaces/minimax-skills/skills/minimax-docx/ · minimax-docx/references/
内容校验值 -> 9137360acd31
当前原文的自动摘译,尚未人工审校。
分工
层 · 所有者 · 里面有什么 OpenXML SDK (
DocumentFormat.OpenXml)、WordprocessingDocumentAPI、XSD 验证器、样式模板、OpenXML 百科全书 ·minimax-skills:minimax-docx· 引擎 + 参考文档。这里从来没有重复过。 CLI 的表达能力上限在哪里,何时放弃 C# · 这个技能 · ISSUE-001, ISSUE-002 一个经过验证的中文正式文档的 markdown-to-docx 生成器 · 这个技能 ·scripts/Program.cs路由:这个文件的路径是什么?
情况 · 路径中文合同/协议/公文/任何带有甲乙方信息块、编号条款、签名块、表格的文档 · 通过
scripts/Program.cs使用C# OpenXML(此技能) 仅限普通散文、标题和段落,无粗体/列表/表格 · minimax-docx CLIcreate --content-json就足够了 填充或编辑现有的.docx · minimax-docx 管道 B (edit-content) — 这个技能没什么可加的快速启动
生成器读取 Markdown 并写入格式化的 .docx。将其复制到文档旁边,以便构建工件远离技能目录:完整的命令详细信息和故障排除:
scripts/README.md。完整的验证步骤和通过/失败标准:references/verification_protocol.md。1. 对齐是分层的——这是最昂贵的
永远不要证明整个文件的合理性。三层,三种对齐:内容·对齐·为什么文档标题(H1)·中心·约定条款标题(H2+)·左·约定信息块和签名块-甲方/乙方/统一社会信用代码/法治代表人/日期,即任何行由markdown软或硬换行符连接的段落·左·对齐拉伸除最后一行之外的每一行。多行信息块是一个段落,因此除了最后一行之外的所有内容都会被吹散成巨大的字符间间隙。
2. 每个列表都从 1 重新开始
每个 Markdown 列表必须有自己的
NumId以及带有StartOverrideNumberingValue = 1的LevelOverride。跨子句重用一个NumId,第 3 子句的列表从 4 继续。在case ListBlock lb:臂和NumberingDefinitionsPart设置中实现 — 请参阅scripts/README.md的查找表。它附带两个 SDK 陷阱(错误的类名、错误的元素顺序)——ISSUE-005、ISSUE-006。