SuperAPI AI 工具集

openai-apps-sdk

编程与开发

查看项目

更新于 10-16 06:16

技能介绍

用途:在用 OpenAI Apps SDK 构建 ChatGPT 应用时参考,指导优先使用 MCP Apps 标准字段,仅在标准未覆盖的能力上使用 ChatGPT 专有扩展。

主要能力与要点:

  1. 标准优先:链路工具→UI 资源用 _meta.ui.resourceUri,接收工具输入、结果、调用工具、发送后续消息、更新模型可见上下文分别对应 ui/initialize 与 ui/notifications/tool-input、ui/notifications/tool-result、tools/call、ui/message、ui/update-model-context。ChatGPT 别名(openai/outputTemplate、window.openai.toolInput 等)仍可用但属旧式。
  2. ChatGPT 专有扩展(无标准等价):requestCheckout(session)、uploadFile(file)、selectFiles()、getFileDownloadUrl({ fileId })、requestModal(opts)、widgetState/setWidgetState(state)。
  3. 特性探测而非宿主探测:const openai = typeof window !== "undefined" ? window.openai : undefined; 按能力存在与否分支,不要判断宿主名。
  4. 工具与资源 _meta:工具侧可含 ui.resourceUri、openai/toolInvocation/invoking 与 invoked、openai/widgetAccessible、openai/visibility、openai/fileParams;资源侧含 ui.prefersBorder、ui.domain、ui.csp(connectDomains、resourceDomains、frameDomains)及 openai/widgetDescription。
  5. 数据/渲染分离模式:数据工具只返回 structuredContent、不带 resourceUri;渲染工具才携带 _meta.ui.resourceUri,避免每次调用重建 iframe、破坏本地状态。渲染工具描述中需写明依赖关系,渲染处理器不放业务逻辑。
  6. 组件状态:用 window.openai?.widgetState 初始化与 setWidgetState 持久化;结构化形式支持 modelContent、privateContent、imageIds。状态属单次渲染实例,非持久存储,localStorage 不可靠。
  7. 显示模式:内联卡片、内联轮播、全屏、画中画,并说明各自适用与约束;用 window.openai?.requestDisplayMode 请求。
  8. 打包与嵌入:用 esbuild 打包为 ESM,服务端读取并用 registerAppResource 以 text/html;profile=mcp-app 内联;建议目录为 plugin-ui/server 与 web/src、web/dist。可选 @openai/apps-sdk-ui 组件库。
  9. 本地化:读取 document.documentElement.lang,配合 IntlProvider。
  10. 结账:外部结账(链接自有域名)为推荐且默认路径,审批目前限于实物商品;requestCheckout 嵌入式支付为内测,会话需含唯一 session ID、明细与数量、整数最小货币单位总额、支付与商户元数据及法律/隐私/退款/支持链接,开发用 payment_mode: "test";服务端为唯一事实来源,需校验支付令牌、使 complete_checkout 幂等、持久化订单并返回权威收据,不得信任组件计算的总价。

限制与说明:原文未提供价格、平台支持范围、性能数据或效果保证;M365 Copilot 支持情况见 host-capability-matrix,未在本文档给出。