tako 文档 GitHub

验收机器化:期望字节要有能自己判红的真源

模块:验收面 · 契约(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,并且分两层落地,因为两类东西的成本完全不同:

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. 落地时撞到的事实

这一轮最硬的一条不是设计出来的,是跑出来的:

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. 现状