设计 Component

规划和设计用户可以交互的 UI component。

为什么 Component 很重要

UI component 是连接器中人类可见的那一半。它们让用户可以 inline 查看或编辑数据,在需要时切换到全屏,并在键入的提示词和 UI 操作之间保持上下文同步。尽早规划它们可以确保你的 MCP 服务器从第一天起就返回正确的结构化数据和 component 元数据。

明确用户交互

对于每个用例,决定用户需要看到和操作什么:

• 查看器与编辑器 – component 是只读的(图表、仪表板)还是应该支持编辑和回写(表单、看板)?
• 单次与多轮 – 用户会在一次调用中完成任务,还是应该在迭代时跨轮次持久化状态?
• Inline 与全屏 – 某些任务在默认 inline 卡片中很舒适,而其他任务则受益于全屏或画中画模式。在实施之前勾勒这些状态。

写下你需要的字段、功能和空状态,以便你可以与设计合作伙伴和审阅者验证它们。

映射数据需求

Component 应该在工具响应中接收它们所需的一切。规划时:

• 结构化内容 – 定义 component 将解析的 JSON 负载。
• 初始 component 状态 – 使用 window.openai.toolOutput 作为初始渲染数据。在调用 callTool 的后续跟进中,使用 callTool 的返回值。要缓存状态以供重新渲染,可以使用 window.openai.setWidgetState。
• 认证上下文 – 注意 component 是应该显示已链接账户信息,还是模型必须首先提示用户连接。

通过 MCP 响应提供这些数据比稍后添加临时 API 更简单。

设计响应式布局

Component 在桌面和移动设备上的 iframe 内运行。规划:

• 自适应断点 – 设置最大宽度并设计在小屏幕上优雅折叠的布局。
• 可访问的颜色和动画 – 遵守系统深色模式(匹配颜色方案)并为键盘导航提供焦点状态。
• 启动器转换 – 如果用户从启动器打开你的 component 或扩展到全屏,请确保导航元素保持可见。

提前记录 CSS 变量、字体堆栈和图标,以便它们在各个 component 之间保持一致。

定义状态契约

因为 component 和聊天界面共享对话状态,所以要明确说明什么存储在哪里:

• Component 状态 – 使用 window.openai.setWidgetState API 来持久化主机应该记住的状态(选定的记录、滚动位置、暂存的表单数据)。
• 服务器状态 – 将权威数据存储在你的后端或内置存储层中。决定如何在后续工具调用后将服务器更改合并回 component 状态。
• 模型消息 – 考虑 component 应该通过 sendFollowupTurn 发送回哪些人类可读的更新,以便记录保持有意义。

尽早捕获此状态图可以防止稍后难以调试的同步问题。

规划遥测和调试钩子

在没有仪器的情况下,inline 体验最难调试。提前决定你将如何:

• 为 component 加载、按钮点击和验证错误发出分析事件。
• 将工具调用 ID 与 component 遥测一起记录,以便你可以端到端跟踪问题。
• 当 component 加载失败时提供后备(例如,显示结构化 JSON 并提示用户重试)。

一旦这些计划就位,你就可以继续进行构建自定义 UX 中的实施细节了。