架構

SoyaOS 是一份能扮演三種角色的二進位。部署,不過是這三種角色組成的某一種型態。無論你是在筆電上跑 solo 還是在封閉機房裡跑 enterprise-private,角色邊界和角色間協議永遠不變——變的只有拓樸。

三種節點角色

Comet

Comet 是短生命週期的工作節點。它跑一次 Agent 呼叫、把輸出串流出來,然後退出。Comet 是無狀態的——從 Moon 拉取 SoyaPack 套件、掛載沙箱化的 /workdir,過程中持續發出 Scope 事件。

心智模型:Comet 就是為一次 Agent 執行準備的、被嚴格塑形的 kubectl exec。

Comet 具體做的事:

• 透過出網 HTTPS WebSocket 訂閱一個 Moon,等任務。
• 把 SoyaPack 具現化到暫存目錄,驗證簽名,能力白名單在本機不可滿足時直接拒絕執行。
• 透過同一個 WebSocket 把 stdout 與 Scope 事件回流。
• 超過 idle_timeout(預設 300s)或 max_runs(預設無限)後自動退出。

Moon

Moon 是單租戶的控制面。它承載開發者和使用者對話的 API 表面、託管 SoyaPack 倉庫、簽發 API Key、轉發 Scope 事件。Moon 不自己跑 Agent——它把任務派發給 Comet。

心智模型:Moon 是「團隊工作區」。一家公司 / 一個工作室 / 一戶人家配一個。

Moon 內部元件:

• OpenAI 相容端點(/v1/chat/completions)——接收 model: "soya:*" 請求,解析到具體 SoyaPack 版本,挑一個 Comet,回傳串流回應。
• SoyaPack 倉庫——版本化、內容定址的套件,後端是 S3 相容物件儲存。
• 鑑權表面——簽發 API Key 與能力 token;push 時校驗套件簽名。
• Scope broker——把每次執行的事件多工給訂閱者(Studio、開發者門戶、webhook)。

Planet

Planet 是聯邦根。它持有身分(你是誰)、計費(若有)、跨 Moon 路由。在 solo 部署裡沒有獨立 Planet——Planet、Moon、Comet 摺疊到一個行程。

心智模型:Planet 是「星座運營方」。單租戶部署可選不用。

Planet 的職責:

• 身分——使用者與 Moon 的 OIDC 簽發方;簽 SSO assertion。
• 路由——把租戶 URL(tenant.moon.example.com)對應到具體的 Moon。
• 跨 Moon 合約——唯一有權授權某個 SoyaPack 在源租戶之外的 Moon 上執行的實體。

一次請求是怎麼流動的

1. 客戶端呼叫 Moon 上的 OpenAI 相容端點:POST /v1/chat/completions,model: "soya:compo"。
2. Moon 把 soya:compo 解析到具體 SoyaPack 版本(如 soya:[email protected]),挑一個熱 Comet(或冷啟)。
3. Comet 在沙箱裡執行 Agent,依能力白名單呼叫上游 LLM,把 Scope 事件經 Moon 回流。
4. Moon 把事件多工給訂閱者(Studio、開發者門戶、webhook)。
5. Agent 完成後,Comet 發出最終產物 JSON,自動退出(或依 idle_timeout 回熱池)。

一次實際的事件軌跡

一次 soya:compo 呼叫的 Scope 事件流大致是:

00.000 run_started        run_id=run_018f… pack=soya:[email protected] comet=cmt-a3
00.012 stage_started      stage=outline
00.087 tool_called        tool=fetch_reference  args={url:…}        # 能力檢查:egress.host
00.412 tool_completed     tool=fetch_reference  ok=true
00.514 llm_request        upstream=claude-sonnet-4-6  prompt_tokens=1842
01.823 llm_response       completion_tokens=612
01.834 stage_completed    stage=outline  artifacts=[outline.v1]
01.835 stage_started      stage=writer
…
04.219 run_completed      ok=true  artifacts=[outline.v1, guide.v1]

每條事件都是 JSON,envelope 一致(run_id、ts、kind),且都由 Comet 的執行 Key 簽名——詳見 Scope 事件與可觀測性。

為什麼這樣切?

• 擴縮型態:Comet 是牛群,Moon 是寵物,Planet 是接近寵物的存在。一個 Moon 後面可以掛百萬 Comet。Moon 單實例垂直擴展到約 1 萬並發;再往上就按租戶分片到多個 Moon。
• 安全:每個 Agent 都跑在 Comet 的能力白名單裡;Moon 永遠不執行使用者程式碼。被攻破的 Comet 拿不到 Moon 的祕密——Comet 只看到自己那條短期執行 Key。
• 聯邦:多個 Moon 可以掛在同一個 Planet 之下,也可以在 enterprise-cloud 部署裡向多個 Planet 匯聚。Planet 故障不會把 Moon 拖下水——Moon 快取身分憑證,在憑證過期前持續服務。

角色到版本的對應

完整矩陣見版本;Comet 能做什麼、不能做什麼見能力與沙箱。

在 GitHub 上編輯本頁