Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions DEVIATIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,3 +102,23 @@
`Ranking`、`build_choice_requests` 和 `ranking_dict` 从原 JEV 模块移到
`models/ranking.py`,供 JEV/Kev 共用;现有函数体、prompt 和排序语义保持不变。
配置字段、启动命令、消息协议、结果目录以及 step/stage 执行行为均不变。

## 共享语义感知(2026-10-29)

30. 【行为】a11y/DOM 先形成慢模型与快模型共用的语义元素表:恢复邻近标签、分离
`browser_chrome` / `web_content` / `dialog` / `menu` / `native`,当前输入值不再冒充
控件名称。CDP 是 Task 008 等已启用远程调试的 Chrome 的可选增强,失败时回退 a11y;
协议新增 `browser_snapshot` 文件引用并升至 0.2。候选备选只在提案 scope 内生成,
不再补入全局 click/keypress;无 grounder 时不提供 visual_fallback。JEV 近期历史只保留
动作、目标、结果和状态变化,不再携带完整 verification。
31. 【修复】慢模型对端提前断开(`RemoteDisconnected` / `ConnectionError`)纳入现有
有界重试,不再把一次 transient 断连直接记为整题异常;重试次数和退避策略不变。
32. 【行为】阶段目标绑定增加规范化名称和兼容 role 的唯一匹配;全部提案未绑定时,
改为当前 scope 内的有限恢复候选 + RETURN_TO_PLANNER,不再在 JEV 前直接计 no_action。
`stage_replan` 记录失败提案和可用目标。滚动提案的 schema 重试反馈定位到具体字段。
33. 【行为】恢复条件扩展到“已绑定但不可执行”的提案;菜单滚动增加 PageDown/PageUp
和方向键候选。CLI milestone 必须顶层携带 command,operation=cli 获得专门的重试反馈。
34. 【修复】JEV 断线恢复支持 endpoint 重新发现、30 秒健康检查、瞬态 HTTP 状态与
Retry-After;恢复等待继续受 1200 秒总窗口限制,并记录 attempt/endpoint/error_type。
35. 【重构】新增 `scripts/run_experiment.sh`:按唯一实验名归档 manifest、batch、driver
和 task 结果到 `rjob_logs/<experiment>/`,避免不同实验日志混写。
33 changes: 27 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

```
观察 Observation
截图 · a11y 树 · 预算 · 上一步回执
截图 · a11y 树 · 可选 CDP DOM 快照 · 预算 · 上一步回执
│
▼
┌─────────────────────────────────────────────┐
Expand Down Expand Up @@ -77,16 +77,19 @@

`TandemSession.act(observation)` 是唯一的决策入口,状态机语义(`runtime/session.py`):

1. **读观察**:`Observation` 含截图引用(path + sha256)、a11y 树引用、预算、上一轮回执。
2. **建目标**:a11y 树解析成 `UITarget` 列表(角色 / 名称 / 坐标 / 边界框,`gui/targets.py`)。
1. **读观察**:`Observation` 含截图、a11y 树和可选 CDP DOM 快照引用、预算、上一轮回执。
2. **建目标**:a11y 树解析成 `UITarget`,`gui/semantics.py` 恢复邻近标签、
分离浏览器外壳与网页内容,并合并 a11y/DOM 元素。
3. **慢模型规划**:`planning.planner.plan_step` 产出 plan——`current_goal`、`expected_observation`、
`route`(gui/cli)、`action_proposals`、`task_status`、`done`。
4. **终态分支**:planner 声称完成 → `handle_done`:若需求带 `output_path`,先发一条 CLI
存在性探针(`done_probe`)核对交付物文件是否真的存在,探针通过后才进入终态裁决
(`terminal_decision`);未通过则回到规划重来。
5. **CLI 路由**:`route == "cli"` → 直接下发 `CliAction`(bash -lc,cwd=/home/user,1 条 CLI 计 1 步)。
6. **建候选空间**:`gui/candidates.py` 由目标展开动作(click / double_click / type / scroll / hotkey…),
再经 `focused_candidates` 聚焦 + `prune_stalled` 剪枝。
6. **建候选空间**:`gui/candidates.py` 由目标展开动作,再经 `focused_candidates`
按慢模型提案和元素 scope 聚焦,经 `prune_stalled` 剪枝;网页提案不会补入浏览器外壳候选。
全部提案无法唯一绑定时,使用当前 scope 内的有限恢复候选和 `RETURN_TO_PLANNER`,
不在调用快模型前直接计为 no_action。
7. **快模型排序**:两阶段——先选 **operation**(点击还是输入),再在胜出 operation 内选 **action**(具体哪个目标)。
结果带 `operation_margin`(两级置信度差)与 `latency_ms`。
8. **编译动作**:`gui/compile.py` 把 winner + 目标编译成**声明式** `GuiAction`
Expand All @@ -108,7 +111,7 @@

## 组件装配

`components.py` 定义依赖注入边界——九个字段,没有插件框架、没有隐藏分发:
`components.py` 定义依赖注入边界——十个字段,没有插件框架、没有隐藏分发:

| 字段 | 职责 | 默认实现 |
|---|---|---|
Expand All @@ -117,6 +120,7 @@
| `requirements` | 需求抽取 | `verification.verifier.task_requirements` |
| `selector` | 排序后端 | `models.jev.JevOmniPolicy` / `models.kev.KevPolicy` |
| `target_builder` | a11y 树 → 目标 | `gui.targets.A11yTargetBuilder` |
| `semantic_enricher` | a11y/DOM → 共享语义元素表 | `gui.semantics.enrich_targets` |
| `candidate_builder` | 目标 → 动作候选 | `gui.candidates.ActionCandidateBuilder` |
| `focus_candidates` | 提案聚焦 + 剪枝 | `gui.proposals.focused_candidates` |
| `compile_gui` | winner → 声明式动作 | `gui.compile.gui_action` |
Expand Down Expand Up @@ -222,6 +226,23 @@ tandem-eval rjob run --run-id <name> --benchmark osworld2 --tasks <task-id> \
**换慢模型厂商**:在 `infra/config.json` 的 `harness.slow_model.apis` 里登记多套 API,
启动时用 `--slow-model <名字>` 挑(缺省取 `default`),不改代码。

## 命名实验与日志目录

`scripts/run_experiment.sh` 将一次实验的全部产物归档到 `rjob_logs/<experiment>/`。
实验名只能使用小写字母、数字和连字符,且每个实验目录必须唯一。

```bash
bash scripts/run_experiment.sh \
--experiment kimi12-retry-20261030 \
--tasks 024,029,037,045,057,059,069,082,088,093,005,031 \
--concurrency 12 --slow-model kimi-k3 --slow-key-ids 1,2,3,4 \
--max-steps 500 --max-wall 14400
```

目录结构:`manifest.json`(实验参数与 git describe)、`batch.log`、
`drivers/<task>.driver.log` 和 `<experiment>-<task>/`(worker、模型、轨迹与结果)。
worker 的 adpc 挂载只读时仍使用 evobox 暂存,任务结束后立即归档到该实验目录。

集群内使用模板配置时,`api_key` 留空会使用默认号池,也可以手动填写自己的 `api_key`。

需要指定号池中的 key 时,在原启动命令后追加:
Expand Down
37 changes: 37 additions & 0 deletions docs/CLUSTER_RUNTIME.md
Original file line number Diff line number Diff line change
Expand Up @@ -295,3 +295,40 @@ worker 侧各段日志:

- `--benchmark mock` 走 mock 链路(不起 VM、不碰共享资源),可本地跑;
- 真实基准走 OSW1 / OSW2 / OSW2.1,按本文 §3–§7。

## 11. 浏览器 CDP 语义快照

- `tandem_eval.browser` 在 VM 内通过 loopback 依次探测 `1337` / `9222`,只调用
`GET /json/list` 与 `Runtime.evaluate`,不重启 Chrome、不激活 tab、不执行页面 mutation。
多 tab 时选择 `document.visibilityState=visible` 的页面。
- 任务必须已由环境以远程调试参数启动 Chrome;Task 008 的 setup 已显式启用 `1337`。
其他任务未启用、端口被拒绝或快照异常时只记录诊断并回退 a11y,不让整题失败。
- 快照经协议 `browser_snapshot` 文件引用进入 harness;episode 正本保存在
`episodes/<task>/browser/step_XX.json`。密码、隐藏和文件输入元素不进入快照。
- 2026-10-29 Task 008 真机 probe 已验证 `1337`、WebSocket 和 DOM 序列化可用,
无需额外权限。首次有效快照含 4 个元素;9222 被其他环境组件占用时不影响 1337 采集。

## 12. JEV 断线恢复

- 排序请求发生连接超时、瞬态 HTTP 408/429/500/502/503/504 或响应 JSON 错误时,
在 1200 秒总窗口内重试;非瞬态 HTTP 错误立即失败,不盲目重试。
- 健康检查超时为 30 秒;`Retry-After` 优先于默认 15 秒等待。恢复事件记录
`attempt`、`endpoint`、`error_type`、`remaining_seconds` 和 `retry_delay_seconds`。
- worker 建 session 时注入 endpoint provider。恢复过程中会重新读取 `endpoint_file`,
JEV 重新部署导致地址变化时记录 `fast_model_endpoint_changed` 并切换地址。
发现文件未 ready 时保留当前地址继续有界恢复,不会直接放弃整题。

## 13. 命名实验

统一使用仓库内 `scripts/run_experiment.sh`,不要直接散落调用 `tandem-eval rjob run`。
每次实验必须指定唯一名称(小写字母、数字、连字符),所有结果归档到
`rjob_logs/<experiment>/`:

- `manifest.json`:tasks、并发、模型、key_ids、预算、watch timeout、git describe;
- `batch.log`:批次输出;
- `drivers/<task>.driver.log`:单个 rjob 生命周期日志;
- `<experiment>-<task>/`:worker、模型调用、轨迹、截图和评分结果。

脚本只同步一次代码,然后按指定并发提交。worker 的 adpc 挂载只读时,结果先落
evobox 暂存,单题完成后立即 rsync 到实验目录。`--dry-run` 只生成 manifest 和 batch log,
不提交 rjob。
7 changes: 4 additions & 3 deletions docs/RESULT_DIR_CONTRACT.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# 结果目录契约(Result Directory Contract)

> eval ↔ demo/分析 的唯一接口。demo/分析工具只读本契约描述的目录;任何一侧改动必须先改本文档。
> 契约版本:`v0.2`(M3 后)。tandem_eval.recorder 是唯一写入者。
> 契约版本:`v0.3`。tandem_eval.recorder 是唯一写入者。

## run 目录(`rjob_logs/<run_id>/`,唯一落盘位置)

Expand All @@ -27,11 +27,12 @@ OSWorld 2.1 显式配置替代 judge/用户模拟器时,`code_version.json.res
| 文件 | 内容 | 写入时机 |
|------|------|---------|
| `task.json` | 任务定义完整副本 | episode 开始 |
| `traj.jsonl` | 每执行步一行:`{step_idx, wall_time, protocol_version, observation{screenshot(sha256/path/w/h), accessibility_tree(present/source/digest/node_count), budget(steps_remaining, wall_seconds_remaining), last_receipt}, action{kind, …}}` | 每步 env.execute 后 |
| `traj.jsonl` | 每执行步一行:`{step_idx, wall_time, protocol_version, observation{screenshot(sha256/path/w/h), accessibility_tree(present/source/digest/node_count), browser_snapshot(present/source/digest/node_count/path 或 null), budget(...), last_receipt}, action{kind, …}}` | 每步 env.execute 后 |
| `llm_calls.jsonl` | 全量 LLM 请求/响应,每行 `{role, time, request{payload, messages}, response, attempt}`;Bearer/api_key 脱敏 | 慢模型客户端成功响应时(llm_sink → LlmTap → 本文件) |
| `events.jsonl` | harness 决策事件(route 字段区分):`planner`(发给 LLM 的计划全文 + 有效响应)/ `gui`(候选列表 + ranking{operation_request, action_request, operation_ranked, action_ranked, winner, margins, latency_ms, used_image} + 编译后动作)/ `cli`(路由决策 + 命令)/ `gui_verified` / `cli_verified`(验证裁决 + 回执)/ `terminal`(终态双确认)/ `action`(runner 写的执行记录,与 session 事件穿插) | session.act() 后增量排水 |
| `a11y_digests.jsonl` | 每步 a11y sha256 + 节点数(`{step_idx, sha256, node_count}`) | 每步(全量 xml 默认关闭,record.a11y_full=true 时另写 `a11y/step_XX.xml`) |
| `screenshots/step_XX.png` | 逐步截图(**契约正本**) | 每步 env.execute 后 |
| `browser/step_XX.json` | CDP DOM 语义快照(启用且成功时);traj 的 browser_snapshot.path 指向此正本 | 每步 env.execute 后 |
| `deliverables/` | finish 时从 VM 导出的交付物文件(含 export_paths) | episode 终态 |
| `artifacts.json` | deliverables 导出记录(`[{vm_path, exported, local_path, bytes}]`) | episode 终态 |
| `evaluation.json` | 官方评分(`{source: "official_benchmark_evaluator", raw, score}`) | episode 终态(评分成功时) |
Expand Down Expand Up @@ -78,7 +79,7 @@ OSWorld 2.1 显式配置替代 judge/用户模拟器时,`code_version.json.res
| `terminal` | 终态裁决(planner 声称完成后的 verifier 双确认全文) |
| `stage_local` | 消费已生成的阶段计划;含 stage_goal、milestone 和当帧重绑定后的 plan,不代表新的模型调用 |
| `stage_progress` | 里程碑推进,含 stage_goal、milestone、验证 source |
| `stage_replan` | 阶段修复请求,含原因及当前里程碑;不等于调用已经完成 |
| `stage_replan` | 阶段修复请求,含原因及当前里程碑;target_unbound 时另含 `unbound_proposals`、`available_targets`、`recovery_scopes`;不等于调用已经完成 |
| `action`(kind 字段) | runner 写的执行记录 `{step, kind: "action", action: {…协议动作…}}` |

stage 模式的 planner 事件只在真实规划调用时写入,增加 mode、reason、seconds;
Expand Down
8 changes: 8 additions & 0 deletions docs/STAGE_EXECUTION.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,11 @@
- `verification/stage_rules.py`:基于回执与 A11y 的后置条件验证。
- `runtime/episode.py`:回执验证编排与独立终态检查。
- `components.py`:按 `execution_mode` 装配规划器,继续复用相同的 GUI 和模型组件。

目标绑定先尝试精确 name/role/parent,再尝试规范化名称和兼容 role;只有唯一匹配才绑定。
全部提案无法唯一绑定时,不再于 JEV 前直接累计 no_action,而是生成当前 scope 内的
有限恢复候选(click、double-click、Enter/Escape)以及 RETURN_TO_PLANNER。
提案已绑定但无法编译为动作时,也进入同一恢复流程;滚动场景额外提供
PageDown/PageUp 和上/下方向键,覆盖菜单内导航。
`stage_replan` 同时记录 `unbound_proposals`、`available_targets` 和 `recovery_scopes`,
供慢模型在下一次修复中选择不同目标或方法。多个匹配仍然不会被静默猜测。
161 changes: 161 additions & 0 deletions scripts/run_experiment.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,161 @@
#!/usr/bin/env bash
# Run one named experiment and keep all artifacts under rjob_logs/<experiment>/.
set -euo pipefail

REPO="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cd "$REPO"

EXPERIMENT=""
TASKS=""
CONCURRENCY=4
SLOW_MODEL="kimi-k3"
SLOW_KEY_IDS="1,2,3,4"
MAX_STEPS=500
MAX_WALL=14400
DRY_RUN=0

usage() {
cat <<'EOF'
Usage:
bash scripts/run_experiment.sh \
--experiment NAME --tasks ID1,ID2,... [--concurrency N] \
[--slow-model NAME] [--slow-key-ids 1,2,3,4] \
[--max-steps N] [--max-wall SECONDS] [--dry-run]

Experiment names use lowercase letters, digits and hyphens only.
Artifacts: rjob_logs/NAME/{manifest.json,batch.log,drivers/,NAME-TASK/}.
EOF
}

while [[ $# -gt 0 ]]; do
case "$1" in
--experiment) EXPERIMENT="$2"; shift 2 ;;
--tasks) TASKS="$2"; shift 2 ;;
--concurrency) CONCURRENCY="$2"; shift 2 ;;
--slow-model) SLOW_MODEL="$2"; shift 2 ;;
--slow-key-ids) SLOW_KEY_IDS="$2"; shift 2 ;;
--max-steps) MAX_STEPS="$2"; shift 2 ;;
--max-wall) MAX_WALL="$2"; shift 2 ;;
--dry-run) DRY_RUN=1; shift ;;
-h|--help) usage; exit 0 ;;
*) echo "unknown argument: $1" >&2; usage >&2; exit 2 ;;
esac
done

if [[ ! "$EXPERIMENT" =~ ^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$ ]]; then
echo "invalid experiment name: use lowercase letters, digits and hyphens" >&2
exit 2
fi
if [[ -z "$TASKS" || "$CONCURRENCY" -lt 1 || "$MAX_STEPS" -lt 1 || "$MAX_WALL" -lt 1 ]]; then
usage >&2
exit 2
fi

EXPERIMENT_ROOT="${TANDEM_EXPERIMENT_ROOT:-$REPO/rjob_logs}"
EXPERIMENT_DIR="$EXPERIMENT_ROOT/$EXPERIMENT"
DRIVER_DIR="$EXPERIMENT_DIR/drivers"
if [[ -e "$EXPERIMENT_DIR/manifest.json" ]]; then
echo "experiment already exists: $EXPERIMENT_DIR" >&2
exit 3
fi
mkdir -p "$DRIVER_DIR"

if [[ ! -f infra/config.json && "$DRY_RUN" -ne 1 ]]; then
echo "infra/config.json is required for a real run" >&2
exit 4
fi
CONFIG_FILE="${TANDEM_CONFIG_FILE:-infra/config.json}"
if [[ ! -f "$CONFIG_FILE" ]]; then
CONFIG_FILE=infra/config.example.json
fi

read -r STAGING < <(python3 - "$CONFIG_FILE" <<'PY'
import json
from pathlib import Path
import sys
print(json.loads(Path(sys.argv[1]).read_text())["log"]["results_root"])
PY
)
export STAGING EXPERIMENT DRIVER_DIR TASKS CONCURRENCY SLOW_MODEL SLOW_KEY_IDS MAX_STEPS MAX_WALL
python3 - <<'PY'
import json
import os
import subprocess
from pathlib import Path

experiment = os.environ["EXPERIMENT"]
directory = Path(os.environ["DRIVER_DIR"]).parent
args = {
"experiment": experiment,
"tasks": os.environ["TASKS"].split(","),
"concurrency": int(os.environ["CONCURRENCY"]),
"slow_model": os.environ["SLOW_MODEL"],
"slow_key_ids": [int(item) for item in os.environ["SLOW_KEY_IDS"].split(",")],
"max_steps": int(os.environ["MAX_STEPS"]),
"max_wall_seconds": float(os.environ["MAX_WALL"]),
"watch_timeout_seconds": float(os.environ["MAX_WALL"]) + 600,
"git_describe": subprocess.check_output(
["git", "describe", "--always", "--dirty"], text=True
).strip(),
}
(directory / "manifest.json").write_text(
json.dumps(args, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
)
PY

exec > >(tee "$EXPERIMENT_DIR/batch.log") 2>&1

if [[ "$DRY_RUN" -eq 1 ]]; then
echo "dry-run: experiment=$EXPERIMENT tasks=$TASKS output=$EXPERIMENT_DIR"
exit 0
fi

env PYTHONPATH=src python3 - <<'PY'
from pathlib import Path
from tandem_eval.rjob import load_config, sync_repo

config = load_config("infra/config.json")
sync_repo(Path("."), Path(config["eval"]["deploy_root"]))
PY

run_task() {
local task="$1"
local run_id="${EXPERIMENT}-${task}"
local driver_log="${DRIVER_DIR}/${task}.driver.log"
local rc=0

tandem-eval rjob run \
--run-id "$run_id" \
--benchmark osworld21 \
--tasks "$task" \
--execution-mode stage \
--stage-max-actions 10 \
--slow-model "$SLOW_MODEL" \
--slow-key-ids "$SLOW_KEY_IDS" \
--max-steps "$MAX_STEPS" \
--max-wall "$MAX_WALL" \
--poll 60 \
--timeout "$((MAX_WALL + 600))" \
--repo . \
--config "$CONFIG_FILE" \
--no-sync >"$driver_log" 2>&1 || rc=$?

if [[ -d "$STAGING/$run_id" ]]; then
mkdir -p "$EXPERIMENT_DIR/$run_id"
rsync -a "$STAGING/$run_id/" "$EXPERIMENT_DIR/$run_id/"
fi
printf '{"task":"%s","returncode":%d,"run_id":"%s","logs":"%s"}\n' \
"$task" "$rc" "$run_id" "$EXPERIMENT_DIR/$run_id"
}
export -f run_task

IFS=',' read -r -a TASK_ARRAY <<< "$TASKS"
for task in "${TASK_ARRAY[@]}"; do
run_task "$task" &
while [[ "$(jobs -pr | wc -l)" -ge "$CONCURRENCY" ]]; do
wait -n
done
done
wait

echo "experiment complete: $EXPERIMENT_DIR"
Loading
Loading