下面是 Claude Code 要把一個小 App 放進 osFoundry 雲端 Room 時呼叫的工具,內容就是線上伺服器在 tools/list 裡列出的樣子(不帶 token 取得,只保留重要的部分):
{
"name": "propose_room_snippet_app",
"description": "Prepare a Room snippet with source files. It appears in the cloud Room launcher only after its owner reviews and approves the full code in osFoundry.",
"inputSchema": {
"type": "object",
"properties": {
"room_id": {"type": "string"},
"name": {"type": "string", "maxLength": 200},
"files": {"type": "object", "additionalProperties": {"type": "string"}},
"idempotency_key": {"type": "string", "minLength": 8, "maxLength": 128}
},
"required": ["room_id", "name", "files", "idempotency_key"],
"additionalProperties": false
},
"annotations": {"readOnlyHint": false, "destructiveHint": true, "openWorldHint": false},
"securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]
}
它旁邊還有四個 Room 工具:read_room、list_room_apps(limit 1–50)、read_room_app_status(需要 room_id 和 instance_id),以及 propose_room_repo_app(用 repository_id 和 version_id 取代 files)。三個讀取工具都是 osfoundry:read、readOnlyHint: true。兩個提議工具都是 osfoundry:write、destructiveHint: true,這也是 Claude Code 在呼叫前會先詢問使用者的原因。
重點在動詞。這個工具不會在 Room 裡建立任何東西。它建立的是一份提議,要由人把它變成 Room 的分頁。以下會談到:schema 強制了什麼、又把什麼留給伺服器,一份提議有多大,為什麼 idempotency key 是必填,以及 client 該怎麼等人回應。所有數據都是用 Python 寫的替代 client 量測的,因為這台 Mac 上沒有安裝 claude 執行檔。
schema 擋得住什麼?又把什麼留給伺服器?
room_proto.py 用 jsonschema 依照上面那份線上的 inputSchema(存成 tools-list.json)驗證呼叫。另外兩條規則來自 osFoundry 處理 snippet 提議的方式。Room runtime 的進入點 src/App.tsx 必須存在。而且每個路徑都必須是安全的相對路徑。腳本在 schema 之外再套用這兩條規則:
$ uv run --with jsonschema --with tiktoken python3 room_proto.py
== validation ==
ok PASS
no App.tsx REJECT rule: src/App.tsx missing
absolute path REJECT rule: unsafe path '/etc/hosts'
dot-dot path REJECT rule: unsafe path 'src/../../x.ts'
backslash path REJECT rule: unsafe path 'src\\x.ts'
name 201 chars REJECT schema: 'nnnn…' is too long
key 7 chars REJECT schema: 'abcdefg' is too short
extra field REJECT schema: Additional properties are not allowed ('visibility' was unexpected)
non-string file REJECT schema: {'a': 1} is not of type 'string'
caught by published schema: 4, needs server rule: 4
有一半的錯誤呼叫能通過 JSON Schema。files 物件裡的路徑 key 沒辦法用 additionalProperties 限制。你得用帶 pattern 的 propertyNames,而要寫一個在正規化之後還能擋掉 .. 的 pattern,很快就會變得很醜。所以 schema 只寫「字串的 map」,key 交給伺服器判斷。不過最外層的 additionalProperties: false 確實有發揮作用。模型如果自己編出 "visibility": "public",會直接收到 schema 錯誤,而不是被默默忽略的欄位。
如果你在寫 client,呼叫前請先跑一樣的檢查。被拒絕的提議會浪費一次來回,更糟的是,還得花 output token 把檔案重寫一遍。
一份提議有多大?
範例裡的 App 是一個站立會議計時器:src/App.tsx(63 行)和 src/styles.css(14 行)。
== size ==
src/App.tsx 2021 B 63 lines 583 tok
src/styles.css 1046 B 14 lines 399 tok
source bytes 3067, envelope bytes 3431, escape+frame overhead 11.9%
argument tokens (cl100k) 1141
2 files: envelope 4463 B, 1394 tok
6 files: envelope 12919 B, 4078 tok
21 files: envelope 44639 B, 14143 tok
tools/list 45368 B for 59 tools; the 5 room tools 3482 B (939 tok)
JSON-RPC 封包比原始程式碼多了 11.9%,大多來自跳脫過的換行和引號。但這不是真正重要的成本。files 裡的每個 byte 都是模型輸出:Claude Code 先寫出檔案,再把它當成工具參數寫第二次。兩個檔案的提議大約是 1,100 個 token 的參數。重複同一個元件做出來的 21 個檔案的 App,則是 14,143。token 是用 tiktoken cl100k_base 計算的,那是 OpenAI 的 tokenizer,所以請當成概略值看待。
schema 沒有公開 files 的 byte 上限。實務上,上限就是審查的人。核准卡片會在 "Review all proposed files (N)" 底下完整列出每個檔案,每個檔案各有自己的捲動框。沒有人會在一張卡片上讀完 21 個檔案。這種規模的東西比較適合用 propose_room_repo_app:它指向同一個專案中 GitNest 儲存庫的固定版本,卡片上放的是 "Review repository code before approving" 的連結,而不是直接貼上程式碼。
審查關卡保證了什麼?
工具描述寫得很直白:snippet "appears in the cloud Room launcher only after its owner reviews and approves the full code"。在 Room 裡,launcher 就是 App 的分頁列。卡片上寫著 "Approval makes this code available in the Room app launcher. Review the files before approving."。按 "Approve and create" 會加入分頁,按 "Decline" 則會捨棄。待審的提議 Room 成員打不開,所以沒審過的 snippet 永遠不會在任何人的 session 裡執行。
這樣一來,重試的問題就落到 client 身上。透過 HTTP 的 MCP 可能在伺服器已經處理完之後弄丟回應。如果 client 接著用新的 key 重試,owner 就會為同一個 App 收到兩張卡片。room_proto.py 用一個依 key 儲存提議的 in-memory 伺服器模擬這種情況,共 1,000 份提議,每個回應有 5% 的機率遺失:
== review gate, 1000 proposals, 5% lost responses ==
random calls 1074 owner cards 1074 duplicates 74 in launcher before approval 0
content calls 1057 owner cards 1000 duplicates 0 in launcher before approval 0
每次嘗試都用新的 UUID 時,1,074 張卡片裡有 74 張是重複的,owner 得自己認出來再拒絕。改用從內容推導出的 key,"snip-" + sha256(room_id, name, files)[:32],重試會帶著同一個 key,重複數量是 0。刻意修改檔案則會產生新的 key 和新的卡片,這正是你要的行為。schema 的 8 字元下限能擋掉像 "1" 這種 key。兩次執行中,都沒有任何東西在核准前進到 launcher。那部分是伺服器的責任,不是 client 的。
Claude Code 該怎麼等 owner?
initialize 只回傳 "capabilities": {"tools": {"listChanged": false}},沒有別的。沒有「你的提議已核准」這類推播。client 有三個選項。可以請使用者核准後告知,可以輪詢 read_room_app_status(或輪詢 list_room_apps 直到新的 instance 出現),也可以針對該 Room 繼續 poll_resource_events,它接受 resource_type: "room"。沒有 token,我沒驗證核准會在那裡寫入哪些事件,所以模擬是輪詢狀態。
輸入是人工審查所需的時間。腳本從中位數 6 分鐘的對數常態分布中抽樣,預算是一小時。這是假設,不是實測,但它的分布形狀(多數人幾分鐘內回應,少數人要半小時)是貼近現實的部分:
== polling while the owner reviews (n=2000, median review 6 min, 1 h budget) ==
review delay p50 357s p95 1816s
fixed 5s calls mean 111.8 lag p50 2.4s p95 4.7s gave up 14
fixed 30s calls mean 19.0 lag p50 14.5s p95 28.4s gave up 14
backoff 5s x1.5 cap 120s calls mean 10.8 lag p50 47.0s p95 111.0s gave up 14
backoff 10s x2 cap 300s calls mean 6.1 lag p50 105.2s p95 273.8s gave up 14
每 5 秒輪詢一次,能在 5 s 內發現核准,代價是每份提議 112 次呼叫,而每次呼叫都是一個花在工具輸出上的模型回合。固定 30 秒的間隔是 19 次呼叫,最差情況延遲 28 秒。用 backoff 並設 2 分鐘上限,可以降到 11 次呼叫,p95 延遲是 111 s。2,000 次審查中有 14 次超過一小時,所有策略都同樣放棄了它們。在互動式 session 中,最省又正確的做法是零次呼叫:用 "approve it under Connected → Needs your approval and tell me"(請在 Connected → Needs your approval 核准後告訴我)結束這個回合,之後只呼叫一次 list_room_apps。只有在 Claude Code 中間還有其他工作要做時,輪詢才划算。
實際的來回時間,給你一個量級參考:從這台位於日本的 Mac 對線上端點,各發出十次未驗證的呼叫。
$ python3 probe.py
initialize HTTP 200 308 B median 680 ms min 358 max 968
tools/list HTTP 200 45368 B median 687 ms min 429 max 1253
tools/call read_room (no token) HTTP 401 337 B median 559 ms min 427 max 847
www-authenticate: Bearer resource_metadata="https://api.osfoundry.io/.well-known/oauth-protected-resource/api/v1/external-mcp", error="invalid_token", error_description="Connect osFoundry to continue"
每次呼叫大約 0.6 s。所以 5 秒的迴圈有十分之一的時間花在網路上,而每次呼叫耗掉的一個模型回合,成本遠高於此。
對 snippet 來說,「build state」是什麼意思?
read_room_app_status 回傳 "the safe launcher and latest build state of one app",不含 config、檔案、log 或 secret。snippet 沒有伺服器端的 build。Room 會在開啟分頁的地方編譯它的檔案:桌面 App 裡是在搭配 Sucrase 的沙箱 iframe 中,瀏覽器裡則是在 Sandpack 沙箱中。儲存庫這條路也是固定版本,它的核准卡片寫著 "This path does not build or deploy a bundle."。兩種提議要等的都是 launcher 裡的項目。build state 要等有人部署這個分頁後才會出現,而部署是在 osFoundry 裡進行的。
為什麼它碰不到本機 Room?
read_room 會回 "Local Rooms are unavailable",initialize 也帶著通用規則:"Local-only data is unavailable to cloud clients."。本機 Room 存在桌面 App 自己的資料庫裡,從不同步。MCP 端點是一個雲端服務,持有以 workspace 為範圍的 OAuth token,沒有任何路徑能連到某一台特定的筆電。要連過去,需要一個由桌面 App 執行的 relay:依裝置和專案個別啟用,有上線/離線狀態,以及指令的 allowlist。工具介面也沒有假裝做得到。同樣的界線也適用於 snippet 內的資料。它的 SDK 儲存空間留在使用該分頁的人的裝置上,而且沒有任何讀取工具會回傳資料庫內容。
如果你要自己串接
- 就算已經公開 schema,也要在伺服器端驗證路徑 key。JSON Schema 能描述「字串的 map」,卻描述不了「安全的相對路徑」,而在這次測試中,一半的錯誤呼叫都是路徑問題。
- idempotency key 要從內容推導,而不是從每次嘗試產生。這樣遺失的回應就不會造成任何成本,真正的修改也依然會有自己的卡片。
- 讓審查者的注意力決定大小上限。如果卡片會顯示每個檔案,snippet 就控制在少數幾個檔案,較大的 App 改用固定的儲存庫版本送出。
- 預設不要讓 agent 為了等人而輪詢。讓它結束回合,等使用者回來時讀一次狀態,只有在它還有其他工作時才用 backoff。
- 讀回的內容要精簡。只回傳身分和 launcher 狀態,絕不回傳 config 或 App 資料,避免狀態查詢變成讀取別人儲存內容的管道。
- 在工具描述中寫明哪些東西碰不到("Local Rooms are unavailable"),讓模型直接告訴使用者,而不是一直重試。
Top comments (0)