ChatGPT Apps 技能的上游示例选择工作流官方示例、ext-apps 示例与本地回退脚手架的三级决策体系【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇指南围绕skills/.curated/chatgpt-apps技能中的上游示例选择参考文档展开完整讲解在从零构建greenfieldChatGPT Apps SDK 应用时如何在官方 OpenAI Apps SDK 示例、版本匹配的modelcontextprotocol/ext-apps示例、本地回退脚手架三条路径之间做出决策并给出将上游代码安全、合规地适配进当前项目的完整规则。读完本文你将掌握该技能的默认起点排序、三类来源的适用条件与取舍标准、示例适配的逐项核对清单以及最小匹配示例启发式选型方法可直接用于 ChatGPT Apps 应用的可复现脚手架搭建。一、这份参考文档在技能体系中的定位references/upstream-example-workflow.md是 chatgpt-apps 技能 的七个核心参考文档之一。按 SKILL.md 的约定它的加载时机非常明确当开始一个 greenfield ChatGPT 应用或需要决定是适配某个上游示例还是使用本地回退脚手架时加载本参考。也就是说这份文档回答的不是怎么写代码而是写代码之前从哪一份已有代码起步。它把示例优先example-first、文档先行docs-first的理念落成了一条可执行的决策链先判断应用的定位再在三条候选起点中按优先级挑选最后按统一的适配规则把选中的示例改造成符合当前文档与用户需求的仓库。在技能的整体构建流程中这条决策链位于规划工具Build Workflow 第 1 步与选择架构第 2 步之后、生成 MCP 服务器脚手架第 3 步之前对应 SKILL.md 的第 2a 步从匹配的上游示例起步与第 2b 步在需要低依赖回退时使用脚手架脚本。而具体选择哪个起点又进一步受 app-archetypes.md应用原型分类 的约束——两者必须协同使用。二、默认起点顺序三条路径的优先级参考文档开篇给出了一条不可倒置的优先级链官方 OpenAI Apps SDK 示例openai-apps-sdk-examples官方示例仓库及文档示例页版本匹配的modelcontextprotocol/ext-apps示例本地回退脚手架scripts/scaffold_node_ext_apps.mjs。这条顺序在 SKILL.md 的 Default Starting-Point Order 一节 中被再次强调并补上了一条纪律性要求如果存在接近的官方上游示例不要从零生成大型自定义脚手架复制最小的匹配示例移除无关的演示代码然后按当前文档与用户请求修补它。这样排序的动机在参考文档中写得很直白让技能始终与最新文档和维护中的示例代码对齐同时保留一个低依赖的回退方案用于示例不适用或网络获取不可取的场景。优先级越高代码与官方能力前沿的贴合度越高优先级越低自主可控性越强但与官方 API 演进脱节的风险也越大。三、三种来源的适用条件与典型代表参考文档对每个来源都给出了明确的何时优先使用Prefer when判据这是整个决策体系的核心。3.1 官方 OpenAI 示例ChatGPT 面向、追求界面质感时适用判据满足其一即可优先应用明确面向 ChatGPTclearly ChatGPT-facing用户希望得到精致的 UI 或 React 组件任务涉及文件上传、模态流程modal flows、显示模式切换或其他 ChatGPT 扩展能力官方文档/示例页上已经存在相似交互模式的示例。典型来源参考文档原文列举OpenAI 官方 Apps SDK 构建示例页developers.openai.com的apps-sdk/build/examples/页面官方示例仓库openai-apps-sdk-examples官方快速入门apps-sdk/quickstart/——当只需要最小的 vanilla 基线时使用。这一判据与 app-archetypes.md 的映射完全一致react-widget、interactive-decoupled、submission-ready三个原型的最佳起点都指向官方示例——分别对应组件化精致 UI带状态与重复交互的应用面向公开上架的应用。3.2modelcontextprotocol/ext-apps示例追求底层基线可移植性时适用判据用户需要更低层的 MCP Apps 基线lower-level MCP Apps baseline跨 MCP Apps 兼容宿主hosts的可移植性比 ChatGPT 专属的精致程度更重要希望使用与已安装的modelcontextprotocol/ext-apps包形态高度接近的、版本匹配的示例。参考文档特别指出这与上游create-mcp-app技能的思路一致以维护中的示例为起点然后再做适配。它列举了三个典型的示例形态examples/demo-vanilla-html——纯 HTML 演示examples/demo-react-simple——极简 React 演示examples/demo-connectors-api——连接器/API 类演示。3.3 本地回退脚手架低依赖、快速打补丁时的兜底适用判据满足其一即可使用不存在贴近的上游示例用户只想要一个轻量的 Node vanilla HTML 起步工程不希望依赖网络/示例拉取需要一个一次性throwaway起步工程以便在实时编码任务中快速修补。参考文档同时给出一条反向纪律不要因为本地脚手架恰好可用就优先使用它——它是兜底选项不是默认选项。这一约束在 SKILL.md 第 2b 步 中被进一步放大当存在贴近的官方示例、用户已有应用结构、需要非 Node 技术栈、明确要求 React或只需要方案/评审而不需要代码时都应跳过脚手架脚本。四、本地回退脚手架的源码级剖析既然第三条路径是仅作兜底那么它具体生成什么、如何使用就值得用源码核实。以下是 scripts/scaffold_node_ext_apps.mjs 的真实行为全部可直接在仓库中验证。4.1 命令行用法与参数从脚本内置的usage()输出脚本第 503-514 行可以看到完整用法./scripts/scaffold_node_ext_apps.mjs output_dir [--app-name name] [--tool-name name] [--port number] [--force]若当前环境没有可执行位则改用node scripts/scaffold_node_ext_apps.mjs output_dir ...调用。参数解析逻辑脚本第 516-571 行定义如下参数默认值说明output_dir必填无默认值输出目录缺失时脚本报错并打印用法--app-name nameexample-chatgpt-app应用名会经 slug 化转小写、非字母数字替换为-用于包名--tool-name name取 app-name 的 slug 形式工具名经 snake_case 化非字母数字替换为_--port number8787HTTP 端口必须为正整数否则报错--force关闭允许写入非空目录默认情况下拒绝写入非空目录防止误覆盖--help/-h—打印用法后退出值得注意的是脚本内置了目录安全保护第 34-47 行如果目标路径已存在且不是目录或已是非空目录且未加--force都会直接抛错退出。4.2 生成的文件清单脚本main()第 573-599 行固定生成四个文件文件内容package.json私有 ESM 包type: module脚本dev/start用tsx运行src/server.tscheck用tsc --noEmit依赖modelcontextprotocol/ext-apps、modelcontextprotocol/sdk、zodtsconfig.jsontarget: ES2022、module: NodeNext、strict: true仅包含src/**/*.tspublic/widget.htmlvanilla HTML 组件默认走 MCP Apps bridgeui/initialize、tools/call、ui/notifications/tool-result、ui/message仅把window.openai用于可选宿主信号如主题读取src/server.ts基于modelcontextprotocol/ext-apps/server的 MCP 服务器registerAppResource注册组件资源、registerAppTool注册一个演示工具、StreamableHTTPServerTransport挂在/mcp路径从生成代码看脚手架默认的组件 URI 为ui://widget/main-v1.html第 579 行演示工具带齐了readOnlyHint: true、destructiveHint: false、openWorldHint: false、idempotentHint: true四个注解并携带_meta.ui.resourceUri、_meta[openai/outputTemplate]与openai/toolInvocation/*状态字符串。也就是说即使是最小的兜底脚手架也在模板层面就示范了参考文档适配规则中要求的全部元数据字段。4.3 脚手架脚本的调用纪律结合 apps-sdk-docs-workflow.md 的 Starter Scaffold Script 一节使用该脚本还有两条硬性纪律只在获取了当前文档之后运行生成结果还要再与所取文档核对包版本、元数据、传输层细节、URI/版本号都可能随文档变化生成后必须按文档与用户请求修补输出工具名/描述、注解、资源元数据、URI 版本化、README/运行说明。五、适配规则把上游代码变成文档对齐的仓库参考文档的核心章节是 Adaptation Rules它定义了拿到任意上游示例后必须执行的六条规则。这里逐条展开并结合仓库内其他参考文档给出依据。规则 1复制最小的匹配示例而不是整个展示应用Copy the smallest matching example, not the entire showcase app.这条规则的工程动机在 interactive-state-sync-patterns.md 的反模式清单 中可以得到印证把组件模板挂在每个工具上、把大块 widget-only 数据塞进structuredContent都属于常见反模式。最小复制从源头避免demo 功能污染。规则 2立即移除无关的演示工具、资产与路由Remove unrelated demo tools, assets, and routes immediately.复制完成后马上做减法而不是等到后期清理避免上游 demo 的副作用代码进入新仓库。规则 3当上游目录结构本身干净且与文档一致时保留它Keep the upstream file structure when it is already clean and docs-aligned.这保证了仓库形态的稳定性。而干净且文档对齐的判断标准可以对照 repo-contract-and-validation.md 的最小可工作仓库契约仓库形态必须匹配所选原型、服务器必须暴露可达的/mcp、工具注解准确、有 UI 时正确注册 MCP Apps UI MIME 类型资源等。规则 4完成前必须与当前文档逐项核对参考文档给出的核对清单是本文必须完整继承的核心内容共六项工具名与描述tool names and descriptions与当前文档中的工具形态对齐注解annotationsreadOnlyHint、destructiveHint、openWorldHint以及为true时必须补上的idempotentHint_meta.ui.resourceUri与可选的_meta[openai/outputTemplate]前者是 UI 联动工具的主契约后者按 repo-contract-and-validation.md 的定义只是可选兼容层不是主要契约资源元数据_meta.ui.csp、_meta.ui.domain以及openai/widgetDescription按 apps-sdk-docs-workflow.mdCSP 的connectDomains/resourceDomains必须精确填写widgetDescription必须始终设置以便模型理解组件用途模板变更时的 URI 版本化把 URI 当作缓存键组件 HTML/JS/CSS 发生破坏性变更时更新 URI 版本apps-sdk-docs-workflow.md本地运行/测试说明仓库必须自带可运行的本地命令。规则 5说明你选择了哪个示例以及为什么State which example you chose and why.这一条与技能Output Expectations的要求一致——SKILL.md 要求输出顺序中第三项就是选定的上游起点官方示例 / ext-apps 示例 / 本地回退脚手架及理由。理由必须挂在用户需求与已选原型上而不是顺手拿来。规则 6依赖上游代码时注明来源仓库与分支/标签/提交If you rely on upstream code, note the source repo and branch/tag/commit when practical; avoid silently depending on a floating example shape for long-lived work.对于长期维护的工程这一点尤为重要显式锁定上游版本避免悬浮的示例形态悄悄漂移导致仓库隐性失效。六、最小选择启发式一页纸决策速查参考文档在末尾给出了四条约简版的决策规则它们是前文判据的浓缩也是实践中最常用的快捷键用户诉求起点选择React 精致 UI直接以官方 OpenAI 示例起步vanilla HTML 极简演示以官方 quickstart 示例起步仅当 quickstart 仍过于有主见或不可用时才使用本地回退脚手架可移植的 MCP Apps 接线以modelcontextprotocol/ext-apps示例起步用户已有应用直接适配现有代码不要引入新示例注意最后一条常常被忽略当用户手上已有应用时正确动作是就地适配而不是为了规范而导入新示例。这与 SKILL.md 第 2b 步 中用户已有应用结构时跳过脚手架的约束互为呼应。七、决策链的完整闭环与周边机制的联动upstream-example-workflow.md不是孤立的一张决策表它在技能里的真实工作方式是嵌入一个更大的闭环先分类再选起点先依据 app-archetypes.md 判定主原型tool-only/vanilla-widget/react-widget/interactive-decoupled/submission-ready原型直接决定示例来源偏好。例如tool-only的默认起点是官方文档与 MCP 服务器示例vanilla-widget则是quickstart 优先、本地脚手架兜底文档先行在选示例之前先按 apps-sdk-docs-workflow.md 的基线页面清单MCP server、ChatGPT UI、examples、plan/tools、reference获取当前文档再检查官方示例页最后才考虑从零发明脚手架apps-sdk-docs-workflow.md 第 69-71 行适配并验证复制最小示例、按第五节核对清单修补最后对照 repo-contract-and-validation.md 的验证阶梯静态契约审查 → 语法/编译检查 → 本地/mcp运行健康检查 → 宿主环回验证逐级校验并明确声明验证做到了哪一级、哪些没跑。三条候选起点的优先级之所以如此设计本质是在两组张力之间取平衡与官方文档/示例的最新性对齐与低依赖、可离线、可快速修补的自主可控。官方示例在前保证技能不落后于 API 演进本地脚手架垫底保证任何情况下都有一条能落地的路径而modelcontextprotocol/ext-apps示例居中服务于看重可移植性的宿主无关场景。八、实践检查清单最后把本文全部要点浓缩为一份可直接照做的检查清单先判定主原型并说明理由再进入示例选择按默认顺序官方 → ext-apps → 本地脚手架选择起点不因本地可用而优先复制最小匹配示例立即移除无关 demo 工具/资产/路由核对工具名、描述与四个注解含为 true 时的idempotentHint核对_meta.ui.resourceUri按需镜像_meta[openai/outputTemplate]精确设置_meta.ui.cspconnectDomains/resourceDomains与_meta.ui.domain并设置openai/widgetDescription组件模板破坏性变更时更新 URI 版本补齐本地运行/测试命令并按验证阶梯声明验证级别一句话说明选择了哪个示例及理由依赖上游代码时注明仓库与分支/标签/提交。这套决策体系的价值在于把示例优先从一句口号变成了可执行、可验证、可追溯的工程流程——这正是 chatgpt-apps 技能 能稳定产出文档对齐、契约自洽的 ChatGPT Apps 工程的方法论基础。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考