在 SDK 出现漂移之前就让它追上来

在项目一开始就建好的一致性,比发布之后再事后补上的一致性便宜一千倍。RakuAI 的绑定与运行时共同开发,在每一个 PR 上都设有关卡——所以你的绑定选择永远不会让你以后失去某个功能。

我一直对一种我曾亲眼见过扼杀多仓库项目的具体失败模式感到紧张,而那正是这个周六早上的起始状态。运行时某个周末加了一个功能,SDK 却要到下个月才追上来。一个绑定里的示例能用,另一个绑定里的示例却在悄悄退化。版本号不再匹配。每个仓库上的 CI 都是绿色的,但它们之间的集成却是坏的。

那部电影的结局是两年之后的一次重新平台化。我不打算这样构建 Raku。这个周末的计划是,在这道差距形成之前就让 SDK 追上运行时,并留下足够的基础设施,让这道差距再也不可能形成。

SDK 那边落地了什么

SDK 迎来了一个大周末。运行时那边比较安静(它的大推进在上个周末就已经完成,PR #104 落地了 VIO/SLAM、QoS 调度器、性能测试框架和遥测管道)。这个周末是绑定的追赶周末。

亮点:

• SDK v0.2.0 的 Unity + Unreal 一致性,附带全面的验证
• 两种绑定中的 HelloAR 示例,带有明确的故障切换演示
• 增强的 Unity 示例交互,支持多对象和交互式教程
• 增强的 Unreal API 文档,附带全面的使用示例
• 将 Agent-Queue Seeder 工作流移植到 SDK 仓库
• 用于 SDK v0.2 包发布的 CI/CD 流水线,带有语义化版本控制和发布自动化
• SDK v0.2 文档与快速入门,附带仓库主页和 wiki 集成
• Epic #42:SDK 与运行时一致性测试基础设施完成

Epic #42 的工作是头条。它是一个针对相同规范场景来检验两种绑定的测试套件,确认它们行为一致。Unity HelloAR 和 Unreal HelloAR 各自加载一个模型,将其锚定到一个标记上,渲染它,并报告遥测数据。一致性测试确认两种绑定报告的遥测数据在容差范围内,并且同一个模型在两者中都能正确加载。如果运行时的某次变更破坏了一个绑定却没破坏另一个,一致性测试会捕捉到它。

为什么一致性测试在这个阶段很重要

Raku SDK 还没有发布。没有公开版本。距离团队之外有人针对它编写代码,还有几个月的时间。那么为什么现在就要在意一致性?

因为在项目一开始就建好的一致性测试,比事后补到一个已经发布的项目上的一致性测试便宜一千倍。运行时新增的每一个 C API,从第一天起就会通过两种绑定被检验。每一个触及公共界面的 PR 都必须要么证明一致性测试仍然通过,要么解释为什么没通过。成本是每个 PR 几分钟。省下的是下游几个月的排查工作,不然当一个合作伙伴报告一个只能在 Unreal 上复现的问题时,团队就得去弄清楚原因。

另一个原因是,一致性测试能暴露架构问题。当一个功能在 Unity 里容易暴露、在 Unreal 里却很难时,问题通常不在绑定本身。而在运行时的 C API 里。这种不对称就是一个信号。这个周末,一致性测试暴露了两个这样的不对称,而两次的修复方式都是改变运行时的 API 界面,而不是在某个绑定里绕开这种不对称。

双流工作流是怎么运作的

我目前为智能体的多仓库开发所敲定的模式:

每个仓库一个智能体队列。 运行时有自己的 issue 队列,SDK 有自己的 issue 队列,文档有自己的。每个智能体在自己的仓库内工作。没有单个智能体试图在一个 PR 里跨越两个仓库之间的接缝。

跨仓库协调在 issue 层面进行。 当一个功能需要在两个仓库中都做变更时,两个相互耦合的 issue 会同时被提交,并带有交叉引用。运行时的 PR 先落地。SDK 的 PR 会被搁置,直到运行时的 PR 被合并。然后 SDK 的 PR 针对新的运行时构建进行更新、重新测试,并在数小时内合并。

每种绑定中都有一套规范示例。 Unity HelloAR 和 Unreal HelloAR 是规范性的测试载体。每一次 C API 变更都必须在两者中都被检验。这些示例不是事后的附加品。它们是公共界面的一部分。

把一致性测试当作 CI 关卡。 这个周末以 Epic #42 落地的一致性测试基础设施,现在会在每一个触及任一仓库的 PR 上运行。如果一次运行时变更没有在两种绑定中都被检验,该 PR 就会被阻止合并,直到一致性测试证明这次变更在两边都能正常工作。

这对构建者意味着什么

如果你是一个考虑将来在 Raku 上构建的 Unity 开发者,这个绑定正在与运行时共同开发,而不是在其身后追赶。Unity API 不会滞后。示例今天就能用,到 1.0 版本时也一样能用。

如果你是一个 Unreal 开发者,同样如此。Unreal 绑定与 Unity 绑定拥有完全相同的优先级。一致性测试证明了这一点。

如果你正在决定从哪种绑定开始,答案是无论哪种更适合你团队现有的技能。一致性测试就是让我能够承诺绑定选择不会让你以后失去功能的原因。

如果你是一个考虑这个引擎如何集成进你的技术栈的合作伙伴,这个界面将会是 C API 加上 Unity 绑定加上 Unreal 绑定,最终还会再加上几个(Godot 在路线图上,web 原生也在路线图上)。每一种新绑定在发布之前,都必须针对这套规范集合建立自己的一致性测试。这份纪律已经被内建其中。

坦诚地说说还有哪些粗糙之处

一致性测试覆盖了基础部分。基于标记的锚定在两种绑定中都能用。HelloAR 在两者中都能加载和渲染。遥测在两者中都能正确报告。更难的一致性问题——完整的手部追踪、语音管道、多人姿态同步——目前还没有被一致性测试覆盖,因为运行时那边还没做完。等它们做完了,就会纳入同一道关卡。

SDK v0.2 发布的 CI 流水线已经搭起来了,但实际发布的包还没有稳定到可以推荐进行集成的程度。整个十月都把这个 SDK 当作开发中的东西对待。到十一月,一致性测试会深入到足以让这个建议发生变化。

我想从这个周末记住的东西

两件事。

多仓库一致性是一种纪律,不是一个功能。 SDK 追上运行时的这个周末,运行时里没有任何闪亮的新功能。没有发生任何可演示的事情。发生的事情是,SDK 不再滞后了。这正是那种一旦被忽视就会扼杀一个多仓库项目的工作。我想把它写下来,这样下次运行时的大功能落地时,我就不会忘记。

智能体队列是按仓库扩展的。 在同一个工作流里跨两个仓库运行同一个队列,产生了我上个周末在运行时层面描述过的那种早期版本的合并冲突泥潭。按仓库分离队列消除了几乎所有这种情况。当智能体的问题空间被恰当划分之后,它们就不再互相绊脚了。

周六晚上,SDK 和运行时已经达到一致。大周末。正确类型的周末。