[jiaran-king]

Refs #344

这次交付什么

给优化轮次增加一个可归档的搜索记录。团队可以打开一份 JSON，检查 Agent 何时查了什么、工具实际返回了哪些材料、其中哪段影响了后续决定，以及这轮有无候选和评测。首版范围来自搜索域负责人委托和 #344 下的方案讨论。

数据怎么来

调用方指定 campaign、轮次、会话行区间、知识库范围
  ├─ 文件检索：关联命令、外层工具调用及给模型的返回 → 查询、范围、可见摘录
  └─ Indexer：校验 capture → 查询、选中的条目、组装的资源
                 └─ 在对应工具返回中核对到完整资源块 → 这份资源已送达

复核者选中材料段落和后续决策摘录 → 导入器逐项核对并建立采用／拒绝关联
campaign 已有的候选和评测         → 按轮次附上候选、run 和实际 verdict
                                      ↓
                search/archive/round-<n>.json → evidence/<campaign>/search/

在原有 campaign import-search 上增加 --archive-review。原始 rollout 和本地轮次索引保留在本机。可归档文件区分工具返回被截断、导出时省略，以及送达情况未知。没有决策引用的材料保留采用未知。导入器验证引用的次序和原文，复核者判断两者是否有实际联系。使用说明与命令

一份可以直接读的结果

在 #380 的 Qwen S2-B1 会话，Agent 先读取昇腾案例，再用 rg 缩小范围。打开 生成的轮次 JSON，查看事件 file-73 的 delivery.passages，能看到同一文件第 16、18、19 行的返回原文。再看该材料的 evidence，第 18 行的三项组合初始化 OOM 对应到 Agent 提出“先做资源检查”的答复。第 19 行出现在返回里，缺少采用依据。

这轮只交付建议，candidates 为空。早先的宽搜索被截断，另有未解析命令，所以保留可观察事件，整轮总数为 null。案例说明

验证与范围

• 用真实 Qwen rollout 经过 CLI 生成上述文件，检查了重复导入与隐私边界。在另一个实际 softmax-cpu campaign，导入器保留了候选及其 FAIL verdict，并将无法解析的检索保留为未知。
• 用真实 Indexer capture 和受控工具返回做对照。只返回 capture 文件名时送达未知；在同一份 capture 的九个资源中返回一个完整资源块时只确认该资源。经复核且与实际返回及后续答复均匹配的段落可以记为采用。
• 本地通过 221 项相关测试，涵盖搜索、campaign、优化日志、Dashboard 数据、插件、evidence 与 smoke。Ruff 通过，evidence inventory 校验通过（23 个 bundle、430 项摘要校验）。上述本地验证对应 e962419。后续文档提交 06999c4 明确了归档复制路径。该提交的 GitHub ready/review CI 状态为 action_required，目前为 0 个 job，尚无远端全量测试结果。

#344 还包括 Dashboard 轮次展示与统计口径的验收。通过这份 JSON 可以复盘单轮决策；评价召回率需要独立确认当时语料中的适用材料，判断性能收益需要实验对照。

[amy-why-3459]

Review（仅评论，不是 Approve）

本次范围：新 PR 完整 diff，3f560642a44a1496aa4984ab936517693be2c788..eb984bb8f23a1d0ed1e3d782542794c6dd3760fd（9feb9b46 与 eb984bb8 两个提交）。重点看了 src/inferrsi/harness/codex_search.py、src/inferrsi/harness/search_attribution.py、CLI 参数和两组测试；文档部分只做了一致性浏览。

整体思路很清楚：轮次窗口由调用方显式给出、无法解释的命令记进 unresolved_command_lines 并把 counts 置空、采用依据必须指向本轮的助手消息，这些边界都和 #344 的讨论一致。下面几处会让“complete”记录里出现错误计数，建议在首版里修掉：

需要修改

1. 不带 -n 的上下文输出会产生虚假命中。 codex_search.py 第 73–75 行只在第一段能匹配 \d+- 时把行当作上下文行跳过，这依赖行号。Codex 里 rg 的 stdout 不是 TTY，默认不输出行号，所以 rg -C 2 key . 的上下文行形如 case.md-some text: foo。这类行含冒号时，第 82 行的 ^([^:]+): 会把 case.md-some text 解析成路径；它在搜索范围内，_material() 也会接受，于是记录一个不存在的材料，且整轮仍可能是 complete。建议：带 -A/-B/-C/--context 但没有 -n/--line-number 时直接把该命令记为无法解释（返回 None, False），或者只在能确认行号格式时解析。请补一个对应测试。
2. cat 部分失败时少记读取，却仍算完整。 第 164–165 行在 code != 0 时返回 None, True。cat a.md missing.md 会输出 a.md 的内容并以 1 退出，结果这次读取被丢掉，且这一行不进 unresolved_command_lines，--complete 下 counts 会少算。建议：refs 非空且退出码非 0 时返回 None, False（标为未解析），而不是视为完整的零读取。也请补测试。
3. CI 尚未在当前 head 上运行完整测试。 eb984bb8 上目前只有 declarations（通过）。PR 描述也写明完整 CPU 测试结果待补。转为 Ready 前请确认 full-check / installed-package 在这个 head 上通过。

需要确认

• --knowledge-root 没有做 resolve() / normpath，而 rollout 里的 cwd 是原样比较的（第 17–21、138–140 行附近的 is_relative_to(corpus)）。如果调用方传入带 .. 的路径，或者 rollout 记录的是符号链接解析后的真实路径，所有命中都会落到“范围外”并被标成未解析。这是有意为之（宁可 partial），还是应该至少对 knowledge_root 做一次 os.path.normpath？
• _round_candidates() 在 evaluation.json 损坏和缺失时都给出 evaluation: null, verdict: null，两种状态无法区分。是否需要把 result_state 一并写入记录？

小问题（不阻塞）

• codex_search.py 从 dashboard_data 引入了私有的 _relative_location、_text，search_attribution.py 也引入了 _inside、_object。如果这些会被多个模块长期复用，可以考虑移到公共的 helper 模块。

首版范围和仓库级验收按描述仍待 #344 的维护者确认，这里不代为判断。

[amy-why-3459]

增量 review（仅评论，不是 Approve）

本次范围：eb984bb8f23a1d0ed1e3d782542794c6dd3760fd..49086cf74657fa89baffc74201dc1cac7c72999e（提交 49086cf7），对照我上一条 review。

已解决

1. 不带行号的上下文输出：_rg_args() 现在区分 numbered_context / unnumbered_context，后者在 _rg_hits() 开头直接返回 [], False，保留搜索事件但不归属命中。带行号时，形似上下文的行若同时像 file:N: 匹配行就标为不完整，不再猜。新测试 unnumbered-context 和 test_ambiguous_numbered_context_cannot_invent_another_file 覆盖了这两种情况。
2. cat 部分失败：refs 非空且退出码非 0 时返回 None, False，这一行进入 unresolved_command_lines，counts 为 null；partial-cat 测试覆盖。
3. 路径规范化：read_window() 对 corpus、_command() 对 cwd 都做了 os.path.normpath，文档也说明了按 trace 中的原始写法（含符号链接名）传入。这个取舍我认可。
4. evaluation 状态：候选记录新增 evaluation_state，missing / corrupt 都有参数化测试。

仍未完成

• CI：49086cf7 上仍然只有 declarations（通过），full-check / installed-package 还没有在这个 head 上运行。PR 仍是 Draft；转为 Ready、完整测试在当前 head 通过后我再看一次，届时如无新问题即可 Approve。

代码层面本轮没有发现新的问题。

[amy-why-3459]

增量 review（仅评论，不是 Approve）

本次范围：49086cf74657fa89baffc74201dc1cac7c72999e..0896f309d061f695cb884c00db74ce046e2cb7d1（提交 0896f309）。

本轮改动，看过没有发现问题

• --files 的识别：判断从 "--files" in argv 改为在 _rg_args() 的解析循环中识别。作为 -e 的值或 -- 之后的操作数时，--files 现在按字面搜索处理，不再被误当作文件清单。test_literal_files_option_is_a_search 覆盖了这两种写法。
• 多行 shell 脚本：bash -c / -lc 等的脚本只要含换行，就整体标为 unresolved，避免把多条 rg/cat 共用的 stdout 混在一起归属。参数化测试覆盖了 rg 和 cat 两种情况。
• 上下文被省略的 used 声明：优化日志声称 used、但 capture 中该条目 resources 为空时，_log_uses() 不再计为 used，而是写入 materials[ref]["conflicts"]（reason: context_omitted）。materials[ref] 在 import_search() 第 196 行已经由 capture 事件建好，不会 KeyError。rejected 仍照常记录，这一取舍我认可。

可选（不阻塞）

• src/inferrsi/harness/codex_search.py 的 multiline = "\n" in argv[2].strip()：用反斜杠续行写成多行的单条 rg 命令也会被判为 unresolved。偏保守，结果只是 counts 为 null，不会算错。如果实际 trace 里常见这种写法，可以考虑先去掉 \\\n 续行再判断。

仍未完成

• CI：0896f309 上仍然只有 declarations（通过），full-check / installed-package 还没有在当前 head 上运行，PR 也还是 Draft。完整测试在当前 head 通过后，我会再看一次。

[amy-why-3459]

增量 review（仅评论，不是 Approve）

本次范围：0896f309d061f695cb884c00db74ce046e2cb7d1..e9624197bb89b3fb99b78475634e75ffb404829d（一个新提交 e9624197，19 个文件，+3,700 行左右）。重点看了新增的 src/inferrsi/harness/codex_tool_returns.py、search_archive.py、capture_delivery.py，search_attribution.py 中 --archive-review 的接入，以及 Qwen S2-B1 evidence 包；codex_search.py 的大段改动和三个新测试文件只做了一致性浏览。

看过、没有发现问题

• 外层 call/result 的关联（codex_tool_returns.py correlate_window()）比较保守：call_id 重复、一个 call 有多个 output、窗口内出现同 cwd 同命令的多次执行，或者扫描中有无法解析的行，都会落到 state: unknown，不会去猜。截断返回只用内容唯一的完整行反查源行号（L165-171），这个取舍我认可。
• review 输入的校验（search_archive.py read_archive_review()）：字段白名单、完整 SHA、可移植的相对路径、decision_quote 经过脱敏后必须不变，这些都齐全。reviewed_uses() 要求引用的事件已经验证为 visible、决策行必须在工具返回之后、passage 定位唯一，否则直接报错。
• 写入顺序：import_search() 先把 reviewed_uses() 全部跑完（L314-315），然后才执行 _write() 和 _write_archive()，所以校验失败不会留下只写了一半的记录。
• evidence 包：我按冻结的语料版本 f6d200775d554d08fb73673833611dd6ac02d14b 核对了 qwen-ascend-rejected-directions.md。README 和 search/round-1.json 里引用的第 6、16、18、19 行内容都对得上。round-1.json 是 schema_version: 2，coverage: partial，counts: null，和 results/summary.json 一致。我没有在里面找到绝对路径或 rollout 文件名。

需要修改或确认

1. CI 仍未在当前 head 上跑完整测试。 e9624197 上只有 declarations（通过），full-check 和 installed-package 都没有运行，PR 也还是 Draft。这次新增了约 750 行测试（tests/test_codex_search_delivery.py、tests/test_search_archive.py、tests/test_search_capture_delivery.py），请在转为 Ready 后确认它们在这个 head 上通过。
2. evidence/README.md 新增段落的措辞容易让人复制错文件。 那里写的是 “archive its reviewed search/round-<n>.json”，可是在本地 campaign 里，search/round-<n>.json 是 v1 的本地窗口记录；可移植的 v2 文件在 search/archive/round-<n>.json（search_attribution.py _write_archive()，docs/dashboard.md 第 57-58、88-89 行也是这么说的）。建议改成“把 search/archive/round-<n>.json 复制为 evidence/<campaign-id>/search/round-<n>.json”，避免有人把带本地路径的 v1 记录提交进来。
3. 请确认： tests/test_evidence_inventory.py 把 bundle 数量写死为 23。如果 main 上其他 PR 先合入了新的 evidence 包，这里会和它冲突，需要 rebase 后再更新。这一点只是提醒，不需要现在改。

可选（不阻塞）

• search_archive.py 没有检查 decisions 里是否有完全相同的条目。重复的条目会通过 _use() 被记两次，可能把 observed.used 多算。如果 _use() 已经去重，可以忽略这一条。我没有在这次 diff 里确认这一点。

[amy-why-3459]

增量 review（仅评论，不是 Approve）

本次范围：e9624197bb89b3fb99b78475634e75ffb404829d..06999c4842d218a535ce09ac8d9c329833b92d98（提交 06999c48，只改了 evidence/README.md），对照我上一条 review。

已解决

• 归档文件的来源和去向：evidence/README.md 现在明确要求把本地 campaign 的 search/archive/round-<n>.json（--archive-review 生成的可移植 v2 记录）复制到 evidence/<campaign-id>/search/round-<n>.json，也说明了本地的 search/round-<n>.json 是 v1 窗口记录。这和 _write_archive() 以及 docs/dashboard.md 的说法一致，上次的第 2 点已经解决。

仍未完成

• CI：06999c48 上仍然只有 declarations（通过），full-check / installed-package 还没有在当前 head 上运行，PR 也还是 Draft。上一轮新增的三个测试文件需要在完整测试里通过。转为 Ready、完整测试在当前 head 通过后我再看一次，届时如果没有新的问题就 Approve。
• 上次第 3 点（tests/test_evidence_inventory.py 写死的 bundle 数 23）和可选项（decisions 里重复条目的去重）只是提醒，不阻塞。

本轮没有发现新的问题。

[amy-why-3459]

增量 review（仅评论，不是 Approve）

本次范围：06999c4842d218a535ce09ac8d9c329833b92d98..a4c8a511fab210e8b7c7157989308dd5f8ccd5ce。新 head 是一个合并提交（a4c8a511），把 main 合进来，main 一侧到 4b3afa55f278ca314e07d5f8acbd0a18f3fa72bf。

看过，没有发现问题

• 冲突处理：git show --remerge-diff 显示只有 tests/test_evidence_inventory.py 一处冲突。处理结果是 bundle 数 24，checked_hashes 为 533，同时保留了本 PR 和 evidence: track H3 Ref2VA on four logical Ascend 910C devices #317 各自新增的 evidence 包。
• 数值核对：我在合并后的树上直接运行了 tools.validate_evidence.validate_inventory()，结果是 errors == []，bundle 数 24，checked_hashes 533，与测试里的断言一致。上次提醒的第 3 点（写死的 bundle 数）已经随 rebase 更新。
• 本 PR 自身的改动没有变：我分别取了本 PR 合并前相对 3f560642 的 diff 和合并后相对 4b3afa55 的 diff，逐行对比。除这处计数外完全相同，都是 21 个文件，+4347/-1。

仍未完成

• CI：a4c8a511 上仍然只有 declarations 通过，full-check / installed-package 还没有在这个 head 上运行，PR 也还是 Draft。之前新增的测试文件还需要在完整测试里通过。等 PR 转为 Ready、完整测试在当前 head 通过后，我再看一次。

本轮没有发现新的代码问题。