用途
Section Merger 用于把分散的、按小节或子小节生成的正文文件，确定性地合并成一份完整的论文式草稿 output/DRAFT.md，供后续润色、评审或 LaTeX 转换使用。它只负责拼接已经生成的产物，不会重写内容，也不会自行编造文字。
主要能力
- 按 outline/outline.yml 驱动小节与子小节的合并顺序，保持大纲顺序。
- 当提供 sections/sections_manifest.jsonl 时，每个被合并的小节必须与其记录的字节数和 SHA-256 哈希一致，作为新鲜度校验。
- 草稿标题在存在 GOAL.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>（可选；覆盖输入；默认值随 profile 变化）
- --outputs <draft_rel;report_rel>（可选；默认为 output/DRAFT.md;output/MERGE_REPORT.md）
- --checkpoint <C#>（可选；合并器会忽略）
示例：
使用默认值合并（按 profile 决定是否插入表格）：
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
输入与输出
输入：
- outline/outline.yml（驱动小节/子小节顺序）
- outline/transitions.md（必需）
- sections/sections_manifest.jsonl（可执行 survey Pipeline 必需；新鲜度门禁）
- GOAL.md（可选标题）
- 对于 arxiv-survey 流水线（默认契约）：outline/tables_appendix.md（除非选择退出，否则必需）
输出：
- output/DRAFT.md
- output/MERGE_REPORT.md
过渡句（需显式开启）
默认情况下不会插入生成的过渡句。
- 要插入 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，不要直接修补合并后的草稿。
表格（两层）
该流水线使用两层表格：
- outline/tables_index.md（内部索引；由 table-filler 生成）：规划/调试产物，不应插入论文。
- outline/tables_appendix.md（面向读者的附录表格；由 appendix-table-writer 生成）：可发布表格（布局干净、信息密度高），由 section-merger 插入到单个 Appendix 标题之下。
附录插入行为：
- section-merger 将 outline/tables_appendix.md 插入到草稿末尾的 ## Appendix: Tables 之下。
- 插入的块不带标题（表格文件中任何误带的 # 标题都会被剥离）。
- 选择退出（少见）：在工作区创建 outline/tables.insert.off。
适用场景
当你拥有 sections/ 下按单元生成的正文文件，并希望得到单一的 output/DRAFT.md 用于润色、评审或 LaTeX 时使用。触发词包括：merge sections、merge draft、combine section files、sections/ -> output/DRAFT.md、合并小节、拼接草稿。
限制与故障排查
- 该技能是确定性的：不重写内容，不虚构文字，只合并已生成的产物。
- 合并报告提示某个子小节文件缺失：可能原因是某个必需的 sections/*.md 文件尚未写入。修复方式是在 sections/ 下补写缺失单元（通常通过 subsection-writer），然后重新运行合并。
- 合并草稿中缺少附录表格：确保 outline/tables_appendix.md 存在并满足 profile 最低要求（课程论文：>=1；survey/deep：>=2），且不含占位符；确保没有创建 outline/tables.insert.off；然后重新运行 section-merger。