data-gen-ebd/docs/task-authoring.md
amos 1b73b3742b fix: keep host stdout complete and lift the GLM output cap
The first Bos pilot batch exposed two adapter faults on long responses:
- fs.writeSync(1, ...) ignored partial writes to a nonblocking stdout pipe,
  so host stdout lost the tail of 100 KB lines and could no longer match
  the native trace. writeAll now loops until every byte is written and
  waits briefly on EAGAIN.
- Pi SDK caps max_tokens at 32000 unless told otherwise; GLM-5.3 spent
  all of it reasoning and stopped with "length" before any edit. The
  adapter now passes the registered 131072 (accepted upstream).

Runtime trace3 is the trace2 digest plus this pi.mjs; 12/12 SDK checks
pass inside it and all 21 tasks were recalibrated.

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

16 KiB
Raw Blame History

任务创建标准

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

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

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

当前 load_task 的合同:

  • id/version/family/source 为非空字符串;version 是任务版本,不是通用 schema 版本字段。
  • template 必须为 template,verifier 必须为 verify.py。
  • candidate_files 为 1–16 个不重复的安全相对路径,必须存在于 template/ 和每个非 template 样例目录;Agent 结束后只冻结并评分这些文件。
  • template/ 最多 64 个常规文件,全部复制到 Agent 工作区,可放公开 README、头文件和公开自测。
  • fixtures 可选,样例名到 PASS/FAIL 的映射;省略时为 gold/template/noop/cheat。自定义时仍须含这四类及原预期,可增加多个 cheat 或合法替代解,最多 12 类。
  • grader_files 可选,任务根目录下与 verify.py 一起以 0600 进入 /grader 的私有测试或数据,不能与 template/样例目录或保留文件重名。
  • timeout_seconds 为 1–300 的整数,约束一次评分;Agent 执行期限另由 controller 设置。
  • 所有文件不得为符号链接,每个捕获文件不超过 1 MiB;task digest 覆盖 template、全部样例、verify.py 与私有附件。

其他字段即使可被 JSON 读取,也没有自动的构建、输入挂载或执行含义。spec.md 与外部输入不进入 task digest;Agent 需要的公开材料放进 template/,私有测试输入放进 grader_files。ROS、交叉编译与仿真任务还需要对应镜像,先按任务族准入。

2. 作者交付物

tasks/<task-id>/
├── spec.md                从模板填写,供作者与评审人使用
├── task.json              可执行合同
├── prompt.md              Agent 可见需求与公开自测说明
├── template/              有缺陷或未实现的完整初态工作区
├── gold/                  可信正确实现(只含 candidate_files),供控制端校准
├── noop/                  未实现需求的负例
├── cheat/                 绕过/伪造结果的负例;其他样例目录按 fixtures 声明
├── dataset.json           可选:与 task/verifier 摘要关联的 argv 判分目标快照
├── verify.py              受保护的正式行为验收器
└── <grader_files>         可选:私有测试或数据,仅评分侧可读

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

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

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

完整初态要包含完成需求所必需的文件、接口定义、依赖版本和固定输入。缺少的材料标记 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 次)。每个预期 PASS 的样例 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 名称唯一,不覆盖历史。私有固定数据放在 grader_files 或验收器内,公开输入放进 template/;需要共享服务的任务先升级合同。

导入 Bos-qiao 已有任务

python3 -m rollout.bos_import BOS_ENV --output tasks/ENV_ID --family FAMILY 逐题导入,不批量通配。规则:

  • final_targets → candidate_files,必须已在 template 中;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 样例;映射写入 task.json 的 bos.fixture_scripts。
  • 根目录全部 *.py(至少 check.py)作为私有 grader_files;统一的 verify.py 以 UID 65534 原样运行 check.py,最后一行 PASS 且退出 0 才判 PASS。
  • 原镜像缺失,统一换成本项目固定 runtime 镜像后重新完整校准;Bos 历史准入与教师结果不沿用。

已知限制:check.py 递归收集工作区全部 *.py 的 rglob 型任务(README 允许新增辅助源码)暂不导入,因为本合同只冻结声明文件,照搬会把合法拆分误判为 FAIL;需要时再增加候选通配合同。ROS2 Jazzy 任务等待对应镜像。原 check 与候选共用 UID 65534,代码中以 shortcut: 标注升级条件。

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 题清单。不要同时建设所有语言、模拟器和板卡平台。