Back to Details

evidence-binder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Evidence Binder (NO PROSE)

Evidence Binder（禁止撰写散文）

Goal: convert a paper-level pool into a subsection-addressable evidence plan.
This skill is the bridge from “Evidence Bank” → “Writer”: the writer should only use evidence IDs bound to the current subsection.
Why this matters for writing quality:
  • Weak/undifferentiated bindings force the writer to either pad prose or cite out-of-scope.
  • Treat 
    binding_gaps
    as a routing signal: fix upstream evidence/mapping instead of "writing around" missing evidence.
目标：将论文级别的证据池转换为可按小节寻址的证据计划。
该技能是连接“证据库（Evidence Bank）”与“撰稿人”的桥梁：撰稿人应仅使用绑定到当前小节的evidence ID。
这对写作质量至关重要的原因：
  • 薄弱/无差异的绑定会迫使撰稿人要么堆砌内容，要么引用超出范围的证据。
  • 将
    binding_gaps
    视为路由信号：修复上游的证据/映射问题，而非“绕开”缺失的证据进行写作。

Inputs

输入

  • outline/subsection_briefs.jsonl
  • outline/mapping.tsv
  • papers/evidence_bank.jsonl
  • Optional: 
    • citations/ref.bib
      (to validate cite keys when evidence items carry citations)
  • outline/subsection_briefs.jsonl
  • outline/mapping.tsv
  • papers/evidence_bank.jsonl
  • 可选： 
    • citations/ref.bib
      （当证据项包含引用时，用于验证引用键）

Outputs

输出

  • outline/evidence_bindings.jsonl
    (1 JSONL record per subsection)
  • outline/evidence_binding_report.md
    (summary; bullets + small tables)
    • Includes 
      gaps
      (missing required evidence fields) and 
      tag mix
      (selected evidence tags) so subsection-specific evidence needs are visible.
  • outline/evidence_bindings.jsonl
    （每个小节对应一条JSONL记录）
  • outline/evidence_binding_report.md
    （摘要；项目符号+小型表格）
    • 包含
      gaps
      （缺失的必填证据字段）和
      tag mix
      （已选证据标签），以便清晰查看小节特定的证据需求。

Output format (
outline/evidence_bindings.jsonl
)

输出格式（
outline/evidence_bindings.jsonl
）

JSONL (one object per H3 subsection). Best-effort fields (keep deterministic):
  • sub_id
    , 
    title
  • paper_ids
    (papers in-scope for this subsection, from 
    mapping.tsv
    )
  • mapped_bibkeys
    (bibkeys mapped to this subsection)
  • bibkeys
    (a selected subset to encourage subsection-first citations)
  • evidence_ids
    (selected evidence items from 
    papers/evidence_bank.jsonl
    )
  • evidence_counts
    (small summary by claim_type / tag / evidence_level)
  • binding_rationale
    (short bullets; why the selected evidence covers this subsection’s axes / desired tags)
  • binding_gaps
    (list[str]; required evidence fields not covered by selected evidence; drives the evidence self-loop upstream)
JSONL（每个H3小节对应一个对象）。尽最大努力保留确定性字段：
  • sub_id
    、
    title
  • paper_ids
    （该小节的关联论文，来自
    mapping.tsv
    ）
  • mapped_bibkeys
    （映射到该小节的引用键）
  • bibkeys
    （精选子集，鼓励优先引用小节专属的文献）
  • evidence_ids
    （从
    papers/evidence_bank.jsonl
    中选择的证据项）
  • evidence_counts
    （按claim_type/标签/证据级别统计的小型摘要）
  • binding_rationale
    （简短项目符号；说明所选证据为何覆盖该小节的维度/所需标签）
  • binding_gaps
    （字符串列表；所选证据未覆盖的必填证据字段；驱动上游的证据自循环优化）

A150++ density contract (default)

A150++密度约定（默认）

  • Use 
    queries.md:per_subsection
    as the width contract (A150++ default: 28).
  • Bind enough evidence to make writing concretely executable without out-of-scope pressure: 
    • mapped_bibkeys
      : >= per_subsection
    • evidence_ids
      : >= per_subsection - 4 (A150++: >=24)
    • bibkeys
      (selected): >= 20 (so each H3 has a usable citation pool, not just a long mapped list)
  • 使用
    queries.md:per_subsection
    作为宽度约定（A150++默认值：28）。
  • 绑定足够的证据，使写作能够具体可执行，且无超出范围的压力： 
    • mapped_bibkeys
      ：≥ per_subsection
    • evidence_ids
      ：≥ per_subsection - 4（A150++：≥24）
    • bibkeys
      （精选）：≥20（确保每个H3都有可用的引用池，而非冗长的映射列表）

Binding policy (how strict to be)

绑定策略（严格程度）

  • Subsection-first by default: the writer should primarily cite 
    bibkeys
    and use 
    evidence_ids
    bound to this 
    sub_id
    .
  • Allow limited within-chapter reuse: citations from sibling H3s within the same H2 chapter may be reused for background/evaluation framing, but:
    • keep >=3 subsection-specific citations per H3 (avoid “free cite drift”)
    • avoid cross-chapter reuse unless the outline explicitly calls for it
  • 默认优先小节专属：撰稿人应主要引用
    bibkeys
    并使用绑定到当前
    sub_id
    的
    evidence_ids
    。
  • 允许有限的章节内复用：同一H2章节内的兄弟H3小节的引用可复用为背景/评估框架，但需满足：
    • 每个H3至少保留3个小节专属引用（避免“无限制引用漂移”）
    • 除非大纲明确要求，否则避免跨章节复用

Workflow (NO PROSE)

工作流（禁止撰写散文）

  1. Read 
    outline/subsection_briefs.jsonl
    to understand each H3’s scope/rq/axes.
  2. Read 
    outline/mapping.tsv
    to know which papers belong to each subsection.
  3. Read 
    papers/evidence_bank.jsonl
    and select a subsection-scoped set of 
    evidence_id
    items per H3.
  4. If 
    citations/ref.bib
    exists, sanity-check that any cite keys referenced by selected evidence items are defined.
  5. Write 
    outline/evidence_bindings.jsonl
    and 
    outline/evidence_binding_report.md
    .
  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
    。

Freeze policy

冻结策略

  • If 
    outline/evidence_bindings.refined.ok
    exists, the script will not overwrite 
    outline/evidence_bindings.jsonl
    .
  • Treat this marker as an explicit refinement/completion signal (especially in strict runs): only create it after you have checked 
    binding_gaps
    and 
    tag mix
    look subsection-specific.
  • 若
    outline/evidence_bindings.refined.ok
    存在，脚本将不会覆盖
    outline/evidence_bindings.jsonl
    。
  • 将此标记视为明确的优化/完成信号（尤其在严格运行模式下）：仅在确认
    binding_gaps
    和
    tag mix
    符合小节特定需求后，再创建该标记。

Heterogeneity sanity check (avoid recipe-like bindings)

异质性检查（避免模板化绑定）

A common hidden failure mode is mechanical uniformity: every H3 ends up with the same 
claim_type
/
tag mix
, which hides what each subsection is actually missing and pushes the writer toward generic prose.
Before you mark bindings as refined:
  • Scan 
    outline/evidence_binding_report.md
    : different H3 should show meaningfully different 
    tag mix
    / 
    claim_type
    balance.
  • If most H3 look identical, treat it as a binder smell: tighten 
    required_evidence_fields
    , adjust selection rationale, or enrich the evidence bank, then rerun.
常见的隐性失败模式是机械统一性：每个H3最终的
claim_type
/
tag mix
都相同，这会掩盖每个小节实际缺失的内容，并促使撰稿人撰写通用化内容。
在标记绑定已优化前：
  • 查看
    outline/evidence_binding_report.md
    ：不同H3应显示出有意义的
    tag mix
    /
    claim_type
    差异。
  • 若大多数H3看起来相同，则视为绑定异常：收紧
    required_evidence_fields
    、调整选择依据、或扩充证据库，然后重新运行。

Script

脚本

Quick Start

快速开始

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

All Options

所有选项

  • --workspace <dir>
    : workspace root
  • --unit-id <U###>
    : unit id (optional; for logs)
  • --inputs <semicolon-separated>
    : override inputs (rare; prefer defaults)
  • --outputs <semicolon-separated>
    : override outputs (rare; prefer defaults)
  • --checkpoint <C#>
    : checkpoint id (optional; for logs)
  • --workspace <dir>
    ：工作区根目录
  • --unit-id <U###>
    ：单元ID（可选；用于日志）
  • --inputs <semicolon-separated>
    ：覆盖输入（罕见；优先使用默认值）
  • --outputs <semicolon-separated>
    ：覆盖输出（罕见；优先使用默认值）
  • --checkpoint <C#>
    ：检查点ID（可选；用于日志）

Examples

示例

  • Bind evidence IDs after building the evidence bank:
    • Ensure 
      papers/evidence_bank.jsonl
      exists.
    • Run: 
      python .codex/skills/evidence-binder/scripts/run.py --workspace workspaces/<ws>
  • 构建证据库后绑定evidence ID：
    • 确保
      papers/evidence_bank.jsonl
      已存在。
    • 运行：
      python .codex/skills/evidence-binder/scripts/run.py --workspace workspaces/<ws>

Troubleshooting

故障排除

Issue: some subsections have too few evidence IDs

问题：部分小节的evidence ID过少

Fix:
  • Strengthen 
    papers/evidence_bank.jsonl
    via 
    paper-notes
    (more extractable evidence items).
  • Or broaden the mapped paper set for the subsection via 
    section-mapper
    , then rerun binder.
修复方案：
  • 通过
    paper-notes
    强化
    papers/evidence_bank.jsonl
    （增加可提取的证据项）。
  • 或通过
    section-mapper
    扩大该小节的映射论文集合，然后重新运行绑定工具。

Issue: 
binding_gaps
is non-empty (missing evidence types)

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

What it means:
  • The subsection brief requires certain evidence fields (e.g., benchmarks/metrics/security/tooling), but the bound evidence items do not cover them.
Fix (self-loop upstream):
  • Prefer enriching 
    papers/evidence_bank.jsonl
    / 
    papers/paper_notes.jsonl
    for mapped papers (extract benchmark/metric/failure-mode details).
  • If the mapping is weak for that evidence type, expand 
    outline/mapping.tsv
    for the subsection and rerun binder.
  • If the requirement is unrealistic for the subsection’s scope, revise 
    outline/subsection_briefs.jsonl:required_evidence_fields
    and rerun binder.
含义：
  • 小节概要要求某些证据字段（如基准/指标/安全性/工具），但绑定的证据项未覆盖这些字段。
修复方案（上游自循环优化）：
  • 优先扩充映射论文对应的
    papers/evidence_bank.jsonl
    /
    papers/paper_notes.jsonl
    （提取基准/指标/故障模式细节）。
  • 若该证据类型的映射较弱，扩大该小节的
    outline/mapping.tsv
    范围，然后重新运行绑定工具。
  • 若该要求超出小节范围的实际情况，修改
    outline/subsection_briefs.jsonl:required_evidence_fields
    ，然后重新运行绑定工具。