WebMCP

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

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

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

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

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

5. 令 targetDocument 为 execution 的目标文档。

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

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

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

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

   3. 令 localExecution 为 localExecutions[uuid]。

   4. 从 localExecutions 中移除[uuid]。

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

      在 targetDocument 的相关全局对象上触发 "toolcanceled" 事件。[议题 #146]

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

2. 并行运行以下步骤：

   1. 令 executionsToRemove 为一个空列表。

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

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

   3. 对于 executionsToRemove 中的每个 uuid：

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

      2. 如果 document 是 execution 的目标文档且 不是 execution 的调用方文档， 则运行 execution 的完成步骤， 并传入 null 和 false。

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

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

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

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

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

2. 令 navigablesToNotify 为 tool owner 的节点可导航对象的可遍历可导航对象的含自身的后代可导航对象。

3. 对于 navigablesToNotify 中的每个 navigable：

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

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

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

document.modelContext.ontoolchange = e => console.log('父级 toolchange');
iframe.contentDocument.modelContext.ontoolchange = e => console.log('子级 toolchange');

// 排入一个任务，以在 `webmcp task source` 上触发 `toolchange`。
const p = document.modelContext.registerTool({
  name: "tool_name",
  description: "工具描述",
  execute: async () => {}
});

p.then(() => console.log('注册 promise 已兑现'));

// 在 `timer task source` 上排入一个任务。
setTimeout(() => console.log('注册后任务'));

// `父级 toolchange` 总是会在 `子级 toolchange` 之前记录，并且
// `注册 promise 已兑现` 总是会在两者之后记录。
// 但 `注册后任务` 可能在这三者之前、之间或之后记录。

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

2. 对于 exposed origins 中的每个 allowed origin：

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

3. 返回 false。

1. 断言：这些步骤正在 targetDocument 的相关智能体的事件循环上运行。

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

3. 如果 toolMap[toolName] 不存在，则 运行 completionSteps，传入 null 和 false， 并中止这些步骤。

   支持将更细粒度的错误传回调用方；这应当在 调用文档中产生一个 "NotFoundError"。

   这可以防止工具注销与执行之间发生竞争。虽然工具 是否存在受到此竞争保护，但工具注销后快速 重新注册具有相同 toolName 但输入模式不同的工具则不 受保护。

   当议题 #92解决后， 这可能导致旧工具的 inputArguments 被应用到较新工具的输入模式，并引发 由此可能产生的任何错误。

   // -- 工具所有者文档。--
   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});
   

4. 令 tool 为 toolMap[toolName]。

5. 运行 tool 的执行步骤，并传入 targetDocument、inputArguments、 completionSteps 和 uuid。

   注：这是我们分支到 命令式执行步骤或 声明式执行步骤的地方。

1. 断言：这些步骤正在 targetDocument 的相关智能体的事件循环上运行。

2. 令 inputObject 为给定 inputArguments 和 targetDocument 的相关领域，运行将 JSON 字符串解析为 JavaScript 值所得的结果。如果抛出了异常，则运行 completionSteps，传入 null 和 false，并中止 这些步骤。

   支持更 细粒度的错误；这里我们应返回某种内容，促使调用方 使用一个 "DataError" DOMException 拒绝其 Promise。

3. 如果 inputObject 不是 Object 为 false，则运行 completionSteps，传入 null 和 false，并中止这些步骤。

   指定并 触发 "toolactivated" 事件。[议题 #146]

4. 令 controller 为在 targetDocument 的相关领域中创建的一个新的 AbortController。

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

   中止控制器

   controller

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

7. 令 options 为一个新的 ToolExecuteCallbackOptions 字典，包含以下字段：

   signal

   controller 的signal

8. 令 toolPromise 为调用 tool 的 execute 并传入 inputObject 和 options 所得的结果。

9. 对 toolPromise 作出反应：

   • 如果 toolPromise 以值 v 兑现：

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

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

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

     3. 从 localExecutions 中移除[uuid]。

     4. 令 serializedResult 为给定 v，运行将 JavaScript 值序列化为 JSON 字符串所得的结果。如果这抛出 异常，则运行 completionSteps，传入 null 和 false，并中止这些步骤。

     5. 运行 completionSteps，传入 serializedResult 和 true。

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

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

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

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

     4. 从 localExecutions 中移除[uuid]。

     5. 运行 completionSteps，传入 null 和 false。

1. 断言：这些步骤正在 modelContext 的相关智能体的事件循环上运行。

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

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

4. 令 exposed origins 为 tool map[tool name] 的公开源。

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

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

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

1. 返回this 的关联 ModelContext 对象。

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

2. 令 tool owner 为 global 的关联 Document。

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

4. 如果this 的周围 智能体的智能体集群的是否以源为键为 false 且this 的相关设置对象的源的 scheme 不是 "file"，则返回一个以 "SecurityError" DOMException 拒绝的 promise。

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

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

7. 令 tool name 为 tool 的 name。

8. 令 tool title 为 tool 的 title。

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

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

11. 如果 tool 的 description 是空字符串，则返回一个被拒绝的 promise，其拒绝理由为一个 InvalidStateError DOMException。

12. 令 stringified input schema 为空字符串。

13. 如果 tool 的 inputSchema 存在，则将 stringified input schema 设置为给定 tool 的 inputSchema， 运行将 JavaScript 值 序列化为 JSON 字符串所得的结果。 如果这抛出异常，则返回一个以该异常拒绝的 promise。

    上述序列化算法会在以下情况下抛出异常：

    1. 当底层 "JSON.stringify()" 产生 undefined 时，例如 "inputSchema: { toJSON() {return HTMLDivElement;}}" 或 "inputSchema: { toJSON() {return undefined;}}"，抛出一个新的 TypeError。

    2. 重新抛出由 "JSON.stringify()" 抛出的异常，例如当 "inputSchema" 是具有循环引用的对象等情况。

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

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

16. 如果 options 的 exposedTo 存在，则：

    1. 对于 options 的 exposedTo 中的每个 origin：

       1. 令 parsedURL 为在 origin 上运行URL 解析器所得的结果。

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

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

17. 令 promise 为在this 的相关领域中创建的一个新的 promise。

18. 如果 options 的 signal 存在，则：

    1. 令 signal 为 options 的 signal。

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

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

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

       2. 以 signal 的中止原因拒绝 promise。

19. 令 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

    公开源

    exposed origins

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

21. 并行运行以下步骤：

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

    2. 在给定 global 的webmcp 任务源上排入一个全局任务，以 使用 undefined兑现 promise。

22. 返回 promise

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

2. 令 toolRequestor 为 global 的关联 Document。

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

4. 如果this 的周围智能体的智能体 集群的是否以源为键为 false 且this 的 相关设置对象的源的scheme 不是 "file"，则返回一个以 "SecurityError" DOMException 拒绝的 promise。

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

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

7. 如果 options 的 fromOrigins 存在，则：

   1. 对于 options 的 fromOrigins 中的每个 origin：

      1. 令 parsedURL 为在 origin 上运行URL 解析器所得的结果。

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

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

8. 令 promise 为在this 的相关领域中创建的一个新的 promise。

9. 并行运行以下步骤：

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

   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. 令 registeredTool 为一个新的 RegisteredTool 字典，包含以下字段：

            name

            tool definition 的名称

            title

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

            考虑不要默认使用 空字符串，而是直接排除此 成员，这将使其结果为 undefined。 [问题 #224]

            description

            tool definition 的描述

            inputSchema

            如果 tool definition 的输入模式不是 空字符串，则为给定 tool definition 的输入模式后，将 JSON 字符串解析为 JavaScript 值的结果； 否则为 undefined。

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

            window

            targetDocument 的相关全局 对象

            origin

            targetOrigin，经序列化。

            annotations

            如果 tool definition 的标注不为 null，则为一个 ToolAnnotations 字典，其 readOnlyHint 为 tool definition 的标注的 只读提示， untrustedContentHint 为 tool definition 的标注的 不受信任 内容提示，而 consequentialHint 为 tool definition 的标注的 后果性 提示。

         3. 将 registeredTool追加到 tools。

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

   5. 在给定 global 的webmcp 任务源上排入一个全局任务，以 使用 tools兑现 promise。

10. 返回 promise。

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

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

3. 如果 this 的外围代理的 代理 集群的 按源设键为 false，并且 this 的相关设置对象的 源的 方案不是 "file"，则返回一个以 "SecurityError" DOMException 拒绝的 Promise。

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

5. 令 expectedTargetOriginURL 为对 tool 的 origin 进行解析的结果。

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

7. 令 expectedTargetOrigin 为 expectedTargetOriginURL 的源。

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

9. 如果 inputObject 不是一个 Object，则返回一个以 TypeError 拒绝的 Promise。

10. 令 inputArguments 为给定 inputObject 时，将 JavaScript 值序列化为 JSON 字符串的结果。如果此操作抛出异常，则返回一个以该异常拒绝的 Promise。

11. 令 promise 为在 this 的相关 Realm中创建的新 Promise。

12. 令 targetWindow 为 tool 的 window。

13. 令 targetDocument 为 targetWindow 的关联 Document。

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

15. 如果 options 的 signal 存在，则：

    1. 令 signal 为 options 的 signal。

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

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

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

       1. 用 signal 的 中止原因拒绝 promise。

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

16. 并行地运行以下步骤：

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

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

       根据每种失败情况，支持比 "UnknownError" 更细粒度的错误。

    2. 令 targetOrigin 为 targetDocument 的源。

    3. 令 callerOrigin 为 callerDocument 的源。

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

       根据每种失败情况，支持比 "UnknownError" 更细粒度的错误。

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

    6. 令 toolName 为 tool 的 name。

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

       根据每种失败情况，支持比 "UnknownError" 更细粒度的错误。

    8. 令 tool definition 为 targetToolMap[toolName]。

    9. 如果给定 targetOrigin、tool definition 的暴露源和 callerOrigin，工具暴露给某个源返回 false，则在 webmcp 任务源上排入一个全局任务 ，给定 callerDocument 的相关全局对象，以用一个 "UnknownError" DOMException 拒绝 promise， 并中止这些步骤。

       根据每种失败情况，支持比 "UnknownError" 更细粒度的错误。

    10. 令 completionSteps 为一个算法，其接受一个字符串或 null 的 result 和一个 布尔值 success，并运行以下步骤：

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

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

           由 uuid 标识的待处理执行可能已不再 存在。这可能 是由于以下两者之间发生竞态所致：(a) 当调用方文档 被销毁，或调用方通过选项 signal 中止 执行时进行工具取消；以及 (b) 工具 Promise 的解决。两者 都会竞相调用 completionSteps，而第一次调用 会通过其键 uuid 移除 待处理执行，此检查可保护后续发生竞态的 调用。

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

        4. 如果 success 为 true，则在 webmcp 任务源上排入一个全局任务，给定 callerDocument 的相关全局对象，以用 result 解决 promise。

        5. 否则，在 webmcp 任务源上排入一个全局任务，给定 callerDocument 的 相关全局对象，以用一个 "UnknownError" DOMException 拒绝 promise。

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

        调用方文档

        callerDocument

        目标文档

        targetDocument

        工具名称

        toolName

        完成步骤

        completionSteps

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

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

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

17. 返回 promise。

1. TODO：从 form 及其表单关联元素派生一个符合要求的 JSON Schema 对象。

指定声明式 执行步骤，以及它们与表单元素的集成。

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

2. 断言：traversable 的活动文档是完全活动的。

3. 令 observation 为一个新的观察。

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

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

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

   2. 令 id 为 document 的唯一 ID。

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

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

      源

      document 的源

      工具

      tools

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

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

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

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