{"id":"542f1456-323b-4d9a-aaef-6b01cf21be49","slug":"docx-smart-format","kind":"skill","name":"docx-smart-format","summary":"","owner":"yaya200325","repoUrl":"https://github.com/yaya200325/docx-smart-format","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":4,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-05-19T11:17:06.000Z","addedAt":"2026-10-21T23:09:05.031Z","logoUrl":"https://avatars.githubusercontent.com/u/219941839?u=46217b4dc5ae98347b75d7fc3da4647f92fffed6&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["files-documents"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T23:45:37.366Z","sample":false,"url":"https://conduits.dev/tools/docx-smart-format","language":"C#","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# docx-smart-format\n\n> LLM-driven Word document formatter — let the model decide the style; let a local engine write the XML.\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![Platform](https://img.shields.io/badge/platform-Windows%20x64-lightgrey)](#平台与依赖)\n[![Skill: Claude Code / Codex](https://img.shields.io/badge/skill-Claude%20Code%20%2F%20Codex-8A2BE2)](SKILL.md)\n[![Release](https://img.shields.io/github/v/release/yaya200325/docx-smart-format)](https://github.com/yaya200325/docx-smart-format/releases)\n\n中文为主、英文同步的 Skill。把\"用 Word 写论文/报告/纪要时的排版判断\"交给 LLM，把\"操作 OOXML 的细节\"交给本地引擎，避免 LLM 直接拼 XML。\n\n## 特性\n\n- **两种模式**：基于现有 `.docx` 重排（analyze → decide → apply），或从零生成新 `.docx`（render）。\n- **LLM 只出决策、不出 XML**：分四层（文档级 / 块级 / 行内 / 对象级）输出 JSON，引擎写回。\n- **覆盖排版痛点**：分节、奇偶页眉、STYLEREF 字段、`pgNumType` + `PAGE` 字段、参考文献条目书签 + 上标 REF 交叉引用、横向页竖排页码（`wps:wsp` + VML 双轨）。\n- **本地、离线**：skill 不联网，所有模板规则在 `references/`。\n- **可校验**：`scripts/validate_decision.py` 校验决策 JSON 结构。\n\n## 平台与依赖\n\n- **当前仅支持 Windows x64**。`engine/runtime/docx-auto-template-engine.exe` 是 .NET self-contained 部署。macOS / Linux 暂未发布预编译产物；可按 `CONTRIBUTING.md` 自行构建对应 RID。\n- Skill 自身运行不需要 .NET SDK，只要 runtime 可执行文件存在即可。\n- 重新构建引擎需要 .NET SDK 8.0+。\n\n## 安装\n\n### 方式 A：下载 Release（推荐）\n\n1. 到 [Releases](https://github.com/yaya200325/docx-smart-format/releases) 下载最新版本的 `docx-smart-format-<version>-win-x64.zip`。\n2. 解压到本机 skill 目录：\n   - Claude Code：`~/.claude/skills/docx-smart-format/`\n   - Codex：`~/.codex/skills/docx-smart-format/`\n   - （Windows 实际路径为 `C:\\Users\\<USER>\\.claude\\skills\\...` 或 `C:\\Users\\<USER>\\.codex\\skills\\...`）\n3. 解压后目录里应当包含 `engine/runtime/docx-auto-template-engine.exe`。\n\n### 方式 B：克隆仓库 + 本地构建\n\n适用于 Linux/macOS 用户或希望自行编译引擎的开发者：\n\n```powershell\ngit clone https://github.com/yaya200325/docx-smart-format.git\ncd docx-smart-format\n# Windows\n.\\build.ps1\n# Linux / macOS\n./build.sh\n```\n\n`build.ps1` / `build.sh` 会调用 `dotnet publish` 把 `engine/src/` 编译并发布到 `engine/runtime/`。脚本默认 RID 为 `win-x64`，可用 `-Rid linux-x64` / `--rid osx-arm64` 等改写。\n\n> ⚠️ Linux / macOS RID 当前未在 CI 自动验证，引擎对非 Windows 平台的兼容性尚未官方背书；如遇问题欢迎开 Issue。\n\n## 快速开始\n\n### 模式一：重排现有 `.docx`\n\n```powershell\n$skill = \"$env:USERPROFILE\\.claude\\skills\\docx-smart-format\"\n\n# 1. 分析源文档\n& \"$skill\\engine\\runtime\\docx-auto-template-engine.exe\" `\n    analyze --input  .\\input.docx `\n            --output .\\analysis.json\n\n# 2. LLM 根据 analysis.json 生成 decision.json（结构见 references/decision-schema.md）\n# 3. 写回\n& \"$skill\\engine\\runtime\\docx-auto-template-engine.exe\" `\n    apply --source   .\\input.docx `\n          --decision .\\decision.json `\n          --output   .\\result.docx `\n          --template .\\template.docx\n```\n\n### 模式二：从零生成\n\n```powershell\n$skill = \"$env:USERPROFILE\\.claude\\skills\\docx-smart-format\"\n\n& \"$skill\\engine\\runtime\\docx-auto-template-engine.exe\" `\n    render --spec   .\\render-spec.json `\n           --output .\\result.docx `\n           --template-preset builtin-undergraduate-thesis\n```\n\n毕业论文场景下 `--template-preset builtin-undergraduate-thesis` 会自动启用 `--normalize-references`。详见 [`references/reference-normalization.md`](references/reference-normalization.md)。\n\n### 校验决策 JSON\n\n```powershell\npython scripts\\validate_decision.py decision.json\n```\n\n通过会打印 `[OK] decision.json 结构合法` 并列出关键计数；错误会以 `[ERROR]` 前缀输出并以非零退出码结束。\n\n## 目录结构\n\n```\ndocx-smart-format/\n├── SKILL.md                       # Skill 主文档（LLM 入口）\n├── agents/openai.yaml             # Codex/OpenAI agent 元数据\n├── references/                    # 模板规则、能力清单、深度规范\n│   ├── decision-schema.md\n│   ├── template-catalog.md        # 字体/字号唯一权威\n│   ├── local-capability-map.md\n│   ├── header-footer-odd-even.md\n│   ├── reference-normalization.md\n│   └── landscape-vertical-pagenum.md\n├── scripts/\n│   ├── sample-decision.json\n│   ├── sample-render-spec.json\n│   ├── sample-chem-render-spec.json\n│   └── validate_decision.py\n└── engine/\n    ├── runtime/                   # 预编译引擎（gitignore，发布到 Release）\n    └── src/                       # 引擎源代码（C# / .NET 8）\n```\n\n## 文档导航\n\n- LLM 怎么用：从 [`SKILL.md`](SKILL.md) 开始。\n- 字段定义：[`references/decision-schema.md`](references/decision-schema.md)。\n- 字体字号默认值：[`references/template-catalog.md`](references/template-catalog.md)。\n- 奇偶页眉与页码：[`references/header-footer-odd-even.md`](references/header-footer-odd-even.md)。\n- 参考文献交叉引用：[`references/reference-normalization.md`](references/reference-normalization.md)。\n- 横向页竖排页码：[`references/landscape-vertical-pagenum.md`](references/landscape-vertical-pagenum.md)。\n- 引擎可调用能力清单：[`references/local-capability-map.md`](references/local-capability-map.md)。\n\n## 贡献\n\n欢迎 Issue 与 PR：\n\n- 贡献规则 → [CONTRIBUTING.md](CONTRIBUTING.md)\n- 行为准则 → [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)\n- 安全问题 → [SECURITY.md](SECURITY.md)（请不要在公开 Issue 中提交安全漏洞）\n- 变更历史 → [CHANGELOG.md](CHANGELOG.md)\n\n## 许可证\n\nApache License 2.0。详见 [`LICENSE`](LICENSE) 与 [`NOTICE`](NOTICE)。\n"}