# 任务制作规范 本规范是写题人(人或 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/ --trusted-local --output runs/dev` | 合同字段、文件数与大小、符号链接、隐藏判据用到却未公开的接口名(仓库测试对 `tasks/` 全部任务执行);样例在本机的预期结果。可信本地模式只跑仓库内可信样例,不能授权正式采样 | | 2 正式校准 | 在 36:`python3 -m rollout calibrate tasks/ --image IMAGE --output runs/` | 每类样例在固定镜像、新工作区、隔离评分容器里各跑 5 次;任何不一致、UNVERIFIED/INFRA_ERROR 或清理未知都不准入 | | 3 真实试采 | `python3 -m rollout.pi_run tasks/ --image IMAGE --credential-file PRIVATE_CREDENTIAL_FILE --calibration CALIBRATION_PATH --output runs/` | 工具反馈、独立评分、候选冻结、证据对账与清理在本题能闭环;Agent 解题失败不否决任务 | | 4 难度分池 | 同一配置每题采样 ≥5 次,`python3 -m rollout.report runs/ --tasks tasks --output …` | 决定进回归集、主采集池还是返工(§9) | `IMAGE` 写固定 digest,`PRIVATE_CREDENTIAL_FILE` 是 host 私有文件路径,不能填密钥值。完整批量命令见 [README](../README.md#导入-bos-qiao-任务与批量采集)。 ## 1. 任务包合同 [机检] ```text tasks// ├── spec.md 作者规格(模板填写),可含根因与答案,不进入 Agent ├── task.json 可执行合同 ├── prompt.md Agent 可见题面 ├── template/ 完整初态工作区,全部复制给 Agent ├── gold/ noop/ cheat/ [其他样例目录] 只含 candidate_files ├── verify.py 受保护判据入口 ├── 私有测试或数据,仅评分侧可读 └── 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`。目标文件超过 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 正式后端属于平台工作,不计入单题。