data-gen-ebd/docs/templates/task-spec.md

144 lines
9.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 任务规格:<task-id>
复制到 `tasks/<task-id>/spec.md` 后填写。本文是作者与评审人的规格模板,**不是运行配置**;`<…>` 都需要替换,未满足项写明 BLOCKED。规范见 [任务制作规范](../task-authoring.md);复制到任务目录后将此链接改为 `../../docs/task-authoring.md`。本文可含根因、隐藏规则和参考解位置,不能整体提供给 Agent。
## 1. 身份与来源
| 字段 | 填写 |
| --- | --- |
| task-id / 任务版本 | <唯一 ID> / <版本> |
| 作者 / 业务评审人 / 独立评审人 | <姓名或团队> |
| 审核状态 | DRAFT |
| 原项目与冻结版本 | <项目、commit/快照及位置> |
| 来源路线 | <A 导入成熟任务 / B 轨迹回放 / C 种子或素材写题 / D 工程问题与开源修复>;<历史问题 / 原创 / mutation> |
| 来源 ID | <Bos env_id / 会话 ID 与观察引用 / 种子 query_id / HWE 基础题 ID / issue 或 commit> |
| 来源与授权 | <原始问题/资产位置,许可或内部授权依据,允许保留范围> |
| 隐私处理 | <真实用户内容的脱敏项与方法;无用户内容写“无”> |
| 替身测试 | <外设换成 PTY/合成数据/桩后问题是否仍复现;结论 software,混杂或必须真硬件则不制作> |
| split 分组键 | <同源变体共用的键:基础题 ID 或来源会话 ID> |
| 来源组 / 根因族 | <去重来源组> / <根因族> |
| 与已有任务的关系 | <独立问题;或列出派生/相同根因的任务 ID> |
| 验证范围 | <实际软件行为> |
| 未验证范围 | <板卡、电气、时序或其他明确边界> |
实际问题说明:<触发条件、观察到的错误、应有行为;原创题说明设计动机,不声称来自现场。>
## 2. 初态与环境
- 初态资产:<全部源码、接口、构建文件、输入的位置与摘要;禁止遗漏目录结构。>
- 回放与补全(路线 B):<逐文件标注“回放”(来源观察引用)或“补全”(补了什么、为什么不泄露答案);充分性评审结论。>
- 目标缺陷复现:<使用初态得到的输出、退出码/错误,以及复现日志位置。>
- 公开资产:<Agent 必需可见的文档、输入与公开测试。>
- 受保护资产:<正式 grader、隐藏输入/预期结果、gold;只在可信控制侧。>
- 环境族 / 架构 / OS / 工具链:<所属环境族(如 C/Python runtime)与精确版本,环境来自固定镜像还是其他后端。>
- 镜像仓库引用 / manifest digest / 实际 image ID:<分别填写,不以浮动 tag 代替身份。>
- 依赖冻结:<lockfile/包版本/下载资产摘要;离线构建或固定依赖方式。>
- 资源和时限:<CPU、内存、工作区容量、每次程序期限、整体验收期限、Agent 防挂死期限。>
- 外部服务 / 硬件要求:<无,或列出尚需准入的能力与健康/复位方法。>
当前合同支持多文件 `candidate_files`、完整 `template/` 工作区、可选 `fixtures` 和私有 `grader_files`,没有服务或独立构建字段。上述资产若不能由当前合同表达,先写 `BLOCKED: <所需合同升级>`;规格记录本身不会完成挂载或身份验证。
## 3. 公开题面与接口
将以下内容写成 Agent 可见的 `prompt.md`,不附根因和参考补丁:
> <任务目标或现场现象与复现方式;最终提交文件;自测入口;明确不验证的范围。允许现象型题面,不点出缺陷位置或知识点;项目约定写入题面或工作区。>
公开构建入口:
```text
工作目录:<目录>
argv:<例如 ["cc", "-std=c11", "decoder.c", "-o", "decoder"]>
构建退出码:<成功/失败定义>
```
公开运行入口:
```text
argv:<例如 ["./decoder", "02", "aa", "bb", "13"]>
输入:<argv/stdin/固定文件;格式、编码、单位及版本>
stdout/stderr/产物:<具体格式>
退出码:<正常、输入错误、任务失败定义>
```
当前示例中的帧协议属于已有 frame-decoder;新题填写真实接口,不照抄其行为。评分器通过 `python3 -I /grader/verify.py /candidate` 接收冻结候选,构建/运行过程由 verifier 显式执行。
## 4. 判据检查项 ↔ 依据与合法解
| 判据检查项 | 依据来源(题面原句、文件:行或标准条款) | 输入/场景 | 可观察结果与允许误差 | 检查方法 | 公开/受保护 | 超时 |
| --- | --- | --- | --- | --- | --- | --- |
| <正常行为> | <逐项写明可核对依据,不只写“见README”> | <固定输入> | <输出、退出码、状态或产物> | <实际运行断言> | <标记> | <秒> |
| <边界行为> | <逐项写明可核对依据,不只写“见README”> | <零/最大/缺失等> | <明确结果> | <实际运行断言> | <标记> | <秒> |
| <异常恢复> | <逐项写明可核对依据,不只写“见README”> | <错误后连续输入> | <恢复结果> | <实际运行断言> | <标记> | <秒> |
| <回归行为> | <逐项写明可核对依据,不只写“见README”> | <历史正常路径> | <不得改变的行为> | <实际运行断言> | <标记> | <秒> |
每个检查项的依据必须可核对;没有依据则删去检查或先补入工作区,判据不能比依据更严。
- 合法替代解:<只要求接口、行为和题面约束;哪些不同算法/实现可以通过。>
- 不允许的捷径:<硬编码例子、打印成功标记、篡改外部评分或读取隐藏资产;说明具体拒绝机制。>
- 判断范围:<构建通过是否足够;要求运行就必须验证运行行为;需要实板而无实板不能宣称已通过。>
- grader 输出:一行 JSON,`PASS/FAIL/UNVERIFIED/INFRA_ERROR`,非负整数 `checks`;PASS/FAIL 的 checks > 0;退出码分别为 0/1/2/2。
- 隔离复核:<候选读取 grader 被拒绝、无网、降权与子进程限制的检查位置;不要把同容器同 UID 当作隐藏测试隔离。>
- 历史答案可见性:<Salty workdir 不代表挂载隔离;确认历史归档的最终候选不可见,或明确记录允许案例检索的范围;隐藏 verifier/gold 始终不可见。>
## 5. 四类样例与校准
| 样例 | 文件 | 预期 verdict | 为什么可以检验 grader |
| --- | --- | --- | --- |
| gold | gold/decoder.c | PASS | <所有需求都满足,允许其他合法实现> |
| 缺陷初态 | template/decoder.c | FAIL | <可复现的目标缺陷> |
| noop | noop/decoder.c | FAIL | <缺少核心功能> |
| cheat | cheat/decoder.c | FAIL | <针对具体可预见捷径> |
- 额外正确解/定向负例复核:<位置与结果,或说明尚未完成>。
- 正式校准:每类新工作区五次,共 20 次;gold PASS、所有负例 FAIL,所以整体 PASS;不得含 UNVERIFIED/INFRA_ERROR。
- 校准命令 / 后端 / 回执目录:<固定镜像的 Docker 校准;可信本地结果只作开发证据>。
- 任务摘要 / verifier 摘要 / 初态摘要 / 镜像身份:<实际值与生成位置>。
- 重置一致性 / cleanup:<20 次结果与清理证据>。
## 6. 真实试采与证据
- 固定 Agent / 模型 / adapter / 参数:<版本与摘要;费用未知则写未知>。
- controller / attempt:<唯一目录,不覆盖已有记录>。
- 候选摘要 / 独立评分:<最终冻结候选和 PASS/FAIL/UNVERIFIED/INFRA_ERROR>。
- 原生轨迹 / 主机日志 / broker 对账:<文件、摘要、模型工具调用闭合与反馈进入后续模型输入的复核>。
- 终止原因 / 人工介入:<正常退出、超时、中断;干预内容与时间>。
- 轨迹质量:<VERIFIED 或未通过项;与任务成功分开>。
- 难度分池:<同一配置 ≥5 次的 PASS/总数;回归集 / 主采集池 / 返工复核及依据>。
- 清理:<拥有的进程、网络、容器、临时文件等已回收/未知>。
- 归档文件 / SHA-256 / Salty 位置:<仅在完整性通过后填写,使用 personal:/embedded-rollout;下载复核并删临时下载>。
- 正式保留与测试清理:<必须保留的证据、本次临时对象及清理回执;不删除他人的资源>。
正常结束、证据完整且清理确认的真实失败尝试也可形成合格 rollout。被截断或环境故障的记录保留故障事实,不能记成完整轨迹或任务能力失败。
## 7. 评审与准入
- [ ] 已按任务创建标准核对来源、完整初态、题面、输入、合法解、隔离与判分。
- [ ] 正式环境四类各五次符合预期,整体 PASS、cleanup confirmed。
- [ ] 准入 task/verifier/image 与正式运行一致,真实采样链路已复核。
- [ ] 重复来源与根因族已登记,未知和未验证项已明确。
- [ ] 独立评审完成,临时资源清理确认。
审核记录:<日期、状态、作者、评审人、具体证据、返修/阻塞原因>。
只在证据齐备后标记 ADMITTED;这些审核状态是人工记录,当前 loader 不解析。任务、grader、题面、样例或镜像变化后重新校准并重新审核。
## 附:当前 v1 的 task.json 参考
下面仅展示当前执行器支持的字段。复制后修改身份与合理的评分期限,配齐全部七个捕获文件;不能只改 JSON 声称新题已可运行。`stream-parser-repair` 是示例 ID,不代表仓库已有第二题。
```json
{
"id": "stream-parser-repair",
"version": "1",
"family": "length-prefixed-stream",
"source": "authored-software-fixture",
"template": "template",
"verifier": "verify.py",
"candidate_files": ["decoder.c"],
"timeout_seconds": 15
}
```
捕获文件为 `task.json`、`prompt.md`、`verify.py`、`template/decoder.c`、`gold/decoder.c`、`noop/decoder.c`、`cheat/decoder.c`。来源与授权、构建、固定输入说明、评审状态先保存在本规格;构建和正式输入必须实际实现在 grader,公开接口写入题面。当前 spec 自身不计入 task digest,因此不能替代上述冻结文件与运行回执。