Word 文档生成
把内容写成 Markdown，剩下的排版交给脚本——不要用 python-docx 手写排版代码。
环境准备
pip install python-docx
用法
python scripts/build_docx.py --input 报告.md -o 报告.docx \
--title "2026 年第三季度经营分析报告" \
--subtitle "经营分析部 · 内部资料" \
--author "经营分析部" --org "XX 零售有限公司" \
--cover --toc
| 参数 | 说明 |
|---|---|
--input |
.md 或 .json |
-o |
输出 .docx 路径 |
--title |
文档标题，用于封面与页眉；不给则取正文第一个 # 一级标题 |
--subtitle / --author / --org / --date |
封面信息 |
--cover |
生成独立封面页 |
--toc |
插入目录域 |
--body-size |
正文字号，默认 12（小四） |
--no-page-number |
不显示页脚页码 |
支持的 Markdown
| 写法 | 效果 |
|---|---|
# ~ #### |
一到四级标题（微软雅黑加粗，深蓝 #1F3A5F） |
| 普通段落 | 宋体小四、1.5 倍行距、首行缩进 2 字符 |
- / * |
无序列表 |
1. |
有序列表 |
\| a \| b \| + 分隔行 |
表格（表头深蓝底白字，数字列右对齐） |
> |
引用块（灰色、左缩进） |
``` 代码块 ``` |
等宽字体、浅灰底纹 |
**加粗** / `代码` |
行内格式 |
--- |
分隔线 |
数字列会自动右对齐（识别 1,234、12.4%、-56 这类），不需要手工处理。
JSON 输入格式
需要精细控制时用 JSON：
{
"title": "文档标题", "subtitle": "副标题", "author": "作者",
"org": "单位", "cover": true, "toc": true,
"blocks": [
{"type": "h1", "text": "第一章"},
{"type": "p", "text": "正文，支持 **加粗**。"},
{"type": "ul", "items": ["要点一", "要点二"]},
{"type": "ol", "items": ["第一步", "第二步"]},
{"type": "table", "header": ["列A", "列B"], "rows": [["1", "2"]]},
{"type": "quote", "text": "强调内容"},
{"type": "code", "text": "等宽文本"},
{"type": "hr"},
{"type": "pagebreak"}
]
}
工作流
- 先问清三件事：给谁看（决定正式程度）、要不要封面、要不要目录
- 把内容写进
.md（正文用什么语气由用户定，脚本只管排版） - 跑脚本生成
.docx - 告诉用户目录需要按 F9 更新——这是 Word 域机制，不是文档坏了
- 需要时把生成的 docx 展示给用户确认
硬约束
- 目录是域，必须提示用户按 F9。不提示的话用户会以为目录是空的。
- 不要在脚本里写死禁用词表、KPI 阈值这类业务规则。脚本只管版式，内容判断交给用户。
- 不要用 python-docx 手搓排版。样式规范已封装在脚本里，手搓会导致同一批文档格式不一致。
- 表格超过 6 列时提醒用户：A4 纸宽 15 cm，7 列以上会挤，建议拆表或转横版。
- 生成的文件名不要用
/ \ : * ? " < > |这些字符。 - 不要在未经用户同意的情况下覆盖已有的 .docx 文件。
进阶
字号字号对照表、中文排版约定、什么时候该用封面/目录见 references/docx-layout-spec.md。
