> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 网站开发与部署

> Zeus Website — 从脚手架到部署的端到端 Web 开发能力

## 概述

Website 是 Zeus 编程模式中的**端到端 Web 开发能力**。Agent 可以在沙盒内初始化 Web 项目、实时预览、检查代码质量，并一键部署到持久化 URL。

核心能力：

* **项目初始化** — 在现有沙箱内 bootstrap Next.js / Vite 项目，秒级就绪
* **实时预览** — 通过沙盒代理 URL 实时查看开发中的网站
* **代码检查** — TypeScript 类型检查 + ESLint 代码质量验证
* **一键部署** — 通过 Freestyle API 部署到持久化 `*.style.dev` URL

***

## 架构

```mermaid theme={null}
flowchart LR
    subgraph sandbox["沙盒"]
        init["website_init<br/>项目初始化"]
        dev["Dev Server<br/>端口 3000"]
        eslint["website_eslint<br/>代码检查"]
    end

    subgraph deploy["部署"]
        tool["website_deploy"]
        freestyle["Freestyle API"]
        url["*.style.dev<br/>持久化 URL"]
    end

    init --> dev
    dev -->|"实时预览"| preview["iframe 预览面板"]
    eslint -->|"诊断结果"| agent["Agent"]
    tool -->|"收集文件"| freestyle
    freestyle --> url
```

### 组件总览

| 组件                 | 路径                                               | 作用                                                   |
| ------------------ | ------------------------------------------------ | ---------------------------------------------------- |
| **Website 工具**     | `ai-backend/src/utils/tools/built_in/website.py` | `website_init` / `website_deploy` / `website_eslint` |
| **SandboxManager** | `ai-backend/src/services/sandbox.py`             | 沙箱生命周期、Web 项目 bootstrap                              |
| **Deploy API**     | `ai-backend/src/api/deploy.py`                   | Freestyle / Vercel / Server 部署路由                     |
| **前端路由**           | `web/src/app/api/deploy/route.ts`                | 代理部署请求到 AI Backend                                   |

***

## Website 工具

编程模式下，Agent 拥有三个 Website 专用工具：

### website\_init

在现有沙箱内初始化 Web 项目。**不会创建新沙箱**，之前的文件完整保留。

| 参数          | 类型     | 默认值      | 说明                     |
| ----------- | ------ | -------- | ---------------------- |
| `framework` | string | `nextjs` | 框架类型：`nextjs` 或 `vite` |

**执行流程：**

```mermaid theme={null}
sequenceDiagram
    participant Agent as Agent
    participant SM as SandboxManager
    participant Sandbox as 沙盒
    participant Preview as 预览面板

    Agent->>SM: website_init(nextjs)
    SM->>Sandbox: mkdir + create-next-app
    SM->>Sandbox: pnpm add lucide-react framer-motion ...
    SM->>Sandbox: pnpm dev --port 3000 (background)
    SM->>SM: 轮询端口就绪 (最长 60s)
    Sandbox-->>SM: 端口 3000 就绪
    SM->>SM: sbx.get_host(3000)
    SM-->>SM: 等待外部代理 URL 可访问
    SM-->>Agent: preview_url + project_files
    SM->>Preview: SSE website_ready 事件
```

**初始化内容（Next.js）：**

* `create-next-app@latest` — TypeScript + Tailwind + ESLint + App Router
* 额外依赖：`lucide-react`、`framer-motion`、`recharts`、`zustand`、`sonner`
* 后台启动 `pnpm dev --port 3000`

### website\_deploy

将当前 Web 项目部署到 Freestyle，获得持久化的公开 URL。

| 参数         | 类型     | 默认值         | 说明                             |
| ---------- | ------ | ----------- | ------------------------------ |
| `platform` | string | `freestyle` | 部署平台：`freestyle`（默认）或 `vercel` |

**执行流程：**

```mermaid theme={null}
sequenceDiagram
    participant Agent as Agent
    participant Tool as website_deploy
    participant Sandbox as 沙盒
    participant FS as Freestyle API

    Agent->>Tool: website_deploy(freestyle)
    Tool->>Sandbox: find 项目文件 (排除 node_modules 等)
    Sandbox-->>Tool: 文件列表
    Tool->>Sandbox: 逐个读取文件内容
    Sandbox-->>Tool: {path: content} 字典
    Tool->>FS: POST /web/v1/deployment
    Note over Tool,FS: source: files<br/>config: build=true, domain=zeus-xxx.style.dev
    FS-->>Tool: deploymentId + domains
    Tool-->>Agent: 持久化 URL
    Tool->>Tool: SSE deploy_complete 事件
```

**部署特性：**

* **持久化 URL** — `https://zeus-{session_id[:8]}.style.dev`
* **自动构建** — Freestyle 自动检测框架（Next.js / Vite），执行 build
* **域名复用** — 同一 session 多次部署更新同一域名的 domain mapping
* **零配置** — 不需要用户提供额外 Token 或服务器信息

### website\_eslint

检查 Web 项目的代码质量。

| 参数           | 类型                 | 默认值    | 说明                  |
| ------------ | ------------------ | ------ | ------------------- |
| `file_paths` | list\[str] \| null | `null` | 要检查的文件路径（为空则检查整个项目） |

**检查内容：**

1. **TypeScript 类型检查** — `tsc --noEmit --pretty`
2. **ESLint 检查** — `next lint`

返回错误数、警告数和详细诊断信息。

***

## 部署体系

Zeus 支持三种部署目标，通过统一的 Deploy API 管理：

| 目标            | 端点                       | 特点                 | 用户需提供        |
| ------------- | ------------------------ | ------------------ | ------------ |
| **Freestyle** | `POST /deploy/freestyle` | 持久化 URL，亚秒级部署，自动构建 | 无（零配置）       |
| **Vercel**    | `POST /deploy/vercel`    | 生产级托管              | Vercel Token |
| **Server**    | `POST /deploy/server`    | 自定义服务器，Docker 部署   | SSH 信息       |

### Freestyle 部署

Freestyle 是默认的部署目标，提供：

* **亚秒级部署** — API-first 设计，从调用到上线 \< 1 秒
* **自动框架检测** — 支持 Next.js、Vite、Expo 等
* **自动 SSL** — `*.style.dev` 域名自带 HTTPS
* **域名映射** — 同一域名可指向不同的 deployment（更新时创建新 deployment，自动重映射域名）

**API 调用示意：**

```python theme={null}
async with httpx.AsyncClient() as client:
    response = await client.post(
        "https://api.freestyle.sh/web/v1/deployment",
        headers={
            "Authorization": f"Bearer {FREESTYLE_API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "source": {
                "kind": "files",
                "files": files_dict,  # {相对路径: 文件内容}
            },
            "config": {
                "domains": ["zeus-abc12345.style.dev"],
                "build": True,
            },
        },
    )
```

### 部署流程（全景）

```mermaid theme={null}
flowchart TD
    trigger["用户点击部署 / Agent 调用 website_deploy"]
    
    trigger --> collect["从沙盒收集项目文件"]
    collect --> exclude["排除 node_modules / .next / .git / dist"]
    exclude --> dict["构建 files_dict: path → content"]
    
    dict --> freestyle["Freestyle API<br/>POST /web/v1/deployment"]
    freestyle --> build["Freestyle 自动检测框架并构建"]
    build --> domain["域名映射<br/>zeus-xxx.style.dev → deployment"]
    domain --> url["返回持久化 URL"]
    url --> notify["SSE deploy_complete 事件通知前端"]
```

***

## 预览 URL vs 部署 URL

| 维度   | 沙盒预览 URL                               | Freestyle 部署 URL                       |
| ---- | -------------------------------------- | -------------------------------------- |
| 格式   | 取决于 Provider（如 `https://{id}.e2b.app`） | `https://zeus-{session[:8]}.style.dev` |
| 生命周期 | 沙盒存活期间（最长 1 小时）                        | 持久化，直到手动删除                             |
| 用途   | 开发时实时预览                                | 分享、展示、生产使用                             |
| 更新方式 | HMR 自动刷新                               | 需重新部署                                  |
| 性能   | 开发模式（较慢）                               | 生产构建（优化后）                              |

***

## 配置

### 环境变量

| 变量                       | 描述                          | 默认值                                   |
| ------------------------ | --------------------------- | ------------------------------------- |
| `FREESTYLE_API_KEY`      | Freestyle API 密钥（部署必需）      | —                                     |
| `SANDBOX_PROVIDER`       | 沙盒 Provider 类型              | `e2b`                                 |
| `SANDBOX_TIMEOUT`        | 沙盒超时时间（秒）                   | `3600`                                |
| `E2B_API_KEY`            | E2B API 密钥（E2B Provider 必需） | —                                     |
| `E2B_SANDBOX_TEMPLATE`   | E2B 模板名称                    | `zeus-nextjs`                         |
| `OPENSANDBOX_SERVER_URL` | OpenSandbox Server 地址       | `http://localhost:8000`               |
| `OPENSANDBOX_IMAGE`      | OpenSandbox 沙盒镜像            | `opensandbox/code-interpreter:v1.0.1` |

### 获取 Freestyle API Key

1. 访问 [admin.freestyle.sh](https://admin.freestyle.sh/) 注册账号
2. 在 Dashboard 中获取 API Key
3. 添加到 `apps/ai-backend/.env`：

```bash theme={null}
FREESTYLE_API_KEY=your_api_key_here
```

### 免费额度

| 项目    | 免费额度    |
| ----- | ------- |
| 并发 VM | 10      |
| 域名数   | 5       |
| 仓库数   | 500     |
| 部署次数  | 500 次/月 |

***

## 使用场景

| 场景    | 工具链                                                            |
| ----- | -------------------------------------------------------------- |
| 快速原型  | `website_init` → AI 编写代码 → 实时预览 → `website_deploy`             |
| 落地页制作 | `website_init` → AI 生成页面 → `website_eslint` → `website_deploy` |
| 组件演示  | `website_init` → AI 编写组件 → 分享 `*.style.dev` URL                |
| 迭代开发  | 开发预览 → 修改代码 → `website_eslint` 检查 → 重新部署（URL 不变）               |