# bench/ 契约(CONTRACT v0.4 落地版) 本文件是《BPU 量化轨迹工厂 设计方案 v0.4》的可执行摘要。代码与本文件冲突时,以本文件为准并修代码;本文件与设计方案冲突时,先改设计方案再改这里。 2026-09-16 按当前目标收敛:默认运行 CSV 中 ready 模型的 S100P(`nash-m`)量化、编译、上板与精度评测,并为这些模型采集真实 Agent 轨迹。新 run 必须固定一个 target:S100P=`nash-m`,S600=`nash-p`;target 只收窄本 run 的 matrix 展开,不修改旧 run 或全局默认。`collect --coverage all` 为本 run 的 oracle 模型补齐 e2e 计划:只去掉 matrix 的 priority 限制,保留任务类型、run target、backend、policy 和 k。已结束的流程和 Agent 轨迹都必须导出为数据,成功、精度未达标、预算耗尽分别标注,导出不能阻塞上板。 2026-09-16 全 338 项覆盖补充:保持原 CSV 标签和历史 run。新批次可用 `expand --model` 显式选择模型, 前置检查依据实际权重入口、构建/导出代码、评测器、校准、数据与附加门;新增 Ultralytics 任务还必须有真实 checkpoint/ONNX/指标对照证据,缺项即拒绝入队。具名批次只放宽 priority/task/status 选择,保留原 march、 backend、policy、k 和精度门。任务快照记录 admission 来源,不能把 admission 或 probe 等同于编译/上板通过。 `collect --first-pass` 每个 job 只领取首条,重复采样仍保持 QUEUED,不改 kk、不补造轨迹。 `coverage --all-runs` 总表包含全部 CSV 行,独立列出前置阻塞、实际阶段、原始响应中的 teacher 身份和训练导出; 传统算法仍保留条目并说明 PTQ 不适用。FastSAM 的类别语义未补齐前不能入队。 Pose 须有真实导出的关键点对应证据;板端同时判定 OKS AP 与平均原图坐标偏移 ≤2px。 对应由同图人框 IoU≥0.5 一对一匹配确定,统计全部17点,保留未匹配记录;无匹配或缺证据为 UNVERIFIED。 ## 0. 三条原则 1. **Agent 独立完成任务。** GLM-5.3 可直接领取 e2e,自行调用输入准备、量化、编译和上板工具;`bench run` 可选地预热 01–03 缓存。harness 分配资源、核验本次 HBM 的实测精度并保存轨迹。完整 Oracle 仅用显式 `bench run --oracle` 作历史对照或排查,不参与 Agent 执行、成功判定、奖励或 SFT 筛选。 2. **agent 只有一个可写区。** `rollouts//workspace/`。`job.json`、`harness/eval/`、`data/`、`cache/` 全部只读。agent 说什么不算数,verdict 才算数。 3. **Append-only。** `run_id` 冻结;换工具链、改配置、修 bug 都开新 run。`manifest.json` 记两套 venv 的 `pip freeze` sha256,job 启动前比对,不一致拒跑。状态只在 `state/jobs.sqlite`,文件系统只存内容。 ## 1. 目录 ``` bench/ ├── CONTRACT.md README.md config.yaml requirements.txt ├── bin/bench # CLI 入口 ├── registry/ # 输入 · 不可变 · git 管理 │ ├── models.csv matrix.yaml gates.yaml budgets.yaml datasets.yaml boards.yaml ├── data/ # 只读 · agent 永不下载 │ ├── pool/// # 全量 + manifest.json │ ├── t1//.tar # smoke 子集,单包 │ └── calib/// # npy,与 val 零交集 ├── cache/{weights,onnx}// cache/baseline/--/ ├── harness/ # L1 + L3 │ ├── pipeline.py scheduler.py watchdog.py registry.py db.py errors.py gates.py │ ├── stages/ backends/{ptq,qat}.py eval/ ├── agent/ # L2 pi 配置 │ ├── SYSTEM.md settings.json.tmpl models.json.tmpl prompts/ extensions/ ├── export/{to_agentrl,redact,reward}.py ├── scripts/ # 一次性:入池、Excel 转换、环境修补、板卡探测 ├── state/jobs.sqlite reports/ datasets// └── runs// ├── manifest.json └── / ├── job.json # 只读 · 输入契约 ├── oracle/stages/-/{stdout.log,stderr.log,exit_code,meta.json} ├── oracle/artifacts/.{onnx,bc,hbm} ├── oracle/result.json └── rollouts//{workspace/, agent/{session.jsonl,events.jsonl}, claim.json, verdict.json} ``` ## 2. 命名 | 标识 | 格式 | 示例 | |---|---|---| | run_id | `r-` | `r20260914-01` | | job_id | `--------` | `det--yolov8n--nash-e--ptq--int8` | | task | 10 类固定 | `cls det seg iseg pose mde stereo flow feat occ` | | march | `nash-e / nash-m / nash-p` | s100→e · s100p→m · s600→p | | qcfg | 段内 `a-z0-9.` | `int8` · `fp16int8` | | rollout | `/rollouts/` | `…/rollouts/03` | | stage | `-` | `01-fetch 02-baseline 03-export 04-calibrate 05-compile 06-hbm 07-board 08-eval` | | dataset_id | `ds-` | `ds20260914-01` | 段内字符集 `[a-z0-9.]`,段间 `--`。job_id 既是目录名也是 join key。 ## 3. 状态机 **job 输入准备**:`PENDING → ORACLE_RUNNING → PREPARED | FAIL | UNVERIFIED`(沿用现有运行态名称)。 `PREPARED` 只表示 01–03 成功,写 `oracle/preparation.json`,不产生 Oracle verdict,也不代表适配或精度通过。显式 `--oracle` 可从 PENDING/PREPARED 跑完整 01–08,写 `oracle/result.json`,终态仍为 PASS/FAIL/UNVERIFIED。默认准备命令不覆盖已结束任务。 **rollout(由实际核验结果决定)**:`QUEUED → RUNNING → VERIFYING → PASS | FAIL | BLOCKED | UNVERIFIED` Agent 执行是否结束/超预算独立记录在 `verdict.execution_terminal`、`timeout_reason`,不再用 `TIMEOUT` 覆盖已经核验的结果。`completion` 分别记录编译、HBM、真实上板、精度评测是否完成及精度是否达标。预算用尽但必选门已通过仍为 PASS;没做到的阶段为未完成,不凭预算耗尽推断模型失败。旧 TIMEOUT 可用 `bench verify` 按原 job 门槛重核,无需重编。 - PASS = 必选门全部 pass。 - 门无法判定(数据缺、板未接)→ 该门 `unverified`,job `UNVERIFIED`。 - `na`(本轮设计上不评)≠ `unverified`(本该评没评成)。na 不阻塞 PASS。 - BLOCKED 记录 Agent 的阻塞报告和本次实测。失败日志不能证明任务不可解,`blocked_correct` 不作推断;不进入成功 SFT 或奖励学习候选。 ## 4. 四道门 | 门 | 必选 | 判定 | |---|---|---| | G1 compile | 是 | .hbm 存在;`hb_model_info` 的 march / 输入 dtype / layout 与 job.json 一致;`hb_verifier` 通过;日志无 ERROR | | G2 numeric | 否 | 校准外样本逐输出余弦用于诊断,记录 min;编译一致性由 G1 单独核验 | | G3 task | 是 | 同一 T1、同一预处理和评测器,板卡 HBM 真实输出相对 FP32 的任务指标劣化 ≤ 5%,改善通过;`rel_pct`,不放宽阈值;T1 上记 `pass-screen`,T2 上才 `pass` | | G4 perf | 否 | 仅 job.json 有 `latency_budget_ms` 才判;mean 与 p95 分开存 | 07-board 记录性能,08-eval 用板卡输出计算任务精度;两者按 job 的 march 领取兼容的空闲板,每块物理板共用一个跨进程锁,凭证只进入这两个受信任阶段的子进程。两个阶段可分别领取同 march 的不同板,实际板名和槽位写入阶段证据。没有兼容板卡时 G3 为 unverified,不回退模拟器冒充上板。 旧 job 的板卡字段为空时按 march 查询当前注册板卡;非空但 march 不匹配则报错。`board-backfill` 复用已有 HBM,补缺失的性能和板端精度,不重编。 新 job 使用新门槛,历史 job 仍按冻结的门槛重判。评测器 0.5 保持 0.4 的 FP32 预处理与指标公式,允许复用其基线;实测文件另记执行版本、输出来源和 HBM SHA256。 ## 5. 数据三档 | 档 | 用途 | 规模 | |---|---|---| | T0 calib | PTQ 校准 | 128–512,train 抽,与 val 零交集 | | T1 smoke | 默认门 | cls 2000 · det/iseg/pose 1000 · seg 500 · 其余全量 | | T2 full | 交付数 | 完整 val,开新 run | 复制入池,不软链;`chmod -R a-w`;`manifest.json` 记 sha256/数量/来源/日期。T1 打成单 tar 避开 JuiceFS 小文件。 ## 6. 调度与看门狗 - 池:`gpu 4 · cpu 24 · agent 12`;board 容量来自 `registry/boards.yaml` 中启用的实际板卡数量。不同板可并行,同一板严格串行带锁。 - 板卡登记使用固定且唯一的 `slot`,对应 `board-.lock`;现有板保留 slot 0 以兼容在途旧进程。新增板使用新槽位,删除/禁用板卡后不复用槽位;重复接入同一地址不能增加容量。只把实际独立、运行库兼容的物理板加入池。新增/禁用板卡是调度资源变更,不重写冻结的 job 或已生成 HBM。新调度进程等待时重读板卡登记;旧进程仍需自然收尾后更换。 - 新 run 的任务指纹不包含板卡设备列表,但仍包含 march 映射与其他 registry 内容。旧 run 扩板前把原始 `boards.yaml` 保存为 `board_registry.initial.yaml`;续跑时用该快照验证旧整体指纹,证明除板卡设备列表外的输入未变,不能跳过模型、数据、门槛、工具链校验。 - **没有固定超时。** STALLED = 日志 `stall_s`(900 s)不增长 且 进程树 CPU < 5%。硬上限 24 h 只是保险。 - 板端 RPC 的原有单次 3600 秒上限由独立 `board_guard` 在板上执行;SSH stdin 租约每 5 秒刷新,断连或 30 秒失联回收本次进程组。守护进程不加载模型,避免原生运行库阻塞清理。板端互斥锁由守护进程和推理子进程共同持有,未清空不能交给新推理。租约存活日志与样本/迭代进度分开记录,不能把心跳当作推理进展。主机阶段锁只代表调度占用,不能代替板端进程核验。 - 重阶段(compile / board / eval)由 harness 执行。agent 走 `bench stage run` / `bench stage wait`,不在 bash 里跑 hb_compile。 - rollout 预算 = turns + tokens;墙钟 12 h 仅防挂死。 - Agent 动态领取任务:先覆盖尚无完整轨迹的不同模型,同等覆盖下优先预计耗时较短的模型,再做重复采样;同一 job 同时最多一条 Agent 轨迹。每次有空位都重新读取队列,`collect --watch` 等待输入准备和在途任务,避免新完成的模型一直排在旧批次后面。 - 同一 run 只运行一个新 collector;任务领取原子化。SIGTERM 或 `state/drain-collect-` 停止领取,已开始的任务自然收尾。导出在独立线程刷新,不占 Agent 名额。 ## 7. 重试与轨迹边界 | 层 | 谁 | 触发 | 轨迹 | |---|---|---|---| | oracle 阶段 | harness | 瞬态 error_class | 不是轨迹 | | rollout 内 | agent | 自己改配置重提 | 同一条轨迹 | | 新 rollout | harness | matrix k | 全新轨迹,永不串联 | | 历史 repair | 不再生成或领取 | 保留既有编号和结果 | 有 Oracle 现场的修复案例,仅保留分析用途 | 显式扩大已有 run 的 Agent 覆盖时,仅追加缺少的计划和范围说明 annotation;编号接在该 job 的最大 kk 之后,重复执行不重复添加。冻结的 job、已执行轨迹、oracle 结果及评测门槛不变。确定性 oracle 的 PASS 不代表该模型已有 Agent 训练轨迹。 **agent 的读写边界(path-guard,2026-09-15 起为读白名单)**:agent 的 cwd 是 `/rollouts//workspace/`,只能写这里(与 `/tmp`)。 可读:workspace、本 rollout 根(`agent/ stages/ handles/ rollout.json`)、`/job.json`、`/data`、`bench/data`、`bench/cache`、`bench/bin`、`.horizon/`、`AGENTS.md`、本 rollout 在 work_root 下的编译工作目录;repair 额外可读 `/oracle/`。 项目树内其余一律拒——**别的 rollout**(GRPO 组内独立性)、e2e 的 `oracle/`、`harness/`、`state/`、`export/`、别的 job;项目树外拒 `~/.pi`、`~/toolchains`、`bench/.env.local`、`state/` 与 work_root 的真实路径。 bash 里 `cd/pushd/popd` 一律拒(唯一例外 `cd <自己的 workspace>`,换行后的 cd 也算——`^` 要带 `m`);命令替换 `$(…)`/反引号、`$IFS`、路径里的 `$VAR/` 一律拒(都是把路径藏起来躲过 token 扫描的手段);剩下像路径的 token 逐个判(glob 取前缀、相对路径按 cwd 解析)。**每个 token 判两次:原路径与 realpath,两次都过才放行**——否则 workspace 里 `ln -s ../../../oracle o` 再 `cat o/result.json` 就绕过去了(read 工具也一样)。`$HOME` 下默认全拒(`~/.pi`、`~/toolchains`、bench-state、bench-work 都在那儿),只放行 ALLOW_EXTRA 与白名单目录的真实路径。 **但 guard 只是教学层,不是防线。** 解析 shell 字符串的白名单每一轮都还能找到新绕法(v3 就被换行 cd、`$IFS`、`$VAR/` 拼接、workspace 内软链四种手法穿透)。真正的隔离是 `scripts/agent_jail.sh`:`unshare -rm` 起 mount namespace,把 `/oracle`(e2e)、所有兄弟 rollout、`~/.pi`、`.env.local` 用空目录/`/dev/null` bind 掉,进程根本看不见。非 root 可用,不影响 `bench stage run` detach 出去的子进程读写 work_root/state。rollout.py 起 pi 时包这一层。 判定核心 `agent/extensions/guard-core.js` 有单测(`node agent/extensions/guard-core.test.js`),真机自检 `scripts/guard_smoke.sh`。每次拒绝记 `agent/guard.log`。 改了 SYSTEM.md / prompts / extensions 就 `agent/VERSION` +1(当前 6),rollout.json 记 `agent_config_version`,导出按版本筛。 ## 8. error_class `unsupported_op shape_infer export_fail calib_nan verifier_mismatch`(确定性,不重试) `oom board_offline board_busy stalled`(瞬态,前三者重试 ≤ 2,stalled 重试 ≤ 1) `unknown`(进人工分类队列) ## 9. reward(v0.6,离线算,配方版本化) ``` r = 1.0[G1] + 1.0[G2] + 2.0[G3] r −= 0.5·turns/max_turns + 0.5·tokens/max_tokens r −= 2.0[claim ≠ verdict] TIMEOUT: −1.0;BLOCKED 无特殊奖惩,仍保存本次真实阶段得分 G3 = na 时其 2.0 权重按比例分给 G1/G2 板卡不可用(G3 unverified 且最后一次 07-board/08-eval 为 board_offline):G2/G3 权重取 0,G1 保持 1.0 不加分, 免 TIMEOUT 罚分,reward 输出带 unverifiable="board_offline"(v0.4,2026-09-16) ``` 板卡不可用的轨迹在导出器里仍按 UNVERIFIED 排除在 RL/SFT 候选之外;回收它们的办法是 `bench board-backfill --run R --rollout JOB:KK` 用其现成 HBM 补跑 07/08 再 verify,而不是改分。 不再计算相对 Oracle 的精度或延时奖励。G3 仍比较同一评测集上的 FP32 与本次 INT8,沿用任务冻结的门槛。 TIMEOUT 扣分根据执行终止原因独立相加,已完成的 G1/G2/G3 成果照常得分,不再整条清零。 ## 10. 两套 venv | backend | venv | 关键版本 | |---|---|---| | ptq | `~/toolchains/oe-3.7.0/venv` | hbdk4 4.7.5 · horizon_tc_ui 3.5.3 · hmct 2.6.5 | | qat | `~/toolchains/oellm2/venv` | hbdk4 4.12.3a2 · horizon_plugin_pytorch 3.3.5 | harness 按 backend 选解释器。**禁止把 backend 判断交给 agent。** ## 11. 下游边界 `~/data_collect` 零耦合。只搬清洗规则 R1–R8 与 redact,落在 `export/`,不 import。 数据默认按 `purpose=all` 保留已结束的成功、失败及部分轨迹;SFT 是其中的用途筛选,不能代表全部数据量。Agent 的 `teacher.jsonl` / `student.jsonl` 只含真实对话、工具调用和观测,缺失内容不得编造。`pipeline.jsonl` 保留确定性流程的实际输入、阶段动作与测量,明确标记其来源,不能计成模型生成的 Agent 轨迹。每个 run 使用同一导出目录,显式刷新,按稳定 ID 去重;导出失败报错并可补导,不回滚已完成任务。 `bench.verdict/3` 不读取 Oracle;旧判定在导出时只读重核,源 verdict、数据库、消息和产物不改。SFT 候选要求本次实测 PASS、声明一致、完整对话和工具定义,并保留污染注释与版本过滤。Oracle FAIL 不再触发待复核;历史 repair 保留原模式,仅供分析。导出是候选数据,仍需训练端分组、去重和独立评测。 ## 12. 协作规则(2026-09-15 起,两个会话同时改一棵树踩过一次) - **只有一个写者能改一层。** 分层:`harness/`(oracle 流水线、阶段、门、调度)· `agent/`(pi 配置、扩展、提示词)· `export/`(清洗、脱敏、reward)· `registry/`(清单与阈值,改了就是新 run)· `scripts/`。谁在改哪层写进下面的表;别的会话对那层只读。 - **改动只发生在本地副本,机器上不直接改代码。** 流程:改 → `git commit`(`scripts/sync.sh` 会自动提交)→ `scripts/sync.sh` 推送。sync 带守卫:远端自上次推送后被动过就拒绝,先合并再推。 - `registry/models.csv` 是在机器上由 `excel_to_models.py` 生成的,方向反过来:`scripts/sync.sh --pull`。 - 机器上的 `runs/ state/ data/ cache/ datasets/` 是数据,不同步、不手改;改判走 `bench rejudge`,补测走 `bench board-backfill`。 - 正在跑的调度进程(`bench run` / `bench collect`)加载的是启动时的代码;改了 harness 只对新进程生效,子进程工具(`harness.tools.*`、`harness.eval.run`)立刻生效——改评测口径必须同时升 `EVALUATOR_VERSION`。**换代必须 `bench drain` 等它跑完再起新进程,只 sync 文件不算换代**(踩过:一个调度进程跑了 13 小时的旧代码)。 | 层 | 当前写者 | |---|---| | harness/ agent/ export/ scripts/ registry/ | 本会话(Cowork · bench 主线) | | 其他会话 | 只读;发现问题写成 issue 贴过来,不直接改 | ## v5 隔离修订(优先于上文旧实现描述) 工具层仍只允许 workspace 写入;底层 jail 额外允许 handles 票据与私有 /tmp。 阶段执行移到 namespace 外,只信任外部生成的 stages/artifacts/verdict;客户端不 import harness。 本 job 输入、本 rollout(除 workspace/handles)、data/cache/bin/.horizon 与本 rollout work_root 均只读。 state(包括真实路径)、harness/export/registry/config/.env.local、其他 job/run/rollout 与其他 work_root 全部隐藏。 repair 仅额外保留本 job oracle 只读。使用 PID namespace 和 capability drop,避免 /proc/宿主进程及 remount 绕过。 ~/.pi 仍可读凭证;这是已有结构性限制。jail 不可用时拒绝启动,不能静默退回 guard。 预算采用 max_turns 硬上限,无 grace turns;成本依据本条 rollout.json 的预算。