Wally 工程实践完整版:OpenAPI 3.1 + Protobuf 契约先行与 CI 漂移检测如何保障每次发布
Wally 工程实践完整版:OpenAPI 3.1 + Protobuf 契约先行与 CI 漂移检测如何保障每次发布
Wally 是一个把编码 Agent(OpenCode、Claude Code 等)直接接入 GLM-5.3-flash、DeepSeek、Gemma 等开源前沿模型的命令行工具。它最值得一读的地方,是工程层面如何用 OpenAPI 3.1 契约 + Protobuf 双契约体系、生成式类型绑定和 CI 漂移检测,让"接口约定"与"实现代码"永远不脱节——每次发布前,任何一处脱节都会直接让 CI 变红。本文完整拆解这套契约先行(contract-first)实践。
一、为什么 Wally 必须"契约先行"
Wally 的调用链横跨两层边界:
CLI 参数解析 → Rust 业务代码 → Protobuf 消息 → C++ SDK kit → 推理引擎
↘ HTTP 调用(auth / 账户 / 用量 / 目录)↗ 控制台服务
- 对 SDK:模型目录、下载、推理生命周期全部由 C++ kit 拥有,Rust 侧只通过 Protobuf 字节流与其通信;
- 对控制台 HTTP API:登录、账户、用量导出、模型目录等约 10 个端点由 Wally 直接调用。
两条边界如果各自"手写 JSON / 手拼字段名",字段重命名、类型变更都会静默地造成运行时错误。Wally 在 AGENTS.md 中把这条规则定为 P0 级网络规则:
每个操作必须有稳定的
operationId和具名 schema;任何命令不得发明字符串拼接路径、临时对象、未校验的响应解析;闭集值必须是生成的 enum;契约、绑定、CLI 适配、测试必须原子性落地,其中任何一个过期 CI 就失败。
二、两条契约线:OpenAPI 3.1 管 API,Protobuf 管 SDK
2.1 OpenAPI 3.1 线:控制台 API 的"切片契约"
完整控制台契约 control-plane-v1.openapi.json 有 8000 行,但 CLI 只用其中 10 个操作(授权开始/轮询/刷新/吊销、/v1/me、用量、目录、取消请求等)。Wally 的做法不是整份 vendor,而是按操作抽取:
- contracts/extract-cli-contract.py:按
operationId白名单从上游契约中抽出 CLI 所需的 10 个操作,并递归求解它们引用的 schema 的传递闭包,产出自包含的 contracts/wally-cli-v1.openapi.json。写入前还会做一次"悬空$ref"检查——任何解析不到的引用直接拒绝写盘; - contracts/wally-decisions-public-v1.openapi.json:另一份独立 vendor 的 decisions 契约,锚定在 versions.toml 的
[contracts]段(源 commit + SHA-256 双钉)。
每份抽取结果都打上 x-runanywhere-source 溯源戳(repository / commit / branch / artifact 四字段,要么全有要么全无),保证"这份契约来自上游哪个版本"永远可追溯。
2.2 Protobuf 线:SDK 边界的"schema 锁"
Protobuf 是 SDK 边界的唯一事实源(SOT),规则写在 AGENTS.md 的 Layering 一节:
- Rust 消息类型在构建时由 build.rs 用
protox(纯 Rust 编译器)直接从 kit 自带的idl/*.proto生成——Wally 从不运行protoc,也不提交任何生成物; - 生成前先算 IDL 目录的
SCHEMA_LOCK哈希(对每个.proto的文件名 + 内容 SHA-256再滚动哈希),与 versions.toml 中idl_schema_sha256比对,不匹配直接构建失败,并提示"换匹配的 kit 或升 pin,绝不在本地重生成 schema"; - 解析 kit 返回的
rac_*_proto字节缓冲统一走 src/io/proto.rs 的ProtoBuffer+parse_proto_buffer(),带 RAII 释放,杜绝泄漏路径。
三、契约 → 类型绑定的生成管线
契约要真正"管住"代码,必须落成强类型。Wally 的生成器 contracts/generate_console_binding.py 把 OpenAPI 工件翻译成 src/account/console_contract.rs(文件头标注 DO NOT EDIT):
| 契约元素 | 生成的 Rust 形态 |
|---|---|
| 具名 string enum | 闭集 enum + 拒绝未知值的 parse() |
| object schema | struct + 手写 to_json / from_json 对 |
oneOf + discriminator |
判别式联合 enum |
| 契约工件 SHA-256 | 文件内 CONTRACT_SHA256 常量(哈希钉) |
两个刻意的设计取舍:
- 请求严格、响应宽容:序列化只发契约允许的字段;反序列化时缺失/为 null 的字段取默认(客户端可以独立于服务端先行发布),但类型错误或未知 enum 值仍然报错——宁可失败也不静默降级;
- 不依赖 serde derive:
to_json/from_json全部手写生成,让"宽容读、严格写"的不对称显式可见,而不是靠属性宏隐式兜底。
每次重新 vendor 契约时,标准流程只有一条命令(见 contracts/sync_from_inferenceinfra.py 头部说明):
python3 contracts/sync_from_inferenceinfra.py --from /path/to/InferenceInfra
它会:拒绝上游脏工作树(保证戳上的是真实 commit)→ 抽取并盖溯源戳 → 重新生成绑定 → 原子性提交两个产物。若本地生成文件有未提交改动,同样拒绝覆盖(除非 --force),防止同步把在途工作静默冲掉。
四、CI 漂移检测:每一层都有"看门人"
这套体系真正的精髓在于:每一对"契约 ↔ 派生物"都有独立的机械校验,任何一层脱节都会让 CI 失败。核心门禁在 ci.yml 的 distribution job 里,逐条看:
4.1 哈希钉校验:绑定文件没被手改
tests/test_wally_contract.rs 把 wally-cli-v1.openapi.json 的 SHA-256 与生成文件里的 CONTRACT_SHA256 常量直接对比。有人手改了绑定或替换了契约而忘了重新生成,这一步立刻失败。
4.2 行为级校验:10 个真实请求 vs 契约工件
tests/test_wally_contract.rs 更进一步——不信任"人写的 URL 清单",而是驱动真实的 ConsoleClient 发出全部 10 个操作,用捕获型 transport 截获请求,再逐一对照工件本身:路径模板逐段匹配({request_id} 通配),query 参数名必须在契约里具名。参数改名、路径挪动、操作被上游删除,都会在这里而不是"某个人终端上的 404"暴露。
4.3 溯源锁校验:Wally CLI lock OK
contracts/sync_from_inferenceinfra.py 的 --check 是自包含(hermetic)CI 门禁:核对溯源戳四字段齐全 → 调生成器 --check 确认 console_contract.rs 与已提交契约一致 → 确认 decisions 绑定同步,全部通过才输出 Wally CLI lock OK。而 tests/test_contract_sync.py 连这个检查器本身也做测试:删掉任一溯源字段必须被拒绝、用"替身契约"跑通时绝不允许输出 lock OK(防止"没看过已提交 pin 的运行声称锁是好的"这类回归)。
4.4 版本一致性:versions.toml 是唯一锚点
versions.toml 是全仓唯一的版本/pin/runner 镜像来源(产品版本、kit 五平台 SHA-256、IDL schema 锁、Swift SDK commit、runner 镜像……)。但 Cargo、rustup、Homebrew、Swift Package、CI workflow、install.sh 各自读各自的文件,从不打开 versions.toml。scripts/ci/check-versions.py 就是为此存在:逐一比对 Cargo.toml 版本、rust-toolchain.toml channel、Homebrew formula 版本与下载 URL、Swift 包的 exact pin、workflow 中 SDK checkout 的完整 ref、install.sh 的 glibc 下限——任何一处"只改了一边"都失败 CI。
4.5 Golden 回放:CLI 表面字节级不变
tests/golden/README.md 记录了 365 个 wally 调用的字节级 stdout / stderr / 退出码基线,tests/cli_golden.rs 在隔离环境逐条回放,任何输出差异即失败。CI 另有一个 ledger 门禁 scripts/test/test-ledger.py 保证"每个 C++ 测试用例都有 Rust 对应物",防止移植过程中用例静默丢失。
发布阶段还有两道收尾:scripts/release/verify-release-assets.py 校验发布资产完整性,scripts/release/check-linux-abi.py 按 versions.toml 的 [linux_abi] 段检查 ELF 符号版本不越过 glibc/GLIBCXX 下限——保证老发行版装得起来。
五、这套实践给普通项目的启示
- 契约即代码:先加操作到契约,再消费生成的绑定,顺序反了就不合并;
- 哈希钉是廉价的强保证:生成物里嵌入源工件 SHA-256,一行 assert 就能锁死"绑定 ↔ 契约"关系;
- 校验器也要被测试:对"漂移检测脚本"本身写拒绝路径测试,防止门禁悄悄失效;
- 溯源戳要么全有要么全无:半截溯源(只有 commit 没有 branch)写出的 pin 永远过不了自己的
--check,这类错误应在生成时拦截而不是在 CI 事后暴露; - 单一锚点 + 全量比对:versions.toml 只写一份 pin,但每个"读不到它的工具"都配一条一致性检查。
完整的多平台验证矩阵可参考 docs/VERIFICATION.md,跨 macOS / Windows / Linux 的 CI 编排见 .github/workflows/ci.yml。
六、关键路径速查
| 模块 | 路径 |
|---|---|
| CLI 契约抽取器 | contracts/extract-cli-contract.py |
| 绑定生成器 | contracts/generate_console_binding.py |
| 契约同步 / CI 门禁 | contracts/sync_from_inferenceinfra.py |
| 已钉的 CLI 契约 | contracts/wally-cli-v1.openapi.json |
| Protobuf 边界与锁校验 | src/io/proto.rs · build.rs |
| 契约行为测试 | tests/test_wally_contract.rs · tests/test_contract_sync.py |
| 版本锚点与漂移检查 | versions.toml · scripts/ci/check-versions.py |
| 规则原文(P0 契约先行) | AGENTS.md |


