企业官网建设流程全解析

WebMCP 声明式 API 终极指南：用

零 JS 把网页表单变成 AI 可调用工具

【免费下载链接】webmcp🤖 WebMCP项目地址: https://gitcode.com/gh_mirrors/webm/webmcp

WebMCP 声明式 API 让你无需写一行 JavaScript，只需给现有的<form>加几个 HTML 属性，就能把网页表单变成 AI 智能体（Agent）可直接发现、填写并提交的工具。本文带你快速上手这套 WebMCP 表单工具新玩法，看懂浏览器如何自动合成参数、如何把提交结果传回给 AI。

什么是 WebMCP？为什么需要"声明式"？

WebMCP 是浏览器层面的开放提案：网页可以把自己的功能注册为"工具"（Tool），供浏览器内置 AI 助手、扩展或页内智能体直接调用，而不用让 AI 靠截图、模拟点击去笨拙地"操控"界面。

WebMCP 提供两种注册方式：

设计文档曾明确回答过"为什么不只保留声明式"：网站的功能不可能只有表单，JavaScript 逻辑才构成 Web 的全部能力；反过来，声明式 API 则让"表单类功能"零成本接入 AI。两者互补，各管一摊。🧩

一键上手：3 个 HTML 属性把 变成 AI 工具

声明式 API 的核心，是给表单加上 3 个新属性（详见 declarative-api-explainer.md）：

<form toolname="Search flights" tooldescription="This form searches flights and displays results" toolautosubmit> <!-- 原有 input / select / button 保持不变 --> </form>

• toolname：工具名，相当于命令式 API 中的name，AI 靠它识别"这是干什么的"。
• tooldescription：自然语言描述，告诉 AI 何时该调用这个表单。
• toolautosubmit（布尔属性）：允许 AI 填完表单后直接代用户提交；如果省略它，AI 填完后会把焦点放到提交按钮上，并提示用户人工检查、手动提交——这对下单、付款等敏感操作非常友好。🛡️

表单被插入、移除或属性更新时，浏览器会自动生成/销毁对应的声明式工具，你无需任何监听代码。

表单如何"编译"成 AI 能看懂的参数？

浏览器会把表单确定性地"合成"为一份 JSON 输入模式（input schema），AI 据此知道每个字段该填什么。规则非常直观：

• 控件的name属性 → schema 中的属性名；
• 新增的toolparamdescription属性 → 每个参数的自然语言描述；
• required属性 → 必填字段；
• min/max/step等约束 → 数值范围声明（精确算法仍在试验中，Chromium 正在实现宽松版本并做社区验证）。

例如以下纯 HTML 表单：

<form toolname="search-cars" tooldescription="Perform a car make/model search"> <input type="text" name="make" toolparamdescription="The vehicle's make (e.g., BMW, Ford)" required> <input type="text" name="model" toolparamdescription="The vehicle's model (e.g., 330i, F-150)" required> <button type="submit">Search</button> </form>

就与一段命令式注册代码完全等价——AI 会拿到make、model两个必填字符串参数，各带清晰的说明文字。这就是"零 JS"的含义：语义化 HTML 本身就是工具的 API 文档。📄

AI 调用表单的完整生命周期：从填写到拿到结果

1. 发现：AI 查询当前页面的工具列表，看到toolname与描述。
2. 填写：AI 按合成的 input schema 逐字段填值。
3. 提交：有toolautosubmit时直接提交；否则等待用户确认。
4. 拿回结果，有两条通道（这也是声明式 API 的精髓——JS 是可选的）：
   • 无跳转 + JS 增强：页面可用SubmitEvent#respondWith()拦截默认提交，把任意结构化数据直接回传给 AI，页面不跳转；
   • 纯 HTML 方案：表单提交跳转后，目标页面上第一个<script type="application/ld+json">结构化数据会被作为工具响应回传给 AI。完全不想写 JS？这条路径就够了。

另外还有两个"小细节"值得知道：

• 表单被 reset 或toolname变化时，正在执行的工具调用会自动取消并通知 AI；
• 新增 CSS 伪类:tool-form-active和:tool-submit-active，可高亮"AI 已填好、等你确认"的表单，toolactivated/toolcanceled事件则提供同样的 JS 钩子。✨

最佳实践：让 AI 工具又快又稳

• 控制工具预算：AI 的上下文窗口有限，每注册一个工具都要占 token，工具太多会拖慢推理、引发混淆——简单站点静态注册几个即可，复杂应用按需动态增删表单属性。
• 单一职责：一个表单只做一个明确的事，避免功能重叠让 AI"选择困难"。
• 命名要精准：动词区分"立即执行"与"开始流程"（如create-eventvsstart-event-creation）；描述用正向陈述，说清"做什么、何时用"。
• 别让 AI 做数学题：接受原始输入、在页面端做归一化；枚举值用自然语言（"express"而非内部 ID1）。
• 状态保持同步：AI 和用户共享同一个页面，工具执行后要立刻更新可见 UI。

完整建议见 README.md 的 Best Practices 章节。

浏览器支持现状：现在就能试吗？

根据 implementation-status.md：

延伸阅读：关键文件导航 📚

• 声明式 API 提案全文（属性、处理模型、事件）：declarative-api-explainer.md
• W3C 规范草案（ModelContext接口定义，声明式章节待并入）：index.bs
• 背景动机、用例与最佳实践总览：README.md
• 各浏览器/智能体支持进度：implementation-status.md
• 进阶方向：Service Worker 后台注册工具，让用户没打开页面时 AI 也能调用：docs/service-workers.md

给现有表单加 3 个属性，你的网站今天就拥有了面向 AI 时代的"第二套 API"。🚀

【免费下载链接】webmcp🤖 WebMCP项目地址: https://gitcode.com/gh_mirrors/webm/webmcp