工具只在页面打开后才存在:WebMCP 按路由注册的入口难题

2026/11/15
工具只在页面打开后才存在:WebMCP 按路由注册的入口难题

AI Summary (BLUF)

本文通过Trip Workbench项目演示了如何利用WebMCP的页面作用域工具注册机制,在React组件中根据路由和状态动态注册和注销工具。文章详细介绍了事件编辑器与旅行编辑器的工具设计、注册生命周期、路由序列测试以及执行有用操作的方法,并讨论了窄接口的进入路径和性能评估的注意事项。

核心洞察

这篇文章最有意思的地方在于它把一个容易被忽略的问题摆上了台面:工具按页面注册之后,智能体怎么进入这个页面?作者没有回避这个尴尬,直接承认了“窄接口需要一个入口”这个设计缺口。我比较欣赏这种写法,先跑通再谈局限,比一上来就吹架构强。


在活动列表页,浏览器发现零个 WebMCP 工具。打开一个活动草稿,出现了四个。切到行程草稿,换成了五个行程工具。

这个路由切换的行为,正是 Trip Workbench 加入第二条工作流之后我想要的效果。如果启动时把所有操作都注册上,那么即使只有一个编辑器可见,两个不相关的领域也会同时暴露出来。

按页面限定工具能让当前上下文更清晰。但它也带来一个设计问题:如果一个工作流的工具只有在对应页面打开后才存在,智能体要怎么进入这个工作流?

核心结论

  1. Trip Workbench 的活动列表页在浏览器中发现零个 WebMCP 工具,打开活动草稿后出现四个活动工具,切换到行程草稿后变为五个行程工具,证明工具注册随路由和页面上下文动态变化。

  2. 活动编辑器仅在拿到草稿标识且状态为 draft 后才注册工具,通过 AbortController 信号在组件清理时移除注册;截至 Chrome 153,中止注册会移除工具但不会取消已在执行的操作。

  3. 按真实路由顺序测试显示:活动列表页和行程列表页均无工具,编辑活动时暴露四个工具,编辑行程时暴露五个工具,观察者角色仅暴露读取、校验、准备三个工具(省略变更工具),但服务端仍须独立拒绝无权限写入。

  4. 执行验证中,更新操作将合成活动草稿从版本 1 推至 2,prepare_event_review 返回 MANUAL_LOCATION 要求、canSubmit: true、submitted: false,可见标题与数据库查询一致,活动保持草稿状态且零提交。

  5. 由于活动列表页有意不暴露编辑器工具,仅限 WebMCP 调用的客户端无法自行进入工作流;可行设计是将浏览器导航纳入客户端契约,或增加有边界的列表级工具来打开已授权草稿或创建新草稿,同时应避免通用的任意 API 调用或任意 JavaScript 执行入口。

把领域身份留在契约里

活动编辑器有标题、日期范围、时区、地点模式、地点标签和备注。行程编辑器有机场、出行日期、舱位、旅客人数和目的。

两个工作流复用了授权、版本和命令回执这些模式,但它们各自保留独立的协调器、服务、数据表、校验规则、策略版本和标识符。活动工具接收 eventId,行程工具接收 draftId。

活动编辑器暴露这些工具:

工具 用途
get_event_draft 读取已保存字段、版本、状态和未保存变更状态
update_event_draft 对期望版本应用允许的补丁
validate_event_draft 返回字段问题和策略发现
prepare_event_review 在活动仍为草稿时展示发现

这个合成示例不会发送邀请、连接日历或预订场地。

编辑器有上下文时再注册

React 编辑器只有在拿到草稿标识和状态之后才注册工具。精简后的生命周期大概是这样:

useEffect(() => {
  if (!eventId || draftStatus !== "draft") return;

  const registration = new AbortController();

  registerEventDraftTools({
    eventId,
    canMutate: Boolean(canMutate),
    coordinator: eventCoordinator,
    signal: registration.signal,
    onStatus: setRegistration,
  });

  return () => registration.abort();
}, [eventId, draftStatus, canMutate, eventCoordinator]);

Chrome 当前的命令式 API 文档里写的就是这种基于信号的生命周期。截至 Chrome 153,中止注册会移除工具,但不会取消已经在执行的操作。这对组件清理很有用,但也意味着路由清理和进行中操作的安全是两件独立的事。

草稿标识必须放进依赖列表。React 可能在不同活动之间切换时保留同一个组件类型,旧工具必须消失,新处理器必须绑定到新活动。

按真实路由顺序测试

原生浏览器运行正常登录,使用可见导航,创建一个合成活动草稿,然后检查浏览器真实的工具集合。它没有直接调用协调器。

上下文 发现的接口
旅客在行程列表 无
旅客在活动列表 无
旅客编辑活动 四个活动工具
旅客编辑行程 五个行程工具
旅客回到活动列表 无
旅客重新打开活动 四个活动工具
观察者编辑活动 读取、校验、准备
观察者回到活动列表 无

精确名称断言能抓住残留的注册:

const expected = [
  "get_event_draft",
  "prepare_event_review",
  "update_event_draft",
  "validate_event_draft",
];

const actual = page.webmcp.tools()
  .map((tool) => tool.name)
  .sort();

assert.deepEqual(actual, expected);

观察者的结果有用但有限。省略变更工具能减少意外暴露,但它不负责授权。服务端仍然必须拒绝没有权限的写入。

执行一个有用的操作,而不只是发现

光有工具名不能证明页面契约能工作。这次运行更新了一个合成工作坊,校验它,并准备了一个内联审查。

{
  "title": "Customer engineering workshop",
  "startDate": "2026-11-25",
  "endDate": "2026-11-26",
  "timeZone": "America/Los_Angeles",
  "locationMode": "manual",
  "locationLabel": "Demo workshop room",
  "notes": "Synthetic example; no invitations"
}

被接受的更新把草稿从版本 1 推到 2。prepare_event_review 显示了一个 MANUAL_LOCATION 要求,canSubmit: true,submitted: false。可见标题和独立的数据库查询一致,活动仍然是草稿,零提交。

注入的测试时钟是 2026 年 10 月 14 日,所以日期还在未来。当校验依赖日期时,固定时间很重要。

窄接口需要一个入口

活动列表有意不暴露任何编辑器工具,所以那些工具没法自己打开工作流。

录制的运行使用了正常的活动链接和“新建活动草稿”按钮。有导航和操作能力的浏览器智能体可以走类似路径。只限于 WebMCP 调用的客户端不行。

有两种站得住脚的设计:

  1. 把浏览器导航当作客户端契约的一部分。
  2. 加一个有边界的列表级工具,用来打开已授权的草稿或创建新草稿。

我会避免通用的“调用任意 API”或“执行任意 JavaScript”逃生口。它会摧毁那些让编辑器工具可审查的窄模式和服务器检查。

别把工具数量当成性能结论

这次运行证明了发现的接口会随路由和角色变化。它没有证明模型用四个工具比用九个工具完成任务更快。

那需要单独的评估:固定任务和可执行行为,改变可见工具集,测量错误目标更新、工作流进入失败、正确持久化结果、恢复步骤和最终答案准确率。

当前证据支持的结论更窄:在相关对象可见的地方暴露编辑工具,上下文结束时移除它们,保留服务器授权,并为你实际支持的客户端设计一条明确的进入路径。

常见问题(FAQ)

WebMCP 工具为什么要按页面动态注册,而不是启动时全部注册?

启动时全注册会让不相关领域同时暴露,即使只有一个编辑器可见。按页面限定工具能让当前上下文更清晰,活动列表页发现零个工具,打开草稿才出现对应工具,路由切换时旧工具随之消失。

React 组件里注册 WebMCP 工具要注意什么?

编辑器拿到草稿标识和状态后才注册,用 AbortController 信号在清理时中止注册。草稿标识必须放进依赖列表,否则组件复用时旧工具不会消失、新处理器可能绑错活动。中止只移除工具,不取消已执行操作。

工具数量少就一定性能更好吗?

不一定。文章明确说这次运行只证明发现的接口随路由和角色变化,没有证明四个工具比九个工具完成任务更快。要下性能结论需单独评估,固定任务、改变可见工具集,测量错误更新、进入失败和结果准确率。

晓婷深圳
本文由 晓婷 审核,最后更新于 2026年11月15日
联系编辑 →
← 返回文章列表
分享到:微博

版权与免责声明:本文仅用于信息分享与交流,不构成任何形式的法律、投资、医疗或其他专业建议,也不构成对任何结果的承诺或保证。

文中提及的商标、品牌、Logo、产品名称及相关图片/素材,其权利归各自合法权利人所有。本站内容可能基于公开资料整理,亦可能使用 AI 辅助生成或润色;我们尽力确保准确与合规,但不保证完整性、时效性与适用性,请读者自行甄别并以官方信息为准。

若本文内容或素材涉嫌侵权、隐私不当或存在错误,请相关权利人/当事人联系本站,我们将及时核实并采取删除、修正或下架等处理措施。也请勿在评论或联系信息中提交身份证号、手机号、住址等个人敏感信息。