AGENTS.md@packages/next-sdk git:20260721.cdc264aA

Immutable. This exact content is served forever at /api/v1/blob/406cd288b6253e3b.

# @opentiny/next-sdk — Agent 指南

改本包时先读本文，再按需打开 Skill / Spec / 测试。用户长文见 VitePress `docs/webmcp-sdk/`。

## 推荐能力（主推）

本包面向浏览器 **内置 WebMCP**（`document.modelContext`）。新代码与约束说明请围绕：

- `initializeBuiltinWebMCP()`：注入 polyfill + 桥接
- `document.modelContext.registerTool` / 业务工具注册
- `registerPageAgentTool` 及 a11y / 运行期配置 API

**不要**再把 `WebMcpServer` / `WebMcpClient` 作为默认推荐路径写进指引或示例（历史兼容代码可能仍存在，但非本仓库 Agent 约束的一部分）。

## 模块地图

| 路径 | 职责 |
|---|---|
| `page-tools/` | page-agent-tool、a11y、桥接、高亮/遮罩、`initializeBuiltinWebMCP` |
| `agent/` | `AgentModelProvider`、`getAISDKTools` |
| `remoter/` | `createRemoter`、`QrCode` |
| `skills/index.ts` | **运行时**业务 Skill 工具（给终端用户 Agent），不是编码用 SKILL.md |
| `skills/page-agent/` | **编码** Agent Skill（本包 page-agent） |
| `runtime.ts` / `core.ts` / `index.ts` | 入口差异见下 |
| `specs/` | Feature Spec 实例 |
| `test/` | Vitest 可执行测试 |

## 入口差异

- `index.ts`：完整导出（含 page-agent、remoter、skills API、polyfill）
- `core.ts`：无 DOM 精简（Agent / `initializeBuiltinWebMCP` 等）
- `runtime.ts`：IIFE/CDN，挂 page-agent 相关 API，**不**自动 register

## Page Agent API（摘要）

详见 [`skills/page-agent/SKILL.md`](./skills/page-agent/SKILL.md) 与文档 `docs/webmcp-sdk/page-agent-tool.md`。

符号：`registerPageAgentTool`、`getPageAgentToolConfig`、`setPageAgentToolConfig`、`defineA11yConfig`、`consoleCloudPageAgentToolOptions`、`isConsoleCloudHost`、`buildA11yTree`、`searchA11yTree`、事件常量。

## Spec / 测试就近

- Spec：`packages/next-sdk/specs/REQ-YYYYMMDD-slug/{requirements,design,tasks}.md`
- 测试：`packages/next-sdk/test/**/*.test.ts`（page-tools 相关在 `test/page-tools/`）
- 模板：`docs/ai-engineering/templates/`

## 命令

```bash
pnpm -F @opentiny/next-sdk test
pnpm -F @opentiny/next-sdk build
```