v1.0.0

首个稳定版。核心是跟进 WebMCP 协议把规范入口从 navigator.modelContext 迁移到 document.modelContext（Chrome 150 已废弃前者），并将 @mcp-b/webmcp-polyfill 从 2.3.2 升级到 5.1.0。选 1.0.0 而非 0.2.0，是因为这是协议层的破坏性变更，并以此宣告 SDK 对外 API 自此稳定。

升级是否无感？

代码层面无感：registerGlobalTools / useWebMcpTools / withWebMcpTools 签名与行为不变，构建插件配置不变，工具函数写法不变——业务代码一行都不用改。

但有几个边缘场景会感知到（多是“以前静默容忍、现在显式化”），升级前请对照下表自查。

升级清单（Migration Checklist）

• 桌面 Agent 用户：把 relay 的 embed.js 升到 5.x（CDN 用 @mcp-b/webmcp-local-relay@5）。relay 2.x 在现代 Chrome 上发现不了工具。relay CLI 要求 Node 22+。
• 工具命名：确认工具名只用 [A-Za-z0-9_]（camelCase），不要用中文、空格、.、-，也不要叫 default。非法名现在会在 pnpm build 直接报错（0.1.14 是静默容忍）。
• JSDoc 描述：给每个工具补上描述。空描述不再静默——构建期会兜底成工具名并告警。
• 部署环境：确认页面是 secure context（https 或 localhost）、origin-isolated（不要发 Origin-Agent-Cluster: ?0、不要用 document.domain）；跨源 iframe 需加 allow="tools"。不满足时工具注册会失败（SDK 会按错误类型给可诊断告警）。
• 用了 shadow DOM 或自定义表单提交：polyfill 5.1.0 会改写 Element.prototype.attachShadow 与 HTMLFormElement.prototype.submit（declarative forms 需要），请回归测试。
• 不要同时引入 @mcp-b/global：它会替换 document/navigator 两个面，摧毁 nexus 的兼容层。

可能踩的坑（0.1.14 → 1.0.0 行为差异）

场景	0.1.14	1.0.0
非法工具名	静默注册	pnpm build 报错
空描述	静默	兜底为工具名 + 告警
宿主准入（secure context / origin isolation / Permissions Policy）	不校验	不满足则注册失败 + 可诊断告警
polyfill 全局原型	不改写	改写 attachShadow / HTMLFormElement.submit，自动注册 <form toolname>
桌面 Agent relay	2.x 可用	现代 Chrome 需 relay 5.x

新增能力

• execute 可声明第二参 (params, { signal }) 感知执行取消（现有单参工具零改动；该信号目前仅原生 Chrome 转发）。
• 新增 @title / @untrusted / @consequential 三个 JSDoc 标签，映射到协议的 title 与 annotations。
• 构建期校验左移 + 运行期单点兜底 + 注册失败按 error.name 分流告警 + 幽灵工具防护。
• 新增 webmcp-nexus-sdk/testing 子入口（测试钩子，不污染主 API）。
• 现代宿主零 patch：Object.keys(document.modelContext) 为空，一次路由切换的 toolchange 从 3 次降为 1 次。
• 旧宿主（Chrome 146–148）额外合成 getTools/executeTool，使 relay 5.x 全档可驱动。

已知差异

• consequentialHint 仅原生 Chrome 153+ 生效，polyfill 5.1.0 会丢弃。
• abort 中断 in-flight execution：polyfill 抛 UnknownError（副作用已执行完），Chrome 153+ 返回 null 且不中断。
• relay 5.x 会 sanitize 工具名（[^a-zA-Z0-9_]→_）、多标签页同名追加 _<tabId>；不支持转发 MCP 多轮 elicitation（input_required 会转为错误）。

完整变更见 CHANGELOG.md。