osFoundry 为什么逼 Claude 用精确 Tab ID 和幂等 Key：一次 MCP 工具设计的实测拆解

作者用 Python 复现了 osFoundry 的 MCP 工具接口，通过上万次模拟实验验证三个设计决策：为什么引用必须用精确的 tab ID 而不是「那个 Slides 标签页」，为什么幂等 Key 必须在版本检查之前校验，以及每条引用为什么要单独的 Key。数据表明，看似更宽松的写法会让 Agent 在无报错的情况下写错文件。

窄 Schema 是刻意的设计

• Connector 里一张幻灯片只有 title、body、notes 三个字段，且 additionalProperties: false，不能选位置、不能建 Markdown 标签页、单次最多 20 页
• 作者用一个小型 Validator 复测了 8 种模型可能发出的 Payload，多余字段、越界枚举、超限数组全部被拒
• 这是分工决策：Agent 只写内容，主题和排版由人在桌面应用里完成

为什么必须用精确 Tab ID

• 桌面应用为了兼容旧链接，允许用类型名当快捷方式，会命中列表里第一个匹配项
• 模拟实验：给一条 Note 建 K 个 Slides 标签页，人在 Agent 两步操作之间随机移动、重命名、新增标签页，跑 10000 次
• 用「位置」引用正确率约 83%，用「类型」在 K=5 时只有 19.7%，用「标签」约 85–92% 但有 2–3% 写进完全错误的 Deck 且毫无报错
• ID 一次性分配、永不复用，三种实验规模下全部 100% 正确

版本检查防不住写错标签页

• 人对标签栏的任何改动都会提升 Note 版本，所以过期写入会被拒绝、Agent 会重新拉取列表
• 但重新拉取后，Agent 仍会拿旧引用去新列表里解析——实验中 100% 的写入都通过了版本检查，包括写错目标的那些
• 版本只能证明 Agent 看过最新状态，不能证明它找对了目标，后者只能靠 Tab ID 保证

幂等 Key 要排在版本检查之前

• 模拟 50 次创建、30% 响应在服务端提交后丢失（即客户端超时重试的场景）
• 如果服务端先查版本，重试携带的是提交前的旧版本，会收到冲突；客户端按惯例换新 Key 重试，就多建出一个 Deck
• 先查 Key 时，重试直接返回第一次创建的 Tab ID，三种客户端策略下都稳定在 50 个标签页；先查版本则多出 16–21% 的调用

每条引用一个 Key 的代价

• 300 场模拟研究：每场引用 6 个页面，同一 URL 可能以加斜杠、带 www、带 utm 参数、带 #fragment 等 7 种写法出现，20% 响应丢失后重试
• 每次引用用新 UUID（重试时复用）：5400 条来源、3038 个重复
• 用原始 URL 字符串做 Hash：4814 条、2452 个重复；按规范化 URL 做 Hash 效果最好（原文在此处截断）