27-goal-contract-format.md 17.5 KB

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.md M-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 指向的东西

三条不变量:

  1. 一个 root run 一份 acceptance.json。三个产出节点(goal-benchmark / goal-test-data / goal-test-script)各写自己那一段,互不覆盖。这是 27-E2E §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": "<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,覆盖:

  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 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 §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。