企业官网建设流程全解析

本文是一份面向 Harbor 任务作者与 Agent 评估工程师的完整实战指南，围绕仓库中轻量级评分工具包harbor-rewardkit展开：它通过"目录即评分组、文件即判分项"的约定，把工作区（workspace）上的 Agent 产出自动转成结构化 JSON 分数，支持程序化判分（Python 判据）、LLM 判官、Agent 判官（claude-code / codex / fx）与 JEV 判官四种模式。读完本文，你将掌握 tests 目录布局约定、reward.toml聚合配置、CLI 全参数、判定并发与隔离机制，以及如何把 rewardkit 接入 Harbor 任务（可运行示例）。

一、Rewardkit 是什么：设计定位与整体管线

rewardkit是 Harbor 生态中的轻量级评分工具包（"lightweight grading toolkit"），既可嵌入 Harbor 任务的 verifier 阶段独立使用，也可 standalone 运行。核心依赖只有一个litellm，其余能力按需安装：documents（markitdown，用于解析 PDF/Word/Excel 等文档）、image（Pillow，用于图片类判据）、jev（TypeSafe SDK，用于 JEV 判官）、all（全部 extras）。这些 extras 在 pyproject.toml 中声明，需要 Python ≥ 3.12。

其核心思想是"discover → build Rewards → run → output JSON"四步管线：

1. discover：递归扫描一个 tests 目录，把其中的 Python 判据文件与 judge TOML 组装成多个Reward对象；
2. run：并发执行这些 Reward（程序化判据直接调用函数，判官类调用 LLM/Agent CLI/JEV）；
3. output：把每个 Reward 的最终分数写入 JSON。

整体入口与公共 API 统一由init.py 导出：run、run_multi、discover、criterion、Reward、Criterion、Score，以及四种输出格式Binary/Likert/Numeric/Rubric，三种判官LLMJudge/AgentJudge/JevJudge，比较工具compare/format_comparison与轨迹格式化format_trajectory。内置判据还可以通过__getattr__直接以rk.file_exists(...)的方式访问。

二、安装与命令行用法

2.1 安装

作为独立包使用（推荐通过 uv）：

# 在仓库内开发（位于 packages/rewardkit 目录） uv sync # 安装到环境（含全部 extras） uv tool install harbor-rewardkit # 按需安装 extras：harbor-rewardkit[jev] / [documents] / [image] / [all]

CLI 入口为rewardkit命令，由main.py 的main()实现（pyproject 中[project.scripts]注册了rewardkit = "rewardkit.__main__:main"）。

2.2 CLI 全参数

rewardkit <tests_dirs...> [--workspace /app] [--output /logs/verifier/reward.json]

• 传入一个tests 目录时调用run()，逐个打印name: score；
• 传入多个tests 目录时调用run_multi()，各自独立运行，并按dir/reward命名空间输出，最后打印比较表格（见第五节）。

其余常用参数（均带短别名）：

run()/run_multi()的 Python 签名与 CLI 一一对应（见 runner.py），默认并发为max_concurrent_programmatic=8、max_concurrent_llm=8、max_concurrent_agent=2。

三、Programmatic 判分：目录布局、判据注册与聚合

3.1 最简用法

tests/checks.py中调用内置判据工厂：

# tests/checks.py from rewardkit import criteria criteria.file_exists("output.txt") criteria.file_contains("output.txt", "hello")

运行：

uvx --from harbor-rewardkit rewardkit /tests

Rewardkit 会把所有判据跑在工作区（默认/app）上，并把结果写入/logs/verifier/reward.json；若判据文件直接放在 tests 根目录，所有分数自动合并进一个reward输出。

3.2 两种布局：Nested 与 Flat

runner.py 中的_discover_group/_discover_layout实现了递归发现逻辑，支持两种目录布局：

• Nested（嵌套）：每个子目录是一个评分维度（scoring group）。根目录的 Python 文件、根 judge 与各评分子目录都是公开维度。例如：

tests/ ├── correctness/ │ └── checks.py ├── structure/ │ └── files.py └── quality/ └── judge.toml

会输出correctness、structure、quality三个独立维度。

• Flat（扁平）：判据直接放在 tests 根目录时，被隐式聚合进reward输出。

两种布局可以在根tests/reward.toml中通过命名聚合统一输出：

[[reward]] name = "reward" aggregation = "weighted-mean" weights = { correctness = 2.0, structure = 1.0, quality = 1.0 }

3.3 每个目录可放什么

一个目录内可以同时共存以下三种输入：

1. Python 文件（.py）：在 import 时执行，每个注册了判据的文件成为一个等权重评分项，以其文件名 stem 命名；
2. Judge.toml文件：声明[judge]+[[criterion]]，用于 LLM/Agent/JEV 评估（见第四节）；
3. reward.toml：可选，配置该目录内的评分聚合方式。

_load_directory_tomls（runner.py）一次性读取目录内所有*.toml，按内容区分 judge TOML（含judge或criterion键）与reward.toml（按文件名）；两套配置都通过 Pydantic 模型严格校验（extra="forbid"），未知键或非法值会在 discover 阶段直接抛错，而不是静默忽略。

一个值得注意的规则：[scoring.<stem>]必须指向确实注册了判据的 Python 文件，否则抛unknown programmatic scoring inputs错误（runner.py）；仅提供导入或shared=True判据定义而未注册任何检查的文件会被忽略。

3.4@criterion装饰器与判据注册机制

判据的注册基于ContextVar的Session（session.py）：

from rewardkit import criterion @criterion(description="file exists: {path}") def file_exists(workspace: Path, path: str) -> bool: return (workspace / path).exists()

• 装饰器要求第一个参数恒为workspace: Path，其余参数成为工厂参数，调用时传入（如file_exists("hello.txt", weight=2.0)）；
• 工厂额外接受weight、name、isolated关键字；
• @criterion(shared=True)的工厂不会自动注册，而是供其他文件递归导入使用；零参数判据（只有workspace）在 import 时自动注册；
• 定义了但从未在 discover 上下文中调用的参数化判据会给出 warning（runner.py）。

内置判据模块位于 criteria/ 目录，共有 23 个，覆盖常见验证场景：文件类（file_exists、file_contains、file_contains_regex、file_matches、file_not_exists、files_equal）、命令类（command_succeeds、command_output_contains、command_output_matches(_regex)）、数据类（json_key_equals、json_path_equals、csv_cell_equals、xlsx_cell_equals、sqlite_query_equals）、图片类（image_size_equals、image_similarity）、HTTP 类（http_status_equals、http_response_contains）以及轨迹类（trajectory_tool_used、trajectory_tool_not_used、trajectory_turn_count）与diff_ratio。

criteria/init.py 通过__getattr__从全局_factory_registry解析判据，这意味着用户自定义判据可以同名覆盖内置判据（覆盖时会收到 warning）。新增内置判据的步骤为：在criteria/下新建模块并加@criterion(description=...)装饰，然后把模块名加入_BUILTIN_MODULES列表。

判据返回值支持三种形式，统一经CriterionResult校验（reward.py）：

return True / False # bool return 0.75 # 数字（0~1） return {"score": 0.75, "reasoning": "...", "confidence": 0.9, "model": "..."} # 字典

3.5 分数聚合模式（Aggregation）

聚合模式在Reward.score属性上生效（reward.py 的aggregate_scores），取值如下：

required-pass的特殊语义：Criterion.optional=True的判据永远不会门控；若所有判据都标了 optional，则发出 warning 并打 0.0 分。程序化判据永远不会 optional，因此对程序化 Reward，required-pass退化为all-pass。

配置某个文件内判据的聚合方式：

# tests/reward.toml [scoring.checks] aggregation = "all-pass"

weighted-mean的实现值得注意（reward.py）：当权重总和为 0 时返回 0.0，避免除零。

四、Judge 判官：LLM、Agent 与 JEV 三种评估模式

4.1 判官 TOML 结构

一个 judge TOML 由[judge]表、一个或多个[[criterion]]表以及可选的[scoring]表组成：

# tests/quality.toml [judge] judge = "anthropic/claude-opus-5-5" files = ["/app/main.py"] [[criterion]] description = "Is the code correct?" type = "binary"

[judge].judge有三种取值方向：LiteLLM 模型名（如"anthropic/claude-opus-5-5"）、Agent CLI 名（"claude-code"、"codex"、"fx"）或"jev"。当judge =是 Agent 时，可选的model =指定该 Agent 实际使用的 LLM；Agent 判官还支持[judge]下的isolated = true。

[[criterion]]的字段（完整定义见 models.py）：

四种输出格式Binary/Likert/Numeric/Rubric都实现OutputFormat协议（normalize()、prompt_fragment()、json_schema()），其中json_schema()返回用于结构化输出强制的 JSON Schema 片段（models.py）。归一化规则：binary 的字符串"yes"/"true"/"1"得 1.0；likert 映射(value-1)/(points-1)；numeric 映射(value-min)/(max-min)；rubric 为value/(len(levels)-1)。

[judge]表的完整字段（models.py）：judge、model、version（Agent CLI 语义化版本）、files、mode（batched/individual）、timeout（默认 300 秒）、reasoning_effort、isolated、cwd、reference、atif_trajectory（TOML 中写作atif-trajectory）、mcp_servers、weight、prompt_template、samples（默认 1，≥1）、guard（off/flag/penalize）。

注意：prompt_template指向.txt/.md文件，必须包含{criteria}占位符，否则 discover 抛错（runner.py）。

4.2 三种判官的执行路径

• LLMJudge（judges.py）：基于判据构造 system prompt，把files指定的工作区文件读成多模态 content blocks（文本 + base64 图片 + markitdown 文档），用litellm.acompletion调用，并通过response_format: json_schema强制结构化输出。支持files、reference（参考解答放在<submission>标签之外）、atif_trajectory字段。解析失败最多重试 3 次（_MAX_JUDGE_RETRIES = 3），最终无法解析时抛ValueError；超时则受影响判据记 0.0。

• AgentJudge：judges.py负责与提供方无关的提示、重试、解析与元数据聚合；异步AgentBackend实现（agents.py）负责 CLI 生命周期，每次执行返回一个AgentAttempt。当前注册了三个 backend（register_agent注册在 agents.py）：

  • claude-code：支持reasoning_efforts = {low, medium, high, xhigh, max}；
  • codex：支持{none, minimal, low, medium, high, xhigh, max}；
  • fx：支持{auto, none, minimal, low, medium, high, xhigh, max}。

  每个 backend 声明其 CLI 接受的reasoning_efforts集合，AgentJudge校验reasoning_effort是否在集合内——backend 没有该属性时任何 level 都会被拒绝。RewardKit 在首次使用时会把固定版本的 Codex CLI 下载到缓存目录（~/.cache/harbor-rewardkit/codex/<version>）。Codex 认证接受OPENAI_API_KEY或CODEX_AUTH_JSON（ChatGPT 订阅会话）；API key 优先，除非设置REWARDKIT_FORCE_SUBSCRIPTION=1。

• JevJudge（judges.py）：judge = "jev"时使用 TypeSafe 的 JEV 模型，通过typesafe_sdk.AsyncTypeSafeClient（惰性导入，需要jevextra）。JEV 不是聊天模型：arun_jev把files与reference的文本作为 state，每个判据发一个类型化问题（按判据名 key）。Binary映射为 Noul 问题，概率 ≥ 0.5 得 1.0；Rubric映射为 Score 问题并归一化零基分数。概率/原生分数保留在Score.raw，reasoning 为空。SDK 读取TYPESAFE_API_KEY、TYPESAFE_BASE_URL、TYPESAFE_DEFAULT_MODEL，因此 LiteLLM 的 TypeSafe passthrough 与 Vercel 的 TypeSafe 兼容端点无需额外 provider 代码。图片、atif-trajectory、prompt_template、Likert/Numeric判据对 JEV 一律拒绝；_validate()在构造期就抛错。

4.3 Batched 与 Individual 模式

• batched（默认）：所有判据放进一次 judge 调用，返回一个 JSON 对象；
• individual：每个判据单独一次调用。对 LLM 是并发扇出（_arun_llm_individual），对 Agent 则是串行的——因为 Agent 调用是重量级 CLI 子进程，并行 N 个会耗尽小型 verifier 容器的资源（代码注释明确说明了这一点）。

判据级files仅允许在individual模式下使用（reward.py）。

4.4 多采样与中位数投票

[judge].samples > 1时，同一判官调用samples次。每个样本独立获取类型信号量（因此排队行为与独立判官完全一致），然后_median_scores（reward.py）给每个判据取下中位数样本——保证value、raw、reasoning永远来自同一个真实样本，binary 判据在 pass 聚合中保持 0/1 语义；出错样本不参与投票但以null出现在samples中。Score.samples与Score.agreement（一致性 = 1 - 平均绝对偏差）仅在多采样时写入。guard 采用上中位数，因此分歧投票会被标记。

4.5 Guard：防"讨好裁判"检测

judge.guard（off/flag/penalize）由judges.py端到端负责：arun_llm/arun_agent通过_with_guard()追加一个名为guard的隐藏判据（prompt 模板见 guard_llm.md，其描述为"agent 是否写了直接面向评估者、或关于自己如何被评分的内容"），该判据照常被 prompt、解析、重试与超时处理，再由_extract_guard()把它的分数移入JudgeResult.guard。guard权重为 0——因为权重为 0 仍会影响any-pass/all-pass，所以必须与scores分离存放。Reward.guard_score是各样本的中位数；guard = "penalize"时，被标记（flagged）的 Reward 分数封顶为 0.0，出错（error）的 guard 永不惩罚，weighted-sum本身可为负。_validate()会拒绝用户自定义名为guard的判据；JevJudge不支持 guard，runner 对 JEV 拒绝任何非"off"的 guard。

4.6 MCP 服务器支持

MCPServerConfig镜像 Harbor 任务的 MCP 配置（models.py），支持stdio/sse/streamable-http三种 transport（http会自动归一化为streamable-http）。Codex 支持 stdio 与 streamable-http（含allowed_tools），但不支持sse；fx 不支持allowed_tools且服务器名只能含字母数字下划线连字符；claude-code 通过claude mcp add注册（stdio 用-- command args，HTTP 用--transport）。

4.7 成本与用量统计

LLM 与 Agent 判官的usage尽量包含cost_usd：LLM 用 LiteLLM 的response_cost，否则按模型单价估算（标记cost_source = "litellm_estimate"）；Claude Code 报告其total_cost_usd；fx 用fx usage --json的完整 spend（每次尝试使用全新临时 profile，避免重试重复计费）；Codex 从其原生 session log 按last_token_usage逐次计价。Agent 聚合 token 永远不按单次请求计价；存在任何带 token 却无法定价的调用时，cost_usd会被省略。失败的 Codex 尝试还会把 stdout/stderr 保存为文本日志。

五、多目录对比：run_multi 与比较表

run_multi()（runner.py）独立运行多个 tests 目录，输出带命名空间的结果（"dir/reward"），并要求目录 basename 不得重复。compare()/format_comparison()（compare.py）对跨目录重叠的 reward 名生成 diff 表：

Comparison: ---------------------------------------- reward dirA dirB diff ---------------------------------------- quality 0.75 0.9000 -0.1500 ----------------------------------------

这在对比"同一评分标准在不同模型/Agent 上的表现"时非常有用：把每个模型的输出目录作为独立 tests 目录传入即可。

六、隔离、并发与共享工作区安全

6.1 工作区隔离（overlayfs）

isolation.py 实现基于 overlayfs（Linux）的工作区隔离：判据或 Agent 判官设置isolated=True时，工作区作为只读 lower layer 挂载，写入落到临时 upper 目录；内核 overlay 不可用时回退到 fuse-overlayfs（必要时自动尝试apt-get install fuse-overlayfs）。程序化判据通过criterion(..., isolated=True)启用；Agent 判官通过[judge].isolated = true启用。隔离后的 Agent 判官cwd必须在工作区内（reward.py 校验）。

6.2 共享工作区守卫

运行开始前，runner._check_shared_workspace()（runner.py）会计算_agent_runs：若整个 run 的 Agent 执行次数（individual 模式为samples × (判据数 + guard)，batched 为samples）超过 1 次，且存在未隔离的 Agent 判官，则抛错——因为该 Agent 可能写入其他 Agent 正在使用的工作区。LLM 判官不能写文件，因此不计入；--yolo（yolo=True）跳过此检查。

6.3 并发模型

_run_all（runner.py）按类型创建信号量，用asyncio.TaskGroup并发调度所有 Reward：程序化判据经asyncio.to_thread跑在线程池，LLM/Agent 判官跑异步任务。这是多个 Reward 之间的并行；同一个 judge 的多个samples也各自获取信号量，因此与独立判官完全同等地排队。

七、轨迹（Trajectory）支持：ATIF 格式化与 Token 预算

trajectory.py 把 ATIF（Agent Trajectory Interchange Format）JSON 格式化为紧凑文本用于 judge prompt。核心设计：

• Token 预算感知：按模型上下文限制，对每个内容块按比例截断；所有步骤永远保留，只有步骤内的内容会被截断；
• 多模态路径：_format_trajectory_content返回 content blocks，图片/音频以image_url/input_audio到达模型；媒体是 all-or-nothing，其 token 成本先预留，文本只吸收剩余截断；
• 图片成本来自litellm.token_counter；音频按duration_sec × 32（_AUDIO_TOKENS_PER_SEC）估算；
• 媒体安全：URL 引用的媒体被拒绝；单个文件与聚合 raw 媒体上限均为 20 MB；轨迹路径做了路径穿越防护（..或绝对路径不允许逃出轨迹目录）；
• 每个解析过的轨迹文件有 per-run 缓存，individual 模式的媒体请求被串行化以避免峰值内存翻倍；
• 公共format_trajectory保持纯文本输出，媒体渲染为[image]/[audio]标记；缺失或无法解析的轨迹抛错，无步骤的合法轨迹格式化为[trajectory empty]。

八、输出格式与积分对接 Harbor

run()默认写出扁平分数（每个 Reward 一个键）：

{"correctness": 0.75, "structure": 1.0, "quality": 0.6}

同时在旁边写出reward-details.json，包含每个判据的明细：kind（programmatic/llm/agent/jev）、judge 配置、原始 judge 输出、usage、guard 结果与任何 warnings（reward.py 的to_detail_dict）。

仓库自带一个完整可运行的 Harbor 任务示例 examples/tasks/reward-kit-example/：

• task.toml 声明任务元数据与 verifier 配置；
• tests/criteria.py 定义@criterion(shared=True)的自定义共享判据（动态加载工作区模块并跑用例打分）；
• tests/reward.toml 用all-pass把correctness与structure两个维度聚合为reward；
• tests/correctness/reward.toml 展示嵌套目录内用未命名[[reward]]设置权重{ most_common = 2.0, word_count = 3.0, pipeline = 1.0 }（Python 文件用 stem、子组用目录名引用）；
• tests/correctness/word_count.py 演示criteria.word_count_correct(weight=3.0)覆盖共享判据权重；
• tests/test.sh 是 Harbor 环境下实际的 verifier 入口：uvx --from 'harbor-rewardkit==0.2.*' rewardkit /tests。

九、开发与测试约定

在packages/rewardkit下开发时：

uv sync # 安装依赖 uv run pytest tests/ # 全部测试 uv run pytest tests/unit/test_runner.py::TestRunner::test_run_programmatic_e2e # 单个测试 uv run ruff check --fix . # lint（改动后必须执行） uv run ruff format . # format（改动后必须执行）

测试全部位于tests/unit/（无集成测试），conftest.py在每个测试前重置 session、判据注册表与 judge 环境；共享 fixtures 提供write_tree、llm_response、agent_backend；需要复制工作区的测试显式请求fake_overlayfs。从仓库根运行完整测试与覆盖率：

uv run pytest packages/rewardkit/tests/unit/ --durations=15 --cov=packages/rewardkit/src/rewardkit --cov-branch --cov-report=term-missing

代码约定要点：用户可见配置值用 kebab-case（解析遗留输入时才保留 snake_case）；判据行为告警用warnings.warn而非logger.warning（保证用户即使未配置日志也能看到）；Agent backend 每个 judge 独立新建，实例内可持有该 judge 串行样本共享的状态（如 Codex SDK client），但禁止使用可变单例 backend 状态——因为 Reward 是并发运行的。

十、快速上手清单

1. 在工作区外准备tests/目录：放checks.py（程序化判据）或judge.toml（判官判据），需要多维度就用子目录；
2. 需要调聚合时加reward.toml（[scoring.<stem>]管文件内，[[reward]]管边界与命名输出）；
3. 运行uvx --from harbor-rewardkit rewardkit /tests，检查/logs/verifier/reward.json与reward-details.json；
4. 多个模型/Agent 对比时传多个 tests 目录，读取控制台比较表；
5. 多个 Agent 判官共用工作区时务必isolated = true，否则运行前会被守卫拦截，必要时显式传--yolo；
6. 需要 LLM 读文件/图片时配files，需要参考解答时配reference，需要看 Agent 行为轨迹时配atif_trajectory，需要防讨好裁判时配guard。

十一、结语

Rewardkit 的价值在于把"评分"从一次性脚本变成可复用、可审计、可对比的声明式配置：目录布局即评分结构，reward.toml即评分策略，judge TOML 即评估标准，JSON 输出即评估结果。配合多采样中位数投票、guard 检测、overlayfs 隔离与 ATIF 轨迹注入，它既能支撑 Harbor 任务的自动化 verifier，也能作为独立工具对任意 Agent 工作区进行多维度、多模型的可复现评估。本文所有结论均可对照仓库源码验证：目录发现与校验逻辑在 runner.py、数据模型在 models.py、判官实现与 prompt 模板在 judges.py 与 prompts/、Agent backend 在 agents.py、轨迹格式化在 trajectory.py，完整可运行的对接示例见 examples/tasks/reward-kit-example/。