evidence-binder

证据绑定器（无正文）

触发条件与路由

• 触发词：evidence binder、evidence plan、section->evidence mapping、证据绑定、evidence_id。
• 适用场景：存在 papers/evidence_bank.jsonl，且希望作者/审计者使用按章节范围限定的证据项（WebWeaver 风格记忆库）。

目标：将论文级证据池转换为可按小节寻址的证据计划。

此技能是从“证据库”到“作者”的桥梁：作者只能使用绑定到当前小节的证据 ID。

这对写作质量很重要，原因如下：

• 薄弱或缺乏区分度的绑定会迫使作者填充正文，或引用范围外的内容。
• 将 binding_gaps 视为路由信号：修复上游证据/映射，而不是“绕开”缺失证据来写作。

输入

• outline/subsection_briefs.jsonl
• outline/mapping.tsv
• papers/evidence_bank.jsonl
• 可选：
  • citations/ref.bib（当证据项包含引用时，用于验证引用键）

输出

• outline/evidence_bindings.jsonl（每个小节 1 条 JSONL 记录）
• outline/evidence_binding_report.md（摘要；项目符号列表 + 小型表格）
  • 包含 gaps（缺失的必需证据字段）和 tag mix（所选证据标签），以便看清小节特定的证据需求。

输出格式（outline/evidence_bindings.jsonl）

JSONL（每个 H3 小节对应一个对象）。尽力填写以下字段（保持确定性）：

• sub_id、title
• paper_ids（来自 mapping.tsv、属于此小节范围的论文）
• mapped_bibkeys（映射到此小节的 bibkey）
• bibkeys（选取的子集，以鼓励优先引用本小节来源）
• evidence_ids（从 papers/evidence_bank.jsonl 中选取的证据项）
• evidence_counts（按 claim_type / tag / evidence_level 分类的简要汇总）
• binding_rationale（简短要点；说明所选证据为何覆盖此小节的维度/期望标签）
• binding_gaps（list[str]；所选证据未覆盖的必需证据字段；用于驱动上游证据自循环）

A150++ 密度约定（默认）

• 使用 queries.md:per_subsection 作为宽度约定（A150++ 默认值：28）。
• 绑定足够的证据，使写作能够具体执行，且不必引用范围外的内容：
  • mapped_bibkeys：>= per_subsection
  • evidence_ids：>= per_subsection - 4（A150++：>=24）
  • bibkeys（所选）：>= 20（确保每个 H3 都有可用的引用池，而不只是冗长的映射列表）

对于 draft_profile=course_paper，保持相同的可追溯性结构，但使用紧凑密度：每个 H3 至少有 8 个映射 bibkey、6 个所选 bibkey，以及来自至少 4 篇论文的 6 个证据 ID。

绑定策略（严格程度）

• 默认优先绑定到小节：作者应主要引用 bibkeys，并使用绑定到此 sub_id 的 evidence_ids。
• 允许在同一章节内有限复用：同一 H2 章节中相邻 H3 小节的引用可用于背景/评估框架，但：
  • 每个 H3 保留 >=3 个小节特定引用（避免“自由引用漂移”）
  • 除非大纲明确要求，否则避免跨章节复用

工作流（无正文）

1. 阅读 outline/subsection_briefs.jsonl，了解每个 H3 的范围、研究问题和维度。
2. 阅读 outline/mapping.tsv，了解每个小节对应哪些论文。
3. 阅读 papers/evidence_bank.jsonl，为每个 H3 选择一组限定在该小节范围内的 evidence_id 项。
4. 如果存在 citations/ref.bib，检查所选证据项引用的任何引用键是否均已定义。
5. 写入 outline/evidence_bindings.jsonl 和 outline/evidence_binding_report.md。

冻结策略

• 如果存在 outline/evidence_bindings.refined.ok，脚本将不会覆盖 outline/evidence_bindings.jsonl。
• 将此标记视为明确的精修/完成信号（尤其是在严格运行中）：只有在检查过 binding_gaps，并确认 tag mix 看起来符合小节特定需求后，才创建此标记。

异质性检查（避免配方式绑定）

一个常见的隐性故障模式是机械式统一：每个 H3 最终都有相同的 claim_type/tag mix，这会掩盖各小节实际缺少的内容，并促使作者写出泛泛而谈的文字。

在将绑定标记为已完善之前：

• 检查 outline/evidence_binding_report.md：不同 H3 应显示出有明显差异的 tag mix / claim_type 平衡。
• 如果大多数 H3 看起来都一样，就要视为绑定器异味：收紧 required_evidence_fields、调整选择理由，或丰富证据库，然后重新运行。

脚本

快速开始

• uv run python .codex/skills/evidence-binder/scripts/run.py --help
• uv run python .codex/skills/evidence-binder/scripts/run.py --workspace <workspace>

所有选项

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

示例

• 构建证据库后绑定证据 ID：
  • 确保 papers/evidence_bank.jsonl 存在。
  • 运行：uv run python .codex/skills/evidence-binder/scripts/run.py --workspace <workspace>

故障排查

问题：某些小节的证据 ID 太少

修复：

• 通过 paper-notes 增强 papers/evidence_bank.jsonl（添加更多可提取的证据项）。
• 或通过 section-mapper 扩大小节映射的论文集，然后重新运行绑定器。

问题：binding_gaps 非空（缺少证据类型）

含义：

• 小节简报要求某些证据字段（例如，基准测试/指标/安全/工具），但已绑定的证据项未涵盖这些内容。

修复（向上游自循环）：

• 优先为已映射的论文丰富 papers/evidence_bank.jsonl / papers/paper_notes.jsonl（提取基准测试/指标/故障模式详情）。
• 如果该证据类型的映射较弱，请扩展该小节对应的 outline/mapping.tsv，然后重新运行绑定器。
• 如果该要求不符合小节的范围，请修改 outline/subsection_briefs.jsonl:required_evidence_fields，然后重新运行绑定器。