验收机器化:期望字节要有能自己判红的真源
模块:验收面 · 契约(AGENTS.md「两台机器」,doc/19-v6/19v6-04)|状态:已落地(2026-10-22 L1–L4)|证据:
tmp/验收机器化/{planning,todos}.md、scripts/acceptance/、yk-tako-eino/internal/runengine/contract_test.go、AGENTS.md
1. 场景与病灶
下一轮有人改契约字节——比如给 GET /api/sessions/:id 的 data 加一个字段,或把某个业务码从 112001 改成 112011。
doc/19-v6/19v6-04 头注的规矩写着「改契约字节必须同步改本篇期望并重跑」。但「重跑」这两个字在人脑里没有可执行的动作。篇子里写的是散文:
curl 'localhost:8080/api/runs/r_1/frames?eventOffset=999' …
→ {"code":0,"message":"","data":{"frames":[],"nextOffset":999,"status":"generating"}}
谁还记得去 tmp/ 里翻出 matrix.py 和 spotcheck.sh?大概率是照着散文再手打一遍三十条 curl,然后肉眼比一次。散文的期望字节跑歪了不会红——唯一的防线是「改契约的那个人当时在不在场、记不记得手打」。人在,就绿;人不在,歪了也绿。
能力其实早就有。 tmp/matrix.py(用例矩阵实跑、逐字节打印)与 tmp/spotcheck.sh(带 ok/no 计数的活体抽验)证明「可机器重跑的验收」完全可行:就是断言跑一遍、失败打 ❌。缺的不是能力,是让它活下来的地方。
三条断链,性质不同:
| # | 断链 | 后果 |
|---|---|---|
| C1 | 脚本躺在 tmp/(.gitignore 排除) |
换个 clone 就没有;下一轮没人翻得到 |
| C2 | 脚本写死本机绝对路径与端口(/Users/…/.env、127.0.0.1:8943) |
换机器/换端口就跑不了,仍是一次性脚本 |
| C3 | 期望字节只在散文与 shell 里,没有机器可断言的形式 | 跑了也不算数:契约漂了脚本可能照样绿 |
C3 最要命:C1/C2 让脚本「找不到、跑不了」,C3 让它「跑了也不算」。三样都得修。
2. 候选与代价
| 候选 | 做法 | 好处 | 代价 |
|---|---|---|---|
| A 维持散文(现状) | 人手打 curl、肉眼比 | 零成本、新人可读 | 不可重跑;漂了不红;依赖「那个人在场」 |
| B 只把脚本搬进仓库 | 文件原样搬,不改写死值 | 找得到 | 换机器仍跑不了(C2);仍不断言(C3),搬了个不判红的脚本 |
| C 搬入 + 参数化 + 机器真源 + 快闸(选定) | scripts/acceptance/ + expected.json + contract_test.go;散文保留为人读版,比对脚本守用例号集合 |
重跑是一句命令;漂了自己红;不依赖人 | 多一份文件要同批改;隔离引擎要手工起 |
D 让脚本解析散文里的 → 202 {...} |
单一真源、零重复 | 理论上最省同步 | 散文体例一改解析器就脆;大量描述性期望(「frames: [start,delta,delta]」)要特判,比维护清单更贵 |
| E 用场景级 Eval 取代 | 每件事写成场景 | 更贴近真实 | 它管「活干完没有」,管不了「字节对不对」;今天还没建(doc/45) |
选 C,并且分两层落地,因为两类东西的成本完全不同:
- 能在 Go 里断言的骨架(信封字段顺序、data 键序、帧 kind 词表、业务码值)→ 进快闸
go test,不打模型、不依赖 PG/Redis,每拍收尾顺带跑; - 必须起引擎/模型的活体(真跑一轮、工具循环、跨租户可见性)→ 进
scripts/acceptance/,参数化到TAKO_BASE/TAKO_ENV/TAKO_PG_DSN。
3. 机器真源长什么样
scripts/acceptance/expected.json 是契约字节的机器真源。每条 = 用例号 + 请求 + 期望 HTTP 码 / 业务码 / 文案 / data 字段序与值。今天它是 26 条 cases(断言)+ 15 条 declared_not_asserted(登记不断言的原因)。
人读版仍是 doc/19-v6/19v6-04。两份同批改,check-expected.sh 守「散文里的用例号集合 == 清单里的用例号集合」——单边漂即非零退出。规则是:散文不删(新会话要读它知道端点长什么样),但它不再是唯一真源。
assert_contract.py 逐条打引擎、比对字节,失败打 ❌、退出码非零。阴性对照是这条链的验收本身:故意把 expected.json 一条 message 改成「故意写错」,必须 FAIL 1、退出码非 0;改回再回到全绿。不会红的断言器等于没建。
快闸 contract_test.go 断的骨架(TestContract*):信封三字段顺序与失败体、GET /api/sessions/:id 的 data 键序(liveRunId → runlogOffset → lastRunStatus → lastRunId → workspaceId)、帧 kind 词表、关键业务码值、流事件的字节形状、新增端点的字节(文件清单、项目对象的 isDefault)。断言里的字节不许手写:先 curl 实跑一次,把真实字节抄进测试——手写的期望只是把手写散文换了个文件名。
4. 落地时撞到的事实
这一轮最硬的一条不是设计出来的,是跑出来的:
- 旧脚本已经烂了。
tmp/matrix.py/tmp/spotcheck.sh早于 doc/40 的信封切换,还在顶层取sessionId(现行是data.sessionId)——直接 KeyError。它们不是「放在 tmp/ 里没人维护」,是已经坏了,只是没人跑到过。这反过来加强 C1:不入库的东西不只是找不到,它是无声腐烂的。 0-signup的 data 键序漏了accessToken(在tokenType之前)——机器清单第一次跑就红。人读散文时这一处很容易滑过去。- terminal 帧比 PG 翻终态早一拍 → 「定稿后立刻读 session」必假失败 → 断言器加
wait_settled等会话落定,不是靠 sleep 猜。 0-runtime-config把字面量$key当密钥 PUT 进了共享账号,把后面所有 model 用例的租户密钥改成垃圾 → 全线 401。修法:占位符真替换 + 该用例自带账号。验收脚本自己也会互相污染,隔离比「小心点」可靠。- 启动配方两处错:Redis db 索引要 URL 形式
redis://127.0.0.1:6390/7;隔离库要先CREATE EXTENSION pg_search CASCADE,否则引擎 fail fast 起不来。
5. 同族小裁定
| 小问题 | 裁定 | 代价 / 备注 |
|---|---|---|
| 机器真源放哪 | 独立 expected.json,不写进脚本、不解析散文 |
多一份文件同批改,由 check-expected.sh 守集合 |
| 散文删不删 | 不删,降级为人读版 | 新会话需要「端点该长什么样」的可读说明 |
| 骨架断在哪 | Go 快闸(contract_test.go) |
不依赖引擎/模型,每拍顺带跑 |
| 活体放哪 | scripts/acceptance/(python + bash) |
参数化 TAKO_BASE / TAKO_ENV / TAKO_PG_DSN |
| 断言的字节从哪来 | 先 curl 实跑、抄真实字节 | 手写期望等于换文件名的散文 |
| 暂不断言的用例怎么处理 | declared_not_asserted 登记原因 |
例:模型行为不稳、要特殊起引擎;今天 15 条 |
旧 tmp/ 脚本 |
被取代后删除/移回收站,台账记一句 | 已坏在信封切换前,保留只会误导 |
| 「重跑」命令 | assert_contract.py + check-expected.sh(+ 各专项 shell) |
方案原写 run.sh,落地拆成按用途的脚本;README 是入口 |
| 隔离靶子 | 独立 PG 库 + 独立 Redis db + 独立 workspace | 别拿开发库当靶子:脚本会注册账号、建项目、删默认工作区 |
DELETE /api/dev/reset |
禁止用来清测试数据 | 全库 TRUNCATE 15 张表 + SCAN tk:*,2026-10-21 真出过一次 |
6. 证据
方案 / 台账:tmp/验收机器化/planning.md(三条断链、L1–L4、§6 三选一 → 用户选「甲」;§7 施工后补记、四处实测问题)、todos.md(每拍 curl + 期望输出 + 阴性对照)、tmp/验收机器化/ 验收后清理;规则落 AGENTS.md「验收:两台机器」。
代码符号:
| 位置 | 是什么 |
|---|---|
scripts/acceptance/expected.json |
机器真源:26 条 cases + 15 条 declared_not_asserted |
scripts/acceptance/assert_contract.py |
逐条打引擎比对,失败非零退出 |
scripts/acceptance/check-expected.sh |
散文用例号集合 ↔︎ 清单用例号集合一致 |
scripts/acceptance/README.md |
隔离引擎起法(建库 + pg_search + 独立 Redis db / workspace) |
yk-tako-eino/internal/runengine/contract_test.go:35 |
TestContractEnvelopeBytes 信封字节 |
yk-tako-eino/internal/runengine/contract_test.go:53 |
TestContractSessionResponseBytes data 键序 |
yk-tako-eino/internal/runengine/contract_test.go:121 |
TestContractBusinessCodes |
yk-tako-eino/internal/runengine/contract_test.go:161 |
TestContractFrameKindVocabulary |
yk-tako-eino/internal/runengine/contract_test.go:199 |
TestContractToolTiering 分档现状 |
doc/19-v6/19v6-04-验收-curl.md:6-15 |
头注:人读版 / 机器版 / 重跑命令 |
复核命令:
# 快闸(不用引擎、不用模型)
cd yk-tako-eino && PATH="$HOME/sdk/go1.27.0/bin:$PATH" go test ./internal/runengine
PATH="$HOME/sdk/go1.27.0/bin:$PATH" go vet ./internal/runengine
# 活体(先按 README 起隔离引擎)
TAKO_BASE=http://127.0.0.1:8943 TAKO_ENV=yk-tako-eino/.env \
python3 scripts/acceptance/assert_contract.py # 红 → 退出码非零
bash scripts/acceptance/check-expected.sh # 用例号集合一致
# 阴性对照:故意写错一条 → 必须红
python3 - <<'PY'
import json,pathlib
p=pathlib.Path("scripts/acceptance/expected.json"); d=json.loads(p.read_text())
d["cases"][0]["message"]="故意写错"; p.write_text(json.dumps(d,ensure_ascii=False,indent=2))
PY活体验收:2026-10-22 全拍完成后 go test / go vet 绿;assert_contract.py 全绿且阴性对照判红;check-expected.sh 一致;check-master-plan.sh OK。doc/48 之后新增的端点在快闸与清单里继续同批登记(如 TestContractWorkspaceFilesBytes / TestContractStreamEventBytes)。
7. 现状
- 仍有效:散文 + 机器真源双份同批改;骨架进 Go 快闸、活体进
scripts/acceptance/;期望字节先实跑再抄;declared_not_asserted必须写原因;隔离靶子参数化。 - 已翻转:
tmp/里的验收脚本不再算资产(旧两份已坏在信封切换前,被取代);「重跑」从一段散文变成一句命令。 - 未做:
doc/45场景级 Eval——它能回答「活干完没有」,但今天没有建成,不属于这一层。 - 同族问题:界面验收怎么分层 → 界面验收双轨;契约字节里的信封形状 → 响应信封统一;帧与 runlog 的状态语义 → 崩溃后这场 run 算什么状态。