Harvey LAB执行框架:六大模块harness目录结构与职责划分完全解析

Harvey LAB执行框架:六大模块harness目录结构与职责划分完全解析【免费下载链接】harvey-labsA benchmark built to evaluate and improve agent capabilities for supporting legal work.项目地址: https://gitcode.com/GitHub_Trending/ha/harvey-labsHarvey LABLegal Agent Benchmark是一个开源法律 Agent 基准项目用于评估 LLM Agent 完成真实法律工作的能力。其核心就是位于项目根目录的harness 执行框架——它负责装载任务、驱动模型循环调用工具、沙箱内产出法律文书并记录完整的运行轨迹。本文将用通俗的方式拆解 harness/ 目录下的六大模块帮你快速理解一次 Agent 评测运行在底层是如何被组织和执行的。一、什么是 Harvey LAB 的执行框架先建立一个整体印象。Harvey LAB 由两大部分组成部分位置职责任务数据集tasks/1671 个真实感法律任务合同、数据室、合规文件等每个任务包含task.json指令 文书材料执行框架harnessharness/读取任务、调用大模型、执行工具、产出交付物并记录指标用一句话概括 harness 的分工任务提供考题harness 提供考场 监考流程。Agent 被限制在一个每任务独立的沙箱工作区里只有 6 个工具可用bash、read、write、edit、glob、grep没有网络访问——这正是 docs/architecture.md 中描述的文件系统优先设计。二、harness 目录结构全景整个执行框架只有 4 个顶层文件 2 个子目录职责高度解耦harness/ ├── run.py # ① 入口装载任务、组装各组件、编排整次运行 ├── agent_loop.py # ② 核心循环模型与工具之间来回传递消息 ├── tools.py # ③ 工具层6 个封闭工作区工具的定义与执行 ├── system_prompt.md # ④ 系统提示词前导工作区布局 工具约定 ├── adapters/ # ⑤ 模型适配器屏蔽不同厂商 API 差异 └── skills/ # ⑥ 技能手册docx / xlsx / pptx 文件操作指南下面逐一拆解每个模块的职责。三、run.py任务的总调度台run.py 是整次运行的入口一条命令即可启动uv run python -m harness.run \ --model anthropic/claude-sonnet-4-6 \ --task corporate-ma/review-data-room-red-flag-review它按顺序完成 8 件事装载任务——根据任务名/子任务名定位 tasks/ 下的task.json与documents/目录并做配置校验生成 run-id——默认格式为{任务}/{模型}-{推理强度}/{时间戳}保证每次运行结果互不覆盖启动沙箱——每个任务运行都独占一个 Podman 容器--networknone文书目录只读、输出目录可写创建模型适配器——根据--model参数前缀自动路由到对应厂商装配工具执行器——把 6 个工具全部接入沙箱拼装系统提示词——前导文本 技能手册启动 Agent 循环并全程记录transcript.jsonl对话轨迹落盘指标——写入config.json、metrics.json轮次、token、耗时、读了多少份文书等。 记住一句话run.py 自己不做思考它只负责把人、模型、工具、环境四样东西组装到位。四、agent_loop.py最简单的思考-行动循环agent_loop.py 是 harness 的心脏但实现刻意保持简单——模型负责思考循环只负责传递消息。循环逻辑就 5 步用系统前导 技能手册 任务指令构建首轮消息调用adapter.chat(messages, tools)请求模型把模型回复追加进对话轨迹模型没再调用工具 →结束否则用ToolExecutor执行工具调用把工具结果转回厂商消息格式回到第 2 步直到模型停下或达到--max-turns默认 200 轮。两个设计细节值得新手注意没有显式的finish 工具模型停止调用工具的那一刻就是任务完成信号非常干净上下文溢出保护若遇到prompt is too long类错误循环会优雅中断并在指标中标记而不是让整个评测崩溃。五、tools.py6 个工具的封闭工作区harness/tools.py 定义了 Agent 的全部能力边界。这是一个无网络、封闭宇宙的工具集工具用途新手理解bash在沙箱内执行 shell 命令跑脚本、装包、文件操作read读取.docx/.xlsx/.pptx/.pdf/文本自动解析直接拿结构化文本write写出交付物只写纯 Markdown如response.mdedit精确替换文件中的字符串增量修改已产出的文件glob按通配符找文件相当于文件浏览器grep按正则搜索文件内容相当于文书全文检索架构上ToolExecutor只是 sandbox/ 沙箱的一层薄封装——所有文件与 shell 操作都经由沙箱接口路由因此即使.docx是被恶意构造的文件解析也发生在容器内部而非宿主机上。工具使用统计读了多少文书、写了多少文件、搜了多少次都会汇入metrics.json为后续对比报告提供数据。六、system_prompt.md写给 Agent 的员工手册harness/system_prompt.md 是一个独立的 Markdown 文件而非写死在代码里作为系统提示词前导注入每次运行。它告诉 Agent 三件事工作区布局$WORKSPACE_DIR工作区、$DOCUMENTS_DIR只读文书、$OUTPUT_DIR交付物三个目录各司其职工具使用约定读文书用read、二进制交付物走技能手册、write只写 Markdown、edit做增量精修红线规则禁止读取task.json评分标准——一旦违反即判任务失败。这种能力说明在前导、任务内容在首条用户消息的拆分让模型把任务当作一份指派工作来处理而不是环境背景噪音。七、adapters/一套接口抹平五大模型厂商不同大模型厂商的 API 格式千差万别adapters/子目录用统一接口把它们全部抹平。harness/adapters/base.py 定义了抽象基类ModelAdapter核心只有 4 个方法chat()、make_tool_result_messages()、make_system_message()、make_user_message()。Agent 循环永远只与这个接口对话完全不感知背后是哪家厂商。目前已内置的适配器适配器支持的模型前缀anthropic.pyclaude*openai.pygpt*、o1*、o3*、o4*google.pygemini*mistral.pymistral*fireworks.pykimi*、glm*、nemotron*等开放模型baseten.pyBaseten 托管模型想在某家厂商上新增一个模型不用改循环、不用改工具——只需确认前缀路由或新增一个适配器文件即可这就是适配器模式带来的扩展性红利。八、skills/让 Agent 会做 Word、Excel、PPT法律交付物大量是二进制格式.docx合同、.xlsx台账、.pptx演示。skills/子目录为这三种格式各准备了一本操作手册skills/ ├── docx/ # SKILL.md 手册 scripts/ 脚本生成、修订标记、批注、校验 ├── xlsx/ # 工作簿构建、公式重算、错误扫描 └── pptx/ # 形状编辑、打包、缩略图、确定性 QA工作机制分两层手册层每个技能目录下的SKILL.md如 harness/skills/docx/SKILL.md会被run.py读取并追加进系统提示词Agent 由此知道如何产出文书脚本层scripts/目录被整体复制进沙箱工作区的skills/name/scripts/Agent 通过bash直接调用。例如 docx 技能提供了 Markdown 转 docxgenerate_from_md.py、模板填充template_fill.py、修订标记红线条redline.py、交付前强制校验validate.py等脚本。 一个典型分工read工具负责读 Worddocx 技能负责写、改、校验 Word——职责清晰、互不越界。九、一次运行的完整职责链把六大模块串起来一次评测的完整链路是run.py 装载任务与文书 → 启动沙箱 创建适配器 装配 ToolExecutor → agent_loop 开始循环 adapter.chat ⇄ ToolExecutor 执行 6 个工具 → 模型停止调用工具 → 运行结束 → 落盘 config.json / transcript.jsonl / metrics.json / output/之后交给评测侧evaluation/run_eval.py由 LLM 裁判按 rubric 逐条打分evaluation/compare.py生成跨模型对比仪表盘。harness 的产出尤其是对话轨迹与工具指标就是评测与报告的数据来源。十、小结为什么这样的目录划分值得学习模块一句话职责run.py总调度装载任务、组装组件、记录指标agent_loop.py核心循环模型与工具的消息摆渡tools.py能力边界6 个沙箱内封闭工具system_prompt.md行为准则工作区布局与红线规则adapters/厂商隔离统一接口适配五大模型商skills/格式技能docx/xlsx/pptx 的手册 脚本harness 的设计哲学可以概括为三点编排与思考分离run.py 不思考agent_loop 不编排、厂商无关换模型只换适配器、能力封闭沙箱 6 工具保证评测结果可复现、可对比。对于想理解Agent 评测框架如何落地的新手来说这 6 个模块就是一个足够小而完整的学习样本。 想动手实践建议从 docs/tutorial.md 的端到端教程开始再用 docs/architecture.md 深入任务模型与评测方法论。【免费下载链接】harvey-labsA benchmark built to evaluate and improve agent capabilities for supporting legal work.项目地址: https://gitcode.com/GitHub_Trending/ha/harvey-labs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考