RempleXI/word-docx-writer

word-docx-writer

中文 Word（.docx）报告生成与排版工具包 / Agent Skill。
无需第三方 Office 库即可生成规范的 .docx；同时提供 DSH / Claude Skill、AGENTS.md 等多种 Agent 入口。

License: MIT
Python

英文版：README_EN.md

简介

word-docx-writer 适用于各类中文长文档（实验报告、课程设计报告、毕业论文、项目总结、研究报告、实训报告、说明书等），不限定专业方向：
用一份简单的标记稿（Markdown 风格）即可生成排版规范的 Word 文档，也可以对已有 .docx 一键套用格式规范。

核心排版规则（可在命令行覆盖）：

| 用途 | Word 内置样式 | 中文字号 | 磅值 | 段落格式 |
| --- | --- | --- | --- | --- |
| 正文 | 正文 / Normal | 小四 | 12 pt | 首行缩进2字符、两端对齐、1.5倍行距、段前段后0 |
| 一级标题 | 标题 1 | 三号 | 16 pt | 段前段后0、1.5倍行距、左对齐 |
| 二级标题 | 标题 2 | 四号 | 14 pt | 段前段后0、1.5倍行距、左对齐 |
| 三级标题 | 标题 3 | 小四 | 12 pt | 段前段后0、1.5倍行距、左对齐 |
| 图表题注 | 正文 + 黑体 | 小五 | 9 pt | 黑体不加粗、居中、单倍行距 |

- 字体：中文宋体（SimSun），西文Times New Roman；标题仍用宋体；默认颜色黑色。
- 表格：表内文字五号、无底纹、不首行缩进。
- 图表题注：按章自动编号（表1.1 题名 / 图1.1 题名），表题在表格上方、图题在图片下方。
- 标题必须使用 Word 内置样式（标题 1/2/3），保证目录（TOC 域）可自动生成。

特性

- 标准库即可生成：OOXML 路径只依赖 Python 标准库（图片尺寸除外，需要 Pillow）。
- 双实现：OOXML（跨平台，不需要 Word）与 Word COM（Windows + Office，功能最全：.doc 转换、目录刷新）。
- 模板套用：保留模板封面/评分表/目录/页眉页脚，只替换正文。
- 规范化已有文档：对任意 .docx 套用字体、字号、段落格式与颜色。
- 多 Agent 兼容：内置 SKILL.md、AGENTS.md / AGENTS_EN.md、CLAUDE.md、GEMINI.md、Copilot / Cursor 入口。
- 可作为 DSH 插件分发：同一仓库附带 package.json + cordis.patch.yml + 内置技能 skills/word-docx-writer.md，可 dsh plugin add 一键安装。

目录结构

word-docx-writer/
├── SKILL.md                    # DSH / Claude Skill 入口
├── AGENTS.md / AGENTS_EN.md    # 通用 Agent 说明（中文 / English）
├── CLAUDE.md / GEMINI.md       # Claude Code / Gemini CLI 入口
├── README.md / README_EN.md    # 说明文档（中文 / English）
├── LICENSE / CHANGELOG.md
├── scripts/
│   ├── word_style.py           # 排版规范唯一来源（字体/字号/段落格式/颜色）
│   ├── build_docx.py           # 标记稿 -> .docx（模板、标题样式、表格、图片、题注、目录）
│   └── read_docx.py            # 读取/转换 .doc、.docx 结构
├── references/
│   ├── style-spec.md           # 排版规范速查
│   └── markup.md               # 内容标记语法
├── assets/blank.docx           # 内置空白模板
├── examples/                   # 可运行示例（content.txt + README）
├── skills/word-docx-writer.md  # 插件内置技能（方式 C）
├── src/index.js                # 插件宿主入口（skills-only，空实现）
├── package.json                # npm 包定义（方式 C）
├── cordis.patch.yml            # DSH 插件挂载声明（方式 C）
├── .github/copilot-instructions.md
└── .cursor/rules/word-docx-writer.mdc

安装

方式 1：作为 DSH / Claude Skill（推荐）

DSH（DeepSeek Harness）
git clone https://github.com/RempleXI/word-docx-writer ~/.dsh/skills/word-docx-writer

Claude Code
git clone https://github.com/RempleXI/word-docx-writer ~/.claude/skills/word-docx-writer

也可以放到项目级目录，仅对当前项目生效：

git clone https://github.com/RempleXI/word-docx-writer /.dsh/skills/word-docx-writer
或
git clone https://github.com/RempleXI/word-docx-writer /.claude/skills/word-docx-writer

方式 2：下载 zip 直接用
下载 Release / 打包好的 word-docx-writer.zip，解压到上面的任一 skill 目录即可。

方式 3：其它 Agent 工具

- Codex / OpenCode / 通用：把本仓库放到项目里，工具会读根目录的 AGENTS.md；
- Gemini CLI：读 GEMINI.md；
- Claude Code：读 CLAUDE.md；
- GitHub Copilot：读 .github/copilot-instructions.md；
- Cursor：读 .cursor/rules/word-docx-writer.mdc；
- 英文用户：见 README_EN.md、AGENTS_EN.md。

方式 4：作为 DSH 插件（npm）

本仓库本身也是一个 skills-only 的 DSH 插件：

npm publish --access public         # 发布为 dsh-plugin-word-docx-writer
dsh plugin --profile web add dsh-plugin-word-docx-writer@latest

- 插件运行时入口 src/index.js 为空实现（no-op）；
- 能力由内置技能 skills/word-docx-writer.md 与 scripts/ 工具包提供；
- 发布前请把 package.json 的 name 改成你的 scope（如 @your-scope/dsh-plugin-word-docx-writer），并同步修改 cordis.patch.yml 里的 name。

快速开始

1）写一份内容稿 content.txt（语法见 references/markup.md）：

TITLE|实验报告标题
H1|1. 实验目的
H2|1.1 实验背景
P|这是一段正文，自动首行缩进2字符、两端对齐、1.5倍行距。
TCAP|实验数据表
TBL|编号;;项目;;结果
ROW|1;;示例项目;;示例结果
FCAP|实验装置图
IMG|fig.png|12

2）生成文档：

python scripts/build_docx.py --content content.txt --out report.docx

3）对已有文档套用规范：

python scripts/word_style.py report.docx          # 默认优先 Word COM，失败自动退回 OOXML
python scripts/word_style.py report.docx --method ooxml

4）校验结构：

python scripts/read_docx.py report.docx

依赖与平台

| 能力 | 依赖 |
| --- | --- |
| 生成 / 排版（OOXML） | Python 3.8+；插入图片时需要 Pillow |
| .doc 转换 | Windows + Microsoft Word（COM） |
| 刷新目录 / 页码 | Windows + Microsoft Word（COM），或手动按 F9 |
| 字体 | 系统需有 宋体（SimSun）、黑体（SimHei）、Times New Roman |

pip install pywin32 Pillow

非 Windows 平台：build_docx.py 与 word_style.py --method ooxml 完全可用；.doc 转换与目录刷新请用 LibreOffice 或 Word 手动完成。

命令行参数（build_docx.py）

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| --content | 必填 | 内容稿路径 |
| --out | 必填 | 输出 .docx |
| --template | assets/blank.docx | 模板 .docx/.doc |
| --font / --font-ascii | 宋体 / Times New Roman | 中文 / 西文字体 |
| --body --h1 --h2 --h3 | 12 / 16 / 14 / 12 | 字号（pt） |
| --table-size | 10.5 | 表格字号 |
| --caption-font --caption-size | 黑体 / 9 | 题注字体字号 |
| --color | 000000 | 默认字体颜色 |
| --title | — | 封面题目（模板含题目占位时替换） |
| --no-update-toc | — | 不调用 Word COM 刷新目录 |

许可证

MIT。使用时请保留版权声明。

贡献

欢迎提 Issue / PR。提交前建议跑一遍 examples/ 验证脚本可用。