实践说明OpenTiny 是面向企业级场景的前端 AI 应用一体化开发平台。包括AI对话组件、生成式UI、WebMCP SDK等面向AI智能化场景的项目可以帮助企业项目搭建业务场景的智能助手增强大模型显示与交互效果让用户使用自然语言即可帮助完成页面操作。受益点通过本次实操开发者可以了解Web场景便捷集成MCP工具实现精准AI操作使用GenUI SDK丰富AI可视化交互方式。体验点通过码道结合OpenTiny智能化Skill集成Next SDK,使用标准WebMCP协议与Skill能力让AI扩展更多能力实现自然语言智能操作。体验生成式UI通过丰富的UI界面进行AI交互。本手册将通过四步实操为现有 Vue 3 Vite 业务应用添加 TinyRobot Chat、 GenUI SDK、业务 WebMCP 与 WebSkills以及 PageTool。实践效果如下https://www.bilibili.com/video/BV1dYh36MEhe/?spm_id_from333.1387.upload.video_card.click本手册将通过四步实操为现有 Vue 3 Vite 业务应用添加 TinyRobot Chat、GenUI SDK、业务 WebMCP 与 WebSkills以及 PageTool。环境准备码道 Agent 开发工具。安装opentiny-next-app-integrationSkill安装命令npx skills add opentiny/agent-skills --skill opentiny-next-app-integrationNode.js 与 pnpm。本手册使用codelabs-demo项目 作为示例 Demo。codelabs-demo是一个基于 OpenTiny Vue 的电商管理后台系统主要提供概览大盘展示销售额、库存量和待处理价保等业务指标库存、订单和价保管理支持新增入库、订单搜索与状态筛选、价保申请与审批等图例电商管理系统-概览大盘图例电商管理系统-库存管理在 Windows、Linux 或 macOS 终端中执行以下命令获取并启动示例项目npx--yesdegit opentiny/community-resources/events/hc-2026/codelabs-demo codelabs-democdcodelabs-demopnpminstallpnpmdev完成本手册的四步实操后开发者可以在codelabs-demo中打开 TinyRobot 对话框选择已配置的模型并进行对话启用 GenUI SDK让模型返回结构化、可交互的界面使用自然语言按订单号、客户或状态查询订单并查看订单详情让 AI 导航到订单管理页面完成的页面查询。Step 1添加 TinyRobot Chat发送如下指令给 Agent/opentiny-next-app-integration 为当前项目添加 TinyRobot Chat。Agent 完成代码接入后根据项目中的.env.example在本地.env中填写准备使用的模型 Key例如VITE_DEEPSEEK_API_KEY你的 DeepSeek API Key # 或 VITE_ALIYUN_DASHSCOPE_KEY你的 Aliyun DashScope API Key如果还没有模型 Key可以参考 DeepSeek API Key 获取指引 或 Aliyun DashScope API Key 获取指引 完成申请。配置完成后你能看到业务页面中出现 TinyRobot 对话入口。打开对话框后可以选择已配置的模型发送消息并能接收模型回复。Step 2集成 GenUI SDK集成 TinyRobotChat 后发送/opentiny-next-app-integration 在当前 TinyRobot Chat 中集成 GenUI SDK。Agent 完成后在本地.env中填写 GenUI SDK 服务地址和 Prompt ID# 下面是 TinyRobot 产品态的 VITE_GENUI_URL 和 VITE_GENUI_PROMPT_ID VITE_GENUI_URLhttps://chat.bytedev.site/api/v1/ai/prompt/chat/completions VITE_GENUI_PROMPT_IDf6a112c8ac8160211886e5eeffcfd037完成后你能看到 Sender 底部工具多出了 GenUI SDK 功能按钮。可以发送提示词让AI生成可交互的UI回复。下图示例的提示词我想定制一个今天运动的清单请给我一个交互界面用开关Switch让我选择‘是否去健身房’。用单选框Radio让我选择‘跑步、游泳、瑜伽’中的一项。用一个滑动条Slider让我选择今天预计运动的分钟数范围 0 到 120 分钟。Step 3接入 WebMCP 与 WebSkills 基础设施发送如下指令给 Agent/opentiny-next-app-integration 为当前项目接入第三步 WebMCP 与 WebSkills 基础设施。Agent 完成后会把页面通过document.modelContext注册的工具连接到 TinyRobot并加载src/skills/**/SKILL.md中的业务说明。基础设施接入完成后开发者需要补充两部分代码注册MCP工具在对应 Vue 页面挂载时通过document.modelContext.registerTool()注册当前页面提供的能力页面卸载时使用AbortController注销避免模型继续看到已经不可用的工具。编写业务 Skill在src/skills/业务名/SKILL.md中说明这些工具何时使用、如何传参以及怎样处理结果。注册MCP工具工具名称、参数和执行逻辑由开发者根据真实业务定义。Agent 不根据页面字段、按钮或示例工程自行生成业务工具。注册工具时需要提供name稳定且唯一的工具名description工具用途、适用条件和限制inputSchema参数名称、类型、必填项和枚举值execute调用现有业务状态或服务并返回真实结果。比如codelabs-demo在src/views/orders/index.vue中注册如下两个工具工具输入作用order_query可选订单号、客户姓名和订单状态查询订单列表并同步页面筛选条件order_detail必填完整订单号查询详情并将页面列表定位到该订单下面示例代码也可以在 registerTool.ts 查看import{nextTick,onMounted,onUnmounted}fromvuetypeOrderQueryInput{orderId?:stringcustomerName?:stringstatus?:OrderItem[status]}constabortControllernewAbortController()onMounted((){constmodelContext(documentasany).modelContextif(!modelContext?.registerTool)returnmodelContext.registerTool({name:order_query,description:查询订单列表可按订单号、客户姓名或状态筛选不传参数时返回全部订单。,inputSchema:{type:object,properties:{orderId:{type:string,description:订单号如 ORD-5X9A2B,},customerName:{type:string,description:客户姓名支持模糊匹配,},status:{type:string,enum:[Pending,Shipped,Delivered,Refunded,Cancelled],description:订单状态,},},},execute:async({orderId,customerName,status}:OrderQueryInput){constnormalizedOrderIdorderId?.trim().toLowerCase()constnormalizedCustomerNamecustomerName?.trim().toLowerCase()constresultorderList.value.filter((order){constmatchesOrderId!normalizedOrderId||order.id.toLowerCase().includes(normalizedOrderId)constmatchesCustomerName!normalizedCustomerName||order.customerName.toLowerCase().includes(normalizedCustomerName)constmatchesStatus!status||order.statusstatusreturnmatchesOrderIdmatchesCustomerNamematchesStatus})filterStatus.valuestatus??searchText.valueorderId?.trim()||customerName?.trim()||consttextresult.length0?未找到符合条件的订单。:找到${result.length}条订单\n${result.map((order)-${order.id}${order.customerName}${order.productName}¥${order.totalAmount.toLocaleString()}${statusLabelMap[order.status]},).join(\n)}return{content:[{type:text,text}],}},},{signal:abortController.signal},)modelContext.registerTool({name:order_detail,description:根据完整订单号查询订单详情并同步筛选页面订单列表。,inputSchema:{type:object,properties:{orderId:{type:string,description:完整订单号如 ORD-5X9A2B,},},required:[orderId],},execute:async({orderId}:{orderId:string}){constnormalizedOrderIdorderId.trim().toUpperCase()constorderorderList.value.find((item)item.id.toUpperCase()normalizedOrderId)filterStatus.valuesearchText.valueorder?.id??orderId.trim()awaitnextTick()if(!order){return{content:[{type:text,text:未找到订单号为${orderId}的订单。}],}}consttext订单详情${order.id} - 客户${order.customerName}- 联系电话${order.customerPhone}- 商品${order.productName}- 数量${order.quantity}- 单价¥${order.unitPrice.toLocaleString()}- 总金额¥${order.totalAmount.toLocaleString()}- 支付方式${order.paymentMethod}- 状态${statusLabelMap[order.status]}- 下单时间${order.createdAt}${order.shippedAt?\n- 发货时间${order.shippedAt}:}页面定位订单列表已筛选到${order.id}。return{content:[{type:text,text}],}},},{signal:abortController.signal},)})onUnmounted((){abortController.abort()})编写业务 Skill可执行工具定义了 AI 能做什么业务 Skill 则指导 AI 正确使用这些工具。业务 Skill 应说明哪些用户意图适合使用当前业务能力当前有哪些可用工具如何把用户表达转换为工具参数什么情况下选择哪个工具如何根据工具的真实返回结果回答用户以及如何处理参数不足、未找到或执行失败。比如codelabs-demo新增src/skills/orders/SKILL.md下面示例代码也可以在 webmcp-skill.md 查看--- name: orders description: 订单查询技能。当用户需要查询订单列表、订单状态、客户订单或指定订单详情时使用。 --- # 订单查询 你负责协助用户查询订单信息。 ## 适用范围 这些工具只在订单管理页面挂载后可用。 如果订单工具当前不可用提示用户先进入订单管理页面不要虚构查询结果。 ## 可用工具 - order_query查询订单列表支持按订单号、客户姓名和订单状态筛选。 - order_detail根据完整订单号查询详情并同步筛选页面订单列表。 ## 参数规则 ### orderId 订单号格式类似 ORD-5X9A2B。 - 用户提供完整订单号并要求查看详情时调用 order_detail。 - 用户只想在列表中搜索订单时调用 order_query。 ### customerName 支持按客户姓名模糊查询使用 order_query。 ### status 只允许使用以下值 - Pending待发货 - Shipped已发货 - Delivered已签收 - Refunded已退款 - Cancelled已取消 ## 工具选择 1. 查询指定订单详情调用 order_detail。 2. 按客户、状态或多个条件筛选调用 order_query。 3. 用户没有提供足够的必填参数时先向用户询问。 4. 工具返回未找到时如实告诉用户不得补造订单。 5. 最终回答只能使用工具实际返回的信息。 6. order_detail 已返回页面筛选结果时无需使用 PageTool 重复确认其他未完成任务不受此限制。如果上述示例代码不满足你的业务需求可以使用 Agent 生成业务代码可用提示词如下/opentiny-next-app-integration 根据以下已确认的业务定义为 codelabs-demo 补充 Step 3 订单工具和 Skill - 在 src/views/orders/index.vue 注册 order_query 和 order_detail。 - order_query 支持按订单号、客户姓名和订单状态查询并同步页面筛选条件。 - order_detail 根据完整订单号查询订单详情同步将页面列表筛选到该订单工具结果只反馈已经完成的详情查询和页面筛选。 - 两个工具复用页面现有的 orderList不创建模拟数据。 - 工具只在订单管理页面打开期间注册并可调用。 - 在 src/skills/orders/SKILL.md 中说明工具用途、参数规则、选择条件和失败处理专用工具已返回页面定位结果时无需使用 PageTool 重复确认其他未完成任务不受此限制。 实现模板 - 在 onMounted 中调用 document.modelContext.registerTool({ name, description, inputSchema, execute }, { signal }) 注册工具。 - 两个工具共用一个 AbortController.signal并在 onUnmounted 中调用 abort() 注销。 - SKILL.md 使用包含 name 和 description 的 YAML frontmatter并包含“适用范围”“可用工具”“参数规则”和“工具选择”。 只实现上述能力不新增或推测其他业务工具。完成后检查代码接入不发送模型消息。使用 WebMCP 获取订单数据进入订单管理页面后Chat 应用中查询订单时AI 会根据 tools 或 Skill 指令如果AI使用了Skill的话 选择order_query或order_detail。AI 回复内容和订单页面会使用同一份业务数据。进入订单管理页面后在 Chat 应用中输入以下提示词验证 AI 调用order_detail查询真实订单数据请查询订单 ORD-5X9A2B 的详细信息。Step 4接入 PageTool 页面查询与导航发送如下指令给 Agent/opentiny-next-app-integration 为当前项目接入 PageTool。Agent 完成后会接入项目当前版本提供的 PageTool 和 TinyRobot adapter。PageTool 接入完成后开发者需要补充两部分代码配置页面访问范围在真实业务页面中标记允许 PageTool 查询、定位或导航的元素并按需排除不允许访问的区域。编写 PageTool Skill在src/skills/业务名/SKILL.md中说明允许处理的用户意图、页面目标、操作流程和安全边界。补充下面的页面目标时使用同一份 action/target 声明配置 adapter policy并与实际交互元素上的data-page-tool-*保持一致。页面属性提供稳定语义adapter policy 负责执行前授权两者不能互相替代。配置页面访问范围标记可访问元素时使用data-page-tool-*属性ahref/hellodata-page-tool-id稳定标识data-page-tool-actionnavigationaria-label名称/adata-page-tool-id页面目标的稳定且唯一的业务标识data-page-tool-action允许的动作类别例如query或navigationaria-label供 PageTool 和辅助技术识别的可访问名称。比如给codelabs-demo的订单页面增加以下能力页面目标允许的动作作用orders-pagequery查询订单管理页面结构orders-listnavigation滚动定位到订单列表orders-navigationnavigation从左侧导航进入订单管理页面给页面元素添加 PageTool 属性在src/views/orders/index.vue中将divclassorders-view/div修改为divclassorders-viewdata-page-tool-idorders-pagedata-page-tool-actionqueryaria-label订单管理页面/div允许 PageTool 滚动定位到订单列表将divclasstable-container/div修改为divclasstable-containerdata-page-tool-idorders-listdata-page-tool-actionnavigationaria-label订单列表/div允许 PageTool 点击左侧“订单管理”进入订单页面在src/App.vue中将router-linkto/ordersclassnav-itemactive-classactive/router-link修改为router-linkto/ordersclassnav-itemactive-classactivedata-page-tool-idorders-navigationdata-page-tool-actionnavigationaria-label进入订单管理/router-link配置 PageTool 黑名单如果业务页面中不允许 PageTool 查询或操作的区域可以修改 PageTool 配置。TinyRobot 对话框已经在 PageTool 配置中排除。具体路径以项目实际代码为准可以搜索registerPageAgentTool或setPageAgentToolConfig定位。找到a11yConfig.blacklist后在保留已有配置的基础上追加业务区域选择器例如registerPageAgentTool({// 保留项目已有的其他 PageTool 配置a11yConfig:{blacklist:[.chat-add-window,.chat-add-launcher,[data-page-tool-excludetrue],不允许访问的业务区域选择器,],// 保留项目已有的 whitelist 和 exposedAttributes},})编写 PageTool SkillPageTool Skill 应说明哪些用户意图可以使用 PageTool可以操作哪些页面目标以及允许的动作什么情况下应优先调用 Step 3 注册的专用业务工具哪些操作必须禁止。Skill 中的目标和动作必须与页面代码一致。提交、删除、发布、支付等操作必须使用带权限校验和确认机制的专用工具不能通过 PageTool 或 Skill 开放。比如codelabs-demo项目在src/skills/orders/SKILL.md末尾加入下面示例代码也可以在 pagetool-skill.md 查看## PageTool 页面目标 - orders-page订单管理页面允许动作query。 - orders-list订单列表允许动作navigation仅用于滚动定位。 - orders-navigation左侧“订单管理”导航允许动作navigation仅用于进入订单页面。 ## PageTool 与业务工具边界 - PageTool 只用于上述页面目标的查询、滚动和导航。 - 查询订单数据并在页面中定位订单时使用 order_query 或 order_detail不使用 PageTool 读取订单数据或操作搜索框。 - order_detail 已返回页面筛选结果时无需使用 PageTool 重复确认其他未完成任务不受此限制。 ## PageTool 禁止操作 - 不操作未在“PageTool 页面目标”中声明的元素。 - 不使用 fill、select 或 executeJavascript。 - 不使用 PageTool 提交、删除、发布、支付或执行其他副作用。如果上述示例代码不满足你的业务需求可以使用 Agent 生成业务代码可用提示词如下/opentiny-next-app-integration 根据以下已确认的页面访问范围为 codelabs-demo 补充 Step 4 PageTool 业务代码 - 在 src/views/orders/index.vue 添加 orders-page允许 query。 - 在订单列表添加 orders-list允许 navigation仅用于滚动定位。 - 在 src/App.vue 的“订单管理”导航添加 orders-navigation允许 navigation。 - 使用同一份 action/target 声明配置 adapter 的 PageTool policy并与页面上的>使用 PageTool 导航页面AI 可以根据一条用户消息通过orders-navigation进入订单管理页面查询订单详情并在页面中定位该订单。对单个订单查询预期最短调用链为PageTool 观察当前页面 → PageTool 点击订单导航 →order_detail查询并定位 → AI 回复无需使用 PageTool 重复确认。在非订单页面打开 Chat 应用并输入以下业务提示词来验证 AI 自动导航能力请查询订单 ORD-5X9A2B 的详细信息并在页面中定位到这条订单。page-tool 自动导航到订单管理页面然后筛选出订单输出订单详情
