审查报告：offline-eval-workflow（PR #6 / `eval_mvp`）¶

状态: 审查完成（本地）日期: 2026-08-06 分支: feat/offline-eval-workflow @ f24329c 基线: develop 关联: offline-eval-workflow-issue.md、offline-eval-workflow-pr-comment.md

1. 结论¶

方向正确，评论清单的主路径已落地：OpenCode JSONL 可解析、默认三产物、golden fixture + 稳定字段 diff、本地 8/8 测试通过。合并前需处理 fixture 敏感信息与「events.jsonl 实为聚合计数」的命名/语义澄清；opencode.db 直读仍属未实现扩展。

2. 审查范围¶

项	内容
提交	`1796be4` Claude reader PoC → `6159a44` issue/PR 文档 + OpenCode 测试数据 → `f24329c` OpenCode 评测 + 期望产物
核心代码	`eval_mvp/claude_trace_reader.py`、`eval_mvp/schemas/sqlopt-workflow-event-v1.schema.json`
测试	`eval_mvp/tests/test_claude_trace_reader.py`（8 cases）
输入 fixture	`eval_mvp/test_dataset/session_full_export.jsonl`、`opencode-db.txt`
期望产物	`eval_mvp/tests/fixtures/expected/{events.jsonl,report.csv,manifest.json}`
文档	`eval_mvp/README.md`、issue/PR 说明文档

非范围：SQL 优化 skill 主流程、sql-distributed 产物路径、把评测挂进 agent 运行时自动触发。

3. 功能定位与触发¶

离线评测器，不在 agent 优化流程内自动触发。会话结束后人工/脚本调用：会话日志（Claude JSONL / OpenCode export）→ claude_trace_reader.py（只读）→ sqlopt-workflow-event/v1 → 默认三产物。不连库、不写回会话、不改 pipeline；事件统一标 trace_quality=inferred。

# Claude：本地会话目录即可（一般无需另导出）
python3 eval_mvp/claude_trace_reader.py \
  --trace path/to/logs --session-id <id> \
  --workspace-root path/to/workspace --out-dir eval_mvp/outputs/trace_run

# OpenCode：当前必须有导出 JSONL（opencode.db 直读未实现）
python3 eval_mvp/claude_trace_reader.py \
  --trace path/to/session_full_export.jsonl --out-dir eval_mvp/outputs/opencode_run

验收不需要 --full。opencode-db.txt 仅 schema/只读查询参考。

4. PR 评论验收（产物 + Checklist）¶

评论清单主路径均 ✅。默认只出三份（--full 才开 metrics / tool_calls / artifact_checks）：

文件 / 评论项	状态	说明
OpenCode 解析 `session_full_export.jsonl`；README 只读边界	✅	db 直读仍是未来项
`workflow_events.jsonl`	✅	运行时是工具调用明细；期望 fixture 存的是 case/stage/status 聚合计数（12 行）
`workflow_report.csv`	✅	case 汇总主看板（含 artifact 列）；整表比对
`trace_manifest.json`	✅	sha256 / 格式 / 输出清单；比对时去掉路径、run_id、时间戳
`case_id` 兼容非 tdsql	✅	单测覆盖 `gcsdb_` / `adhoc_`
`expected/` + 稳定字段 diff	✅	events（聚合）/ report / manifest

OpenCode fixture 实测：gcsdb_0005 完整路径；gcsdb_0019 缺 precheck/execute。manifest 固化了 3 条 parts[].content JSON 解析错误，属已知行为。

5. 测试逻辑审查¶

eval_mvp/tests/test_claude_trace_reader.py 分两层：

5.1 单元测试（6）¶

case_id 不限于 tdsql（如 gcsdb_0009、adhoc_01）
阶段分类：读脚本 ≠ 执行脚本
blocker 分类
多 session 未指定 --session-id 报错
agent case 扫描不截断在 12 条
tool_call_id 按 session/agent 隔离，event_id 唯一

5.2 CLI 集成（2）¶

Claude 合成日志：构造 baseline → table_ctx → precheck → execute（失败+重试）→ write_result，校验 metrics / blocker / inferred
OpenCode golden：跑 session_full_export.jsonl 默认三产物，与 expected/ 稳定字段 diff

本地重跑结果：

Ran 8 tests in 0.252s
OK

6. 发现问题与风险¶

级别	问题	建议
高	`session_full_export.jsonl` 体积大（~769KB），历史上审查曾发现疑似真实凭据/内网信息	合并前脱敏或换合成 fixture；勿把生产密钥留在仓内
中	`expected/events.jsonl` 文件名像全量事件，实际是聚合计数	README/测试注释写明，或改名为 `event_counts.jsonl`
中	OpenCode 3 条 content 解析失败被固化为期望	记录为 known issue；后续适配器应减少静默丢内容
低	`opencode.db` 只读投影未实现	内网若无法方便导出 JSONL，需单开 follow-up
低	工作区若曾把仓内 `logs/` 挪到 `.tmp/`，会出现大量未提交 `D logs/...`	勿误提交；与本 PR 评测代码无关

7. 建议结论¶

功能与测试主路径可接受合并（在处理敏感 fixture 之后）。
合并前最低动作：
脱敏或替换 session_full_export.jsonl
文档澄清 expected/events.jsonl = 聚合计数
确认不要把 logs/ 删除变更带进本 PR
workflow_report.csv 字段冗余性（测评，非阻塞）：多数列有独立语义；可瘦身候选为
可推导：tool_error_rate（= error/ended）、retry_count（= agent+tool）、observed_stages/missing_stages 二选一、blocker_source（≈ primary 非空）、required_artifact_valid（大半可由 reason 推导）
当前恒定：trace_quality 行行 inferred，无区分度
建议保留：case_id、体量三元组、abandoned、两档 retry 拆分、workflow_completed/happy_path_completed、trace 侧 encountered_blocker_type vs 产物侧 primary_blocker_type+terminal_status、artifact_validation_reason、case_match_confidence
后续可选：opencode.db 只读投影、agent 评测 skill/脚本封装（导出 → reader → 三产物）、report 列瘦身（上条）。

附录：关键路径速查¶

eval_mvp/
├── claude_trace_reader.py
├── README.md
├── schemas/sqlopt-workflow-event-v1.schema.json
├── test_dataset/
│   ├── session_full_export.jsonl   # OpenCode 输入
│   └── opencode-db.txt             # 文档，非运行时输入
└── tests/
    ├── test_claude_trace_reader.py
    └── fixtures/expected/
        ├── events.jsonl            # 聚合计数期望
        ├── report.csv
        └── manifest.json

审查报告：offline-eval-workflow（PR #6 / eval_mvp）¶