趁 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 介面，而不是在其中一套繫結裡繞過不對稱。

雙流工作流程怎麼運作

我為代理人多儲存庫開發敲定的模式：

每個儲存庫一條代理人佇列。 執行環境有自己的議題佇列，SDK 有自己的議題佇列，文件有自己的。每個代理人在自己的儲存庫裡工作。沒有任何單一代理人試圖在一個 PR 裡橫跨兩個儲存庫的接縫。

跨儲存庫協調發生在議題層級。 當一個功能需要兩個儲存庫都改動時，同時開立兩個相互耦合的議題，附上交叉引用。執行環境的 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 和執行環境達到對等。大週末。是對的那種週末。