OpenTiny Next 应用集成

在现有 Vue 3 + Vite 业务应用中增量接入 TinyRobot、GenUI、业务 WebMCP 和 PageTool。以目标项目实际安装的包、公开 API 和业务声明为准，不用演示组件、模拟工具或预设回答替代真实接入。

默认完成代码接入验证；只有用户明确要求验证对话、服务或端到端功能时，才执行相应运行时闭环。

选择阶段

只实施用户要求的阶段，并检查它依赖的已有能力。用户要求一次完成全部流程时，按下列依赖顺序执行；缺少运行时配置不阻塞后续代码接入。

阶段	目标	前置能力	详细参考
1	TinyRobot Chat	Vue 3 + Vite 应用	TinyRobot 接入
2	GenUI	已接入的唯一 TinyRobot Chat	GenUI 接入、模板适配
3	业务 WebMCP 与业务 Skill	TinyRobot runtime	业务 WebMCP
4	PageTool	TinyRobot 可消费的 WebMCP 通道	PageTool

若项目已具备某个前置能力，通过源码、依赖和构建证据确认后直接继续，不重复生成或重写。

第二、三阶段都会改变 useLocalChatRuntime 的请求或 MCP 所有权。实施前必须读取 Runtime 所有权，根据目标版本源码中的 guard 选择唯一所有者，不能把两个互斥入口叠加到同一个 runtime。

通用工作方式

1. 确认当前应用目录、Git 与 workspace 边界、包管理器、入口文件、现有聊天实现和 dirty 文件。所有命令都在目标应用边界内执行，保留用户改动。
2. 检查目标项目实际解析的包版本、exports、类型、源码和 runtime 参数校验，再决定导入路径与适配方式；不要只凭记忆或参考项目版本实现。
3. 优先复用项目已有组件、runtime、模型策略、业务状态和测试入口。全应用只保留一个聊天界面。
4. 依赖安装、代码生成或构建失败时，根据原始输出诊断；不要把失败命令、局部文件变化或 mock 结果报告成成功。
5. 业务工具合同和 PageTool 操作范围只来自业务方已有代码、业务合同或用户明确说明。缺少声明时可完成通用基础设施，但必须指出业务方需要修改的实际文件和字段，然后停止对应业务能力实现。

四个阶段

1. TinyRobot Chat

先查找项目中已有的 TinyRobot 组件和挂载链。不存在时，按 TinyRobot 接入 中当前锁定的已发布 CLI 先执行 add chat --dry-run，确认计划后再应用，不使用 create。CLI 版本只约束生成器调用，不替代对目标项目 runtime 版本和 API 的检查。

CLI 生成文件或同名组件存在并不单独证明接入完成。继续前确认：依赖与 lockfile 可解析、TrThemeProvider/TrChat 使用当前包的有效导出、组件在真实入口链中只挂载一次、样式已接入。

2. GenUI

在现有 TrChat 上增加 GenUI，不创建第二个聊天面。兼容时可复用 assets/genui-v1.3.0/；版本或宿主结构不同则逐项适配。

保持普通文本路径、当前模型选择和宿主模型策略。GenUI 开关只改变已声明的请求路由与 schema 渲染行为；流式内容通过 PatternExtractor 解析，普通文本仍由 TinyRobot 渲染，只有有效 schema-card 进入 GenuiRenderer。认证方式和 prompt 结构必须来自服务合同。

若 GenUI 通过自定义 responseProvider 统一普通请求与 GenUI 请求，则它是唯一请求所有者；不要再向同一个 useLocalChatRuntime 传入 modelProviders。原有 provider 定义应迁入自定义 provider runtime，并显式连接当前模型，不能为消除冲突而删除模型选择能力。完成前检查最终 runtime 调用只保留一个请求所有者，并做不发送消息的本地挂载验证。

3. 业务 WebMCP 与业务 Skill

接入 Next SDK 的浏览器 WebMCP 初始化、TinyRobot adapter 和 src/skills/**/SKILL.md 加载链。adapter 从 document.modelContext 读取并执行真实 descriptor，不维护重复的业务 schema。加载后的业务 Skill instructions 必须通过当前唯一请求所有者进入模型请求；已有自定义 responseProvider 时扩展它，不绕过现有模型与 GenUI 路由创建第二条请求链。

业务方负责在实际页面或业务模块中注册工具，并编写对应业务 Skill；工具名、参数、返回值、副作用和确认规则均以业务声明为准。业务工具若产生会影响后续模型决策的页面状态变化，应在工具合同中说明；返回结果只反馈已经完成的可观察状态。专用工具结果已经足以完成用户目标时，不再用 PageTool 重复搜索或验证。不要根据页面字段、按钮、路由或示例生成业务工具。

工具注册作用域由业务可见性决定：仅在当前页面成立的能力随页面挂载和卸载，真正与页面无关的能力才应用级持久注册。不能为了绕过 TinyRobot 的轮次工具快照而改变业务工具作用域；同一条消息跨路由后继续调用页面工具时，应使用目标版本公开的逐模型请求工具刷新能力。TinyRobot Chat 0.5.2-alpha.15 可使用版本化资产中的动态 toolPlugin，在每次模型请求前读取当前已注册且启用的 descriptor，同时把 adapter runtime 单独连接到 MCP 面板。具体规则见 业务 WebMCP。

Next SDK 必须是目标应用可追踪的直接依赖，并在客户端入口、createApp 和业务页面注册工具之前完成官方 WebMCP 初始化。自定义 adapter 是 MCP 唯一所有者时，不得同时向 useLocalChatRuntime 传入 mcpServers；已有真实 MCP server 不能静默删除，按 Runtime 所有权 合并或停止并报告。

adapter 必须按目标版本真实合同处理异步工具发现、模型可见的 server 命名空间、同一 descriptor 执行、参数序列化、toolchange 刷新和组件卸载清理。toolchange 只代表目录和界面状态已刷新；当前轮次后续模型请求是否重新取工具必须由 runtime 原生能力或动态工具 plugin 保证。命中已验证精确版本时可使用 业务 WebMCP 中的版本化模板；否则把模板作为数据流参考并逐项适配。

4. PageTool

使用目标项目当前 Next SDK 的公开 PageTool API，接入注册、TinyRobot adapter、通用观察流程和动作策略。

基础设施可以实现查询通道，但模型只能观察业务方声明的安全范围；没有声明时不暴露业务页面内容。页面目标、稳定标识、可操作动作和排除区域由业务方声明；未声明时不要自行给菜单、按钮或区块添加可操作语义。若 SDK 本身没有动作授权机制，在 adapter 执行前校验动作与目标。提交、删除、发布、支付等副作用应使用带业务 ID、权限和确认合同的专用 WebMCP 工具，不通过通用 PageTool 或提示词放行。

adapter 既要按业务策略收窄模型可见的 PageTool action schema，也要在执行前校验最新观察、ref 和稳定 target；工具名不能作为 PageTool action。目标版本支持时启用工具调用后的遮罩清理；除非用户明确要求隐藏操作光标，否则使用仅在操作期间展示的 actionOnly，不要改成 never。命中已验证精确版本时可适配 assets/webmcp-next-0.4.11-tinyrobot-0.5.2-alpha.15/pagetool/ 中的通用模板，业务 target policy 必须来自目标项目，不能写入通用资产。

一条消息需要 PageTool 导航后继续调用目标页面工具时，将页面就绪条件作为项目配置传给 adapter：PageTool 导航动作执行后等待目标路由所需 descriptor 全部注册，再返回工具结果；下一次模型请求通过第三阶段接入的动态工具刷新取得新工具。PageTool 保持应用级注册，业务工具继续遵循页面生命周期，两者不能通过迁移作用域来互相替代。

PageTool 只补足业务工具尚未覆盖的页面观察或交互。专用业务工具结果已经足以完成用户目标时，生成的业务 Skill 应要求模型直接回答；只有结果不足、工具报告失败，或用户明确要求额外检查页面时，才继续调用 PageTool。

配置与密钥

只在 .env.example 中补充所需变量的空占位。不要读取、输出、删除、覆盖、提交或硬编码真实 .env 和密钥。任何 VITE_* 值都会进入浏览器产物；需要保密的认证应由服务端或同源代理处理。

缺少模型 Key、GenUI URL、Prompt ID 或其他运行时配置时，保持相关功能不可启用，继续完成不依赖真实服务的代码接入，并在结果中列出待补配置。

验证与报告

默认验证范围：

• 依赖、lockfile、公开导出和真实挂载链；
• 按项目已有测试入口或临时检查，验证与本阶段有关的解析、请求路由、adapter、Skill 加载和动作策略；
• 项目已有的类型检查与生产构建。

Skill 只规定要验证的生产行为，不向目标项目复制测试模板。为定位或验收临时新增的测试、fixture 和诊断代码在完成前删除；只有目标项目本身需要长期保护的重要回归，才按其测试规范保留。

第二、三阶段修改 runtime 接线后，默认复用已有本地服务，或启动 Agent 自己可清理的开发服务，完成不发送模型消息的挂载检查：

• 第二阶段打开唯一聊天面并检查 GenUI 控件：配置齐全时切换，缺配置时验证禁用态；两种情况都确认没有 runtime 配置异常；
• 第三阶段打开 MCP 面板，确认 server 与业务方已注册工具可见；没有业务声明时只确认初始化和空状态。

不占用或停止用户已有进程；只有 Agent 自己启动的服务才在验证后停止。默认不发送模型消息、不调用远程服务，也不采集截图。

当用户明确要求运行时验证时，只验证其点名范围，并完成真实用户路径：用户输入 → 实际模型或工具调用 → 可观察的聊天、页面或业务结果 → 助手反馈一致。截图按用户指定的分辨率，在首次加载页面前设置视口。

最终报告使用事实描述：修改了哪些文件、哪些检查通过或失败、哪些配置待补、哪些运行时能力未验证以及仍存在的风险。不要用自定义状态码替代这些事实。

范围边界

本 Skill 不内置业务工具、业务页面目标、模型供应商偏好或 Demo 数据。它提供集成通道、通用契约和安全边界；业务能力仍由目标应用定义。