DEV Community

Cover image for 為什麼 osFoundry 要 Claude 指定確切的 Slides 分頁,還要每筆引用都帶 key?
BBT for BBT 繁體中文

Posted on

為什麼 osFoundry 要 Claude 指定確切的 Slides 分頁,還要每筆引用都帶 key?

這是 Claude 連線在 osFoundry Notes 上拿到的建立工具,2026-11-09 對公開 MCP endpoint 用未驗證的 tools/list 抓下來,有刪減:

{"name": "create_note_tab",
 "description": "Create a new Slides or Sheet tab in an approved Note. Use the version from list_note_tabs; returns the exact new tab ID for later edits. An optional outline fills a Slides tab. A repeated idempotency key returns the first tab.",
 "inputSchema": {
   "required": ["note_id", "expected_version", "idempotency_key", "tab_type"],
   "properties": {
     "tab_type": {"enum": ["slides", "sheet"]},
     "label": {"type": "string"},
     "slides": {"type": "array", "minItems": 1, "maxItems": 20,
                "items": {"required": ["title"], "additionalProperties": false,
                          "properties": {"title": {}, "body": {}, "notes": {}}}}},
   "additionalProperties": false},
 "annotations": {"readOnlyHint": false, "destructiveHint": true},
 "securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]}
Enter fullscreen mode Exit fullscreen mode

這項工作會用到的另外兩個工具:

{"name": "add_note_source",
 "description": "Add an HTTP or HTTPS citation to the Sources tab of an approved Note. Uses the Note version and an idempotency key; returns the new source ID.",
 "inputSchema": {"required": ["note_id", "expected_version", "idempotency_key", "title", "url"]}}

{"name": "list_note_tabs",
 "description": "List every tab instance and its type. A Note may have multiple Slides or Sheet tabs; use the exact tab ID returned here."}
Enter fullscreen mode Exit fullscreen mode

整個設計靠三句話撐起來:"every tab instance"、"returns the exact new tab ID",以及 "a repeated idempotency key returns the first"。本文接下來用 Python 重建這些工具,量測每一句話各自防掉了什麼問題。Note 版本上的樂觀鎖是另一篇文章的主題,這裡只在它和另外兩者有交集的地方出現。

Claude 實際上能在一張投影片上放什麼?

比桌面 app 內建的 assistant 少。在 osFoundry 裡,Note assistant 的 slide_create_deck_from_outline 和 slide_add_slide(在 apps/web/src/screens/notes/lib/note-surface-tools.ts)可以接受版面配置、項目符號、雙欄內容、表格、圖片,以及五種主題之一。Connector 的 outline 項目只有 title、body、notes,而且 additionalProperties: false。edit_note_tab 提供單張投影片用的 slide_add,和陣列用的 slides_add_outline,兩者都是同樣這三個欄位。

code/note_store.py 會載入存下來的 tools/list 回應,再用一個很小的 validator(required、enum、additionalProperties、minItems/maxItems)檢查 payload。以下是模型很可能會送出的八個 payload:

edit_note_tab    {"operation": "slide_add", "title": "Sources", "body": "3 links"}  -> ok
edit_note_tab    {"operation": "slide_add", "title": "Sources", "index": 0}         -> unexpected index
edit_note_tab    {"operation": "slides_add", "slides": [{"title": "a"}]}            -> operation: not in enum
edit_note_tab    {"operation": "slides_add_outline", "slides": [{... "bullets"}]}   -> slides: [0] unexpected bullets
create_note_tab  {"tab_type": "slides", "slides": "[21 items]"}                     -> slides: maxItems 20
create_note_tab  {"tab_type": "markdown"}                                           -> tab_type: not in enum
add_note_source  {"url": "https://example.org/report"}                              -> missing title
list_note_attachments {"kind": "sources", "limit": 100}                             -> ok
Enter fullscreen mode Exit fullscreen mode

最後一個能通過這個 validator,但過不了完整的 live schema:limit 有 maximum: 50,而重建版沒有檢查這點。slide_add 不能指定位置,create_note_tab 不能建立 Markdown 分頁,超過 20 張投影片的 deck 要分成多次 call。窄的 schema 其實是在決定誰來負責 deck 的樣式:connector 寫內容,桌面 app 裡的人負責套主題和版面。

為什麼要確切的分頁 ID,而不是「那個 slides 分頁」?

因為桌面 app 自己到現在還接受這種捷徑,而捷徑會挑第一個符合的。apps/web/src/screens/notes/types.ts 裡的 resolveTabInstanceId():

if (cfg.some((t) => t.id === rawTabId)) return rawTabId
const byType = cfg.find((t) => t.type === rawTabId)
if (byType) return byType.id
Enter fullscreen mode Exit fullscreen mode

這個 fallback 讓 …/slides 這種舊連結還能用。但對 agent 來說,這代表「編輯 slides」會寫進分頁列上排在最前面的那個 Slides 分頁。新分頁會由 NotesContentPanel.tsx 的 nextTabId() 拿到像 slides-9-mh8z1k2a 這樣的 ID,固定分頁是 markdown、files 和 sources,而使用者可以新增任意多個 Slides 分頁、拖曳調整順序、重新命名,名稱重複也可以(handleRename 只做 trim)。

重建版給一份 Note 放 K 個標籤各不相同的 Slides 分頁。一個寫好腳本的 agent 先列出分頁,選一個 deck 當目標,並記住指向它的 handle:它在分頁列上的位置、它的類型、它的標籤,或它的 ID。在 agent 的兩個回合之間,使用者會隨機做零到兩次變更(移動分頁 40%、把某個 Slides 分頁改名成五個標籤之一 35%、新增 Slides 分頁 25%)。接著 agent 再列一次,並解析它的 handle。每個 K 跑 10,000 次,seed 7:

K 個 deck handle 正確 寫錯 deck 找不到
2 位置 83.7% 16.3% 0.0%
2 類型 50.7% 49.3% 0.0%
2 標籤 85.6% 2.1% 12.3%
2 ID 100% 0 0
5 位置 82.7% 17.3% 0.0%
5 類型 19.7% 80.3% 0.0%
5 標籤 92.1% 3.0% 5.0%
5 ID 100% 0 0

用類型當 handle,正確率果然是 1/K。位置只要有一次拖曳越過目標就會出錯,跟 K 無關。標籤最誘人,因為那就是使用者在 prompt 裡打的字,而且大部分時候都對。但錯的那 2–3% 才是真正麻煩的情況:另一個 deck 現在掛著同一個標籤,agent 寫進去卻完全沒有任何錯誤。「找不到」反而是安全的失敗。ID 只分配一次、永不重複使用,所以使用者在分頁列上怎麼改都不會影響它。

版本檢查不是已經能擋下寫錯分頁嗎?

不能。上面每一種分頁列變更都會讓 Note 版本往上加,所以過期的寫入會被拒絕,agent 會重新列一次。重新列出來就拿到了最新版本,接著它用舊的 handle 對新列表做解析。在重建版裡,這些寫入 100% 都通過版本檢查,包括所有寫到錯誤 deck 的那些。版本證明的是 agent 看過最新的 Note,但完全說明不了 agent 在裡面有沒有找到對的分頁。那部分要靠分頁 ID。

冪等檢查要放在版本檢查之前還是之後?

之前,不然工具說明裡的承諾就破功了。每個 run 呼叫 create_note_tab 50 次,其中 30% 的回應在伺服器 commit 之後遺失,從 client 看起來就是 host timeout。Client 會重送同一個 call。三種 client 策略、兩種伺服器順序,seed 1–3:

伺服器檢查順序 client 的 key 策略 建立的分頁數(送出的 call 數)
先 key,再版本 每次 call 都用新 key 63 (76) / 75 (100) / 62 (74)
先 key,再版本 重試時沿用同一個 key 50 (67) / 50 (81) / 50 (62)
先 key,再版本 遇到 conflict 後換新 key 50 (67) / 50 (81) / 50 (62)
先版本,再 key 每次 call 都用新 key 63 (76) / 75 (100) / 62 (74)
先版本,再 key 重試時沿用同一個 key 50 (79) / 50 (98) / 50 (72)
先版本,再 key 遇到 conflict 後換新 key 72 (94) / 73 (96) / 61 (72)

重送帶的是遺失那次 commit 之前的版本。先檢查版本的伺服器會看到過期版本,於是回傳 conflict,而不是第一次的結果。用合理方式處理 conflict 的 client,也就是重新讀取、把下一次嘗試當成新的意圖並換新 key,這時就會建立出第二個 deck。就算 client 一直沿用同一個 key,也會多送 16–21% 的 call。如果先檢查 key,不管版本是什麼,重送都會回傳原本的分頁 ID。"a repeated idempotency key returns the first tab" 必須是這個意思。

add_note_source 的 key 應該用什麼?

重建版跑了 300 個研究 session。每個 session 有三個回合,每回合引用 8 個頁面中的 6 個,而同一個頁面可能以七種寫法之一回來:結尾多一個斜線、www.、?utm_source=…、#fragment、http://,或沒有 scheme。20% 的回應會遺失,並用同一個 key 重送。

key 存下的 source 數 重複數 每個 session
每筆引用一個新 UUID,重送時沿用 5,400 3,038 10.13
照原樣對 URL 做 hash 4,814 2,452 8.17
對正規化後的 URL 加 Note ID 做 hash 2,362 0 0.00

每筆引用用新 key,只處理得了回應遺失(第一列沒有任何一筆是重送造成的),其他都擋不住。研究在下一個回合又會引用同一個頁面,而每個新回合都是新的 key。照原樣對 URL 做 hash 能抓到完全一樣的重複,但抓不到 ?utm_source= 或結尾斜線。真正能消除重複的 key,是把意圖命名出來:「這個頁面是這份 Note 的一個 source」,也就是對 note_id 加上正規化後的 URL 做 hash(https、小寫且去掉 www. 的 host、不含 fragment、不含 utm_*、不含結尾斜線)。

桌面 app 自己的 Sources 表單做的是比較輕量的版本。NotesSourcesTab.tsx 會用 new URL(...) 正規化輸入的連結,並拒絕已經附加過的連結("This source is already attached")。在重建版裡,用瀏覽器式的 href 比對,可以抓出第一列 3,038 筆重複中的 725 筆。Connector 的 add_note_source 並沒有標明會檢查 URL,所以 agent 要靠 key 來表達這件事。從 URL 推出來的 key 有一個副作用:用更好的描述重新加入同一個頁面,回傳的會是第一筆。要修改它,得去 Sources 分頁。

一次帶 outline 建立,還是一張一張加?

一個 12 張投影片的 deck 的成本,每個 request 都對 live schema 驗證過:

做法 寫入次數 request bytes 每個 deck 的 conflict
create_note_tab 帶 slides 1 1,673 0.070
空的 create + 12 × slide_add 13 5,237 0.817

Conflict 這一欄是模型推算,不是對 osFoundry 的實測:agent 讀取和寫入之間隔 4 s,使用者平均每分鐘在 Note 的某處存檔一次(指數分布),模擬 2,000 個 deck。每次寫入都是 Note 層級版本可能變動的新窗口,所以一張一張建要多出大約十二倍的重新讀取。把 deck 放進 outline(最多 20 張),slide_add 留給事後才想到的那張投影片。

另一個值得知道的數字是分頁。list_note_attachments 把 limit 上限設在 50,所以有 120 個 source 的 Note 要 3 次 call 才列得完。

重建版是怎麼跑的

這台機器上沒有跑任何 Claude binary。code/run.py 扮演 agent,直接呼叫 code/note_store.py。Store 放在記憶體裡、用一把 lock 保護,版本就是一個計數器。工具名稱、必填欄位、enum 和項目上限都來自 code/tools_list.raw 裡的 live schema,分頁 ID 照 nextTabId() 的規則產生。錯誤格式、key 的範圍(這裡是每份 Note)和冪等檢查順序是重建版自己的選擇,而第二種順序只是為了示範哪裡會出錯。Apple Silicon 上的 Python 3.9.6,五個實驗總共 1.0 s wall time。輸出在 code/run.out。

如果要自己串接

  • 每個 list 和 create call 都回傳每個實例的 ID,並讓編輯工具一定要帶這個 ID。寫入路徑上不要用類型或標籤去解析,就算你的 UI 在 URL 裡還接受它們。
  • 先檢查冪等 key,再檢查版本。回應遺失後的重送,帶的一定是舊版本。
  • 在工具說明裡告訴 agent,key 應該代表什麼。以引用來說,正規化後的「這份文件裡的這個 URL」能消除跨回合的重複。隨機 UUID 只處理得了重送。
  • Connector 的投影片格式要小(title、body、notes),設計交給編輯器裡的人。Schema 越小,模型能填錯的欄位就越少。
  • 讓 agent 一次 call 就送出整份 outline,並設上限(osFoundry 用 20)。寫入越少,共用文件上的 conflict 窗口就越少。
  • 透過 agent 通道只回傳附件的 metadata,絕對不要回傳內容或 signed link。連結的壽命比抓取它的 session 還長。

使用者那一側的 Sources 分頁存了什麼,請見 Sources 分頁頁面。底層協定的概要在 osFoundry 的 MCP 詞彙條目。

Top comments (0)