# Local Codex + MCP Image Agent Demo

这是一个本地运行的图片生成 Demo，完整调用链为：

`React → FastAPI → Codex CLI → STDIO MCP generate_image → OpenAI-compatible 中转 API → 本地存储`

项目只包含单用户本地原型需要的功能：提交提示词、异步查询状态、预览和下载图片。它不包含登录、计费、历史记录、图片编辑或多用户并发。

## 环境要求

- Python 3.13+
- Node.js 20+
- 已安装并登录的 Codex CLI
- 支持 `POST /images/generations` 的 OpenAI-compatible 图片中转 API

## 安装

在项目根目录执行：

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
Copy-Item .env.example .env
```

编辑 `.env`，至少填写：

```dotenv
IMAGE_API_BASE=https://relay.example.com/v1
IMAGE_API_KEY=your-local-key
IMAGE_MODEL=gpt-image-2
```

真实 `.env` 已被 Git 忽略。不要把 Key 写进 `.codex/config.toml`、前端代码或日志。

安装前端依赖：

```powershell
Set-Location frontend
npm install
Set-Location ..
```

## 分层验证

先绕过 Codex 和 MCP 验证中转 API：

```powershell
python scripts/test_relay_api.py
```

成功后，图片会保存到 `data/generated/test-output.<格式>`。

项目级 `.codex/config.toml` 已配置 `image_generator` STDIO MCP。项目被 Codex 信任并激活虚拟环境后，可检查连接：

```powershell
codex mcp list
codex
```

进入 Codex TUI 后使用 `/mcp`，确认存在 `image_generator` 和 `generate_image`。也可以要求：

```text
使用 image generator MCP 工具生成一张蓝白色科技风海报。
```

## 启动

终端一，启动后端：
# 激活后，提示符前会出现 (.venv)
python -m pip install -e ".[dev]"

# 启动后端
python -m uvicorn backend.app.main:app --host 127.0.0.1 --port 8000 --reload
```powershell
python -m uvicorn backend.app.main:app --host 127.0.0.1 --port 8000 --reload
```

终端二，启动前端：
Set-Location d:\project\image-2-Agent\frontend
```powershell
Set-Location frontend
npm run dev
```

浏览器打开 `http://127.0.0.1:5173`。

## API

- `POST /api/generations`：创建任务，返回 `job_id`
- `GET /api/generations/{job_id}`：查询任务状态
- `GET /api/images/{image_id}`：预览图片
- `GET /api/images/{image_id}/download`：下载图片
- `GET /api/health`：健康检查

任务状态保存在内存中，服务重启后会丢失。图片和元数据分别保存在 `data/generated` 与 `data/results`。

## 测试与构建

```powershell
pytest
Set-Location frontend
npm run build
```

Provider 和后端测试全部使用 mock，不会请求真实中转 API，也不会产生图片费用。真实端到端测试必须由本机已登录的 Codex 和有效中转 Key 完成。

## 常见错误

- `codex_not_found`：后端账号找不到 Codex CLI。
- `codex_not_authenticated`：先在同一操作系统账号下登录 Codex。
- `mcp_unavailable`：检查虚拟环境、项目信任和 `.codex/config.toml`。
- `provider_auth_failed`：检查 API Base、Key 和模型别名。
- `provider_rate_limited`：请求过于频繁，稍后重试。
- `provider_quota_exhausted`：中转 API 免费额度已用完，请充值或更换模型。
- `provider_unavailable`（no_available_channel）：免费模型通道暂不可用，可改用 `gpt-image-2` 或稍后重试。
- `provider_auth_failed`：检查 API Key 是否来自当前平台，修改 `.env` 后需重启后端。
- `provider_timeout`：提高 `IMAGE_API_TIMEOUT_SECONDS` 或检查中转服务。
- `tool_not_called`：Codex 没有实际调用 `generate_image`，结果会被拒绝。
- `mcp_tool_cancelled` / `user cancelled MCP tool call`：Codex `exec` 在 `read-only` 沙箱下会取消 MCP 工具调用。将 `.env` 中 `CODEX_SANDBOX` 设为 `danger-full-access`。
- `provider_invalid_response`（404 Invalid URL）：`IMAGE_API_BASE` 应填写到 `/v1`，不要包含 `/images/generations`。