在 OSWorld 2.1 上用上游 CUA harness 跑 agent 测评,通过内部集群的 rjob 提交任务。
本分支是测评工程分支,与 main(JevDuo harness 本体)相互独立,不 merge、不 rebase。
被测 agent 来自 src/upstream/(以 git subtree 方式入库的上游精简树,见
上游源码),评测链路为:
切题 → 渲染 job spec → 并发提交 rjob → 起 VM → 跑 agent → 官方评分 → 落盘汇总。
当前 config.yaml 开启 Slow 编排,由 Slow 选择 gui_jev 或 general 子代理并核验结果。
编排与插件配置详见 ORCHESTRATION.md。
gui_jev 使用的原生桌面工具源码随仓库保存在 jev_tools/agent-desktop/,
构建和部署方法见使用仓库内的 agent-desktop。
- 开发机需要已配置权限的
rjob、uv >= 0.13.6,以及集群可访问的共享盘。 可用JEVDUO_UV=/path/to/uv指定 setup 使用的 uv。 - 检查
config.yaml的cluster和benchmark:镜像、挂载、prepared runtime、 VM qcow2、assets、共享env.sh必须在实际 worker 中可用;GitLab token 文件由 driver 读取并将值写入私有 spec,因此须在 driver 中可读。 - 当前开启
gui_jev,所需 Python 包已收录在jev_tools/jev-desktop/,setup_env.sh默认以 editable 方式安装;所有 worker 需要能读取同一仓库路径。 它与jev_tools/agent-desktop/中的 Rust CLI 是两个独立组件。 VM 镜像内还需安装下文构建的 CLI 和 Linux helper,并将配置指向客体中的 CLI 路径。
从仓库根目录安装。setup_env.sh 会重建 venv/,搬动源码后也需要重建:
bash scripts/setup_env.sh
venv/bin/python -c 'import northcua, nexau, yaml; from jev_desktop import AgentDesktop, JevLoop'已有 venv 时,也可单独安装插件:
uv pip install --python venv/bin/python --no-deps -e jev_tools/jev-desktop需要替换 Python 包来源时,可设置 JEVDUO_JEV_PACKAGE=/absolute/shared/path/to/jev-desktop
再运行 setup_env.sh;相对路径按仓库根目录解析。脚本会在重建 venv 前检查包的安装元数据
和入口源码,并在安装后验证 AgentDesktop、JevLoop 等导出,避免残留 editable 记录掩盖源码缺失。
jev_tools/agent-desktop/ 通过 git subtree 引入自
k4ngzy/agent-desktop 的 ubuntu2204 分支,
导入基线为 b7f968003746d90432de8d92b00692d068407419。普通 clone 即包含源码,
无需初始化 submodule。复现实验时使用本仓库固定的版本;其中的 Cargo.lock、
rust-toolchain.toml 和 LICENSE 一并保留。
配套的 Python 运行库独立放在 jev_tools/jev-desktop/,同样以 subtree 收录。
其中 17 个 Python 模块恢复自本批测评的源码快照,保留原有实现;包元数据、许可证和安装说明
随包提供。它负责 Jev 决策循环和 CLI 传输,使用说明见 Python 包 README。
下面以 OSWorld 的 Ubuntu 22.04、x86_64 客体为例。在仓库根目录执行, 通过 Docker 在 Ubuntu 22.04 中构建,避免开发机较新的 glibc 成为客体运行依赖。 构建机需要 Docker 及拉取镜像、Rust 工具链和 Cargo 依赖的网络权限:
docker run --rm --platform linux/amd64 \
-v "$PWD/jev_tools/agent-desktop:/src" -w /src ubuntu:22.04 \
bash -euo pipefail -c '
export DEBIAN_FRONTEND=noninteractive
apt-get update
apt-get install -y --no-install-recommends \
ca-certificates curl build-essential binutils git xz-utils
curl --proto "=https" --tlsv1.2 -sSf https://sh.rustup.rs | \
sh -s -- -y --profile minimal --default-toolchain 1.89.0
. /root/.cargo/env
cargo build --locked --release -p agent-desktop
cargo build --locked --release -p agent-desktop-linux --bins
for executable in agent-desktop agent-desktop-linux-clipboard-owner; do
bash scripts/check-elf-glibc-floor.sh "target/release/$executable" 2.35
done
target/release/agent-desktop version
'两份产物位于宿主机的 jev_tools/agent-desktop/target/release/:
agent-desktop 和 agent-desktop-linux-clipboard-owner。Linux CLI 从自身所在目录查找
helper,部署时将同一次构建的两份文件放在一起。glibc 检查读取 ELF 符号版本,
用于确认构建产物要求的 glibc 版本不高于 2.35;这不等同于 GUI 功能已通过验证。
CLI 运行在 VM 客体中;只在开发机或 rjob 外层容器安装不能替代客体部署。 先启动准备环境用的 VM,从实际 provider/连接信息取得其 HTTP 服务地址和端口。 下面的上传命令在能够访问该服务的构建机或 worker 上、从本仓库根目录执行:
# 替换为实际 VM 服务地址;不是集群的 SSH 登录地址
JEVDUO_VM_SERVER='http://VM_IP:SERVER_PORT'
for executable in agent-desktop agent-desktop-linux-clipboard-owner; do
curl --fail --show-error --noproxy '*' \
-F "file_path=/tmp/$executable" \
-F "file_data=@jev_tools/agent-desktop/target/release/$executable" \
"$JEVDUO_VM_SERVER/setup/upload"
done随后在 VM 内的终端安装两份文件及运行依赖:
sudo apt-get update
sudo apt-get install -y --no-install-recommends at-spi2-core dbus-x11 python3-gi
sudo install -d -m 0755 /opt/jev/agent-desktop/bin
sudo install -m 0755 \
/tmp/agent-desktop /tmp/agent-desktop-linux-clipboard-owner \
/opt/jev/agent-desktop/bin/在 VM 桌面用户的现有图形会话终端中检查 CLI 和可访问的应用:
JEVDUO_DESKTOP_BIN=/opt/jev/agent-desktop/bin/agent-desktop
"$JEVDUO_DESKTOP_BIN" version
"$JEVDUO_DESKTOP_BIN" status
"$JEVDUO_DESKTOP_BIN" list-apps
"$JEVDUO_DESKTOP_BIN" list-windows
# 将窗口 ID 换成 list-windows 实际返回的值
"$JEVDUO_DESKTOP_BIN" snapshot --window-id '<window-id>' --max-depth 3 -i观察与动作需要同一桌面会话的 DISPLAY、session D-Bus 和运行目录;通过 SSH 或 HTTP
执行时也要继承该会话环境,不能凭空指定另一个 D-Bus 会话。OSWorld 的 headed 操作使用
X11;Chromium 启动参数需包含 --force-renderer-accessibility,当前 gui_jev.launch_args
已经为 Chrome 配置该参数。应用本身仍须暴露 AT-SPI 接口。
将以下字段合入现有 config.yaml,其余模型、编排预算和基准配置保留:
harness:
orchestration:
gui_jev:
enabled: true
desktop:
binary: /opt/jev/agent-desktop/bin/agent-desktop
headed: true
benchmark:
vm: /absolute/shared/path/to/unified-with-agent-desktop.qcow2desktop.binary 是 VM 内路径,不是共享盘上的 target/release/agent-desktop。
测评会 reset VM,因此应将安装完成的环境保存为独立的 prepared qcow2,并把 benchmark.vm
指向它;只向某次运行中的 VM 上传文件不会更新基础镜像。scripts/setup_env.sh 只准备
agent 的 Python 环境,并默认安装 jev_tools/jev-desktop/;不会构建 Rust 工具或自动将文件安装进 VM。
在工作区干净时,从仓库根目录执行:
git subtree pull --prefix=jev_tools/agent-desktop \
https://github.com/k4ngzy/agent-desktop.git ubuntu2204 --squash更新后重新构建 CLI/helper、准备对应 VM 镜像,并记录本次使用的仓库版本。 更多命令与平台限制见工具自身的安装文档和 Linux 平台说明。
首次创建 .env.local 模板;已有文件会保留。随后编辑模板中的占位值:
if [ ! -f .env.local ]; then
(umask 077; cat > .env.local <<'EOF'
export JEVDUO_KIMI_API_KEY='...'
export JEVDUO_REGISTRY_AUTH='...'
export TYPESAFE_API_KEY='...'
# 按 Jev 服务配置,必要时设置:
# export TYPESAFE_MODEL='jev-latest'
# export TYPESAFE_BASE_URL='...'
# 选择 MiniMax actor 时还需:
# export JEVDUO_MINIMAX_API_KEY='...'
EOF
)
fi
chmod 600 .env.localJEVDUO_REGISTRY_AUTH 支持裸 user:pass 或其 base64 编码。
JEVDUO_KIMI_API_KEY 用于当前默认 actor,也用于 evaluation_model 配置的官方评分模型;
使用 --model MiniMax-M3.1-Flash 只切换 actor,不会同时切换评分模型。
TYPESAFE_API_KEY 用于 Jev 决策服务。run.sh 自动加载 .env.local,driver 将明确支持的
TYPESAFE_API_KEY、TYPESAFE_MODEL、TYPESAFE_BASE_URL 写入私有 spec,再注入 agent 进程。
以下命令会实际提交集群任务;每次新评测使用新的 run ID。
# 单题冒烟;前台等待任务结束
bash scripts/run.sh --run-id jv-smoke-001 --tasks 001 --jobs 1 --per-job 1
# 全量 108 题:最多 6 个 rjob,各串行 18 题;脱离终端运行
bash scripts/run.sh --run-id jv-osw21-all --jobs 6 --per-job 18 --detach
# 只跑第 1/6 分片(18 题),最多 2 个 rjob
bash scripts/run.sh --run-id jv-osw21-shard1 --shard 1/6 --jobs 2 --per-job 9前台输出写入 runs/<run_id>/submit.log;--detach 模式写入 pool.log,PID 位于 pool.pid。
平台任务名及收尾结果位于 jobs/job-NN/job.json。当前 cluster.keep_job: true,结束后保留
平台任务,由使用者按实际任务名清理;--keep 也可要求保留任务。
同一 run ID 默认跳过已有 episode.json 的题,包括 failed_unscored;
显式加 --retry-failed 才重跑其中未评分的题,合法零分不会因此重跑。
--no-resume 关闭这项跳过逻辑。配置切换使用 --config,actor 切换使用 --model。
提交失败不会自动重新提交;结果不明时保留记录供人工核对,不按推导名操作平台任务。
同一 run ID 可按保存的实际平台任务名接管等待;短暂状态查询失败继续等待,监控中不自动重启任务。
显式重跑已结束的题会分配新的 job 目录,保留旧轨迹与日志。
以下为当前 config.yaml 的默认值,命令行覆盖仅作用于本次运行:
| 配置 | 默认值与含义 |
|---|---|
harness.max_steps / orchestration.max_cycles |
20 个编排轮次,不是 20 次 GUI 动作 |
orchestration.subagent_steps_per_cycle |
每个子任务最多 50 次模型调用、50 次工具调用 |
orchestration.max_model_calls / max_tool_calls |
整题分别 1300 / 1000;调用失败也消耗额度 |
harness.max_wall_seconds |
10800 秒,覆盖 VM setup、actor 和官方评分 |
harness.evaluation_reserve_seconds |
在上述总时间内为评分预留 600 秒 |
harness.inactivity_timeout_seconds |
720 秒无活动触发 actor 错误 |
orchestration.model_timeout_retries |
每次模型推理超时最多重试 2 次,仍受总预算约束 |
pool.max_parallel / tasks_per_job |
1 / 1;仅在 rjob 级并发,job 内逐题串行 |
cluster.cpu / memory |
每 job 4 CPU / 16384 MB |
Desktop 唯一执行模式为 Slow 编排,orchestration.enabled 总开关已删除。
harness.orchestration 必须提供 max_cycles、max_seconds、max_model_calls、max_tool_calls;
gui_jev.enabled、general.enabled 只控制插件注册。多阶段任务共用整题预算,并要求完整 usage。
轮次上限应同时检查 harness.max_steps 和 harness.orchestration.max_cycles;
--max-steps 只覆盖前者。--max-wall 覆盖单题墙钟上限,子任务仍受自身及编排时间预算限制。
models.apis 登记模型与凭据环境变量;direct_api: true 会剔除 actor 子进程的代理环境变量。
harness.evaluation.enabled: false 关闭的是上游内部评估器,OSWorld 官方评分仍运行。
evaluation_model 单独配置官方评分使用的模型;其故障会使当前题成为 failed_unscored,
不会伪装成得分 0,也不会污染同一 job 的后续题。
scored 包括合法零分和部分分;actor 返回 DONE、job 成功退出都不能代替官方分数。
步数或 actor 时间耗尽后仍可进入官方评分;setup、agent 异常或整题硬截止导致的失败记为未评分。
| 路径 | 内容 |
|---|---|
config.yaml |
唯一配置:模型、harness 行为、并发、集群、基准、日志;不含密钥 |
scripts/run.sh |
常规评测入口(开发机) |
scripts/setup_env.sh |
重建 agent venv(解释器装共享盘 + 路径断言) |
infra/worker.sh |
rjob worker 入口:共享 env、dockerd、拉镜像、进 entry |
src/settings.py |
读 config.yaml、切题、渲染 job spec(开发机侧,需要 PyYAML) |
src/pool.py |
普通任务池:切片、并发 rjob、接管等待、收日志与汇总 |
src/rjob.py |
rjob CLI 封装与状态解析 |
src/entry.py |
worker 主循环(冻结解释器,只读 JSON spec) |
src/vm.py |
OSWorld VM 生命周期:fetch_task / reset / execute / score / close |
src/launch.py |
起 agent 子进程、超时杀进程组、终态映射 |
src/actor_run.py |
单阶段与多阶段共用的配置生成、actor 调用和终态交付 |
src/phase_run.py |
原生阶段 setup、共享预算、逐阶段评分与 gate |
src/appcfg.py |
生成 app.yaml / agent.yaml(指向 VM 的 osworld 后端) |
src/task_run.py |
单题 agent 运行器(在 agent venv 内跑) |
src/recorder.py |
结果目录契约(轨迹摘要、截图、汇总) |
src/scoring.py |
官方分数归一化与 failed_unscored 判定 |
src/evaluation_runtime.py |
官方评分模型配置与按题隔离的模型故障检查 |
src/evaluator_dependencies.py / src/setup_transport.py |
评分依赖预检与一次投递的慢 setup 传输 |
src/worker_limits.py |
覆盖 setup、actor 和评分的整题硬截止 |
docs/ORCHESTRATION.md |
Slow、Jev、general 插件协议及行为说明 |
jev_tools/agent-desktop/ |
ubuntu2204 分支的 Rust CLI/helper 源码,以 git subtree 管理;在 VM 内运行 |
jev_tools/jev-desktop/ |
Jev Python 决策循环和 CLI 传输包,以 git subtree 管理;安装在 agent venv 中 |
tests/ |
本地逻辑与模拟传输回归,不启动真实 VM 或模型调用 |
runs/<run_id>/ |
全部产物(gitignore) |
| 角色 | 解释器 | 说明 |
|---|---|---|
开发机 pool / settings |
仓库 venv/bin/python |
有 PyYAML,读 config.yaml |
worker entry |
共享 $OSWORLD_PYTHON |
冻结 venv,没有 PyYAML,只读 JSON spec |
agent 子进程 task_run |
仓库 venv/bin/python |
上游源码 + NexAU |
因此 config.yaml 只在开发机解析;worker 只接收 settings.py 渲染好的 job_specs/*.json。
补跑统一使用 scripts/run.sh。修改代码、模型或配置后,使用新的 run ID,并显式选择任务:
bash scripts/run.sh --run-id jv-rerun-001 --tasks 005,018 --jobs 1 --per-job 1预算来自 config.yaml,支持普通入口的 --config、--model、--max-steps 和 --max-wall。
同一 run ID 下重跑未评分题使用 --retry-failed,不包含已评分的零分题。
任务直接使用当前共享工作区的 src/、infra/ 和 venv/,不再复制源码或根目录说明文件;
运行期间应保持这些代码和环境不变。补跑会新建 VM 执行,不从旧轨迹或旧 VM 状态继续。
runs/<run_id>/
├── run.json / submit.log / summary.json / summary.csv
├── job_specs/job-NN.json # 600;含 key,跑完可删
├── jobs/job-NN/
│ ├── job.json / status.txt / tail.log / heartbeat.json / summary.json
│ ├── worker/{entry,dockerd,docker-pull,deps-check}.log
│ ├── worker/evaluation_model.jsonl # 配置评分模型时记录调用状态
│ ├── evaluation_dependencies/<task>.json # 需要预检的评分依赖
│ └── episodes/<task>/
│ ├── task.json / episode.json / evaluation.json
│ ├── traj.jsonl # 步骤摘要(动作、回执、窗口、截图引用)
│ ├── llm_calls.jsonl # 相对软链 → agent/<session>/llm_trace.jsonl
│ ├── screenshots/step_NN.png
│ ├── agent/ # 上游原始产物(steps.jsonl / llm_trace / runtime)
│ ├── config/{app.yaml,agent.yaml}
│ └── agent_result.json / agent_stdout.log
多阶段题还会生成 phases/phase-NN/ 下的配置、actor 结果、stdout、评分和轨迹;
原始 agent 日志位于 agent/phase-NN/。phase_results.json 保存逐阶段分数,
顶层 traj.jsonl 合并阶段摘要并附 phase_index,llm_calls.index.json 索引各阶段 trace。
原始模型响应与编排 journal 分别见 agent 目录下的 provider_responses.jsonl、
query_NNNN/orchestration.jsonl;实际位置由 session/query 子目录决定。
summary.csv 字段:task_id,status,score,steps,seconds,stop_reason,model,failure_reason。
每个 job 独立写汇总,run 汇总从磁盘读取各题最新的 episode.json,区分零分与未评分。
scripts/export_jevduo_trajectories.py 与同目录 HTML 模板组成独立导出工具,仅需 Python 3.10+ 标准库。
输入路径必填,兼容原生 runs/<run_id>/jobs/job-NN/episodes/<task>/ 和归档的 episodes/<task>/;
也可直接传入某个 jobs/job-NN/。默认生成输入目录下的 trajectories.html,浏览器可直接打开。
# 导出指定 run,图片通过相对路径引用
venv/bin/python scripts/export_jevduo_trajectories.py runs/jv-smoke-001
# 单题可携带页面;重复 --task 可选多题
venv/bin/python scripts/export_jevduo_trajectories.py runs/jv-smoke-001 \
--task 001 --embed-images -o /tmp/jevduo-001.html默认不覆盖已有页面,更新时显式加 --force。相对图片模式需保留页面与产物的相对位置;
--embed-images 将截图嵌入 HTML,便于复制,但页面会更大。
--skip-model-observations 可跳过较大的模型 trace,省略 General 中间观察。
页面区分编排周期、工具执行、子代理返回和后续父代理验证,分别展示零分与未评分。 同题多份执行按来源路径单独展示,页内统计包含每份执行,不等同于 run 汇总中按最新结果去重的统计。 缺失的日志、截图或无法唯一关联的记录会提示,不能据此推断工具已执行或任务成功。 导出页面含模型文本、工具结果和截图,保留原始内容;嵌入图片不会自动脱敏,分享前须检查。
uv pip install --python venv/bin/python pytest ruff
venv/bin/python -m pytest -q
venv/bin/python -m ruff check src tests scripts/export_jevduo_trajectories.py
bash -n scripts/setup_env.sh scripts/run.sh infra/worker.sh
git diff --check上述检查不提交集群任务;真实模型、VM 和官方评分链路需通过单题冒烟另行验证。
.env.local、runs/、venv/、job_specs/ 均已忽略。spec 含 actor、评分模型、Jev 和基准凭据,
按私有文件处理;配置示例只引用环境变量。异常摘要会遮盖 sk- 前缀和 Bearer 格式的值,
这是有限格式的脱敏,不代表原始模型、工具、截图等产物可以直接公开。
src/upstream/ 以 git subtree 方式入库,内容是上游仓库的精简树(去掉 docs/、tests/、
examples/、CI,仅保留运行必需部分):
| 项 | 值 |
|---|---|
| 上游仓库 | https://github.com/beipo-ai/NorthCUA |
| 导入基线 commit | 7069e43446c21184f493681ef1eddffa3aeff871 |
| 保留内容 | northcua、northcua_protocol、northcua_runtime_shared、northcua_controller_plugins、northcua_device、packages、config、skills、pyproject.toml、uv.lock、LICENSE、NOTICE、THIRD_PARTY_NOTICES.md |
| 入库体积 | 压缩后约 2 MB(工作区展开约 97 MB) |
跟随上游升级(在新的精简分支上做,再 pull 进 subtree):
# 1. 取上游新版本并精简
UPSTREAM_REPO='https://github.com/beipo-ai/NorthCUA.git'
NEW_COMMIT='填写上游 commit'
JEVDUO_REPO='/共享盘上的/JevDuo'
git clone "$UPSTREAM_REPO" /tmp/ncua-trim
cd /tmp/ncua-trim && git checkout -b trimmed "$NEW_COMMIT"
git rm -r --cached --ignore-unmatch docs tests examples .github
git commit -m "trim upstream"
# 2. 回到本仓库拉进子树
cd "$JEVDUO_REPO"
git subtree pull --prefix=src/upstream /tmp/ncua-trim trimmed --squash升级后若 uv.lock 变化,重跑 bash scripts/setup_env.sh。
- PyYAML 只在开发机:worker 侧不要 import
settings。 - venv 解释器必须在共享盘:
setup_env.sh会断言venv/bin/python的解引用路径位于仓库内, 否则 worker 内会No such file or directory。 - registry 凭据:
settings.py将裸user:pass规范为 base64 后写入 spec;worker.sh将cluster.registry_auth[host].auth写入~/.docker/config.json。 - 集群容量:CPU 紧张时 rjob 会长时间排队(事件里是
Insufficient cpu),不是代码问题。 - 预算耗尽:actor 预算停止仍可进入评分;以
episode.json的实际状态和官方分数为准, 不将整题硬截止或评分异常算作有效零分。
测评分支保留评测工程及配套文档;harness 本体和 demo 的主线开发属于 main。
两个分支保持独立,不从 main 合并,也不向 main 回推。