Merge pull request 'A3 capability recall evaluation set and metrics baseline' (#713) from feature/catalog-recall-eval-a3 into main

2026-10-23 03:08:41 +00:00
parent fa79a8eb84 d610a99274
commit bccb88f294
6 changed files with 220 additions and 4 deletions
@@ -0,0 +1,168 @@
+# feature/catalog-recall-eval-a3 任务卡
+
+任务主记录：PR #713 https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/713；状态：已完成（合入前闭合）；owner：weichen
+
+## 基线与授权
+
+- 权威仓：ssh://git@git-ssh.u1680832.nyat.app:31411/weichen/Agent-System-Dev.git；目标分支：main；R0（initial_base_sha）= 6ced938a126981ee2a4fab671a2da94f49cb56c5
+- 工作区：/home/weichen/projects/Agent-System-Dev-wt-feature-catalog-recall-eval-a3（worktree）；分支：feature/catalog-recall-eval-a3
+- 分支类型：standalone；root_target：main；immediate_target：main；accepting_requirements：false
+- 需求分流：verdict=NEW；selected_initiative=无；requirement_sha256=bf205afb1f04e503573784c93b52a991095554ed7314d9ac0f6c1996660a3211；triage_receipt=/tmp/triage-a3-1792716554.json；receipt_sha256=1a4ee8fe2133a52386520d35955d0fc600817f9a6bd94d40730eb8fce0904f44
+
+- 授权与交付终点：用户已批准启动 A3 能力目录召回评测（方案 Functional Follow-Ups 第三项：先建脱敏评测集并产出指标基线，"是否需要检索/调模型"的决策由基线数据支撑、另行决策）。范围内连续推进：设计、agent-per-unit 实施、验证、组合、Review、PR/CI/合入。未授权：检索实现、模型/提示词调整、A2 后续、A4、部署。
+- 设计决定（2026-10-22，host）：
+  1. 评测落在 agent-intent 既有机制上（cmd/intentctl eval + testdata/corpus.json 共用格式），不新建平行体系。
+  2. 数据集五类覆盖（否定/引用指令、多意图、错误槽位、过期确认、生成规则一致性），全部合成脱敏、由现有 fixture 规格派生；规模 ≥30 例。
+  3. 指标层只记录不设质量阈值：top-1 命中率、误执行数（命中≠预期动作）、澄清率、fallback 率、生成 vs 规则一致性（离线 fake generator）。
+  4. 基线报告（evaluation/BASELINE.md + metrics.json）随库提交，附复跑方式；质量结论由人/后续任务基于数据做出。
+- 交付模式：goal-first（目标、范围和交付终点一次确认；范围内连续推进）
+- 实施执行：agent-per-unit（配置：AGENT-EXECUTION.md）
+- 合入执行：agent（已授权交付范围内，Review 通过、冲突解决且当前 HEAD 的 CI 通过后合入）
+- 人工决策点：仅限目标/范围/验收变更、重大取舍、高后果操作或无法自动判定的业务验收
+- 当前阶段：需求拆解；当前增量：I1（待定义）
+- 流程依据：仓库根目录 policy/delivery.md（归档后仍按仓库根目录定位）
+
+## 目标与非目标
+
+**目标**：脱敏评测集（五类 ≥30 例）+ intentctl eval 指标输出（JSON 与表格）+ 基线报告；离线可复跑（fake generator，无真实模型调用）。
+
+**非目标**：检索/召回增强实现；提示词或模型调整；真实用户数据；控制台；A2 后续/A4。
+
+## Agent 实施收据
+
+路由与 fail-stop 规则见根目录 AGENT-EXECUTION.md 与 policy/delivery.md；每次尝试一行，原始日志留在源码外收据路径。
+
+| 单元 ID | 预期范围 | 配置摘要 | 角色 | 候选顺序 | attempt | CLI/模型 | 终态 | transport | fallback | 源码外收据路径 |
+|---|---|---|---|---|---|---|---|---|---|---|
+| 待定义 | — | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | NOT_RUN | — |
+
+## 关联方向与规划
+
+- 适用状态：待核对（无适用规划时说明原因）
+- 主记录路径/版本：待核对（路径按仓库根目录定位，归档后不变；只引用唯一正文）
+- 对应里程碑：待核对
+
+## 需求分析
+
+| ID | 描述 | 项目符合度及依据 | 优先级 | 验收条件 | 依赖 | 结论 |
+|---|---|---|---|---|---|---|
+| R1 | 待填写 | 待评估 | 待定 | 待定义 | 待确认 | 待评审 |
+
+## 方案与计划
+
+- 方案引用：待填写（含对象版本）
+- 实施计划引用：待填写（含增量与需求 ID）
+- 测试计划引用：待填写（含需求 ID 与验收条件）
+
+## 阶段记录
+
+| 阶段 | 对象版本 | 状态 | 决策/执行者 | 时间 | 依据 |
+|---|---|---|---|---|---|
+| 需求拆解 | 待定 | 待执行 | — | — | — |
+| 需求评估 | 待定 | 待执行 | — | — | — |
+| 需求表确认 | 待定 | 待执行 | — | — | — |
+| 方案设计 | 待定 | 待执行 | — | — | — |
+| 实施计划 | 待定 | 待执行 | — | — | — |
+| 实施与自检 | 待定 | 待执行 | — | — | — |
+| 正式测试与验收 | 待定 | 待执行 | — | — | — |
+| 代码 Review | 待定 | 待执行 | — | — | — |
+| 合入 | 待定 | 待执行 | — | — | — |
+| 合入核验与收口 | 待定 | 待执行 | — | — | — |
+
+## 探索试验与迭代
+
+| 增量/试验 | 假设 | 范围 | 判断和停止条件 | 授权/决策依据 | 结果 | 变更影响 | 需重审补测 |
+|---|---|---|---|---|---|---|---|
+| 待定义 | — | — | — | 待核对 | NOT_RUN | 待评估 | 待评估 |
+
+## 同步记录
+
+| 节点 | sync_base_sha | tested_head_sha | checked_at |
+|---|---|---|---|
+| 启动 | 6ced938a126981ee2a4fab671a2da94f49cb56c5 | 6ced938a126981ee2a4fab671a2da94f49cb56c5 | 2026-10-23T00:51:18Z |
+
+## 证据（Evidence）
+
+<!-- CMD="<命令>" make evidence 写入；手抄/转写输出视为无效证据（AGENTS.md 证据与验证门禁）。 -->
+| 时间(UTC) | 命令 | 被测HEAD | exit | 来源 | sha256(16) |
+|---|---|---|---|---|---|
+
+## 交付调度
+
+- 调度状态：未入队；调度记录：无
+- entry_id：无；attempt_id：无；窗口执行者：无
+- 固定候选：无（base/head、组件与相关配置引用实际尝试）
+- 调度依据：policy/delivery.md#合入调度
+- 固定后证据：源码外 RECEIPT；实际结果后按授权原样导入和闭合
+
+## 结果与验证
+
+- 结果：
+- 验证：<结论摘要 PASS/FAIL/SKIP/NOT_RUN 逐项；逐条证据由 make evidence 写入上方证据表>
+- 影响与剩余项：
+
+## 规划进展与下一步
+
+- 本次推进/剩余：待核对（依据实际成果更新适用方案/规划）
+- 首选下一任务：待核对（无适用规划、已完成或受阻时如实说明，不虚构任务）
+- 推荐依据：待填写
+- 前置条件/待确认：待核对
+- 预期产物/验收条件：待定义
+- 重复任务核对：待核对（已有/在途任务、PR 与规划记录）
+- 启动授权：未授权（建议不自动启动新任务，仍须明确授权）
+
+## 合入与清理
+
+- 实施收据：a3-recall-eval-dataset（cursor attempt1，五类语料+指标+基线报告，intent 6aa4925，verify-a3 exit=0）；gitlink 集成（native d1f72aa/squad a5afe9c/backend 8dc91c1 含嵌套 intent/native 级联，a3git5/a3git10-run.json）。
+- 组合验证：全量 make test PASS（verify-a3-combo3.json exit=0）。
+- Review 记录：独立 CLI 评审单元 a3-independent-review（收据 /tmp/agent-stack-b2/reviewa3-run.json）；结论 APPROVE；报告 .task/reviews/2026-10-22-a3-recall-eval-independent-review.md；被审对象 35524f3d 组合 vs main
+- 冲突记录：NOT_RUN（最新目标同步、冲突处置、组合兼容核验及复审/补测）
+- CI 记录：NOT_RUN（当前 HEAD 完整 SHA、全部必需检查、运行链接、执行身份及 GATE 结果）
+- 合入记录：NOT_RUN（交付授权范围、PR、被核验 HEAD、合入 SHA、目标分支及内容核验）
+- 清理记录：NOT_RUN（授权依据、写者退出确认、worktree/分支/任务卡处置）
+
+<!-- Local receipt: SELF. Digests detect corruption; they do not authenticate a reviewer or CI. -->
+```json
+{
+  "summary_schema": 1,
+  "source": "SELF",
+  "timestamp": "2026-10-23T00:50:13.586423+00:00",
+  "command": "make precheck",
+  "exit_code": 0,
+  "cwd": "/home/weichen/projects/Agent-System-Dev",
+  "before_head": "6ced938a126981ee2a4fab671a2da94f49cb56c5",
+  "after_head": "6ced938a126981ee2a4fab671a2da94f49cb56c5",
+  "branch": "main",
+  "target_branch": "main",
+  "target_head": "6ced938a126981ee2a4fab671a2da94f49cb56c5",
+  "root_target": "main",
+  "immediate_target": "main",
+  "before_tracked_diff_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  "after_tracked_diff_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  "output_tail": [
+    "make[1]: Entering directory '/home/weichen/projects/Agent-System-Dev'",
+    "[repo]   branch=main head=6ced938a12",
+    "[remote] origin/main=6ced938a12 ahead=0 behind=0",
+    "[tree]   clean submodules_drift=0 uninit=0",
+    "[worktrees] linked=8",
+    "[recycle] merged un-recycled branches: feature/exec-recovery-diagnostics-a2 fix/rdm-pin-advance-latest-2",
+    "[initiatives] local cards (not authoritative): none",
+    "[hooks]   core.hooksPath=scripts/hooks（pre-commit/post-merge 实际接线）",
+    "[facts]   policy/facts.md 6 条事实均在有效期内",
+    "[required-reading] core/baseline.md, workflows/delivery.md §1, policy/delivery.md",
+    "[R0] 6ced938a12（完整：6ced938a126981ee2a4fab671a2da94f49cb56c5）",
+    "[worktree] before-sync: recursive component checks passed",
+    "[verdict] READY — 保留本次 precheck receipt 后建任务工作区：PRECHECK_RECEIPT=/tmp/task-precheck.json make task-start NAME=feature/your-branch",
+    "make[1]: Leaving directory '/home/weichen/projects/Agent-System-Dev'"
+  ],
+  "output_sha256": "9f6b7e8979503847e2ec5623a17ee9624cbafd5450149556482244a86abe9192",
+  "receipt_sha256": "1cf2c62aea8ef98b5d211cb94c053174407c70aeab274681c1b77db0a2878db9",
+  "receipt_path": "/home/weichen/.cache/agent-system-dev/evidence/1cf2c62aea8ef98b5d211cb94c053174407c70aeab274681c1b77db0a2878db9.json"
+}
+```
+
+## 闭合记录（合入前折叠）
+
+- 本卡在 PR #713（https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/713）合入前闭合并归档，随该 PR 一同合入。
+- 该 PR 的合并提交即本任务的落地记录。
+- 合入后无需回填，也无需单独的闭合 PR。
@@ -0,0 +1,48 @@
+# 独立代码 Review：feature/catalog-recall-eval-a3（A3 召回评测集与指标基线）
+
+- Reviewer：独立 CLI session（未参与本单元实施；本报告为唯一产出变更）
+- 日期：2026-10-22
+- Review 对象：`git diff 6ced938a...HEAD`（6ced938a = R0 / origin-main 合入点，与任务卡 R0 一致）
+- 组件重点：`deps/agent-intent` 765a7e7..6aa4925（单提交 "Add the sanitized recall evaluation set and metrics baseline"，9 文件 +1354/-18）；Dev 层 4 个 gitlink 前移 + 任务卡
+- 方法：全量 diff 阅读被测文件；对语料/指标做独立的脚本化交叉复核（只读）；静态追踪指标口径、生成回放路径与 JSON 兼容性；检查嵌套 pin 级联与越界改动。聚焦测试见下文 NOT_RUN 说明。
+
+## 复核结论摘要（独立重算，非转抄）
+
+- 语料 `intent/testdata/recall_corpus.json`：**37 例 / 46 轮**，五类齐全且恰好五类（expired_confirmation 7/14、generation_consistency 8/8、multi_intent 7/7、negation_reference 8/10、wrong_slot 7/7），`record_only: true`；`expect_top` 轮次 31、生成用例 8 —— 与 BASELINE.md 表头逐项一致。
+- 语料 digest `sha256:53d26cfc…bc2885` 与 `evaluation/metrics.json` 的 `corpus_digest`、BASELINE.md 摘要三方一致（本机 `sha256sum` 独立重算）。
+- `evaluation/metrics.json` 全部 10 组计数与比率逐项等于 BASELINE.md 表；比率均可用 `round(n/d*10000)/10000` 独立复算（如 30/31→0.9677、13/46→0.2826、6/46→0.1304、5/14→0.3571、5/8→0.625、5/7→0.7143、3/7→0.4286）。
+- 总体口径自洽：top1_expected 3+3+7+11+7=31、hits 30（唯一 miss 即 multi_greet_then_report 的 1 次误执行）、mis_exec 5+1=6、clarify 0+0+5+5+3=13、fallback 2+0+0+3+0=5+1(gen)=6、pass 3+6+7+7+8=27。
+- 嵌套 pin 级联一致：native@d1f72aa→intent@6aa4925；squad@a5afe9c→intent@6aa4925+native@d1f72aa；backend@8dc91c1→intent@6aa4925+native@d1f72aa+squad@a5afe9c（各自 `git ls-tree` 核对）；三个组件 bump 均为 pins-only（`git diff --stat` 仅 gitlink），superrepo 层 diff 仅 4 gitlink + 任务卡，无评测范围外源码改动。
+
+## Findings
+
+### Blocker
+
+无。
+
+### Major
+
+无。
+
+### Minor
+
+1. **基线数值漂移不设防（结构性盲区，刻意取舍但建议记录）** — `intent/recall_eval_test.go:119-162`（`checkSummaryJSON`/`checkMetricsBounds`）：结构测试对已提交基线只校验 schema、digest、类别计数与「内部一致」（rate==ratio(n,d)），不把基线里的 hits/rates 与本次新鲜运行比对。若识别器行为改变而语料不变（digest 不变、计数不变），过期的基线数值不会被任何测试发现；BASELINE.md「重跑」一节只靠流程约束。这与「只记录不设阈值」的定位一致（比对数值即变相质量断言），属可辩护的设计取舍，但建议在 BASELINE.md 明示「引擎变更不会触发基线失效告警，须人工重跑」。
+2. **missing-slots 断言用 `fmt.Sprint` 比较切片** — `intent/corpus.go:194-222`（`matchTurn` 中 `fmt.Sprint(got) != fmt.Sprint(turn.ExpectMissingSlots)`）：`[]string(nil)` 与 `[]string{}` 都打印 `[]`，且比较对元素顺序敏感。当前引擎输出顺序确定、语料只断言单元素缺失（`["run_id"]`/`["topic"]`），不构成现实缺陷；但后续一旦断言多缺失槽位，顺序耦合会变成脆弱测试。建议改为逐元素显式比较。
+3. **任务卡内部记录不一致（文档级）** — `.task/feature-catalog-recall-eval-a3.md`：「Agent 实施收据」表全部为 NOT_RUN/待定义 占位，而「合入与清理」节已记载 `a3-recall-eval-dataset（…intent 6aa4925，verify-a3 exit=0）`、嵌套级联与 `组合验证：全量 make test PASS`；且「证据（Evidence）」表为空，组合验证结论以带外文件名（verify-a3-combo3.json 等）引用。按仓库门禁「命令输出只经 make evidence 写入任务卡」，合入前应把收据表与证据表补齐一致。不阻塞本次代码评审结论。
+
+### Notes
+
+1. **指标口径正确** — `intent/evalmetrics.go:129-141`（`misExecuted`）：仅当实际 `matched`/`expectation_hit` 出 Top 且与期望动作不同时计数；期望 matched/expectation_hit 而未写 expect_top 的轮次不约束动作，不计；期望 fallback/ambiguous/guard_hit 却执行了即计。与 BASELINE.md「指标口径」一节逐条一致。分母：top1=写了 expect_top 的轮次（`evalmetrics.go:103-108`）、clarify/fallback=全部轮次（`evalmetrics.go:111-118,153-159`）、gen_agree=写了 generator_commands 的用例数（用例级，`evalmetrics.go:120-124`）。`ratio` 定点 4 位舍入保证 JSON 字节稳定（`evalmetrics.go:161-166`）。
+2. **汇总对账安全** — `intent/evalmetrics.go:61-92`（`SummarizeCorpus`）：cases/results 按下标一一对应（越界即 break，契约已在注释声明），空 category 归入 `uncategorized`（旧语料兼容），类别名升序、overall 独立。`intent/eval_test.go:78-89` 在既有 `corpus.json`（无 category）上跑了一遍汇总，兼容路径有覆盖。
+3. **生成回放路径离线、确定性、fail-closed** — `intent/corpus.go:156-186`：`replayGenerator.Generate` 忽略输入与目录、只回放脚本命令（无模型/无网络），并深拷贝 slots 防串染；`compareGeneratorPath` 复用识别器兜底同款 `generateCommands`（`intent/recognizer.go:352-385`：start 的 ActionRef 必须从同一快照唯一解析、命令种类受限、槽位键集校验，任一不过即无 Top）。三个「故意不一致」用例路径成立：`run_id=43` 槽位分歧（sameSlots 判否）、`taskrun.restart` 错动作（handler 反查到 restart spec）、`ghost.flow` 幻觉动作（resolveActionRef 失败→校验拒绝→无 Top）。两边都无 Top 也算一致，`gen_chitchat_agree` 覆盖该分支。Nil expectation 传入 `NewRecognizer` 在该路径安全（`generateCommands` 不触达链式预期）。
+4. **eval 向后兼容** — `cmd/intentctl/main.go:254,260-262,365-390`：`-metrics-out` 缺省为空不写文件（唯一新增写文件入口，显式 opt-in；`-` 走 stdout）；旧语料（无 `record_only`）失败语义不变，且 `TestEvalRecordOnlyWritesMetrics`（`cmd/intentctl/main_test.go:79-112`）同时断言 record_only 不失败+strict 语料仍失败。输出新增的指标表为追加行，不破坏既有两行指标输出。`evalCorpus` 结构仅增可选字段（`omitempty`），旧 JSON 解析不受影响。
+5. **结构测试无质量阈值伪装** — `intent/recall_eval_test.go:64-117`：只断言 ≥30 例、恰好五类、每例可执行（无「识别错误」）、generation_consistency 用例形态、JSON 合法且计数与语料一致、基线 digest 与语料一致；`checkMetricsBounds`（:164-186）只做数学界校验（n≤d、rate==ratio）。无任何质量数值断言，符合「基线只记录」边界。测试与 CLI 同源建快照（:36-62，语料自声明 builtin_specs/guard/protected + 同款 specs 目录），指标同源声明成立。
+6. **语料确为夹具派生、五类行为真实可辨** — 全部期望 top ∈ {demo.run.status_query/restart/cancel, demo.greet.hello, demo.misc.deploy, report.generate, guard.config_change}，动作 id ∈ base.json 的 handler 集 + 刻意的幻觉 id；生成动作 id 与 `intent/testdata/specs/base.json` 的 handler/action 一一对应。各类用例确实 exercising 所标行为：语义否定（「不要/别/不用/先不要」无 excludes 声明，理想为 fallback）对照 `excludes_any` 声明否定（「配置」）；multi_intent 覆盖 动作+动作→ambiguous、寒暄+动作→动作、动作+guard→guard_hit；wrong_slot 覆盖 缺失/中文数字/双候选/越字符集/仅符号/空主题；expired_confirmation 覆盖 链式命中、过期后裸回答回落、过期后完整重述走 matched、宿主声明 pending 再过期（`pending_expectation`+`expectation_expired` 组合，语义为「先声明后作废」，实现顺序 `intent/corpus.go:120-126` 与用例意图一致）；wrong_slot 用单轮 `turns` 包装以使用本轮新增的 `expect_slots`/`expect_missing_slots` 能力。
+7. **安全边界** — 语料全合成（无真实用户数据/PII）；`record_only: true` 无阈值断言；生成路径为确定性回放，无网络/模型调用；未发现任何对外部输入的写路径（除显式 `-metrics-out`）。
+8. **聚焦测试 NOT_RUN（环境受限，非变更缺陷）** — `cd deps/agent-intent && GOWORK=off go test ./intent/...` 无法编译：`agent-intent` 的嵌套 gitlink（deps/error-code-system@a3ee67b、logging-system@49b5d8b 等）在本工作区未物化，且目标提交不在任何本地对象库（`git cat-file` fatal）、无网络。按诚实出口如实标注 NOT_RUN；作为补偿，本文「复核结论摘要」的计数/digest/比率均为独立脚本重算，与基线三方对账一致。任务卡所记 `make test PASS（verify-a3-combo3.json exit=0）`本评审无法复现，标注 [未经证实]（属 host 组合门禁范畴，不阻塞代码评审）。
+
+## Verdict
+
+未发现 blocker/major 级代码缺陷；三项 minor（基线漂移不设防的取舍说明、fmt.Sprint 切片比较的脆弱写法、任务卡收据/证据表未同步）均不阻塞合入，可在本次或后续增量处理。语料、指标、基线、CLI 兼容、结构守卫与嵌套 pin 级联均通过独立静态复核与数值对账。
+
+REVIEW VERDICT: APPROVE