data-gen-ebd/docs/task-authoring.md
amos 293c2c7a8e docs: task-making spec, Codex factory brief and storage layout
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>
2026-10-14 15:22:36 +08:00

19 KiB
Raw Blame History

任务制作规范

本规范是写题人(人或 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。

  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 教训:题面写了绝对路径,模型就去自己留下的残留目录构建,整组作废。
  • [机检+评审] 判据要考的每个约定都必须公开:接口名与签名、字段、默认值、边界、单位、误差、异常类型与退出码,以及“不得修改输入”之类的行为约束。机检只覆盖 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 映射到上表。设计准则:

  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。换任务不能省掉这条边界。

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 正式后端属于平台工作,不计入单题。