data-gen-ebd/docs/task-authoring.md
amos dd69720c15 Let Bos fixture scripts rewrite a target; the last write wins
The fixture grammar is straight-line heredocs with no branches, so a script that
writes the same target twice has a well-defined result: its last write. 55
rglob-type environments in batch 16 were refused only because their no-op
fixture writes a module twice.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 11:40:08 +08:00

210 lines
23 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 任务制作规范
本规范是写题人(人或 Agent)与 rollout 平台之间的契约:一道题按它交付,通过四道闸门,才能进入采集。它合并了三处已验证的经验:Bos-qiao 写题契约(`/mnt/data/ming01.wang/Bos-qiao/agent_sft_pipeline/TASK_SPEC.md`)的判据准则、[Terminal-Universe](https://arxiv.org/abs/2609.04148) 的轨迹回放规则,以及本项目 M0/M1 的实测教训。作者填写 [任务规格模板](templates/task-spec.md);可执行参考是 [frame-decoder](../tasks/frame-decoder/task.json)(手写 C 题)与 [S500_n2_155](../tasks/S500_n2_155/task.json)(Bos 导入题)。本规范只管制题与准入,不涉及模型训练。
每条规则标注检查方式:**[机检]** 由命令自动拒绝;**[校准]** 由正负例重复运行暴露;**[评审]** 只能由未制作该题的人核对。机检通过不代表评审项已满足。
## 0. 流程与四道闸门
```text
选来源 → 准入预筛(§3) → 造初态(§4) → 写题面(§5) → 写判据(§6) → 写样例(§7)
→ 闸门1 合同与本地自测 → 闸门2 正式校准 → 闸门3 真实试采 → 闸门4 难度分池 → 登记(§10)
```
| 闸门 | 命令(项目根目录) | 拦下什么 |
| --- | --- | --- |
| 1 合同与本地自测 | `python3 -m unittest discover -s tests`;`python3 -m rollout calibrate tasks/<id> --trusted-local --output runs/dev` | 合同字段、文件数与大小、符号链接、隐藏判据用到却未公开的接口名(仓库测试对 `tasks/` 全部任务执行);样例在本机的预期结果。可信本地模式只跑仓库内可信样例,不能授权正式采样 |
| 2 正式校准 | 在 36:`python3 -m rollout calibrate tasks/<id> --image IMAGE --output runs/<batch>` | 每类样例在固定镜像、新工作区、隔离评分容器里各跑 5 次;任何不一致、UNVERIFIED/INFRA_ERROR 或清理未知都不准入 |
| 3 真实试采 | `python3 -m rollout.pi_run tasks/<id> --image IMAGE --credential-file PRIVATE_CREDENTIAL_FILE --calibration CALIBRATION_PATH --output runs/<batch>` | 工具反馈、独立评分、候选冻结、证据对账与清理在本题能闭环;Agent 解题失败不否决任务 |
| 4 难度分池 | 同一配置每题采样 ≥5 次,`python3 -m rollout.report runs/<batch> --tasks tasks --output …` | 决定进回归集、主采集池还是返工(§9) |
`IMAGE` 写固定 digest,`PRIVATE_CREDENTIAL_FILE` 是 host 私有文件路径,不能填密钥值。完整批量命令见 [README](../README.md#导入-bos-qiao-任务与批量采集)。
## 1. 任务包合同 [机检]
```text
tasks/<task-id>/
├── spec.md 作者规格(模板填写),可含根因与答案,不进入 Agent
├── task.json 可执行合同
├── prompt.md Agent 可见题面
├── template/ 完整初态工作区,全部复制给 Agent
├── gold/ noop/ cheat/ [其他样例目录] 只含 candidate_files
├── verify.py 受保护判据入口
├── <grader_files> 私有测试或数据,仅评分侧可读
└── dataset.json 可选:argv 参考快照,见 data-format.md
```
[load_task](../rollout/core.py) 的规则:
- `id/version/family/source` 为非空字符串;`template` 必须为 `template`,`verifier` 必须为 `verify.py`。
- `candidate_files` 为 1–16 个不重复的安全相对路径,必须存在于 template 和每个非 template 样例目录;Agent 结束后只冻结并评分这些文件。
- template 为 1–64 个常规文件;`fixtures` 可选,最多 12 类且必须保留 gold=PASS、template/noop/cheat=FAIL;`grader_files` 最多 16 个,不能与样例目录或保留文件重名。
- `timeout_seconds` 为 1–300 的整数,约束一次评分;Agent 期限由 controller 另设。
- 不得有符号链接,单文件不超过 1 MiB。task digest 覆盖 task.json、prompt.md、verify.py、私有附件、template 和全部样例;改其中任何文件都是新身份,必须重新校准。
其他字段(如导入题的 `bos`)只作记录,没有执行含义。spec.md 与外部输入不进入 digest。
## 2. 四条来源路线
先选路线再动手,不同路线的初态来源和可信度不同,规格里必须写明。
| 路线 | 来源 | 初态从哪来 | 当前可用量(2026-10-13 实测) |
| --- | --- | --- | --- |
| A 导入成熟任务 | Bos-qiao `envs/S500_*` | 原 template 原样搬入 | 已导入 20;direct 题另有 71 道候选(尚未逐题导入);81 道 rglob 型、5 道 ROS2 等待合同或镜像;318 道支撑题未盘点 |
| B 轨迹回放 | 有完整工具参数与结果的原始会话 | 回放会话里的文件观察 | BOS `rdk-gateway/v2-spans` 2,408 个会话中 263 个可回放,中位 1 个文件,八成在板端;`data-litellm-1.0` 未全量扫描、未授权 |
| C 种子/素材写题 | Bos B 级种子 3,060 条、HWE 材料 | 新写,标记原创 | 种子与材料只给需求方向,判据和样例全部新写 |
| D 工程问题与开源修复 | 团队工单、修复记录、开源 issue/PR | 冻结修复前版本 | 逐题收集 |
### 2.1 路线 A:导入 Bos-qiao 任务
`python3 -m rollout.bos_import BOS_ENV --output tasks/ENV_ID --family FAMILY`,一次一题;批量时用 shell 循环逐题调用并保存每题的通过或拒绝原因,不做通配导入。
- [机检] `final_targets` → `candidate_files`,必须在 template 中。样例脚本只解析不执行:允许 `set -e(u)`、`mkdir -p`、带引号 heredoc 的 `cat >`,以及 `python3 -B -` 中的字面量 `Path(...).write_text(...)` 或工厂固定的 `files` 循环;其他命令或写非目标文件即拒绝;脚本没有分支,同一文件写多次以最后一次为准。
- [机检] `gold.sh` → gold;`valid_*.sh` → 同名 PASS 样例;`cheat_exit_zero.sh` → noop;第一个其他 cheat → cheat,其余保留原名为 FAIL 样例;映射写入 `bos.fixture_scripts`。
- [机检] 根目录全部 `*.py`(至少 `check.py`)作为私有 `grader_files`;统一的 [verify.py](../rollout/bos_verify.py) 以 root 原样运行 `check.py`,check 启动的子进程降为 UID 65534,最后一行为 `PASS` 且退出 0 才判 PASS,失败子进程的 stderr 尾部只进私有 `grade.stderr`。根目录还有 `check.py` 以外的 `*.py`(工厂的 tests.py 会和候选在同一进程运行)时,导入器加私有 `isolation-blocked.txt`,评分恒为 UNVERIFIED,需按 §6 第 8 条重写判据、去掉标记并加 `cheat_read_grader` 后以新版本准入。
- [机检] 公开合同检查:隐藏判据从候选 Python 模块导入或以 `模块.名字`(含 `import … as`)访问的名字,必须出现在 prompt 或 template 中,否则拒绝导入。
- Bos 题声明的 python、rlenv 镜像 digest 在 36 上已不存在,统一换成本项目固定 runtime 后完整重新校准;Bos 历史准入与教师结果不沿用。
- rglob 型任务(`check.py` 递归收集工作区全部 `*.py`):平台只冻结声明的 `candidate_files`,照搬会把合法拆分判 FAIL。用户 2026-10-26 要扩题量,改为导入后重写:判据只读取声明文件(gold 需要的非目标文件作为私有判据数据提供),README 写明"只交付并评分这些文件,新增文件不会被收集",记入 spec.md,`version` 加 1;判据同时按 §6 第 8 条改过隔离的,照该条加 `cheat_read_grader`。gold 或其他样例写出目标以外的新模块(导入器报 non-target)时,手工建包:把这些文件并入 `candidate_files`,template 放同名空文件,README 列出全部交付文件,各样例的文件仍只解析脚本、不执行,未写到的文件取 template 版本,建包后须过 `core.load_task` 和两道闸门。目标文件超过 16 个或 template 超过 64 个文件的仍不导入。
- 暂不导入:ROS2 Jazzy 任务(等镜像)。
### 2.2 路线 B:轨迹回放
只用保存了完整工具参数和工具结果的原始数据。flat-logs 只有预览、hermes 只有结果而没有参数,均不能回放;派生的 rebuilt_sessions 只覆盖约七成会话,不作回放来源。
- [评审] **初态**=每个路径在第一次被修改之前、最早一次完整读取到的内容。Agent 自己新建的文件不进初态。带 offset/limit 的读取、`head`/`sed -n`、被截断的输出、后来被清空或改写的观察都作废。
- [评审] 只用同一会话里的工具调用与对应返回作证据;不能用助手的推测、相似会话或常识补写文件内容。
- [评审] **补全**只允许加让工作区能构建运行的支撑材料(构建文件、依赖桩、固定输入);不得实现需求、不得留下指向答案的注释。spec 里逐文件标注“回放”或“补全”。
- [评审] **充分性**:评审人只看工作区和题面,判断能否解题;缺关键文件即 BLOCKED,不能靠题面措辞推断完整。
- [评审] **意图还原**:题面只写用户在会话里明确提出的要求;判据要考的新增约定必须公开(§5)。
- [评审] **板端会话**(`device_*` 工具)只能还原文件,还原不了设备、驱动和运行时;必须先过 §3 的替身测试。
- [评审] **隐私**:会话来自真实用户。回放内容进入 template 前去除或参数化密码、口令、Token、SSH/网络端点、内网 IP、个人信息和用户绝对路径;无法脱敏就放弃。spec 记录来源会话 ID 与观察引用,原始会话不随任务交付。
- 回放产出低是常态:论文中终端类工作区仅靠回放只有 40.2% 判定为充分;BOS 原始数据可回放 263 个会话,此前按同一方法全量复核(`auto_task_codex/recoverable_queries_v1`)只有 18 条 query 初态充分。
### 2.3 路线 C:种子与素材写题
- 种子和素材只提供需求方向,初态、判据和样例都是新写的;`source` 写清种子 ID,规格标记“原创”,不称为现场故障。
- Bos 种子字段映射:`query`/`task_prompt` → 题面初稿(按 §5 改写);`fill` → 必须公开的约定;`recipe.initial_state`/`dependencies`/`platform` → 初态与环境族依据;`grader.checks` → 验收矩阵;`family` → 去重与配比。种子的 `training_ready` 全为 false,不代表已有环境。
- HWE 材料:`reference/` 可作 gold 起点;`checks/behavior.py` 的上板判据(如 `return rc is not None`)和 L0 静态检查不能作为成功门,必须重写为行为判据;mutation 只作同族变体,分组键为基础题 ID。
- 期望输出是固定字符串的题(如只要求打印 `second_lock=EDEADLK`),直接 printf 就能通过;判据必须加运行时随机量、隐藏输入变体或受控桩(§6)。
- 同一族共用一个判据实现,每题差异放进私有 `grader_files` 数据;先做一题建族准入,再批量。
### 2.4 路线 D:工程问题与开源修复
冻结修复前后的版本,在固定环境里复现原问题,用修复补丁作 gold,再验证至少一个不同写法的合法解;记录许可或内部授权与可保留范围。
## 3. 准入预筛:先排除,再制作 [评审]
命中任一条就不做:登记原因,标记 BLOCKED 或 REJECTED。
1. **平台纯度(替身测试)**:把外设换成软件替身(PTY、合成数据序列、桩回调)后,原问题还会复现吗?
- 会复现 → 软件题,可做。例:串口回显题跑在 Linux PTY 上是纯软件题。
- 不复现,必须有真硬件才能判 → 板端题,只登记,暂不制作。
- 说不清,或者软件逻辑和硬件状态要同时在场才成立 → 丢弃。具体包括:判据既要跑 BPU 推理又要查源码;“板上编译、服务器验证”这类跨机器流程;成败取决于真实时序或电气特性;外设状态不可控、不可重置。
2. **不可判**:没有确定的可观察行为(“分析一下这段代码”“解释原理”),或正确性只能靠主观评价。
3. **材料缺失**:初态、输入、依赖或通过标准任一缺失,且不能按 §2 的规则补全;不把遗漏材料算作 Agent 能力。
4. **授权或隐私不明**:来源不能确认可用,或个人信息无法脱敏。
5. **重复**:同一根因只改问法、参数或语言的变体不计新题;变体必须真的改变解题路径(多文件、多一层间接、换失败模式、要先复现才能定位)。
## 4. 初态 `template/`
- [机检] 包含完成任务所需的全部文件,并含全部 `candidate_files`。
- [校准] 必须复现目标缺陷:template 样例要判 FAIL。
- [评审] 不泄露答案:不放 `.git` 历史、`*.bak`/`*.orig`/`*.rej`/`*~` 备份、注释掉的正确实现或 gold 片段;未实现的功能用明确的桩(如 `raise NotImplementedError`)。
- [评审] 公开接口写在 `template/README.md` 或题面里;隐藏测试和它的输入只能放 `grader_files`。
- [评审] 依赖要么在镜像里,要么在 template 里,不能在运行时下载。
## 5. 题面 `prompt.md`
- [评审] 不写指代工作目录的绝对路径(`/workspace`、`/root`、`/home` 等),只说“当前目录”。Bos 教训:题面写了绝对路径,模型就去自己留下的残留目录构建,整组作废。
- [机检+评审] 判据考的每个行为都必须**有据可查**:依据只能来自题面(包括现象描述)、工作区材料(代码、头文件、README、随题提供的协议或数据手册片段),或公认标准(C11、POSIX、Linux UAPI、协议 RFC 等)。项目自己的约定(接口名与签名、字段、默认值、单位、误差、退出码、输出格式)必须写在题面或工作区里,不能只存在于判据。机检仍只覆盖 Python 模块的属性和导入名。S500_n3_152 v1 的隐藏测试调用了未公开的 `process(request)`,两个模型都因此 FAIL;v2 公开该接口后通过,v1 结果不作为能力信号。
- [评审] 允许现象型题面:只描述现场现象和复现方式,不逐条列出正确行为,也不指出出错位置或涉及的知识点。正确行为由工作区材料和公认标准决定。spec.md 的“判据检查项 ↔ 依据”对照表必须逐项写明依据在哪里(题面原句、`文件:行`,或标准条款)。对不上依据的检查项,要么删掉,要么把依据补进工作区。
- [评审] 判据不能考比依据更严的要求。隐藏测试可以隐藏输入组合和场景,不能隐藏正确行为。
- [评审] 描述问题而不是解法,并说明如何自测。导入题由导入器自动在末尾追加“最终只提交并评分以下文件”。
## 6. 判据
接口固定:控制器调用 `python3 -I /grader/verify.py /candidate`,stdout 只输出一行 JSON,含 `status` 和非负整数 `checks`;诊断写 stderr,正式用例和答案不能进入 Agent 可读的反馈。
| 情况 | `status` | 退出码 |
| --- | --- | --- |
| 全部必需行为通过(checks > 0) | PASS | 0 |
| 已执行检查,候选不满足要求(checks > 0) | FAIL | 1 |
| 缺依赖、隔离不成立或证据不足 | UNVERIFIED | 2 |
| 判据或执行环境故障 | INFRA_ERROR | 2 |
Bos 导入题由包装器把 `check.py` 的退出码和最后一行 `PASS` 映射到上表。设计准则:
1. **[评审] 只看最终候选。** 需要构建或运行时,把候选拷到 `/tmp` 的干净目录重新构建,不复用 `build/`、`install/`、`__pycache__` 等中间产物。Bos 教训:判据在 Agent 留下的 `install/` 上构建,8 次正确修复全判 0。这类错误校准查不出来,只有真实试采会暴露。
2. **[评审] 不信候选自述。** 独立复算期望值并要求完全相等;或用判据控制的桩记录调用次数、顺序和参数;或要求输出判据运行时才生成的随机 nonce,使硬编码失效。
3. **[评审] 期望值只来自题面、工作区材料或公认标准中有据可查的行为及随题提供的输入数据**,不能拿未完成或参考实现的运行结果当答案。
4. **[校准] 确定性。** 随机用例固定种子;不依赖网络、真实时间、外部服务或机器负载;同一候选 5 次结果必须一致。
5. **[评审] 覆盖。** 正常路径、边界值(阈值相等、空、长度 0/1、最大值)、分片与乱序、非法输入(明确要求的异常或退出码)、大数据量,以及保持原有正确行为的回归项。
6. **[评审] 不跳过。** 缺能力报 UNVERIFIED,不能 skip 后给 PASS;单项超时留足余量,避免正确解因主机负载判 FAIL。
7. **[评审] 不因多出文件判错。** Agent 留下额外文件是正常的,只检查关心的目标。
8. **[校准] 隔离。** 判据以 root 读取 `/grader`,候选和编译器降为 UID 65534;运行前探测候选读不到 `verify.py`,否则 UNVERIFIED。换任务不能省掉这条边界。候选代码只能在子进程里运行,子进程只拿输入、输出结果,期望值留在 check 进程里比对(参照 S500_n2_155);在 check 进程内 import 候选会被包装器判 UNVERIFIED,把隐藏测试或断言放进候选进程的判据无法隔离,记 BLOCKED。重写这类判据(参照 S500_n3_133、S500_n3_102、S500_a2_426889b9a968):用例生成和期望值搬进 check.py;Python 候选由 check 写出的 RUNNER 子进程 import,从 stdin 收输入,把结果按类型标记、连同异常名和“是否改了输入”等观察一起打印回来;C 候选和只打印原始观察的 harness 一起编译,桩只记录调用、不断言;所有输入文件在候选运行前写好,候选运行后 check 不再读写临时目录(root 会跟随候选放的符号链接)。
## 7. 样例与校准
| 样例 | 预期 | 要求 |
| --- | --- | --- |
| gold | PASS | 满足全部需求;只是正确实现之一,不能成为唯一标准 |
| template | FAIL | 原样初态,复现目标缺陷 |
| noop | FAIL | 未实现核心功能(如直接退出 0) |
| cheat | FAIL | 最省事的糊弄:硬编码公开例子、打印期望字符串、用累计均值冒充滑窗、整数除法抹掉小数等 |
| `cheat_*`(可选) | FAIL | 每个对应判据里的一条拦截机制 |
| `valid_*`(建议) | PASS | 风格或算法不同的合法解,证明判据不只认一个补丁 |
| `cheat_read_grader`(重写判据的 Bos 题必备) | FAIL | 读得到隐藏判据(`/grader`、`/proc/<父进程>/cwd/grader`、进程命令行里的 check.py 路径)才按 gold 行为解题,否则以 `grader unreadable` 失败。正式校准必须 FAIL;可信本地在 Linux 上没有隔离,它会读到判据而 PASS,闸门 1 在 Linux 上此样例不符合预期属正常,以正式校准为准 |
- [评审] 写 cheat 时问自己“最省事的糊弄办法是什么”,并确认判据靠哪一条抓住它。
- [校准] 正式校准每类样例各跑 5 次(默认四类共 20 次):预期 PASS 的必须 PASS,负例必须 FAIL,整体 PASS 且 cleanup confirmed。
## 8. 环境与镜像
- 镜像按**环境族**做,不按题做;同一镜像既跑 Agent 也跑评分。当前正式族是 C/Python runtime(trace5 digest,见 [README](../README.md))。aarch64 交叉编译、ROS2 等新族先用一题建族准入。
- 镜像按 digest 固定,不含判据、gold、历史归档或凭据;换镜像后全族重新校准,旧 PASS 不沿用。
- 资源:工作容器 2 GiB/1 CPU,评分容器 512 MiB/1 CPU;评分总时长受 `timeout_seconds` 约束。
## 9. 准入、试采与难度分池
审核状态是人工记录,loader 不解析:
`DRAFT → READY_FOR_CALIBRATION → CALIBRATED → APPROVED_FOR_PILOT → ADMITTED`;另有 `BLOCKED`(缺材料或能力)、`REJECTED`(无效题)、`RETIRED`(被新版本替代)。
- `ADMITTED` 需要闸门 2 通过、独立评审完成、闸门 3 试采链路闭环;不要求 Agent 解题成功。生产运行门仍由 controller 校验校准回执和固定身份,不能只凭规格里写了 ADMITTED。
- 闸门 4:用同一 task/verifier/image/模型配置,每题采样至少 5 次。
- 全部 PASS → **回归集**,不进主采集池;
- 部分 PASS → **主采集池**;
- 0 PASS → 先复核题面与判据(是否有未公开的约定、判据是否误拒合法解),确认题没问题才进主采集池。
- 失败分诊看 report 的 `fail_detail`(来自私有 `grade.stderr`)。判据或题面改动都会产生新 digest,按新版本重新校准和采样,不改写旧结果。
## 10. 登记、去重与版本
- 每题一份 spec.md,记录来源路线、来源 ID、授权、来源组与根因族、split 分组键(mutation 用基础题 ID,回放题用来源会话 ID,同源变体必须分在同一组)。
- 每批保留导入台账(每个来源条目的通过或拒绝原因)和准入记录(task digest、image、校准目录),批量 JOBS 从准入记录生成。
- 生产统计同时报:候选数、准入数、独立任务族、制作人时和淘汰原因;mutation、改写和重复采样不计独立任务。
## 11. 评审清单
- [ ] 来源路线、来源 ID、授权与隐私处理已记录;原创、历史、回放、mutation 标记准确。
- [ ] 替身测试结论为软件题;无混杂硬件依赖。
- [ ] 初态完整、复现目标缺陷,没有答案泄露;回放与补全文件逐一标注。
- [ ] 判据每个行为均有题面、工作区材料或公认标准依据;项目约定已在题面或工作区公开,“判据检查项 ↔ 依据”逐项可核对,判据不比依据更严;题面没有工作目录绝对路径。
- [ ] 现象型题面只描述症状与复现,不点出出错位置或知识点;正确行为的依据充分,不以隐藏约定制造难度。
- [ ] 判据重新构建、独立复算、确定、覆盖边界与非法输入;合法替代解可以通过。
- [ ] 每个 cheat 都有对应的拦截机制;判据、gold 与密钥对 Agent 不可见,历史归档答案不可见。
- [ ] 正式校准整体 PASS、cleanup confirmed,校准身份与采样身份一致。
- [ ] 真实试采的工具因果、独立评分、终态与清理已复核。
- [ ] 难度分池结论与依据已记录;评审人、日期与版本已签署。
## 12. 工作量
1 人日指一位熟悉该领域的工程师约 8 小时有效研发时间,不含模型和作业排队。以下是起步估算,以首批实测修正:
| 单题条件 | 作者工作量 |
| --- | --- |
| 路线 A 导入成熟任务 | 0.5–1.5 人日/题(导入、校准、来源核对、评审) |
| 路线 B 回放 / 路线 D 工程问题 | 2–4 人日/题(复现、补全、判据、样例、脱敏) |
| 路线 C 写题 | 同族后续题 2–4 人日;首次建立新任务族 4–8 人日 |
独立评审与返修另加约 20%–30%。新环境族的镜像、rglob 候选通配合同和 Salty 正式后端属于平台工作,不计入单题。