section-mapper

Section Mapper

触发条件与路由

• 触发词：section mapper、mapping.tsv、覆盖率、论文到小节映射、论文映射、覆盖率。
• 适用场景：处于 structure 阶段（C2），已有 papers/core_set.csv + outline/outline.yml，需要确保每个小节都有足够的支持论文，再进入 evidence/writing 阶段。

创建论文→小节映射，以支持证据构建和后续综合。

好的映射应当相关、多样且易于解释。整个语料的主题词和大纲中重复出现的套话，都不能证明论文与小节相关。

适用场景

• 已有 outline/outline.yml 和 papers/core_set.csv，需要检查各小节的覆盖情况。
• 想尽早发现信号较弱的小节，以便调整范围或补充论文。

输入

• papers/core_set.csv
• outline/outline.yml

输出

• outline/mapping.tsv
• outline/mapping_report.md（诊断信息：重复使用热点、信号较弱的小节）
• outline/mapping_gap_candidates.tsv（当核心集无法满足某小节的目标时，从去重后的论文池中生成的只读修复候选项）

冻结标记（显式）

为防止完善映射理由后意外覆盖文件：

• 创建 outline/mapping.refined.ok。

仅当此标记的时间晚于映射文件、核心集、大纲、查询约定和映射器实现时，该标记才有效。任何上游变更都会使其失效。

如果在没有此标记的情况下重新运行脚本，脚本会将先前的映射备份到带时间戳的文件：

• outline/mapping.tsv.bak.<timestamp>

工作流（启发式）

1. 从大纲中的小节开始（每个小节都应当“可映射”）。
2. 对于每个小节，选择足够的论文来支持证据优先的写作（A150++ 默认：28 篇；较小规模的运行：约 12–20 篇；轻量级：约 3–6 篇），这些论文应当：
   • 有代表性（典型论文 / 经常被引用）
   • 互为补充（设计选择、评估设置各不相同）
   • 除非确属基础性论文，否则不要在其他小节中过度重复使用
   • 有小节特定概念的支持，而不只是依赖“整体主题名称”等整个语料共有的词语
3. 在 why 中填写简短的语义理由（一行即可），例如：
   • 机制：“解耦规划器与执行器；工具调用 API”
   • 评估：“交互式 Web 任务；深入分析工具错误”
   • 安全：“Agent 越狱攻击面；缓解措施研究”
4. 初步映射完成后，检查以下情况：
   • 论文数少于 3 篇的小节 → 扩大范围、合并小节或扩展检索
   • 少数几篇论文被映射到所有小节 → 增加多样性；仅在真正相关的部分保留“基础性”论文
   • 未达到目标的情况 → 将其视为证据缺口；不要仅为满足行数要求而填入无关论文

质量检查清单

• outline/mapping.tsv 存在且非空。
• 大多数小节都映射了 ≥3 篇论文（或在 why 中注明明确的例外情况）。
• why 应说明语义理由（不能只是 matched_terms=...）。
• 没有单篇论文主导无关的小节。
• 不得使用低置信度的填充行来掩盖证据缺口。

辅助脚本（可选）

快速开始

• uv run python .codex/skills/section-mapper/scripts/run.py --help
• uv run python .codex/skills/section-mapper/scripts/run.py --workspace <workspace> --per-subsection 28

所有选项

• --per-subsection <n>：每个小节的目标映射论文数
• --diversity-penalty <int>：对同一篇论文在多个小节中重复使用进行惩罚
• --soft-limit <n> / --hard-limit <n>：每篇论文的重复使用上限（0 = 自动）
• --minimum-score <n>：自动相关性下限（默认值：3）；仅在之后会人工审核映射结果时调低

示例

• 提高多样性（减少重复使用）：
  • uv run python .codex/skills/section-mapper/scripts/run.py --workspace <workspace> --per-subsection 4 --diversity-penalty 5
• 收紧重复使用上限：
  • uv run python .codex/skills/section-mapper/scripts/run.py --workspace <workspace> --per-subsection 3 --soft-limit 6 --hard-limit 10

说明

• 写入 outline/mapping_report.md 诊断报告。
• 写入 outline/mapping_gap_candidates.tsv，而不是悄悄修改 papers/core_set.csv；更改冻结的核心集合仍由人工或整理步骤负责。
• 在评分前移除语料库常见词和大纲常见词，提高小节标题对齐度的权重，并拒绝缺乏足够小节特定证据的候选项。
• 可选的 assets/domain_packs/*.json 规则可针对明确检测到的领域，收紧有歧义的小节标签；这些规则用于约束映射，而非更改核心集合。
• 在 pipeline.py --strict 模式下，可能会阻止映射，直到将通用的 why 理由替换为语义理由。

故障排除

常见问题

问题：outline/mapping.tsv 为空或覆盖率低

症状：

• 映射行数很少，或许多小节的论文少于 3 篇。

原因：

• 核心集合太小，或大纲划分过细。

解决方案：

• 增大核心集合（使用更大的 --core-size 重新运行 dedupe-rank）。
• 合并信号较弱的小节，或扩大范围／查询条件。

问题：映射过度重复使用相同的论文

症状：

• 质量门禁报告指出，许多无关小节重复使用相同的论文。

原因：

• 多样性惩罚过低；核心集合有限。

解决方案：

• 提高 --diversity-penalty，和／或设置更严格的 --soft-limit/--hard-limit。
• 手动为无关章节的映射增加多样性。

恢复检查清单

• 每个小节都映射了 ≥3 篇论文（目标值）。
• why 列包含语义理由（而不只是词项重叠）。