# 27-T0. 验收契约格式 —— `acceptance.json` 与执行器 > **所属**: [27-P3/P4](./27-p3-p4-work-graph-console.md) §五 **阶段 0**(T0),需求源头 [27-REQ](./27-requirement.md) R-15.6 > **实现**: `server/services/goal-contract.js` > **配套**: [27-E2E](./27-e2e-task-execution-flow.md) §十一(三个验收产出节点)、`docs/prd/newfunction/_spec/sdd-model.md` M-6/M-7/M-8(形态来源) > **日期**: 2026-08-16 --- ## 〇、这份文档定死什么、放开什么 [27-P3/P4](./27-p3-p4-work-graph-console.md) §八.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](./27-p3-p4-work-graph-console.md) §四.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 指向的东西 ``` 三条不变量: 1. **一个 root run 一份 `acceptance.json`**。三个产出节点(`goal-benchmark` / `goal-test-data` / `goal-test-script`)各写自己那一段,互不覆盖。这是 [27-E2E](./27-e2e-task-execution-flow.md) §11.2 的定案:三者产出形态不同,但下游 validator 必须能统一消费,**否则每加一种验收节点就要改一次 validator**。 2. **契约里的相对路径一律相对 `artifacts/`,且不许逃出 `artifacts/`**。`resolveInsideArtifacts()` 强制这条——一份契约不能指向 `../../../etc/passwd`,也不能指向别的节点的 `nodes/`。这是信任边界,不是洁癖:契约由 LLM 产出,`test_script.path` 会被真的拿去起进程。 3. **`verdicts/index.ndjson` append-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": ""}`。** 一个机制覆盖三段,不为 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`)。 --- ## 三、执行器接口(稳定面) ```js 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 ← 纯执行,不落盘 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 ```jsonc { "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(演进面) ```jsonc { "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` —— 打分式验收 ```jsonc { "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](./27-e2e-task-execution-flow.md) §11.4 的遗留缺口),**执行器只负责把分数按契约算成判决**。分从哪来是节点的事,怎么判是执行器的事——和 §四.D.2.1「数到 3 就停是代码的活,判断修好没有是 LLM 的活」同一条分工原则。 ### 4.2 `test_data` —— 样本集比对 ```jsonc { "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` —— 真实子进程执行 ```jsonc { "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 /check-goal-contract.js`,覆盖: 1. 写一份三段齐全的契约(benchmark 走 `$ref` 外置,验证 §四.A.5 的文件位),`writeContract` 返回 `contract_hash`; 2. 四种非法契约被挡:空契约、runner 越界、路径逃逸 `../../etc/passwd`、权重不足 1; 3. **通过的产物**:benchmark 加权 89.2 ≥ 78 且逐维度过线、test_data 2/2(subset 模式忽略额外键)、脚本 exit 0 → `ok:true, fail_reason:null`; 4. **不通过的产物**:coverage 61 < 80、一个 case 值错一个 case 缺失、脚本 exit 1 → `ok:false, fail_reason:'acceptance_not_met'`,`failures[]` 汇总 4 条; 5. 判决可查可追溯:`listVerdicts` 的 `onlyFailed` / `nodeRunId` 过滤正确,`readVerdict` 取回的 `contract_hash` 与写入时一致; 6. 脚本超时 → `fail_reason:'infra_flake'`(引擎侧不烧计数的那一类)。 > 自查脚本目前放在 scratchpad——T0 的独占文件清单只含 `goal-contract.js` 与本文档,落库到 `server/tests/unit/goal-contract.test.js` 留给 T10 一并收进测试套件。 --- ## 七、遗留 / 交给下游 1. **谁调 `runAcceptance`**:work 层的 `{orgNode}-validator` 节点和 org 层的 `org-validator`(§四.D.3 两级验收)。引擎侧接线属 T2/T7,本文档只提供被调用的能力。 2. **写 `artifacts/` 是特权动作**(§四.A.5)——只有被规划标记为验收契约产出者的节点能写。本文件不做权限判定,权限模型属引擎侧(T2)。 3. **`qa-judge` 的程序化入口仍缺**([27-E2E](./27-e2e-task-execution-flow.md) §11.4)。benchmark 的分数目前只能由产出被测产物的节点自报。接上 `qa-judge` 后它的输出协议(`PASS`/`REWORK`/`RETRAIN_REQUIRED`)需映射进 `scores` + `fail_reason`,其中 `RETRAIN_REQUIRED` → `skill_defect` 那一支即 L4,v1 挂起等人工。 4. **两处 R-16 待定案按假设执行**,代码里以 `// 假设(R-16待定案):` 标注: - 判决只归到「这次验收没达成」这个 **org node 粒度**的结论,不跨层直接寻址子图里的具体节点(保持层级封装,`remediation_note` 随回退往下传); - 归因节点名保留 **`validator-reflection`**,不改 `validator-triager`。