chat-apps-ui-sdk

聊天应用 UI SDK 最佳实践

一份参考指南，介绍如何构建精美、可供审核的应用，并在 ChatGPT 和 Claude 的聊天界面中呈现交互式 UI。截至 2026 年 1 月，这些平台共享同一基础——MCP Apps 标准（@modelcontextprotocol/ext-apps），由 Claude、ChatGPT、VS Code 和 Goose 呈现。OpenAI Apps SDK 是一个超集，增加了 window.openai 桥接；而 MCP-UI（@mcp-ui/server / @mcp-ui/client）则是社区实现。本技能包含 8 个类别中的 46 条规则，并按影响程度排序，让最具杠杆效应的决策优先呈现。

思维模型：应用首先是一个 MCP 工具，其次才是 UI。模型调用工具；工具返回数据以及指向 UI 资源的链接；宿主在沙盒 iframe 中呈现该资源；iframe 通过定义好的桥接进行回传。链路前段的错误会导致无法呈现任何内容；后段的错误则会让内容呈现异常、不安全或不够完善。

适用时机

在以下情况下参考这些指南：

• 为聊天应用设计 MCP 工具以及 structuredContent / content / _meta 契约
• 将工具连接到组件（_meta.ui.resourceUri、text/html;profile=mcp-app MIME 类型、ui:// 方案）
• 编写 iframe 组件及其桥接（window.openai、ui/notifications/*、MCP-UI onUIAction）
• 选择显示模式、组件状态、主题和响应式布局
• 强化聊天应用安全性（CSP、沙盒、密钥、OAuth），或准备提交到目录
• 审查或重构现有的 ChatGPT 应用 / Claude 应用 / MCP-UI 代码

按优先级划分的规则类别

优先级	类别	影响	前缀
1	MCP 工具与发现设计	CRITICAL	tool-
2	UI 资源连接与模板	CRITICAL	wire-
3	宿主与组件之间的数据桥接	HIGH	bridge-
4	显示模式与响应式布局	HIGH	display-
5	状态与模型上下文	HIGH	state-
6	安全与数据边界	HIGH	sec-
7	视觉设计与 UX 润色	MEDIUM-HIGH	design-
8	分发与跨宿主可移植性	MEDIUM	dist-

快速参考

1. MCP 工具与发现设计（CRITICAL）

• tool-structured-content-contract - 在 structuredContent、content 和 _meta 之间拆分输出
• tool-specific-verb-names - 使用具体的动作动词命名工具
• tool-output-schema-validation - 为 structuredContent 声明输出架构
• tool-safety-annotations - 准确设置 readOnlyHint 和 destructiveHint
• tool-minimal-scoped-inputs - 仅请求最少且与任务相关的工具输入
• tool-feed-widget-in-response - 在一次响应中返回组件所需的全部内容
• tool-honest-descriptions - 撰写诚实的工具描述和状态文本

2. UI 资源连接与模板（CRITICAL）

• wire-resource-uri-link - 使用 resourceUri 将每个工具连接到其 UI
• wire-mcp-app-mimetype - 使用 mcp-app MIME 类型提供 UI 资源
• wire-ui-scheme-and-handler - 将 ui:// URI 与已注册资源相匹配
• wire-version-uri-cache-key - 将资源 URI 版本化，以用作缓存键
• wire-inline-self-contained-bundle - 将组件包内联到资源中
• wire-set-ui-domain - 为组件设置唯一的 ui.domain

3. 宿主–组件数据桥接（高）

• bridge-render-from-notifications - 根据工具输出渲染，而不是在首次绘制时渲染
• bridge-call-tools-app-visibility - 调用工具前，先将工具提供给应用
• bridge-followup-vs-silent-call - 选择后续消息或静默工具调用
• bridge-validate-postmessage-origin - 在宿主中验证 postMessage 来源
• bridge-handle-all-mcpui-actions - 处理每一种 MCP-UI onUIAction 类型
• bridge-use-host-apis - 使用宿主桥接 API，而不是重新实现

4. 显示模式与响应式布局（高）

• display-pick-the-right-mode - 选择适合任务的显示模式
• display-request-mode-with-fallback - 请求全屏，但先以内嵌方式渲染
• display-report-intrinsic-height - 报告固有高度并遵循 maxHeight
• display-avoid-nested-scroll - 避免在内嵌卡片中嵌套滚动
• display-respect-theme - 遵循宿主主题和配色方案
• display-responsive-breakpoints - 在小屏幕上灵活调整布局

5. 状态与模型上下文（高）

• state-separate-three-stores - 分离组件、服务端和模型状态
• state-persist-widget-state - 通过 setWidgetState 持久化 UI 状态
• state-no-secrets-in-state - 不要将机密信息和个人身份信息放入组件状态
• state-update-model-context - 将用户决策推送到模型上下文
• state-keep-state-small - 保持组件状态精简且可序列化

6. 安全与数据边界（高）

• sec-declare-csp-allowlist - 为组件声明 CSP 许可列表
• sec-avoid-frame-domains - 避免在组件中使用嵌套框架域名
• sec-no-secrets-in-payloads - 绝不要在包或有效负载中嵌入机密信息
• sec-enforce-server-side-auth - 在服务端强制执行授权
• sec-signal-oauth-challenge - 使用 www-authenticate 挑战指示身份验证
• sec-minimize-restricted-data - 尽量减少并避免输入受限数据

7. 视觉设计与 UX 润色（中高）

• design-inherit-native-typography - 沿用原生字体并限制字号
• design-restrain-brand-color - 品牌色仅用于点缀
• design-render-loading-empty-error - 渲染加载、空内容和错误状态
• design-meet-wcag-contrast - 满足 WCAG AA 对比度要求并提供替代文本
• design-limit-actions-hierarchy - 限制操作数量并保持清晰的层级
• design-respect-reduced-motion - 遵循减少动态效果偏好

8. 分发与跨宿主可移植性（中等）

• dist-build-on-mcp-apps-standard - 基于共享的 MCP Apps 标准构建
• dist-degrade-without-ui - UI 不受支持时返回文本备用内容
• dist-provide-submission-metadata - 提供准确的提交元数据
• dist-feature-detect-host-apis - 使用前检测宿主功能

使用方法

阅读各个参考文件，了解完整说明以及错误与正确的代码示例。从顶部开始——类别 1（tool-）和类别 2（wire-）决定内容是否能够渲染，因此应先解决这两类问题，再处理显示或设计。

• 章节定义 - 类别结构和影响级别
• 规则模板 - 用于添加新规则的模板
• AGENTS.md - 汇总所有规则的目录

参考文件

文件	描述
references/_sections.md	类别定义和影响级别排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考 URL

相关技能

• build-mcp-server — 用于设计 MCP 服务结构（部署模型、工具模式）的入口，本技能的 UI 规则基于此构建。