section-merger

小节合并器

触发条件与路由

• 触发词：合并小节、合并草稿、合并小节文件、sections/ -> output/DRAFT.md、合并小节、拼接草稿。
• 适用场景：你有存放于 sections/ 下、按单元划分的正文文件，并希望生成单个 output/DRAFT.md，以便润色、审阅或转换为 LaTeX。

目标：根据以下内容组装一份论文式的 output/DRAFT.md：

• sections/（按小节/子小节划分的正文）
• outline/transitions.md（可选的衔接建议；由 transition-weaver 生成）
• outline/tables_appendix.md（面向读者的附录表格；由 appendix-table-writer 生成）

合并顺序由 outline/outline.yml 决定。草稿标题取自 GOAL.md（如果存在）。如果 Pipeline 合约要求提供 sections/sections_manifest.jsonl，则每个合并的小节都必须与其中记录的字节数和 SHA-256 哈希值一致。

此技能具有确定性：不会改写内容或编造正文，只会合并已生成的产物。

过渡段（显式启用）

• 默认情况下，不会插入生成的过渡段。
• 若要插入 H3 级过渡段，请创建 outline/transitions.insert_h3.ok。
• 若要插入 H2 级过渡段，请创建 outline/transitions.insert_h2.ok。
• 格式约定：H3 条目使用 - 3.1 -> 3.2: <text>。
• 兼容性：接受 →，但首选约定格式 ->（可避免控制字符编码问题）。
• 将过渡段视为注入的草稿文本：合并后运行 post-merge-voice-gate，并将修复内容反馈到 outline/transitions.md（不要直接修改合并后的草稿）。

表格（两层）

此 Pipeline 使用两层表格：

• outline/tables_index.md（内部索引；由 table-filler 生成）

  • 规划/调试产物
  • 不应插入论文

• outline/tables_appendix.md（面向读者的附录表格；由 appendix-table-writer 生成）

  • 可发表的表格（布局清晰、信息密度高）
  • 由 section-merger 插入，统一置于一个附录标题下

附录插入行为

• section-merger 会将 outline/tables_appendix.md 插入草稿末尾，标题为 ## 附录：表格。
• 插入的内容块不带标题（会移除表格文件中意外出现的任何 # 标题）。
• 如需退出（较少见）：在工作区中创建 outline/tables.insert.off。

输入

• outline/outline.yml（决定小节/子小节顺序）
• outline/transitions.md（必需）
• sections/sections_manifest.jsonl（可执行的调查 Pipeline 所需；用于新鲜度检查）
• GOAL.md（可选标题）

对于 arxiv-survey Pipeline（默认合约）：

• outline/tables_appendix.md（必需，除非已选择退出）

输出

• output/DRAFT.md
• output/MERGE_REPORT.md

脚本

快速开始

• uv run python .codex/skills/section-merger/scripts/run.py --help
• uv run python .codex/skills/section-merger/scripts/run.py --workspace <workspace>

所有选项

• --workspace <workspace>（必需）
• --unit-id <id>（可选；仅用于运行器记录）
• --inputs <a;b;c>（可选；覆盖输入；默认值因配置而异）
• --outputs <draft_rel;report_rel>（可选；默认为 output/DRAFT.md;output/MERGE_REPORT.md）
• --checkpoint <C#>（可选；合并器会忽略）

示例

• 使用默认设置合并（按配置插入表格）：

  uv run python .codex/skills/section-merger/scripts/run.py --workspace <workspace>

• 指定输出路径合并：

  uv run python .codex/skills/section-merger/scripts/run.py --workspace <workspace> --outputs output/DRAFT.md;output/MERGE_REPORT.md

故障排查

问题：合并报告显示缺少子小节文件

可能原因：

• 尚未写入必需的 sections/*.md 文件。

解决方法：

• 将缺失单元写入 sections/（通常通过 subsection-writer），然后重新运行合并。

问题：合并后的草稿中缺少附录表格

修复方法：

• 确保 outline/tables_appendix.md 存在，且包含最低配置的表格数量（课程论文：>=1；综述/深度研究：>=2），没有占位符。
• 确保未创建 outline/tables.insert.off。
• 重新运行 section-merger。