# 使用 AI Agent 开发和部署站点

星图站点空间将 UCloud Sandbox 与 AI Agent 结合，您可以直接用自然语言描述需求，让 Codex、Claude Code 或 OpenCode 等 Agent 在云端站点中生成代码、安装依赖、启动服务并完成部署。

适合的场景包括：

- 仪表盘、数据大屏和运营看板
- 展示页、工具页和其他 Web 站点
- 基于星图管理 API 的模型用量、请求日志或账单数据面板
- 贪吃蛇等轻量互动游戏

> 本页中的站点 ID 使用 `site_<sandbox-id>` 作为占位符。站点 ID 同时是只能访问该站点的受限凭证，请勿将真实值写入代码仓库、截图或公开内容。

## 前置准备

开始前，请确保本机已安装：

- Node.js 和 `npx`，用于安装 Agent skill
- 一款支持 skill 的 AI Agent，例如 Codex、Claude Code 或 OpenCode

## 第一步：创建站点

登录星图平台，进入站点管理页面，点击创建站点。根据页面提示填写站点信息并完成创建。

![在星图平台创建站点](https://cdnv2-cache.udelivrs.com/2026/07/308fbd6a0e116a012c6b27bd5fe0da50_1784874571993.png)

## 第二步：获取远程开发指引

站点创建成功后，在站点列表中找到目标站点，点击【远程开发】。

![在站点列表中选择远程开发](https://cdnv2-cache.udelivrs.com/2026/07/989a34a3eb3421536f4fd20ca1519017_1784874699489.png)

页面会显示当前站点的连接方法和站点 ID。后续需要将这个站点 ID 提供给本地 AI Agent。

![查看 AI Agent 连接站点的指引](https://cdnv2-cache.udelivrs.com/2026/07/f02ac5652d3b0bba9ad8473e5591338d_1784874767513.png)

## 第三步：准备本地开发目录

在本机新建一个独立的开发目录，并进入该目录：

```bash
mkdir -p /path/to/site-dev
cd /path/to/site-dev
```

> 请将 `/path/to/site-dev` 替换为您实际使用的目录。建议为每个站点使用独立目录，避免 Agent 误读或修改其他项目。

## 第四步：安装 Agent skill

在开发目录中执行：

```bash
npx skills add ucloud/ucloud-sandbox-cli -s astraflow-api -s ucloud-sandbox-site
```

该命令会安装两个 skill：

| Skill | 用途 |
| --- | --- |
| `ucloud-sandbox-site` | 连接站点空间、管理文件、生成代码、启动服务和部署站点 |
| `astraflow-api` | 调用星图管理 API，查询模型、请求日志、账单和订单等数据 |

## 第五步：让 AI Agent 连接站点

在当前目录启动您使用的 Agent。例如，启动 Codex：

```bash
codex
```

在 Agent 中输入以下提示词，并将占位符替换为【远程开发】页面显示的站点 ID：

```text
连接星图站点 site_<sandbox-id>
```

Agent 会根据 skill 指引完成 CLI 检查、站点身份校验和连接测试。当 Agent 确认连接成功后，即可继续描述站点需求。

## 第六步：描述您的站点需求

连接成功后，您可以直接使用自然语言提出需求。例如：

```text
帮我开发一个贪吃蛇小游戏。
```

可以在首次提示中一次说清页面用途、目标用户、期望风格、数据来源和主要交互，便于 Agent 更准确地完成开发。

Agent 会完成代码生成、依赖安装、构建、服务启动和访问验证。正常情况下，您无需手动执行这些步骤；如果 Agent 请求确认覆盖文件、删除内容或执行其他高风险操作，请在确认影响范围后再授权。

## 使用星图管理 API 构建数据面板

如果站点需要展示您账号下的模型用量、推理请求日志或账单等数据，可以让 Agent 通过 `astraflow-api` skill 调用星图管理 API。

### 1. 获取 UCloud API 密钥

前往 [UCloud API 密钥管理](https://console.ucloud.cn/uapi/apikey)创建或查看 `PublicKey` 和 `PrivateKey`。

> 这里使用的是 UCloud 账号级 `PublicKey`/`PrivateKey`，用于星图管理 API 的签名认证；它们不是站点 ID，也不是调用大模型时使用的 Bearer API Key。

### 2. 配置站点环境变量

创建或编辑站点时，在环境变量区域添加：

| 变量名 | 值 |
| --- | --- |
| `UCLOUD_PUBLIC_KEY` | UCloud API 公钥 |
| `UCLOUD_PRIVATE_KEY` | UCloud API 私钥 |

![为站点配置 UCloud API 公钥和私钥](https://cdnv2-cache.udelivrs.com/2026/07/b39d1ced7c77a4a72fe1fa5f16f30ff4_1784875213941.png)

> `UCLOUD_PRIVATE_KEY` 是高度敏感的凭证。只通过站点环境变量注入，不要将它写入提示词、前端代码、代码仓库或日志。前端页面不应直接持有或使用私钥；应由站点后端读取环境变量、计算签名并调用 API。

星图管理 API 通常还需要业务地域 `Region` 和项目 ID `ProjectId`。您可以在提示词中告诉 Agent 实际值，或另行将它们配置为站点环境变量。如果不确定应使用哪个值，可让 Agent 先查询可用地域和项目列表；子账号必须提供 `ProjectId`。

### 3. 连接站点和星图 API

重新打开 Agent 时，可以使用以下提示词：

```text
连接星图站点 site_<sandbox-id>，使用站点环境变量 UCLOUD_PUBLIC_KEY 和 UCLOUD_PRIVATE_KEY 连接星图管理 API。不要输出、记录或将密钥发送到前端。
```

连接后，即可提出数据面板需求。例如：

```text
请调用星图管理 API，开发一个面板页面，展示今天的模型消费情况，包括模型名称、请求数和消费趋势。请以 API 实际返回的日志或账单字段为准，对空数据和调用失败提供友好提示。
```

## 访问已部署的站点

Agent 完成部署后，会在站点内验证服务，并返回实际访问地址。在浏览器中打开该地址即可访问页面。

部署成功后，星图控制台中的站点状态会变为【已上线】，您也可以直接从控制台打开站点地址。

![站点状态为已上线](https://cdnv2-cache.udelivrs.com/2026/07/cc97c35e0d71392b8f05241517d3311e_1784876037302.png)

> 如果 Agent 返回了地址，但页面无法打开，请让 Agent 继续检查服务进程、80 端口、监听地址和服务日志，并在站点内访问成功后再确认部署完成。