opentiny next-sdk Page Agent Skill
动手前（硬门禁）
先遵守根 AGENTS.md「任务分流」。修改下列任一内容前，必须先创建或更新 packages/next-sdk/specs/REQ-YYYYMMDD-slug/（仅当用户明确豁免时可例外）：
- 公开 API / 类型（含
A11yRoleRule、A11yConfig、PageAgentToolOptions等） consoleCloudPageAgentToolOptions或其他默认/预设行为- 无障碍树构建、剪枝、Static-Lift、序列化语义
- 需要更新
docs/webmcp-sdk/page-agent-tool.md的行为说明
近期示例：specs/REQ-20260904-contenteditable-a11y-ref/、specs/REQ-20260903-mask-cursor-lifecycle/、specs/REQ-20260817-clipboard-handler/。
拿不准是否琐碎 → 先问用户，不要默认开写。
何时使用
- 改
packages/next-sdk/page-tools/** - 注册或配置
registerPageAgentTool - 调整
a11yConfig、站点预设consoleCloudPageAgentToolOptions - 改
runtime.ts挂载的 page-agent API
权威长文：docs/webmcp-sdk/page-agent-tool.md
入口
| 入口 | 用途 |
|---|---|
index.ts |
完整浏览器侧导出 |
core.ts |
无 DOM 精简入口（不含完整 page-agent API） |
runtime.ts |
CDN/IIFE：挂 API，不自动 registerPageAgentTool |
关键 API（符号级）
import {
registerPageAgentTool,
getPageAgentToolConfig,
setPageAgentToolConfig,
defineA11yConfig,
consoleCloudPageAgentToolOptions,
isConsoleCloudHost,
buildA11yTree,
searchA11yTree,
PAGE_AGENT_TOOL_CALL_EVENT,
PAGE_AGENT_TOOL_RESULT_EVENT,
} from '@opentiny/next-sdk'
registerPageAgentTool(options?)：注册page-agent-tool，内部调用initializeBuiltinWebMCP()（默认forcePolyfill: true，覆盖会崩溃的 Chromium 实验性 native）；重复调用为 replace 式重新初始化。返回{ showMask, hideMask }。Chrome 146+ 原生registerTool在非 origin-keyed 文档上抛SecurityErrorDOMException；SDK 会中和document/navigatornative 并把 JS polyfill 挂到 document 实例。polyfill 在originAgentCluster === false时也会抛空消息SecurityError，仅对 polyfill 实例绕过该检查。- 运行期唯一配置面：
getPageAgentToolConfig/setPageAgentToolConfig（a11yConfig数组合并；enableHighlight/cursorMode覆盖；支持mode: 'replace'）。 cursorMode：'actionOnly'（默认，仅操作类出光标） /'always'/'never'。无参showMask()默认不出光标；操作类结束后若遮罩仍开着且cursorMode !== 'always'则收光标。always下显式{ showCursor: false }仍可临时隐藏；never覆盖显式showCursor: true。whitelist/blacklist中的选择器字符串在构建无障碍树时 动态解析。A11yRoleRule.name：可选声明可访问名（不改 DOM），用于 landmark / 布局容器在 YAML 中保留分区名。- 站点预设：云控制台用
consoleCloudPageAgentToolOptions+isConsoleCloudHost()（含ti-app-layout-*landmark）。 clipboardaction：text有值写剪切板、无值读剪切板；不依赖index、不展示 mask；handler 见page-tools/handlers/clipboard.ts。- contenteditable：
browserState将自身声明contenteditable的编辑宿主标为textbox（显式 role 优先）、分配 ref、输出[contenteditable]token；fill用该 ref 填写。继承可编辑的子孙不单独占 ref。见REQ-20260904-contenteditable-a11y-ref。
测试落点
packages/next-sdk/test/page-tools/（Vitest + jsdom）
修 Bug 须在用例中用中文写清复现场景，例如：
it('复现：… —— 前置…；步骤…；期望…', () => {})
注意
- 不要再引入已废弃的独立
getA11yConfig/setA11yConfig。 - 包约定见
packages/next-sdk/AGENTS.md。