Repository navigation
task: 支持每个优化迭代的知识库命中归因统计 #344
Description
Current state: 新增需求提案：按优化迭代统计知识库命中、采用及关联验证结果。 新增意见建议关联已有 campaign/run/iteration 的实际 token 用量和可得费用，区分整轮会话成本与检索成本，缺失货币费用仍记未知。该意见及此前候选集合/数据契约建议仍待维护者取舍，不是已接受的新验收项，也不授权实施或因果收益判断。
Decision needed: 请维护者确认统计口径和首版范围，并指定负责人。
Next action: 实现负责人梳理检索与迭代证据，明确数据契约及展示方案。
Goal and acceptance
用户需要了解每轮优化命中了哪些知识、实际用了哪些，以及关联了什么结果，以评估知识库覆盖和复用情况。
- 按 campaign/run/iteration 关联检索事件，保留知识条目 ID、版本或来源引用、检索阶段和已有的命中理由/分数。
- 区分检索命中、实际采用、未采用及使用情况未知；采用须有引用、操作或产物记录支撑。
- 每轮展示检索次数、命中次数、去重命中条目数与采用条目数；比率明确分子、分母和去重口径。
- 展示条目明细及关联候选、变更、精度/性能结果和证据链接，保留失败、无收益和 INCONCLUSIVE 结果。
- 区分使用关联与因果贡献；没有对照证据时不声称知识导致收益或分摊收益百分比。
- 零命中显示零，缺失采集显示未知；重试和重复事件不重复计数，不同迭代不串数据。
- 提供统计测试及多轮示例，覆盖命中未采用、采用后失败、重复事件和缺失记录。
Scope and constraints
- In scope: 检索/使用记录、每轮聚合统计、可审计明细及 dashboard 轮次查看入口。
- Out of scope: 自动调整检索排序、自动更新知识库及无证据的因果收益推断。
- Interfaces / limits: 复用现有知识与迭代证据；历史数据缺失明确展示；不要求采集完整私密上下文。
Inputs and deliverables
- Related issues: [Tracking] Skill Indexer: retrieval efficiency and accuracy #255（检索效率与准确率）、[Task] RSI Dashboard: Optimization Workflow Visualization and Trace Capture #314（dashboard）、discussion: what trace evidence should InferRSI persist beyond per-run artifacts? #333（trace 持久化讨论；本需求不预先决定存储方案）。
- Expected artifacts: 统计口径、记录与聚合实现、dashboard 明细、测试和使用文档。
Ownership and authorization
- Proposed by / actual requester: 用户在 Codex 对话中提出，Codex 代为整理提交。
- Status: Proposed
- Accountable parent / implementer / goal-acceptance owner: TBD，由维护者指定。
- Accepted decision or scoped delegation: 本次授权为创建需求 issue；未指定实现、合并或关闭权限。
Completion and closure
- Who accepts completion and may close: 待指定的目标验收负责人。
- Remaining uncertainty / next decision: 维护者确认首版范围、数据接口和负责人。
Activity
Dong1017 commentedon Nov 5, 2026
增量意见：四条可操作的补充
静态查证，基线
9dded7ad；未运行测试或实验。只补充提案未覆盖的部分，不重述已有验收项。先确认一处口径，因为后面三条都依赖它：本提案能产出的最强结论是「某条知识被检索到、被采用过」，不能产出「某条知识有用」。提案自己写明了这一点（不声称因果贡献、不分摊收益百分比），这个边界是对的。因此它可以作为下架候选的证据来源，不能作为知识质量评价。三个信号的强度不同：
1. 零命中需要候选集合，否则分母不成立
提案要求「比率明确分子、分母和去重口径」，但当前分母是检索次数，这只解决了分子侧。零命中有两种互斥含义：进入候选但未被选中，以及从未进入候选。只统计命中无法区分。
这不是理论问题。
src/inferrsi/data/repo_packs下有 107 个带status字段的知识条目，而已有战役只覆盖少数主题。若按零命中判断下架，绝大多数条目都会落入候选，原因却只是没有匹配的任务运行过。建议新增验收项：
2. 复用现有的检索评估汇总器，不另写聚合
tools/evaluate_indexer.py已经实现了配对分组重采样与分位数汇总（percentile、summarize），是 #255 检索效率与准确率那条线的统计实现，对应证据在evidence/indexer-255-*六个目录（约 15.9 MB）。它目前唯一的消费者是
tests/test_indexer_evaluation_summary.py，没有生产调用方。本提案要的每轮比率统计正好是它的用途。建议： 首版聚合复用该模块，并在提案里显式声明这一依赖，避免出现第二份口径不同的统计实现。
3. 下架需要状态定义，建议与本提案分开
知识条目的生命周期槽位已经存在，但从未被使用过：
107 个条目全部停在
imported，没有任何条目进入过其他状态；skill-index.json顶层只有schema_version与skills，没有生命周期字段。所以下架缺的不是统计数据，是状态定义与进入条件：有哪些状态、谁决定、需要什么证据、下架后检索与历史证据如何处理。本提案的 out of scope 已排除「自动更新知识库」，方向正确。
建议： 把状态定义单独开一个 issue，本提案只负责产出证据，不承担下架决定。知识晋升保留显式决定，下架应当对称。
附一处澄清，避免实现时误用：
tools/skill_eval_quarantine.py不是知识下架机制。它的文件头声明是「Explicit trusted incident stop; never admission, billing ingestion or unquarantine」，作用对象是付费预算账本，与知识条目无关。4. 这条需求暴露了目标职责图缺一条边
#6 第三轮的目标职责图里，Workbench 侧没有任何一条边回到 Knowledge 侧：现有的边是入口→知识检索、入口→实验编排、知识检索↔知识资产、执行管理↔被测系统。
而本提案要求把命中与采用记录按 campaign/run/iteration 关联后供知识侧使用，这需要一条从实验侧到知识资产的数据流。知识循环的「提取经验 → 审阅确认」两步同样依赖它。
建议： 在数据契约里显式定义这条回流的方向与所有者（谁写入、谁读取、保留多久），不要让它成为隐式耦合。这也是确定首版范围时需要先回答的接口问题。
关于首版范围的一个意见
提案把 dashboard 轮次查看入口列入 in scope。若要先服务下架判断，建议首版优先做记录与候选集合采集，展示可以后置：没有候选集合的历史数据无法事后补齐，而展示随时可以加。#314 与 #333 的结论不影响这个取舍。
Dong1017 commentedon Nov 5, 2026
补一条验收项：每轮的实际成本
读了 PR #338 新发布的 六条件 MoE 对照证据（三个模型 × 知识库 on/off）之后补这一条。静态读取已发布数据，未重跑任何实验。
缺口
当前验收项里每轮展示的是检索次数、命中次数、去重命中条目数、采用条目数——四个都是知识事件的计数。但那份对照里最大的差异不在计数上：
按现有口径记录，这三对会得到形如「检索 N 次、命中 M 条、采用 K 条」的小整数行，看不出其中两对多花了一千万 token。而这个量级的差异不需要任何因果假设就成立，属于使用事实。
建议的措辞
这不是新增采集，是把已有数据关联起来
该证据包里数据形状已经存在：
results/rounds.csv有round_input_tokens、round_cached_input_tokens、round_output_tokens、round_total_tokens、round_uncached_input_tokens及对应的cumulative_*；results/session-usage.csv有整会话聚合。关联键正是本提案第一条验收项已经要求保留的 campaign / run / iteration。
两处必须写进口径的限定
一、它回答「这一轮花了多少」，不是「检索花了多少」。 该证据包定义的轮边界是「完成评测的工具结果返回之后、下一条模型生成之前的延迟遥测快照，包含此前检索、失败、等待交互等全部会话工作」。作为迭代成本是对的，但不能拆成检索成本与推理成本。想要后者需要另一个埋点，建议不做。
rounds.csv已有token_boundary_status列跟踪边界质量，可沿用。二、费用字段可能为空。 该包
session-usage.csv的monetary_cost列六个会话全部为空，只有 token 计数，与其 README「token 不是货币账单」一致。所以验收项写「可得费用」，不假设存在货币金额。它仍然不改变本提案的因果边界
记录成本不支持「知识库有用或无用」。成本与命中、采用同属关联类事实。
反而值得记下的是：这份是目前最受控的知识开关对照，而它自己的结论仍然是不能归因。 该 README 明确写「每条件只有一条轨迹……没有逐份知识的消融实验……不能把最终高低直接归因于知识库好坏」，并指出 OFF 条件仍可访问公开技术资料、两组物理卡与时段不同、加速比是各自配对基线下的分数（跨条件候选原始延迟几何平均只差约 0.82%，medium 场景 OFF 更慢）。
所以本提案「没有对照证据时不声称因果」这条前提不需要修订——一次真实受控尝试得出的正是同一结论。成本那条的价值在别处：它是目前唯一一个量级足够大、不依赖归因推断就能读出的差别。