Back to Details

chatgpt-apps

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ChatGPT Apps

ChatGPT Apps

Overview

概述

Scaffold ChatGPT Apps SDK implementations with a docs-first, example-first workflow, then generate code that follows current Apps SDK and MCP Apps bridge patterns.
Use this skill to produce:
  • A primary app-archetype classification and repo-shape decision
  • A tool plan (names, schemas, annotations, outputs)
  • An upstream starting-point recommendation (official example, ext-apps example, or local fallback scaffold)
  • An MCP server scaffold (resource registration, tool handlers, metadata)
  • A widget scaffold (MCP Apps bridge first, 
    window.openai
    compatibility/extensions second)
  • A reusable Node + 
    @modelcontextprotocol/ext-apps
    starter scaffold for low-dependency fallbacks
  • A validation report against the minimum working repo contract
  • Local dev and connector setup steps
  • A short stakeholder summary of what the app does (when requested)
遵循文档优先、示例优先的工作流生成ChatGPT Apps SDK实现的脚手架，然后生成符合当前Apps SDK和MCP Apps桥接层规范的代码。
使用本技能可产出：
  • 核心应用原型分类与代码仓库结构决策
  • 工具规划（名称、Schema、注解、输出）
  • 上游起始项目推荐（官方示例、ext-apps示例或本地兜底脚手架）
  • MCP服务器脚手架（资源注册、工具处理器、元数据）
  • widget脚手架（优先适配MCP Apps桥接层，其次适配
    window.openai
    兼容/扩展能力）
  • 可复用的Node + 
    @modelcontextprotocol/ext-apps
    入门脚手架，用于低依赖兜底场景
  • 符合最低可运行仓库契约的验证报告
  • 本地开发与连接器配置步骤
  • 面向利益相关者的应用功能简短摘要（按需提供）

Mandatory Docs-First Workflow

强制文档优先工作流

Use 
$openai-docs
first whenever building or changing a ChatGPT Apps SDK app.
  1. Invoke 
    $openai-docs
    (preferred) or call the OpenAI docs MCP server directly.
  2. Fetch current Apps SDK docs before writing code, especially (baseline pages): 
    • apps-sdk/build/mcp-server
    • apps-sdk/build/chatgpt-ui
    • apps-sdk/build/examples
    • apps-sdk/plan/tools
    • apps-sdk/reference
  3. Fetch 
    apps-sdk/quickstart
    when scaffolding a new app or generating a first-pass implementation, and check the official examples repo/page before inventing a scaffold from scratch.
  4. Fetch deployment/submission docs when the task includes local ChatGPT testing, hosting, or public launch: 
    • apps-sdk/deploy
    • apps-sdk/deploy/submission
    • apps-sdk/app-submission-guidelines
  5. Cite the docs URLs you used when explaining design choices or generated scaffolds.
  6. Prefer current docs guidance over older repo patterns when they differ, and call out compatibility aliases explicitly.
  7. If doc search times out or returns poor matches, fetch the canonical Apps SDK pages directly by URL and continue; do not let search failure block scaffolding.
If 
$openai-docs
is unavailable, use:
  • mcp__openaiDeveloperDocs__search_openai_docs
  • mcp__openaiDeveloperDocs__fetch_openai_doc
Read 
references/apps-sdk-docs-workflow.md
for suggested doc queries and a compact checklist. Read 
references/app-archetypes.md
to classify the request into a small number of supported app shapes before choosing examples or scaffolds. Read 
references/repo-contract-and-validation.md
when generating or reviewing a repo so the output stays inside a stable “working app” contract. Read 
references/search-fetch-standard.md
when the app is connector-like, data-only, sync-oriented, or meant to work well with company knowledge or deep research. Read 
references/upstream-example-workflow.md
when starting a greenfield app or when deciding whether to adapt an upstream example or use the local fallback scaffold. Read 
references/window-openai-patterns.md
when the task needs ChatGPT-specific widget behavior or when translating repo examples that use wrapper-specific 
app.*
helpers.
无论何时构建或修改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专属的widget行为，或是需要转换使用特定封装
app.*
辅助方法的仓库示例，请阅读
references/window-openai-patterns.md
。

Prompt Guidance

提示词使用指南

Use prompts that explicitly pair this skill with 
$openai-docs
so the resulting scaffold is grounded in current docs.
Preferred prompt patterns:
  • 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.
When responding, ask for or infer these inputs before coding:
  • Use case and primary user flows
  • Read-only vs mutating tools
  • Demo vs production target
  • Private/internal use vs public directory submission
  • Backend language and UI stack
  • Auth requirements
  • External API domains for CSP allowlists
  • Hosting target and local dev approach
  • Org ownership/verification readiness (for submission tasks)
使用提示词时请明确将本技能与
$openai-docs
搭配使用，确保生成的脚手架符合最新文档要求。
推荐的提示词模式：
  • 使用$chatgpt-apps和$openai-docs为<场景>生成ChatGPT应用脚手架，使用<TS/Python> MCP服务器和<React/vanilla> widget。
  • 使用$chatgpt-apps和$openai-docs将最匹配的官方Apps SDK示例适配为面向<场景>的ChatGPT应用。
  • 使用$chatgpt-apps和$openai-docs将这个Apps SDK演示重构为生产就绪结构，包含工具注解、CSP和URI版本控制。
  • 使用$chatgpt-apps和$openai-docs先规划工具，再生成MCP服务器和widget代码。
响应请求时，编码前请询问或推断以下输入信息：
  • 使用场景和核心用户流程
  • 工具是只读还是可修改数据
  • 目标是演示项目还是生产项目
  • 是私有/内部使用还是提交到公共目录
  • 后端语言和UI技术栈
  • 鉴权要求
  • CSP允许列表中的外部API域名
  • 部署目标和本地开发方案
  • 组织归属/验证准备情况（针对提交类任务）

Classify The App Before Choosing Code

选择代码前先对应用进行分类

Before choosing examples, repo shape, or scaffolds, classify the request into one primary archetype and state it.
  • tool-only
  • vanilla-widget
  • react-widget
  • interactive-decoupled
  • submission-ready
Infer the archetype unless a missing detail is truly blocking. Use the archetype to choose:
  • whether a UI is needed at all
  • whether to preserve a split 
    server/
    + 
    web/
    layout
  • whether to prefer official OpenAI examples, ext-apps examples, or the local fallback scaffold
  • which validation checks matter most
  • whether 
    search
    and 
    fetch
    should be the default read-only tool surface
Read 
references/app-archetypes.md
for the decision rubric.
选择示例、仓库结构或脚手架前，先将需求分类为一个核心原型并明确说明。
  • tool-only
    （仅工具）
  • vanilla-widget
    （原生widget）
  • react-widget
    （React widget）
  • interactive-decoupled
    （解耦式交互）
  • submission-ready
    （可提交版本）
除非缺失的信息确实阻塞流程，否则直接推断原型。基于原型选择：
  • 是否需要UI
  • 是否保留
    server/
    + 
    web/
    的拆分结构
  • 优先选择官方OpenAI示例、ext-apps示例还是本地兜底脚手架
  • 哪些验证检查最重要
  • search
    和
    fetch
    是否应该作为默认的只读工具接口
阅读
references/app-archetypes.md
了解决策规则。

Default Starting-Point Order

默认起始项目优先级

For greenfield apps, prefer these starting points in order:
  1. Official OpenAI examples when a close example already matches the requested stack or interaction pattern.
  2. Version-matched 
    @modelcontextprotocol/ext-apps
    examples     when the user needs a lower-level or more portable MCP Apps baseline.
  3. scripts/scaffold_node_ext_apps.mjs
     only when no close example fits, the user wants a tiny Node + vanilla starter, or network access/example retrieval is undesirable.
Do not generate a large custom scaffold from scratch if a close upstream example already exists. Copy the smallest matching example, remove unrelated demo code, then patch it to the current docs and the user request.
对于全新应用，按以下优先级选择起始项目：
  1. 官方OpenAI示例：如果已有匹配请求技术栈或交互模式的近似示例。
  2. 版本匹配的
    @modelcontextprotocol/ext-apps
    示例    ：如果用户需要更低层级、更具可移植性的MCP Apps基线。
  3. scripts/scaffold_node_ext_apps.mjs
    ：仅当没有匹配的示例、用户需要极小的Node + 原生开发入门模板，或是不希望进行网络访问/获取示例时使用。
如果已有近似的上游示例，不要从零生成大型自定义脚手架。复制最小匹配的示例，删除无关的演示代码，然后根据最新文档和用户需求进行调整。

Build Workflow

构建工作流

0. Classify The App Archetype

0. 对应用原型进行分类

Pick one primary archetype before planning tools or choosing a starting point.
  • Prefer a single primary archetype instead of mixing several.
  • If the request is broad, infer the smallest archetype that can still satisfy it.
  • Escalate to 
    submission-ready
    only when the user asks for public launch, directory submission, or review-ready deployment.
  • Call out the chosen archetype in your response so the user can correct it early if needed.
规划工具或选择起始项目前先选定一个核心原型。
  • 优先选择单个核心原型，不要混合多个原型。
  • 如果需求范围很广，选择可以满足需求的最小原型。
  • 仅当用户要求公开发布、提交到目录或是需要可审核的部署版本时，才选择
    submission-ready
    原型。
  • 在响应中明确说明你选择的原型，方便用户尽早纠正。

1. Plan Tools Before Code

1. 编码前先规划工具

Define the tool surface area from user intents.
  • Use one job per tool.
  • Write tool descriptions that start with "Use this when..." behavior cues.
  • Make inputs explicit and machine-friendly (enums, required fields, bounds).
  • Decide whether each tool is data-only, render-only, or both.
  • Set annotations accurately (
    readOnlyHint
    , 
    destructiveHint
    , 
    openWorldHint
    ; add 
    idempotentHint
    when true).
  • If the app is connector-like, data-only, sync-oriented, or intended for company knowledge or deep research, default to the standard 
    search
    and 
    fetch
    tools instead of inventing custom read-only equivalents.
  • For educational/demo apps, prefer one concept per tool so the model can pick the right example cleanly.
  • Group demo tools by learning objective: data into the widget, widget actions back into the conversation or tools, host/layout environment signals, and lifecycle/streaming behavior.
Read 
references/search-fetch-standard.md
when 
search
and 
fetch
may be relevant.
根据用户意图定义工具接口范围。
  • 每个工具只负责一项任务。
  • 工具描述以「Use this when...」的行为提示开头。
  • 输入参数明确且机器友好（枚举、必填字段、取值范围）。
  • 明确每个工具是仅数据、仅渲染，还是两者兼具。
  • 准确设置注解（
    readOnlyHint
    、
    destructiveHint
    、
    openWorldHint
    ；如果适用请添加
    idempotentHint
    ）。
  • 如果应用是连接器类、仅数据类、同步导向类，或是面向企业知识库/深度调研场景，默认使用标准的
    search
    和
    fetch
    工具，不要自定义等价的只读工具。
  • 对于教育/演示类应用，每个工具优先对应一个概念，方便模型清晰选择合适的示例。
  • 按学习目标对演示工具分组：数据传入widget、widget动作返回对话或工具、宿主/布局环境信号、生命周期/流式行为。
如果涉及
search
和
fetch
相关场景，请阅读
references/search-fetch-standard.md
。

2. Choose an App Architecture

2. 选择应用架构

Choose the simplest structure that fits the goal.
  • Use a minimal demo pattern for quick prototypes, workshops, or proofs of concept.
  • Use a decoupled data/render pattern for production UX so the widget does not re-render on every tool call.
Prefer the decoupled pattern for non-trivial apps:
  • Data tools return reusable 
    structuredContent
    .
  • Render tools attach 
    _meta.ui.resourceUri
    and optional 
    _meta["openai/outputTemplate"]
    .
  • Render tool descriptions state prerequisites (for example, "Call 
    search
    first").
选择符合目标的最简单结构。
  • 对于快速原型、研讨会或概念验证，使用极简演示模式。
  • 生产环境UX使用数据/渲染解耦模式，避免每次工具调用都重新渲染widget。
非小型应用优先使用解耦模式：
  • 数据工具返回可复用的
    structuredContent
    。
  • 渲染工具附加
    _meta.ui.resourceUri
    和可选的
    _meta["openai/outputTemplate"]
    。
  • 渲染工具描述明确说明前置条件（例如「请先调用
    search
    」）。

2a. Start From An Upstream Example When One Fits

2a. 存在适配的上游示例时优先使用

Default to upstream examples for greenfield work when they are close to the requested app.
  • Check the official OpenAI examples first for ChatGPT-facing apps, polished UI patterns, React components, file upload flows, modal flows, or apps that resemble the docs examples.
  • Use 
    @modelcontextprotocol/ext-apps
    examples when the request is closer to raw MCP Apps bridge/server wiring, or when version-matched package patterns matter more than ChatGPT-specific polish.
  • Pick the smallest matching example and copy only the relevant files; do not transplant an entire showcase app unchanged.
  • After copying, reconcile the example with the current docs you fetched: tool names/descriptions, annotations, 
    _meta.ui.*
    , CSP, URI versioning, and local run instructions.
  • State which example you chose and why in one sentence.
Read 
references/upstream-example-workflow.md
for the selection and adaptation rubric.
全新开发时如果存在接近请求需求的上游示例，默认使用上游示例。
  • 面向ChatGPT的应用、成熟UI模式、React组件、文件上传流程、模态框流程或是和文档示例相似的应用，优先查看官方OpenAI示例。
  • 如果需求更偏向原生MCP Apps桥接/服务器连接，或是版本匹配的包模式比ChatGPT专属优化更重要，请使用
    @modelcontextprotocol/ext-apps
    示例。
选择最小匹配的示例，仅复制相关文件；不要原样移植整个展示应用。 复制完成后，对照你获取的最新文档调整示例：工具名称/描述、注解、
_meta.ui.*
、CSP、URI版本控制和本地运行说明。 用一句话说明你选择的示例以及选择原因。
阅读
references/upstream-example-workflow.md
了解选择和适配规则。

2b. Use the Starter Script When a Low-Dependency Fallback Helps

2b. 需要低依赖兜底时使用启动脚本

Use 
scripts/scaffold_node_ext_apps.mjs
only when the user wants a quick, greenfield Node starter and a vanilla HTML widget is acceptable, and no upstream example is a better starting point.
  • Run it only after fetching current docs, then reconcile the generated files with the docs you fetched.
  • If you choose the script instead of an upstream example, say why the fallback is better for that request.
  • Skip it when a close official example exists, when the user already has an existing app structure, when they need a non-Node stack, when they explicitly want React first, or when they only want a plan/review instead of code.
  • The script generates a minimal 
    @modelcontextprotocol/ext-apps
    server plus a vanilla HTML widget that uses the MCP Apps bridge by default.
  • The generated widget keeps follow-up messaging on the standard 
    ui/message
    bridge and only uses 
    window.openai
    for optional host signals/extensions.
  • After running it, patch the generated output to match the current docs and the user request: adjust tool names/descriptions, annotations, resource metadata, URI versioning, and README/run instructions.
仅当用户需要快速的全新Node入门模板、可以接受原生HTML widget，且没有更合适的上游示例时，才使用
scripts/scaffold_node_ext_apps.mjs
。
  • 仅在获取最新文档后运行脚本，然后对照最新文档调整生成的文件。
  • 如果你选择使用脚本而不是上游示例，请说明为什么兜底方案更适合该需求。
  • 以下场景跳过该脚本：存在近似官方示例、用户已有现有应用结构、用户需要非Node技术栈、用户明确优先使用React、用户只需要规划/审核而非代码。
  • 脚本默认生成极简的
    @modelcontextprotocol/ext-apps
    服务器，以及使用MCP Apps桥接层的原生HTML widget。
  • 生成的widget在标准
    ui/message
    桥接层上保留后续消息能力，仅将
    window.openai
    用于可选的宿主信号/扩展。
  • 运行脚本后，根据最新文档和用户需求调整生成的输出：调整工具名称/描述、注解、资源元数据、URI版本控制和README/运行说明。

3. Scaffold the MCP Server

3. 生成MCP服务器脚手架

Generate a server that:
  • Registers a widget resource/template with the MCP Apps UI MIME type (
    text/html;profile=mcp-app
    ) or the SDK constant (
    RESOURCE_MIME_TYPE
    ) when using 
    @modelcontextprotocol/ext-apps/server
  • Registers tools with clear names, schemas, titles, and descriptions
  • Returns 
    structuredContent
    (model + widget), 
    content
    (model narration), and 
    _meta
    (widget-only data) intentionally
  • Keeps handlers idempotent or documents non-idempotent behavior explicitly
  • Includes tool status strings (
    openai/toolInvocation/*
    ) when helpful in ChatGPT
Keep 
structuredContent
concise. Move large or sensitive widget-only payloads to 
_meta
.
生成的服务器需满足：
  • 使用
    @modelcontextprotocol/ext-apps/server
    时，使用MCP Apps UI MIME类型（
    text/html;profile=mcp-app
    ）或SDK常量（
    RESOURCE_MIME_TYPE
    ）注册widget资源/模板
  • 注册的工具具备清晰的名称、Schema、标题和描述
  • 有意识地返回
    structuredContent
    （模型 + widget）、
    content
    （模型叙述）和
    _meta
    （仅widget可见数据）
  • 处理器保持幂等性，否则明确说明非幂等行为
  • 有需要时在ChatGPT中包含工具状态字符串（
    openai/toolInvocation/*
    ）
保持
structuredContent
简洁。将大型或敏感的仅widget可见 payload 移动到
_meta
。

4. Scaffold the Widget UI

4. 生成Widget UI脚手架

Use the MCP Apps bridge first for portability, then add ChatGPT-specific 
window.openai
APIs when they materially improve UX.
  • Listen for 
    ui/notifications/tool-result
    (JSON-RPC over 
    postMessage
    )
  • Render from 
    structuredContent
  • Use 
    tools/call
    for component-initiated tool calls
  • Use 
    ui/update-model-context
    only when UI state should change what the model sees
Use 
window.openai
for compatibility and extensions (file upload, modal, display mode, etc.), not as the only integration path for new apps.
优先使用MCP Apps桥接层保障可移植性，当可以显著提升UX时再添加ChatGPT专属的
window.openai
API。
  • 监听
    ui/notifications/tool-result
    （基于
    postMessage
    的JSON-RPC）
  • 基于
    structuredContent
    渲染
  • 组件发起工具调用时使用
    tools/call
  • 仅当UI状态需要修改模型可见内容时使用
    ui/update-model-context
window.openai
用于兼容和扩展（文件上传、模态框、展示模式等），不要作为新应用的唯一集成路径。

API Surface Guardrails

API接口防护规则

  • Some examples wrap the bridge with an 
    app
    object (for example, 
    @modelcontextprotocol/ext-apps/react
    ) and expose helper names like 
    app.sendMessage()
    , 
    app.callServerTool()
    , 
    app.openLink()
    , or host getter methods.
  • Treat those wrappers as implementation details or convenience layers, not the canonical public API to teach by default.
  • For ChatGPT-facing guidance, prefer the current documented surface: 
    window.openai.callTool(...)
    , 
    window.openai.sendFollowUpMessage(...)
    , 
    window.openai.openExternal(...)
    , 
    window.openai.requestDisplayMode(...)
    , and direct globals like 
    window.openai.theme
    , 
    window.openai.locale
    , 
    window.openai.displayMode
    , 
    window.openai.toolInput
    , 
    window.openai.toolOutput
    , 
    window.openai.toolResponseMetadata
    , and 
    window.openai.widgetState
    .
  • If you reference wrapper helpers from repo examples, map them back to the documented 
    window.openai
    or MCP Apps bridge primitives and call out that the wrapper is not the normative API surface.
  • Use 
    references/window-openai-patterns.md
    for the wrapper-to-canonical mapping and for React helper extraction patterns.
  • 部分示例使用
    app
    对象封装桥接层（例如
    @modelcontextprotocol/ext-apps/react
    ），暴露
    app.sendMessage()
    、
    app.callServerTool()
    、
    app.openLink()
    等辅助方法或宿主获取方法。
  • 将这些封装视为实现细节或便利层，不要作为默认教授的规范公共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. Add Resource Metadata and Security

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

Set resource metadata deliberately on the widget resource/template:
  • _meta.ui.csp
    with exact 
    connectDomains
    and 
    resourceDomains
  • _meta.ui.domain
    for app submission-ready deployments
  • _meta.ui.prefersBorder
    (or OpenAI compatibility alias when needed)
  • Optional 
    openai/widgetDescription
    to reduce redundant narration
Avoid 
frameDomains
unless iframe embeds are core to the product.
在widget资源/模板上主动设置资源元数据：
  • _meta.ui.csp
    包含精确的
    connectDomains
    和
    resourceDomains
  • 可提交部署的应用配置
    _meta.ui.domain
  • _meta.ui.prefersBorder
    （需要时使用OpenAI兼容别名）
  • 可选配置
    openai/widgetDescription
    减少冗余叙述
除非iframe嵌入是产品核心功能，否则避免使用
frameDomains
。

5a. Enforce A Minimum Working Repo Contract

5a. 强制满足最低可运行仓库契约

Every generated repo should satisfy a small, stable contract before you consider it done.
  • The repo shape matches the chosen archetype.
  • The MCP server and tools are wired to a reachable 
    /mcp
    endpoint.
  • Tools have clear descriptions, accurate annotations, and UI metadata where needed.
  • Connector-like, data-only, sync-oriented, and company-knowledge-style apps use the standard 
    search
    and 
    fetch
    tool shapes when relevant.
  • The widget uses the MCP Apps bridge correctly when a UI exists.
  • The repo includes enough scripts or commands for a user to run and check it locally.
  • The response explicitly says what validation was run and what was not run.
Read 
references/repo-contract-and-validation.md
for the detailed checklist and validation ladder.
每个生成的仓库在完成前都需要满足小型稳定的契约要求。
  • 仓库结构匹配选择的原型。
  • MCP服务器和工具连接到可访问的
    /mcp
    端点。
  • 工具具备清晰的描述、准确的注解，需要时包含UI元数据。
  • 连接器类、仅数据类、同步导向类和企业知识库类应用相关场景下使用标准的
    search
    和
    fetch
    工具形态。
  • 存在UI时widget正确使用MCP Apps桥接层。
  • 仓库包含足够的脚本或命令，方便用户本地运行和检查。
  • 响应明确说明执行了哪些验证，未执行哪些验证。
阅读
references/repo-contract-and-validation.md
了解详细检查清单和验证层级。

6. Validate the Local Loop

6. 验证本地运行链路

Validate against the minimum working repo contract, not just “did files get created.”
  • Run the lowest-cost checks first:
    • static contract review
    • syntax or compile checks when feasible
    • local 
      /mcp
      health check when feasible
  • Then move up to runtime checks:
    • verify tool descriptors and widget rendering in MCP Inspector
    • test the app in ChatGPT developer mode through HTTPS tunneling
    • exercise retries and repeated tool calls to confirm idempotent behavior
    • check widget updates after host events and follow-up tool calls
  • If you are only delivering a scaffold and are not installing dependencies, still run low-cost checks and say exactly what you did not run.
Read 
references/repo-contract-and-validation.md
for the validation ladder.
对照最低可运行仓库契约进行验证，不要仅验证「文件是否生成」。
  • 优先运行成本最低的检查：
    • 静态契约审核
    • 可行时进行语法或编译检查
    • 可行时进行本地
      /mcp
      健康检查
  • 然后进行运行时检查：
    • 在MCP Inspector中验证工具描述符和widget渲染
    • 通过HTTPS隧道在ChatGPT开发者模式中测试应用
    • 测试重试和重复工具调用，确认幂等行为
    • 检查宿主事件和后续工具调用后的widget更新
  • 如果你只提供脚手架不安装依赖，仍然需要运行低成本检查，并明确说明未执行的检查项。
阅读
references/repo-contract-and-validation.md
了解验证层级。

7. Connect and Test in ChatGPT (Developer Mode)

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

For local development, include explicit ChatGPT setup steps (not just code/run commands).
  • Run the MCP server locally on 
    http://localhost:<port>/mcp
  • Expose the local server with a public HTTPS tunnel (for example 
    ngrok http <port>
    )
  • Use the tunneled HTTPS URL plus 
    /mcp
    path when connecting from ChatGPT
  • In ChatGPT, enable Developer Mode under Settings → Apps & Connectors → Advanced settings
  • In ChatGPT app settings, create a new app for the remote MCP server and paste the public MCP URL
  • Tell users to refresh the app after MCP tool/metadata changes so ChatGPT reloads the latest descriptors
Note: Some docs/screenshots still use older "connector" terminology. Prefer current product wording ("app") while acknowledging both labels when giving step-by-step instructions.
本地开发场景下，提供明确的ChatGPT配置步骤（不只是代码/运行命令）。
  • 在本地
    http://localhost:<port>/mcp
    运行MCP服务器
  • 使用公共HTTPS隧道暴露本地服务器（例如
    ngrok http <port>
    ）
  • 从ChatGPT连接时使用带隧道的HTTPS URL + 
    /mcp
    路径
  • 在ChatGPT中，在设置 → 应用和连接器 → 高级设置下启用开发者模式
  • 在ChatGPT应用设置中，为远程MCP服务器创建新应用，粘贴公共MCP URL
  • 告知用户MCP工具/元数据修改后刷新应用，让ChatGPT加载最新的描述符
注意：部分文档/截图仍使用旧的「connector」术语。提供分步指引时优先使用当前产品术语（「app」），同时说明两种命名。

8. Plan Production Hosting and Deployment

8. 规划生产环境托管和部署

When the user asks to deploy or prepare for launch, generate hosting guidance for the MCP server (and widget assets if hosted separately).
  • Host behind a stable public HTTPS endpoint (not a tunnel) with dependable TLS
  • Preserve low-latency streaming behavior on 
    /mcp
  • Configure secrets outside the repo (environment variables / secret manager)
  • Add logging, request latency tracking, and error visibility for tool calls
  • Add basic observability (CPU, memory, request volume) and a troubleshooting path
  • Re-test the hosted endpoint in ChatGPT Developer Mode before submission
当用户要求部署或准备发布时，生成MCP服务器的托管指引（以及单独托管的widget资源指引）。
  • 托管在稳定的公共HTTPS端点（非隧道）上，具备可靠的TLS配置
  • 保留
    /mcp
    端点的低延迟流式行为
  • 在仓库外配置密钥（环境变量/密钥管理器）
  • 为工具调用添加日志、请求延迟追踪和错误可视化能力
  • 添加基础可观测性（CPU、内存、请求量）和故障排查路径
  • 提交前在ChatGPT开发者模式中重新测试托管端点

9. Prepare Submission and Publish (Public Apps Only)

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

Only include these steps when the user intends a public directory listing.
  • Use 
    apps-sdk/deploy/submission
    for the submission flow and 
    apps-sdk/app-submission-guidelines
    for review requirements
  • Keep private/internal apps in Developer Mode instead of submitting
  • Confirm org verification and Owner-role prerequisites before submission work
  • Ensure the MCP server uses a public production endpoint (no localhost/testing URLs) and has submission-ready CSP configured
  • Prepare submission artifacts: app metadata, logo/screenshots, privacy policy URL, support contact, test prompts/responses, localization info
  • If auth is required, include review-safe demo credentials and test the login path end-to-end
  • Submit for review in the Platform dashboard, monitor review status, and publish only after approval
仅当用户计划发布到公共目录时才包含这些步骤。
  • 使用
    apps-sdk/deploy/submission
    了解提交流程，使用
    apps-sdk/app-submission-guidelines
    了解审核要求
  • 私有/内部应用保持在开发者模式即可，无需提交
  • 提交工作前确认组织验证和Owner角色前置条件已满足
  • 确保MCP服务器使用公共生产端点（无localhost/测试URL），并配置了符合提交要求的CSP
  • 准备提交物料：应用元数据、logo/截图、隐私政策URL、支持联系方式、测试提示词/响应、本地化信息
  • 如果需要鉴权，提供审核可用的演示凭证，并端到端测试登录流程
  • 在平台控制台提交审核，监控审核状态，仅在审核通过后发布

Interactive State Guidance

交互状态指引

Read 
references/interactive-state-sync-patterns.md
when the app has long-lived widget state, repeated interactions, or component-initiated tool calls (for example, games, boards, maps, dashboards, editors).
Use it to choose patterns for:
  • State snapshots plus monotonic event tokens (
    stateVersion
    , 
    resetCount
    , etc.)
  • Idempotent retry-safe handlers
  • structuredContent
    vs 
    _meta
    partitioning
  • MCP Apps bridge-first update flows with optional 
    window.openai
    compatibility
  • Decoupled data/render tool architecture for more complex interactive apps
如果应用具备长期widget状态、重复交互或组件发起的工具调用（例如游戏、看板、地图、仪表盘、编辑器），请阅读
references/interactive-state-sync-patterns.md
。
使用该文档选择以下场景的模式：
  • 状态快照 + 单调事件令牌（
    stateVersion
    、
    resetCount
    等）
  • 幂等、重试安全的处理器
  • structuredContent
    和
    _meta
    的划分
  • 优先MCP Apps桥接层的更新流，可选兼容
    window.openai
  • 更复杂的交互应用的解耦数据/渲染工具架构

Output Expectations

输出预期

When using this skill to scaffold code, produce output in this order unless the user asks otherwise:
  • For direct scaffold requests, do not stop at the plan: give the brief plan, then create the files immediately.
  1. Primary app archetype chosen and why
  2. Tool plan and architecture choice (minimal vs decoupled)
  3. Upstream starting point chosen (official example, ext-apps example, or local fallback scaffold) and why
  4. Doc pages/URLs used from 
    $openai-docs
  5. File tree to create or modify
  6. Implementation (server + widget)
  7. Validation performed against the minimum working repo contract
  8. Local run/test instructions (including tunnel + ChatGPT Developer Mode app setup)
  9. Deployment/hosting guidance (if requested or implied)
  10. Submission-readiness checklist (for public launch requests)
  11. Risks, gaps, and follow-up improvements
使用本技能生成脚手架代码时，除非用户另有要求，否则按以下顺序输出：
  • 对于直接的脚手架请求，不要停留在规划阶段：先提供简短规划，然后立即创建文件。
  1. 选择的核心应用原型以及选择原因
  2. 工具规划和架构选择（极简还是解耦）
  3. 选择的上游起始项目（官方示例、ext-apps示例或本地兜底脚手架）以及选择原因
  4. 从
    $openai-docs
    获取的文档页面/URL
  5. 需要创建或修改的文件树
  6. 实现代码（服务器 + widget）
  7. 对照最低可运行仓库契约执行的验证结果
  8. 本地运行/测试指引（包括隧道 + ChatGPT开发者模式应用配置）
  9. 部署/托管指引（按需或隐含要求时提供）
  10. 提交就绪检查清单（公开发布请求时提供）
  11. 风险、缺口和后续改进方向

References

参考资料

  • references/app-archetypes.md
    for classifying requests into a small number of supported app shapes
  • references/apps-sdk-docs-workflow.md
    for doc queries, page targets, and code-generation checklist
  • references/interactive-state-sync-patterns.md
    for reusable patterns for stateful or highly interactive widget apps
  • references/repo-contract-and-validation.md
    for the minimum working repo contract and lightweight validation ladder
  • references/search-fetch-standard.md
    for when and how to default to the standard 
    search
    and 
    fetch
    tools
  • references/upstream-example-workflow.md
    for choosing between official examples, ext-apps examples, and the local fallback scaffold
  • references/window-openai-patterns.md
    for ChatGPT-specific extensions, wrapper API translation, and React helper patterns
  • scripts/scaffold_node_ext_apps.mjs
    for a minimal Node + 
    @modelcontextprotocol/ext-apps
    fallback starter scaffold
  • references/app-archetypes.md
    ：将需求分类为少量支持的应用形态
  • references/apps-sdk-docs-workflow.md
    ：文档查询、页面目标和代码生成检查清单
  • references/interactive-state-sync-patterns.md
    ：有状态或高交互widget应用的可复用模式
  • 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
    兜底入门脚手架