# EPEEKit

AI 美术资源生成工具集 — 通过对话生成游戏美术资源。

## 快速开始

### 1. 准备 API Key

你需要两个 API Key：

- **OpenAI API Key**（或兼容 API）：https://platform.openai.com/api-keys
- **Replicate API Token**：https://replicate.com/account/api-tokens

### 2. 启动后端

```bash
cd art-agent/backend

# 创建虚拟环境（推荐）
python -m venv venv
venv\Scripts\activate      # Windows
# source venv/bin/activate  # macOS/Linux

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
copy .env.example .env
# 编辑 .env，填入你的 API Key 和模型配置

# 启动（--host 0.0.0.0 允许局域网/穿透访问）
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### 3. 启动前端

```bash
cd art-agent/frontend

# 安装依赖（需要 Node.js >= 18）
npm install

# 启动
npm run dev
```

### 4. 使用

打开浏览器访问 http://localhost:3000

- 输入文字描述你想要的美术资源
- 可以上传参考图引导风格
- 生成的图片可以点击"保存"按钮下载
- 持续对话进行迭代修改

## 访问地址

| 场景 | 前端页面 | 后端 API | 后端文档 |
|------|---------|---------|---------|
| **本机** | http://localhost:3000 | http://localhost:8000 | http://localhost:8000/docs |
| **局域网**（同一 WiFi） | `http://<你的IP>:3000` | `http://<你的IP>:8000` | `http://<你的IP>:8000/docs` |
| **外网**（Cloudflare Tunnel） | `https://xxx.trycloudflare.com`（每次启动不同） | `https://yyy.trycloudflare.com` | — |

查看本机局域网 IP：

```powershell
# Windows
Get-NetIPAddress -AddressFamily IPv4 | Where-Object { $_.InterfaceAlias -eq 'WLAN' }

# macOS / Linux
ifconfig | grep "inet " | grep -v 127.0.0.1
```

## 配置说明

所有可配置项都集中在 `backend/.env` 文件中，分为以下几组：

| 配置组 | 变量 | 说明 |
|--------|------|------|
| **LLM 对话** | `OPENAI_API_KEY` | API 密钥 |
| | `OPENAI_BASE_URL` | API 基地址，支持任何 OpenAI 兼容 API |
| | `LLM_MODEL` | 模型名称，如 `gpt-4o-mini`、`deepseek-chat` 等 |
| | `LLM_MAX_ITERATIONS` | Agent 单轮最大工具调用次数 |
| **图像生成** | `REPLICATE_API_TOKEN` | Replicate API Token |
| | `IMAGE_MODEL` | 图像生成模型，如 `black-forest-labs/flux-schnell` |
| | `IMAGE_ASPECT_RATIO` | 默认宽高比，如 `1:1` |
| | `IMAGE_OUTPUT_FORMAT` | 输出格式，如 `png` |
| **网络** | `HTTP_PROXY` / `HTTPS_PROXY` | 代理配置 |
| **服务** | `PORT` | 后端服务端口 |

切换 LLM 供应商只需修改 `OPENAI_BASE_URL` + `OPENAI_API_KEY` + `LLM_MODEL` 三个值。

## 项目结构

```
art-agent/
  backend/           # Python FastAPI 后端
    app/
      main.py        # 入口
      config.py      # 集中配置（读取 .env）
      api/chat.py    # 对话 API
      agent/         # Agent Loop 核心
      services/      # AI 服务封装
  frontend/          # Next.js 前端
    src/
      app/           # 页面
      components/    # UI 组件
      lib/           # 工具函数
  docs/              # 文档
```

## 远程访问（外网穿透）

通过 Cloudflare Quick Tunnel 免费穿透内网，手机或朋友在任何网络下都能访问，无需买服务器。

### 安装 cloudflared

```powershell
# Windows（任选一种）
winget install Cloudflare.cloudflared

# 或手动下载
# https://github.com/cloudflare/cloudflared/releases/latest
# 下载 cloudflared-windows-amd64.exe，放到项目目录下即可
```

```bash
# macOS
brew install cloudflared

# Linux
# https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/
```

### 一键启动穿透

确保前后端服务已经在运行，然后在另一个终端执行：

```powershell
cd art-agent
.\start-tunnel.ps1
```

脚本会自动：
1. 为后端和前端各创建一条穿透隧道
2. 更新 `frontend/.env.local` 中的后端 API 地址为穿透地址
3. 打印手机可访问的公网 HTTPS 链接
4. 关闭脚本时（Ctrl+C）自动恢复 `.env.local` 为 localhost

> **重要**：穿透启动后需要**重启前端** (`npm run dev`) 才能读取新的 `.env.local`。

### 穿透管理

| 操作 | 方式 |
|------|------|
| **启动** | 运行 `.\start-tunnel.ps1`，等待打印出两条 `trycloudflare.com` 地址 |
| **停止** | 在脚本窗口按 `Ctrl+C`，或在任务管理器中结束 `cloudflared.exe` 进程 |
| **查看状态** | 检查日志：`Get-Content $env:TEMP\epeekit-tunnel-backend.log` |
| **重启** | 先停止再启动，地址会变（Quick Tunnel 每次分配随机域名） |

### 注意事项

- Quick Tunnel **免费无需账号**，但地址每次启动都会变化
- 如果 cloudflared 连接超时，可能需要配置代理（Clash 等），在运行脚本前设置：
  ```powershell
  $env:HTTP_PROXY = "http://127.0.0.1:7890"
  $env:HTTPS_PROXY = "http://127.0.0.1:7890"
  .\start-tunnel.ps1
  ```
- 电脑关机、休眠或代理断开后隧道会自动失效
- 停止穿透后，`start-tunnel.ps1` 会自动将 `.env.local` 恢复为 `localhost`；如果手动杀进程，需要自行恢复

## 技术栈

- 前端：Next.js + TypeScript + Tailwind CSS
- 后端：Python FastAPI + SSE
- AI：可配置 LLM（默认 GPT-4o-mini）+ 可配置图像模型（默认 Replicate Flux）