chatgpt-apps

ChatGPT Apps

概述

采用文档优先、示例优先的工作流搭建 ChatGPT Apps SDK 实现，然后生成符合当前 Apps SDK 和 MCP Apps 桥接模式的代码。

使用此技能生成：

• 主要应用类型分类和仓库结构决策
• 工具规划（名称、架构、注解、输出）
• 上游起点建议（官方示例、ext-apps 示例或本地备用脚手架）
• MCP 服务脚手架（资源注册、工具处理程序、元数据）
• 小组件脚手架（优先采用 MCP Apps 桥接，其次采用 window.openai 兼容性/扩展）
• 可复用的 Node + @modelcontextprotocol/ext-apps 入门脚手架，用于低依赖备用方案
• 针对最低可用仓库契约的验证报告
• 本地开发和连接器设置步骤
• 应用功能的简短利益相关者摘要（按需提供）

强制执行文档优先工作流

构建或修改 ChatGPT Apps SDK 应用时，务必先使用 $openai-docs。

1. 调用 $openai-docs（首选），或直接调用 OpenAI 文档 MCP 服务。
2. 在编写代码前获取当前 Apps SDK 文档，尤其是以下基准页面：
   • apps-sdk/build/mcp-server
   • apps-sdk/build/chatgpt-ui
   • apps-sdk/build/examples
   • apps-sdk/plan/tools
   • apps-sdk/reference
3. 搭建新应用或生成第一版实现时，获取 apps-sdk/quickstart，并在从头设计脚手架前检查官方示例仓库/页面。
4. 任务涉及 ChatGPT 本地测试、托管或公开发布时，获取部署/提交文档：
   • apps-sdk/deploy
   • apps-sdk/deploy/submission
   • apps-sdk/app-submission-guidelines
5. 解释设计选择或生成的脚手架时，引用所用文档的 URL。
6. 如当前文档指南与较旧的仓库模式不同，优先遵循当前文档指南，并明确指出兼容性别名。
7. 如果文档搜索超时或结果不佳，直接按 URL 获取规范的 Apps SDK 页面并继续；不要让搜索失败阻碍脚手架搭建。

如果 $openai-docs 不可用，请使用：

• mcp__openaiDeveloperDocs__search_openai_docs
• mcp__openaiDeveloperDocs__fetch_openai_doc

阅读 references/apps-sdk-docs-workflow.md，了解推荐的文档查询方式和精简检查清单。 阅读 references/app-archetypes.md，在选择示例或脚手架前，将请求归类为少数几种受支持的应用类型。 生成或审查仓库时，阅读 references/repo-contract-and-validation.md，确保输出符合稳定的“可运行应用”契约。 如果应用类似连接器、仅处理数据、以同步为导向，或旨在与公司知识或深度研究协同运行，请阅读 references/search-fetch-standard.md。 开始开发新应用，或需要决定是改造上游示例还是使用本地备用脚手架时，请阅读 references/upstream-example-workflow.md。 如果任务需要 ChatGPT 专属的小组件行为，或要翻译使用封装器专属 app.* 辅助函数的仓库示例，请阅读 references/window-openai-patterns.md。

提示词指南

使用提示词明确要求将此技能与 $openai-docs 配合使用，确保生成的脚手架基于最新文档。

推荐的提示词模式：

• Use $chatgpt-apps with $openai-docs to scaffold a ChatGPT app for <use case> with a <TS/Python> MCP server and <React/vanilla> widget.
• Use $chatgpt-apps with $openai-docs to adapt the closest official Apps SDK example into a ChatGPT app for <use case>.
• Use $chatgpt-apps and $openai-docs to refactor this Apps SDK demo into a production-ready structure with tool annotations, CSP, and URI versioning.
• Use $chatgpt-apps with $openai-docs to plan tools first, then generate the MCP server and widget code.

编写代码前，先询问或推断以下信息：

• 用例和主要用户流程
• 工具是只读还是会修改数据
• 目标是演示还是生产环境
• 用于私有／内部用途，还是要提交到公开目录
• 后端语言和 UI 技术栈
• 身份验证要求
• CSP 允许列表中的外部 API 域名
• 托管目标和本地开发方式
• 组织所有权／验证是否已准备就绪（适用于提交任务）

选择代码前先确定应用类型

选择示例、仓库结构或脚手架之前，先将请求归为一种主要应用类型，并明确说明。

• tool-only
• vanilla-widget
• react-widget
• interactive-decoupled
• submission-ready

除非缺少的信息确实会阻碍工作，否则请推断应用类型。根据应用类型决定：

• 是否需要 UI
• 是否保留拆分为 server/ + web/ 的布局
• 优先选用 OpenAI 官方示例、ext-apps 示例，还是本地备用脚手架
• 哪些验证检查最重要
• 是否默认将 search 和 fetch 作为只读工具集

请阅读 references/app-archetypes.md 中的决策标准。

默认起点选择顺序

对于从零开始开发的应用，请按以下顺序选择起点：

1. OpenAI 官方示例：已有示例与所需技术栈或交互模式相近时，优先选用。
2. 版本匹配的 @modelcontextprotocol/ext-apps 示例：用户需要更底层或更具可移植性的 MCP Apps 基础方案时，优先选用。
3. scripts/scaffold_node_ext_apps.mjs：仅当没有合适的示例、用户需要精简的 Node + vanilla 起步项目，或不希望联网／检索示例时使用。

如果已有合适的上游示例，请勿从头生成大型自定义脚手架。 复制最精简的匹配示例，移除无关演示代码，然后根据当前文档和用户需求进行调整。

构建工作流

0. 确定应用类型

规划工具或选择起点前，先选定一种主要应用类型。

• 优先选定一种主要应用类型，不要混用多种类型。
• 如果请求范围较广，请推断能够满足需求的最精简应用类型。
• 只有在用户要求公开发布、提交到目录或部署为待审核版本时，才升级为 submission-ready。
• 在回复中说明所选应用类型，以便用户在需要时尽早提出修正。

1. 编写代码前规划工具

根据用户意图定义工具范围。

• 每个工具只负责一项任务。
• 编写工具说明时，以“在……情况下使用”这类行为提示开头。
• 让输入明确且便于机器处理（枚举、必填字段、范围）。
• 确定每个工具是纯数据、纯渲染，还是两者兼具。
• 准确设置注解（readOnlyHint、destructiveHint、openWorldHint；如果工具具有幂等性，则添加 idempotentHint）。
• 如果应用类似连接器、仅处理数据、面向同步，或用于公司知识或深度研究，默认使用标准的 search 和 fetch 工具，而不是自行设计自定义的只读替代工具。
• 对于教育或演示应用，优先让每个工具只展示一个概念，以便模型清楚地选择合适的示例。
• 按学习目标对演示工具分组：将数据传入小组件、将小组件操作传回对话或工具、主机／布局环境信号，以及生命周期／流式行为。

当 search 和 fetch 可能适用时，请阅读 references/search-fetch-standard.md。

2. 选择应用架构

选择符合目标的最简单结构。

• 对于快速原型、工作坊或概念验证，使用最简演示模式。
• 对于生产级 UX，使用数据与渲染解耦模式，以免小组件在每次工具调用时都重新渲染。

对于并非简单的应用，优先采用解耦模式：

• 数据工具返回可复用的 structuredContent。
• 渲染工具附加 _meta.ui.resourceUri 和可选的 _meta["openai/outputTemplate"]。
• 渲染工具的说明应注明前置条件（例如，“先调用 search”）。

2a. 适用时从上游示例开始

对于全新开发，如果上游示例与所需应用相近，默认优先使用。

• 对于面向 ChatGPT 的应用、精致的 UI 模式、React 组件、文件上传流程、模态框流程，或与文档示例相似的应用，先查看 OpenAI 官方示例。
• 如果需求更接近原生 MCP Apps 桥接／服务端接线，或匹配版本的包模式比面向 ChatGPT 的精致体验更重要，则使用 @modelcontextprotocol/ext-apps 示例。
• 选择最小的匹配示例，只复制相关文件；不要原样移植整个展示应用。
• 复制后，根据已获取的最新文档核对并调整示例：工具名称／说明、注解、_meta.ui.*、CSP、URI 版本控制以及本地运行说明。
• 用一句话说明你选择了哪个示例以及原因。

请阅读 references/upstream-example-workflow.md，了解示例的选择与改造标准。

2b. 适合低依赖回退方案时使用脚手架脚本

仅当用户想要快速搭建全新的 Node 项目、可接受原生 HTML 小组件，且没有更合适的上游示例时，才使用 scripts/scaffold_node_ext_apps.mjs。

• 只有在获取最新文档后才运行该脚本，随后根据已获取的文档核对生成的文件并进行调整。
• 如果选择脚本而非上游示例，请说明此回退方案为何更适合该需求。
• 存在合适的官方示例、用户已有应用结构、用户需要非 Node 技术栈、用户明确希望优先使用 React，或用户只想要计划／评审而非代码时，不要使用该脚本。
• 该脚本会生成一个最简的 @modelcontextprotocol/ext-apps 服务端和一个默认使用 MCP Apps 桥接的原生 HTML 小组件。
• 生成的小组件通过标准 ui/message 桥接发送后续消息；仅在需要可选主机信号／扩展时才使用 window.openai。
• 运行脚本后，根据最新文档和用户需求修补生成的文件：调整工具名称／说明、注解、资源元数据、URI 版本控制以及 README／运行说明。

3. 搭建 MCP 服务

生成的服务应：

• 注册使用 MCP Apps UI MIME 类型（text/html;profile=mcp-app）或 SDK 常量（使用 @modelcontextprotocol/ext-apps/server 时为 RESOURCE_MIME_TYPE）的小组件资源／模板
• 注册具有清晰名称、架构、标题和描述的工具
• 有意返回 structuredContent（模型 + 小组件）、content（模型叙述）和 _meta（仅供小组件使用的数据）
• 使处理程序具备幂等性，或明确说明其非幂等行为
• 在有助于 ChatGPT 的情况下，包含工具状态字符串（openai/toolInvocation/*）

保持 structuredContent 简洁。将较大或敏感的、仅供小组件使用的数据移至 _meta。

4. 搭建小组件 UI

优先使用 MCP Apps 桥接以确保可移植性，然后在确实能改善用户体验时添加 ChatGPT 专用的 window.openai API。

• 监听 ui/notifications/tool-result（通过 postMessage 传输的 JSON-RPC）
• 从 structuredContent 渲染
• 使用 tools/call 进行由组件发起的工具调用
• 仅在 UI 状态应改变模型所见内容时使用 ui/update-model-context

使用 window.openai 实现兼容性和扩展功能（文件上传、模态框、显示模式等），不要将其作为新应用的唯一集成途径。

API 范围使用准则

• 有些示例会用 app 对象封装桥接（例如 @modelcontextprotocol/ext-apps/react），并提供 app.sendMessage()、app.callServerTool()、app.openLink() 等辅助函数，或宿主 getter 方法。
• 请将这些封装视为实现细节或便捷层，而非默认应教授的规范公共 API。
• 编写面向 ChatGPT 的指南时，优先使用当前文档所述的接口：window.openai.callTool(...)、window.openai.sendFollowUpMessage(...)、window.openai.openExternal(...)、window.openai.requestDisplayMode(...)，以及 window.openai.theme、window.openai.locale、window.openai.displayMode、window.openai.toolInput、window.openai.toolOutput、window.openai.toolResponseMetadata 和 window.openai.widgetState 等直接全局对象。
• 如果引用仓库示例中的封装辅助函数，请将其对应到文档所述的 window.openai 或 MCP Apps 桥接原语，并指出该封装并非规范 API 接口。
• 使用 references/window-openai-patterns.md 查阅封装到规范 API 的映射以及 React 辅助函数提取模式。

5. 添加资源元数据和安全设置

有意为小组件资源／模板设置资源元数据：

• _meta.ui.csp，包含精确的 connectDomains 和 resourceDomains
• _meta.ui.domain，用于适合提交应用的部署
• _meta.ui.prefersBorder（或在需要时使用 OpenAI 兼容别名）
• 可选的 openai/widgetDescription，以减少重复叙述

除非 iframe 嵌入是产品的核心功能，否则不要使用 frameDomains。

5a. 确保满足最低可用仓库约定

在认为工作已完成前，每个生成的仓库都应满足一套小而稳定的约定。

• 仓库结构符合所选的架构类型。
• MCP 服务和工具已接入可访问的 /mcp 端点。
• 工具具有清晰的描述、准确的注解，以及所需的 UI 元数据。
• 类连接器、纯数据、面向同步以及企业知识类应用应在适用时使用标准的 search 和 fetch 工具结构。
• 存在 UI 时，小组件应正确使用 MCP Apps 桥接。
• 仓库包含足够的脚本或命令，供用户在本地运行和检查。
• 回复应明确说明已运行和未运行哪些验证。

阅读 references/repo-contract-and-validation.md，了解详细检查清单和验证流程。

6. 验证本地开发闭环

根据最低可运行仓库契约进行验证，而不只是检查“是否创建了文件”。

• 先运行成本最低的检查：
  • 静态契约审查
  • 可行时进行语法或编译检查
  • 可行时进行本地 /mcp 健康检查
• 然后进行更深入的运行时检查：
  • 在 MCP Inspector 中验证工具描述符和组件渲染
  • 通过 HTTPS 隧道在 ChatGPT 开发者模式下测试应用
  • 测试重试和重复工具调用，确认行为具备幂等性
  • 检查宿主事件和后续工具调用后组件是否更新
• 如果你只交付脚手架且不安装依赖，仍需运行低成本检查，并明确说明哪些检查没有运行。

阅读 references/repo-contract-and-validation.md，了解验证步骤。

7. 在 ChatGPT 中连接并测试（开发者模式）

进行本地开发时，请提供明确的 ChatGPT 设置步骤（而不只是代码或运行命令）。

• 在本地运行 MCP 服务：http://localhost:<port>/mcp
• 使用公共 HTTPS 隧道公开本地服务（例如 ngrok http <port>）
• 从 ChatGPT 连接时，使用隧道提供的 HTTPS URL，并附上 /mcp 路径
• 在 ChatGPT 中，前往 设置 → 应用和连接器 → 高级设置，启用开发者模式
• 在 ChatGPT 应用设置中，为远程 MCP 服务创建新应用，并粘贴公共 MCP URL
• 告知用户，MCP 工具或元数据变更后应刷新应用，以便 ChatGPT 重新加载最新的描述符

注意：部分文档和截图仍使用较旧的“连接器”术语。提供分步说明时，优先使用当前产品用语“应用”，同时注明这两种称呼。

8. 规划生产托管和部署

当用户要求部署或为上线做准备时，请提供 MCP 服务（以及单独托管的组件资源）的托管指南。

• 部署在稳定的公共 HTTPS 终端后（而非隧道），并确保 TLS 可靠
• 保持 /mcp 上的流式传输低延迟
• 在仓库外配置密钥（环境变量／密钥管理器）
• 为工具调用添加日志记录、请求延迟跟踪和错误可见性
• 添加基本可观测性（CPU、内存、请求量）和故障排查路径
• 提交前在 ChatGPT 开发者模式下重新测试托管终端

9. 准备提交并发布（仅限公共应用）

仅当用户计划在公共目录中列出应用时，才包含以下步骤。

• 使用 apps-sdk/deploy/submission 进行提交，并使用 apps-sdk/app-submission-guidelines 了解审核要求
• 将私人／内部应用保留在开发者模式中，而不是提交
• 在开始提交工作前，确认组织验证和 Owner 角色的前置要求
• 确保 MCP 服务使用公共生产终端（不使用 localhost／测试 URL），并配置好符合提交要求的 CSP
• 准备提交材料：应用元数据、徽标／截图、隐私政策 URL、支持联系方式、测试提示词／响应、本地化信息
• 如果需要身份验证，提供适合审核的演示凭据，并端到端测试登录流程
• 在 Platform 控制面板中提交审核，跟踪审核状态，并仅在获批后发布

交互状态指南

如果应用具有长期存在的组件状态、重复交互或由组件发起的工具调用（例如游戏、棋盘、地图、仪表板、编辑器），请阅读 references/interactive-state-sync-patterns.md。

使用该指南选择以下模式：

• 状态快照加单调递增的事件令牌（stateVersion、resetCount 等）
• 支持幂等重试的处理程序
• structuredContent 与 _meta 的划分
• 以 MCP Apps bridge 为首选、并可选兼容 window.openai 的更新流程
• 面向更复杂交互式应用的解耦数据／渲染工具架构

输出要求

使用此技能搭建代码时，除非用户另有要求，否则请按以下顺序输出：

• 对于直接搭建请求，不要止步于计划：先简要说明计划，然后立即创建文件。

1. 选择的主要应用类型及原因
2. 工具计划和架构选择（最小化或解耦）
3. 选择的上游起点（官方示例、ext-apps 示例或本地备用脚手架）及原因
4. 从 $openai-docs 使用的文档页面/URL
5. 要创建或修改的文件树
6. 实现（服务端 + 小组件）
7. 根据最小可运行仓库约定进行的验证
8. 本地运行/测试说明（包括隧道 + ChatGPT Developer Mode 应用设置）
9. 部署/托管指南（如用户要求或有此暗示）
10. 发布就绪检查清单（针对公开发布请求）
11. 风险、缺口和后续改进

参考资料

• references/app-archetypes.md：用于将请求归类为少数几种受支持的应用形态
• references/apps-sdk-docs-workflow.md：用于查询文档、确定页面目标和检查代码生成清单
• references/interactive-state-sync-patterns.md：用于为有状态或交互性很强的小组件应用提供可复用模式
• references/repo-contract-and-validation.md：用于了解最小可运行仓库约定和轻量级验证流程
• references/search-fetch-standard.md：用于了解何时以及如何默认使用标准 search 和 fetch 工具
• references/upstream-example-workflow.md：用于在官方示例、ext-apps 示例和本地备用脚手架之间进行选择
• references/window-openai-patterns.md：用于了解 ChatGPT 专属扩展、封装 API 转换和 React 辅助模式
• scripts/scaffold_node_ext_apps.mjs：用于生成基于 Node 和 @modelcontextprotocol/ext-apps 的最小备用入门脚手架