thesis-format

论文 Word 文档格式合规审查与修复。

When to Activate

• 用户要求检查/审查/修复论文 docx 的格式合规性
• 用户提到"格式规范"、"模板对齐"、"格式审查"、"论文格式"、"排版检查"
• 用户提供了模板 Word 和目标 Word，要求对比格式
• 用户要求将论文格式对齐到某个模板标准

Core Workflow

输入：
  必选：模板 Word + 目标 Word
  可选：--supplementary-specs（补充规范文件/目录）
        --hints（问题报告/指导意见文件/目录）
  ↓
Phase 1: 提取规范（6 个并行 Agent）
  → format_specs/*.md（每个类别一个文件）
  ↓
Phase 1.5: 规范合并（如有 --supplementary-specs）
  → 将补充规范 patch 到 format_specs/ 对应文件
  → 冲突时补充规范覆盖主模板，属性标注来源
  ↓
Phase 2: 并行审查（N 个 Agent，全量采集 + 全量判断）
  → 主对话预写数据采集脚本，输出全量属性表
  → Agent 读取全量数据 + 规范 + hints，逐段判断
  → 审查报告（合规项 + 不合规项 + hint 确认）
  ↓
⚠ 用户确认门控（必须）
  ↓
Phase 3: 顺序修复（按修复类型分组）
  → 修复后文档 + 验证报告
  ↓
Phase 4: 交叉验证
  → PDF 视觉检查确认

角色分工

• 主对话：编排者 — 撰写提示词、预写采集脚本、审查结果、做决策、汇总修复方案
• 子 Agent：审查决策者 — 读取全量数据 + 规范，逐段判断合规性，发现语义层面问题
• 脚本：数据采集器 — 全量提取段落属性，输出紧凑表格供 Agent 判断
• 用户：确认修复方案、提供补充规范/问题报告、人工检查无法自动化的项

核心原则

脚本是数据采集器，Agent 是审查决策者。 脚本只负责从 docx XML 提取原始属性值；Agent 负责理解上下文、判断合规性、发现脚本无法捕捉的语义层面问题。 全文覆盖，逐段判断，不留盲区。

主对话不直接写代码，所有 python-docx 操作交给子 Agent。

Phase 1: 提取格式规范

从模板 Word 文件中提取格式规范，按类别分文件存放到 format_specs/ 目录。

并行 Agent 分工（6 个）

每个 Agent 的工作内容

1. 用 python-docx 读取模板 Word 中对应区域的段落和样式
2. 从 XML 层提取东亚字体、ASCII 字体、字号、加粗、间距、缩进等属性
3. 同时读取段落文本中的说明文字（模板内嵌的格式说明/气泡框）
4. 按 templates/spec-file-template.md 的统一格式输出

提取的核心属性

对每个格式元素，提取以下属性的三层值（样式定义、段落级覆盖、run 级覆盖）：

属性级打卡表

对每种元素类型，Agent 必须对上表列出的全部 9 个属性逐段检查，标注 PASS / SKIP / FAIL。禁止跳过任何属性。

各元素类型的检查要求

标记：V = 必检 | C = 条件检（模板有要求时必检，否则标 SKIP）| — = 不适用

标题逐级独立检查：一级/二级/三级标题的每个属性必须独立提取、独立比对，不允许假设"上级属性适用于下级"。 C（条件检）：模板中该属性有明确值 → 必检；模板未设置（继承上级样式）→ 跳过标 SKIP。C 列不得标 PASS，只能是 SKIP 或 FAIL。 编号格式额外检查：标题和参考文献条目的编号需检查 w:numPr（Word 自动编号）与手动编号（如 [n]、第X章）是否冲突，冲突标 FAIL。

级间关系验证

属性打卡完成后，额外执行以下验证：

1. 级间递减：一级标题字号 ≥ 二级 ≥ 三级 ≥ 正文（违反标 WARNING）
2. 同级一致性：所有同级标题的 9 个属性必须完全一致（不一致标 WARNING）
3. 语义审查（与属性打卡等权重，不可跳过）：
   • 样式名与文本内容是否语义一致
   • 同一段落内不同 run 是否混用不同字体
   • 段落顺序是否正确（图题在图之后）
   • 残留空白段落

Phase 1.5: 规范合并

当用户提供了 --supplementary-specs 时，将补充规范合并到 Phase 1 提取的 format_specs/ 中。

补充规范的格式

补充规范文件使用与 templates/spec-file-template.md 相同的格式。文件名应与对应的主规范文件匹配（如补充标题格式 → 05_标题格式_补充.md）。

合并规则

1. 按类别匹配：补充文件的属性 patch 到 format_specs/ 中对应类别的文件
2. 属性级覆盖：同一属性存在时，补充规范覆盖主模板值（补充规范通常更新、更具体）
3. 来源标注：合并后每个属性标注来源 — [主模板] / [系部补充] / [导师规范] / [历史审查]
4. 新增属性：补充规范中的新属性（主模板未涉及的）直接追加

合并时机

Phase 1 全部完成后、Phase 2 启动前。合并由主对话执行（读取两方文件 → 生成合并后的 format_specs/）。

Phase 2: 并行审查（全量采集 + 全量判断）

对目标文档发起 N 个并行审查 Agent。每个 Agent 对照一类规范文件检查。

全量审查保障

禁止抽查，必须全文覆盖。 具体机制：

1. 主对话预写数据采集脚本：在启动 Phase 2 之前，主对话为每个审查区域编写 python-docx 全量采集脚本
2. 脚本输出紧凑属性表格：每段一行（索引、样式名、字体、字号、间距、对齐、缩进），保证全覆盖
3. Agent 提示词明确约束："以下是该区域全部 N 段的格式数据，请逐段判断，禁止抽查"
4. Agent 额外负责语义审查：识别"这段文本看起来像标题但样式名不对"等脚本无法捕捉的问题

Agent 分配策略

根据目标文档实际内容裁剪审查范围：

如果目标文档无目录、无附录、无表格，则跳过对应 Agent。

Hints 注入

当用户提供了 --hints 时：

1. 每个 Agent 启动时额外读取 hints/ 中与自身审查区域相关的条目
2. 对 hint 条目优先检查并报告：已确认违规 / 已确认合规 / 需人工确认
3. hint 文件格式参考 templates/hint-file-template.md

Agent 审查工作方式

Agent 输入：
  1. 规范文件（标准值） — 来自 format_specs/（已合并补充规范）
  2. 全量属性表（当前值） — 由主对话预写的采集脚本输出
  3. Hint 条目（如有） — 优先检查项
  4. common-issues.md — 已知问题模式参考
       ↓
Agent 逐段判断：
  - 属性打卡（逐段逐项，禁止跳过）：
    - 东亚字体 / 西文字体 / 字号 / 加粗 / 对齐 / 段前间距 / 段后间距 / 行距 / 首行缩进
    - 每个属性标注 PASS（合规）/ SKIP（不适用）/ FAIL（不合规）
    - 标题按级别独立比对，额外执行级间递减验证和同级一致性验证
  - 语义审查（与属性打卡等权重）：
    - 样式名与文本内容是否语义一致（如"第一章 绪论"是否使用了标题样式）
    - 同段落内不同 run 是否混用不同字体
    - 段落顺序是否正确、是否有残留空白段落
  - Hint 确认：对每个 hint 条目明确给出结论
       ↓
Agent 输出：结构化审查报告

统一审查输出格式

## [类别] 审查结果

### 合规项
（简要列出）

### 不合规项
| # | 属性 | 段落索引 | 当前值 | 标准值 | 严重度 |
|---|------|---------|--------|--------|--------|

> 同一段落可出现多行，每行对应一个不合规属性。属性列使用"属性级打卡表"中的 9 个属性名。

### 语义问题
（脚本无法检测但 Agent 发现的问题，如样式错用）

### Hint 条目确认（如有）
| # | 问题描述 | 结论 | 证据 |
|---|---------|------|------|

### 无法自动检查的项
（需人工确认）

主对话汇总

收集所有审查结果后，主对话：

1. 按严重度分类（严重/中等/轻微）
2. 合并同类修复（如多个标题共用一个样式覆盖问题）
3. 生成修复分组方案

⚠️ 用户确认门控（必须）

修复前必须等待用户确认。 格式修复直接覆盖原文件，错误修复比不修复更危险。输出审查汇总表 + 修复分组方案后，暂停等待用户说"确认"/"执行"再进入 Phase 3。用户可能排除某些修复、调整优先级、或要求先备份。

Phase 3: 顺序修复

修复分组原则

• 样式级修复优先：修改样式定义 → 批量生效（如 Heading 1 字号）
• 同文件不能并行写：目标 docx 同一文件，修复 Agent 必须顺序执行
• 每组一个 Agent：每次打开文件→修改→保存→验证

典型修复分组

修复操作要点

参考 references/check-methods.md 中的代码片段和 references/common-issues.md 中的修复方法。

修复硬约束

1. 图片保护：修复过程中绝对不能删除图片/绘图元素（InlineShape、w:drawing、wp:anchor）。修复前后必须验证图片数量一致。
2. 精确操作：修复 Agent 必须使用 python-docx 精确 XML 操作（定位段落索引 → 修改特定属性），禁止整文件 Document.save() 全量覆盖（防止丢失图片、分节符等元素）。
3. 操作后验证：每组修复完成后立即验证修改项 + 图片数量 + 段落总数。

批量修改模式（可选）

当用户一次性提供多项修改需求时，按优先级排序后逐项执行：

用户输入示例：
"请执行以下修改：
1. 检查所有表格是否为三线表，缺失的补上
2. 统一引用编号为 [n] 格式
3. 确认所有图片完整"

Agent 执行方式：
逐项执行 → 每完成一项汇报结果 → 全部完成后做最终验证

关键：python-docx 修改 docx 时注意三层覆盖关系：

1. 样式定义（doc.styles['Heading 1']）— 最低优先级
2. 段落级属性（pPr 内的 rPr、spacing、ind）— 中优先级
3. run 级属性（rPr 内的 rFonts、sz、b）— 最高优先级

修复时需三层全部清理，否则样式定义无法生效。

Phase 4: 交叉验证

修复后执行：

1. 结构验证（python-docx）：检查 InlineShape 数量、图题完整性、段落总数
2. 格式抽查（python-docx）：对每类修复项抽查 3-5 个段落
3. PDF 视觉验证（LibreOffice 转换后逐页检查）：

   soffice --headless --convert-to pdf "目标.docx" --outdir output/

References

• references/check-methods.md — python-docx 数据采集代码片段（全量提取段落属性）
• references/common-issues.md — 常见格式问题与修复方法速查表
• templates/spec-file-template.md — 格式规范文件的统一模板
• templates/hint-file-template.md — 问题报告/指导意见的统一模板