ChatGPT应用构建器

从概念到生产环境，构建、测试和部署ChatGPT应用的完整工作流程。

命令

• /chatgpt-apps new- 创建一个新的ChatGPT应用
• /chatgpt-apps add-tool- 向你的应用添加一个MCP工具
• /chatgpt-apps add-widget- 向你的应用添加一个小部件
• /chatgpt-apps add-auth- 配置身份验证
• /chatgpt-apps add-database- 设置数据库
• /chatgpt-apps validate- 验证你的应用
• /chatgpt-apps test- 运行测试
• /chatgpt-apps deploy- 部署到生产环境
• /chatgpt-apps resume- 继续处理某个应用

目录

1. 创建新应用
2. 添加MCP工具
3. 添加小组件
4. 添加身份验证
5. 添加数据库
6. 生成黄金提示
7. 验证应用程序
8. 测试应用程序
9. 部署应用程序
10. 恢复应用程序

1. 创建新应用程序

目的：从概念到可运行代码，创建一个新的ChatGPT应用程序。

工作流程

阶段1：概念化

1. 询问应用程序构思"您想构建什么样的ChatGPT应用程序？请描述它的功能和解决的问题。"

2. 基于用户体验原则进行分析

   • 对话优势：用户通过自然语言能实现什么？
   • 原生适配性：这如何与ChatGPT的对话流集成？
   • 可组合性工具能否独立工作并与其他应用程序结合？

3. 检查反模式

   • 静态网站内容展示
   • 需要外部标签页的复杂多步骤工作流
   • 重复ChatGPT的固有功能
   • 广告或追加销售

4. 定义用例创建3-5个主要用例，并附上用户故事。

第二阶段：设计

1. 工具拓扑结构

   • 查询工具 (readOnlyHint: true)
   • 变更工具 (destructiveHint: false)
   • 破坏性工具 (destructiveHint: true)
   • 小部件工具 (使用_meta返回UI)
   • 外部API工具 (openWorldHint: true)

2. 小部件设计针对每个小部件：

   • id- 唯一标识符 (kebab-case)
   • name- 显示名称
   • description- 它显示的内容
   • 模拟数据- 用于预览的示例数据

3. 数据模型设计实体和关系。

4. 认证要求

   • 单用户（无需认证）
   • 多用户（Auth0 或 Supabase Auth）

阶段 3：实施

按此结构生成完整应用程序：

{app-name}/
├── package.json
├── tsconfig.server.json
├── setup.sh
├── START.sh
├── .env.example
├── .gitignore
└── server/
    └── index.ts

关键要求：

• 服务器来自@modelcontextprotocol/sdk/server/index.js 的类
• StreamableHTTPServerTransport用于会话管理
• 小部件 URI：ui://widget/{widget-id}.html
• 小部件 MIME 类型：text/html+skybridge
• structuredContent在工具响应中
• _meta使用openai/outputTemplate关于工具

第四阶段：测试

• 运行设置：./setup.sh
• 开始开发：./START.sh --dev
• 预览小部件：http://localhost:3000/preview
• 测试 MCP 连接

第五阶段：部署

• 生成 Dockerfile 和 render.yaml
• 部署到 Render
• 配置 ChatGPT 连接器

2. 添加 MCP 工具

目的：向您的 ChatGPT 应用添加一个新的 MCP 工具。

工作流程

1. 收集信息

   • 这个工具是做什么的？
   • 它需要哪些输入？
   • 它返回什么？

2. 分类工具类型

   • 查询(readOnlyHint: true) - 获取数据
   • 变更(destructiveHint: false) - 创建/更新数据
   • 破坏性操作(destructiveHint: true) - 删除数据
   • 微件- 返回用户界面内容
   • 外部(openWorldHint: true) - 调用外部API

3. 设计输入模式创建带有适当类型和描述的Zod模式。

4. 生成工具处理器使用chatgpt-mcp-generator代理来创建：

   • 工具处理器位于server/tools/
   • Zod模式导出
   • 类型导出
   • 数据库查询（如果需要）

5. 注册工具更新server/index.ts带有元数据：

   {
     name: "my-tool",
     _meta: {
       "openai/toolInvocation/invoking": "Loading...",
       "openai/toolInvocation/invoked": "Done",
       "openai/outputTemplate": "ui://widget/my-widget.html", // if widget
     }
   }
   

6. 更新状态添加工具到.chatgpt-app/state.json。

工具命名

使用短横线命名法：列表项、创建任务、显示食谱详情

注解指南

3. 添加小部件

目的：通过 HTML/CSS/JS 和应用 SDK 集成添加内联 HTML 小部件。

5 种小部件模式

1. 卡片网格- 网格中的多个项目
2. 统计仪表板- 关键指标显示
3. 表格- 表格数据
4. 条形图- 简单可视化
5. 详情小部件- 单个项目详情

工作流程

1. 收集信息

   • 小部件目的和数据
   • 视觉设计（卡片、表格、图表等）
   • 交互性需求

2. 定义数据结构使用TypeScript接口记录预期结构。

3. 添加小部件配置

   const widgets: WidgetConfig[] = [
     {
       id: "my-widget",
       name: "My Widget",
       description: "Displays data",
       templateUri: "ui://widget/my-widget.html",
       invoking: "Loading...",
       invoked: "Ready",
       mockData: { /* sample */ },
     },
   ];
   

4. 添加小部件HTML使用以下方式生成HTML：

   • 支持预览模式 (window.PREVIEW_DATA)
   • 集成OpenAI Apps SDK (window.openai.toolOutput)
   • 事件监听器 (openai:set_globals)
   • 轮询后备方案 (100毫秒间隔，10秒超时)

5. 创建/更新工具通过以下方式将工具链接到小部件：widgetId.

6. 测试小部件在以下地址预览：/preview/{widget-id}使用模拟数据。

小部件HTML结构

(function() {
  let rendered = false;

  function render(data) {
    if (rendered || !data) return;
    rendered = true;
    // Render logic
  }

  function tryRender() {
    if (window.PREVIEW_DATA) { render(window.PREVIEW_DATA); return; }
    if (window.openai?.toolOutput) { render(window.openai.toolOutput); }
  }

  window.addEventListener('openai:set_globals', tryRender);

  const poll = setInterval(() => {
    if (window.openai?.toolOutput || window.PREVIEW_DATA) {
      tryRender();
      clearInterval(poll);
    }
  }, 100);
  setTimeout(() => clearInterval(poll), 10000);

  tryRender();
})();

4. 添加身份验证

目的：使用 Auth0 或 Supabase Auth 配置身份验证。

何时添加

• 多用户
• 每个用户的持久私有数据
• 用户特定的 API 凭证

提供商

Auth0：

• 企业级
• OAuth 2.1，PKCE 流程
• 社交登录（Google、GitHub 等）

Supabase Auth：

• 设置更简单
• 默认电子邮件/密码
• 与 Supabase 数据库集成

工作流程

1. 选择提供商根据需求询问用户偏好。

2. 指导设置

   • Auth0：创建应用程序、配置回调 URL、获取凭证
   • Supabase：已配置数据库设置

3. 生成认证码使用chatgpt-auth-generator代理来创建：

   • 会话管理中间件
   • 用户主体提取
   • 令牌验证

4. 更新服务器添加认证中间件以保护路由。

5. 更新环境

   # Auth0
   AUTH0_DOMAIN=your-tenant.auth0.com
   AUTH0_CLIENT_ID=...
   AUTH0_CLIENT_SECRET=...
   
   # Supabase (from database setup)
   SUPABASE_URL=...
   SUPABASE_ANON_KEY=...
   

6. 测试验证登录流程和用户隔离。

5. 添加数据库

目的：使用Supabase配置PostgreSQL数据库。

何时添加

• 持久化用户数据
• 多实体关系
• 查询/过滤能力

工作流程

1. 检查Supabase设置验证账户和项目是否存在。

2. 收集凭据

   • 项目URL
   • 匿名密钥（公开）
   • 服务角色密钥（服务器端）

3. 定义实体为每个实体，指定：

   • 字段和类型
   • 关系
   • 索引

4. 生成模式使用chatgpt-database-generator代理来创建包含以下内容的SQL：

   • id（UUID主键）
   • user_subject（varchar，已索引）
   • created_at（timestamptz类型）
   • updated_at（timestamptz类型）
   • 用于用户隔离的行级安全策略

5. 设置连接池

   import { createClient } from '@supabase/supabase-js';
   
   const supabase = createClient(
     process.env.SUPABASE_URL!,
     process.env.SUPABASE_SERVICE_ROLE_KEY!
   );
   

6. 应用迁移在 Supabase 仪表板或通过迁移工具运行 SQL。

查询模式

始终按user_subject进行筛选：

const { data } = await supabase
  .from('tasks')
  .select('*')
  .eq('user_subject', userSubject);

6. 生成黄金提示词

目的：生成测试提示词，以验证 ChatGPT 是否正确调用工具。

重要性

• 衡量精确度/召回率
• 支持迭代改进
• 发布后监控

3个类别

1. 直接提示词- 明确要求调用工具

   • "显示我的任务列表"
   • "创建一个名为...的新任务"

2. 间接提示词- 基于结果，ChatGPT 应推断出使用工具

   • "我今天需要做什么？"
   • "帮我整理一下工作"

3. 负面提示词- 不应触发工具调用

   • “什么是任务？”
   • “跟我讲讲项目管理”

工作流程

1. 分析工具审查每个工具的用途和输入。

2. 生成提示为每个工具创建：

   • 5个以上直接提示
   • 5个以上间接提示
   • 3个以上负面提示
   • 2个以上边界案例提示

3. 最佳实践

   • 工具描述以“在以下情况下使用此工具：”开头
   • 清晰说明局限性
   • 在描述中包含示例

4. 保存输出写入.chatgpt-app/golden-prompts.json：

   {
     "toolName": {
       "direct": ["prompt1", "prompt2"],
       "indirect": ["prompt1", "prompt2"],
       "negative": ["prompt1", "prompt2"],
       "edge": ["prompt1", "prompt2"]
     }
   }
   

7. 验证应用

目的：部署前的验证套件。

10个验证检查

1. 必需文件

   • package.json
   • tsconfig.server.json
   • setup.sh (可执行文件)
   • START.sh (可执行文件)
   • server/index.ts
   • .env.example

2. 服务器实现

   • 使用服务器来自 MCP SDK
   • 具有StreamableHTTPServerTransport
   • 使用 Map 进行会话管理
   • 正确的请求处理器

3. 小部件配置

   • 小部件数组存在
   • 每个都具有 id、name、description、templateUri、mockData
   • URI 符合模式ui://widget/{id}.html

4. 工具响应格式

   • 返回结构化内容（不仅仅是内容)
   • 小部件工具具有_meta与openai/outputTemplate

5. 资源处理器格式

   • MIME类型：text/html+skybridge
   • 返回_meta包含序列化和CSP

6. 小部件HTML结构

   • 预览模式支持
   • 适用于Apps SDK的事件监听器
   • 轮询后备方案
   • 渲染保护

7. 端点存在性

   • /health- 健康检查
   • /preview- 小部件索引
   • /preview/:widgetId- 小部件预览
   • /mcp- MCP端点

8. Package.json脚本

   • 包含build:server
   • 包含start且设置HTTP_MODE=true
   • 包含dev且启用监视模式
   • 无Web构建脚本（web/、ui/、client/）

9. 注解验证

   • readOnlyHint设置正确
   • 删除操作的destructiveHint
   • 外部API的openWorldHint

10. 数据库验证（如启用）

    • 表包含必需字段
    • user_subject已建立索引
    • RLS策略已启用

常见错误

关键：在其他验证之前，首先检查文件是否存在！

8. 测试应用

目的：使用MCP检查器和黄金提示运行自动化测试。

4个测试类别

1. MCP协议

   • 服务器启动无错误
   • 处理初始化
   • 正确列出工具
   • 正确列出资源

2. 模式验证

   • 工具模式是有效的Zod
   • 标记必填字段
   • 类型与实现匹配

3. 组件测试

   • 所有组件在预览模式下都能渲染
   • 模拟数据正确加载
   • 无控制台错误

4. 黄金提示测试

   • 直接提示触发正确的工具
   • 间接提示按预期工作
   • 负面提示不触发工具

工作流程

1. 在测试模式下启动服务器

   HTTP_MODE=true NODE_ENV=test npm run dev
   

2. 运行MCP检查器测试协议合规性：

   • 初始化连接
   • 列出工具
   • 使用有效输入调用每个工具
   • 检查响应

3. 模式验证验证模式是否编译并与实现匹配。

4. 黄金提示测试使用ChatGPT测试提示：

   • 记录调用了哪个工具
   • 与预期工具对比
   • 计算精确率/召回率

5. 生成报告

   {
     "passed": 42,
     "failed": 3,
     "categories": {
       "mcp": "✅",
       "schema": "✅",
       "widgets": "✅",
       "prompts": "⚠️ 3 failures"
     },
     "timing": "2.3s"
   }
   

修复失败项

针对每个失败项，说明：

• 失败内容
• 失败原因
• 如何修复（附代码示例）

9. 部署应用

目的：将ChatGPT应用部署到Render平台，使用PostgreSQL数据库并配置健康检查。

先决条件

• ✅ 验证通过
• ✅ 测试通过
• ✅ Git仓库状态干净
• ✅ 环境变量已就绪

工作流程

1. 部署前检查

   • 运行验证
   • 运行测试
   • 检查数据库连接（如已启用）

2. 生成 render.yaml 文件

   services:
     - type: web
       name: {app-name}
       runtime: docker
       plan: free
       healthCheckPath: /health
       envVars:
         - key: PORT
           value: 3000
         - key: HTTP_MODE
           value: true
         - key: NODE_ENV
           value: production
         - key: WIDGET_DOMAIN
           generateValue: true
         # Add auth/database vars if needed
   

3. 生成 Dockerfile

   FROM node:20-slim
   WORKDIR /app
   COPY package*.json ./
   RUN npm ci --only=production
   COPY dist ./dist
   EXPOSE 3000
   CMD ["node", "dist/server/index.js"]
   

4. 部署 选项A：自动（如果Render MCP可用）使用Render MCP代理进行部署。

   选项B：手动

   • 推送至GitHub
   • 在Render仪表板中连接仓库
   • 设置环境变量
   • 部署

5. 验证部署

   • 健康检查：https://{app}.onrender.com/health
   • MCP端点：https://{app}.onrender.com/mcp
   • 工具发现功能正常
   • 小部件正常渲染

6. 配置ChatGPT连接器

   • URL：https://{app}.onrender.com/mcp
   • 在ChatGPT中测试

10. 恢复应用

目的：恢复构建一个进行中的ChatGPT应用。

工作流程

1. 加载状态读取.chatgpt-app/state.json:

   {
     "appName": "My Task Manager",
     "phase": "Implementation",
     "tools": ["list-tasks", "create-task"],
     "widgets": ["task-list"],
     "auth": false,
     "database": true,
     "validated": false,
     "deployed": false
   }
   

2. 显示进度显示当前状态：

   • 应用名称
   • 当前阶段
   • 已完成项（工具、小组件）
   • 待办项（认证、验证、部署）

3. 提供后续步骤基于阶段：

   概念阶段：

   • "我们来设计工具和小组件"
   • "我们开始实施吗？"

   实施阶段：

   • "添加另一个工具？"
   • "添加一个小组件？"
   • "设置认证？"
   • "设置数据库？"

   测试阶段：

   • "生成黄金提示词？"
   • "运行验证？"
   • "运行测试？"

   部署阶段：

   • "部署到Render？"
   • “配置ChatGPT连接器？”

4. 继续工作根据用户的选择，调用相应的工作流部分。

最佳实践

1. 始终保存状态在每个主要步骤之后
2. 在继续前进之前进行验证（尤其是在部署之前）
3. 使用代理进行代码生成（chatgpt-mcp-generator、chatgpt-auth-generator等）
4. 在每个阶段进行测试（预览小部件、测试工具、运行黄金提示）
5. 保持对话性- 自然地引导用户完成工作流
6. 解释权衡在提供选择时（如Auth0与Supabase等）
7. 展示示例在引入新概念时

状态管理

该.chatgpt-app/state.json文件跟踪进度：

{
  "appName": "string",
  "description": "string",
  "phase": "Concept" | "Implementation" | "Testing" | "Deployment",
  "tools": ["tool-name"],
  "widgets": ["widget-id"],
  "auth": {
    "enabled": boolean,
    "provider": "auth0" | "supabase" | null
  },
  "database": {
    "enabled": boolean,
    "entities": ["entity-name"]
  },
  "validated": boolean,
  "tested": boolean,
  "deployed": boolean,
  "deploymentUrl": "string | null",
  "goldenPromptsGenerated": boolean,
  "lastUpdated": "ISO timestamp"
}

命令参考

# Setup
./setup.sh

# Development
./START.sh --dev          # Dev mode with watch
./START.sh --preview      # Open preview in browser
./START.sh --stdio        # STDIO mode (testing)
./START.sh                # Production mode

# Testing
npm run validate          # Type checking
curl http://localhost:3000/health

# Deployment
git push origin main      # Trigger Render deploy

入门指南

当用户调用任何 chatgpt-app 命令时：

1. 检查.chatgpt-app/state.json是否存在
2. 如果是 → 使用恢复应用工作流程
3. 如果否 → 使用创建新应用工作流程

始终引导用户遵循自然的流程：概念 → 实现 → 测试 → 部署