← Browser AI From First Principles

暴露第一个 WebMCP 工具

通过 WebMCP 暴露一个类型化的只读书籍操作,校验其参数、限定其结果,并检视完整的调用生命周期。

第 17 章建好了契约。本章把它注册给浏览器。

我们的第一个 WebMCP 工具不应发消息、编辑文档或购买任何东西。它应当从我们控制的这本书里读取。我们将暴露 search_book:一个有界的、返回相关章节与段落的操作。

这种克制是刻意的。从一个有界的只读工具开始,能在我们测试注册、发现、schema 处理、执行与追踪时,先移除改变状态的后果。它没有移除披露风险——读取工具仍可能泄漏——所以语料与结果仍然需要显式的边界,这就是第 6 节大部分内容所讲的。


1. 为什么第一级是只读

存在一段能力阶梯,search_book 是它的最低一级:

读取一个受控语料          ← 我们在这里
跨 origin 读取
准备一份草稿
可逆本地写入
外部效应(发送、发布)

每高一级都增加一个下一级不必回答的权威性问题。从底部开始,让我们先把管道做对——浏览器能看到这个工具吗,schema 能往返吗,轨迹能捕获每个阶段吗——然后任何错误才可能离开页面之前。


2. 完整的 search_book 契约

读者应当能讲出这个工具的每个维度:

维度 值
标识 programmer.ie + search_book + 注册实例
名字 search_book
描述 “Search this book for passages related to a query.”
输入 schema query(string,2–300 字符)、limit(integer,1–10,默认 5)、additionalProperties: false
效应类别 read,作用域 registered-book-index,network: forbidden
Annotations readOnlyHint: true、consequentialHint: false、untrustedContentHint: false
结果形状 { chapter, title, url, excerpt } 数组加 truncated
结果边界 至多 10 条匹配;摘录上限 180 字符;语料限于本书
确定性校验 schema,再领域(query 长度、limit 范围),再结果形状检查
错误 query 触发 TypeError,limit 触发 RangeError,无匹配返回空数组
权威性类别 在声明的作用域内自动准入;无需批准界面

这些行中的每一行都由应用代码执行。schema 是给智能体关于参数形状的提示;它不是执行边界。


3. WebMCP 注册表面

WebMCP 是一项 origin trial API。下面的语法已于 2026 年 9 月 6 日对照 Chrome for Developers 的 WebMCP 文档重新核查;它从 Chrome 149 起在 origin trial 背后可用,并从 chrome://flags/#enable-webmcp-testing 用于本地开发。

const controller = new AbortController();

await document.modelContext.registerTool(
  {
    name: "search_book",
    description: "Search this book for passages related to a query.",
    inputSchema: {
      type: "object",
      properties: {
        query: { type: "string", minLength: 2, maxLength: 300 },
        limit: { type: "integer", minimum: 1, maximum: 10 }
      },
      required: ["query"],
      additionalProperties: false
    },
    annotations: {
      readOnlyHint: true,
      consequentialHint: false,
      untrustedContentHint: false
    },
    execute: async ({ query, limit = 5 }, { signal }) => {
      return searchBook({ query, limit, signal });
    }
  },
  { signal: controller.signal }
);

三个细节很重要,并且随 API 演进变化过:

  • 注册在 document.modelContext.registerTool 上,而不是 navigator.modelContext。早期草稿用的是 navigator 路径;手稿与第 18 章的实验元数据在 2026 年 9 月的那次核查中被更正为 document。
  • 撤回由一个 AbortController 驱动。 你向 registerTool 传 { signal },之后调用 controller.abort() 撤回该注册。截至 Chrome 153,中止不会打断已在进行中的执行——这个细节 Observatory 应当记录,而不是假定。
  • execute 处理器收到输入对象与一个携带 signal 的 options 对象。无论平台对 schema 施加(或不施加)什么,处理器都要重新校验(第 5 节),并把该 signal 传进任何可取消的工作中。

要抓住的不变式是:

平台可能约束  +  应用校验  =  实际的执行边界

持久的架构是将比语法活得更久的那部分:一个名字、一条描述、一个类型化输入 schema、安全 annotations、一个生命周期与一个实现。


4. 安全 annotations 做什么、不做什么

readOnlyHint、consequentialHint 与 untrustedContentHint 是沟通,不是执行。

Annotation 它告诉智能体什么 它不保证什么
readOnlyHint: true 作者声明这次调用不改变任何状态 实现真的无副作用
consequentialHint: true 该调用有重大或难以逆转的效应,因此消费方智能体或浏览器可以在其运行前要求用户确认 false 值就可以无人值守地安全运行,或该 annotation 本身就是授权机制
untrustedContentHint: true 结果可能包含需要消毒的外部或用户生成文本 false 值就不含被注入的指令

这些 hint 让行为良好的智能体与浏览器做出更好的默认决策。它们由页面提供,因此 Observatory 把它们存储为 browserAttested: false。对 search_book 真正的约束——无网络、无写入、有界披露——活在实现里与确定性政策层里,后者从自己的注册表赋予效应,无论 annotations 声称什么。


5. 校验两次,然后检查结果

schema 约束模型产出的形状。应用执行领域规则。

function searchBook({ query, limit = 5, signal }) {
  if (typeof query !== "string" || query.trim().length < 2) {
    throw new TypeError("query must contain at least two characters");
  }
  if (!Number.isInteger(limit) || limit < 1 || limit > 10) {
    throw new RangeError("limit must be between 1 and 10");
  }
  const matches = index.search(query.trim(), limit, { signal });
  return boundResult(matches); // caps count, excerpt length and corpus
}

有五道门,不是两道:

schema validation      → 形状良好
domain validation      → query 与 limit 满足工具自己的规则
policy validation      → 该效应类别在此上下文中可准入
resource limits        → 数量、摘录长度、语料作用域
result validation      → 返回值符合结果契约

一个通过 schema 的 JSON 参数不是一次有效的操作,一个 resolve 的处理器不是一个有效的结果。最后一道门很重要:一个携带二十条匹配或 4,000 字符摘录的 resolved promise 已经违反了契约,尽管什么都没有抛出。


6. “只读"不等于"可以安全披露一切”

读取工具没有副作用。它仍然可能泄漏。

search_book 的披露边界由四个限制设定:

  • 语料作用域 —— 搜索只在本书的已注册索引上运行,不在任意 DOM 文本、文件或另一个 origin 上。
  • 摘录大小 —— 每条匹配 180 字符,足以判断相关性,不足以重构一个章节。
  • 结果数量 —— 至多 10 条引用,这也保护智能体的上下文窗口不被一次调用淹没。
  • 仅公开内容 —— 索引包含已发布的章节摘要;私密或草稿材料绝不会被注册。

“只读"描述的是对状态的效应。披露边界是一个分开的决定,对一个读取私密内容的工具而言,它是更重要的那个。


7. 工具标识是上下文相关的

两个站点可以注册一个都叫 search_book 的工具,一个站点也可以在一次访问中注册、撤回并重新注册它。光凭工具名不是标识。

WebMCP 本身按 origin 与名字给工具编号。为了追踪,我们需要区分同一名字的两次注册,因此 Observatory 给每次注册分配自己的 ID,并把有效的轨迹标识视为:

origin + 工具名 + Observatory 注册 ID

智能体的工具列表是依赖时间的页面状态:注册可能在加载之后出现、被一份新定义替换,或在 controller 中止时被撤回。Observatory 为每次注册存下快照:

  • 页面 origin;
  • 完整工具定义与一个 schema 哈希;
  • 注册时间;
  • annotations;
  • 来源是声明式(HTML form)还是命令式(registerTool);
  • 替换或移除,附带原因。

两次运行之间的行为变化,只有在我们知道工具列表相同——或确切知道它有何不同——时才可解读。


8. 在模型碰到工具之前先测试它

这是本章的方法论核心。在请智能体去发现 search_book 之前,用完全不涉及模型的 fixture 证明这份确定性契约:

Fixture 预期结果 被锻炼的阶段
有效查询,limit: 3 至多 3 条来自本书的有界匹配 执行 + 结果边界
语料中无匹配的查询 空数组,truncated: false —— 绝不捏造文本 依据性
301 字符的查询 拒绝 schema
limit: 11 拒绝 schema
额外的 destination 字段 拒绝 schema(additionalProperties: false)
格式错误的 JSON 字符串 拒绝 解析
为返回长文本而构造的查询 摘录仍被封顶在 180 字符 结果验证
执行中途中止 处理器观察到 signal;部分工作被丢弃 取消

只有当每一行都确定性地通过,我们才转向评估智能体是否会发现并选择该工具。以相反次序运行这些,会让一个工具 bug 伪装成一次推理失败——这是智能体调试出错最常见的单一方式。


9. 这本书变成可寻址的软件

一旦站点暴露一族操作——

search_book
get_chapter
find_concept
compare_chapters
run_experiment
inspect_evidence

——这本书就不再只是渲染在浏览器里的文本。它有了一个语义接口:智能体可以在一份有界契约下检索某个特定章节、比较二者,或定位一个概念,而无需被交予页面的控制权。

这比"这本书是一个智能体"是一个更小的主张。这本书暴露能力。发现并使用它们的是另一套系统,被单独评估,从下一章开始。


10. 运行 WebMCP search-book 实验室

从第 18 章选择 Run with Browser AI 以打开:

/tools/ai/browser-ai-from-first-principles/18-chapter/

实验室有两条分开的路径。live path 调用 document.modelContext.registerTool、检视该表面是否存在,并在不存在时记录确切的失败——origin trial 未激活、flag 未设置——而不是把每种情况都折叠成"不可用”。simulator path 在页面内行使同一份契约;其事件携带 surface: in-page-simulator,且绝不被计为浏览器注册。

无论哪条路径,你都可以运行第 8 节的确定性 fixture、检视身份快照(origin、契约版本、注册 ID、schema 哈希、定义哈希、surface),并逐步查看生命周期事件:检视、注册、提议、参数校验、政策准入、执行、结果验证、替换、移除。

这确立了什么:search_book 契约在可用之处已通过当前 WebMCP 表面注册,其确定性行为被充分测试。什么仍是被规定而非被观察的:policy.modelSelectionClaim 为 not-observed——本章不主张有浏览器智能体发现或选择了该注册。记录中的轨迹仍只显示 Prompt API 生命周期。对发现与选择的行为评估从第 19 章开始。


结论

一个有用的 WebMCP 工具把语义名字、类型化输入、告知而非执行的安全 annotations、有界结果、每道门上的应用侧校验,以及完整的身份与生命周期轨迹组合在一起。

search_book 给了我们一个安全的第一机制。下一个问题是行为性的:当存在几个貌似可用的工具时,智能体会不会发现并选对那个,带着正确的参数,并真正使用它返回的东西?


参考与延伸阅读

  1. Chrome for Developers, WebMCP.
  2. Chrome for Developers, WebMCP imperative API.
  3. Chrome for Developers, WebMCP tool security.
  4. Model Context Protocol, Specification.
  5. JSON Schema, Understanding JSON Schema.