Skybridge：用React+TypeScript构建AI交互应用的全栈框架

1. 从零到一为什么我们需要 Skybridge如果你最近在捣鼓 ChatGPT 的 Apps SDK 或者 Anthropic 的 MCPModel Context Protocol想给大模型对话里塞点能交互的 UI 组件那你大概率已经体验过那种“原始”的酸爽了。官方 SDK 确实给了你一把锤子但用它来盖房子你得从烧砖开始。没有热重载改个样式就得重启应用类型安全基本靠猜状态管理自己从头搭。开发体验就像在命令行里写网页效率低得让人抓狂。Skybridge 的出现就是为了终结这种“手工作坊”式的开发。它本质上是一个全栈的 TypeScript 框架专门为构建嵌入在 AI 对话中的交互式应用无论是 ChatGPT Apps 还是 MCP Apps而生。它的核心主张很明确用现代前端开发者最熟悉、最高效的方式——React TypeScript 完善的开发工具链——来开发 AI 应用。想象一下你正在开发一个航班查询的 AI 助手。传统方式下你需要在服务端定义一个工具Tool处理查询逻辑然后返回一段 JSON 数据。前端如果那能叫前端的话可能只是一段静态描述。用户无法直观地浏览航班列表、筛选时间、查看价格趋势一切交互都依赖于用户用自然语言反复描述需求。而有了 Skybridge你可以在对话中直接嵌入一个完整的、可交互的航班搜索组件。用户可以看到带图片的航班卡片点击筛选按钮选择心仪的航班所有操作都在对话流中无缝完成。这不仅仅是“展示数据”而是提供了完整的应用体验。Skybridge 的“桥梁”寓意正在于此它一端连接着强大的大模型后端通过 MCP 或 Apps SDK 协议另一端连接着成熟、丰富的现代 Web 交互生态React。它把构建 AI 应用的体验拉回到了构建普通 Web 应用的水平让你能专注于业务逻辑和创新而不是在底层协议和开发工具上挣扎。2. 核心架构与设计哲学拆解2.1 全栈类型安全从后端到前端的无缝衔接Skybridge 最让我惊艳的特性是其“tRPC 风格”的端到端类型安全。在传统的全栈开发中前后端分离最大的痛点之一就是接口契约的维护。后端改了个字段名前端可能直到运行时才会报错。Skybridge 通过巧妙的架构设计几乎彻底消除了这个痛点。它的核心在于skybridge/server和skybridge/web这两个紧密耦合的模块。你在服务端使用McpServer定义工具Tools和部件Widgets时需要明确指定输入输出的 Zod Schema。这个 Schema 不仅仅是运行时校验的规则更是类型信息的源头。// server/tools/flight.ts import { z } from zod; import { McpServer } from skybridge/server; const server new McpServer({ name: flight-demo }); server.registerTool( search_flights, { description: Search for available flights between two cities., }, { // 使用 Zod 定义输入参数的类型 origin: z.string().describe(Departure city airport code, e.g., JFK), destination: z.string().describe(Arrival city airport code, e.g., LAX), date: z.string().describe(Departure date in YYYY-MM-DD format), }, async ({ origin, destination, date }) { // 业务逻辑调用外部 API 获取航班数据 const flights await externalFlightApi.search({ origin, destination, date }); // 返回的结构也会被自动推断类型 return { structuredContent: { flights: flights.map(f ({ id: f.id, airline: f.airline, price: f.price, departureTime: f.departureTime, // ... 其他字段 })) } }; } );关键在于当你在前端组件中导入并调用useToolInfo或类似的 Hook 时TypeScript 能够自动推断出output的完整类型包括structuredContent.flights数组里每个对象的形状。你不需要手动定义任何 DTOData Transfer Object也不需要维护一份独立的类型声明文件。这种体验极其流畅编码时享受完整的自动补全和类型检查将运行时错误提前到了编译时。实操心得为了最大化利用这一特性建议将 Zod Schema 定义得尽可能精确。例如为价格字段使用z.number().positive()为日期字段使用z.string().datetime()。这不仅能提升前端开发的体验也能在服务端第一时间拦截非法数据构建更健壮的应用。2.2 统一的开发模型Widget 即 Tool在 Skybridge 的体系里Widget部件和 Tool工具是一体两面的。一个 Widget 本质上是一个具有可视化界面的 Tool。这个设计非常精妙它统一了 AI 应用的交互范式。对于大模型LLM而言它调用的是一个 Tool。模型根据对话上下文决定何时调用、传递什么参数。对于用户而言他们在对话中看到的是一个交互式的 UI 组件Widget。他们可以通过界面操作如点击、输入来触发新的 Tool Call或者更新现有 Widget 的状态。这种“双向通道”通过>npm create skybridgelatest这个命令行工具会引导你输入项目名并选择模板。我强烈建议初学者从examples/目录下的官方示例开始比如capitals首都探索或ecom-carousel电商轮播。这些模板已经配置好了完整的开发环境、示例组件和构建脚本能让你在几分钟内看到运行效果。初始化后的项目结构非常清晰my-skybridge-app/ ├── src/ │ ├── server/ # 服务端工具和 Widget 定义 │ │ └── index.ts # 主服务入口注册所有 Tools/Widgets │ ├── widgets/ # React 组件Widget UI │ │ └── MyWidget.tsx │ └── client.ts # 客户端入口渲染根组件 ├── skybridge.config.ts # 框架配置文件平台、构建目标等 ├── vite.config.ts # Vite 配置已集成 Skybridge 插件 └── package.json关键文件是skybridge.config.ts。在这里你需要声明你的应用要适配的平台// skybridge.config.ts import { defineConfig } from skybridge; export default defineConfig({ // 可以同时配置多个平台 platforms: [chatgpt, mcp], // 开发服务器配置 devServer: { port: 3000, }, });3.2 开发你的第一个交互式 Widget一个待办清单让我们抛开航班查询那种复杂例子用一个更简单的“待办清单”来演示完整的开发循环。这个 Widget 允许用户查看、添加、标记完成待办事项并且所有操作都会同步给 LLM。第一步定义服务端 Tool/Widget在src/server/todos.ts中我们定义数据模型和核心工具。import { z } from zod; import { McpServer } from skybridge/server; // 1. 定义类型 Schema const TodoSchema z.object({ id: z.string(), title: z.string(), completed: z.boolean(), }); type Todo z.infertypeof TodoSchema; // 模拟一个内存数据库 let todos: Todo[] [ { id: 1, title: Learn Skybridge, completed: true }, { id: 2, title: Build a demo app, completed: false }, ]; // 2. 创建 Server 实例通常全局一个即可 export const server new McpServer({ name: todo-demo }); // 3. 注册一个“获取待办事项”的工具 server.registerTool( get_todos, { description: Get the current list of todo items. }, {}, // 这个工具不需要输入参数 async () { return { structuredContent: { todos, // 将数据放在 structuredContent 中供 Widget 消费 count: todos.length, completed: todos.filter(t t.completed).length, } }; } ); // 4. 注册一个“添加待办事项”的工具 server.registerTool( add_todo, { description: Add a new todo item. }, { title: z.string().min(1).describe(The title of the new todo item), }, async ({ title }) { const newTodo: Todo { id: Date.now().toString(), title, completed: false, }; todos.push(newTodo); // 返回更新后的列表 return { structuredContent: { todos }, // 可以同时返回一个文本摘要供 LLM 阅读 text: Added todo: ${title}. Now you have ${todos.length} items in total. }; } ); // 5. 注册一个“切换待办状态”的工具 server.registerTool( toggle_todo, { description: Toggle the completion status of a todo item. }, { id: z.string().describe(The ID of the todo item to toggle), }, async ({ id }) { const todo todos.find(t t.id id); if (todo) { todo.completed !todo.completed; } return { structuredContent: { todos }, text: Toggled todo ${todo?.title}. It is now ${todo?.completed ? completed : incomplete}. }; } );第二步创建对应的 React Widget在src/widgets/TodoList.tsx中我们构建用户界面。import React, { useState } from react; import { useToolInfo, useToolMutation } from skybridge/web; // 导入从服务端定义自动推断出的类型假设通过代码生成或 monorepo 链接 // 在实际项目中Skybridge 的类型系统会自动连接这里为演示说明 interface Todo { id: string; title: string; completed: boolean; } export function TodoListWidget() { // 1. 使用 useToolInfo 获取初始数据 // 这个 Hook 会自动调用我们在服务端注册的 get_todos 工具 const { data, isLoading, isError } useToolInfo(get_todos); // 2. 使用 useToolMutation 定义修改数据的操作 const addTodoMutation useToolMutation(add_todo); const toggleTodoMutation useToolMutation(toggle_todo); const [newTitle, setNewTitle] useState(); const handleSubmit async (e: React.FormEvent) { e.preventDefault(); if (!newTitle.trim()) return; // 触发服务端的 add_todo 工具调用 await addTodoMutation.mutateAsync({ title: newTitle }); setNewTitle(); // 清空输入框 // 注意mutateAsync 成功后useToolInfo 会自动重新获取数据更新 UI }; const handleToggle async (id: string) { await toggleTodoMutation.mutateAsync({ id }); }; if (isLoading) return divLoading todos.../div; if (isError) return divFailed to load todos./div; const { todos [], completedCount 0 } data?.structuredContent || {}; return ( div>import { server } from ./todos; import { TodoListWidget } from ../widgets/TodoList; // 将 React 组件注册为一个 Widget并关联到 get_todos 工具 server.registerWidget( todo_list, // Widget 名称 {}, // Widget 配置 { // 关联的工具名称当 LLM 决定调用此工具时会渲染此 Widget toolName: get_todos, }, // 这是一个异步渲染函数可以在这里进行服务端数据获取或处理 // 对于简单的场景可以直接返回组件 async () { // 这里可以执行一些服务端逻辑比如从数据库获取用户特定的待办事项 // 返回的 props 会传递给 Widget 组件 return { component: TodoListWidget, props: {}, // 可以传递初始 props }; } ); // 导出处理请求的函数供 Vite 开发服务器或生产服务器使用 export default server;现在运行npm run dev。Skybridge 的 Vite 插件会启动一个开发服务器并提供一个本地调试界面。你可以在这个界面中模拟 LLM 调用get_todos工具并立即看到TodoListWidget被渲染出来并且可以进行完整的交互。热重载HMR功能让你在修改组件或服务端代码时页面能即时更新开发体验与普通 React 应用无异。3.3 状态管理进阶React Query 风格 Hook 的妙用Skybridge 从 React Query 中汲取了灵感提供了useToolInfo和useToolMutation等 Hook。这不仅仅是 API 设计上的借鉴更是将服务端状态管理的成熟模式引入了 AI 应用开发。useToolInfo(get_todos): 类似于 React Query 的useQuery。它负责获取数据并自动管理isLoading,isError,data等状态。它还会在组件挂载、窗口重新聚焦时自动重新获取数据可配置保证了数据的时效性。useToolMutation(add_todo): 类似于useMutation。它用于执行创建、更新、删除等操作提供了mutateAsync,isPending,isError等状态方便在 UI 中显示加载或错误提示。这种模式将服务端状态和 UI 状态清晰地分离开。你的 Widget 组件变得非常“纯净”只关心如何根据状态渲染 UI 和响应用户交互复杂的缓存、重试、竞态处理等都由框架层处理。实操心得充分利用useToolInfo的staleTime和cacheTime配置如果框架暴露了这些选项或查看文档。对于实时性要求不高的数据如商品分类可以设置较长的staleTime以减少不必要的网络请求。对于频繁变动的数据如股票价格则应将其设置为 0 或很短的时间。4. 高级特性与生产实践指南4.1 处理复杂状态与 Widget 间通信当你的应用包含多个相互关联的 Widget 时例如一个筛选器 Widget 和一个结果列表 Widget状态管理就需要更细致的考虑。Skybridge 本身不强制你使用特定的状态管理库你可以自由选择 Zustand、Jotai 甚至 React Context。然而更符合 Skybridge 哲学的方式是利用LLM 作为状态协调中心。每个 Widget 都通过>// 伪代码示例在工具处理函数中获取用户信息 server.registerTool(get_my_profile, {}, {}, async (_, context) { // 假设认证中间件已将用户信息注入 context const userId context.user?.id; if (!userId) { throw new Error(Unauthorized); } const profile await db.user.findUnique({ where: { id: userId } }); return { structuredContent: { profile } }; });4.3 性能优化与构建部署开发体验很棒那生产环境呢Skybridge 的 Vite 插件同样为生产构建做了优化。代码分割Vite 默认支持基于动态 import 的代码分割。确保你的 Widget 如果不是立即必需的可以使用React.lazy进行懒加载这能显著降低初始加载体积。Tree Shaking得益于 ES 模块和 Vite最终打包的产物会自动剔除未使用的代码。确保你的skybridge/server导入是精确的避免引入整个庞大的库。构建配置在vite.config.ts中你可以像优化任何 Vite 项目一样配置压缩、资源处理等。Skybridge 插件会在此基础上生成针对目标平台ChatGPT/MCP的特定入口文件和清单manifest。部署时你需要将构建出的静态文件通常位于dist/目录托管到一个可靠的 CDN 上。同时你的服务端代码即McpServer实例需要作为一个独立的服务部署这个服务负责处理来自 AI 平台的实际 Tool Call。Skybridge 的架构天然支持前后端分离部署。4.4 调试与监控开发过程中的调试Skybridge 提供了本地 DevTools可以模拟 LLM 的调用、查看>