section-merger

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Section Merger

小节合并工具

Goal: assemble a paper-like

output/DRAFT.md

from:

```
sections/
```
(per-section/per-subsection prose)
```
outline/transitions.md
```
(short hand-offs; generated by
```
transition-weaver
```
)

outline/tables_appendix.md

(reader-facing Appendix tables; generated by

appendix-table-writer

)

Merge order is driven by

outline/outline.yml

. The draft title is taken from

GOAL.md

when present.

sections/sections_manifest.jsonl

is an optional diagnostics input.

This skill is deterministic: it does not rewrite content or invent prose; it only merges already-generated artifacts.

目标：将以下内容组装成类论文格式的

output/DRAFT.md

：

```
sections/
```
（按小节/子小节划分的文稿）
```
outline/transitions.md
```
（简短过渡内容；由
```
transition-weaver
```
生成）

outline/tables_appendix.md

（面向读者的附录表格；由

appendix-table-writer

生成）

合并顺序由

outline/outline.yml

决定。若存在

GOAL.md

，则草稿标题取自该文件。

sections/sections_manifest.jsonl

是可选的诊断输入文件。

本工具是确定性的：它不会重写内容或生成新文稿，仅合并已生成的产物。

Transitions (injected text)

过渡内容（嵌入文本）

By default,
```
section-merger
```
inserts only within-chapter H3->H3 transitions.
Optional: if you want between-H2 transitions inserted too, create
```
outline/transitions.insert_h2.ok
```
in the workspace.
Format contract: only lines matching
```
- 3.1 -> 3.2: <text>
```
are injected by default.
Compatibility:
```
→
```
is accepted, but
```
->
```
is the preferred contract (avoids control-character encoding issues).
Treat transitions as injected draft text: run
```
post-merge-voice-gate
```
after merging, and route fixes back to
```
outline/transitions.md
```
(do not patch the merged draft).

默认情况下，
```
section-merger
```
仅插入章节内H3到H3的过渡内容。
可选配置：若要同时插入H2之间的过渡内容，请在工作区中创建
```
outline/transitions.insert_h2.ok
```
文件。
格式约定：默认仅注入匹配
```
- 3.1 -> 3.2: <文本>
```
格式的行。
兼容性：支持
```
→
```
符号，但推荐使用
```
->
```
（避免控制字符编码问题）。
过渡内容视为嵌入的草稿文本：合并后请运行
```
post-merge-voice-gate
```
，并将修改反馈至
```
outline/transitions.md
```
（不要直接修改合并后的草稿）。

Tables (two layers)

表格（两层结构）

This pipeline uses two table layers:

```
outline/tables_index.md
```
(internal index; produced by
```
table-filler
```
)
- planning/debugging artifact
- should NOT be inserted into the paper
```
outline/tables_appendix.md
```
(reader-facing Appendix tables; produced by
```
appendix-table-writer
```
)
- publishable tables (clean layout + high information density)
- inserted by
```
section-merger
```
  under a single Appendix heading

本流水线使用两层表格结构：

```
outline/tables_index.md
```
（内部索引；由
```
table-filler
```
生成）
- 用于规划/调试的产物
- 不应插入到论文中
```
outline/tables_appendix.md
```
（面向读者的附录表格；由
```
appendix-table-writer
```
生成）
- 可发布的表格（布局整洁+信息密度高）
- 由
```
section-merger
```
  插入到单一附录标题下

Appendix insertion behavior

附录插入行为

section-merger

inserts

outline/tables_appendix.md

at the end of the draft under

## Appendix: Tables

The inserted block is heading-free (any accidental
```
#
```
headings inside the tables file are stripped).
Opt-out (rare): create
```
outline/tables.insert.off
```
in the workspace.

section-merger

会将

outline/tables_appendix.md

插入到草稿末尾，标题为

## Appendix: Tables

。

插入的内容不含标题（表格文件中若存在意外的
```
#
```
标题将被移除）。
可选关闭：若要关闭该功能，请在工作区中创建
```
outline/tables.insert.off
```
文件。

Inputs

输入文件

```
outline/outline.yml
```
(drives section/subsection order)
```
outline/transitions.md
```
(required)
```
sections/sections_manifest.jsonl
```
(optional diagnostics)
```
GOAL.md
```
(optional title)

For arxiv-survey pipelines (default contract):

```
outline/tables_appendix.md
```
(required unless opted out)

```
outline/outline.yml
```
（决定小节/子小节顺序）
```
outline/transitions.md
```
（必填）
```
sections/sections_manifest.jsonl
```
（可选诊断文件）
```
GOAL.md
```
（可选标题来源）

对于arxiv-survey流水线（默认约定）：

```
outline/tables_appendix.md
```
（必填，除非手动关闭该功能）

Outputs

输出文件

```
output/DRAFT.md
```
```
output/MERGE_REPORT.md
```

```
output/DRAFT.md
```
```
output/MERGE_REPORT.md
```

Script

脚本使用

Quick Start

快速开始

python .codex/skills/section-merger/scripts/run.py --help

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

python .codex/skills/section-merger/scripts/run.py --help

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

All Options

所有选项

```
--workspace <workspace_dir>
```
(required)
```
--unit-id <id>
```
(optional; used only for runner bookkeeping)
```
--inputs <a;b;c>
```
(optional; override inputs; defaults are profile-aware)

--outputs <draft_rel;report_rel>

(optional; defaults to

output/DRAFT.md;output/MERGE_REPORT.md

)

```
--checkpoint <C#>
```
(optional; ignored by the merger)

```
--workspace <workspace_dir>
```
（必填）
```
--unit-id <id>
```
（可选；仅用于运行器记录）
```
--inputs <a;b;c>
```
（可选；覆盖默认输入；默认值与配置文件关联）

--outputs <draft_rel;report_rel>

（可选；默认值为

output/DRAFT.md;output/MERGE_REPORT.md

）

```
--checkpoint <C#>
```
（可选；合并工具会忽略该参数）

Examples

示例

Merge with defaults (profile-aware table insertion):

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

Merge with explicit outputs:

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

使用默认配置合并（根据配置文件自动插入表格）：

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

自定义输出路径进行合并：

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

Troubleshooting

故障排除

Issue: merge report says a subsection file is missing

问题：合并报告显示某个子小节文件缺失

Likely cause:

A required
```
sections/*.md
```
file has not been written yet.

Fix:

Write the missing units under
```
sections/
```
(typically via
```
subsection-writer
```
) and rerun merge.

可能原因：

所需的
```
sections/*.md
```
文件尚未生成。

解决方法：

在
```
sections/
```
目录下生成缺失的单元内容（通常通过
```
subsection-writer
```
工具），然后重新运行合并。

Issue: Appendix tables are missing in the merged draft

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

Fix:

Ensure
```
outline/tables_appendix.md
```
exists and contains >=2 Markdown tables (no placeholders).
Ensure you did not create
```
outline/tables.insert.off
```
.
Rerun
```
section-merger
```
.

解决方法：

确保
```
outline/tables_appendix.md
```
存在且包含至少2个Markdown表格（无占位符）。
确认未创建
```
outline/tables.insert.off
```
文件。
重新运行
```
section-merger
```
。