DEV Community

Cover image for 為什麼 osFoundry 在 Codex 列出的每一頁都附上 record schema?
BBT for BBT 繁體中文

Posted on

為什麼 osFoundry 在 Codex 列出的每一頁都附上 record schema?

這些是 Codex CLI 連線從 osFoundry 拿到的 record channel 工具,內容取自公開 MCP endpoint 的列表。資料是 2026-11-09 用未驗證的 tools/list 抓下來的,只保留跟本文有關的欄位:

{"name": "list_record_items",
 "description": "List the schema and a bounded page of item previews from one granted record channel. Use read_record_item for the complete values.",
 "inputSchema": {"required": ["record_channel_id"],
   "properties": {"record_channel_id": {"type": "string"}, "before_id": {"type": "string"},
                  "limit": {"type": "integer", "minimum": 1, "maximum": 50}}},
 "annotations": {"readOnlyHint": true}}

{"name": "read_record_item",
 "description": "Read one item by ID from a granted record channel and return its current version.",
 "inputSchema": {"required": ["record_channel_id", "item_id"]}}

{"name": "edit_record_item",
 "description": "Update validated fields in one record item. Supply the version from read_record_item; concurrent changes are rejected.",
 "inputSchema": {"required": ["record_channel_id", "item_id", "values", "expected_version", "idempotency_key"],
   "properties": {"values": {"type": "object"}}},
 "annotations": {"readOnlyHint": false, "destructiveHint": true},
 "securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]}
Enter fullscreen mode Exit fullscreen mode

看一下 values。它就只是 {"type": "object"}。工具的 schema 沒辦法說明一個 channel 有哪些 key、哪些是 Select 欄位、Points 可以放什麼,因為這些每個 channel 都不同,而且有人編輯 Schema 分頁時就會改變。Codex 唯一能得知這些的地方,是 list 工具描述的第一行:schema 會跟著頁面一起回來。本文接下來在一個重建版本上量測這樣做換來什麼,以及同樣這四個工具裡的另外兩個選擇:用 before_id cursor 而不是 offset,以及一個可以回頭查的 event log。

什麼是有效的值?

欄位型別是固定的。osFoundry 前端的 packages/shared/src/types/record.ts 把 RecordChannelFieldType 定義成 16 種型別:text、number、date、boolean、email、phone、url、select、multi_select、currency、percentage、rating、relation、file、json 和 formula。每個欄位都帶有 is_required、is_unique 和依型別而定的 config:text 用 max_length,number 用 min/max,rating 用 max_stars,兩種 select 型別用 options,formula 用 expression。

最容易讓 agent 踩雷的是 Select。一個選項是 {value, label, color}。存進去的是 value,使用者看到的是 label。RecordDataGrid.tsx 用 options.find((o) => o.value === params.value) 渲染 select 儲存格,找不到相符的就退回成在灰色 chip 上顯示 String(params.value)。所以如果寬鬆的檢查讓 "In progress" 進到一個值是 in_progress 的欄位,grid 就會顯示一個看起來對、實際上錯的東西:沒有顏色,而且任何依值分組或篩選的功能都看不到它。一個只看過 grid 上的 label、或只看過某個人訊息的模型,送出來的就會是 label。總得有人說不。

拒絕訊息應該長什麼樣子?

osFoundry 的 record API 對失敗的呼叫回傳 {ok: false, error: {message}}。桌面 app 給內建 agent 用的 record 工具(src-tauri/src/record_tools.rs)會把這則訊息原封不動交給模型,註解也寫了原因:API 的訊息 "names the field that failed validation, which is usually enough for a self-correcting retry." 它的 unit test 用 values.status is not a valid option 當例子。

「usually enough」是可以量測的。重建版本在拒絕訊息裡試了四種詳細程度:

  • terse:{"error": "validation_failed"}
  • field:哪些 key 沒通過
  • values:key、原因,以及允許的選項值或範圍
  • labels:同上,再加上每個選項的 label

這是「values」等級,直接取自執行結果:

{"error": "validation_failed", "fields": [
  {"key": "status", "message": "values.status must be one of the option values, got \"In progress\"",
   "allowed": ["new", "triaged", "in_progress", "fixed", "wont_fix"]},
  {"key": "owner", "message": "values.owner must be one of the option values, got \"Aiko\"",
   "allowed": ["aiko", "mika", "ren"]},
  {"key": "points", "message": "values.points must be between 0 and 13, got 20", "min": 0, "max": 13},
  {"key": "due", "message": "values.due must be a date as YYYY-MM-DD, got \"Friday\""},
  {"key": "age_days", "message": "values.age_days is a formula field and is computed, not written"}]}
Enter fullscreen mode Exit fullscreen mode

這些字串是重建版本自己的。只有 values.<key> 這種命名方式沿用 osFoundry。

重建版本

這裡沒有執行任何 Codex binary。record_store.py 在 in-memory sqlite 上實作了 list_record_items、read_record_item、edit_record_item 和 poll_resource_events,工具名稱、參數名稱和限制都跟正式環境一樣。欄位型別和 config key 來自 record.ts。preview 長度(120 個字元)、回傳結果的格式和所有驗證規則都是重建版本自己定的。一次編輯在 BEGIN IMMEDIATE 裡執行:idempotency 查詢、版本比對、驗證、merge、版本遞增、寫入 event、commit。任何問題都會 rollback 整筆編輯。

triage.py 是一個照腳本跑的 Codex。它處理一個有 11 個欄位的 bug tracker(範例:ticket、title、description、status、owner、severity、points、area、due、reporter、age_days),每次執行 200 個 New item,seed 1–5。每個 item 都會拿到一個用人話寫的 triage 意圖:"In progress"、"Aiko"、"S2 Major" 或只寫 "major",points 從 {1, 2, 3, 5, 8, 13, 20} 裡挑,due 是 "Friday" 或 ISO 日期,外加一個 area。agent 要嘛照原樣送出這些字,要嘛先透過 schema 把 label 對應到 value。被拒絕時,它會修正拒絕訊息讓它能修的部分,放掉修不了的,並把該欄位標記給人處理。它從不把數字硬夾到範圍內。Python 3.9.6,Apple M1。

頁面裡附 schema 有差嗎?

1,000 個 item,每個要填 6 個欄位:

Agent 有讀 schema 拒絕訊息內容 存進去的欄位(共 6,000) 留給人處理 每個 item 的編輯呼叫數
否 什麼都沒有 1,363 (22.7%) 4,637 7.00
否 哪個欄位 1,363 (22.7%) 4,637 2.00
否 欄位、原因、允許的值 5,361 (89.3%) 639 2.00
否 欄位、原因、值和 label 5,857 (97.6%) 143 2.00
是 什麼都沒有 5,857 (97.6%) 143 1.86
是 哪個欄位 5,857 (97.6%) 143 1.14
是 值,或值和 label 5,857 (97.6%) 143 1.14

97.6% 是天花板。剩下的 143 個是那些人說要 20 points、但欄位上限只到 13 的 item。這些本來就該被拒絕,而且每一列都確實拒絕了。

讀過 schema 的 agent,不管拒絕訊息寫什麼都能碰到天花板。它的第一次編輯只會因為那 143 個超出範圍的 points 失敗。沒有 schema 的話,每一次第一次編輯都失敗:status、owner、severity 和 area 都是 label,一半的 due 日期是 "Friday"。之後能不能救回來,完全取決於錯誤訊息。沒有允許值的話,「哪個欄位」毫無用處:agent 知道 status 錯了,卻不知道什麼才對,只好放掉。有允許值但沒有 label 可以到 89.3%。那 639 個失誤是 "Won't fix" 對上 wont_fix,以及 "major" 對上 s2。這兩種都沒辦法從值的清單比對出來。拒絕訊息裡有 label 的話,沒有 schema 的 agent 也能追上,代價是每個 item 多一次呼叫。沒有 schema 又只給簡短錯誤,會讓 agent 把每次編輯拆成六次單欄位編輯,每個 item 7 次呼叫,結果存進去的還不到四分之一。

所以 schema 是驗證設計的一半。伺服器端的檢查擋下錯誤的值。跟著每一頁一起送來的 schema,則是讓第一次嘗試就能做對的關鍵。在這個 channel 裡它每頁的成本是 1,705 bytes,大約是一頁 50 筆 preview、16.7 KiB 的 10%。

為什麼用 preview,又為什麼最多 50 筆?

一頁 50 筆 preview 是 16.7 KiB。把這 50 個 item 完整讀出來是 124.6 KiB,因為這裡的描述長度在 300–4,000 個字元之間。做 triage 時,preview 就夠用來決定要打開哪些:status、ticket、標題開頭。Codex 只打開它要改的那些。限制頁面大小也能避免大型 channel 把 context 塞爆。工具描述寫的是 "bounded",schema 寫的是 maximum: 50。

為什麼用 before_id 而不是 offset?

Codex 在讀的時候,大家還是會繼續開 bug。重建版本以每頁 50 筆、從最新開始分頁讀 600 個 item,並在每一頁之後變動 channel。五次執行:

每頁之後的變動 分頁方式 頁數 item 讀取數 重複讀取 從未看到
新開 2 個 bug offset 65 3,120 120 0
新開 2 個 bug before_id 60 3,000 0 0
刪除 2 個已讀 item offset 60 2,890 0 110
刪除 2 個已讀 item before_id 60 3,000 0 0

開頭新增的 item 會把所有東西往下推,所以 offset 分頁會重疊,Codex 會把部分 item triage 兩次。刪掉已經讀過的東西會讓所有東西往上移,所以下一個 offset 頁面會從沒人讀過的 item 後面開始。從頭到尾都存在的 110 個 bug 從來沒被看到。cursor 指的是最後讀到的那個 item,別處的新增或刪除都移不動它。在這輪處理期間新開的 item 不會出現在任何一頁上。event log 就是為此而存在。

Codex 怎麼找出上一輪之後改了什麼?

在一輪處理完 400 個 item 之後,大家編輯了 30 個 item、新開了 12 個、刪了 3 個。找出這 45 個的兩種方式:

策略 呼叫數 回傳資料量 找到
每一頁重新 list,比對版本 9.0 135.8 KiB 45 / 45
從儲存的 sequence 開始 poll_resource_events 1.0 4.6 KiB 45 / 45

腳本用 assert 確認兩種方式找到的都剛好是那 45 個。polling 的成本等於變動的量。重新 list 的成本每次都等於整個 channel 的大小。兩次執行之間要保存的狀態只有一個整數,也就是最後的 sequence。

那版本檢查呢?

簡單帶過,因為它跟 Notes 和知識庫的運作方式一樣。在 1,000 次編輯中,有人在 Codex 讀取和寫入之間改動了每 8 個 item 裡的 1 個;用讀取時拿到的版本,產生 131 次衝突,覆蓋掉 0 個人為修改。在寫入前一刻才重新讀版本,衝突是 0 次,但 131 個修改全被蓋掉。發生衝突後,照腳本跑的 Codex 會重新讀取,看到 item 已經是 in progress,就只補上 severity。

驗證的成本是多少?

2,000 次有效的六欄位編輯,跑三次:有驗證時每次編輯的中位數是 72.8–75.1 µs,把 validate() 換成 stub 後是 41.9–42.4 µs。差距來自 transaction 裡的 schema 查詢和逐欄位檢查。跟一次動輒好幾秒的模型回合比起來,根本感覺不到。

如果你要自己串接

  • 把 schema 跟 listing 一起回傳,每一頁都附,不要放在 agent 可能會跳過的另一個呼叫裡。量測到的差距是每個 item 一次被拒絕的編輯。
  • 在拒絕訊息裡放入允許的選項值和它們的 label。只有欄位名稱,agent 什麼都修不了。
  • 只要有任何欄位失敗就拒絕整筆編輯,並說明是哪些欄位。回報成功的部分儲存,會把 agent 弄錯的欄位藏起來。
  • 永遠不要在伺服器端轉換 label 或把數字夾到範圍內。"major" 和 "20 points" 是該問人的問題,不是交給 matcher 的。
  • 用穩定 ID 上的 cursor 分頁,並給 agent 一個 event sequence 供下次執行使用。
  • 在真的需要之前,不要把 schema 變更、新增和刪除放進 agent 的工具裡。只有在 agent 無法放寬欄位時,驗證才有意義。

osFoundry 對底層協定的簡短定義在它的 MCP 詞彙條目。schema 所來自的 record channel 畫面,請見 Records 頁面。

Top comments (0)