27-T0. 验收契约格式 —— acceptance.json 与执行器
所属: 27-P3/P4 §五 阶段 0(T0),需求源头 27-REQ R-15.6 实现:
server/services/goal-contract.js配套: 27-E2E §十一(三个验收产出节点)、docs/prd/newfunction/_spec/sdd-model.mdM-6/M-7/M-8(形态来源) 日期: 2026-08-16
〇、这份文档定死什么、放开什么
27-P3/P4 §八.9 给的边界很明确——阶段 0 的契约格式一旦定错,阶段 A 的 schema 要返工,所以
先把存储位置和与
output_ref/artifacts/的关联方式定死,格式内部细节允许后续演进。
本文档照这个优先级组织:§一~§三 是稳定面(改动即破坏兼容),§四 是演进面(加字段、加断言种类都不影响引擎)。
| 稳定面(定死) | 演进面(可改) | |
|---|---|---|
| 契约放哪 | artifacts/acceptance.json,一个 root run 一份 |
— |
| 谁引用它 | 引擎的 validator 节点,按 root_run_id 上溯 |
— |
| 怎么被执行 | runAcceptance({runDir, targetPath, ...}),被测产物由 output_ref 给出 |
— |
| 判决存哪 | artifacts/verdicts/{verdictId}.json + index.ndjson |
— |
| 判决的追溯四元组 | run_id / node_run_id / attempt / contract_hash |
— |
| 三个 section 各自怎么断言 | — | ✅ 随便演进 |
fail_reason 取值域 |
— | ✅ 引擎不硬编码(§四.D.2.2) |
一、存储位置(稳定面)
沿用 27-P3/P4 §四.A.5 已定的产物布局,本文档只把 verdicts/ 这一格补上:
data/companies/{cid}/runs/{rootRunId}/
├── artifacts/ # 任务级共享产物区,跨 org node 只读
│ ├── acceptance.json # ← 唯一契约入口(本文档的主角)
│ ├── goal-benchmark.json # ← 大块内容外置,契约里 {"$ref": "goal-benchmark.json"}
│ ├── goal-test-data/
│ ├── goal-test-script/
│ └── verdicts/
│ ├── {verdictId}.json # ← 一次执行一份完整判决
│ └── index.ndjson # ← append-only 索引,可查、可追溯
└── nodes/{nodeRunId}/
└── attempt-{n}.json # ← 被测产物,即 output_ref 指向的东西
三条不变量:
- 一个 root run 一份
acceptance.json。三个产出节点(goal-benchmark/goal-test-data/goal-test-script)各写自己那一段,互不覆盖。这是 27-E2E §11.2 的定案:三者产出形态不同,但下游 validator 必须能统一消费,否则每加一种验收节点就要改一次 validator。 - 契约里的相对路径一律相对
artifacts/,且不许逃出artifacts/。resolveInsideArtifacts()强制这条——一份契约不能指向../../../etc/passwd,也不能指向别的节点的nodes/。这是信任边界,不是洁癖:契约由 LLM 产出,test_script.path会被真的拿去起进程。 verdicts/index.ndjsonappend-only,永不改已写行(CONVENTIONS.md§12 的 ndjson 不变量)。
为什么允许 $ref
§四.A.5 的布局写着 goal-benchmark.json / goal-test-data/ / goal-test-script/ 三个独立文件位,§11.2 又要求三段合成一份 acceptance.json。两者都成立——一份 5000 行的测试数据集塞进 acceptance.json 会让契约本身不可读。
统一解法:任何一段都可以写成 {"$ref": "<artifacts/ 下的相对路径>"}。 一个机制覆盖三段,不为 benchmark 和 test_data 各发明一套外置规则。
⚠️ contract_hash 一律按解引用后的形态计算。否则「内联写」和「$ref 外置写」同一份验收标准会算出两个 hash,判决就追溯不回契约版本了。writeContract() 和 readContract() 共用同一个 resolveRefs(),就是为了堵这条缝(自查时先踩到过:写入返回的 hash 与执行时算出的 hash 不一致)。
二、与 output_ref / artifacts/ 的关联方式(稳定面)
graph_run_nodes.output_ref ──解析──▶ targetPath(被测产物)
│
artifacts/acceptance.json ──readContract──┼──▶ executeContract ──▶ verdict
│ │
└────────────────────────────┘
verdict.run_id / node_run_id / attempt / contract_hash
- 被测产物:执行器的入参
targetPath就是某个graph_run_nodes.output_ref解析出来的绝对路径。执行器不猜、不扫目录、不自己去找产物。 - 契约:按
root_run_id上溯到 root run 的artifacts/。子 run、孙 run 的 validator 节点读的是同一份契约——这正是 §四.A.5 要把验收契约放在 root 级共享区、而不是节点私有区的原因(产出者org-planner和消费者org-validator是两个不同的 org node)。 - 判决:落在契约旁边(
artifacts/verdicts/),不落在节点私有目录。因为一次验收可能对多个节点的产物做,判决是任务级资产。 - 相对路径:
verdict.target落在 run 目录内时存相对路径,整个 run 目录可整体归档搬走后仍可读。
双向可追溯:给一个 node_run_id 能查出它历次验收判决(listVerdicts(runDir, {nodeRunId}));给一份判决能查出它用的是哪版契约(contract_hash)、判的是哪次尝试(run_id + attempt)。
三、执行器接口(稳定面)
const gc = require('@server/services/goal-contract');
// 路径
gc.resolveRunDir(companyId, rootRunId) // → data/companies/{cid}/runs/{rootRunId}
gc.resolveArtifactsDir(runDir) // → {runDir}/artifacts
gc.resolveContractPath(runDir) // → {runDir}/artifacts/acceptance.json
gc.resolveVerdictsDir(runDir) // → {runDir}/artifacts/verdicts
// 契约
gc.validateContract(contract) // → {ok, errors: [{rule, detail}]} ← 只校验契约本身
gc.readContract(runDir) // → {contract, path} | null ← 含 $ref 解引用
gc.writeContract(runDir, contract) // → {path, contract_hash} ← 写前必校验,tmp+rename
gc.contractHash(resolvedContract) // → 'sha256:...'(复用 doc-store.hashContract)
// 执行
gc.executeContract(contract, targetPath, {runDir, runId, nodeRunId, attempt})
// → Promise<verdict> ← 纯执行,不落盘
gc.runAcceptance({runDir, targetPath, runId, nodeRunId, attempt})
// → Promise<{verdict, path}> ← 读契约→执行→落盘,引擎调这个
// 判决
gc.persistVerdict(runDir, verdict) // → {path, indexPath, entry}
gc.listVerdicts(runDir, {runId, nodeRunId, onlyFailed, limit}) // → [indexEntry]
gc.readVerdict(runDir, verdictId) // → verdict | null
errors 形态 {rule, detail} 与 org-graph-service.validateGraph() 对齐(rule ∈ schema | section | reference | runner),两处校验器的调用方可以共用同一套错误渲染。
判决 schema
{
"verdict_id": "vd-20260816-1208-a3b4", // CONVENTIONS §2 的 ID 形态
"goal_id": "GOAL-xxx",
"contract_hash": "sha256:bf76e6de3eb406b2", // ← 追溯到哪版契约
"run_id": "run_xxx", // ← 追溯到哪次 run
"node_run_id": "rn_xxx", // ← 哪个节点
"attempt": 1, // ← 第几次尝试
"target": "nodes/rn_xxx/attempt-1.json",
"ok": false, // 所有非 null section 全 ok 才 true
"fail_reason": "acceptance_not_met", // null | acceptance_not_met | infra_flake | input_underspecified
"sections": {
"benchmark": { "ok": false, "score": 73.4, "dimensions": [...], "failures": [...] } | null,
"test_data": { "ok": false, "total": 2, "passed": 0, "failed": 2, "failures": [...] } | null,
"test_script": { "ok": false, "exit_code": 1, "timed_out": false, "stdout_excerpt": "...", "failures": [...] } | null
},
"failures": [ { "case": "...", "expected": ..., "got": ..., "hint": "..." } ], // 三段扁平汇总
"duration_ms": 812,
"created_at": "2026-08-16T04:08:48.387Z"
}
failures[] 的 {case, expected, got, hint} 四字段直接抄 DevLoop 的 runs/result.json(M-7)——归因节点已经会读这个形状了,不另发明。
fail_reason 与引擎的关系
判决产出的 fail_reason 落进 graph_run_nodes.fail_reason,供 §四.D.2.2 选边。取三个值:
| 值 | 含义 | 引擎侧动作 |
|---|---|---|
acceptance_not_met |
真的没达标 | 正常走 fail 边,烧计数 |
infra_flake |
脚本超时 / 进程起不来 | 原地重跑,不烧任何计数(§四.D.2.1) |
input_underspecified |
契约本身不合法 | 退回契约产出者——不是产物的错 |
infra_flake 这一档是刻意的:把「进程超时」误判成「实现有问题」会白烧一轮回退预算。
四、契约 schema(演进面)
{
"version": "1",
"goal_id": "GOAL-xxx", // 必填,一次人类需求 = 一个验收边界(27-NAMING §四)
"created_by": "goal-benchmark", // 可选,审计用
"created_at": "2026-08-16T...",
"benchmark": { ... } | { "$ref": "goal-benchmark.json" } | null,
"test_data": { ... } | { "$ref": "..." } | null,
"test_script": { ... } | { "$ref": "..." } | null
}
三段各自可为 null(对应「这次没加这个节点」),validator 只处理非 null 的部分。但三段全 null 直接判非法——空契约会「平凡通过」,正是 §四.D.3 要求 planner-validator 盯的那类漏洞,在格式层面就堵掉,不指望下游发现。
4.1 benchmark —— 打分式验收
{
"dimensions": [
{ "name": "coverage", "weight": 0.6, "pass_threshold": 80 },
{ "name": "readability", "weight": 0.4, "pass_threshold": 70 }
],
"overall_pass_threshold": 78
}
- 权重之和必须 = 1(容差 1e-6),维度名不许重复。
- 被测产物形态:
{"scores": {"coverage": 92, "readability": 85}},或直接{"coverage": 92, ...}。 - 判定:逐维度
score >= pass_threshold,再看加权总分>= overall_pass_threshold。缺某维度的分 = 该维度 fail(不是当 0 分,是明确报missing score in target)。
为什么阶段 0 不起 LLM 打分:§五 明写阶段 0「起 LLM ❌」。打分这件事本身是 agent 的活(
qa-judge那条线,27-E2E §11.4 的遗留缺口),执行器只负责把分数按契约算成判决。分从哪来是节点的事,怎么判是执行器的事——和 §四.D.2.1「数到 3 就停是代码的活,判断修好没有是 LLM 的活」同一条分工原则。
4.2 test_data —— 样本集比对
{
"match": "deep-equal", // 或 "subset"(默认 deep-equal)
"cases": [
{ "id": "c-normal", "input": {"n": 2}, "expect": {"out": 4} },
{ "id": "c-edge", "input": {"n": 0}, "expect": {"out": 0} }
]
}
- 被测产物形态:
{"results": {"c-normal": {...}, ...}},或{"results": [{"id": "...", "output": {...}}]}。 deep-equal= key 排序后规范序列化比对;subset= expect 里出现的键必须匹配,实际输出允许有额外键(数组仍要求等长)。- case 缺结果 = fail,且 hint 明说
no result for case X in target——和「值错了」区分开,归因时有用。 input字段执行器不读,它是给产出被测产物的那个节点看的。契约同时是「考题」和「答案」,执行器只用后半截。
4.3 test_script —— 真实子进程执行
{
"runner": "node",
"path": "goal-test-script/acceptance.js", // 相对 artifacts/,不许逃出去
"args": [],
"cwd": ".", // 相对 artifacts/,默认 runDir
"timeout_ms": 120000,
"pass_on": { "exit_code": 0 }
}
- 脚本怎么拿到被测产物:env 注入
ACCEPTANCE_TARGET(绝对路径)、ACCEPTANCE_RUN_DIR、ACCEPTANCE_ARTIFACTS_DIR。不走 argv——argv 位置约定容易和args打架。 - 判定:退出码 ==
pass_on.exit_code(默认 0)。超时先SIGTERM、3s 后SIGKILL(沿用integrator-tools.js的killAll做法),超时归infra_flake。 - stdout/stderr 各截 64KB,判决里只留末 4KB 摘要——完整输出应由脚本自己写文件。
runner v1 只支持 node。实测结论(不是偷懒,是核实过):仓库根 vitest.config 的 include 只覆盖 src/ server/tests/ packages/,验收脚本住在 data/companies/... 下,vitest run <脚本> / --root / --dir 三种写法都会被根 config 的 include 盖掉,直接 No test files found, exiting with code 1。要支持 vitest 得先为验收脚本生成一份临时 config 再 --config 指过去——没人要求的机器。
上限与升级路径:眼下 node 脚本里自己 spawn 任何测试框架不受限制,所以不急;真需要原生 vitest 时,加临时 config + 把 'vitest' 加回 RUNNERS 白名单即可,runner 字段就是为此留的扩展位。
五、设计取舍
| 取舍 | 选了 | 没选 | 理由 |
|---|---|---|---|
| 契约文件数 | 一份 acceptance.json + 可选 $ref 外置 |
三份独立文件各自为政 | §11.2:下游 validator 必须统一消费,否则每加一种验收节点就改一次 validator。$ref 让「大块内容外置」这个真实需求不必破坏统一入口 |
| hash 算在哪一版 | 解引用后 | 原文件字节 | 同一份标准两种写法必须算出同一个 hash,否则判决追溯不回契约 |
| benchmark 谁打分 | 被测产物提供分数,执行器只算加权 | 执行器起 LLM 打分 | §五 阶段 0 明写不起 LLM;且「打分」是节点职责、「判定」是执行器职责,分工与 §四.D.2.1 一致 |
| test_script 执行方式 | 真子进程 + 退出码 | 沙箱内 eval |
DevLoop Integrator 起真实进程跑 e2e 是已验证的先例(§11.3);eval 拿不到真实进程的超时/信号语义 |
| runner 白名单 | 只有 node |
任意 shell 命令串 | 契约由 LLM 产出且会被真的执行,命令串 = 任意代码执行。白名单 + 路径必须落在 artifacts/ 内是这里唯一的信任边界防线 |
| 判决存哪 | artifacts/verdicts/ |
节点私有 nodes/{id}/ |
一次验收可能判多个节点的产物,判决是任务级资产;且与契约放一起便于整体归档 |
| 索引形态 | ndjson append-only | SQLite 表 | 与 timeline.ndjson / bugs.ndjson 同款;判决量级是每 run 几十条,不值得开表。上限:listVerdicts 是全文件扫描,O(n);上万条时再考虑进 graph.sqlite |
| 空契约 | 判非法 | 判通过 | 平凡通过是 §四.D.3 点名的漏洞 |
六、自查(已跑过)
node <scratchpad>/check-goal-contract.js,覆盖:
- 写一份三段齐全的契约(benchmark 走
$ref外置,验证 §四.A.5 的文件位),writeContract返回contract_hash; - 四种非法契约被挡:空契约、runner 越界、路径逃逸
../../etc/passwd、权重不足 1; - 通过的产物:benchmark 加权 89.2 ≥ 78 且逐维度过线、test_data 2/2(subset 模式忽略额外键)、脚本 exit 0 →
ok:true, fail_reason:null; - 不通过的产物:coverage 61 ok:false, fail_reason:'acceptance_not_met',
failures[]汇总 4 条; - 判决可查可追溯:
listVerdicts的onlyFailed/nodeRunId过滤正确,readVerdict取回的contract_hash与写入时一致; - 脚本超时 →
fail_reason:'infra_flake'(引擎侧不烧计数的那一类)。
自查脚本目前放在 scratchpad——T0 的独占文件清单只含
goal-contract.js与本文档,落库到server/tests/unit/goal-contract.test.js留给 T10 一并收进测试套件。
七、遗留 / 交给下游
- 谁调
runAcceptance:work 层的{orgNode}-validator节点和 org 层的org-validator(§四.D.3 两级验收)。引擎侧接线属 T2/T7,本文档只提供被调用的能力。 - 写
artifacts/是特权动作(§四.A.5)——只有被规划标记为验收契约产出者的节点能写。本文件不做权限判定,权限模型属引擎侧(T2)。 qa-judge的程序化入口仍缺(27-E2E §11.4)。benchmark 的分数目前只能由产出被测产物的节点自报。接上qa-judge后它的输出协议(PASS/REWORK/RETRAIN_REQUIRED)需映射进scores+fail_reason,其中RETRAIN_REQUIRED→skill_defect那一支即 L4,v1 挂起等人工。- 两处 R-16 待定案按假设执行,代码里以
// 假设(R-16待定案):标注:- 判决只归到「这次验收没达成」这个 org node 粒度的结论,不跨层直接寻址子图里的具体节点(保持层级封装,
remediation_note随回退往下传); - 归因节点名保留
validator-reflection,不改validator-triager。
- 判决只归到「这次验收没达成」这个 org node 粒度的结论,不跨层直接寻址子图里的具体节点(保持层级封装,