系统架构

系统概览

Open-OX Studio 由三个主要层次构成：Next.js 前端（SSR + 客户端状态）、 AI 流水线（服务端编排）、以及外部服务（Supabase、E2B、LLM API）。

浏览器
  └── /studio/[projectId]   ← React 客户端，SSE 消费者
        │
        ├── POST /api/projects      → 创建 DB 记录，返回 projectId
        ├── POST /api/ai            → 启动生成流（SSE）
        ├── POST /api/.../modify    → 启动修改流（SSE）
        └── POST /api/.../preview   → 启动/刷新预览（后端随 OPEN_OX_PREVIEW_BACKEND 分支）

服务端（Next.js API Routes）
  ├── AI 流水线（generate_project / modify_project）
  ├── Supabase（projects 表 + project-files / site-previews Storage）
  └── 预览：OPEN_OX_PREVIEW_BACKEND env → local | storage | e2b

技术栈

为什么用原生 fetch 而非 OpenAI SDK

OpenAI SDK 内部使用 agentkeepalive，默认 socket timeout 为 8 秒。 单次 section 生成调用可达 60 秒，SDK 会强制断连。 原生 fetch 配合 AbortSignal.timeout(300_000) 覆盖所有场景。

const res = await fetch(`${baseURL}/chat/completions`, {
  method: "POST",
  body: JSON.stringify({ model, messages, tools }),
  signal: AbortSignal.timeout(300_000), // 5 min
});

请求流程

从用户输入到上线预览的完整生命周期：

1. 用户输入 prompt → 点击 Build
2. POST /api/projects  → 创建 DB 记录（status=generating）
3. 服务端立即返回 projectId（< 100ms）
4. 浏览器跳转到 /studio/{projectId}
5. 页面检测 status=generating 且 buildSteps 为空
6. 自动触发 POST /api/ai，传入 projectId
7. 服务端运行 AI 流水线，每个步骤完成后：
   a. SSE 事件推送到浏览器（实时显示）
   b. 写入 Supabase（支持断线恢复）
8. status → ready / failed

API 路由

输入触发器系统

HeroPrompt 输入框支持多种触发器，在文本任意位置通过特殊字符激活。 选中后以彩色 chip 形式注入，提交时各 chip 的 payload 合并到请求体。

架构

app/hooks/usePromptTriggers.ts   — 统一触发器 hook（检测 / @ # + 光标位置）
app/components/ui/TriggerMenu.tsx — 浮层下拉菜单（按类型显示不同颜色前缀）
app/components/ui/PromptChips.tsx — 注入的标签展示（含图片缩略图）
app/components/ui/QuickTemplates.tsx — 快捷模板 pills

触发检测基于光标位置：从光标往前搜索最近的触发字符， 触发字符必须在行首或空格后，且到光标之间不含空格。 这允许用户在文本中间任意位置触发菜单。

Modify Agent

生成后的迭代修改由 Modify Agent 处理 — 一个受 Claude Code 启发的开放式 Agent 循环。 Agent 在单次循环中完成搜索、阅读、编辑和验证。

工具列表

4-Phase 工作流

Phase 1: ORIENT  — search_code + list_dir，建立全局理解
Phase 2: READ    — 只读 1-2 个最相关文件，形成修改计划
Phase 3: EDIT    — edit_file 精确替换，最小改动
Phase 4: VERIFY  — run_build 验证编译

安全机制

Must read before edit — edit_file 前必须先 read_file，防止盲改。Loop Detection — 连续 4 次操作同一文件时注入策略转换提示。Tool Result Budget — 单条结果上限 30K 字符。Context 压缩 — 基于相关性，热文件保留完整，冷文件压缩。

数据持久化

projects 表

源码持久化在 Storage 桶 project-files；静态预览产物在 site-previews（由 /site-previews/… 代理访问）。 本地丢失时从 project-files 恢复到 sites/ 后再构建预览。

关键工程决策