WebMCP

断言：这些步骤正在并行运行。

如果traversable的待处理工具执行 映射[uuid]不 存在，则返回。

注意：参阅此注释，了解工具的自然 兑现或拒绝如何与调用方的取消操作发生竞态。这可能导致uuid对应的待处理 执行条目在执行到这里之前就已被移除。在这种情况下， executeTool() promise 仍会因中止 原因而被拒绝，且永远不会观察到工具的 自然兑现或拒绝。

令execution为traversable的待处理工具执行 映射[uuid]。

从traversable的待处理工具执行 映射中移除[uuid]。

令targetDocument为execution的目标文档。

注意：当 这些步骤运行时，可以保证targetDocument仍然存在（即尚未被卸载或销毁），因为 如果targetDocument已被销毁，那么本规范的文档卸载清理步骤 就会 已经从映射中移除execution，而我们会进入上述 提前返回路径。

以targetDocument的相关全局对象为给定对象，在webmcp 任务源上排入一个全局任务，以运行以下步骤：

1. 令localExecutions为targetDocument的关联的 ModelContext的内部上下文的本地待处理工具 执行映射。

2. 如果localExecutions[uuid]不存在， 则返回。

3. 令localExecution为localExecutions[uuid]。

4. 移除localExecutions[uuid]。

5. 在localExecution的中止控制器上发出中止信号。

6. 在targetDocument的 关联的 ModelContext上触发一个事件，其名称为toolcancel， 使用 ToolCancelEvent， 并将其toolName 属性初始化为 execution的工具名称。

令traversable为document的节点可导航对象的可遍历可导航对象。

并行运行以下步骤：

1. 令executionsToRemove为一个空列表。

2. 对于traversable的待处理工具 执行映射中的每个uuid → execution：

   1. 如果document是execution的目标文档，或者 document是 execution的调用方文档， 则将uuid追加到 executionsToRemove。

3. 对于executionsToRemove中的每个uuid：

   1. 令execution为traversable的待处理工具 执行映射[uuid]。

   2. 如果document是execution的目标文档，且 不是execution的调用方文档， 则以 null 和目标文档 已卸载为参数，运行execution的完成步骤。

      注意：这会从待处理工具 执行映射中移除 execution。

   3. 否则，如果document是 execution的调用方文档，且 不是execution的目标文档， 则给定traversable和uuid，取消待处理工具 执行。

   4. 否则，从traversable的待处理工具 执行映射中移除[uuid]。

   5. 断言：traversable的待处理工具 执行映射[uuid] 不存在。

断言：这些步骤正在并行运行。

令navigablesToNotify为tool owner的节点可导航对象的可遍历可导航对象的活动文档的包含自身的后代可导航对象。

对于navigablesToNotify中的每个navigable：

1. 令targetDocument为navigable的活动文档。

2. 如果targetDocument不被允许使用“tools” 特性，则 继续。

3. 如果给定tool owner的源、exposed origins和targetDocument的源，工具暴露给某个源，则以 targetDocument的相关全局对象为给定对象，在 webmcp 任务源上排入一个全局任务，以便在targetDocument的 关联的 ModelContext上触发一个事件，其名称为toolchange。

如果tool owner origin与accessing origin同源，则返回 true。

对于exposed origins中的每个allowed origin：

1. 如果accessing origin与allowed origin同源，则 返回 true。

返回 false。

断言：这些步骤正在targetDocument的相关代理的事件循环上运行。

令toolMap为targetDocument的关联的 ModelContext的内部 上下文的工具映射。

如果toolMap[toolName]不存在，则 以 null 和 工具未找到为参数运行completionSteps，并终止这些步骤。

// -- 工具所有者文档。 --
const oldInputSchema = {...};
const newInputSchema = {...};
const ac = new AbortController();
document.modelContext.registerTool({... , inputSchema: oldInputSchema}, {signal: ac.signal});

// 注销，然后迅速使用更新后的输入模式重新注册。
ac.abort();
document.modelContext.registerTool({... , inputSchema: newInputSchema});


// -- 执行方文档。 --
//
// 这可能指向上面的“旧”工具或“新”工具，
// 执行可能因不匹配而遇到任何相应的错误。
const [tool] = await document.modelContext.getTools();
document.modelContext.executeTool(tool, {a: 10});

令tool为toolMap[toolName]。

给定targetDocument、inputArguments、 completionSteps和uuid，运行tool的执行步骤。

断言：这些步骤正在targetDocument的相关代理的事件循环上运行。

令inputObject为给定inputArguments，将 JSON 字符串解析为 JavaScript 值的结果。如果抛出了异常，则以 null 和无效输入为参数运行completionSteps，并终止这些步骤。

如果inputObject不是 Object，则以 null 和无效输入为参数运行completionSteps，并终止这些步骤。

在targetDocument的关联的ModelContext上触发一个事件，其名称为toolactivated， 使用ToolActivatedEvent， 并将其 toolName 属性初始化为tool的name。

令controller为一个新建的AbortController， 它创建于targetDocument的相关 realm中。

令localExecution为一个新的本地 待处理工具执行，具有以下项：

中止控制器

controller

将targetDocument的关联的 ModelContext的内部 上下文的本地待处理工具执行 映射[uuid]设置为localExecution。

令options为一个新的ToolExecuteCallbackOptions 字典，具有以下字段：

signal

controller的signal

令toolPromise为使用 inputObject和options调用tool的execute 所得到的结果。

对toolPromise进行响应：

• 如果toolPromise以值v兑现：

  1. 令localExecutions为targetDocument的关联的 ModelContext的内部上下文的本地待处理 工具执行映射。

  2. 如果localExecutions[uuid]不存在，则返回。

     注意：如果在开发者的 toolPromise敲定之前执行已被取消（因此 对应的条目已被移除），则与 uuid对应的条目将不存在。

  3. 移除 localExecutions[uuid]。

  4. 令serializedResult为给定v，将 JavaScript 值序列化为 JSON 字符串的结果。如果这会抛出 异常，则以 null 和 不可序列化的 结果为参数运行completionSteps，并终止这些步骤。

  5. 以serializedResult和 null 为参数运行completionSteps。

• 如果toolPromise以原因r被拒绝，则：

  1. 可以选择向控制台报告警告， 描述r。

  2. 令localExecutions为targetDocument的关联的 ModelContext的内部上下文的本地待处理 工具执行映射。

  3. 如果localExecutions[uuid]不存在，则返回。

  4. 移除 localExecutions[uuid]。

  5. 以 null 和工具被拒绝为参数运行completionSteps。

断言：这些步骤正在 modelContext 的 相关代理的 事件循环上运行。

令 tool map 为 modelContext 的 内部 上下文的 工具映射。

如果 tool map[tool name] 不存在，则 返回。

令 exposed origins 为 tool map[tool name] 的 暴露的源。

从 tool map 中移除 tool map[tool name]。

注： 注销工具不会取消 已经调用其 ToolExecuteCallback 的执行， 包括回调自身执行注销操作的情况。 注册时的 signal 仅控制工具的 可用性，而执行时的 signal 则控制 某次特定调用的生命周期。

令 targetDocument 为 modelContext 的 相关全局对象的 关联的 Document。

如果 targetDocument 不是完全活动的，则返回。

注： 如果工具的 signal 在 targetDocument 从其可导航对象中移除后被中止，例如因为其 iframe 被移除，就可能发生这种情况。此时，targetDocument 没有可供节点可导航对象，无法从中 查找需要通知的其他文档。

并行地，以 通知文档工具发生变更，给定 targetDocument 和 exposed origins。

返回this 的关联 ModelContext 对象。

令 global 为 this 的相关全局对象。

令 tool owner 为 global 的关联的 Document。

如果 tool owner 不是完全活动的，则返回一个以 "InvalidStateError" DOMException 拒绝的 Promise。

如果 tool owner 不被允许使用 "tools" 特性，则返回一个以 "NotAllowedError" DOMException 拒绝的 Promise。

令 tool map 为 this 的内部上下文的工具映射。

令 tool name 为 tool 的 name。

令 tool title 为 tool 的 title。

如果 tool map[tool name] 存在，则 返回一个以 InvalidStateError DOMException 拒绝的 Promise。

如果 tool name 是空字符串，或者其长度 大于 128，或者 tool name 包含任何不是 码点 ASCII 字母数字字符、U+005F (_)、 U+002D (-) 或 U+002E (.) 的码点，则返回一个以 InvalidStateError DOMException 拒绝的 Promise。

如果 tool 的 description 是空字符串，则返回一个以 InvalidStateError DOMException 拒绝的 Promise。

令 stringified input schema 为空字符串。

如果 tool 的 inputSchema 存在，则将 stringified input schema 设置为将 JavaScript 值序列化 为 JSON 字符串的结果，给定 tool 的 inputSchema。 如果此操作抛出异常，则返回一个以该异常拒绝的 Promise。

如果 tool owner 不是完全活动的，则返回一个以 "InvalidStateError" DOMException 拒绝的 Promise。

注： 上文已经 检查过 tool owner 是否完全活动，但是序列化 tool 的 inputSchema 可能运行脚本（例如 toJSON() 方法），使 tool owner 不再完全活动，例如通过移除其 iframe。

如果 tool map[tool name] 存在，则 返回一个以 InvalidStateError DOMException 拒绝的 Promise。

注： 同样，在 序列化 tool 的 inputSchema 时运行的脚本 也可以 注册另一个名为 tool name 的工具。

如果 options 的 signal 存在且已被 中止，则返回一个以 options 的 signal 的 中止原因拒绝的 Promise。

令 exposed origins 为一个空的列表，包含源。

如果 options 的 exposedTo 存在，则：

1. 对于 options，遍历其中每个 origin（它们取自 exposedTo 成员）：

   1. 令 parsedURL 为对 origin 运行 URL 解析器的结果。

   2. 如果 parsedURL 是失败，或者其源不是潜在可信的，则返回 一个以 "SecurityError" DOMException 拒绝的 Promise。

   3. 将 parsedURL 的附加 源到 exposed origins。

令 promise 为在 一个新建的 Promise，创建于 this 的相关领域中。

如果 options 的 signal 存在，则：

1. 令 signal 为 options 的 signal。

2. 断言：signal 尚未被中止。

3. 向 signal 添加以下中止步骤：

   1. 给定 注销工具、this 和 tool name。

   2. 以 signal 为中止信号，拒绝 promise，使用该信号的 中止原因。

令 tool definition 为一个新的工具定义，具有以下项：

名称

tool name

标题

tool title

描述

tool 的 description

输入模式

stringified input schema

执行步骤

一个接受 Document targetDocument、一个字符串 inputArguments、一个 算法 completionSteps 和一个唯一内部值 uuid，并 给定 tool、targetDocument、inputArguments、 completionSteps 和 uuid 来调用执行回调的算法。

注解

如果 tool 的 annotations 不存在，则为 null。否则，为一个 注解 ，具有以下项：

只读提示

tool 的 annotations 的 readOnlyHint

不可信内容提示

tool 的 annotations 的 untrustedContentHint

后果提示

tool 的 annotations 的 consequentialHint

调试

tool 的 annotations 的 debugging

暴露的源

exposed origins

将 this 的内部上下文的工具映射[tool name] 设置为 tool definition。

并行运行以下步骤：

1. 给定 tool owner 和 exposed origins，通知文档工具发生 变更。

2. 在 排入一个全局任务到webmcp 任务源，给定 global 以 兑现 promise 为 undefined。

返回 promise。

令 global 为 this 的相关全局对象。

令 toolRequestor 为 global 的关联的 Document。

如果 toolRequestor 不是完全活动的，则返回一个以 "InvalidStateError" DOMException 拒绝的 Promise。

如果 toolRequestor 不被允许使用 "tools" 特性，则返回一个以 "NotAllowedError" DOMException 拒绝的 Promise。

令 from origins 为一个空的列表，包含源。

如果 options 的 fromOrigins 存在，则：

1. 对于 options，遍历其中每个 origin（它们取自 fromOrigins 成员）：

   1. 令 parsedURL 为对 origin 运行 URL 解析器的结果。

   2. 如果 parsedURL 是失败，或者其源不是潜在可信的，则返回 一个以 "SecurityError" DOMException 拒绝的 Promise。

   3. 将 parsedURL 的附加 源到 from origins。

令 promise 为在 一个新建的 Promise，创建于 this 的相关领域中。

并行运行以下步骤：

1. 令 discoveredTools 为一个空的列表。

2. 令 navigables 为 toolRequestor 的节点可导航对象的可遍历可导航对象的活动文档的包含自身的后代可导航对象。

3. 对于 navigables 中的每个 navigable：

   1. 令 targetDocument 为 navigable 的活动文档。

   2. 如果 targetDocument 不被允许使用 "tools" 特性，则 继续。

   3. 令 targetOrigin 为 targetDocument 的源。

   4. 令 callerOrigin 为 toolRequestor 的源。

   5. 如果 targetOrigin 与 callerOrigin 同源，或者 from origins 包含 targetOrigin，则令 toolOwnerIsRequested 为 true；否则为 false。

   6. 如果 toolOwnerIsRequested 为 false，则继续。

   7. 令 targetToolMap 为 targetDocument 的关联的 ModelContext 的内部上下文的工具映射。

   8. 对于 targetToolMap 中的每个 tool name → tool definition：

      1. 如果以 targetOrigin 为第一实参，对 tool definition 进行工具是否向某个 源暴露判断，其第二实参为该工具定义的暴露的源，第三实参为 callerOrigin，且该判断返回 false，则 继续。

      2. 将 (tool definition, targetDocument) 附加到 discoveredTools。

4. 在 排入一个全局任务到webmcp 任务源，给定 global 以 运行以下 步骤：

   1. 令 tools 为一个空的列表，包含 RegisteredTool 字典。

   2. 对于 discoveredTools 中的每个 (tool definition, targetDocument)：

      1. 令 registeredTool 为一个新的 RegisteredTool 字典，具有以下字段：

         name

         tool definition 的名称

         title

         tool definition 的标题，如果其 非 null；否则为空 字符串。

         考虑不默认使用 空字符串，而是直接排除该 成员，这将产生 undefined。 [议题 #224]

         description

         tool definition 的描述

         inputSchema

         对于 tool definition，取 将 JSON 字符串解析 为 JavaScript 值的结果，传入参数为 tool definition 的输入模式， 前提是 tool definition 的 输入模式 不是空字符串；否则为 undefined。

         注： 这 永远不会抛出异常，因为存储在工具 定义中的字符串始终是有效的 JSON 字符串。

         window

         targetDocument 的相关全局 对象

         origin

         targetDocument 的序列化的 源。

         annotations

         如果 tool definition 的注解 非 null，则为一个 ToolAnnotations 字典，其 readOnlyHint 是 tool definition 的注解的 只读提示， untrustedContentHint 是 tool definition 的注解的 不可信 内容提示， consequentialHint 是 tool definition 的注解的 后果 提示，以及 debugging 是 tool definition 的注解的 调试。

      2. 将 registeredTool 附加到 tools。

   3. 将 tools 按升序排序，如果 a["name"] 在码元顺序上小于 b["name"]，则 a 小于 b。

   4. 以 tools 兑现 promise。

返回 promise。

令 callerDocument 为 this 的相关全局对象的关联的 Document。

如果 callerDocument 不是完全活动的，则返回一个以 "InvalidStateError" DOMException 拒绝的 Promise。

如果 callerDocument 不被允许使用 "tools" 特性，则返回一个以 "NotAllowedError" DOMException 拒绝的 Promise。

令 expectedTargetOriginURL 为解析 tool 的 origin 的结果。

如果 expectedTargetOriginURL 是失败，或者 expectedTargetOriginURL 的源是一个 不透明源，则返回一个以 "NotSupportedError" DOMException 拒绝的 Promise。

令 expectedTargetOrigin 为 expectedTargetOriginURL 的源。

断言：expectedTargetOrigin 不是一个不透明源。

如果未提供 inputObject，则将 inputObject 设置为 OrdinaryObjectCreate(%Object.prototype%)。

断言：inputObject 是一个 Object。

令 inputArguments 为以 inputObject 为输入，执行将 JavaScript 值序列化 为 JSON 字符串所得的结果；如果 inputObject 的序列化过程抛出异常，则返回一个以该异常拒绝的 Promise。

令 promise 为在 一个新建的 Promise，创建于 this 的相关领域中。

令 targetWindow 为 tool 的 window。

令 targetDocument 为 targetWindow 的关联的 Document。

如果 targetDocument 的节点可导航对象为 null，则返回一个以 "InvalidStateError" DOMException 拒绝的 Promise。

令 uuid 为一个新的唯一内部值。

如果 options 的 signal 存在，则：

1. 令 signal 为 options 的 signal。

2. 如果 signal 已被中止，则返回一个以 signal 的 中止原因拒绝的 Promise。

3. 令 traversable 为 targetDocument 的节点可导航对象的可遍历可导航对象。

4. 向 signal 添加以下中止步骤：

   1. 以 signal 为中止信号，拒绝 promise，使用该信号的 中止原因。

   2. 并行地，给定 traversable 和 uuid，取消一个待处理的工具 执行。

并行运行以下步骤：

1. 如果 targetDocument 的节点可导航对象的可遍历可导航对象不是 callerDocument 的节点可导航对象的可遍历可导航对象，则排入一个全局任务到webmcp 任务源，给定 callerDocument 的相关全局对象，以一个 "InvalidStateError" DOMException 拒绝 promise， 并中止 这些步骤。

   考虑支持在同一 浏览上下文组中的顶级文档之间执行工具。[议题 #227]

2. 令 targetOrigin 为 targetDocument 的源。

3. 令 callerOrigin 为 callerDocument 的源。

4. 如果 targetOrigin 与 expectedTargetOrigin 不同源，则 排入一个全局任务到webmcp 任务源，给定 callerDocument 的相关全局对象，以 拒绝 promise，使用一个 "NotFoundError" DOMException， 并中止这些步骤。

5. 令 targetToolMap 为 targetDocument 的关联的 ModelContext 的内部上下文的工具映射。

6. 令 toolName 为 tool 的 name。

7. 如果 targetToolMap[toolName] 不存在，则排入一个全局任务到 webmcp 任务源，给定 callerDocument 的相关全局对象，以拒绝 promise，使用一个 "NotFoundError" DOMException， 并中止这些步骤。

8. 令 tool definition 为 targetToolMap[toolName]。

9. 如果以 targetOrigin 为第一实参，对 tool definition 进行工具是否向某个源暴露判断，其第二实参为该工具定义的 暴露的源，第三实参为 callerOrigin，且该判断返回 false，则排入一个全局任务 到webmcp 任务源，给定 callerDocument 的相关全局对象，以 拒绝 promise，使用一个 "NotFoundError" DOMException， 并中止这些步骤。

   注： 在上述三项检查中均以 "NotFoundError" 拒绝——当 targetOrigin 不 匹配 expectedTargetOrigin、当 toolName 不存在，以及 当 tool definition 未向 callerOrigin 暴露时——可防止跨源调用方使用 伪造的 RegisteredTool 字典来探测 targetDocument 的当前源，或枚举 未向 callerOrigin 暴露的私有工具。

10. 令 completionSteps 为一个接受字符串或 null 的 result 和一个 工具执行错误或 null 的 error，并并行运行以下步骤的算法：

    1. 断言：result 和 error 中恰好有一个为 null。

    2. 如果 targetDocument 的节点可导航对象的可遍历可导航对象的 待处理工具 执行映射[uuid] 不存在， 则返回。

       由 uuid 标识的待处理执行可能 已不再存在。这可能 是由于 (a) 调用方文档 被销毁或调用方 通过选项信号中止 执行时的工具取消操作；与 (b) 工具 Promise 兑现之间的竞态。两者 都会竞相调用 completionSteps，首次调用 将通过键 uuid 移除 待处理的执行，此检查可保护后续 发生竞态的 调用。

    3. 从 targetDocument 的移除 节点可导航对象的可遍历可导航对象的待处理 工具执行映射[uuid]。

    4. 如果 error 为 null，则排入一个全局任务到webmcp 任务源，给定 callerDocument 的相关全局对象，以兑现 promise 为 result。

    5. 否则，排入一个全局任务到webmcp 任务源，给定 callerDocument 的 相关全局对象，以拒绝 promise，使用一个 DOMException ，其名称为 error 的对应的 异常名称。

       注： 仅传递工具执行错误（而不是在 targetDocument 中抛出的任何 内部 JavaScript 异常对象或消息），可以防止跨源泄露提供方的 实现细节或堆栈跟踪。

11. 令 execution 为一个新的待处理工具执行，具有以下 项：

    调用方文档

    callerDocument

    目标文档

    targetDocument

    工具名称

    toolName

    完成步骤

    completionSteps

12. 将 targetDocument 的节点可导航对象的可遍历可导航对象的 待处理工具 执行映射[uuid] 设置为 execution。

13. 在 排入一个全局任务到webmcp 任务源，给定 targetWindow 以运行工具执行步骤，给定 toolName、 targetDocument、inputArguments、completionSteps 和 uuid。

    注： 由于文档仅在完全活动时才处理 其事件循环上的任务，因此如果 targetDocument 不是完全活动的，这只会将 执行工具的步骤排入队列，待文档最终再次变为活动状态时运行（即 当 它离开 bf-cache 时）。

返回 promise。

断言：此算法正在浏览器代理的AI 代理队列中运行。

断言：traversable 的活动文档处于完全活动状态。

令 observation 为一个新的观察。

令 flat descendants 为 traversable 的 活动文档的包含自身的后代可导航对象。

对于每个 flat descendants 中的可导航对象 descendant：

1. 令 document 为 descendant 的活动文档。

2. 令 id 为 document 的唯一 ID。

3. 令 tools 为 document 的关联的 ModelContext 的内部上下文的工具映射的值，这些值是工具定义。

   注意：虽然这些步骤在 AI 代理 队列上运行，并与每个 Document 的 相关代理的事件循环并行执行，但实现会 通过进程间通信或 锁定机制同步对每个工具映射的访问，以确保 永远不会观察到部分更新。

4. 令 observedToolCollection 为一个新的已观察的 工具集合，包含以下项：

   源

   document 的源

   工具

   tools

5. 将 observation 的工具映射[id] 设为 observedToolCollection。

执行任何由实现定义的步骤，以向 observation 添加用户代理 可能认为有用或必要的任何内容，而不仅仅是填充工具映射。 这可能包括页面的带注释截图、无障碍树的部分内容等。

执行任何由实现定义的步骤，使用 observation 和浏览器代理，以 将 observation 的工具映射以浏览器代理所接受的任何方式 向其公开。

注意：尽管此 API 的名称（即 WebMCP）如此，但本规范并未规定 向浏览器代理公开工具时所使用的格式。浏览器可以自由地提炼 并通过模型上下文协议、其他专有的“函数调用”方法或其认为适当的 任何其他方式公开工具。