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
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ jobs:
- name: Lint
run: ruff check src tests demo
- name: Protocol self-check
run: tandem check
run: jevduo check
- name: Test
run: |
set -o pipefail
Expand Down
32 changes: 16 additions & 16 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

## 仓库定位

主体是 **Tandem harness**(快慢双模 CUA,`src/tandem/`);`src/tandem_eval/` 仅为适配集群 rjob 的测评薄适配层(worker 侧 6 文件 + 开发机侧 rjob.py / rjob_spec.py / rjob_status.py / config_schema.py)。
主体是 **Tandem harness**(快慢双模 CUA,`src/jevduo/`);`src/jevduo_eval/` 仅为适配集群 rjob 的测评薄适配层(worker 侧 6 文件 + 开发机侧 rjob.py / rjob_spec.py / rjob_status.py / config_schema.py)。

## 五条硬纪律(CI/评审强制)

Expand All @@ -16,7 +16,7 @@
4. **一个 PR = 一个组件改动 + 单测 + smoke 结果链接**(真机 smoke 已可用:`--benchmark mock` 走 mock 链路;真实基准走 OSW1/OSW2)。
5. **ruff + pytest + 契约测试三件套从第一天齐上**:本地提交前 `ruff check src tests && pytest` 必须绿。

## 协议纪律(`src/tandem/protocol/`)
## 协议纪律(`src/jevduo/protocol/`)

- `schema/*.json` 是唯一真源;`validate.py` 是运行时强制者;`samples/*.json` 是 golden 样例。三者由 `tests/protocol/` 锚定,改动必须同步。
- 任何字段增删/语义变化 = bump `protocol_version` 次版本号,并同步全部 golden 样例与 schema。
Expand All @@ -40,13 +40,13 @@
## 开发闭环

```
改代码 → ruff check src tests → pytest →(若触碰协议)tandem check → PR(附单测 + smoke 链接)
改代码 → ruff check src tests → pytest →(若触碰协议)jevduo check → PR(附单测 + smoke 链接)
```

- `tandem check`:协议样例自检(CI 也跑)。
- `tandem-eval rjob run …`:一站式提交(sync→spec→submit→watch→fetch→cleanup)。
- `jevduo check`:协议样例自检(CI 也跑)。
- `jevduo-eval rjob run …`:一站式提交(sync→spec→submit→watch→fetch→cleanup)。
**收尾默认删 rjob**——成功/失败/超时/异常都删,不在集群上留残留;`--keep` 保留现场。
- `tandem-eval entry --spec …`:worker 侧入口(infra/worker.sh 调用)。
- `jevduo-eval entry --spec …`:worker 侧入口(infra/worker.sh 调用)。

## 共享资源纪律(worker 侧)

Expand Down Expand Up @@ -86,14 +86,14 @@
## 目录地图

```
src/tandem/ harness 主体(组件、协议、CLI)
src/tandem/runtime/ 会话状态机、回执处理、阶段推进与停止条件
src/tandem/planning/ 单步规划与阶段规划
src/tandem/gui/ A11y 目标、动作候选、聚焦剪枝与声明式动作编译
src/tandem/models/ 慢模型客户端、JEV/Kev 选择器与共用排序结构
src/tandem/verification/ 需求抽取、模型验证与阶段规则验证
src/tandem/protocol/ 消息层协议:schema/ 真源、validate/ 校验、samples/ golden
src/tandem_eval/ worker 侧 6 文件(entry/env/runner/recorder/scoring/manifest)
src/jevduo/ harness 主体(组件、协议、CLI)
src/jevduo/runtime/ 会话状态机、回执处理、阶段推进与停止条件
src/jevduo/planning/ 单步规划与阶段规划
src/jevduo/gui/ A11y 目标、动作候选、聚焦剪枝与声明式动作编译
src/jevduo/models/ 慢模型客户端、JEV/Kev 选择器与共用排序结构
src/jevduo/verification/ 需求抽取、模型验证与阶段规则验证
src/jevduo/protocol/ 消息层协议:schema/ 真源、validate/ 校验、samples/ golden
src/jevduo_eval/ worker 侧 6 文件(entry/env/runner/recorder/scoring/manifest)
+ 开发机侧 rjob.py / rjob_spec.py / rjob_status.py 生命周期客户端
+ config_schema.py(config.json 的校验与 API 选取)
tests/ protocol/ harness/ eval/ demo/ 四组
Expand All @@ -108,9 +108,9 @@ docs/ RESULT_DIR_CONTRACT.md(eval↔demo 唯一接口)
CLUSTER_RUNTIME.md(内部集群运行手册:rjob/共享资源/已知坑)
```

`src/tandem/` 根目录只保留包信息、CLI、`config.py` 和 `components.py`。
`src/jevduo/` 根目录只保留包信息、CLI、`config.py` 和 `components.py`。
组件继续经 `Components` / `build_default` 装配;不要在 runtime 中硬编码新的模型后端。
真实执行、环境生命周期、评分与结果落盘仍归 `tandem_eval`。
真实执行、环境生命周期、评分与结果落盘仍归 `jevduo_eval`。

## 结果目录纪律

Expand Down
40 changes: 27 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@

## 一次决策的链路

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

1. **读观察**:`Observation` 含截图、a11y 树和可选 CDP DOM 快照引用、预算、上一轮回执。
2. **建目标**:a11y 树解析成 `UITarget`,`gui/semantics.py` 恢复邻近标签、
Expand All @@ -94,7 +94,7 @@
结果带 `operation_margin`(两级置信度差)与 `latency_ms`。
8. **编译动作**:`gui/compile.py` 把 winner + 目标编译成**声明式** `GuiAction`
(kind / action_type / parameters / target_id),不做代码生成。
9. **执行与验证**(tandem_eval 层):环境执行后回传 `Receipt`;下一轮进入
9. **执行与验证**(jevduo_eval 层):环境执行后回传 `Receipt`;下一轮进入
`runtime.episode.verify_pending`——用新观察独立核验上一步,更新 verified_focus、failed_toggles、
以及**逐条需求的核验状态**(`requirement_checks`)。
10. **停止条件**:步数/墙钟预算耗尽 → `FailAction`;连续 3 次无可执行动作 → `FailAction(no_action_limit)`。
Expand Down Expand Up @@ -130,7 +130,7 @@

## 消息层协议

harness 与环境之间只走 JSON 消息(`src/tandem/protocol/`):
harness 与环境之间只走 JSON 消息(`src/jevduo/protocol/`):

- **Observation**(环境 → harness):任务指令、步号、预算、截图引用、a11y 树引用、上一轮回执;
- **Action**(harness → 环境):`GuiAction` / `CliAction` / `WaitAction` / `FinishAction` / `FailAction`;
Expand All @@ -146,15 +146,15 @@ harness 与环境之间只走 JSON 消息(`src/tandem/protocol/`):
自检:

```bash
tandem check # 协议样例自检(CI 同样跑)
jevduo check # 协议样例自检(CI 同样跑)
```

## 仓库结构

| 路径 | 定位 |
|---|---|
| `src/tandem/` | **仓库主体**:快慢双模 harness(决策状态机、规划/验证、候选与排序、协议层、组件装配) |
| `src/tandem_eval/` | 测评薄适配层:worker 侧 6 文件(entry/env/runner/recorder/scoring/manifest)+ 开发机侧 `rjob.py` 生命周期客户端 |
| `src/jevduo/` | **仓库主体**:快慢双模 harness(决策状态机、规划/验证、候选与排序、协议层、组件装配) |
| `src/jevduo_eval/` | 测评薄适配层:worker 侧 6 文件(entry/env/runner/recorder/scoring/manifest)+ 开发机侧 `rjob.py` 生命周期客户端 |
| `infra/` | 内部集群适配:唯一配置文件、worker 入口脚本(详见 [集群运行手册](docs/CLUSTER_RUNTIME.md)) |
| `demo/` | 轨迹回放与对比站点:只读结果目录,不 import harness、不调模型、不碰 VM |
| `tests/` | `protocol/` `harness/` `eval/` `demo/` 四组 |
Expand All @@ -171,30 +171,30 @@ tandem check # 协议样例自检(CI 同样跑)
pip install -e '.[dev]'

# 三件套:lint + 单测 + 协议自检
ruff check src tests && pytest && tandem check
ruff check src tests && pytest && jevduo check
```

把 harness 当库用:

```python
from tandem.components import build_default
from tandem.config import SessionConfig
from tandem.runtime.session import TandemSession
from jevduo.components import build_default
from jevduo.config import SessionConfig
from jevduo.runtime.session import JevDuoSession

components = build_default(
client=slow_client, # models.slow.SlowModelClient(慢模型客户端)
endpoint="http://<排序服务>/rank",
config=SessionConfig(fast_backend="jev"),
)
session = TandemSession(components)
session = JevDuoSession(components)
session.begin("把 FYP 答辩安排逐条加进日历", None) # None → 慢模型抽取需求
action = session.act(observation) # Observation → Action
```

在真实环境上跑一题(提交到内部集群):

```bash
tandem-eval rjob run --run-id <name> --benchmark osworld2 --tasks <task-id> \
jevduo-eval rjob run --run-id <name> --benchmark osworld2 --tasks <task-id> \
--repo . --config infra/config.json --poll 60 --timeout 3600
```

Expand All @@ -207,9 +207,23 @@ tandem-eval rjob run --run-id <name> --benchmark osworld2 --tasks <task-id> \

完整参数表与运行细节见 [docs/CLUSTER_RUNTIME.md](docs/CLUSTER_RUNTIME.md)。

### 从旧名称 tandem 升级

项目已更名为 JevDuo:包名 `tandem` → `jevduo`,`tandem_eval` → `jevduo_eval`,命令 `tandem` / `tandem-eval` → `jevduo` / `jevduo-eval`,类 `TandemSession` → `JevDuoSession`。旧入口已移除,不保留别名。已有安装按下面三步升级:

```bash
pip uninstall -y tandem # 卸载旧包(uv 环境:uv pip uninstall tandem)
pip install -e '.[dev]' # 以新名称重装
jevduo check # 确认入口可用
```

- 自己的脚本里 `import tandem` / `from tandem_eval ...` 需改为 `jevduo` / `jevduo_eval`。
- 环境变量 `TANDEM_*` 本次未改名,仍按原名使用。
- rjob 任务名前缀由 `tandem-<run-id>` 变为 `jevduo-<run-id>`;开发机 `infra/config.json` 里的 `eval.repo_root` / `eval.deploy_root` 需按新目录同步,旧的部署副本确认无在跑任务后再清理。

## 会话配置

`SessionConfig`(`src/tandem/config.py`,frozen dataclass,构造即校验):
`SessionConfig`(`src/jevduo/config.py`,frozen dataclass,构造即校验):

| 字段 | 默认 | 说明 |
|---|---|---|
Expand Down
2 changes: 1 addition & 1 deletion demo/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

## 边界(硬约束)

demo 层与 harness **完全解耦**:不 import `tandem` / `tandem_eval`、不调模型、不碰 VM。
demo 层与 harness **完全解耦**:不 import `jevduo` / `jevduo_eval`、不调模型、不碰 VM。
唯一输入是 `docs/RESULT_DIR_CONTRACT.md` 描述的结果目录契约 + `demo/data/` 里的
官方数据快照。`tests/demo/test_site.py` 有一条断言专门守这条边界。

Expand Down
2 changes: 1 addition & 1 deletion demo/reader/__init__.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
"""demo 读取层:结果目录 → 站点数据契约。

**边界**(见 `demo/README.md`):不 import `tandem` / `tandem_eval`、不调模型、不碰 VM。
**边界**(见 `demo/README.md`):不 import `jevduo` / `jevduo_eval`、不调模型、不碰 VM。
唯一输入是 `docs/RESULT_DIR_CONTRACT.md` 描述的结果目录契约。

**为什么拆成包**:老 `demo/adapter.py` 一个模块同时干了"读目录 / 算指标 / 拼 HTML",
Expand Down
2 changes: 1 addition & 1 deletion demo/sync_official.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
站点是**离线可开**的,所以官方数据要 vendored 进 `demo/data/`;本脚本负责
"重新拉一遍 + 校验 + 写回",保证快照不是手工维护的。

只用标准库(无新增依赖),不 import `tandem` / `tandem_eval`(demo 层纪律)。
只用标准库(无新增依赖),不 import `jevduo` / `jevduo_eval`(demo 层纪律)。

用法:
python3 demo/sync_official.py # 刷新全部
Expand Down
24 changes: 12 additions & 12 deletions docs/CLUSTER_RUNTIME.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ worker 入口、共享资源与已知坑。

| 组件 | 位置 | 职责 |
|---|---|---|
| `src/tandem/` | 仓库主体 | harness 本体,与集群无关(见 README) |
| `src/tandem_eval/` | 薄适配层 | worker 侧 6 文件(entry/env/runner/recorder/scoring/manifest)+ 开发机侧 `rjob.py` / `rjob_spec.py` / `rjob_status.py` / `config_schema.py` |
| `src/jevduo/` | 仓库主体 | harness 本体,与集群无关(见 README) |
| `src/jevduo_eval/` | 薄适配层 | worker 侧 6 文件(entry/env/runner/recorder/scoring/manifest)+ 开发机侧 `rjob.py` / `rjob_spec.py` / `rjob_status.py` / `config_schema.py` |
| `infra/config.json` | 唯一配置 | 全绝对路径、含密钥 → **已 gitignore**,模板 `infra/config.example.json` 提交 |
| `infra/worker.sh` | worker 入口 | rjob worker 内被调用,按 benchmark 分 mock / 真机两条路 |
| `scripts/` | 批量脚本 | `run_osw2_20x5.sh` 等批量运行 |
Expand Down Expand Up @@ -83,12 +83,12 @@ Harness 内部已按 `runtime` / `planning` / `gui` / `models` / `verification`
| `log.results_root` | 唯一落盘位置,run 目录 = `<results_root>/<run_id>/` |
| `log.record.a11y_full` | 是否落每步完整 a11y XML(默认只落摘要) |

缺项/非法值由 `tandem_eval.config_schema` 统一校验(一次列出全部问题);
缺项/非法值由 `jevduo_eval.config_schema` 统一校验(一次列出全部问题);
必填路径清单见 `config_schema.REQUIRED_PATHS`。

## 3. 一次 run 的生命周期

`tandem-eval rjob run` 一站式完成 **sync → spec → submit → watch → fetch → cleanup**
`jevduo-eval rjob run` 一站式完成 **sync → spec → submit → watch → fetch → cleanup**
(`rjob.run_job`):

```
Expand Down Expand Up @@ -153,25 +153,25 @@ cleanup stop(释放资源)+ delete(永久删除 rjob 记录)——默
单独盯一个已提交的 job:

```bash
tandem-eval rjob watch tandem-<run-id> --run-id <run-id> --config infra/config.json
jevduo-eval rjob watch jevduo-<run-id> --run-id <run-id> --config infra/config.json
```

## 4. worker 侧入口

`infra/worker.sh <job spec 绝对路径>` 由 rjob worker 调用:

- **mock 基准**:直接用系统 `python3` 跑 `tandem_eval entry`,不碰共享资源与 docker;
- **mock 基准**:直接用系统 `python3` 跑 `jevduo_eval entry`,不碰共享资源与 docker;
- **真实基准**:
1. source 共享 `env.sh`(`OSWORLD_PYTHON` / `EVAL_TOOLS` / `LD_LIBRARY_PATH` 等);
2. 把 config 里的 registry 凭据写入 `~/.docker/config.json`(`chmod 600`);
3. 覆盖平台预注入的代理(真机上 `httpproxy-headless-dev-test` 不可解析),
固定为 `httpproxy-headless.kubebrain.svc.pjlab.local:3128`,并设置 `NO_PROXY`;
4. 起 `dockerd`(独立 data-root/exec-root,指向该代理),拉 `inner_image`,
打 tag 为 `happysixd/osworld-docker:latest`;
5. 用 `$OSWORLD_PYTHON` 跑 `tandem_eval entry`(Pillow / easyocr 已在冻结 venv 内),
5. 用 `$OSWORLD_PYTHON` 跑 `jevduo_eval entry`(Pillow / easyocr 已在冻结 venv 内),
跑前先做一次依赖自检。

worker 侧 `tandem_eval entry --spec <spec>` 是实际执行体:起 VM → 跑任务 → 录事件 → 评分 →
worker 侧 `jevduo_eval entry --spec <spec>` 是实际执行体:起 VM → 跑任务 → 录事件 → 评分 →
写 run 目录。环境生命周期、预算强制、落盘都在这一层,harness 只管决策。

## 5. 共享资源(只读)
Expand Down Expand Up @@ -229,7 +229,7 @@ OSW2.1 走**独立环境**(独立 runtime / VM / 资产 / venv / env.sh),
`desktop_env/providers/docker/provider.py`。
- **依赖自检**:OSW2.1 的独立 venv 按官方 `uv.lock` 安装,**没有 easyocr**,
worker 只检查 Pillow;旧环境仍检查 `easyocr + PIL`。
- **题目清单**:`tandem_eval/manifest.py` 的 `OSWORLD21_TASK_IDS` 覆盖官方001–108题。
- **题目清单**:`jevduo_eval/manifest.py` 的 `OSWORLD21_TASK_IDS` 覆盖官方001–108题。
清单不等于环境验收报告;API、VM或评分异常仍记为 `failed_unscored`。
- **共享环境**:通用VM为 `vm/unified-20261022-complete.qcow2`,经 `prepared/runtime`
接入环境准备适配。依赖缓存、网站DNS/证书和控制器传输适配在共享环境侧维护,
Expand Down Expand Up @@ -288,7 +288,7 @@ worker 侧各段日志:
## 10. 开发闭环

```
改代码 → ruff check src tests demo → pytest →(若触碰协议)tandem check → 提交
改代码 → ruff check src tests demo → pytest →(若触碰协议)jevduo check → 提交
```

真机 smoke:
Expand All @@ -298,7 +298,7 @@ worker 侧各段日志:

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

- `tandem_eval.browser` 在 VM 内通过 loopback 依次探测 `1337` / `9222`,只调用
- `jevduo_eval.browser` 在 VM 内通过 loopback 依次探测 `1337` / `9222`,只调用
`GET /json/list` 与 `Runtime.evaluate`,不重启 Chrome、不激活 tab、不执行页面 mutation。
多 tab 时选择 `document.visibilityState=visible` 的页面。
- 任务必须已由环境以远程调试参数启动 Chrome;Task 008 的 setup 已显式启用 `1337`。
Expand All @@ -320,7 +320,7 @@ worker 侧各段日志:

## 13. 命名实验

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

Expand Down
2 changes: 1 addition & 1 deletion 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.3`。tandem_eval.recorder 是唯一写入者。
> 契约版本:`v0.3`。jevduo_eval.recorder 是唯一写入者。

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

Expand Down
2 changes: 1 addition & 1 deletion docs/STAGE_EXECUTION.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

通过 `--execution-mode stage` 启用:慢模型规划阶段,JEV/Kev 连续选择 GUI 动作,CLI 执行计划中的命令;优先使用规则验证,证据不足时调用模型 Verify,失败或状态偏离时按需重规划,最终完成仍需独立验证。默认保留原有 `step` 模式。

开发入口(相对 `src/tandem/`):
开发入口(相对 `src/jevduo/`):

- `planning/stage_planner.py`:阶段计划生成与响应校验。
- `runtime/stages.py`:里程碑进度、当前目标重新绑定及重规划。
Expand Down
6 changes: 3 additions & 3 deletions infra/config.example.json
Original file line number Diff line number Diff line change
Expand Up @@ -71,8 +71,8 @@
}
},
"eval": {
"repo_root": "/mnt/shared-storage-user/adpc-share/chenxinquan/fastslow/tandem",
"deploy_root": "/mnt/shared-storage-user/adpc-share/chenxinquan/fastslow/tandem-deploy",
"repo_root": "/mnt/shared-storage-user/adpc-share/chenxinquan/fastslow/jevduo",
"deploy_root": "/mnt/shared-storage-user/adpc-share/chenxinquan/fastslow/jevduo-deploy",
"mounts": [
{
"source": "gpfs://gpfs2/adpc-share",
Expand Down Expand Up @@ -129,7 +129,7 @@
}
},
"log": {
"results_root": "/mnt/shared-storage-user/adpc-share/chenxinquan/fastslow/tandem/rjob_logs",
"results_root": "/mnt/shared-storage-user/adpc-share/chenxinquan/fastslow/jevduo/rjob_logs",
"record": {
"a11y_full": false
}
Expand Down
Loading
Loading