# 文档排版用法指南：让 agent 写出格式精确的 Word

> 适用对象：用 KHY OS 让 AI 生成论文、报告、说明书等需要**精确排版**的 Word 文档的用户。
> 一句话：**你（或模型）只写内容，格式交给模板。** 字体、字号、页边距、行距、换页全部
> 由样式模板确定性决定，模型不碰任何排版代码。
>
> 设计原理见 [DESIGN-ARCH-023]；实现见 [IMPL-RPT-023]。

---

## 0. 为什么不直接让模型写 docx / LaTeX？

因为模型对"格式代码"的输出**不稳定**：同一个"加粗标题"意图，它这次写 `\textbf`、下次写
`**`、再下次写 `<b>`；中文字体常漏 `eastAsia` 属性导致整篇回退成默认字体。**只要格式决策
留在模型手里，排版就无法复现。** KHY OS 的做法是把格式收归"样式模板"，模型只输出语义结构。

---

## 1. 最快上手

让 AI 调用 `renderDocument` 工具（别名 `typeset_document` / `render_docx` / `create_paper`），
只需给两样东西：**语义内容**（Markdown）+ **模板名**。

```jsonc
// renderDocument 的入参
{
  "content": "# 引言\n\n这是正文，包含 **重点**。\n\n## 方法\n\n- 步骤一\n- 步骤二",
  "template": "gbt7714",                 // 国标中文学术；可选 default / ieee
  "title": "基于 X 的 Y 研究",            // 可选，用模板标题样式渲染
  "outputPath": "~/Desktop/paper.docx"   // 限项目目录或家目录子树
}
```

产物就是排好版的 `.docx`：一级标题黑体三号居中、正文宋体小四 1.5 倍行距首行缩进 2 字符、
A4 页面、页脚页码——**全部来自模板，无需你指定一个字号**。

---

## 2. 三套内置模板

| 模板名 | 适用 | 关键样式 |
|--------|------|----------|
| `default` | 通用 A4 文档 | 完整基线，中性字体；其它模板都叠加在它之上 |
| `gbt7714` | 国标 GB/T 7714 中文学术（学位论文/期刊） | H1 黑体三号(16pt)居中**前自动换页**；正文宋体小四(12pt) 1.5 倍行距首行缩进 2 字符；参考文献宋体五号悬挂缩进 |
| `ieee` | IEEE 英文会议/期刊 | Times New Roman 正文，标题加粗分级，紧凑行距（单栏近似；双栏需后处理） |

不填 `template` 默认用 `default`。

---

## 3. 内容怎么写（语义，不是格式）

### 3.1 Markdown（推荐，最自然）

| 想要 | 写法 | 说明 |
|------|------|------|
| 各级标题 | `# 一级` `## 二级` `### 三级` | 层级映射模板的 heading1~4 样式 |
| 正文 | 直接写；空行分段 | 同段换行会合并为一段 |
| 加粗 / 斜体 | `**重点**` / `*强调*` | 这是**语义**标记，由模板用强调字体渲染 |
| 列表 | `- 项` 或 `1. 项` | 有序/无序 |
| 引用 | `> 引文` | 引文样式 |
| 表格 | `| A | B |` + `| --- | --- |` + 数据行 | 标准 Markdown 表 |
| 代码 | 用 ``` 围栏 | 等宽渲染，正文原样不解释 |
| **换页** | 单独一行 `[[newpage]]` | 见 §4 |

### 3.2 文档 AST（需要精确结构时）

复杂结构（图片、参考文献条目）可直接给 AST JSON：

```jsonc
{
  "blocks": [
    { "type": "heading", "level": 1, "text": "结论" },
    { "type": "paragraph", "runs": [
        { "text": "总体表现" }, { "text": "显著", "bold": true }, { "text": "优于基线。" } ] },
    { "type": "figure", "path": "./fig1.png", "caption": "图 1 系统架构" },
    { "type": "pagebreak" },
    { "type": "reference", "entries": [
        "[1] 张三. 论文标题[J]. 期刊, 2024, 12(3): 1-10." ] }
  ]
}
```

可用块类型：`heading` / `paragraph` / `list` / `table` / `quote` / `code` / `pagebreak` /
`figure` / `reference`。

---

## 4. 换页：只用确定性 API，别插空行

换页**只**认这三种来源，其余一律不换页：

1. Markdown 单独一行 `[[newpage]]`（或 `<<<pagebreak>>>`）；
2. AST 里的 `{ "type": "pagebreak" }` 块；
3. 模板策略：`gbt7714` 默认**每个一级标题前自动换页**。

> ⚠️ 多打几个空行**不会**换页，`---` 水平线也**不会**换页——这是刻意设计，避免"靠空白
> 占位"的不确定排版。

---

## 5. 自定义格式：两种方式

### 5.1 临时微调：`overrides`

只改一两个键、不想另写模板时，传 `overrides` 深合并到所选模板之上：

```jsonc
{
  "content": "…",
  "template": "gbt7714",
  "overrides": { "paragraph": { "lineSpacing": 2.0 } },   // 改成 2 倍行距，其余不变
  "outputPath": "paper.docx"
}
```

### 5.2 自定义模板文件

把一份 JSON 模板存到任意位置，`template` 传它的**绝对路径**即可。模板会自动叠加在
`default` 基线上，所以你**只需写要改的键**。最小示例：

```jsonc
// ~/my-style.json
{
  "name": "my-style",
  "label": "我的公司报告风格",
  "paragraph": { "lineSpacing": 1.25, "firstLineIndentChars": 0 },
  "fonts": {
    "heading1": { "ascii": "Arial", "eastAsia": "微软雅黑", "size": 18, "bold": true, "align": "left", "color": "1F4E79" },
    "default":  { "ascii": "Calibri", "eastAsia": "微软雅黑", "size": 11 }
  }
}
```

```jsonc
{ "content": "…", "template": "/home/me/my-style.json", "outputPath": "report.docx" }
```

模板字段速查：
- `page`：`size`(A4/Letter)、`margins`(top/bottom/left/right + unit:cm)、`footer.pageNumber`
- `paragraph`：`lineSpacing`、`lineSpacingRule`(multiple/exact)、`spaceBefore/After`、`firstLineIndentChars`
- `fonts.<key>`：`ascii`、`eastAsia`(中文字体，**必填否则中文回退**)、`size`(pt)、`bold`、`italic`、`align`、`color`(十六进制)、`pageBreakBefore`
  - key 包括 `default`/`title`/`heading1~4`/`quote`/`code`/`caption`/`reference`/`list`/`tableCell`
- `pagination.pageBreakBeforeHeading1`：是否每个一级标题前自动换页

中文字号 → pt 对照：二号 22 / 三号 16 / 小三 13 / 四号 14 / 小四 12 / 五号 10.5。

---

## 6. 中文支持要点

渲染器对**每一个 run 都强制写 `eastAsia` 中文字体**，并在写后校验阶段再次核查、对漏设的
run 自动打补丁——所以你用 `gbt7714` 或任何设了 `eastAsia` 的模板，中文都不会回退。
自定义模板时务必给每个 `fonts.<key>` 填 `eastAsia`（如"宋体"/"黑体"/"微软雅黑"）。

---

## 7. 排错

| 现象 | 原因 | 解决 |
|------|------|------|
| `Structured-content check failed: … forbidden LaTeX/HTML …` | 内容里夹了排版代码（`\textbf`、`<b>` 等） | 删掉，改用 Markdown 语义或模板控制格式 |
| `Unknown style template "xxx"` | 模板名拼错 | 用 `default`/`gbt7714`/`ieee` 或自定义模板绝对路径 |
| `Refused to write …` / 路径相关错误 | 输出路径越界 | 写到项目目录或家目录（Desktop/Documents/Downloads）子树内 |
| 工具不可用 | 缺 python 或 python-docx | 安装 `pip install python-docx`；`khy preflight` 体检 |
| 中文变方框/回退 | 自定义模板某 font 漏 `eastAsia` | 给该 font 补 `eastAsia` 字体名 |

---

## 8. 与旧 `createDocument` 的区别

`createDocument` 把文本按行裸塞、无样式控制，适合"随手存个 txt 转 docx"。
要**精确排版**（论文/正式报告）一律用 `renderDocument`。两者并存，互不影响。
