tfboy1/academic-paper-writer/academic-paper-writer

学术论文专家（主路由）

[!IMPORTANT]

本文件是主路由入口 + Pipeline B/C 定义 + 排版格式规范库。Pipeline A（OCR 管道）的详细规范请参见 ocr_kb/SKILL.md。

所有管道的 DOCX 生成均使用 docx/SKILL.md 中定义的方法（docx-js 创建新文档 / unpack-edit-pack 编辑现有文档）。

0. 目录规范 (Directory Convention)

[!IMPORTANT]

所有中间文件和生成产物必须严格遵守以下目录结构，禁止在项目根目录下放置任何生成文件（包括 .md、.py、.docx 等）。

项目根目录/
├── resources/
│   ├── pages/          # Pipeline A: 切分出的单页 PNG 图片
│   ├── figures/        # 所有管道: 配图（裁剪的或提取的）
│   ├── md/             # 所有管道: 提取/拆分结果
│   │   ├── page_N.md       # Pipeline A 按页
│   │   └── section_N.md    # Pipeline B/C 按章节
│   ├── scripts/        # 所有 Python 辅助脚本（可跨任务复用，清理时不删除）
│   ├── compiled_paper.md  # 最终汇总的完整 Markdown
│   ├── config.json     # 任务配置（源文件、格式、管道类型），整个任务期间不变
│   └── checkpoint.json # 运行时进度（当前单元、计数器、失败项），随处理进度更新
├── outputs/            # 最终交付的 .docx / .bib 文件 + 核查点中间版本
├── ocr_kb/             # Pipeline A: OCR 工作流 Skill
│   └── SKILL.md
├── docx/               # Word 文档操作 Skill（DOCX 生成的技术实现基础）
│   └── SKILL.md
├── pdf/                # PDF 操作 Skill
│   └── SKILL.md
├── content_generation/ # Pipeline D: 论文内容智能生成 Skill
│   └── SKILL.md
├── SKILL.md            # 本文件（主入口路由 + Pipeline B/C + 排版规范库）
└── <source>.*          # 用户提供的原始文件 (.pdf / .doc / .docx / .md / 项目代码目录)

1. 新任务启动协议 (Step 0: Pre-flight)

[!CAUTION]

以下四项检查必须在执行任何写作或排版动作之前全部完成，不可跳过。

1.0 技能版本检查与自动更新 (Version Check & Auto Update)

在每次启动处理时，必须首先对比用户本地的 skill 版本和现在的最新版本：

• 运行相应的命令（如 git fetch origin && git status -uno）检测本地仓库状态。
• 如果本地版本与最新版本不一致：应当主动提示并帮助用户自动更新：

> "检测到 academic-paper-writer-pro 技能存在最新版本，是否需要帮您自动更新？回复 更新 进行升级，或 跳过 继续当前任务。"

• 若用户选择更新，自动执行更新命令（如 git pull 或 npx skills add https://github.com/tfboy1/academic-paper-writer --skill academic-paper-writer-pro），待更新完成后再进入下一步。

1.1 环境清理确认

检测 resources/ 下的 pages/、md/、figures/ 以及 resources/checkpoint.json 是否存在旧文件。

• 若存在旧文件：列出文件清单，明确询问用户：

> "检测到上次任务的中间文件（N 个页面/章节、M 个 Markdown、K 张配图）。是否删除以避免干扰？回复 删除 清空，或 保留 继续上次任务。"

• 若不存在旧文件：跳过此步。
• 用户选择"删除"时：删除 resources/pages/*、resources/md/*、resources/figures/*、resources/checkpoint.json、resources/config.json。resources/scripts/ 不删除（脚本可复用）。
• 用户选择"保留"时：读取 resources/checkpoint.json，进入断点恢复流程（见 §1.3）。

1.2 源文件确认与管道选择

扫描项目根目录下的所有支持格式文件（.pdf、.doc、.docx、.md）：

• 只有 1 个：自动选定，根据扩展名决定管道。
• 有多个：列出所有文件名、类型及大小，要求用户明确指定目标文件。
• 没有：报错，要求用户放入源文件。

管道自动选择规则：

1.3 断点恢复检测

检查 resources/checkpoint.json 是否存在且合法：

• 存在且 `status == "suspended"`：

向用户展示上次进度（已完成单元数 / 总单元数，管道类型），询问： > "检测到上次任务（Pipeline X，已完成 N/M 个单元）。是否从断点继续？回复 继续 从第 N+1 个单元开始，或 重新开始 清空所有中间文件。"

• 不存在或 `status == "completed"`：正常启动新任务。

2. 文件完整性检查与资源准备

2.1 文件完整性检查

要求用户把需要排版的文稿和格式要求放入本目录下：

• 草稿 (Draft)：用户的内容文件（.pdf、.doc、.docx 或 .md）。
• 格式要求 (Style Guide/Template)：.docx 模板或 .pdf 指南（如 IEEE 模板）。
• 参考文献 (References)：询问用户是否有 .bib 文件。如果有，必须优先使用。

2.2 格式规范解析（所有管道必执行）

[!IMPORTANT]

在拆分内容或提取文字之前，必须先完成格式规范解析，确定所有排版参数。

1. 如果用户提供了 `.docx` 模板（config.template_file 非空）：

• 使用 docx/SKILL.md 的 unpack 方法打开模板
• 提取样式定义（标题层级、正文字体/字号、行距、页边距、页眉页脚、分栏设置）
• 将提取到的参数记录到 config.json 的 format_params 字段

1. 如果用户指定了格式名称（如"IEEE"、"APA"）：

• 从本文件 §6 排版格式规范库 中读取对应的预设参数
• 将参数记录到 config.json 的 format_params 字段

1. 如果两者都有：模板优先，预设参数作为兜底。

2.3 资源目录准备

确保 resources/（含子目录 pages/、md/、figures/、scripts/）和 outputs/ 存在，不存在则自动创建。

2.4 任务配置持久化

创建或读取 resources/config.json（详细格式见 ocr_kb/SKILL.md §0.5），记录源文件路径、文件类型、管道类型、格式规范和排版参数，使后续续作无需重复指定。

3. 核心处理流程（按管道分发）

3.1 Pipeline A — OCR 管道（PDF 输入）

[!IMPORTANT]

Pipeline A 的全部详细规范定义在 ocr_kb/SKILL.md 中。本节仅做高层描述。

1. 切图：运行 resources/scripts/split_pdf.py 将 PDF 分割为单页 PNG。
2. 逐页循环：按 ocr_kb/SKILL.md 的规范逐页提取 + 逐页追加 DOCX。
3. 核查与悬挂：每 2 页核查，每 4 页悬挂。
4. 汇总定稿：合并所有 page_N.md → compiled_paper.md → 最终 DOCX。

DOCX 生成方式：使用 docx/SKILL.md 中的 docx-js 创建新文档，按 §6 格式规范库中的参数配置样式。

3.2 Pipeline B — 重排版管道（.doc / .docx 输入）

适用场景：用户已有 Word 文档，需要按新的格式规范（如 IEEE）无损排版。为了绝对保留原文原生复杂公式（OMML）、图表和批注，本管道严禁使用 Markdown 中转提取方案，必须采用底层 XML 外观平移（Unpack-Edit-Pack）。

第一步：格式转换（仅 .doc）

如果输入是 .doc（旧格式），先转换为 .docx：

python docx/scripts/office/soffice.py --headless --convert-to docx <input.doc>

第二步：解包 (Unpack) 与提取规范

1. 按 §2.2 解析目标格式参数。
2. 将输入 DOCX 解压到原生 XML 目录：

python docx/scripts/office/unpack.py <input.docx> resources/unpacked/

第三步：XML 级别样式重构 (Edit XML)

此步骤不触碰主体内容逻辑。编写局部脚本直接从底层“换肤”：

1. 替换 Styles (`word/styles.xml`)：针对格式规范（如 IEEE），将 styles.xml 内的全部核心样式强制替换为预设样式名称及字体。
2. 强制排定 `<w:sectPr>`：在 word/document.xml 内，定位节区配置块，强制挂载双栏设定（如 <w:cols w:num="2" w:space="360"/>）及要求的纸张尺寸（如 US Letter: <w:pgSz w:w="12240" w:h="15840"/>）。
3. 重新绑定 `<w:pStyle>`：遍历所有 <w:p>，通过文字特征或旧样式的权重判定其所属层级，将其挂载为 IEEE 标准的 Heading1、Normal。这确保绝不触碰封装在同层段落内的公式结构 <m:oMath>。

第四步：原貌打包定稿 (Pack)

对重构后的外观进行无缝打包验证：

python docx/scripts/office/pack.py resources/unpacked/ outputs/<name>_final_<date>.docx --original <input.docx>

这彻底废弃了高风险 Markdown 中转生成法，成就 100% 内容与排版无损保留！

3.3 Pipeline C — MD 直转管道（.md 输入）

[!CAUTION]

绝对禁止使用 Pandoc 进行 Markdown 到 Word 的一键直转！

Pandoc 会丢失所有针对中国学位论文或顶会要求的高度定制化格式（如三线表渲染、首行缩进强绑定等）。必须且只能严格调用 `docx/SKILL.md` 中定义的 `docx-js` (Node引擎) 或底层的 unpack -> edit XML -> pack 脚本。

适用场景：用户已有 Markdown 格式的论文，需要转为带格式的 Word 文档。

第一步：格式规范解析

按 §2.2 解析目标格式规范，确定所有排版参数。

第二步：章节拆分

1. 读取 .md 文件，按一级标题（# ...）拆分为多个章节。
2. 每个章节保存为 resources/md/section_N.md。
3. 统计总章节数。
4. 创建 resources/config.json（pipeline: "C", unit_type: "section"）。
5. 创建 resources/checkpoint.json（current_unit: 1，计数器归零）。

第三步：Mermaid 架构图高清预渲染与自愈 (关键)

如果 Markdown 中包含 ```mermaid``` 代码块，在注入 Word 之前，必须执行独立的高清渲染管线：

1. 提取并保存：将 Mermaid 代码块保存为独立的 resources/figures/fig_N.mmd 文件。
2. 挂载环境拦截器：受限于 Windows 严格的进程穿透策略，必须在根目录动态生成 puppeteer-config.json（内容：{"args": ["--no-sandbox", "--disable-setuid-sandbox"]}）。
3. 调用 CLI 编译：执行命令 npx mmdc -i resources/figures/fig_N.mmd -o resources/figures/fig_N.png -b transparent -p puppeteer-config.json。
4. 编译容错自愈 (Auto-healing)：若 mmdc 抛出报错（常因 subgraph 命名含空格、状态标量含括号/单双引号等非严谨语法引起），Agent 必须捕获报错日志，主动运用 Python 或正则修复 `.mmd` 文本内的语法残缺，随后重试编译指令，直至高清 .png 成功产出。严禁在此步骤静默跳过或残留乱码！
5. DOM 占位替换：将 Markdown 原文中的复杂 Mermaid 块一律替换为标准图片引用语法 ![Figure N](resources/figures/fig_N.png)，以便下一步原生嵌入。

第四步：逐章节转换与排版

使用 docx/SKILL.md 中的 docx-js 创建新 DOCX 文档（必须通过代码映射所有样式！），按 §6 的格式参数配置样式，然后逐章节转换内容：

1. 公式转换：

• 行内公式 $...$ → 原生 OMML（通过 ocr_kb/scripts/latex_to_omml.py，接口见 ocr_kb/SKILL.md §0.7）
• 独立公式 $$...$$ → OMML 公式段落，编号靠右对齐
• 更新 checkpoint.json 的 global_equation_count

1. 表格转换：

• Markdown 表格 → Word 表格 XML（按 §5.3 表格排版参数 + docx/SKILL.md Tables 章节，强制输出学术三线表）
• 更新 global_table_count

1. 图片嵌入：

• ![caption](path) → 检查图片文件是否存在
• 将图片复制到 resources/figures/（如不在其中），全局编号
• 按 §5.2 图片排版参数嵌入 DOCX
• 更新 global_figure_count

1. 文本排版：

• 标题层级映射（# → Heading 1，## → Heading 2，...）
• 按 §6 格式参数应用字体、字号、段间距、对齐方式。特别是段落首行缩进（2字符）的精确控制。

1. 追加到输出 DOCX。
2. 更新 checkpoint.json。

第五步：核查与上下文保护

• 与 Pipeline B 完全相同（每 2 章节核查，每 4 章节悬挂）。
• 增加物理拦截：如果检测到没有按要求生成表格数据和足够的页面容量，则报废该生成的 docx。

第六步：汇总定稿

1. 所有 section_N.md 已在拆分时创建，合并为 resources/compiled_paper.md。
2. 最终 DOCX 保存为 outputs/<name>_final_<date>.docx。

3.4 Pipeline D — 内容生成管道（项目记录/代码输入）

适用场景：用户没有完整的论文草稿，只有代码、实验数据或笔记，希望基于现有项目素材智能生成符合学术格式的论文初稿。

详情操作规范见 content_generation/SKILL.md，主要流程概览：

1. 分析用户提供的各种技术素材，提取并与用户确认论文整体大纲结构。
2. 以逐节自回归生成的方式构建高质量学术文本，保存至 resources/md/section_N.md。
3. 系统在生成完毕后，自动将其流转到 Pipeline C（MD 直转管道），复用其排版能力输出最终样式。

3.5 所有管道的通用规则

以下规则不分管道，强制执行：

4. 参考文献管理

• 优先：解析用户提供的 .bib 文件。
• 补充：如果用户未提供 .bib，不要自行编造或搜索文献。标记所有缺失的引用（列出引用标记名），通知用户手动补充。
• 输出：在 outputs/references.bib 中生成参考文献文件。

5. 通用排版细则 (Cross-Pipeline Formatting Details)

[!IMPORTANT]

以下细则适用于所有管道，具体参数受 §6 格式规范库中的预设值或用户模板覆盖。DOCX 的技术实现统一参考 docx/SKILL.md。

5.1 模板文件使用流程

当 config.template_file 非空时：

1. 方式一（推荐）：使用 docx/SKILL.md 的 unpack 方法打开模板，提取 word/styles.xml 中的样式定义，然后用 docx-js 创建新文档时复制这些样式。
2. 方式二：直接复制模板文件为输出文件，然后用 unpack → edit XML → pack 的方式替换内容，保留模板的全部样式和页面设置。

当 config.template_file 为空时：

• 使用 docx-js 创建全新文档，按 §6 格式规范库的预设参数手动配置样式。

5.2 图片排版参数

docx-js 实现参考：docx/SKILL.md Images 章节（§220-232），注意 type 参数必填，altText 三个子字段都必填。

5.3 表格排版参数

docx-js 实现参考：docx/SKILL.md Tables 章节（§173-219），必须同时设置 columnWidths 和每个 cell 的 width，且必须使用 WidthType.DXA。

5.4 页眉页脚与页码

docx-js 实现参考：docx/SKILL.md Headers/Footers 章节（§251-268），使用 PageNumber.CURRENT。

5.5 分栏排版

docx-js 实现：通过 sections 属性设置不同的 section 拥有不同的栏数：

// 标题区域 - 单栏
{ properties: { column: { count: 1 } }, children: [/* 标题、作者、摘要 */] },
// 正文区域 - 双栏
{ properties: { column: { count: 2, space: 360 } }, children: [/* 正文 */] }

5.6 公式排版

docx-js / XML 实现参考：docx/SKILL.md Formulas (OMML) 章节（§447-469）。

6. 排版格式规范库 (Format Style Library)

[!IMPORTANT]

格式预设以独立 .md 文件存放在 templates/ 目录下，每个文件包含完整的排版参数表。当用户指定格式名称时，读取对应文件。如果用户提供了 .docx 模板，模板中的设置覆盖预设。

6.1 内置格式预设

查找规则：

1. 用户说 "按 IEEE 排版" → 读取 templates/ieee.md
2. 用户说 "按 APA 排版" → 读取 templates/apa7.md
3. 用户说 "按学位论文排版" / "按毕业论文排版" → 读取 templates/chinese_thesis.md
4. 用户说 "按 ACM 排版" → 读取 templates/acm.md
5. 用户说 "按 Springer 排版" / "按 LNCS 排版" → 读取 templates/springer_lncs.md
6. 用户说 "按 NeurIPS 排版" / "按 NIPS 排版" → 读取 templates/nips.md
7. 用户说 "按 MLA 排版" → 读取 templates/mla.md
8. 无法匹配 → 进入 §6.2 用户自定义流程

6.2 用户自定义格式

当用户指定的格式不在内置预设中时：

1. 要求用户提供 .docx 模板或明确描述格式要求。
2. 从模板或描述中提取参数，填充 config.json 的 format_params。
3. 如果用户描述不完整，对缺失参数读取 templates/ieee.md 作为兜底默认值。

6.3 扩展新格式