ai-image/SKILL.md

ai-image

绘图聚合服务。通过 REST API 或 MCP 调用任意已接入的生图上游。

服务地址

• Web 控制台 + REST：http://127.0.0.1:8765/
• MCP（streamable HTTP）：http://127.0.0.1:8765/mcp
• MCP（stdio 子进程）：python main.py --stdio

调用流程（必须按顺序）

1. list_providers() —— 列出可用供应商及其已启用模型数。
2. discover_models(provider_id) —— 必做，拉取指定供应商的上游模型清单。 返回 {provider_id, total, matched}，matched 是模型 ID 转小写后包含 image 的集合。
3. generate_image(...) —— 出图，model 必须取自上一步的 matched。

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

MCP 工具

工具	参数	说明
list_providers	—	第 1 步，列出可用供应商
discover_models	provider_id	第 2 步（必做），返回 {provider_id, total, matched}
generate_image	provider, model, prompt, size, ratio, n, images, profile_name	第 3 步，出图
list_generations	limit	查询最近生成记录
get_skill_doc	—	获取本文件最新内容

REST 端点

方法	路径	说明
GET	/health	健康检查
GET	/api/providers	供应商列表（密钥掩码）
POST	/api/providers	新增 / 更新供应商
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	本文件内容

出图参数

参数	类型	说明
provider / provider_id	str	供应商 ID，来自 list_providers
model	str	模型 ID，来自 discover_models 的 matched
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	画廊标识；建议显式传调用 Agent 的名称，例如 codex，决定落盘目录

落盘规则

图生图通过 REST/MCP 的 images 字段传入参考图。以下 REST 示例中的供应商和模型 须替换为发现接口返回且已启用的值；仅支持参考图的适配器（如 Agnes）可用：

{
  "provider_id": "<provider_id>",
  "model": "<discovered_model_id>",
  "prompt": "保留参考图的构图，调整为水彩风格",
  "size": "1024x1024",
  "n": 1,
  "images": ["https://example.com/reference.png"],
  "profile_name": "codex"
}

output/
└── <profile_name>/        ← 目录名 = 谁生成的图片
    ├── <model>-<id>.png
    └── ...

• 网页端手动出图固定 profile_name = user → output/user/
• Agent 调用时建议显式将 profile_name 设为自己的名称（例如 codex），图片进入同名画廊。
• 服务端不会自动识别 Agent 身份；省略 profile_name 时 MCP 使用通用默认值 agent，它不代表具体 Agent 的名字。
• 目录不存在时后端自动创建
• 允许字符：字母、数字、下划线、短横线（1~64 位）

异常处理

• matched 为空 → 回复「没找到有效的模型」，停止流程。
• 上游返回 4xx/5xx → 出图工具返回 {status: "failed", error: "..."}，把错误原样告知用户，不要重试伪造结果。
• 供应商未配置密钥 → 先用 list_providers 确认该供应商存在，再提示用户在控制台「供应商」页填写。

模型清单

本文件不包含任何固定模型名。可用模型一律来自 discover_models 的实时返回， 上游上下线模型不会让文档失效。