@opentiny/next-sdk 0.3.2 → 0.3.3-alpha.1

package/index.ts

@@ -57,17 +57,5 @@ export {
 
 export * from '@mcp-b/webmcp-polyfill'
 
-import { initializeWebMCPPolyfill } from '@mcp-b/webmcp-polyfill'
-import { setupModelContextBridge } from './page-tools/bridge'
-import { isBrowser } from './utils/env'
-
-export const initializeBuiltinWebMCP = () => {
-  if (isBrowser()) {
-    try {
-      initializeWebMCPPolyfill()
-      setupModelContextBridge()
-    } catch (err) {
-      console.warn('[next-sdk] 自动注入 modelContext polyfill 和桥接同步失败:', err)
-    }
-  }
-}
+export { initializeBuiltinWebMCP } from './page-tools/initialize-builtin-WebMCP'
+export { registerPageAgentTool } from './page-tools/page-agent-tool'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentiny/next-sdk",
-  "version": "0.3.2",
+  "version": "0.3.3-alpha.1",
   "type": "module",
   "homepage": "https://docs.opentiny.design/next-sdk/guide/",
   "repository": {
@@ -40,18 +40,25 @@
     "@ai-sdk/deepseek": "1.0.30",
     "@ai-sdk/provider": "^3.0.0",
     "@ai-sdk/mcp": "^1.0.0",
-    "@mcp-b/webmcp-polyfill": "^2.2.0",
+    "@mcp-b/webmcp-polyfill": "^3.0.0",
+    "@page-agent/page-controller": "^1.9.0",
     "qrcode": "^1.5.4",
     "zod": "^3.25.76",
+    "zod-to-json-schema": "^3.25.2",
     "ajv": "^8.17.1",
-    "ai": "^6.0.0"
+    "ai": "^6.0.0",
+    "dom-accessibility-api": "^0.6.3",
+    "aria-query": "^5.3.2",
+    "tabbable": "^6.2.0",
+    "diff": "^7.0.0"
   },
   "devDependencies": {
     "typescript": "~5.9.3",
     "vite": "^7.1.7",
     "vite-plugin-dts": "^3.9.1",
     "@types/qrcode": "^1.5.5",
-    "@types/node": "^24.3.0"
+    "@types/node": "^24.6.0",
+    "@types/diff": "^7.0.0"
   },
   "publishConfig": {
     "access": "public"

package/page-tools/a11y-tree.ts

@@ -0,0 +1,532 @@
+/**
+ * a11y-tree.ts
+ *
+ * 浏览器内语义化 ARIA 树生成器（重构版）
+ *
+ * 核心改进：
+ * 1. 两阶段处理：buildVNode（构建中间树）→ serializeVNode（剪枝序列化）
+ * 2. 统一剪枝规则：无 ref 且无 accessible name → 透明穿透（跳过本节点，保留子节点）
+ *    - 兼顾操作场景（去掉 generic/list/listitem 噪音）
+ *    - 兼顾内容理解场景（有 name 的 listitem 等节点保留）
+ * 3. 修复全局可变状态：refCounter 改为局部对象，消除并发调用隐患
+ *
+ * 依赖：
+ *   - dom-accessibility-api: W3C AccName 规范 JS 实现（计算 accessible name）
+ *   - tabbable: 可交互/可聚焦元素检测（工业级，处理所有边界情况）
+ */
+
+import { computeAccessibleName } from 'dom-accessibility-api'
+import { isFocusable } from 'tabbable'
+
+// ─── 类型定义 ────────────────────────────────────────────────────────────────
+
+/** ref 索引 → HTMLElement 映射，供 click/fill/select 操作使用 */
+export type RefMap = Map<number, HTMLElement>
+
+/** 内部中间态节点，与 DOM 解耦，便于剪枝和序列化 */
+interface VNode {
+  role: string
+  /** W3C AccName 算法计算出的语义化名称 */
+  name: string
+  tokens: string[]
+  /** 只有交互节点才有 ref */
+  ref?: number
+  el: HTMLElement
+  children: VNode[]
+}
+
+export interface A11yTreeOptions {
+  /**
+   * 是否启用剪枝：无 ref 且无 accessible name 的节点透明穿透
+   * 默认 true（推荐）
+   */
+  pruneUnnamed?: boolean
+  /**
+   * 强制保留的角色列表，即使无 name 也不穿透（优先级最高）
+   * 例如：['table', 'row'] 用于保留表格结构
+   */
+  preserveRoles?: string[]
+}
+
+export interface A11yTreeResult {
+  /** 语义化 YAML 文本（供 AI 阅读和 Diff 计算） */
+  yaml: string
+  /** ref 索引 → HTMLElement 映射（供后续操作使用） */
+  refMap: RefMap
+  /** 可交互元素总数 */
+  interactiveCount: number
+  /** 原始行数组（不含 yaml 代码块包裹），供搜索使用 */
+  lines: string[]
+}
+
+/** 关键词搜索选项 */
+export interface SearchA11yTreeOptions extends A11yTreeOptions {
+  /**
+   * 每个匹配行前后保留的上下文行数（类似 grep -C N）
+   * 默认 2
+   */
+  contextLines?: number
+  /**
+   * 是否大小写不敏感，默认 true
+   */
+  caseInsensitive?: boolean
+  /**
+   * 最大返回匹配分组数（防止命中过多撑爆上下文），默认 20
+   */
+  maxMatches?: number
+}
+
+/** 单个匹配分组 */
+export interface A11ySearchMatch {
+  /** 主命中行行号（1-based） */
+  lineNumber: number
+  /** 主命中行内容 */
+  line: string
+  /** 含上下文的行列表（带行号） */
+  context: Array<{ lineNumber: number; line: string }>
+}
+
+/** searchA11yTree 返回值 */
+export interface SearchA11yTreeResult {
+  /** 格式化后可直接发给 LLM 的文本 */
+  text: string
+  /** 结构化匹配列表 */
+  matches: A11ySearchMatch[]
+  /** 无障碍树总行数 */
+  totalLines: number
+  /** 原始命中行数（去重前） */
+  matchCount: number
+}
+
+// ─── ARIA 隐式角色静态映射表（覆盖页面 95%+ 的常用标签）───────────────────────
+
+const TAG_ROLE_MAP: Record<string, string> = {
+  a: 'link',
+  article: 'article',
+  aside: 'complementary',
+  button: 'button',
+  caption: 'caption',
+  cell: 'cell',
+  checkbox: 'checkbox',
+  code: 'code',
+  columnheader: 'columnheader',
+  combobox: 'combobox',
+  datalist: 'listbox',
+  dd: 'definition',
+  details: 'group',
+  dialog: 'dialog',
+  dt: 'term',
+  em: 'emphasis',
+  fieldset: 'group',
+  figure: 'figure',
+  footer: 'contentinfo',
+  form: 'form',
+  h1: 'heading',
+  h2: 'heading',
+  h3: 'heading',
+  h4: 'heading',
+  h5: 'heading',
+  h6: 'heading',
+  header: 'banner',
+  hr: 'separator',
+  img: 'img',
+  input: 'textbox',         // 默认，具体 type 下面会覆盖
+  li: 'listitem',
+  link: 'link',
+  main: 'main',
+  mark: 'mark',
+  math: 'math',
+  menu: 'list',
+  menuitem: 'menuitem',
+  meter: 'meter',
+  nav: 'navigation',
+  ol: 'list',
+  option: 'option',
+  output: 'status',
+  p: 'paragraph',
+  progress: 'progressbar',
+  rowheader: 'rowheader',
+  search: 'search',
+  section: 'region',
+  select: 'listbox',
+  strong: 'strong',
+  summary: 'button',
+  table: 'table',
+  tbody: 'rowgroup',
+  td: 'cell',
+  tfoot: 'rowgroup',
+  th: 'columnheader',
+  thead: 'rowgroup',
+  time: 'time',
+  tr: 'row',
+  ul: 'list',
+}
+
+// input[type=*] 的角色覆盖
+const INPUT_TYPE_ROLE: Record<string, string> = {
+  button: 'button',
+  checkbox: 'checkbox',
+  color: 'textbox',
+  email: 'textbox',
+  file: 'textbox',
+  image: 'button',
+  number: 'spinbutton',
+  radio: 'radio',
+  range: 'slider',
+  reset: 'button',
+  search: 'searchbox',
+  submit: 'button',
+  tel: 'textbox',
+  text: 'textbox',
+  url: 'textbox',
+}
+
+// ─── 工具函数 ────────────────────────────────────────────────────────────────
+
+/**
+ * 获取元素的 ARIA 角色
+ * 优先级：显式 role 属性 > 标签隐式角色 > 'generic'
+ */
+function inferRole(el: Element): string {
+  const explicit = el.getAttribute('role')
+  if (explicit && explicit !== 'presentation' && explicit !== 'none') {
+    return explicit
+  }
+  const tag = el.tagName.toLowerCase()
+  if (tag === 'input') {
+    const inputType = (el as HTMLInputElement).type?.toLowerCase() ?? 'text'
+    return INPUT_TYPE_ROLE[inputType] ?? 'textbox'
+  }
+  return TAG_ROLE_MAP[tag] ?? 'generic'
+}
+
+/**
+ * 收集节点的 ARIA 状态 token
+ * 格式：[checked] [selected] [disabled] [hasPopup] [cursor=pointer] [value="..."]
+ */
+function getStateTokens(el: Element): string[] {
+  const tokens: string[] = []
+  const aria = (k: string) => el.getAttribute(k)
+
+  const checked = aria('aria-checked')
+  if (checked === 'true') tokens.push('checked')
+  else if (checked === 'false') tokens.push('unchecked')
+
+  if (aria('aria-selected') === 'true') tokens.push('selected')
+
+  const disabled = aria('aria-disabled') === 'true' || (el as HTMLInputElement).disabled
+  if (disabled) tokens.push('disabled')
+
+  const hasPopup = aria('aria-haspopup')
+  if (hasPopup && hasPopup !== 'false') tokens.push('hasPopup')
+
+  if (aria('aria-expanded') === 'true') tokens.push('expanded')
+
+  // heading level（h1-h6）
+  const headingMatch = el.tagName.match(/^H([1-6])$/)
+  if (headingMatch) tokens.push(`level=${headingMatch[1]}`)
+  const ariaLevel = aria('aria-level')
+  if (ariaLevel && !headingMatch) tokens.push(`level=${ariaLevel}`)
+
+  // cursor=pointer 表示"视觉上可点击"
+  try {
+    const style = window.getComputedStyle(el as HTMLElement)
+    if (style.cursor === 'pointer') tokens.push('cursor=pointer')
+  } catch {
+    // 某些元素 getComputedStyle 可能抛异常，忽略
+  }
+
+  // 记录输入元素的值，以便在 fill/输入后在 A11y 树中显示并产生 Diff
+  const tag = el.tagName.toLowerCase()
+  if (tag === 'input' || tag === 'textarea' || tag === 'select') {
+    const val = (el as HTMLInputElement).value
+    if (val !== undefined && val !== '') {
+      tokens.push(`value="${val}"`)
+    }
+  }
+  const valuenow = el.getAttribute('aria-valuenow')
+  if (valuenow) {
+    tokens.push(`valuenow="${valuenow}"`)
+  }
+
+  return tokens
+}
+
+/** 判断元素是否应被跳过（不可见或在黑名单中） */
+function isHidden(el: Element): boolean {
+  if (el.getAttribute('aria-hidden') === 'true') return true
+  if ((el as HTMLElement).hidden) return true
+  try {
+    const style = window.getComputedStyle(el as HTMLElement)
+    if (style.display === 'none' || style.visibility === 'hidden') return true
+  } catch {
+    // 忽略
+  }
+  return false
+}
+
+// ─── 阶段 1：构建 VNode 中间树 ────────────────────────────────────────────────
+
+/**
+ * 递归将 DOM 元素转换为 VNode 中间表示
+ * @param el 当前 DOM 元素
+ * @param refCounter 引用计数器（使用对象引用避免全局可变状态）
+ * @param refMap ref 索引 → 元素映射
+ * @param blacklistSet 用户自定义黑名单
+ */
+function buildVNode(
+  el: Element,
+  refCounter: { value: number },
+  refMap: RefMap,
+  blacklistSet: Set<Element>,
+  whitelistSet: Set<Element>,
+): VNode | null {
+  if (isHidden(el) || blacklistSet.has(el)) return null
+
+  const role = inferRole(el)
+  const tokens = getStateTokens(el)
+  const name = computeAccessibleName(el as HTMLElement)
+  const isTrulyInteractive = isFocusable(el as HTMLElement)
+  const isVisuallyClickable = tokens.includes('cursor=pointer')
+  const isWhitelisted = whitelistSet.has(el)
+  // generic 无 name 时，即使有 cursor=pointer 也不分配 ref：
+  // cursor 通常是 CSS 继承传播的，这类 div 本身无法被有意义地操作
+  const interactive = isTrulyInteractive || isWhitelisted || (isVisuallyClickable && (role !== 'generic' || name !== ''))
+
+  let ref: number | undefined
+  if (interactive) {
+    ref = refCounter.value
+    refMap.set(ref, el as HTMLElement)
+    refCounter.value++
+  }
+
+  const children: VNode[] = []
+  for (const child of Array.from(el.children)) {
+    const childVNode = buildVNode(child, refCounter, refMap, blacklistSet, whitelistSet)
+    if (childVNode) children.push(childVNode)
+  }
+
+  return { role, name, tokens, ref, el: el as HTMLElement, children }
+}
+
+// ─── 阶段 2：剪枝序列化 ──────────────────────────────────────────────────────
+
+/**
+ * 判断 VNode 子树是否包含任何有价值的节点（有 ref 或有 accessible name）
+ * 用于过滤空容器子树，避免输出无内容的嵌套层级
+ */
+function hasValue(vnode: VNode): boolean {
+  if (vnode.ref !== undefined || vnode.name.trim() !== '') return true
+  return vnode.children.some(hasValue)
+}
+
+/**
+ * 判断节点是否需要透明穿透（跳过本节点但保留子节点）
+ *
+ * 统一规则：无 ref（非交互）且无 accessible name → 穿透
+ * 这样可以同时：
+ * - 去掉 generic/list/listitem 等纯布局噪音（无 name 时穿透）
+ * - 保留有 name 的 listitem（有 name 时保留，兼顾内容理解场景）
+ */
+function shouldPassThrough(vnode: VNode, opts: Required<A11yTreeOptions>): boolean {
+  if (!opts.pruneUnnamed) return false
+  // preserveRoles 中的角色强制保留
+  if (opts.preserveRoles.includes(vnode.role)) return false
+  // 有 ref（交互节点）→ 永远保留
+  if (vnode.ref !== undefined) return false
+  // 有 accessible name → 保留（兼顾内容理解场景）
+  if (vnode.name.trim() !== '') return false
+  // 无 ref 且无 name → 透明穿透
+  return true
+}
+
+/**
+ * 将 VNode 序列化为 YAML 行数组
+ * 穿透节点时，子节点在当前 depth 平铺输出（不增加缩进层级）
+ */
+function serializeVNode(
+  vnode: VNode,
+  depth: number,
+  opts: Required<A11yTreeOptions>,
+): string[] {
+  if (shouldPassThrough(vnode, opts)) {
+    // 透明穿透：跳过本节点，子节点保持当前 depth（层级不增加）
+    // 同时过滤掉整棵子树都无价值的空容器，避免输出无意义的嵌套
+    return vnode.children
+      .filter(c => hasValue(c))
+      .flatMap(c => serializeVNode(c, depth, opts))
+  }
+
+  const indent = '  '.repeat(depth)
+  const refStr = vnode.ref !== undefined ? ` #${vnode.ref}` : ''
+  const tokenStr = vnode.tokens.length > 0 ? ` [${vnode.tokens.join(' ')}]` : ''
+  const nameStr = vnode.name ? ` "${vnode.name}"` : ''
+  const line = `${indent}- ${vnode.role}${refStr}${tokenStr}${nameStr}`
+
+  const childLines = vnode.children.flatMap(c => serializeVNode(c, depth + 1, opts))
+  return [line, ...childLines]
+}
+
+// ─── 主入口 ──────────────────────────────────────────────────────────────────
+
+const DEFAULT_OPTIONS: Required<A11yTreeOptions> = {
+  pruneUnnamed: true,
+  preserveRoles: [],
+}
+
+/**
+ * 生成当前页面的语义化 ARIA YAML 树
+ *
+ * @param root 遍历起点，默认 document.body
+ * @param blacklist 需要跳过的元素（用户自定义黑名单）
+ * @param whitelist 需要识别为可交互的白名单元素列表
+ * @param options 过滤选项
+ */
+export function buildA11yTree(
+  root: Element = document.body,
+  blacklist: Element[] = [],
+  whitelist: Element[] = [],
+  options?: A11yTreeOptions,
+): A11yTreeResult {
+  const opts: Required<A11yTreeOptions> = { ...DEFAULT_OPTIONS, ...options }
+  // 使用对象引用避免全局可变状态，消除并发调用隐患
+  const refCounter = { value: 0 }
+  const refMap: RefMap = new Map()
+  const blacklistSet = new Set(blacklist)
+  const whitelistSet = new Set(whitelist)
+  const lines: string[] = []
+
+  for (const child of Array.from(root.children)) {
+    const vnode = buildVNode(child, refCounter, refMap, blacklistSet, whitelistSet)
+    if (vnode) {
+      lines.push(...serializeVNode(vnode, 0, opts))
+    }
+  }
+
+  const yaml = '```yaml\n' + lines.join('\n') + '\n```'
+
+  return {
+    yaml,
+    refMap,
+    interactiveCount: refMap.size,
+    lines,
+  }
+}
+
+// ─── 关键词搜索 ──────────────────────────────────────────────────────────────
+
+/**
+ * 在无障碍树中按关键词搜索，返回带行号的匹配结果和上下文
+ *
+ * 支持的搜索维度（均对同一个 query 字符串做包含匹配）：
+ *   - role：如 `button`、`link`、`heading`
+ *   - accessible name：节点的语义化名称（引号内文本）
+ *   - state token：如 `checked`、`disabled`、`expanded`
+ *   - ref 索引：如 `#5`
+ *
+ * @example
+ *   searchA11yTree('button')    // 找全部按钮
+ *   searchA11yTree('提交')      // 找名称含"提交"的节点
+ *   searchA11yTree('#3')        // 找 ref #3
+ */
+export function searchA11yTree(
+  query: string,
+  root: Element = document.body,
+  blacklist: Element[] = [],
+  whitelist: Element[] = [],
+  options?: SearchA11yTreeOptions,
+): SearchA11yTreeResult {
+  const {
+    contextLines = 2,
+    caseInsensitive = true,
+    maxMatches = 20,
+    ...treeOptions
+  } = options ?? {}
+
+  // 复用 buildA11yTree 生成完整树，直接取 lines 数组（不重复构建 DOM 遍历）
+  const { lines } = buildA11yTree(root, blacklist, whitelist, treeOptions)
+
+  const needle = caseInsensitive ? query.toLowerCase() : query
+  const totalLines = lines.length
+
+  const isRefQuery = /^#\d+$/.test(query)
+  const refRegex = isRefQuery ? new RegExp(`\\s${query}(?:\\s|[\\[]|$)`) : null
+
+  // 找出所有命中行的下标（0-based）
+  const hitIndices: number[] = []
+  for (let i = 0; i < lines.length; i++) {
+    let matched = false
+    if (refRegex) {
+      matched = refRegex.test(lines[i])
+    } else {
+      const haystack = caseInsensitive ? lines[i].toLowerCase() : lines[i]
+      matched = haystack.includes(needle)
+    }
+    if (matched) {
+      hitIndices.push(i)
+    }
+  }
+
+  // 合并重叠的上下文区间，避免重复输出行
+  const mergedRanges: Array<{ start: number; end: number; hits: number[] }> = []
+  let isTruncated = false
+  for (const idx of hitIndices) {
+    const start = Math.max(0, idx - contextLines)
+    const end = Math.min(totalLines - 1, idx + contextLines)
+    const last = mergedRanges[mergedRanges.length - 1]
+    if (last && start <= last.end + 1) {
+      // 区间重叠或紧邻，合并
+      last.end = Math.max(last.end, end)
+      last.hits.push(idx)
+    } else {
+      if (mergedRanges.length >= maxMatches) {
+        isTruncated = true
+        break
+      }
+      mergedRanges.push({ start, end, hits: [idx] })
+    }
+  }
+
+  // 构建结构化结果
+  const matches: A11ySearchMatch[] = mergedRanges.map((range) => ({
+    lineNumber: range.hits[0] + 1,
+    line: lines[range.hits[0]],
+    context: Array.from({ length: range.end - range.start + 1 }, (_, k) => ({
+      lineNumber: range.start + k + 1,
+      line: lines[range.start + k],
+    })),
+  }))
+
+  // 格式化为可读文本（模仿 grep -n -C 风格，便于 LLM 直接理解）
+  const textParts: string[] = [
+    `无障碍树搜索结果 — 关键词: "${query}" | 总行数: ${totalLines} | 命中: ${hitIndices.length} 行 | 返回分组: ${matches.length}`,
+    '',
+  ]
+
+  if (matches.length === 0) {
+    textParts.push('（未找到匹配项）')
+  } else {
+    matches.forEach((match, m) => {
+      const range = mergedRanges[m]
+      textParts.push(`── 分组 ${m + 1}（第 ${range.start + 1}–${range.end + 1} 行）──`)
+      match.context.forEach(({ lineNumber, line }) => {
+        const isHit = range.hits.includes(lineNumber - 1)
+        const ln = String(lineNumber).padStart(4)
+        // 命中行用 >>> 标记，上下文行用普通行号前缀
+        textParts.push(isHit ? `>>>${ln} | ${line}` : `   ${ln} | ${line}`)
+      })
+      textParts.push('')
+    })
+    if (isTruncated) {
+      textParts.push(`⚠️ 命中过多，已截断至前 ${maxMatches} 个分组，建议缩小搜索范围`)
+    }
+    textParts.push(`提示：如需操作命中元素，使用其 #N 索引；如需查看完整树，请使用 browserState。`)
+  }
+
+  return {
+    text: textParts.join('\n'),
+    matches,
+    totalLines,
+    matchCount: hitIndices.length,
+  }
+}

package/page-tools/bridge.ts

@@ -609,29 +609,49 @@ export function registerPageTool(options: RegisterPageToolByHandlersOptions): ()
  * 我们通过此函数进行拦截劫持，并同步到 next-sdk 的握手线路 (MSG_TOOL_REGISTERED / MSG_TOOL_UNREGISTERED)，
  * 从而保证无论浏览器是否原生支持，均能正常完成 WebMCP 握手交互。
  */
+// 已注册工具列表（由 setupModelContextBridge 维护）
+// 供 content.ts 通过 window.__nextSdkRegisteredTools() 跨沙箱查询完整工具定义
+const _registeredTools = new Map<string, any>()
+
 export function setupModelContextBridge() {
-  if (typeof navigator === 'undefined') return
-  const nav = navigator as any
-  const nativeCtx = nav.modelContext
+  if (typeof document === 'undefined') return
+  const doc = document as any
+  const nativeCtx = doc.modelContext
 
   // 如果不存在或者已经被拦截过，则不处理
   if (!nativeCtx || nativeCtx.__isNextSdkBridgeSetup) return
 
+  // 挂载全局查询函数，供 content script（隔离沙箱）访问
+  // 注意：必须强制覆盖，不检查是否已存在。
+  // init-webmcp.js 的 fallback polyfill 会提前注册一个基于内联 Map 的版本，
+  // 而该版本无法感知 bridge 拦截后的注册行为，必须用 bridge 版覆盖。
+  if (isBrowser()) {
+    ;(window as any).__nextSdkRegisteredTools = () => Array.from(_registeredTools.values())
+  }
+
   const originalRegisterTool = nativeCtx.registerTool?.bind(nativeCtx)
   const originalUnregisterTool = nativeCtx.unregisterTool?.bind(nativeCtx)
 
   if (typeof originalRegisterTool === 'function') {
-    nativeCtx.registerTool = (config: any) => {
+    nativeCtx.registerTool = (config: any, options?: any) => {
       const name = config.name
       const toolConfig = { ...config } // 拷贝一份，避免修改用户原始对象
 
-      // 1. 识别路由配置核心件：原生格式下仅从 config.routeConfig 对象识别
+      // 1. 监听 AbortSignal 以同步卸载状态
+      if (options?.signal) {
+        options.signal.addEventListener('abort', () => {
+          _registeredTools.delete(name)
+          broadcastToolChange(MSG_TOOL_UNREGISTERED)
+        })
+      }
+
+      // 2. 识别路由配置核心件：原生格式下仅从 config.routeConfig 对象识别
       const routeConfig: RouteConfig | null =
         toolConfig.routeConfig && typeof toolConfig.routeConfig === 'object' && 'route' in toolConfig.routeConfig
           ? (toolConfig.routeConfig as RouteConfig)
           : null
 
-      // 2. 如果存在路由配置，且当前不在该目标页面，则包装为自动跳转的 handler
+      // 3. 如果存在路由配置，且当前不在该目标页面，则包装为自动跳转的 handler
       if (routeConfig) {
         const normalizedRoute = normalizeRoute(routeConfig.route)
         const effectConfig = resolveRuntimeEffectConfig(name, toolConfig.title, routeConfig.invokeEffect)
@@ -643,24 +663,38 @@ export function setupModelContextBridge() {
         delete toolConfig.routeConfig
       }
 
-      // 3. 执行底层的原生注册逻辑并广播同步
+      // 4. 维护工具定义，供 content.ts 握手查询
+      _registeredTools.set(name, {
+        name,
+        title: config.title,
+        description: config.description,
+        inputSchema: config.inputSchema
+      })
+
+      // 5. 执行底层的原生注册逻辑并广播同步
       try {
-        originalRegisterTool(toolConfig)
+        originalRegisterTool(toolConfig, options)
         broadcastToolChange(MSG_TOOL_REGISTERED)
       } catch (err) {
+        // 如果注册失败，撤销记录
+        _registeredTools.delete(name)
         // 忽略重复注册错误
       }
     }
   }
 
-  if (typeof originalUnregisterTool === 'function') {
-    nativeCtx.unregisterTool = (name: string) => {
-      try {
+  // 无论原生是否提供 unregisterTool，都在 bridge 侧保证此方法存在，从而向后兼容老旧的卸载写法
+  nativeCtx.unregisterTool = (name: string) => {
+    try {
+      if (typeof originalUnregisterTool === 'function') {
         originalUnregisterTool(name)
-        broadcastToolChange(MSG_TOOL_UNREGISTERED)
-      } catch (err) {
-        // 忽略注销错误
       }
+    } catch (err) {
+      // 忽略原生注销错误
+    } finally {
+      // 从工具名集合中移除
+      _registeredTools.delete(name)
+      broadcastToolChange(MSG_TOOL_UNREGISTERED)
     }
   }