webmcp

WebMCP

流程

步骤 1：识别浏览器集成界面

1. 检查工作区，查找浏览器入口、UI 处理程序，以及现有应用状态或表单处理层。
2. 如果可以使用 Node 运行时，执行 node scripts/find-webmcp-targets.mjs .，盘点可能的前端文件和现有 WebMCP 标记。
3. 如果无法使用 Node 运行时，手动检查最近的 package.json、HTML 入口文件和框架引导文件，以确定浏览器应用的边界。
4. 如果工作区包含多个前端应用，优先选择包含当前路由、组件或用户请求功能界面的应用。
5. 如果盘点后仍有多个可能的前端目标，请停止并询问用户应将 WebMCP 集成到哪个应用中。
6. 如果项目不是浏览器 Web 应用，请停止并说明此技能不适用。

步骤 2：选择 WebMCP 形式

1. 编写代码前，阅读 references/webmcp-reference.md。
2. 如果该功能可以通过 HTML 表单流程实现，或需要由 Agent 调用提交处理程序，请阅读 references/declarative-api.md。
3. 如果涉及原生功能是否可用、Chrome 预览版设置，或草案与预览版行为，请阅读 references/compatibility.md。
4. 如果注册、架构序列化或 Agent 驱动的表单执行失败，请阅读 references/troubleshooting.md。
5. 确认集成在安全的窗口浏览上下文中运行。
6. 如果该功能必须在服务端、工作线程中运行，或在没有可见浏览上下文的情况下以无头模式运行，请停止并说明平台限制。
7. 如果工具包装现有 JavaScript 逻辑、需要动态注册，或必须处理执行取消，请选择命令式 API。
8. 如果用户流程已经可以自然映射到表单提交，且页面能够让面向用户的表单与 Agent 活动保持同步，请选择声明式 API。
9. 保持工具名称、描述和参数明确且积极，并优先选择原子化工具，避免使用功能重叠的变体。 步骤 3：实现工具注册
10. 使用命令式 API 时，阅读 assets/model-context-registry.template.ts，并根据工作区中的框架、状态模型和文件布局进行调整。
11. 使用特性检测模式 const modelContext = document.modelContext || navigator.modelContext; 解析模型上下文，并在后续注册前检查其是否存在。优先使用 document.modelContext（当前接口），仅将 navigator.modelContext 保留为 Chrome 146–149 旧版本的后备方案。
12. 通过在 try/catch 中等待 modelContext.registerTool() 来注册命令式工具，并使用稳定的 name（由 1–128 个 ASCII 字母数字字符、_、- 或 . 组成）、正向的 description、对象类型的 inputSchema 和 execute 回调。在 Chrome 151+ 中，该调用会返回一个 Promise<void>，并在工具可用于整个框架树时解析；使用 await 可确保同一代码也能在同步注册的旧版本中正常运行。
13. 仅对不会修改状态的工具，将 annotations.readOnlyHint 设为 true。
14. 在 Chrome 154.0.8017.0+ 中，对执行高风险、不可逆或影响现实世界的操作（例如预订旅行、转账、购物或删除数据）的工具，将 annotations.consequentialHint 设为 true。这会提示 Agent 在执行前获取用户的明确确认。
15. 在 Chrome 156.0.8067.0+ 中，仅对专门用于检查、诊断、测试框架或开发者工具（例如 Chrome DevTools AI 辅助功能）的工具，将 annotations.debugging 设为 true。这样，通用 Agent 和面向终端用户的 Agent 就能识别并筛除面向开发者的工具。
16. 如果工具输出可能包含来自不可信来源的数据，请将 annotations.untrustedContentHint 设为 true。
17. 即使架构严格，也要在工具实现中验证业务规则，并返回有助于 Agent 更正输入后重试的明确错误。
18. 仅在 UI 和应用状态反映了工具的效果后，才返回工具结果。
19. 在 Chrome 153+ 中，接受始终存在的 { signal } 作为 execute 的第二个参数，并将其传递给 fetch() 等可取消的任务。请将此执行信号与注册信号分开处理。
20. 如果工具的可用性取决于路由、选择项或页面状态，请仅在工具有效时注册，并通过中止传递给 registerTool() 的信号所属的 AbortController 来注销过时工具；在 Chrome 148 过渡期间，也要在中止前通过可选链调用 modelContext.unregisterTool?.()。
21. 对于声明式工具，请在目标 <form> 上添加 toolname 和 tooldescription，并由表单控件定义参数范围。
22. 使用标签或 toolparamdescription 为声明式字段提供清晰的参数描述。
23. 仅当页面应在 Agent 填写表单后自动提交时，才使用 toolautosubmit。 步骤 4：安全地接入 Agent 驱动的用户体验
24. 即使页面支持 Agent 调用，也要保留常规的人类交互路径。
25. 如果工具需要明确确认或面向用户的步骤，请通过应用的可见界面和现有授权检查处理；当前的 execute(input, { signal }) 契约不提供客户端回调。
26. 自定义声明式提交处理时，请在调用 respondWith() 前调用 preventDefault()，并为 Agent 调用的提交返回结构化验证错误。
27. 仅在具备兼容性意识的界面逻辑中使用 toolactivated、toolcancel、agentInvoked 等仅供预览的事件以及 WebMCP 表单伪类。对于 toolactivated 和 toolcancel，请阅读 references/declarative-api.md，并先检测 document.modelContext 上的 on* 属性，再为较旧版本的构建回退到 window。
28. 即使 annotations.consequentialHint 为 true，破坏性或敏感操作仍须经过可见的用户确认和现有授权检查；该注解仅向 Agent 提供信息，不会强制执行应用安全措施。
29. 保持界面状态同步，确保同一页面能准确反映由人工输入和工具调用导致的更改。

步骤 5：验证行为

1. 测试注册和注销的生命周期，包括重复名称防护，以及路由或状态变化时的清理。
2. 测试无效或不完整的输入，确认工具会返回纠正性错误，而不是悄然失败。
3. 对于声明式工具，请验证生成的参数描述、必填字段、提交行为以及任何自定义 respondWith() 处理。
4. 如果目标环境是当前 Chrome 预览版，请先根据 references/compatibility.md 确认所需版本和标志状态，再将运行时故障视为应用错误。
5. 通过中止传递给 executeTool() 的信号来测试执行取消，并验证长时间运行的工作会停止，而不依赖工具注销。
6. 仅将 Model Context Tool Inspector 或同类预览工具用作验证辅助工具，不要将其作为运行时依赖。
7. 首先通过检查已注册的工具集，并在有预览工具时使用有代表性的参数手动调用工具，来验证确定性执行。
8. 确定性执行正确后，再验证自然语言路由，确保描述和参数结构能引导 Agent 使用正确的工具。
9. 验证所有高风险、不可逆或涉及现实世界操作的工具都声明了 annotations.consequentialHint: true，并且仍会执行应用的确认和授权流程。
10. 验证专用于检查、诊断、测试或开发者工具的工具声明了 annotations.debugging: true，并确保面向用户的工具未设置该项或将其设为 false。
11. 编辑后运行工作区构建、类型检查或测试。

错误处理

• 如果 document.modelContext 和 navigator.modelContext 都缺失，请确认代码是在安全的浏览器窗口上下文中运行，然后检查 references/compatibility.md 中的预览版要求。
• 如果只有 navigator.modelContext 存在，则页面运行在较旧的 Chrome 146–149 预览版上；请保留 document.modelContext || navigator.modelContext 回退逻辑，但计划在弃用期限结束后移除 navigator.modelContext。
• 在 try/catch 中等待 registerTool()。在 Chrome 151.0.7922.0+ 中，它会返回一个失败时拒绝的 Promise<void>；较旧版本则会同步返回并抛出异常。同样的 await + try/catch 写法可以捕获这两种情况，因此无论错误是以同步异常还是 Promise 拒绝的形式出现，下面的错误检查都适用。
• 如果 registerTool() 抛出 InvalidStateError，请检查是否存在重名、空的 name 或 description 值，或长度超过 128 个字符或包含不允许字符的工具名称（仅允许 ASCII 字母数字字符、_、-、.）。
• 如果 registerTool() 抛出 NotAllowedError，请检查 tools Permissions Policy 功能是否被禁用；跨源 iframe 需要嵌入文档提供 allow="tools"。
• 如果 registerTool() 抛出 TypeError 或 JSON 序列化错误，请将不可序列化或循环引用的 inputSchema 值替换为纯 JSON 兼容对象。
• 如果较旧的演示或文章提到了 provideContext、clearContext 或 toolparamtitle，请将这些接口视为当前实现中的过时内容。
• 如果声明式执行未能正确更新页面，请先阅读 references/declarative-api.md 和 references/troubleshooting.md，再更改工具契约。