cwc-workshops harness目录深挖：probes、replay与verify.py的实现原理

cwc-workshops harness目录深挖probes、replay与verify.py的实现原理【免费下载链接】cwc-workshops项目地址: https://gitcode.com/GitHub_Trending/cw/cwc-workshops cwc-workshops 的 agent-battle 工作坊用 Claude 托管 Agent 驱动 Minecraft 挖矿其 harness 目录内置了一条完整的评测→回放→验证工具链probes.py 用 10 个合成游戏状态做秒级决策评测replay.py 把 JSONL 运行日志变成人类可读剧本verify.py 则为前三名颁奖做轨迹防伪核验。本文带你逐层拆解这三个模块的实现原理与设计取舍。一、先看懂背景agent-battle 是什么agent-battle 是一场 45 分钟的实战工作坊你只负责配置一个 Claude 托管 Agent模型 系统提示词 技能 MCP 工具云端 Agent 通过 MCP 驱动本地 Minecraft 机器人5 分钟内挖到的钻石最多者获胜平局比谁消耗的 token 少。整个 harness 目录就是这场Agent 大战背后的支撑层各模块分工如下模块角色agent.py参考实现Claude tool-use 循环的教学范本client.py对接 bot.js 的 HTTP 客户端定义 GameStatelogging_.py每轮运行写一份 JSONL 轨迹 人类可读 thinking 日志probes.py--eval背后的快速决策探针replay.py把 JSONL 轨迹回放成可读文本verify.py颁奖前的轨迹防伪核验leaderboard.py向排行榜上报 token/轮次成本三个主角——probes、replay、verify——恰好覆盖了 Agent 开发闭环的三个时机跑之前快测、跑之后复盘、发奖前防伪。下面逐个拆解。二、probes.py10 个合成状态30 秒测出 Agent 的决策质量2.1 核心思路用假状态代替真游戏一次完整对局要 5 分钟而且结果受矿脉运气影响噪声太大。probes.py 的做法是不启动游戏直接构造一个合成的/stateJSON发给参与者真实配置的 Agent只抓它做出的第一个动作来打分。每个探针约 10 秒全程无 Minecraft 副作用结果落地前就中断会话。Probe 数据类只有 5 个字段设计得极其克制dataclass class Probe: key: str # 探针名如 iron-required title: str # 一句话场景描述 state: dict # 合成的游戏状态 JSON score: Callable # 打分函数(动作名, 参数) → (✓/⚠/✗, 理由) capture_lookup: bool False preamble: str # 补充上下文如你已连续 chat 了 3 次_state()辅助函数提供一套合理的默认状态位置、血量、背包、附近方块每个探针只需覆盖差异字段这就是为什么整个文件能紧凑地装下 10 个场景。2.2 10 个探针考的是什么全部探针集中在 PROBES 列表可以归为三类考点知识类靠技能/Wiki 补事实iron-required石镐挖不了钻石矿得先造铁镐、ore-variant要挖的是deepslate_diamond_ore而不是diamond_ore、depth钻石矿在 y0 的深处别再在 y10 挖石头行为类只有系统提示词能塑造relocate矿脉挖空后应转移 20 格以上、restraint连续 4 次 chat 是浪费 token、discipline矿石就在 2 格外别再 get_state 了、durability镐耐久只剩 9/250该备一把新的、prioritizes剩 2 分钟先挖 3 格外的近矿而不是 35 格外的工具类uses-lookup满屏陌生的 tuff 方块应该先调lookup()查 Wiki 再决定挖不挖——这是唯一开启capture_lookupTrue的探针也是检验挂了 MCP 但没提示 Agent 去用这一经典坑的考题。每个探针配一个打分函数如 _score_iron_required输出三档结论✓正确、⚠尚可、✗错误并附上一句人话理由比如mines diamond ore with STONE pick — drops nothing。2.3 抓取动作的关键技巧真正的执行逻辑在 _probe_one有几个值得偷师的细节每个探针开一个独立的 CMA 会话消息模板直接告诉 Agent你已经调过 get_state下面是结果只选一个动作从而把多轮博弈压缩成单轮决策跳过读技能和多余 get_state流式事件里遇到read、get_state等前置调用会跳过最多 3 次确保抓到的是 Agent 真正的第一决策而不是它加载技能的仪式动作抓完立刻user.interrupt并归档会话——这就是无副作用的实现挖矿指令根本没机会落地并发执行run() 用ThreadPoolExecutor并发跑全部探针默认 4 线程可用EVAL_WORKERS调墙钟时间约等于最慢一个探针的耗时所以整轮评测只要 30~60 秒。入口在 my_agent.py运行python3 my_agent.py --eval即调用probes.run()。如果没拿满分结尾还会输出一段诊断文案直接点明三类探针分别对应技能/提示词/MCP三个可调杠杆——它测的不是运气而是你的配置。三、replay.py把 JSONL 轨迹翻译成剧本3.1 日志从哪来Agent 运行时的原始记录由 RunLogger 产出--log-dir开启后每个事件一行自包含 JSONrun_start/turn/task_end/task_notes_after/run_end行缓冲写入保证崩溃也不丢已发生的事件同时维护latest.jsonl符号链接方便演示时一条tail -F看全场。3.2 回放的设计原则replay.py 的定位是Pretty-print a run JSONL三条原则贯穿实现零依赖纯标准库、纯文本输出任何终端都能跑刻意不用 rich/textual容错坏行只警告不崩溃打到 stderr缺失字段用.get()兜底旧版本 agent.py 的日志照样能读可过滤--task stone_pickaxe只看单个任务--grep mine_block按动作名 参数 推理 报错做大小写不敏感的子串匹配见 _matches_grep过滤模式下还会聪明地跳过全局 run_end 汇总因为它不代表过滤子集。每轮 turn 的渲染是一行动作 一行推理── task: iron_pickaxe ── [ 3] mine_block(namedeepslate_diamond_ore) ok inv: 1 diamond ore is close, mine it first ✓ 4 turns — reached iron_pickaxe库存增量1 diamond来自 logging_.py 中记录 inventory_delta让复盘者一眼看出这一步到底有没有产出。四、verify.py给前三名的轨迹做防伪4.1 它防的是什么工作坊要发奖品而排行榜分数来自参与者自己上报——bot.js 归参与者所有logger 理论上可被篡改。verify.py 的注释说得很坦诚它不是密码学意义上的验证但能抓住最廉价的造假直接 curl 往排行榜 POST 一个从未发生的成就。4.2 重建逻辑从轨迹反推应该发生的成就verify() 单遍扫描 JSONL从录下的游戏状态而非自报结果重建四个事实items_seen所有 turn 里出现过的物品名集合用来核对六条科技树里程碑木镐→石镐→熔炉→铁锭→铁镐→钻石是否真的依次达成钻石数优先取diamonds_collected计数器峰值它不受合成/丢弃影响旧轨迹缺该字段时回退到背包峰值取两者最大值作为最终口径min_y全程最低 y 坐标用来审计是否真到过钻石深度y16tokens / turns从 run_end 直接取作为平局裁决的对照值。输出分两段前段是与排行榜可逐字段比对的Agent Battle scoring后段是标注为 audit only, does not affect rank 的里程碑审计清单✓/·。设计意图很清楚让主持人在颁前三之前一条命令就能交叉验证自报分数与轨迹证据是否自洽。命令入口在 main()python -m harness.verify logs/latest.jsonlHOST.md 也把它列为主持人手册里的 Top-3 核验步骤。五、三者如何拼成完整闭环 配置 Agentmy_agent.py 的 AGENT dict │ ▼ ① probes ──跑之前── 10 个合成状态30~60s 定位提示词/技能/MCP 的问题 │ ▼ ② 正式 5 分钟对局 RunLogger 落盘 JSONL │ ├──▶ ③ replay ──跑之后── 过滤/搜索轨迹复盘哪一轮走歪了 │ └──▶ ④ verify ──发奖前── 从轨迹重建事实防伪核验前三名这条闭环体现了工作坊三个可迁移的工程观点快反馈优先probes 把改一次提示词的验证成本从 5 分钟 运气降到 30 秒 确定性打分迭代速度决定调优深度日志是一等公民JSONL 每行自包含、行缓冲落盘才能支撑事后任意角度的 replay 和第三方 verify——先设计好证据格式再谈复盘与审计验证分层probes 验证决策、replay 服务理解、verify 服务信任三种诉求用三个轻量工具各管一段而不是造一个大而全的调试器。六、上手速查三条命令在 agent-battle 目录下只读浏览代码不受影响实际运行需先按 README 完成 setup场景命令秒级评测当前配置python3 my_agent.py --eval回放某次运行的完整轨迹python -m harness.replay logs/run_xxx.jsonl只查某任务 / 某类动作追加--task stone_pickaxe或--grep mine_block核验轨迹真伪python -m harness.verify logs/latest.jsonl七、写在最后harness 目录没有一行炫酷代码却把如何评价一个 Agent这件难事拆成了三件小事probes 用最小状态做确定性单测replay 用容错遍历做可读回放verify 用单遍扫描做证据重建。对任何想给自己的 Agent 项目建立评测能力的团队来说这三个约 100~400 行的文件就是一套可以直接借鉴的轻量模板——先让决策可测再让过程可看最后让结果可信。 【免费下载链接】cwc-workshops项目地址: https://gitcode.com/GitHub_Trending/cw/cwc-workshops创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考