专题研究

AIData · water_emergency 全景拆解：从 case 配置到完整轨迹

Nexus-AIDATA harness 上一道供水抢修计费纠纷处置题的端到端走读。覆盖双容器硬隔离、17 张 mock 表的 DATA_PATCH_B64 注入、15 条三层 verifier check、15 个真实 step 的轨迹回放，以及最终 12/15 = 0.800 的总分是怎么打出来的。

AIData Nexus-AIDATA Harness Engineering Verifier Rubric Case Study Agent 轨迹 Walkthrough
新窗口

AIData · water_emergency 全景拆解

这是一篇”打开盒子”的走读。water_emergency 是 Nexus-AIDATA harness 在 nexus/extensions/tasks/aidata/cases/water_emergency/ 下的一道完整 case，模拟某市自来水公司在管网抢修期间产生的计费纠纷处置。围绕这道题，我把它从 静态配置 → 运行时容器 → 工具调用 → verifier 评分 整条链路拆开做了一次端到端走读。

建议直接切到右上角”富文本”视图——这篇 Markdown 只是骨架，真正可交互的内容（文件浏览器、轨迹回放、token 统计、rubric 折叠面板）都在 HTML 版本里。

这篇文档解决什么问题

之前同事进来看 AIData 这套东西，最常见的两个问题：

  1. “一道 case 长什么样？里面到底有哪些文件，谁喂给谁？“——case.yaml、rubric.yaml、data_patch.json、setup.sh、assets/mock_startup.sh 这五个文件（再加 README.md）究竟怎么协作？
  2. “agent 拿到题之后怎么跑，verifier 怎么打分，最后那个总分是怎么算出来的？“——只看 trajectory.jsonl 太干，看 rubric_judgement 又只有结论看不到过程。

走读页就是为了一次性回答这两个问题。

富文本版本的目录

直接戳右上角”富文本”按钮，会用 iframe 把走读页内嵌进来。下面只是节标题预览，方便决定要不要打开。

  • §① TL;DR：一分钟把这道 case 讲清楚——情景、目标、工具、得分。
  • §② 怎么跑：5 行命令把双容器拉起来、agent 跑完、judge 评完。
  • §③ 业务场景：客户视角的题面（计费纠纷、抢修证据、稽核要点）。
  • §④ 运行架构：main + service 双容器硬隔离、MCP 工具集、DATA_PATCH_B64 的注入路径。
  • §⑤ Mock 数据设计：17 张表怎样靠”关键阈值”制造出”该免单 / 该补退 / 该走稽核”三个分支。
  • §⑥ 真实执行时间线：这次跑出来的 15 个 step，按时间线列表逐条展开。
  • §⑦ 分支决策：case 的核心设计——agent 必须先识别异常类型才能选对工具链。
  • §⑧ Verifier 设计：15 条三层 check（regex / llm_judge / combined）的覆盖度与权重。
  • §⑨ 真实评分结果：12 命中 + 3 失败 = 12/15 = 0.800，每条 check 的命中过程。
  • §⑩ 学到的 / 改进方向：为什么是 0.800 而不是 1.0，下一版 case 该怎么改。
  • §⑪ 重放：把 trajectory 渲染成”伪 terminal”，可播放、暂停、调速。
  • 附录 A · Case 源文件浏览器：左侧文件树 / 右侧内容窗，支持 case.yaml 中超长 DATA_PATCH_B64 的折叠、README.md 的渲染态↔原文切换、data_patch.json 的 key 高亮跳转。
  • 附录 B · 完整 log / 轨迹：模拟一次完整跑通的 5 类阶段日志，展开即可逐行查看。

为什么单独做这道 case 的 walkthrough

water_emergency 在 AIData 这一批 case 里有几个”教学价值”特别集中的点，所以适合作为新人/外部协作方的入门 case：

  1. 不是单表查询：要跨 bills × maintenance_orders × complaints × audit_records 等多张表才能对齐”谁该免单、谁该补退、谁该走稽核”。光做 SQL 是过不了 verifier 的。
  2. 服务容器是 mock 出来的：assets/mock_startup.sh 把 DATA_PATCH_B64 解码后注入进 service 容器，是 AIData 标配的”两容器 + 一份 patch”模型最干净的展示。任何想搞自定义 case 的同学，照着这个抄就行。
  3. rubric 的 15 条覆盖三层风格：纯 regex（结构性）、llm_judge（语义性）、combined（先抓结构再喂 judge）。看完这一道 case，basically 整个 aidata rubric DSL 你都见过了。
  4. 0.800 而不是满分：跑出来 12 条命中 / 3 条失败——失败的那 3 条恰好暴露了”格式正确但语义没对齐”的边界情况。比”一把过满分”更有教学价值。

怎么本地跑这道 case

仅作为参考。这部分跟 tuntang 知识库无关，是给真正想动 AIData 仓库的同学的。详细步骤见富文本版本的 §②。

# 0. 前置：完成 setup-nexus-aidata skill §0–§4
#    （uv 装好、submodule 拉好、.env 配好 GONGFENG_TOKEN + LLM key）
cd Nexus-AIDATA
source .env

# 1. 跑！耗时 ~5 分钟
#    （容器拉起 ~60s + agent 主循环 ~3 分钟 + judge 评分 ~30s）
uv run python nexus/extensions/tasks/aidata/aidata.py run water_emergency -v

# 2. 结果文件路径会打印在日志开头，长这样：
#    workspace/mcp/tmp/aidata_water_emergency_<ts>.result.json
#    它包含 score / rubric_results / agent_output.main_trajectory 全量。

如果只是想看”长什么样”而不想跑，直接切右上角富文本视图，案件涉及的所有文件都已经打包到 /research/assets/aidata-water-emergency/ 下，文件浏览器会同源 fetch 它们，不需要本地起 server。

一些有用的链接

  • Nexus-AIDATA 仓库：git.woa.com/nexus/Nexus-AIDATA · nexus/extensions/tasks/aidata/cases/water_emergency/
  • harness 主框架：nexus.extensions.tasks.aidata.engine.rubric 是 verifier 实际跑的入口
  • 同系列 case：emergency_hospital、emergency_incident_response、flight_cancelled、relocation_sz_gz 等十余道——结构同构，只是行业不同

反馈

如果你看完之后觉得有哪一节”还应该展开多讲一点”、或者发现 case / rubric / 轨迹的具体细节有出入，欢迎直接在 Nexus-AIDATA 仓库内提 MR，或在飞书 @ 我。