用途
WebMCP 技能用于在 JavaScript 或 TypeScript 编写的浏览器 Web 应用中实现和调试 WebMCP 集成。它适用于需要把页面中的既有逻辑或表单流程暴露给智能体（agent）调用的场景，例如通过 document.modelContext 注册命令式工具，或通过 HTML 表单声明可由智能体调用的提交流程。该技能同时覆盖注册失败、schema 序列化错误以及智能体驱动表单执行异常等问题的排查。
主要能力
该技能提供了一套分步骤的操作流程，主要包含以下环节：
第一步：识别浏览器集成面。 检查工作区中的浏览器入口、UI 处理逻辑以及已有的应用状态或表单处理层。在具备 Node 运行时时，可执行 node scripts/find-webmcp-targets.mjs . 来盘点可能的前端文件与已有的 WebMCP 标记；否则手动检查最近的 package.json、HTML 入口与框架引导文件。若存在多个前端应用，应优先选择包含当前路由、组件或用户请求功能面的应用；若仍无法确定，应停下并询问用户。若项目不是浏览器 Web 应用，应停止并说明该技能不适用。
第二步：选择 WebMCP 形态。 在写代码前先阅读 references/webmcp-reference.md。当功能可表达为 HTML 表单流程或需要智能体调用的提交处理时，阅读 references/declarative-api.md；当涉及原生可用性、Chrome 预览设置或草案与预览行为差异时，阅读 references/compatibility.md；当注册、schema 序列化或智能体驱动表单执行失败时，阅读 references/troubleshooting.md。集成必须运行在安全的窗口浏览上下文中。当工具封装已有 JavaScript 逻辑、需要动态注册或必须处理执行取消时，选择命令式 API；当用户流程能清晰映射到表单提交且页面能让人类可见表单与智能体活动保持同步时，选择声明式 API。工具名称、描述与参数应保持明确、正向，优先使用原子工具而非重叠变体。
第三步：实现工具注册。 使用命令式 API 时，参考 assets/model-context-registry.template.ts 并适配工作区的框架、状态模型与文件布局。使用 const modelContext = document.modelContext || navigator.modelContext; 进行特性检测，并以其存在为前提守护后续注册；优先使用 document.modelContext，navigator.modelContext 仅作为旧版 Chrome 146–149 的回退。在 try/catch 中 await modelContext.registerTool() 注册命令式工具，使用稳定名称（1–128 个 ASCII 字母数字/_/-/. 字符）、正向描述、对象 inputSchema 与 execute 回调。仅在工具不修改状态时设置 annotations.readOnlyHint 为 true；在 Chrome 154.0.8017.0+ 上，对高风险、不可逆或现实世界操作（如预订旅行、转账、购买、删除数据）设置 annotations.consequentialHint 为 true，以提示智能体在 执行前获取明确用户确认；在 Chrome 156.0.8067.0+ 上，仅对专用于检查、诊断、测试框架或开发者工具的工具设置 annotations.debugging 为 true；当工具输出可能包含不可信来源数据时，设置 annotations.untrustedContentHint 为 true。即使 schema 严格，也应在工具实现内验证业务规则，并返回有助于智能体修正输入后重试的描述性错误。仅在 UI 与应用状态反映工具效果后返回结果。在 Chrome 153+ 上，接受始终存在的 { signal } 作为第二个 execute 参数并传给可取消的工作。当工具可用性依赖路由、选择或页面状态时，仅在有效期间注册，并通过中止传给 registerTool() 的 AbortController 来注销过期工具；在 Chrome 148 过渡窗口期，中止前还应以可选链调用 modelContext.unregisterTool?.()。声明式工具需在目标 <form> 上标注 toolname 与 tooldescription，由表单控件定义参数面；使用 label 或 toolparamdescription 生成清晰的参数描述；仅在页面应在智能体填充表单后自动提交时使用 toolautosubmit。
第四步：安全接入智能体驱动 UX。 即使页面支持智能体调用，也要保留正常的人类交互路径。当工具需要明确确认或面向用户的步骤时，应经由应用可见 UI 与既有授权检查；当前 execute(input, { signal }) 契约不提供客户端回调。自定义声明式提交处理时，应在 respondWith() 前调用 preventDefault()，并为智能体发起的提交返回结构化验证错误。仅在兼容性感知的 UI 逻辑后使用预览专用事件（如 toolactivated、toolcancel、agentInvoked 及 WebMCP 表单伪类）；对于 toolactivated 和 toolcancel，应先在 document.modelContext 上特性检测其 on* 属性，再回退到 window。即使 consequentialHint 为 true，破坏性或敏感操作仍应置于可见用户确认与既有授权检查之后；该注解只提示智能体，不强制执行应用安全。保持 UI 状态同步，使同一页面能准确反映人类输入与工具调用造成的变更。
第五步：验证行为。 测试注册与注销生命周期，包括重复名称保护与路由/状态变化时的清理；测试非法或不完整输入，确认工具返回纠正性错误而非静默失败；对声明式工具验证生成的参数描述、必填字段、提交行为及自定义 respondWith() 处理；若目标环境是当前 Chrome 预览，先依据 references/compatibility.md 确认所需版本与标志状态；通过中止传给 executeTool() 的 signal 测试执行取消；仅在验证时使用 Model Context Tool Inspector 或等效预览工具，不作为运行时依赖。先通过检查已注册工具集并手动以代表性参数调用，验证确定性执行，再验证自然语言路由。确认所有高风险、不可逆或现实世界命令式工具声明了 annotations.consequentialHint: true 并仍执行应用的确认与授权流程；确认专用于检查、诊断、测试或开发者工具的工具声明了 annotations.debugging: true，而面向用户的工具保持未设置或 false。编辑后运行工作区构建、类型检查或测试。
错误处理
若 document.modelContext 与 navigator.modelContext 均缺失，确认代码运行在安全浏览器窗口上下文中，并检查 references/compatibility.md 中的预览要求。若仅存在 navigator.modelContext，页面运行在旧版 Chrome 146–149 预览构建上，应保留回退并计划在弃用窗口关闭后移除。在 try/catch 中 await registerTool()：Chrome 151.0.7922.0+ 返回会在失败时拒绝的 Promise<void>，旧版同步返回并抛出，同一 await + try/catch 可同时捕获。若抛出 InvalidStateError，检查重复名称、空名称或描述、名称超过 128 字符或含不允许字符；若抛出 NotAllowedError，检查 tools Permissions Policy 是否被拒绝，跨源 iframe 需要嵌入文档提供 allow="tools"；若抛出 TypeError 或 JSON 序列化错误，将不可序列化或循环的 inputSchema 值替换为纯 JSON 兼容对象。若旧演示或文章引用 provideContext、clearContext 或 toolparamtitle，应视为已过时。若声明式执行未正确更新页面，先阅读 references/declarative-api.md 与 references/troubleshooting.md 再修改工具契约。
适用场景
适用于 JavaScript/TypeScript 浏览器 Web 应用中的 WebMCP 集成实现与调试，涵盖命令式工具注册、声明式表单暴露、智能体驱动交互以及相关兼容性与错误排查。
限制
集成必须运行在安全的窗口浏览上下文中。若功能必须在服务器、worker 中或无可见浏览上下文的无头环境运行，该技能不再适用。若项目不是浏览器 Web 应用，也不适用。部分注解（如 consequentialHint、debugging）仅在特定 Chrome 版本上可用，具体版本信息已在资料中给出；其他平台或版本的支持情况暂未提供。