mcp-duojie-image 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,62 @@
+# mcp-duojie-image
+
+MCP server for image generation via duojie.games API (Gemini 3.1 Flash Image).
+
+## Features
+
+- Text-to-image generation
+- Image-to-image with reference images
+- Automatic file saving with conflict handling
+- Configurable output format and size
+
+## Installation
+
+```bash
+npx mcp-duojie-image
+```
+
+## Configuration
+
+Set environment variable:
+
+```bash
+export DUOJIE_API_KEY=sk-your-key-here
+```
+
+Or configure in MCP client (e.g., Claude Desktop):
+
+```json
+{
+  "mcpServers": {
+    "duojie-image": {
+      "command": "npx",
+      "args": ["-y", "mcp-duojie-image"],
+      "env": {
+        "DUOJIE_API_KEY": "sk-your-key-here"
+      }
+    }
+  }
+}
+```
+
+## Usage
+
+The server provides one tool: `generate_image`
+
+**Required parameters:**
+- `prompt`: Image description
+- `output_dir`: Output directory path
+- `output_filename`: Output filename (extension optional)
+
+**Optional parameters:**
+- `reference_images`: Array of local image paths for reference
+- `size`: "512px" | "1K" | "2K" | "4K"
+- `aspect_ratio`: e.g., "16:9"
+- `format`: Output format (default: "png")
+- `model`: Model override
+- `overwrite`: Overwrite existing file (default: false)
+- `negative_prompt`: What to avoid in the image
+
+## License
+
+MIT

package/dist/config.js

@@ -4,20 +4,15 @@ export function maskKey(key) {
         return "***";
     return `${key.slice(0, 6)}...${key.slice(-4)}`;
 }
-function getArg(name) {
-    const flag = `--${name}=`;
-    const arg = process.argv.find((a) => a.startsWith(flag));
-    return arg ? arg.slice(flag.length) : undefined;
-}
-export function loadConfig() {
-    const apiKey = getArg("api-key") ?? process.env.DUOJIE_API_KEY ?? "";
+export function loadConfig(overrides) {
+    const apiKey = overrides?.apiKey ?? process.env.DUOJIE_API_KEY ?? "";
     if (!apiKey) {
-        throw new AppError("E_CONFIG_MISSING_KEY", "--api-key is required");
+        throw new AppError("E_CONFIG_MISSING_KEY", "DUOJIE_API_KEY is not set");
     }
     return {
         apiKey,
-        baseUrl: getArg("base-url") ?? process.env.DUOJIE_BASE_URL ?? "https://api.duojie.games",
-        model: getArg("model") ?? process.env.DUOJIE_IMAGE_MODEL ?? "gemini-3.1-flash-image",
+        baseUrl: overrides?.baseUrl ?? process.env.DUOJIE_BASE_URL ?? "https://api.duojie.games",
+        model: overrides?.model ?? process.env.DUOJIE_IMAGE_MODEL ?? "gemini-3.1-flash-image",
         timeoutMs: 60_000,
     };
 }

package/dist/saver.js

@@ -14,8 +14,11 @@ export function saveImage(imageBuffer, opts) {
     const base = extname(outputFilename) ? basename(outputFilename, ext) : outputFilename;
     let finalPath = join(absDir, `${base}${ext}`);
     if (!overwrite && existsSync(finalPath)) {
-        const ts = new Date().toISOString().replace(/[-:T]/g, "").slice(0, 15);
-        finalPath = join(absDir, `${base}_${ts}${ext}`);
+        let counter = 1;
+        do {
+            finalPath = join(absDir, `${base}_${counter}${ext}`);
+            counter++;
+        } while (existsSync(finalPath));
     }
     try {
         writeFileSync(finalPath, imageBuffer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-duojie-image",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MCP server for image generation via duojie.games",
   "type": "module",
   "main": "dist/index.js",
@@ -12,14 +12,17 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "test": "vitest run",
-    "lint": "tsc --noEmit"
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
   },
-  "keywords": ["mcp", "image-generation", "gemini", "ai"],
+  "keywords": [
+    "mcp",
+    "image-generation",
+    "gemini",
+    "ai"
+  ],
   "author": "",
   "license": "MIT",
-  "engines": {
-    "node": ">=18.0.0"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.23.8"
@@ -29,5 +32,11 @@
     "tsx": "^4.19.0",
     "typescript": "^5.5.0",
     "vitest": "^2.0.0"
-  }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist"
+  ]
 }

package/.env.example

@@ -1,6 +0,0 @@
-# API key (required)
-DUOJIE_API_KEY=sk-your-key-here
-
-# Optional overrides
-# DUOJIE_BASE_URL=https://api.duojie.games
-# DUOJIE_IMAGE_MODEL=gemini-3.1-flash-image

package/AGENTS.md

@@ -1,66 +0,0 @@
-# Repository Guidelines
-
-## 基础规则
-- 说中文
-
-## Project Structure & Module Organization
-This repository is currently requirements-first. Keep that pattern clear:
-
-- Top-level requirement Markdown in the documentation folder: source-of-truth for MVP scope, tool schema expectations, error codes, and acceptance criteria.
-- `.codex/config.toml`: local Codex/MCP runtime config (tooling only, not product logic).
-
-When adding implementation, use a predictable layout:
-
-- `src/` for MCP service/tool code.
-- `tests/` for automated tests.
-- `examples/` for runnable request samples.
-
-## Build, Test, and Development Commands
-No build pipeline is committed yet. Until code is added, use:
-
-- `rg --files -uu` to inspect the full tree quickly.
-- `Get-ChildItem -Recurse -File *.md` to find and review the current requirement/spec document.
-
-For new runtime modules, add and document standard scripts:
-
-- `npm run dev` (local run),
-- `npm run build` (production build),
-- `npm test` (unit/integration),
-- `npm run lint` (style checks).
-
-## Coding Style & Naming Conventions
-- Use UTF-8 and keep Markdown/docs readable in both Chinese and English where needed.
-- Keep MCP tool names in `snake_case` (example: `generate_image`).
-- Keep error codes in `UPPER_SNAKE_CASE` with `E_` prefix (example: `E_PROVIDER_TIMEOUT`).
-- Environment variables must be uppercase (example: `DUOJIE_API_KEY`).
-- Prefer small, composable modules; avoid mixing HTTP adapter, validation, and file-save logic in one file.
-
-## Testing Guidelines
-A testing framework is not defined yet; add one in the same PR as runtime code. Minimum coverage should map to Section 9 acceptance criteria in the requirement doc:
-
-- text-to-image success path,
-- optional `reference_images` path,
-- output directory/file conflict handling (`overwrite` true/false),
-- missing/invalid key behavior,
-- upstream timeout/auth error mapping.
-
-Use `*.test.*` naming and keep provider calls mocked for deterministic tests.
-
-## Commit & Pull Request Guidelines
-Git history is not available in this workspace snapshot, so use Conventional Commits by default:
-
-- `feat(mcp): add generate_image schema`
-- `fix(save): handle overwrite=false filename collision`
-
-PRs should include:
-
-- clear summary and scope,
-- linked requirement sections from the current requirement/spec Markdown,
-- test evidence (command + result),
-- sample input/output (including saved file path),
-- confirmation that no API keys or Authorization values are exposed.
-
-## Security & Configuration Tips
-- Never hardcode or commit real API keys.
-- Mask secrets in logs (show only partial key, e.g., first 6 + last 4).
-- Keep `DUOJIE_BASE_URL` and model value configurable; do not bury them in code constants without override support.

package/src/config.ts

@@ -1,32 +0,0 @@
-import { AppError } from "./errors.js";
-
-export interface Config {
-  apiKey: string;
-  baseUrl: string;
-  model: string;
-  timeoutMs: number;
-}
-
-export function maskKey(key: string): string {
-  if (key.length <= 10) return "***";
-  return `${key.slice(0, 6)}...${key.slice(-4)}`;
-}
-
-function getArg(name: string): string | undefined {
-  const flag = `--${name}=`;
-  const arg = process.argv.find((a) => a.startsWith(flag));
-  return arg ? arg.slice(flag.length) : undefined;
-}
-
-export function loadConfig(): Config {
-  const apiKey = getArg("api-key") ?? process.env.DUOJIE_API_KEY ?? "";
-  if (!apiKey) {
-    throw new AppError("E_CONFIG_MISSING_KEY", "--api-key is required");
-  }
-  return {
-    apiKey,
-    baseUrl: getArg("base-url") ?? process.env.DUOJIE_BASE_URL ?? "https://api.duojie.games",
-    model: getArg("model") ?? process.env.DUOJIE_IMAGE_MODEL ?? "gemini-3.1-flash-image",
-    timeoutMs: 60_000,
-  };
-}

package/src/errors.ts

@@ -1,19 +0,0 @@
-export type ErrorCode =
-  | "E_CONFIG_MISSING_KEY"
-  | "E_INPUT_INVALID"
-  | "E_REFERENCE_NOT_FOUND"
-  | "E_PROVIDER_AUTH"
-  | "E_PROVIDER_RATE_LIMIT"
-  | "E_PROVIDER_BAD_REQUEST"
-  | "E_PROVIDER_TIMEOUT"
-  | "E_SAVE_FAILED";
-
-export class AppError extends Error {
-  constructor(
-    public readonly code: ErrorCode,
-    message: string,
-  ) {
-    super(message);
-    this.name = "AppError";
-  }
-}

package/src/index.ts

@@ -1,79 +0,0 @@
-#!/usr/bin/env node
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { z } from "zod";
-import { loadConfig } from "./config.js";
-import { generateImage } from "./provider.js";
-import { saveImage } from "./saver.js";
-import { AppError } from "./errors.js";
-
-const server = new McpServer({
-  name: "duojie-image",
-  version: "0.1.0",
-});
-
-server.registerTool(
-  "generate_image",
-  {
-    description: "Generate an image and save to disk.",
-    inputSchema: z.object({
-      prompt: z.string().min(1).describe("Image prompt"),
-      output_dir: z.string().describe("Output directory (absolute path)"),
-      output_filename: z.string().describe("Output filename (no extension needed)"),
-      reference_images: z.array(z.string()).optional().describe("Local image paths for reference"),
-      size: z.enum(["512px", "1K", "2K", "4K"]).optional().describe("Image size"),
-      aspect_ratio: z.string().optional().describe("e.g. 16:9"),
-      format: z.string().optional().describe("Output format, default png"),
-      model: z.string().optional().describe("Model override"),
-      overwrite: z.boolean().optional().describe("Overwrite existing file, default false"),
-      negative_prompt: z.string().optional().describe("What to avoid"),
-    }),
-  },
-  async (args) => {
-    let config;
-    try {
-      config = loadConfig();
-    } catch (err: unknown) {
-      const code = err instanceof AppError ? err.code : "E_CONFIG_MISSING_KEY";
-      return { content: [{ type: "text", text: JSON.stringify({ success: false, error: code, message: String(err instanceof Error ? err.message : err) }) }], isError: true };
-    }
-
-    // Enrich prompt with size/aspect hints
-    let fullPrompt = args.prompt;
-    if (args.size) fullPrompt += ` [size: ${args.size}]`;
-    if (args.aspect_ratio) fullPrompt += ` [aspect_ratio: ${args.aspect_ratio}]`;
-
-    try {
-      const imageBuffer = await generateImage(config, {
-        prompt: fullPrompt,
-        referenceImages: args.reference_images,
-        model: args.model,
-        negativePrompt: args.negative_prompt,
-      });
-
-      const savedPath = saveImage(imageBuffer, {
-        outputDir: args.output_dir,
-        outputFilename: args.output_filename,
-        format: args.format ?? "png",
-        overwrite: args.overwrite ?? false,
-      });
-
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({ success: true, saved_path: savedPath, model: args.model ?? config.model }),
-        }],
-      };
-    } catch (err) {
-      const code = err instanceof AppError ? err.code : "E_PROVIDER_BAD_REQUEST";
-      const msg = err instanceof Error ? err.message : String(err);
-      return {
-        content: [{ type: "text", text: JSON.stringify({ success: false, error: code, message: msg }) }],
-        isError: true,
-      };
-    }
-  },
-);
-
-const transport = new StdioServerTransport();
-await server.connect(transport);

package/src/provider.ts

@@ -1,123 +0,0 @@
-import { readFileSync } from "node:fs";
-import { AppError } from "./errors.js";
-import type { Config } from "./config.js";
-
-export interface GenerateOptions {
-  prompt: string;
-  referenceImages?: string[];
-  model?: string;
-  negativePrompt?: string;
-}
-
-interface ApiResponse {
-  choices: Array<{
-    message: {
-      images?: Array<{
-        image_url: { url: string };
-      }>;
-    };
-  }>;
-}
-
-async function fetchWithRetry(
-  url: string,
-  init: RequestInit,
-  timeoutMs: number,
-  retries = 2,
-): Promise<Response> {
-  let lastErr: unknown;
-  for (let attempt = 0; attempt <= retries; attempt++) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-      const res = await fetch(url, { ...init, signal: controller.signal });
-      clearTimeout(timer);
-      return res;
-    } catch (err: unknown) {
-      clearTimeout(timer);
-      const isAbort = err instanceof Error && err.name === "AbortError";
-      if (isAbort) {
-        throw new AppError("E_PROVIDER_TIMEOUT", "Request timed out");
-      }
-      lastErr = err;
-      if (attempt < retries) {
-        await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, attempt)));
-      }
-    }
-  }
-  throw new AppError("E_PROVIDER_BAD_REQUEST", `Network error: ${lastErr}`);
-}
-
-function buildMessages(opts: GenerateOptions): unknown[] {
-  const { prompt, referenceImages, negativePrompt } = opts;
-  const fullPrompt = negativePrompt ? `${prompt}\n\nAvoid: ${negativePrompt}` : prompt;
-
-  if (!referenceImages || referenceImages.length === 0) {
-    return [{ role: "user", content: fullPrompt }];
-  }
-
-  const parts: unknown[] = referenceImages.map((imgPath) => {
-    let data: Buffer;
-    try {
-      data = readFileSync(imgPath);
-    } catch {
-      throw new AppError("E_REFERENCE_NOT_FOUND", `Cannot read reference image: ${imgPath}`);
-    }
-    const b64 = data.toString("base64");
-    const mime = imgPath.toLowerCase().endsWith(".jpg") || imgPath.toLowerCase().endsWith(".jpeg")
-      ? "image/jpeg"
-      : "image/png";
-    return { type: "image_url", image_url: { url: `data:${mime};base64,${b64}` } };
-  });
-  parts.push({ type: "text", text: fullPrompt });
-
-  return [{ role: "user", content: parts }];
-}
-
-export async function generateImage(
-  config: Config,
-  opts: GenerateOptions,
-): Promise<Buffer> {
-  const messages = buildMessages(opts);
-  const model = opts.model ?? config.model;
-
-  const body = JSON.stringify({ model, messages });
-  const url = `${config.baseUrl}/v1/chat/completions`;
-
-  const res = await fetchWithRetry(
-    url,
-    {
-      method: "POST",
-      headers: {
-        "Authorization": `Bearer ${config.apiKey}`,
-        "Content-Type": "application/json",
-      },
-      body,
-    },
-    config.timeoutMs,
-  );
-
-  if (res.status === 401 || res.status === 403) {
-    throw new AppError("E_PROVIDER_AUTH", `Auth failed (HTTP ${res.status})`);
-  }
-  if (res.status === 429) {
-    throw new AppError("E_PROVIDER_RATE_LIMIT", "Rate limit exceeded");
-  }
-  if (!res.ok) {
-    const text = await res.text().catch(() => "");
-    throw new AppError("E_PROVIDER_BAD_REQUEST", `Upstream error ${res.status}: ${text.slice(0, 200)}`);
-  }
-
-  const data = (await res.json()) as ApiResponse;
-  const imageUrl = data.choices?.[0]?.message?.images?.[0]?.image_url?.url;
-  if (!imageUrl) {
-    throw new AppError("E_PROVIDER_BAD_REQUEST", "No image in response");
-  }
-
-  // data:image/png;base64,<data>
-  const comma = imageUrl.indexOf(",");
-  if (comma === -1) {
-    throw new AppError("E_PROVIDER_BAD_REQUEST", "Unexpected image_url format");
-  }
-  return Buffer.from(imageUrl.slice(comma + 1), "base64");
-}

package/src/saver.ts

@@ -1,38 +0,0 @@
-import { mkdirSync, existsSync, writeFileSync } from "node:fs";
-import { resolve, join, extname, basename } from "node:path";
-import { AppError } from "./errors.js";
-
-export interface SaveOptions {
-  outputDir: string;
-  outputFilename: string;
-  format?: string;
-  overwrite?: boolean;
-}
-
-export function saveImage(imageBuffer: Buffer, opts: SaveOptions): string {
-  const { outputDir, outputFilename, format = "png", overwrite = false } = opts;
-
-  const absDir = resolve(outputDir);
-  try {
-    mkdirSync(absDir, { recursive: true });
-  } catch (err) {
-    throw new AppError("E_SAVE_FAILED", `Cannot create directory: ${absDir} - ${err}`);
-  }
-
-  const ext = extname(outputFilename) || `.${format}`;
-  const base = extname(outputFilename) ? basename(outputFilename, ext) : outputFilename;
-  let finalPath = join(absDir, `${base}${ext}`);
-
-  if (!overwrite && existsSync(finalPath)) {
-    const ts = new Date().toISOString().replace(/[-:T]/g, "").slice(0, 15);
-    finalPath = join(absDir, `${base}_${ts}${ext}`);
-  }
-
-  try {
-    writeFileSync(finalPath, imageBuffer);
-  } catch (err) {
-    throw new AppError("E_SAVE_FAILED", `Cannot write file: ${finalPath} - ${err}`);
-  }
-
-  return finalPath;
-}

package/tests/provider.test.ts

@@ -1,60 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { generateImage } from "../src/provider.js";
-import type { Config } from "../src/config.js";
-import { AppError } from "../src/errors.js";
-
-const config: Config = {
-  apiKey: "sk-test",
-  baseUrl: "https://api.duojie.games",
-  model: "gemini-3.1-flash-image",
-  timeoutMs: 5000,
-};
-
-const fakeB64 = Buffer.from("fake-image").toString("base64");
-const fakeDataUri = `data:image/png;base64,${fakeB64}`;
-
-function makeOkResponse() {
-  return new Response(
-    JSON.stringify({
-      choices: [{ message: { images: [{ image_url: { url: fakeDataUri } }] } }],
-    }),
-    { status: 200, headers: { "Content-Type": "application/json" } },
-  );
-}
-
-describe("provider.generateImage", () => {
-  beforeEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it("returns image buffer on success", async () => {
-    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(makeOkResponse()));
-    const buf = await generateImage(config, { prompt: "a cat" });
-    expect(buf).toBeInstanceOf(Buffer);
-    expect(buf.toString()).toBe("fake-image");
-  });
-
-  it("throws E_PROVIDER_AUTH on 401", async () => {
-    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response("", { status: 401 })));
-    await expect(generateImage(config, { prompt: "x" })).rejects.toMatchObject({ code: "E_PROVIDER_AUTH" });
-  });
-
-  it("throws E_PROVIDER_RATE_LIMIT on 429", async () => {
-    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response("", { status: 429 })));
-    await expect(generateImage(config, { prompt: "x" })).rejects.toMatchObject({ code: "E_PROVIDER_RATE_LIMIT" });
-  });
-
-  it("throws E_PROVIDER_BAD_REQUEST when no image in response", async () => {
-    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(
-      new Response(JSON.stringify({ choices: [{ message: {} }] }), { status: 200 }),
-    ));
-    await expect(generateImage(config, { prompt: "x" })).rejects.toMatchObject({ code: "E_PROVIDER_BAD_REQUEST" });
-  });
-
-  it("throws E_REFERENCE_NOT_FOUND for missing reference image", async () => {
-    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(makeOkResponse()));
-    await expect(
-      generateImage(config, { prompt: "x", referenceImages: ["/nonexistent/image.png"] }),
-    ).rejects.toMatchObject({ code: "E_REFERENCE_NOT_FOUND" });
-  });
-});

package/tests/saver.test.ts

@@ -1,48 +0,0 @@
-import { describe, it, expect, afterEach } from "vitest";
-import { mkdirSync, rmSync, existsSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-import { saveImage } from "../src/saver.js";
-
-const testDir = join(tmpdir(), "mcp-duojie-test-" + Date.now());
-
-afterEach(() => {
-  rmSync(testDir, { recursive: true, force: true });
-});
-
-describe("saver.saveImage", () => {
-  it("creates directory and saves file", () => {
-    const buf = Buffer.from("imgdata");
-    const path = saveImage(buf, { outputDir: testDir, outputFilename: "out" });
-    expect(existsSync(path)).toBe(true);
-    expect(path.endsWith(".png")).toBe(true);
-  });
-
-  it("respects format extension", () => {
-    const buf = Buffer.from("imgdata");
-    const path = saveImage(buf, { outputDir: testDir, outputFilename: "out", format: "jpg" });
-    expect(path.endsWith(".jpg")).toBe(true);
-  });
-
-  it("does not overwrite when overwrite=false", () => {
-    const buf = Buffer.from("imgdata");
-    const first = saveImage(buf, { outputDir: testDir, outputFilename: "out", overwrite: false });
-    const second = saveImage(buf, { outputDir: testDir, outputFilename: "out", overwrite: false });
-    expect(first).not.toBe(second);
-    expect(existsSync(first)).toBe(true);
-    expect(existsSync(second)).toBe(true);
-  });
-
-  it("overwrites when overwrite=true", () => {
-    const buf = Buffer.from("imgdata");
-    const first = saveImage(buf, { outputDir: testDir, outputFilename: "out", overwrite: true });
-    const second = saveImage(buf, { outputDir: testDir, outputFilename: "out", overwrite: true });
-    expect(first).toBe(second);
-  });
-
-  it("preserves extension in filename", () => {
-    const buf = Buffer.from("imgdata");
-    const path = saveImage(buf, { outputDir: testDir, outputFilename: "poster.webp" });
-    expect(path.endsWith(".webp")).toBe(true);
-  });
-});

package/tsconfig.json

@@ -1,14 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "Node16",
-    "moduleResolution": "Node16",
-    "outDir": "dist",
-    "rootDir": "src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true
-  },
-  "include": ["src"],
-  "exclude": ["node_modules", "dist", "tests"]
-}

package//346/226/207/346/241/243/345/214/272/MCP-/351/246/231/350/225/211/346/250/241/345/236/213/347/224/237/345/233/276-/351/234/200/346/261/202/346/226/207/346/241/243.md

@@ -1,190 +0,0 @@
-# MCP 香蕉模型生图需求文档（v0.1）
-
-更新时间：2026-03-03
-
-## 1. 背景与目标
-
-目标是实现一个 MCP 服务，让用户通过自然语言一句话完成生图任务：
-
-- 说清楚要生成什么图（提示词）
-- 说清楚保存到哪里（目录）
-- 说清楚文件叫什么（文件名）
-
-MCP 收到调用后，使用固定服务地址 `https://api.duojie.games` 和模型 `gemini-3.1-flash-image` 生成图片，并保存到指定目录。
-
-## 2. 设计范围（MVP）
-
-MVP 只做一件事：`生成并落盘图片`，不做图库管理、任务队列面板、鉴权后台。
-
-必须支持：
-
-- 文生图（无参考图）
-- 图生图（有 1~N 张参考图，参考图可选）
-- 指定输出目录 + 文件名
-- 可配置图片大小
-- 用户自行配置 API Key（不能写死）
-
-## 3. 对“香蕉模型常用生图姿势”的理解
-
-结合 Gemini/Nano Banana 官方能力，优先支持以下 4 种高频姿势：
-
-1. 文生图（Text-to-Image）
-- 输入：`prompt`
-- 输出：1 张图片（默认）
-- 场景：海报、封面、插画草图
-
-2. 单图参考编辑（Image + Text -> Image）
-- 输入：`prompt + 1 张参考图`
-- 输出：1 张改造后的图
-- 场景：换背景、换风格、加元素
-
-3. 多图融合（Multi-reference composition）
-- 输入：`prompt + 多张参考图`
-- 输出：1 张融合图
-- 场景：商品合成、角色一致性、素材拼合
-- 说明：Gemini 3.1 Image 能力文档提到可混合多张参考图（上限能力较高），MVP 先做保守上限以控风险
-
-4. 多轮迭代编辑（Multi-turn editing）
-- 输入：上一轮结果 + 新 prompt
-- 输出：迭代后的新图
-- 场景：持续改图直到满意
-- MVP 策略：先不做服务端会话态，只支持“用户显式把上一轮图作为参考图再提交”
-
-## 4. 用户流程（你预期的简单流程）
-
-1. 用户对 AI 说：`生成什么图 + 存哪里 + 叫什么`
-2. AI 触发 MCP 工具 `generate_image`
-3. MCP 读取 key，调用 `https://api.duojie.games`
-4. MCP 拿到图片数据（base64 或 URL）
-5. MCP 在本地创建目录并保存文件
-6. MCP 返回：成功/失败、最终保存路径、请求摘要
-
-## 5. MCP 工具定义（建议）
-
-工具名建议：`generate_image`
-
-### 5.1 入参（需求版）
-
-| 字段 | 类型 | 必填 | 说明 |
-|---|---|---|---|
-| `prompt` | `string` | 是 | 生图提示词 |
-| `reference_images` | `string[]` | 否 | 参考图路径列表（本地绝对路径） |
-| `output_dir` | `string` | 是 | 输出目录（绝对路径或工作区相对路径） |
-| `output_filename` | `string` | 是 | 导出文件名，建议不含扩展名 |
-| `size` | `string` | 否 | 大小档位，建议：`512px`/`1K`/`2K`/`4K` |
-
-### 5.2 建议扩展参数（预留）
-
-| 字段 | 类型 | 必填 | 说明 |
-|---|---|---|---|
-| `aspect_ratio` | `string` | 否 | 如 `1:1`、`16:9` |
-| `format` | `string` | 否 | 输出格式，默认 `png` |
-| `model` | `string` | 否 | 默认 `gemini-3.1-flash-image` |
-| `overwrite` | `boolean` | 否 | 文件存在时是否覆盖，默认 `false` |
-| `negative_prompt` | `string` | 否 | 若网关支持则透传 |
-
-## 6. 配置需求（Key 与网关）
-
-### 6.1 必需配置
-
-- `DUOJIE_BASE_URL=https://api.duojie.games`
-- `DUOJIE_API_KEY=用户自行配置`
-- `DUOJIE_IMAGE_MODEL=gemini-3.1-flash-image`（默认值）
-
-### 6.2 配置优先级
-
-1. MCP 启动参数
-2. 环境变量
-3. 配置文件
-
-### 6.3 安全约束
-
-- 严禁把 key 写入代码仓库
-- 日志中 key 必须脱敏（只显示前 6 后 4）
-- 报错信息中不回显 Authorization 原文
-
-## 7. 接口与落盘行为
-
-### 7.1 调用行为
-
-- HTTP Header：`Authorization: Bearer <KEY>`
-- 请求超时：默认 60s（可配）
-- 重试策略：仅网络抖动/5xx 重试，最多 2 次，指数退避
-
-### 7.2 文件保存规则
-
-- 若目录不存在：自动创建
-- 默认扩展名：`.png`
-- 文件冲突：
-  - `overwrite=false` 时自动追加时间戳或序号
-  - `overwrite=true` 时覆盖
-- 返回绝对路径，方便上游 AI 直接引用
-
-## 8. 错误处理（MVP）
-
-统一错误码建议：
-
-- `E_CONFIG_MISSING_KEY`：未配置 key
-- `E_INPUT_INVALID`：参数不合法（空 prompt、非法路径等）
-- `E_REFERENCE_NOT_FOUND`：参考图不存在或不可读
-- `E_PROVIDER_AUTH`：上游鉴权失败（401/403）
-- `E_PROVIDER_RATE_LIMIT`：限流
-- `E_PROVIDER_BAD_REQUEST`：上游参数错误
-- `E_PROVIDER_TIMEOUT`：上游超时
-- `E_SAVE_FAILED`：落盘失败（权限/磁盘空间）
-
-## 9. 验收标准（第一版）
-
-1. 文生图成功
-- 输入：仅 `prompt + output_dir + output_filename`
-- 结果：指定目录出现图片文件，MCP 返回完整路径
-
-2. 参考图可选
-- 不传 `reference_images`：可正常生图
-- 传 1~N 张有效参考图：可正常生图
-
-3. 指定名称与目录生效
-- 文件名与目录按用户要求保存
-- 冲突策略符合 `overwrite` 规则
-
-4. key 配置生效
-- 未配置 key 时给出明确报错
-- 配置错误 key 时能识别并返回鉴权错误
-
-5. 基本稳定性
-- 连续 20 次调用无进程崩溃
-
-## 10. 当前假设与待确认项
-
-以下内容需要你确认后再进入开发实现：
-
-1. `https://api.duojie.games` 对 `gemini-3.1-flash-image` 的具体协议
-- 是 OpenAI 兼容（如 `/v1/images/generations`）还是 Gemini `generateContent` 风格
-
-2. `size` 参数真实字段名
-- 可能是 `image_size`（如 `1K/2K`）或 `size`（如 `1024x1024`）
-
-3. 参考图上传方式
-- base64 内联
-- URL 引用
-- multipart 文件上传
-
-4. 返回图片格式
-- `b64_json`、`url`、或混合
-
-5. 模型名是否固定为 `gemini-3.1-flash-image`
-- 官方文档常见命名为 `gemini-3.1-flash-image-preview`，你的网关可能做了别名映射
-
-## 11. 建议的下一步
-
-确认完第 10 节后，下一步直接输出：
-
-- MCP 工具 schema（JSON Schema）
-- 请求适配层（兼容两类上游协议）
-- 本地落盘实现与错误码实现
-- 最小可跑 demo（CLI + MCP）
-
-## 12. 参考资料
-
-- Gemini Image Generation 文档：<https://ai.google.dev/gemini-api/docs/image-generation>
-- Gemini OpenAI Compatibility 文档：<https://ai.google.dev/gemini-api/docs/openai>