ai-image

验收记录与当前限制见 docs/acceptance.md。

AI 绘图聚合服务。对外提供统一的多供应商生图能力（文生图 / 图生图），内置 Web 控制台，Agent 可通过 REST API 或 MCP 调用。

---

一、快速开始

pip install -r requirements.txt

# 启动（Web + REST + MCP 同端口）
python main.py

# 仅 MCP stdio（给 MCP 客户端当子进程用）
python main.py --stdio

打开 http://127.0.0.1:8765/ 即可进入控制台。

首次使用：进入「供应商」页填写上游的 Base URL 与 API Key → 「拉取模型」→ 勾选含 image 的模型保存 → 到「出图」页输入提示词出图。

---

二、当前状态（v2 · 已落地）

技术栈

层	选型
Web 框架	FastAPI
前端	原生 HTML/CSS/JS 静态页（web/），与后端同端口同源
持久化	SQLite（标准库 sqlite3）
HTTP 客户端	httpx
密钥加密	cryptography / Fernet
MCP	fastmcp（stdio + streamable HTTP）
部署	Docker / docker-compose

目录结构

main.py                     入口：REST + Web + MCP
app/
  config.py                 路径与运行配置
  db.py                     SQLite 连接与建表
  security.py               密钥加解密与掩码
  schemas.py                Pydantic 请求模型
  providers/
    base.py                 适配器基类与能力声明
    openai_compat.py        OpenAI 兼容网关
    agnes.py                Agnes 原生协议
    __init__.py             适配器注册表
  services/
    providers.py            供应商 / 模型 CRUD 与模型发现
    generation.py           出图、落盘、记录
    gallery.py              output/ 扫描
    skill_doc.py            SKILL.md 读取
  routers/
    api_providers.py        供应商与模型 API
    api_models.py
    api_generate.py
    api_gallery.py
    api_skills.py
  mcp_server.py             MCP 工具
web/                        前端静态页
data/                       SQLite + 密钥文件（不入库）
output/                     图片输出（画廊数据源）
SKILL.md                    Agent 使用说明

Web 控制台

页面	文件	功能
出图	web/create.html	输入提示词、选供应商与模型、选尺寸与数量，直接出图
画廊	web/index.html	按画廊（profile）浏览、搜索、进入查看、删除
生成记录	web/records.html	查看历史生成任务与失败原因
供应商	web/providers.html	增删改供应商、拉取上游模型、勾选启用
模型	web/models.html	跨供应商查看模型、启用 / 停用
SKILL.md	web/skills.html	在线查看 Agent 使用说明

前端只有一层数据出入口 web/api.js，全部走真实 REST；无 mock 数据。

---

三、核心机制

统一参数体系

所有供应商收敛到同一套入参，内部再翻译成各上游格式：

入参	类型	说明
provider_id	str	供应商 ID，界面创建时自定义
model	str	模型 ID，来自上游模型列表
prompt	str	提示词
size	str	统一 WxH 像素，如 1024x1024；也接受 1K/2K/3K/4K
ratio	str	仅 Agnes 支持，如 16:9；省略时从 size 推导
n	int	生成数量（1~4）
images	list[str]	图生图参考图（URL 或 Data URI），仅部分供应商支持
profile_name	str	调用方标识，用于输出目录隔离

适配器声明自身能力（supports_image_input、size_hint、kind），服务端据此校验，避免把不支持的参数透传给上游。

数据模型（SQLite）

providers

字段	类型	说明
id	TEXT PK	用户自定义唯一标识
name	TEXT	显示名
adapter	TEXT	openai_compat / agnes
base_url	TEXT	上游地址
api_key	TEXT	上游密钥（Fernet 加密存储，接口返回掩码）
default_model	TEXT	默认模型
enabled	INTEGER	是否启用
note	TEXT	备注
created_at / updated_at	TEXT	时间戳

models

字段	类型	说明
id	TEXT PK	provider_id:model_id
provider_id	TEXT	外键（ON DELETE CASCADE）
model_id	TEXT	上游模型标识
display_name	TEXT	显示名
enabled	INTEGER	是否对外暴露
kind	TEXT	类型（image）
size_hint	TEXT	尺寸提示
supports_image_input	INTEGER	是否支持参考图
note	TEXT	备注
discovered_at	TEXT	最近一次发现时间

generations

字段	类型	说明
id	TEXT PK	任务 ID
provider_id / provider_name	TEXT	实际使用的供应商
model	TEXT	模型
profile_name	TEXT	调用方
prompt	TEXT	提示词
size / ratio / n	—	入参快照
status	TEXT	success / failed
error	TEXT	失败原因
files	TEXT(JSON)	落盘文件名列表
duration_ms	INTEGER	耗时
created_at	TEXT	时间戳

模型发现

用户在界面填完 API Key 与 Base URL 后点击「拉取模型」，服务端请求上游 GET {base_url}/models，筛选规则：模型 ID 转小写后包含 image。命中的模型写入 models 表并标记 discovered_at，用户可勾选哪些对外启用（未勾选的自动停用）。拉取失败不阻塞保存，仅提示错误。

两种适配器的发现与出图路径：

适配器	模型发现	出图
openai_compat	GET /models	POST /images/generations（data[0].b64_json 或 data[0].url）
agnes	GET /models	POST /images/generations（size 档位 + ratio，response_format 放在 extra_body 内）

画廊

output/ 目录即画廊数据源：

output/
├── slime-fellowship/   ← 一个画廊（profile_name）
│   ├── gpt-image-2-1K-0014ef2b.png
│   └── ...
├── smoke-gpt-1/
└── user/               ← 网页端手动出图（固定 profile_name = user）

目录名语义 = 谁生成的图片：Agent 调用时由调用方指定 profile_name（默认 agent），网页端手动出图固定 user；目录不存在时后端自动创建。

接口	说明
GET /api/galleries	画廊列表：名称、图片数、占用空间、更新时间、封面、涉及的模型
GET /api/galleries/{profile}	某个画廊内的图片（含模型、供应商、时间）
DELETE /api/galleries/{profile}/{filename}	删除单张（物理删除 + 同步 generations 记录）

MCP 对接

Agent 侧可用工具：

工具	说明	顺序
list_providers	列出可用供应商及其启用模型数	1
discover_models	拉取指定供应商的上游模型，返回 { provider_id, total, matched }	2（必做）
generate_image	出图（文生图 / 图生图）	3
list_generations	查询生成记录	可选
get_skill_doc	获取最新版 SKILL.md 内容	任意时刻

MCP 只暴露用户在界面中启用的供应商，不泄露未启用配置与密钥。

Agent 强制流程：list_providers() → discover_models(provider_id) → 用返回的 matched 出图。

matched 为空时，Agent 必须直接结束并回复「没找到有效的模型」，不得猜测模型名、不得调用出图接口。

SKILL.md

GET /api/skills 返回 SKILL.md 内容（JSON）或原文（/api/skills/raw，text/markdown）。页面提供在线查看，Agent 通过 MCP 工具 get_skill_doc 拉取。

SKILL.md 中不写任何固定模型名称：只描述「先拉模型、再出图」的流程与参数说明，模型清单一律来自 discover_models 的实时返回。

---

四、接口清单

方法	路径	说明
GET	/health	健康检查
GET	/api/providers	供应商列表（密钥掩码）
POST	/api/providers	新增 / 更新供应商（api_key 留空表示不修改）
DELETE	/api/providers/{id}	删除供应商及其模型
POST	/api/providers/discover	手填 Base URL + Key 临时拉模型
POST	/api/providers/{id}/discover	按已保存供应商拉模型并写库
POST	/api/providers/{id}/models	保存勾选的模型，未勾选的自动停用
GET	/api/models	模型列表（可 ?provider_id=）
PATCH	/api/models/{id}	启用 / 停用单个模型
POST	/api/models/bulk	批量启用 / 停用
POST	/api/generate	出图
GET	/api/generations	生成记录
GET	/api/galleries	画廊列表
GET	/api/galleries/{profile}	画廊内图片
DELETE	/api/galleries/{profile}/{filename}	删除图片
GET	/api/skills	SKILL.md（JSON）
GET	/api/skills/raw	SKILL.md 原文（markdown）
GET	/output/{profile}/{filename}	图片访问
POST	/mcp	MCP streamable HTTP

---

五、配置

.env（参考 .env.example）：

变量	默认值	说明
AI_IMAGE_HOST	127.0.0.1	监听地址
AI_IMAGE_PORT	8765	监听端口
AI_IMAGE_DATA_DIR	data	SQLite 与密钥文件目录
AI_IMAGE_OUTPUT_DIR	output	图片输出根目录
AI_IMAGE_SECRET_KEY	自动生成	密钥加密主密钥，不填则落 data/secret.key

供应商的 API Key 与 Base URL 不再走环境变量，在控制台填写，服务端加密后存 SQLite。

---

六、部署

docker compose up -d

宿主机 output/ 与 data/ 挂载进容器，端口映射 8765:8000。

---

七、MCP 客户端接入

config.json 示例：

{
  "mcpServers": {
    "ai-image": {
      "command": "python",
      "args": ["d:\\source\\MyProject\\ai-image\\main.py", "--stdio"],
      "cwd": "d:\\source\\MyProject\\ai-image",
      "env": {}
    }
  }
}

也可用 streamable HTTP 直连：http://127.0.0.1:8765/mcp。

八、测试

# 后端回归：标准库 unittest，无需额外测试框架
python -m unittest discover -s tests -p test_app.py -v

# 完整验收：包含 Chromium 浏览器交互、桌面/移动布局、MCP HTTP/stdio
pip install -r requirements-dev.txt
python -m playwright install chromium
python -m unittest discover -s tests -v

测试使用临时目录、独立 SQLite、虚拟密钥和本地模拟上游，不读取现有数据库或调用付费生图服务。 浏览器测试会启动临时本地服务，结束后关闭服务并清除临时数据。