outline-refiner

大纲优化器（规划阶段，不写正文）

触发条件与路由

• 触发条件：规划器、动态大纲、大纲优化、覆盖率报告、大纲迭代、覆盖率报告。
• 适用场景：已有 outline/outline.yml + outline/mapping.tsv，并希望在开始写作前进行可验证的、不写正文的规划阶段。

目标：通过添加明确的规划阶段，让大纲可审计，并回答以下问题：

• 每个 H3 是否有足够的映射证据？
• 是否在各处重复使用同几篇论文？
• 小节的划分轴是否仍然过于通用或像脚手架？
• 大纲是否可能形成论文式结构（最终目录预算：约 6–8 个 H2；H3 数量更少、内容更充实）？

这是一个确定性的“规划器”单元：不得撰写综述正文。

输入

必需：

• outline/outline.yml
• outline/mapping.tsv

可选（尽力诊断；流程早期可能缺失）：

• outline/OUTLINE_BUDGET_REPORT.md（若存在：说明近期的合并情况；有助于解读映射或覆盖率的变化）
• papers/paper_notes.jsonl（用于证据等级）
• outline/subsection_briefs.jsonl（用于划分轴的具体程度）
• GOAL.md（用于提示范围偏移）

输出

• outline/coverage_report.md（项目符号列表 + 小型表格；不写正文）
• outline/outline_state.jsonl（仅追加的 JSONL；每次运行一条记录）

工作流（规划阶段，不写正文）

1. 解析 outline/outline.yml，列出 H2 章节和 H3 小节（章节规模／预算）。
   • 如果存在 outline/OUTLINE_BUDGET_REPORT.md，将其用作合并／变更日志，以便覆盖率报告能够说明结构为何发生变化。
2. 读取 outline/mapping.tsv，计算每个 H3 的覆盖率和重复使用热点。
3. 如果存在 papers/paper_notes.jsonl，汇总映射论文的证据等级（全文／摘要／标题）。
4. 如果存在 outline/subsection_briefs.jsonl，计算每个 H3 的划分轴具体程度（通用与具体）。
5. 可选：使用 GOAL.md 标记明显的范围偏移（大纲中未体现的关键词）。
6. 写入 outline/coverage_report.md，并向 outline/outline_state.jsonl 追加一条运行记录。

冻结策略

• 如果存在 outline/coverage_report.refined.ok，脚本不会覆盖 outline/coverage_report.md。

脚本

快速开始

• uv run python .codex/skills/outline-refiner/scripts/run.py --help
• uv run python .codex/skills/outline-refiner/scripts/run.py --workspace <workspace>

所有选项

• --workspace <dir>：工作区根目录
• --unit-id <U###>：单元 ID（可选；用于日志）
• --inputs <semicolon-separated>：覆盖输入项（较少使用；优先采用默认值）
• --outputs <semicolon-separated>：覆盖输出项（较少使用；优先采用默认值）
• --checkpoint <C#>：检查点 ID（可选；用于日志）

示例

• 在 section-mapper 之后运行规划阶段诊断：
  • uv run python .codex/skills/outline-refiner/scripts/run.py --workspace <workspace>

故障排除

问题：报告缺少证据等级或划分轴具体程度列

原因：

• 缺少可选输入（没有 papers/paper_notes.jsonl 和／或 outline/subsection_briefs.jsonl）。

解决方法：

• 运行 paper-notes 和／或 subsection-briefs，然后重新运行 outline-refiner。