這些是 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"]}]}
看一下 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"}]}
這些字串是重建版本自己的。只有 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)