144 lines
9.7 KiB
Markdown
144 lines
9.7 KiB
Markdown
# 任务规格:<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,因此不能替代上述冻结文件与运行回执。
|