1

2026-05-05 14:40:41 +08:00
parent e847fcea6f
commit 07e777fef8
76 changed files with 4246 additions and 444 deletions
--- a/.codex/skills/gpt-image-2-apimart/SKILL.md
+++ b/.codex/skills/gpt-image-2-apimart/SKILL.md
@@ -0,0 +1,91 @@
+---
+name: gpt-image-2-apimart
+description: Generate or inspect project image assets through this repository's APIMart OpenAI-compatible gpt-image-2 workflow. Use when Codex needs to create puzzle template sample images, reproduce the server-rs gpt-image-2 request body, dry-run image prompts, batch-generate local project thumbnails, or debug APIMART_BASE_URL / APIMART_API_KEY image-generation configuration without exposing secrets.
+---
+
+# gpt-image-2 APIMart
+
+Use this skill for project-local image asset generation that must match the repository's `server-rs` APIMart `gpt-image-2` path.
+
+## Workflow
+
+1. Read the local task and decide whether the image is project-bound.
+2. Prefer `scripts/generate-template-samples.mjs` for puzzle template thumbnails or small batches.
+3. Run dry-run first:
+
+   ```powershell
+   node .codex/skills/gpt-image-2-apimart/scripts/generate-template-samples.mjs --dry-run
+   ```
+
+4. If dry-run looks correct and the user asked for real assets, run live generation with a small limit:
+
+   ```powershell
+   node .codex/skills/gpt-image-2-apimart/scripts/generate-template-samples.mjs --live --limit 6
+   ```
+
+5. Save final project assets under `public/` or another explicitly requested workspace path.
+6. Never print `APIMART_API_KEY`. Report only whether configuration exists.
+
+## Request Contract
+
+The repository image path uses:
+
+```text
+POST {APIMART_BASE_URL}/images/generations
+Authorization: Bearer {APIMART_API_KEY}
+Content-Type: application/json
+```
+
+Default body:
+
+```json
+{
+  "model": "gpt-image-2",
+  "prompt": "<prompt>",
+  "n": 1,
+  "size": "1:1"
+}
+```
+
+For a reference image, add:
+
+```json
+{
+  "image_urls": ["data:image/png;base64,..."]
+}
+```
+
+Poll async responses with:
+
+```text
+GET {APIMART_BASE_URL}/tasks/{task_id}
+```
+
+Accept image output from `data[].url`, `data[].b64_json`, direct nested `url` fields, or async task results.
+
+## Environment
+
+Load environment values from process env first, then `.env.secrets.local`, `.env.local`, and `.env.example`.
+
+Required for live generation:
+
+- `APIMART_BASE_URL`
+- `APIMART_API_KEY`
+
+Optional:
+
+- `APIMART_IMAGE_REQUEST_TIMEOUT_MS`
+
+If the key or base URL is missing, stop after dry-run or explain the missing configuration. Do not ask the user to paste the key in chat.
+
+## Prompt Rules
+
+- Use Chinese prompts when generating project puzzle templates.
+- Keep template samples square, clear, image-only, and suitable for puzzle thumbnails.
+- Avoid text, watermark, UI chrome, buttons, borders, and tutorial overlays.
+- Include local negative constraints in the prompt instead of relying on provider-specific negative prompt fields.
+
+## Resources
+
+- `scripts/generate-template-samples.mjs`: dry-run or live-generate puzzle template sample thumbnails.
+- `assets/puzzle-template-prompts.json`: default prompt list consumed by the script.
--- a/.codex/skills/gpt-image-2-apimart/agents/openai.yaml
+++ b/.codex/skills/gpt-image-2-apimart/agents/openai.yaml
@@ -0,0 +1,7 @@
+interface:
+  display_name: "GPT Image 2 APIMart"
+  short_description: "Generate project thumbnails through APIMart"
+  brand_color: "#10B981"
+  default_prompt: "Use $gpt-image-2-apimart to dry-run or generate puzzle template thumbnails through APIMart."
+policy:
+  allow_implicit_invocation: true
--- a/.codex/skills/gpt-image-2-apimart/assets/puzzle-template-prompts.json
+++ b/.codex/skills/gpt-image-2-apimart/assets/puzzle-template-prompts.json
@@ -0,0 +1,62 @@
+[
+  {
+    "id": "couple-memory",
+    "title": "情侣合照拼图",
+    "prompt": "温暖自然光下的一对情侣纪念合照，城市咖啡馆窗边，桌面有花束和两杯热饮，人物神情自然，画面主体清晰，前中后景层次明确，适合切成拼图。"
+  },
+  {
+    "id": "family-keepsake",
+    "title": "家庭纪念拼图",
+    "prompt": "三代家人在客厅沙发前的家庭纪念合照，柔和午后阳光，孩子抱着生日蛋糕，长辈微笑，画面温暖完整，细节丰富但不杂乱。"
+  },
+  {
+    "id": "friends-party",
+    "title": "朋友聚会拼图",
+    "prompt": "朋友们在露台夜晚聚会，彩灯、桌上零食和举杯瞬间，人物分布有层次，中央焦点清楚，氛围轻松热闹，适合社交分享拼图。"
+  },
+  {
+    "id": "festival-card",
+    "title": "节日贺卡拼图",
+    "prompt": "节日餐桌与礼物布置，暖色灯光、彩带、蜡烛和窗外烟花，画面像无字贺卡，主体集中，边角细节可辨，适合节日拼图。"
+  },
+  {
+    "id": "knowledge-summary",
+    "title": "知识总结拼图",
+    "prompt": "一张无文字的知识学习主题插画，书桌上有打开的笔记本、便签、咖啡、台灯和思维导图式图形元素，构图整洁，重点明确，适合学习打卡拼图。"
+  },
+  {
+    "id": "product-detail",
+    "title": "商品细节拼图",
+    "prompt": "精致商品静物展示，一只高质感香水瓶放在丝绸与花瓣之间，玻璃反光清晰，包装和材质细节丰富，背景干净，适合作为电商细节拼图。"
+  },
+  {
+    "id": "healing-landscape",
+    "title": "治愈风景拼图",
+    "prompt": "治愈风景插画，清晨湖边、薄雾、远山、木栈道和一盏小灯，色彩柔和，层次清楚，局部元素可辨，适合长时间拼图。"
+  },
+  {
+    "id": "cute-pet",
+    "title": "宠物可爱拼图",
+    "prompt": "一只可爱的橘猫趴在阳光窗台上，旁边有绿植、毛线球和小毯子，猫的表情清楚，画面温柔干净，适合萌宠拼图分享。"
+  },
+  {
+    "id": "hot-topic-poster",
+    "title": "热点海报拼图",
+    "prompt": "电影感热点海报风插画，雨夜街头、霓虹反光、奔跑的人影和远处光束，强烈视觉焦点，画面无文字，适合热点话题拼图。"
+  },
+  {
+    "id": "event-invitation",
+    "title": "活动邀请拼图",
+    "prompt": "活动邀请主题插画，展厅入口、花艺装置、签到台和柔和灯带，人群剪影自然分布，画面高级干净，无文字，适合活动预热拼图。"
+  },
+  {
+    "id": "daily-challenge",
+    "title": "每日挑战拼图",
+    "prompt": "每日挑战主题插画，清爽桌面上摆放相机、明信片、计时器和小奖章，色彩明亮，构图有趣，细节可拆解，适合平台每日拼图。"
+  },
+  {
+    "id": "children-learning",
+    "title": "儿童认知拼图",
+    "prompt": "儿童认知学习插画，木质桌面上有积木、彩色形状、动物玩偶和小书本，色彩明快，元素边界清晰，无文字，适合儿童教育拼图。"
+  }
+]
--- a/.codex/skills/gpt-image-2-apimart/scripts/generate-template-samples.mjs
+++ b/.codex/skills/gpt-image-2-apimart/scripts/generate-template-samples.mjs
@@ -0,0 +1,347 @@
+import { Buffer } from 'node:buffer';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const skillRoot = path.resolve(__dirname, '..');
+const repoRoot = path.resolve(skillRoot, '..', '..', '..');
+const promptsPath = path.join(
+  skillRoot,
+  'assets',
+  'puzzle-template-prompts.json',
+);
+const defaultOutDir = path.join(repoRoot, 'public', 'puzzle-creation-templates');
+const defaultTimeoutMs = 180000;
+const pollDelayMs = 3000;
+
+const args = new Map();
+for (let index = 2; index < process.argv.length; index += 1) {
+  const raw = process.argv[index];
+  if (raw.startsWith('--')) {
+    const next = process.argv[index + 1];
+    if (next && !next.startsWith('--')) {
+      args.set(raw, next);
+      index += 1;
+    } else {
+      args.set(raw, true);
+    }
+  }
+}
+
+function readDotenv(fileName) {
+  const filePath = path.join(repoRoot, fileName);
+  if (!existsSync(filePath)) {
+    return {};
+  }
+
+  const values = {};
+  for (const line of readFileSync(filePath, 'utf8').split(/\r?\n/u)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      continue;
+    }
+    const match = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/u.exec(trimmed);
+    if (!match) {
+      continue;
+    }
+    let value = match[2].trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    values[match[1]] = value;
+  }
+  return values;
+}
+
+function resolveEnv() {
+  const loaded = {
+    ...readDotenv('.env.example'),
+    ...readDotenv('.env.local'),
+    ...readDotenv('.env.secrets.local'),
+    ...process.env,
+  };
+  return {
+    baseUrl: String(loaded.APIMART_BASE_URL || '').trim().replace(/\/+$/u, ''),
+    apiKey: String(loaded.APIMART_API_KEY || '').trim(),
+    timeoutMs: Number.parseInt(
+      String(loaded.APIMART_IMAGE_REQUEST_TIMEOUT_MS || defaultTimeoutMs),
+      10,
+    ),
+  };
+}
+
+function buildPrompt(template) {
+  return [
+    '请生成一张高清 1:1 方形插画，用作拼图创作模板样例图。',
+    `画面主体：${template.prompt}`,
+    '要求：主体清晰集中，前中后景层次明确，边角有可辨识细节，适合切成 3x3 到 7x7 拼图。',
+    '避免：文字、水印、边框、按钮、UI 元素、教程标注、低清晰度、过度模糊、杂乱构图。',
+  ].join('');
+}
+
+function collectStringsByKey(value, targetKey, output) {
+  if (Array.isArray(value)) {
+    value.forEach((entry) => collectStringsByKey(entry, targetKey, output));
+    return;
+  }
+  if (!value || typeof value !== 'object') {
+    return;
+  }
+
+  for (const [key, nested] of Object.entries(value)) {
+    if (key === targetKey) {
+      if (typeof nested === 'string' && nested.trim()) {
+        output.push(nested.trim());
+      }
+      if (Array.isArray(nested)) {
+        nested.forEach((entry) => {
+          if (typeof entry === 'string' && entry.trim()) {
+            output.push(entry.trim());
+          }
+        });
+      }
+    }
+    collectStringsByKey(nested, targetKey, output);
+  }
+}
+
+function extractImageUrls(payload) {
+  const urls = [];
+  collectStringsByKey(payload, 'url', urls);
+  collectStringsByKey(payload, 'image', urls);
+  collectStringsByKey(payload, 'image_url', urls);
+  return [...new Set(urls)].filter((url) => /^https?:\/\//u.test(url));
+}
+
+function extractBase64Images(payload) {
+  const values = [];
+  collectStringsByKey(payload, 'b64_json', values);
+  return values;
+}
+
+function extractTaskId(payload) {
+  const ids = [];
+  collectStringsByKey(payload, 'task_id', ids);
+  collectStringsByKey(payload, 'taskId', ids);
+  collectStringsByKey(payload, 'id', ids);
+  return ids[0] || null;
+}
+
+function inferExtensionFromContentType(contentType) {
+  const normalized = contentType.split(';')[0]?.trim().toLowerCase();
+  if (normalized === 'image/png') {
+    return 'png';
+  }
+  if (normalized === 'image/webp') {
+    return 'webp';
+  }
+  if (normalized === 'image/gif') {
+    return 'gif';
+  }
+  return 'jpg';
+}
+
+function inferExtensionFromBytes(bytes) {
+  if (bytes.subarray(0, 8).equals(Buffer.from('\x89PNG\r\n\x1A\n', 'binary'))) {
+    return 'png';
+  }
+  if (bytes.subarray(0, 3).equals(Buffer.from([0xff, 0xd8, 0xff]))) {
+    return 'jpg';
+  }
+  if (
+    bytes.subarray(0, 4).toString('ascii') === 'RIFF' &&
+    bytes.subarray(8, 12).toString('ascii') === 'WEBP'
+  ) {
+    return 'webp';
+  }
+  return 'png';
+}
+
+async function fetchJson(url, options, timeoutMs) {
+  const abortController = new AbortController();
+  const timer = setTimeout(() => abortController.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, {
+      ...options,
+      signal: abortController.signal,
+    });
+    const text = await response.text();
+    if (!response.ok) {
+      throw new Error(`APIMart ${response.status}: ${text.slice(0, 600)}`);
+    }
+    return JSON.parse(text);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function downloadUrl(url, timeoutMs) {
+  const abortController = new AbortController();
+  const timer = setTimeout(() => abortController.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { signal: abortController.signal });
+    if (!response.ok) {
+      throw new Error(`download ${response.status}`);
+    }
+    const bytes = Buffer.from(await response.arrayBuffer());
+    return {
+      bytes,
+      extension: inferExtensionFromContentType(
+        response.headers.get('content-type') || 'image/jpeg',
+      ),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function waitForTask(env, taskId) {
+  const deadline = Date.now() + env.timeoutMs;
+  await new Promise((resolve) => setTimeout(resolve, 10000));
+
+  while (Date.now() < deadline) {
+    const payload = await fetchJson(
+      `${env.baseUrl}/tasks/${encodeURIComponent(taskId)}`,
+      {
+        headers: {
+          Authorization: `Bearer ${env.apiKey}`,
+        },
+      },
+      env.timeoutMs,
+    );
+    const statuses = [];
+    collectStringsByKey(payload, 'status', statuses);
+    collectStringsByKey(payload, 'task_status', statuses);
+    const status = String(statuses[0] || '').trim().toLowerCase();
+
+    if (['completed', 'succeeded', 'success'].includes(status)) {
+      return payload;
+    }
+    if (['failed', 'error', 'canceled', 'cancelled', 'unknown'].includes(status)) {
+      throw new Error(`APIMart task ${taskId} failed: ${JSON.stringify(payload).slice(0, 600)}`);
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, pollDelayMs));
+  }
+
+  throw new Error(`APIMart task ${taskId} timed out`);
+}
+
+async function generateOne(env, template, outDir) {
+  const requestBody = {
+    model: 'gpt-image-2',
+    prompt: buildPrompt(template),
+    n: 1,
+    size: '1:1',
+  };
+  const payload = await fetchJson(
+    `${env.baseUrl}/images/generations`,
+    {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${env.apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(requestBody),
+    },
+    env.timeoutMs,
+  );
+
+  const resolvedPayload =
+    extractImageUrls(payload).length || extractBase64Images(payload).length
+      ? payload
+      : await waitForTask(env, extractTaskId(payload));
+  const urls = extractImageUrls(resolvedPayload);
+  const b64Images = extractBase64Images(resolvedPayload);
+
+  let image;
+  if (urls[0]) {
+    image = await downloadUrl(urls[0], env.timeoutMs);
+  } else if (b64Images[0]) {
+    const bytes = Buffer.from(b64Images[0], 'base64');
+    image = {
+      bytes,
+      extension: inferExtensionFromBytes(bytes),
+    };
+  } else {
+    throw new Error(`APIMart returned no image for ${template.id}`);
+  }
+
+  mkdirSync(outDir, { recursive: true });
+  const outputPath = path.join(outDir, `${template.id}.${image.extension}`);
+  writeFileSync(outputPath, image.bytes);
+  return outputPath;
+}
+
+const dryRun = args.has('--dry-run') || !args.has('--live');
+const outDir = path.resolve(String(args.get('--out-dir') || defaultOutDir));
+const limit = Number.parseInt(String(args.get('--limit') || '0'), 10);
+const onlyIds = String(args.get('--only') || '')
+  .split(',')
+  .map((value) => value.trim())
+  .filter(Boolean);
+const templates = JSON.parse(readFileSync(promptsPath, 'utf8')).filter(
+  (template) => !onlyIds.length || onlyIds.includes(template.id),
+);
+const selectedTemplates = limit > 0 ? templates.slice(0, limit) : templates;
+
+if (dryRun) {
+  console.log(
+    JSON.stringify(
+      {
+        mode: 'dry-run',
+        outDir,
+        count: selectedTemplates.length,
+        requests: selectedTemplates.map((template) => ({
+          id: template.id,
+          title: template.title,
+          body: {
+            model: 'gpt-image-2',
+            prompt: buildPrompt(template),
+            n: 1,
+            size: '1:1',
+          },
+        })),
+      },
+      null,
+      2,
+    ),
+  );
+  process.exit(0);
+}
+
+const env = resolveEnv();
+if (!env.baseUrl || !env.apiKey) {
+  console.error(
+    JSON.stringify({
+      ok: false,
+      error: 'Missing APIMART_BASE_URL or APIMART_API_KEY',
+      hasBaseUrl: Boolean(env.baseUrl),
+      hasApiKey: Boolean(env.apiKey),
+    }),
+  );
+  process.exit(1);
+}
+
+const generated = [];
+for (const template of selectedTemplates) {
+  console.log(`Generating ${template.id}...`);
+  generated.push(await generateOne(env, template, outDir));
+}
+
+console.log(
+  JSON.stringify(
+    {
+      ok: true,
+      count: generated.length,
+      files: generated,
+    },
+    null,
+    2,
+  ),
+);