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. 启动前端

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：

# 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

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

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

# macOS
brew install cloudflared

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

一键启动穿透

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

cd art-agent
.\start-tunnel.ps1

脚本会自动：

为后端和前端各创建一条穿透隧道
更新 frontend/.env.local 中的后端 API 地址为穿透地址
打印手机可访问的公网 HTTPS 链接
关闭脚本时（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 等），在运行脚本前设置：

$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）

README.md Unescape Escape

EPEEKit

快速开始

1. 准备 API Key

2. 启动后端