Wally 工程实践完整版:OpenAPI 3.1 + Protobuf 契约先行与 CI 漂移检测如何保障每次发布

原创2026-10-11 12:52:421,420 阅读

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 工程实践:编码 Agent 通过契约化 CLI 接入托管模型完成调试

一、为什么 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 就失败。

Wally 的双契约边界:Protobuf 管 SDK,OpenAPI 管 HTTP

二、两条契约线:OpenAPI 3.1 管 API,Protobuf 管 SDK

2.1 OpenAPI 3.1 线:控制台 API 的"切片契约"

完整控制台契约 control-plane-v1.openapi.json 有 8000 行,但 CLI 只用其中 10 个操作(授权开始/轮询/刷新/吊销、/v1/me、用量、目录、取消请求等)。Wally 的做法不是整份 vendor,而是按操作抽取:

每份抽取结果都打上 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 常量(哈希钉)

两个刻意的设计取舍:

  1. 请求严格、响应宽容:序列化只发契约允许的字段;反序列化时缺失/为 null 的字段取默认(客户端可以独立于服务端先行发布),但类型错误或未知 enum 值仍然报错——宁可失败也不静默降级;
  2. 不依赖 serde derive:to_json / from_json 全部手写生成,让"宽容读、严格写"的不对称显式可见,而不是靠属性宏隐式兜底。

每次重新 vendor 契约时,标准流程只有一条命令(见 contracts/sync_from_inferenceinfra.py 头部说明):

python3 contracts/sync_from_inferenceinfra.py --from /path/to/InferenceInfra

它会:拒绝上游脏工作树(保证戳上的是真实 commit)→ 抽取并盖溯源戳 → 重新生成绑定 → 原子性提交两个产物。若本地生成文件有未提交改动,同样拒绝覆盖(除非 --force),防止同步把在途工作静默冲掉。

Wally 契约管线:上游契约 → 抽取 → 生成 Rust 绑定 → 哈希钉

四、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 下限——保证老发行版装得起来。

五、这套实践给普通项目的启示

  1. 契约即代码:先加操作到契约,再消费生成的绑定,顺序反了就不合并;
  2. 哈希钉是廉价的强保证:生成物里嵌入源工件 SHA-256,一行 assert 就能锁死"绑定 ↔ 契约"关系;
  3. 校验器也要被测试:对"漂移检测脚本"本身写拒绝路径测试,防止门禁悄悄失效;
  4. 溯源戳要么全有要么全无:半截溯源(只有 commit 没有 branch)写出的 pin 永远过不了自己的 --check,这类错误应在生成时拦截而不是在 CI 事后暴露;
  5. 单一锚点 + 全量比对: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
登录后查看全文
wally