你手上有份稿子，想让 AI 帮你排版。
于是你说：「帮我排个版。」
然后就没有然后了。字号多大、什么字体、页边距多少、行距几倍、页码放哪儿、标题分几级 —— 这些你一条都没说。不是你不说，是你不知道该怎么说。 你不是排版专家， 这些词你听过，但说不清。
直接把稿子丢给助手，等于给了它一个几乎没有边界的活儿。它不知道你要什么，只能自己猜； 猜错了不一定吭声，换个方式接着猜 —— 一版不满意、改一版还不满意，来回几轮， 时间花了、token 烧了，最后交给你那份，可能还不如原稿顺眼。
根子不在 AI 不会排版，也不在你不懂排版，在于没有一个落地的标准。
doc-format 就是挡在「直接动手」之前的那一步。
它不是让 AI 现场发挥，后端是写好的。 该问哪些项、每项的标准值是多少、值从哪来， 都固化成脚本和预设了。所以你不用懂排版术语，也不用担心它拿你的 token 去反复试错 —— 它先把规格问清楚、确认掉，看到确定的结果之后，才动手。
它不拿到文件就改。
而且它会成长。 你第一次填的那套参数会存成你自己的预设，下次一句话调出来； 跑出问题它当面告诉你，你决定修的那条，修完记进清单 —— 之后再遇到同类问题，它先查清单。 它不是一个用完就走的工具，是一个越用越顺手的 skill。
-
你不懂排版，也能拿到合格的文件。 内置六套中文排版预设，每一套都写清了字号、字体、 行距、页边距、页码的来处与核验日期：
预设 依据 党政机关公文 GB/T 9704-2012（国标） 学位论文 GB/T 7713.1-2025（校级模板优先） 学术论文 GB/T 7713.2-2022 + 参考文献 GB/T 7714-2025 中文图书 出版社惯例 商务报告 行业惯例 微信公众号 平台惯例 -
手上有一份别人排好的文件，可以照着来。 给它一份现成的 Word，它能读出现用的字体、 字号、行距、页边距、表格对齐，先告诉你「你现在用的是这样」，再存成你自己的预设。
-
你单位有自己的规矩，说一次就够。 它逐项跟你确认，然后存成一份自定义预设； 下次直接说预设名就行。
-
已有的 Word 想换排版：只换样式，一个字不动。 段落文字、表格内容、图片全部原样保留。
-
一段粘过来的文字也能排。 不管来源是 Markdown、Word，还是聊天里直接贴的一段话， 它先读结构、跟你确认分节和标题，再动手。
-
出 Word、PDF、公众号 HTML 三种成品。
-
生成之后逐条核对，报告写明「已落实 / 跳过 / 失败」，跳过也会说清为什么。
- 不替你写内容、不改措辞、不做美化装饰。它只管排版规格，以及规格有没有真的落实。
- PDF 和图片改不了排版 —— 这是格式本身的限制，不是它偷懒。它会直说，并给你替代路径。
- 你那份稿子的原始文件永远不会被改动，输出永远是新文件。
整个文件夹放在哪儿都行 —— 脚本靠自己在磁盘上的位置找预设和参考文档，不需要改配置。
只要做一件事：让你用的 agent 能找到这个文件夹。
| 你在用什么 | 放到这里 | 一行命令（把 <你的目录> 换成实际路径） |
|---|---|---|
| Codex | ~/.codex/skills/doc-format |
ln -s <你的目录>/doc-format-skill ~/.codex/skills/doc-format |
| Claude Code | ~/.claude/skills/doc-format |
ln -s <你的目录>/doc-format-skill ~/.claude/skills/doc-format |
其他支持 SKILL.md 的 agent |
该 agent 的 skills 目录，看它的文档 | 同上，换个目标路径 |
| 不装也行 | —— | 直接把 SKILL.md 的路径发给 agent，让它照这个流程做 |
Windows 没有 ln -s，把文件夹直接复制过去即可。
-
Python 3.9 或更高（开发环境用的是 3.10）。
-
三个 Python 库：
pip3 install python-docx PyYAML PyMuPDF
-
出 PDF 需要 LibreOffice。脚本会自己找：先在
PATH里找soffice， 再依次试 macOS 的应用程序目录、Linux 的包管理 / Snap / Flatpak、Windows 的 Program Files。 找不到会明确告诉你，不会闷声失败。 -
（可选）联网：只用于查国标有没有换版。不联网也能用，只是预设的时效性要你自己留意。
不用记命令，用大白话说你要什么就行。比如：
- 「把这本 Markdown 书排成 Word，32 开，要页码」
- 「按党政机关公文的标准，把这份稿子做成红头文件，出一份 Word 和一份 PDF」
- 「我这有个 Word，排版太乱了，帮我按学位论文的格式重排一遍」
- 「我要发公众号，把这篇 Markdown 转成能直接粘进公众号编辑器的 HTML」
- 「我单位有自己的排版要求，以后都按这个来」——它会把你的规格存成预设
遇到它需要知道才能往下做的事（纸张多大、字体装没装、页眉放什么、这篇稿子怎么分节）， 它会停下来问你，并且给你推荐值。它不会自己替你拍板。
doc-format-skill/
├── SKILL.md # 唯一入口：主流程、硬规则、反模式、验证清单
├── README.md # 本文件：安装与文件摆放
├── references/ # 参考文档（流程中按需读取）
│ ├── standards.md # 国标核验记录 + 时效声明
│ ├── spec-schema.md # 规格卡字段定义与校验规则
│ ├── fonts.md # 字体记忆、获取优先级、授权清单、排字坑
│ ├── carriers.md # Word / PDF / HTML 三种载体的能力差异
│ ├── markdown-rules.md # Markdown 规范化规则
│ ├── known-issues.md # 已知问题清单：现象 → 根因 → 处理 → 状态
│ └── presets/ # 六类内置预设，每个都带时效声明（随 skill 一起更新）
├── assets/
│ ├── icon.svg # 图标矢量源文件（改完用无头 Chrome 重新导出 PNG）
│ ├── icon.png # 图标成品：256×256 透明底，供 App / 文档引用
│ └── spec-template.yaml # 规格卡填空骨架
└── scripts/ # 全部是独立脚本，可单独运行，也可被别的流程调用
├── spec_lib.py # 公共库：读规格、字号换算、字体检测、表格与标题计算
├── extract_source.py # 任意输入 → 保序草稿
├── infer_structure.py # 推断标题层级，列出待确认项（不生成文件）
├── structure_check.py # 生成前的结构确认闸门
├── typo_check.py # 错别字与用词检查
├── md_normalize.py # Markdown 规范化（标点、空格、软换行）
├── spec_check.py # 规格体检（冲突、载体、字体、预设时效）
├── font_check.py # 字体可用性检查 + 获取决策树
├── check_standard_updates.py # 联网复查国标现行性
├── inspect_docx.py # 反推现有 Word 的规格
├── convert_docx.py # 现成 Word 重新套规格（内容不变）
├── build_docx.py # Markdown → Word
├── build_pdf.py # Word → PDF（含中文字体安装与内嵌核对）
├── build_html.py # Markdown → 内联样式 HTML（公众号用）
├── render_preview.py # 产物渲染成图片供肉眼核对；看完用 --clean 删掉
├── verify_output.py # 产物合规校验（Word / PDF / HTML）
├── save_preset.py # 把本次规格存成用户预设
└── user_data.py # 告诉你「用户数据存在哪、该往哪个文件写」
上面那棵目录树是「出厂规则」，只读。 它随 skill 版本发布，你改了下次更新就没了。 你自己产生的东西一律放用户数据目录：
~/.local/share/doc-format/ ← 用户数据根目录（环境变量 DOC_FORMAT_HOME 可覆盖）
├── presets/ 你存的排版预设
├── known-issues.md 你遇到的问题与处置
├── standards.md 你自己核验或更正过的标准
└── fonts.md 你自己查到的字体授权与排字坑
~/.cache/doc-format/font-memory.json 字体装没装的记忆（缓存，删了下次自动重建）
规矩三条：读的时候两层都读（出厂 + 你的）、写只写用户目录、冲突以你那份为准。 所以升级 skill、换 agent、重装，都不会覆盖你攒下的任何东西。
不知道该往哪个文件写、目录在哪，问它就行：
python3 scripts/user_data.py # 总览：目录在哪、哪些文件已经有了
python3 scripts/user_data.py --path known-issues.md # 该写哪个文件（父目录会建好）生成出来的 Word 里中文变成方框或另一种字体。 这台电脑缺规格要求的那款字体（比如「宋体」「仿宋_GB2312」是商业字体，Mac 上通常没有）。 脚本不会偷偷拿别的字体顶上，它会告诉你两条路：装上那款字体，或者从你机器上已有的同类字体里挑一个。
出 PDF 时报「找不到 LibreOffice」。 这只影响 PDF，Word 文件已经生成好了，能正常打开。装上 LibreOffice 再重跑一次就行：
- macOS：
brew install --cask libreoffice，或去官网下 dmg 拖进「应用程序」 - Windows：去官网下载安装包，装到默认位置
- Linux：
sudo apt install libreoffice（Fedora 用sudo dnf install libreoffice）
装完不用改任何配置。如果已经装了还报找不到，说明它装在非常规位置， 在那个程序前面加一个环境变量指过去即可：
DOC_FORMAT_SOFFICE=/你的路径/soffice python3 scripts/build_pdf.py --input x.docx --output x.pdf填错了也没关系：脚本会先确认那个文件是不是真的 LibreOffice，不是就告诉你一声， 然后继续自己找，不会拿一个别的程序硬跑。
换了一台电脑，之前存的自定义预设还能用吗？
能用，预设文件在你自己电脑的 ~/.local/share/doc-format/presets/ 里，跟着你的用户目录走。
但字体要在新电脑上重新确认一次 —— 预设存的是字体名，不含「这台机器装没装」。
我在 skill 目录里改了预设 / 记了笔记，更新之后不见了？
skill 目录是「出厂规则」，git pull 会整体替换，改在那儿的东西必然被覆盖。
把要长期留着的东西放进用户数据目录（python3 scripts/user_data.py 会告诉你放哪）；
想改内置预设，就把那份预设另存到 ~/.local/share/doc-format/presets/ 下同名文件，它会自动覆盖内置的那份。
预设里的国标会不会过期？
每条预设都写了核验日期与复检期限。超过期限，或者标准换版了，
先要出处（标准原文 / 学校单位模板 / 期刊须知），拿不到就联网复查，确认后把结论写进你自己那份标准核验记录
（python3 scripts/user_data.py --path standards.md 会告诉你放哪）。
要改的是内置预设本身，就另存一份到用户预设目录再改，别直接改出厂文件。
我想让它按我单位的规矩排，每次都一样。 把要求告诉它，它会逐项跟你确认，然后存成一份自定义预设。下次直接说预设名就行。 每个预设必须有唯一的名字，重名会被拒绝并自动加序号，不会覆盖已有的。
- 流程、硬规则、反模式、验证清单：全在
SKILL.md，先读这一份。 - 踩过的坑：
references/known-issues.md，每条写清「现象 → 根因 → 处理 → 状态」。 出了新问题先查这里，是已知问题就直接引用，不重复排查。 只有你决定修的那一条才记进来；你说不修的，它不记 —— 不认为那是问题，记了只是噪音。 每次出问题它仍然会查一遍这张表、并且当面告诉你，不会放过。 - 脚本都带详细中文注释，每一行都写了「做什么、为什么这样做」。