doc-forge/docs/需求与设计/02-模板格式规范.md

模板格式规范

一、对用户（模板提供方）的要求

必须遵守

要求	说明
标题样式	需要 AI 生成的段落，其标题必须应用 Word 内置标题样式（Heading 1~3）
段落独立性	每个标题段落的内容应当主题独立，方便 AI 分别生成

强烈建议

建议	说明
正文提供参考内容	标题下的现有文本可作为 AI 生成的上下文，建议保留
表格上方有说明文字	表格前最好有一段文字说明，方便定位表格归属
文件名中文	模板文件名建议用中文，方便识别

不约束

项	说明
字体/配色/布局	不限，导出时完全保留
页眉页脚	不限，导出时完全保留
图片	不限，解析时保留占位，导出时保持不动
封面/附录	不限，不作为段落处理，导出时保留

二、解析规则（面向开发）

2.1 段落检测算法

for each paragraph in document.paragraphs:
    style = paragraph.style.name
    
    if style starts with "Heading":
        → 新段落开始
        → style 等级 = heading level (1~6)
        → 该段落为「标题段落」
    elif style is "Normal" or None:
        → 属于上一个标题段落的「正文内容」
        → 追加到 paragraph.content
    elif paragraph is inside a table cell:
        → 属于表格内容，跳过段落检测

2.2 表格归属

当前检测到的表格 → 归属于最近的标题段落
if 无标题段落:
    → 独立成段，段名 = "表格_{序号}"

2.3 样式捕获字段

对每个标题段落，捕获以下样式信息：

{
  "font": {
    "name": "等线",
    "eastAsia": "等线",
    "size": 16,
    "bold": true,
    "italic": false,
    "color": "000000"
  },
  "paragraph": {
    "alignment": "CENTER",
    "spaceBefore": 12,
    "spaceAfter": 6,
    "lineSpacing": 1.5,
    "firstLineIndent": 0
  },
  "headingLevel": 1
}

2.4 表格样式捕获

{
  "rows": 5,
  "cols": 6,
  "gridSpan": {},
  "cellStyles": [
    {
      "font": {"name": "宋体", "size": 10.5, "bold": false},
      "shading": "D9E2F3",
      "alignment": "CENTER",
      "borders": {"top": "single", "bottom": "single", "left": "single", "right": "single"}
    }
  ],
  "tableWidth": 5000
}

三、AI 输出解析规则

3.1 强制输出 JSON

在 prompt 末尾附加：
请以 JSON 格式返回，不要包含任何其他说明文字。
{
  "content": [
    {"type": "text|table", ...}
  ]
}

3.2 JSON 解析

收到 AI 响应后：
1. 尝试解析为 JSON
2. 若解析失败，尝试从响应的 ```json ``` 代码块中提取
3. 若仍然失败，将整个响应作为纯文本处理（type=text）

3.3 表格插入

当 type=table:
1. 在原始 docx 中找到该段落后面的第一个表格占位
2. 删除占位表格的 XML 节点
3. 创建新表格（python-docx add_table）
4. 逐格填充数据
5. 应用模板中该位置的表格样式（边框、底纹、对齐）

四、段落编辑方式

人工编辑

• 段落内容完全由用户手动输入
• 不参与 AI 生成流程
• 导出时保留用户输入的内容

AI 生成

• 参与 AI 生成流程
• 可配置：生成模型、提示词、参考文件、输出格式
• 生成后可在预览编辑页手动修改