Rewrite task-authoring.md as one spec (four source routes, exclusions, prompt/grader/fixture rules, four gates, difficulty pools), add the brief that gives Codex the machines, storage layout, data map, commands and red lines, and record the Bos-qiao raw-data audit. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
19 KiB
任务制作规范
本规范是写题人(人或 Agent)与 rollout 平台之间的契约:一道题按它交付,通过四道闸门,才能进入采集。它合并了三处已验证的经验:Bos-qiao 写题契约(/mnt/data/ming01.wang/Bos-qiao/agent_sft_pipeline/TASK_SPEC.md)的判据准则、Terminal-Universe 的轨迹回放规则,以及本项目 M0/M1 的实测教训。作者填写 任务规格模板;可执行参考是 frame-decoder(手写 C 题)与 S500_n2_155(Bos 导入题)。本规范只管制题与准入,不涉及模型训练。
每条规则标注检查方式:[机检] 由命令自动拒绝;[校准] 由正负例重复运行暴露;[评审] 只能由未制作该题的人核对。机检通过不代表评审项已满足。
0. 流程与四道闸门
选来源 → 准入预筛(§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。
1. 任务包合同 [机检]
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 的规则:
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 以 UID 65534 原样运行check.py,最后一行为PASS且退出 0 才判 PASS,失败子进程的 stderr 尾部只进私有grade.stderr。 - [机检] 公开合同检查:隐藏判据从候选 Python 模块导入或以
模块.名字(含import … as)访问的名字,必须出现在 prompt 或 template 中,否则拒绝导入。 - Bos 题声明的 python、rlenv 镜像 digest 在 36 上已不存在,统一换成本项目固定 runtime 后完整重新校准;Bos 历史准入与教师结果不沿用。
- 暂不导入:
check.py递归收集工作区全部*.py的 rglob 型任务(本合同只冻结声明文件,照搬会把合法拆分判 FAIL),以及 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。
- 平台纯度(替身测试):把外设换成软件替身(PTY、合成数据序列、桩回调)后,原问题还会复现吗?
- 会复现 → 软件题,可做。例:串口回显题跑在 Linux PTY 上是纯软件题。
- 不复现,必须有真硬件才能判 → 板端题,只登记,暂不制作。
- 说不清,或者软件逻辑和硬件状态要同时在场才成立 → 丢弃。具体包括:判据既要跑 BPU 推理又要查源码;“板上编译、服务器验证”这类跨机器流程;成败取决于真实时序或电气特性;外设状态不可控、不可重置。
- 不可判:没有确定的可观察行为(“分析一下这段代码”“解释原理”),或正确性只能靠主观评价。
- 材料缺失:初态、输入、依赖或通过标准任一缺失,且不能按 §2 的规则补全;不把遗漏材料算作 Agent 能力。
- 授权或隐私不明:来源不能确认可用,或个人信息无法脱敏。
- 重复:同一根因只改问法、参数或语言的变体不计新题;变体必须真的改变解题路径(多文件、多一层间接、换失败模式、要先复现才能定位)。
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 教训:题面写了绝对路径,模型就去自己留下的残留目录构建,整组作废。 - [机检+评审] 判据要考的每个约定都必须公开:接口名与签名、字段、默认值、边界、单位、误差、异常类型与退出码,以及“不得修改输入”之类的行为约束。机检只覆盖 Python 模块的属性和导入名,其余由评审对照验收矩阵逐项核对。S500_n3_152 v1 的隐藏测试调用了未公开的
process(request),两个模型都因此 FAIL;v2 公开该接口后通过,v1 结果不作为能力信号。 - [评审] 判据不能考比题面更严的要求;隐藏测试可以隐藏输入组合,不能隐藏正确行为。
- [评审] 描述问题而不是解法,并说明如何自测。导入题由导入器自动在末尾追加“最终只提交并评分以下文件”。
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 映射到上表。设计准则:
- [评审] 只看最终候选。 需要构建或运行时,把候选拷到
/tmp的干净目录重新构建,不复用build/、install/、__pycache__等中间产物。Bos 教训:判据在 Agent 留下的install/上构建,8 次正确修复全判 0。这类错误校准查不出来,只有真实试采会暴露。 - [评审] 不信候选自述。 独立复算期望值并要求完全相等;或用判据控制的桩记录调用次数、顺序和参数;或要求输出判据运行时才生成的随机 nonce,使硬编码失效。
- [评审] 期望值只来自题面写明的值或随题提供的输入数据,不能拿未完成或参考实现的运行结果当答案。
- [校准] 确定性。 随机用例固定种子;不依赖网络、真实时间、外部服务或机器负载;同一候选 5 次结果必须一致。
- [评审] 覆盖。 正常路径、边界值(阈值相等、空、长度 0/1、最大值)、分片与乱序、非法输入(明确要求的异常或退出码)、大数据量,以及保持原有正确行为的回归项。
- [评审] 不跳过。 缺能力报 UNVERIFIED,不能 skip 后给 PASS;单项超时留足余量,避免正确解因主机负载判 FAIL。
- [评审] 不因多出文件判错。 Agent 留下额外文件是正常的,只检查关心的目标。
- [校准] 隔离。 判据以 root 读取
/grader,候选和编译器降为 UID 65534;运行前探测候选读不到verify.py,否则 UNVERIFIED。换任务不能省掉这条边界。
7. 样例与校准
| 样例 | 预期 | 要求 |
|---|---|---|
| gold | PASS | 满足全部需求;只是正确实现之一,不能成为唯一标准 |
| template | FAIL | 原样初态,复现目标缺陷 |
| noop | FAIL | 未实现核心功能(如直接退出 0) |
| cheat | FAIL | 最省事的糊弄:硬编码公开例子、打印期望字符串、用累计均值冒充滑窗、整数除法抹掉小数等 |
cheat_*(可选) |
FAIL | 每个对应判据里的一条拦截机制 |
valid_*(建议) |
PASS | 风格或算法不同的合法解,证明判据不只认一个补丁 |
- [评审] 写 cheat 时问自己“最省事的糊弄办法是什么”,并确认判据靠哪一条抓住它。
- [校准] 正式校准每类样例各跑 5 次(默认四类共 20 次):预期 PASS 的必须 PASS,负例必须 FAIL,整体 PASS 且 cleanup confirmed。
8. 环境与镜像
- 镜像按环境族做,不按题做;同一镜像既跑 Agent 也跑评分。当前正式族是 C/Python runtime(trace5 digest,见 README)。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 正式后端属于平台工作,不计入单题。