课时

在本讲中，我们拆解 ChatGPT Apps 的“中枢大脑”：模型如何在普通文本回复与工具调用（ tool-call）之间做选择；它究竟能看到什么（system prompt、 tools 列表、对话历史）；为什么 name/ description/ inputSchema 至关重要；在 API 层面的调用长什么样（ tool_calls、 finish_reason）；以及权限/注解（ readOnly、 destructive）如何影响模型行为与 UX。

在本讲中，我们讲解如何在 MCP 和 ChatGPT Apps 中通过 JSON Schema来描述工具： inputSchema 的结构、为何它是模型“提示词”的一部分、如何编写合适的 description、何时使用 enum 与约束（ minItems、 format）。接着我们在 TypeScript 中用 Zod + zod-to-json-schema 搭建“single source of truth”，讨论 optional 字段的问题，并展示 _meta/annotations（例如 readOnlyHint、 destructiveHint、 openai/outputTemplate）在 UX 与安全上的作用。

解析在 Apps SDK + MCP 生态中的工具调用服务端链路：ChatGPT 如何通过 JSON-RPC 调用 tool，Next.js 模板中 MCP 服务器（ app/mcp/route.ts）位于何处，如何设计 inputSchema 并通过 content 与 structuredContent 返回结果，如何通过 _meta 和 openai/outputTemplate 绑定 UI，以及如何进行校验、授权、调用外部 API、日志记录与错误处理。

我们来拆解 ChatGPT Apps 中从 server tool 到 React‑UI 的完整数据路径： ToolOutput 如何通过 Apps SDK 进入小部件， structuredContent、 content 与 _meta 有何不同；如何通过钩子（ useWidgetProps）而不是直接访问 window 来安全读取 toolOutput；以及如何围绕工具调用结果构建 UI 状态（loading/empty/error）。

本讲将解释为什么在 ChatGPT Apps 中同一个 tool 可能被重复调用（重试、 Regenerate、网络故障），如何通过 idempotency_key 设计幂等操作，如何以模型与 UI 都能一致理解的方式返回错误（ ok/ error、 code、 retryable），以及如何通过 text/html+skybridge 和 _meta（CSP、域、视觉标记）安全地配置小部件。