| name | next-sdk-page-agent |
| description | @opentiny/next-sdk 的 page-agent-tool / a11y / registerPageAgentTool 相关开发。 在修改 page-tools、无障碍配置、console-cloud 预设、runtime 注入时使用。 |
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-20260722-console-layout-landmark/、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()；重复调用为 replace 式重新初始化。- 运行期唯一配置面：
getPageAgentToolConfig / setPageAgentToolConfig（a11yConfig 数组合并；enableHighlight 覆盖；支持 mode: 'replace'）。
whitelist / blacklist 中的选择器字符串在构建无障碍树时 动态解析。A11yRoleRule.name：可选声明可访问名（不改 DOM），用于 landmark / 布局容器在 YAML 中保留分区名。- 站点预设：云控制台用
consoleCloudPageAgentToolOptions + isConsoleCloudHost()（含 ti-app-layout-* landmark）。
clipboard action：text 有值写剪切板、无值读剪切板；不依赖 index、不展示 mask；handler 见 page-tools/handlers/clipboard.ts。
测试落点
packages/next-sdk/test/page-tools/（Vitest + jsdom）
修 Bug 须在用例中用中文写清复现场景，例如：
it('复现：… —— 前置…；步骤…；期望…', () => {})
注意
