构建 ChatGPT Apps SDK 应用（MCP…

当你需要用 MCP 服务器加小组件 UI 搭建、重构或排查 ChatGPT Apps SDK 应用时，按文档优先、示例优先的方式生成符合当前规范的代码。

适用场景

解决思路

1. 先调用 `$openai-docs`（首选）或直接调用 OpenAI docs MCP 服务器，在写代码前获取最新 Apps SDK 文档，至少抓取基线页面：`apps-sdk/build/mcp-server`、`apps-sdk/build/chatgpt-ui`、`apps-sdk/build/examples`、`apps-sdk/plan/tools`、`apps-sdk/reference`。
2. 脚手架新应用或生成首版实现时抓取 `apps-sdk/quickstart`，并在从零发明脚手架前先检查官方示例仓库/页面。
3. 当任务涉及本地 ChatGPT 测试、托管或公开发布时，抓取部署/提交文档：`apps-sdk/deploy`、`apps-sdk/deploy/submission`、`apps-sdk/app-submission-guidelines`。
4. 在解释设计选择或生成的脚手架时引用所用文档 URL。
5. 当当前文档指导与旧仓库模式冲突时，优先采用当前文档，并显式说明兼容性别名。
6. 如果文档搜索超时或匹配不佳，直接按 URL 抓取规范 Apps SDK 页面并继续，不要让搜索失败阻塞脚手架。
7. 若 `$openai-docs` 不可用，改用 `mcp__openaiDeveloperDocs__search_openai_docs` 和 `mcp__openaiDeveloperDocs__fetch_openai_doc`。
8. 按需阅读参考文件：`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`（上游示例选择）、`references/window-openai-patterns.md`（ChatGPT 专属小组件行为）。
9. 使用明确将本技能与 `$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.`
10. 编码前询问或推断这些输入：用例与主要用户流程、只读 vs 变更型工具、演示 vs 生产目标、私有/内部 vs 公开目录提交、后端语言与 UI 技术栈、认证需求、CSP 白名单所需的外部 API 域名、托管目标与本地开发方式、组织所有权/验证就绪度（提交任务）。
11. 在选择示例、仓库形态或脚手架前，先把请求归类为一个主要原型并说明：`tool-only`、`vanilla-widget`、`react-widget`、`interactive-decoupled`、`submission-ready`。
12. 除非缺失细节确实阻塞，否则推断原型；用原型决定：是否需要 UI、是否保留 `server/` + `web/` 拆分布局、优先官方 OpenAI 示例还是 ext-apps 示例还是本地回退脚手架、哪些验证检查最重要、是否默认使用 `search` 和 `fetch` 作为只读工具面。
13. 绿地应用按此顺序选择起点：1) 官方 OpenAI 示例（当已有接近的示例匹配技术栈或交互模式）；2) 版本匹配的 `@modelcontextprotocol/ext-apps` 示例（需要更底层或更可移植的 MCP Apps 基线）；3) 仅当没有接近示例、用户想要极简 Node + vanilla 起步、或网络/示例获取不可取时，才用 `scripts/scaffold_node_ext_apps.mjs`。
14. 不要在有接近上游示例时从零生成大型自定义脚手架；复制最小匹配示例，删除无关演示代码，再按当前文档和用户请求打补丁。
15. 在规划工具或选择起点前先选定一个主要原型；优先单一原型而非混合多个；请求宽泛时推断能满足需求的最小原型；仅当用户要求公开发布、目录提交或可评审部署时才升级到 `submission-ready`；在回复中说明所选原型以便用户尽早纠正。
16. 编码前先规划工具面：每个工具一个职责；工具描述以“Use this when...”行为线索开头；输入显式且机器友好（枚举、必填字段、边界）；决定每个工具是纯数据、纯渲染还是两者兼具；准确设置注解（`readOnlyHint`、`destructiveHint`、`openWorldHint`，为真时加 `idempotentHint`）。
17. 若应用是连接器类、纯数据、同步导向或面向公司知识/深度研究，默认使用标准 `search` 和 `fetch` 工具，而不是自创只读等价物。
18. 教育/演示应用每个工具只讲一个概念，便于模型干净地选对示例；按学习目标分组演示工具：数据进小组件、小组件动作回到对话或工具、宿主/布局环境信号、生命周期/流式行为。
19. 选择最简单且契合目标的结构：快速原型/工作坊/概念验证用最小演示模式；生产 UX 用解耦的数据/渲染模式，避免小组件在每次工具调用时重渲染。
20. 非平凡应用优先解耦模式：数据工具返回可复用的 `structuredContent`；渲染工具附加 `_meta.ui.resourceUri` 和可选 `_meta["openai/outputTemplate"]`；渲染工具描述中说明前置条件（例如“先调用 `search`”）。
21. 绿地工作默认用接近的上游示例：ChatGPT 面向应用、精致 UI 模式、React 组件、文件上传流程、模态流程或类似文档示例的应用先查官方 OpenAI 示例；更接近原始 MCP Apps 桥/服务器接线或版本匹配包模式更重要时用 `@modelcontextprotocol/ext-apps` 示例。
22. 挑选最小匹配示例，只复制相关文件，不要原样移植整个展示应用；复制后按抓取的当前文档对齐：工具名/描述、注解、`_meta.ui.*`、CSP、URI 版本化和本地运行说明；用一句话说明选了哪个示例及原因。
23. 仅当用户想要快速绿地 Node 起步、可接受 vanilla HTML 小组件、且没有更好的上游示例时，才用 `scripts/scaffold_node_ext_apps.mjs`；抓取当前文档后再运行，然后按文档对齐生成文件；若选脚本而非上游示例，说明回退为何更适合该请求。
24. 以下情况跳过脚本：已有接近的官方示例、用户已有应用结构、需要非 Node 技术栈、明确要 React 优先、或只要计划/评审而非代码。
25. 脚本生成最小 `@modelcontextprotocol/ext-apps` 服务器加默认使用 MCP Apps 桥的 vanilla HTML 小组件；生成的小组件把后续消息保持在标准 `ui/message` 桥上，仅用 `window.openai` 做可选宿主信号/扩展；运行后按当前文档和用户请求打补丁：调整工具名/描述、注解、资源元数据、URI 版本化和 README/运行说明。
26. 脚手架 MCP 服务器：用 MCP Apps UI MIME 类型（`text/html;profile=mcp-app`）或使用 `@modelcontextprotocol/ext-apps/server` 时的 SDK 常量（`RESOURCE_MIME_TYPE`）注册小组件资源/模板；注册工具时给出清晰名称、schema、标题和描述；有意返回 `structuredContent`（模型+小组件）、`content`（模型叙述）和 `_meta`（仅小组件数据）；保持处理器幂等或显式记录非幂等行为；在 ChatGPT 中有帮助时包含工具状态字符串（`openai/toolInvocation/*`）。
27. 保持 `structuredContent` 简洁；把大体积或敏感的仅小组件载荷移到 `_meta`。
28. 脚手架小组件 UI：优先用 MCP Apps 桥以保证可移植性，再在能实质改善 UX 时添加 ChatGPT 专属 `window.openai` API；监听 `ui/notifications/tool-result`（基于 `postMessage` 的 JSON-RPC）；从 `structuredContent` 渲染；组件发起的工具调用用 `tools/call`；仅当 UI 状态应改变模型所见时才用 `ui/update-model-context`。
29. `window.openai` 用于兼容和扩展（文件上传、模态、显示模式等），不要作为新应用的唯一集成路径。
30. API 表面护栏：把示例中包装桥的 `app` 对象（如 `@modelcontextprotocol/ext-apps/react` 暴露的 `app.sendMessage()`、`app.callServerTool()`、`app.openLink()` 或宿主 getter）视为实现细节或便利层，而非默认教学的规范公共 API。
31. 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`。
32. 若引用仓库示例中的包装辅助函数，把它们映射回文档化的 `window.openai` 或 MCP Apps 桥原语，并说明该包装不是规范 API 表面；用 `references/window-openai-patterns.md` 做包装到规范的映射和 React 辅助提取模式。
33. 在小组件资源/模板上有意设置资源元数据：`_meta.ui.csp` 带精确的 `connectDomains` 和 `resourceDomains`；`_meta.ui.domain` 用于提交就绪部署；`_meta.ui.prefersBorder`（或需要时用 OpenAI 兼容别名）；可选 `openai/widgetDescription` 减少冗余叙述；除非 iframe 嵌入是产品核心，否则避免 `frameDomains`。
34. 强制最小可工作仓库契约：仓库形态匹配所选原型；MCP 服务器和工具接到可达的 `/mcp` 端点；工具有清晰描述、准确注解和所需 UI 元数据；连接器类/纯数据/同步导向/公司知识类应用在相关时使用标准 `search` 和 `fetch` 工具形态；有 UI 时小组件正确使用 MCP Apps 桥；仓库包含足够脚本或命令供用户本地运行和检查；回复明确说明运行了哪些验证、哪些没运行。
35. 按最小可工作仓库契约验证本地循环，而非仅“文件是否创建”：先跑最低成本检查（静态契约审查、可行时语法/编译检查、可行时本地 `/mcp` 健康检查）；再升级到运行时检查（在 MCP Inspector 中验证工具描述符和小组件渲染、通过 HTTPS 隧道在 ChatGPT 开发者模式测试、演练重试和重复工具调用确认幂等、检查宿主事件和后续工具调用后小组件更新）。
36. 若只交付脚手架而不安装依赖，仍要跑低成本检查并明确说明未运行什么。
37. 本地开发时包含明确的 ChatGPT 设置步骤（不只是代码/运行命令）：在 `http://localhost:<port>/mcp` 本地运行 MCP 服务器；用公共 HTTPS 隧道暴露本地服务器（例如 `ngrok http <port>`）；从 ChatGPT 连接时用隧道 HTTPS URL 加 `/mcp` 路径；在 ChatGPT 中于 **Settings → Apps & Connectors → Advanced settings** 启用开发者模式；在 ChatGPT 应用设置中为远程 MCP 服务器创建新应用并粘贴公共 MCP URL；告诉用户在 MCP 工具/元数据变更后刷新应用以重载最新描述符。
38. 注意：部分文档/截图仍用旧“connector”术语；逐步说明时优先当前产品措辞（“app”），同时承认两种标签。
39. 用户要求部署或准备发布时，为 MCP 服务器（以及单独托管时的小组件资源）生成托管指导：托管在稳定公共 HTTPS 端点（非隧道）并具备可靠 TLS；在 `/mcp` 上保持低延迟流式行为；在仓库外配置密钥（环境变量/密钥管理器）；为工具调用添加日志、请求延迟跟踪和错误可见性；添加基本可观测性（CPU、内存、请求量）和排查路径；提交前在 ChatGPT 开发者模式重新测试托管端点。
40. 仅当用户打算公开目录上架时才包含提交与发布步骤：用 `apps-sdk/deploy/submission` 做提交流程、`apps-sdk/app-submission-guidelines` 做评审要求；私有/内部应用留在开发者模式而非提交；提交前确认组织验证和 Owner 角色前提；确保 MCP 服务器使用公共生产端点（无 localhost/测试 URL）并配置提交就绪的 CSP；准备提交材料：应用元数据、logo/截图、隐私政策 URL、支持联系方式、测试提示/响应、本地化信息；若需认证，包含评审安全的演示凭据并端到端测试登录路径；在平台仪表板提交评审、监控评审状态、仅在批准后发布。
41. 当应用有长生命周期小组件状态、重复交互或组件发起的工具调用（如游戏、看板、地图、仪表板、编辑器）时，阅读 `references/interactive-state-sync-patterns.md`，用于选择：状态快照加单调事件令牌（`stateVersion`、`resetCount` 等）、幂等重试安全处理器、`structuredContent` vs `_meta` 分区、MCP Apps 桥优先更新流加可选 `window.openai` 兼容、更复杂交互应用的解耦数据/渲染工具架构。
42. 脚手架代码时按此顺序输出（除非用户另有要求）：1) 所选主要应用原型及原因；2) 工具计划与架构选择（最小 vs 解耦）；3) 所选上游起点（官方示例、ext-apps 示例或本地回退脚手架）及原因；4) 所用 `$openai-docs` 文档页面/URL；5) 要创建或修改的文件树；6) 实现（服务器+小组件）；7) 针对最小可工作仓库契约执行的验证；8) 本地运行/测试说明（含隧道 + ChatGPT 开发者模式应用设置）；9) 部署/托管指导（若要求或隐含）；10) 提交就绪清单（公开发布请求）；11) 风险、缺口和后续改进。
43. 对于直接脚手架请求，不要停在计划：给出简要计划后立即创建文件。

适用边界 · 注意事项

• 当 `$openai-docs` 或 OpenAI 文档 MCP 工具不可用且无法直接按 URL 抓取规范文档时，不要凭记忆生成代码。
• 当已有接近的官方或 ext-apps 上游示例时，不要从零生成大型自定义脚手架。
• 当用户已有应用结构、需要非 Node 技术栈、明确要 React 优先、或只要计划/评审而非代码时，不要使用 `scripts/scaffold_node_ext_apps.mjs`。