data-gen-ebd/docs/task-authoring.md
amos e524d9eda5 docs: deployment map, task authoring standard and Qwen trial record
Add the current and target deployment diagrams, the task author standard
and copyable spec template, the five-field data contract, and record the
Qwen Responses trial and pending-create cleanup fix in progress and
acceptance.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 21:06:06 +08:00

14 KiB
Raw Blame History

任务创建标准

本标准用于把已有工程问题制作成可复现、可独立判分的 rollout 任务。作者填写 任务规格模板,以 frame-decoder 为当前可执行参考。工时是规划估算,实际准入依赖证据;本标准不增加任务、不升级执行器,也不涉及模型训练。

1. 先分清规格与运行合同

作者规格回答“为什么做、输入是什么、什么才算正确、来源能否使用”。运行合同回答“控制器现在可以执行哪些文件”。两者一起评审,不能只填一个 JSON 就认为任务完整。

当前 load_task 的合同是首题 v1:

  • id/version/family/source 为非空字符串;version: "1" 是任务版本,不是通用 schema 版本字段。
  • template 必须为 template,verifier 必须为 verify.py。
  • candidate_files 必须恰好为 ["decoder.c"],评分器接收候选目录。
  • timeout_seconds 为 1–300 的整数,约束一次评分;Agent 执行期限另由 controller 设置。
  • 必须包含题面、验收器及四份 decoder.c 校准样例;所有文件不得为符号链接,每个捕获文件不超过 1 MiB。

其他字段即使可被 JSON 读取,也没有自动的构建、输入挂载或执行含义。spec.md、外部输入和其他工程文件目前不会随任务包自动提供给 Agent,也不进入当前 task digest。它们的来源、版本和摘要先在作者规格中冻结,不能冒充执行器已经核对的资产。

因此,v1 可运行的新增任务必须能在单个 decoder.c 内表达,固定输入由 verify.py 管理,公开需求写进 prompt.md。多文件工程、独立数据文件、ROS、交叉编译与仿真任务先完成合同升级,再逐题准入;不要为兼容文件名把真实工程拆成失真的代码片段。

2. 作者交付物

tasks/<task-id>/
├── spec.md                从模板填写,供作者与评审人使用
├── task.json              当前 v1 可执行合同
├── prompt.md              Agent 可见需求与公开自测说明
├── template/decoder.c     有缺陷且能复现目标问题的初态
├── gold/decoder.c         一个可信正确实现,供控制端校准
├── noop/decoder.c         未实现需求的负例
├── cheat/decoder.c        绕过/伪造结果的负例
├── dataset.json           与 task/verifier 摘要关联的可信判分目标快照
└── verify.py              受保护的正式行为验收器

这不是 Agent 容器的目录。Agent 只接收初态、题面与已准入的公开资产;spec.md 可包含根因和答案,不能整体注入 Agent,gold 与正式验收器也不得进入 Agent 镜像或其可读存储。

数据导出按 五字段合同:快照目标来自可信 verifier/gold 的独立行为校验,不从被测模型输出反推;判分向量、退出码和输入方式必须完整。dataset.json 与归档中的 dataset.jsonl 仅留在可信处理侧。首题为链路回归,主采集题另记录目标模型的重复难度测量,不能把断言数量当难度。

Salty 的 workdir 不代表挂载隔离。若 Agent 能读取整个个人盘,也可能读到 personal:/embedded-rollout 中历史归档的最终候选;独立修复采集须隔离这些答案。若业务明确允许案例检索,则单独记录检索范围与条件,不能混作独立解题;隐藏 verifier/gold 始终留在可信侧。

完整初态要包含完成需求所必需的文件、接口定义、依赖版本和固定输入。当前 v1 只有单源文件;新任务如依赖其他材料,标记 BLOCKED 并说明所需合同,不把遗漏材料算作 Agent 解题能力。

每个交付包同时需要以下内容:

内容 必须说明或提供的证据
来源与授权 项目/材料位置、原始版本、许可或内部使用授权、可保留范围;原创题写明原创,不称为现场故障
独立问题身份 来源组、根因族、与已有任务的关系;同一问题的 mutation、题面改写和重采样不计独立任务
问题与范围 可观察错误、预期行为、约束、明确不验证的硬件条件
环境 架构、工具链、依赖与实际镜像 digest;禁止运行时依赖浮动下载
构建与运行 可复制的命令 argv、工作目录、退出码、输入、输出、超时;正式 grader 调用同一公开接口
验收矩阵 每个需求对应行为断言,含正常、边界、错误恢复与回归;数值问题写误差/单位,时序问题写测量条件
正负例 gold、缺陷初态、noop、cheat 的预期结果及为何能代表所测问题
替代正确解 满足公开接口和全部行为约束即可通过,不能要求补丁等于 gold、特定变量名或固定实现风格
重置与清理 每次新工作区;进程、临时目录、端口、容器、网络的所有者和回收方式
准入记录 校准回执、评审结论、未验证项、批准的任务/verifier/image 身份与复核日期

3. 制作与准入步骤

  1. 选题与去重。 优先恢复已有成熟任务。核对完整资产、授权和根因,确定独立问题分母与任务族。缺源码、输入或通过标准的材料先补齐,不进入采样。
  2. 写规格和题面。 在规格中定义验收矩阵,题面描述可观察需求、接口和公开例子;隐藏测试可以隐藏输入组合,不能隐藏正确行为要求。题面不泄露参考补丁。
  3. 固定环境和初态。 写可复跑的构建/运行入口,用初态复现目标问题。固定依赖与镜像身份,明确软件抽象边界;构建失败题应由相应行为判定,不能靠文件文本相似度。
  4. 实现受保护验收器。 实际构建并执行候选,核对输出、退出码或业务行为。候选不可读取正式测试/预期结果;当前 Docker grader 复用 UID 降权及读取隔离探针,不能因换任务省去该边界。命令用 argv,候选和输出路径校验。
  5. 制作校准样例。 gold 全部必需检查 PASS;template 必须复现目标缺陷并 FAIL;noop 未实现功能而 FAIL;cheat 针对可预见捷径且 FAIL。增加不同合法实现或定向负例复核,避免 grader 只认一个补丁。
  6. 正式环境重复校准。 四类各在新工作区运行五次,共 20 次。每个 gold 的 verdict 为 PASS,每个负例 verdict 为 FAIL,因此校准整体 status 为 PASS。任何 UNVERIFIED/INFRA_ERROR、结果不一致或清理未知都不能准入。可信本地校准只用于开发,不能授权 Docker 正式采样。
  7. 独立评审与试采。 评审题面与断言一致性、误拒正确解、负例绕过、来源去重、隔离和证据。准入后做一次真实 Pi 尝试,验证工具反馈、独立判分、候选身份、终态和清理;Agent 修复失败不自动否决任务。
  8. 冻结并登记。 将 task/verifier/template/image 身份及校准路径写入准入记录。更换题面、样例、验收器、任务配置或镜像后重新校准,旧 PASS 不沿用。只上传经过 归档合同 复核的尝试;临时测试内容核对后清理。

当前参考命令,在项目根目录执行;IMAGE 是已拉取的固定镜像引用,PRIVATE_CREDENTIAL_FILE 是 host 私有文件路径,不能填密钥值:

python3 -m rollout calibrate tasks/frame-decoder --trusted-local --output runs
python3 -m rollout calibrate tasks/frame-decoder --image IMAGE --output runs
python3 -m rollout.pi_run tasks/frame-decoder --image IMAGE --credential-file PRIVATE_CREDENTIAL_FILE --calibration CALIBRATION_PATH --output runs

这些命令是使用示例,本次编写标准没有执行校准或外部采样。输出在任务目录外,attempt 名称唯一,不覆盖历史。固定数据在当前 v1 必须包含于验收器,任务输入如需要文件挂载或共享服务,先升级合同。

4. 验收器接口与结果

控制器调用 python3 -I /grader/verify.py /candidate。验收器 stdout 只能输出一行 JSON,至少含 status 与非负整数 checks;详细诊断使用 stderr,避免正式用例与答案进入 Agent 可读反馈。

情况 status 退出码 处理
全部必需行为通过 PASS 0 checks 必须大于 0
已执行检查,候选行为不满足要求 FAIL 1 checks 必须大于 0;可给简洁原因
缺依赖、隔离不成立或证据不足 UNVERIFIED 2 补环境或合同后重验
验收器/执行环境发生故障 INFRA_ERROR 2 修复基础设施,不归为 Agent 能力失败

正常 PASS 示例:{"status":"PASS","checks":87}。这是首题真实断言数量的格式参考,新任务应报告实际运行检查数,不复制数字。编译失败、程序超时如何裁决由任务需求明确;控制端超时或作业故障不得直接冒充任务 FAIL。

任务评分、轨迹完整和来源可信分别验收。完整、正常结束、证据 VERIFIED 且清理确认的真实 FAIL 也可按当前归档合同封存;被截断、中断或基础设施异常的记录保留故障事实,不能混入合格完整轨迹。

5. 角色、状态与准入清单

小团队由任务作者、平台负责人、评审人分工;平台负责人维护运行合同和隔离。业务评审人确认题目是否符合真实需求。多人不足时可以兼任,但至少由未制作该题的人复核判分,记录评审身份;Agent 生成材料也要经过同一校准。

作者规格的状态是人工审核记录,当前解析器不会自动执行这些状态:

DRAFT → READY_FOR_CALIBRATION → CALIBRATED → APPROVED_FOR_PILOT → ADMITTED。

材料或环境缺失标记 BLOCKED,无效问题标记 REJECTED,被替代版本标记 RETIRED。ADMITTED 需要正式校准、独立评审及真实采样链路复核;不要求 Agent 必须解题成功。生产运行门仍由 controller 校验校准回执和固定身份,不能仅凭规格里写了 ADMITTED。

  • 来源可查、使用权限明确;原创/历史/mutation 标记准确。
  • 原项目、来源组和根因族已登记,同源变体没有重复计独立问题。
  • 初态完整,目标错误可复现,环境和输入固定。
  • 题面明确全部正确行为,公开接口和正式判分一致。
  • 验收覆盖正常、边界、恢复与回归;合法替代实现可以通过。
  • 正式测试/gold/密钥与 Agent 隔离,候选无法读取受保护 grader。
  • 历史归档答案不可见,或已明确记录允许的案例检索范围;未以 workdir 冒充存储隔离。
  • 四类各五次,gold PASS、三个负例 FAIL,校准整体 PASS、cleanup confirmed。
  • 校准 task/verifier/image 与正式采样相同;实际摘要和回执路径已记录。
  • 真实试采的模型与工具因果、候选、独立判分、终态与清理已复核。
  • 人工介入、未知费用、未验证硬件条件和其他限制已标记。
  • 合格证据按允许清单封存,临时资源只清理本项目拥有的对象。
  • 评审人签署版本与日期,环境/任务变化后取消旧准入并重新校准。

6. 工作量与实施顺序

1 人日指一位熟悉该领域的工程师约 8 小时有效研发时间,包含构建、验收器、校准与作者修正;模型和作业排队的等待不是人日。下面是建议估算,未做新批次实测,不构成交付日期承诺。假设权限、固定镜像、源码与输入已可用,软件任务无需实板。

单题条件 作者工作量 主要工作
已有成熟任务包复用 0.5–1.5 人日/题 恢复资产、映射合同、重校准、来源核对、准入记录
从完整问题材料制题 2–4 人日/题 复现、初态与输入、构建入口、行为 grader、四类样例
首次建立新任务族 4–8 人日/首题 明确领域验收方式、最小环境与隔离、首套样例、可重复复跑;后续同族通常按前两类估

这些单题数字不包含平台合同升级。ROS、跨架构运行、仿真服务或不完整材料可能超出区间,先做一题恢复实验再估,不能把困难压进固定每题天数。独立评审与返修在作者估算上另预留约 20%–30%。

20 题示例: 已有 1 题获准,剩余 19 题若由 15 个成熟复用任务与 4 个材料制题组成,作者工作约 16–39 人日;加独立评审与返修约 20–50 人日。若两位工程师并行且资产齐备,对应约 10–25 个工作日的任务工程量;平台工程、等待和特殊任务族另计。这个例子依赖成熟资产可恢复,尚未确认的历史任务数量不能直接代入承诺。

平台另按以下工作包做初步估算,等完成能力探针再更新:

平台工作包 建议工程量 完成标准
多文件/输入/构建合同及封存升级 3–5 人日 目录边界、冻结身份、校准、独立 grade、归档回归通过
串行批次、断点续跑与统计 2–4 人日 唯一 attempt、停止后续跑、完整/失败/故障分母、用量与清理可复核
Salty 正式 Agent 后端 3–6 人日 安全模型通道、候选交接、取消与回收实测;先沿用 36 评分

Salty 平台权限、网络或隔离能力缺失可能延长第三项,不能把此范围当作已验证。工作区容量限制必须在并发扩量前落实,也可能增加平台工作量。旧立项方案中“20 题 1–2 周”是资产齐备时的起步建议,本标准按恢复与制题结构拆估,后续以首批实测修正。

建议下一步选 3–5 题、两个任务族:包含已有首题,优先恢复 2–4 个成熟资产;先补确实需要的多文件合同,再做串行真实试采与逐题复核。记录每题制作人时、环境问题、校准耗时、轨迹完整率及失败原因,再确定 20 题清单。不要同时建设所有语言、模拟器和板卡平台。