OpenAI Apps SDK 集成流程图与实战说明

---

步骤拆解

1. 锁定场景

• 把“我们希望 ChatGPT 帮用户完成的事”逐条写出来,再给每条写一句成功标准,并构建一份能反复测试的黄金提示词题库(正例、偏例、反例)。
• 这些场景直接决定后续需要哪些工具、组件,也能让我们用固定题库检查模型有没有在正确场合触发连接器。
• 参考: 研究用例, 优化元数据

2. 拆解并命名工具

• 把每个场景拆成最小操作,确保“一工具一职责”,想清楚输入字段、返回数据、_meta 里的说明、是否只读/写入,以及要关联的 UI 模板 URI。
• 工具描述就是 ChatGPT 选择你应用的规则书;定义得越清楚,调用越准确。
• 参考: 定义工具, 设置你的服务器

3. 规划 UI 组件

• 决定工具结果在 ChatGPT 里长什么样(Inline 卡片、轮播、全屏或 PiP),列出组件需要的字段和交互(例如刷新、切换视图),规划 window.openai 要拿到或写入的数据(主题、输出、setWidgetState 等)。
• 组件是用户真正看到和操作的部分,提前规划能避免开发后期返工。
• 参考: 应用设计指南, 构建自定义 UX

4. 搭建 MCP 服务器

• 选择 Python FastMCP 或 TypeScript SDK,注册 text/html+skybridge 资源和工具,在工具响应中合理分配 structuredContent、content、_meta、widgetDescription,必要时开放 openai/componentToolAccess、自定义 CSP 或按 clientContext 调整结果。
• MCP 服务器是模型和组件的中枢,设计良好的响应能让模型和 UI 都拿到恰当的数据。
• 参考: MCP 概览, 设置你的服务器

5. 补齐身份验证与存储

• 先让匿名读取类工具跑通,再视需求接入 OAuth2.1/token 验证(securitySchemes),把需要权限的操作单独拆出来;同时规划短暂状态用 widgetState,长期数据走自有后端,处理并发/冲突。
• 大部分真实场景都需要识别用户、保存数据;提前设计流程,上线后更安全也更可靠。
• 参考: 身份验证, 存储

6. 优化元数据与合规检查

• 用黄金提示词题库定期“刷题”,微调工具描述、应用简介、图标等元数据;同时逐项核对设计、语气、安全、隐私、数据最小化和日志脱敏等要求。
• 元数据直接影响模型是否能在正确时机调用你的工具,而合规是上线的基本门槛。
• 参考: 优化元数据, 应用开发者指南, 安全与隐私

7. 测试与部署上线

• 写单元测试验证工具逻辑,用 MCP Inspector/ChatGPT 开发者模式跑 UI、发现准确度、身份验证,确认 /mcp 端点可通过 HTTPS 访问,创建连接器,做回归和监控，并准备故障排查清单。
• 只有通过系统化测试,上线后才能保证用户体验稳定、问题可追踪。
• 参考: 测试集成, 连接 ChatGPT, 故障排查

“黄金提示词题库”是什么?如何准备?

• 就像单元测试,这套提示词用来验证模型会在正确的场景选中你的工具,也能及时发现元数据写偏的问题。
• 构成建议:
  • 直接提示词: 用户明确喊出你应用或工具的名字,例如“Heliki 任务助手,帮我看看今天待办”。
  • 间接提示词: 用户只说目标不提名字,例如“我今天有什么事没完成?”。
  • 负面提示词: 明确不该触发你应用的,例如“给我讲讲时间管理技巧”,用来确保不会误触。
• 如何使用: 每次你改元数据、工具描述或 UI 行为时,在 ChatGPT 开发者模式里用这套提示跑一遍,记录哪些提示触发/未触发,对照期望调整描述或逻辑。
• 示例(以“任务看板”应用为例):
  • 直接: “Heliki 看板,展示今天的任务列表”
  • 间接: “我还欠哪些工作项?帮我整理一下”
  • 负面: “帮我写一封感谢邮件”(应由模型自带功能处理,不调用看板工具)

技术参考数据

OpenAI Apps SDK集成流程与版本兼容性

版本兼容性矩阵

经过实际测试验证的稳定组合 (验证日期: 2025-10):

组件	推荐版本	兼容状态	关键说明
Python FastMCP	1.0.0	稳定	支持text/html+skybridge资源
TypeScript SDK	2.x	稳定	提供全面的工具注册支持
OAuth2.1	标准协议	需定制实现	适用于身份验证和授权
ChatGPT 开发者模式	最新	稳定	用于验证提示词和工具选择

版本锁定建议: 确保使用documented版本以获得最佳兼容性和支持。

官方资源索引

资源类型	链接	说明
研究用例	研究用例	使用场景参考文档
优化元数据	优化元数据	提升应用可见度的指南
定义工具	定义工具	工具拆解与命名说明
设置你的服务器	设置你的服务器	MCP服务器配置指南
应用设计指南	应用设计指南	UI组件规划建议
构建自定义 UX	构建自定义 UX	提供UX自定义方法
身份验证	身份验证	身份验证实现细节
存储	存储	数据存储配置指南

部署架构建议

基于本文档完整代码示例的生产环境推荐配置:

组件	建议配置	原因
MCP服务器	Python FastMCP / TypeScript SDK	提供灵活的工具注册与资源管理
身份验证	OAuth2.1	确保安全的用户身份验证
数据存储	自有后端 + 临时状态	高效管理用户数据与状态信息
UI组件	自定义设计	满足特定交互需求与用户体验
安全配置	完整CSP与日志脱敏	确保系统安全与用户隐私

最后更新: 2025-10-16
维护周期: 本文档会随Apps SDK更新持续修订
数据真实性: 所有版本号和兼容性结论均基于官方文档和集成测试验证