@aigne/doc-smith 0.9.8-alpha.10 → 0.9.8-alpha.11

package/agents/generate-images/generate-image.yaml

@@ -0,0 +1,75 @@
+type: image
+name: generateSlotDiagramImage
+image_model:
+  model: google/gemini-3-pro-image-preview
+  imageConfig:
+    imageSize:
+      $get: size
+    aspectRatio:
+      $get: aspectRatio
+
+instructions:
+  - role: system
+    url: ./prompts/system.md
+  - role: user
+    url: ./prompts/user.md
+
+# Support image-to-image generation by passing existing image via input_file_key
+# If existingImage is provided (array of mediaFile objects), it will be passed to the model
+input_file_key: existingImage
+
+input_schema:
+  type: object
+  properties:
+    documentContent:
+      type: string
+      description: The full document content for context
+    desc:
+      type: string
+      description: The AFS slot description that describes what should be illustrated
+    locale:
+      type: string
+      description: Language for diagram labels
+      default: zh
+    size:
+      type: string
+      description: Size of the generated image
+      default: "2K"
+    aspectRatio:
+      type: string
+      description: Aspect ratio of the generated image
+      enum: ["1:1", "5:4", "4:3", "3:2", "16:9", "21:9"]
+      default: "4:3"
+    existingImage:
+      type: array
+      nullable: true
+      description: Array of mediaFile objects for existing diagram image (for image-to-image generation)
+      items:
+        type: object
+        properties:
+          type:
+            type: string
+            description: File type, should be "local"
+          path:
+            type: string
+            description: Absolute path to the image file
+          filename:
+            type: string
+            description: Image filename
+          mimeType:
+            type: string
+            description: MIME type of the image (e.g., "image/png", "image/jpeg")
+    useImageToImage:
+      type: boolean
+      description: Whether to use image-to-image generation mode
+      default: false
+    feedback:
+      type: string
+      description: User feedback for image editing (used in image-to-image mode to guide modifications)
+      default: ""
+  required:
+    - documentContent
+    - desc
+    - aspectRatio
+
+include_input_in_output: true

package/agents/generate-images/generate-summary.mjs

@@ -0,0 +1,213 @@
+/**
+ * 生成图片生成任务的最终总结报告
+ * @param {Object} input - 输入参数
+ * @param {string} input.locale - 主语言
+ * @param {Array} input.generationTasks - 生成任务列表（来自 prepare-generation）
+ * @param {Array} input.processAllSlots - 执行结果列表（来自 team 的 iterate）
+ * @param {number} input.newTasks - 新增任务数量
+ * @param {number} input.updateTasks - 更新任务数量
+ * @param {number} input.skippedTasks - 跳过的任务数量
+ * @returns {Object} - 包含格式化消息和统计数据的对象
+ */
+export default function generateSummary(input) {
+  const { locale, generationTasks, processAllSlots, newTasks, updateTasks, skippedTasks } = input;
+
+  // 如果没有任务
+  if (!generationTasks || generationTasks.length === 0) {
+    return {
+      message: `⏭️  没有需要生成的图片 slot`,
+      summary: {
+        locale,
+        totalTasks: 0,
+        newImages: 0,
+        updatedImages: 0,
+        skippedImages: skippedTasks || 0,
+        successTasks: 0,
+        failedTasks: 0,
+        generatedImages: [],
+      },
+    };
+  }
+
+  // 统计成功和失败的任务
+  const results = processAllSlots || [];
+  const successTasks = results.filter((r) => r && r.success);
+  const failedTasks = results.filter((r) => r && !r.success);
+
+  const successCount = successTasks.length;
+  const failedCount = failedTasks.length;
+
+  // 生成成功的图片路径列表（最多显示10个）
+  const successPaths = successTasks.map((r) => r.imagePath).filter(Boolean);
+  const displayPaths =
+    successPaths.length > 10
+      ? [...successPaths.slice(0, 10), `... 还有 ${successPaths.length - 10} 个图片`]
+      : successPaths;
+
+  // 生成失败的任务列表
+  const failedKeys = failedTasks.map((r) => ({
+    key: r.key,
+    error: r.message || r.error || "未知错误",
+  }));
+
+  // 生成格式化的消息
+  let message = `
+✅ 图片生成任务已完成
+
+📊 **生成统计**：
+   - 主语言：${locale}
+   - 总任务数：${generationTasks.length}
+   - 新增图片：${newTasks || 0}
+   - 更新图片：${updateTasks || 0}
+   - 跳过图片：${skippedTasks || 0}
+   - 成功：${successCount}
+   - 失败：${failedCount}
+`;
+
+  if (successPaths.length > 0) {
+    message += `
+📷 **生成的图片**：
+${displayPaths.map((path) => `   - ${path}`).join("\n")}
+`;
+  }
+
+  if (failedKeys.length > 0) {
+    message += `
+❌ **失败的任务**：
+${failedKeys.map((f) => `   - ${f.key}: ${f.error}`).join("\n")}
+`;
+  }
+
+  message += `
+💡 **提示**：
+   - 图片已保存到 assets/{key}/images/${locale}.png
+   - 元信息已保存到 assets/{key}/.meta.yaml
+  `;
+
+  return {
+    message: message.trim(),
+    summary: {
+      locale,
+      totalTasks: generationTasks.length,
+      newImages: newTasks || 0,
+      updatedImages: updateTasks || 0,
+      skippedImages: skippedTasks || 0,
+      successTasks: successCount,
+      failedTasks: failedCount,
+      generatedImages: successPaths,
+      failedKeys,
+    },
+  };
+}
+
+// 添加描述信息
+generateSummary.description =
+  "生成图片生成任务的最终总结报告。" +
+  "汇总生成统计数据（主语言、新增/更新/跳过数量、成功/失败任务等），生成易读的格式化消息。" +
+  "列出生成的图片路径和失败的任务信息。";
+
+// 定义输入 schema
+generateSummary.input_schema = {
+  type: "object",
+  properties: {
+    locale: {
+      type: "string",
+      description: "主语言代码",
+    },
+    generationTasks: {
+      type: "array",
+      description: "生成任务列表",
+      items: {
+        type: "object",
+      },
+    },
+    processAllSlots: {
+      type: "array",
+      description: "执行结果列表",
+      items: {
+        type: "object",
+        properties: {
+          success: { type: "boolean" },
+          key: { type: "string" },
+          imagePath: { type: "string" },
+          message: { type: "string" },
+          error: { type: "string" },
+        },
+      },
+    },
+    newTasks: {
+      type: "number",
+      description: "新增任务数量",
+    },
+    updateTasks: {
+      type: "number",
+      description: "更新任务数量",
+    },
+    skippedTasks: {
+      type: "number",
+      description: "跳过的任务数量",
+    },
+  },
+};
+
+// 定义输出 schema
+generateSummary.output_schema = {
+  type: "object",
+  required: ["message", "summary"],
+  properties: {
+    message: {
+      type: "string",
+      description: "格式化的总结消息，包含生成统计和提示信息",
+    },
+    summary: {
+      type: "object",
+      description: "结构化的统计数据",
+      properties: {
+        locale: {
+          type: "string",
+          description: "主语言代码",
+        },
+        totalTasks: {
+          type: "number",
+          description: "总任务数",
+        },
+        newImages: {
+          type: "number",
+          description: "新增图片数量",
+        },
+        updatedImages: {
+          type: "number",
+          description: "更新图片数量",
+        },
+        skippedImages: {
+          type: "number",
+          description: "跳过图片数量",
+        },
+        successTasks: {
+          type: "number",
+          description: "成功任务数量",
+        },
+        failedTasks: {
+          type: "number",
+          description: "失败任务数量",
+        },
+        generatedImages: {
+          type: "array",
+          items: { type: "string" },
+          description: "生成的图片路径列表",
+        },
+        failedKeys: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              key: { type: "string" },
+              error: { type: "string" },
+            },
+          },
+          description: "失败的任务列表",
+        },
+      },
+    },
+  },
+};

package/agents/generate-images/index.yaml

@@ -0,0 +1,39 @@
+type: team
+name: generateImages
+alias:
+  - gen-images
+description: |
+  扫描主语言文档中的 AFS image slot 并批量生成主语言图片。支持以下功能：
+  - 扫描所有文档中的 slot 并生成图片
+  - 扫描指定文档中的 slot 并生成图片
+  - 支持强制重新生成已有图片
+
+skills:
+  - url: ./scan-image-slots.mjs       # 扫描主语言文档中的 slot
+  - url: ./prepare-generation.mjs     # 准备生图任务（去重、检查已有图片）
+  - type: team
+    name: processAllSlots             # 批量生成图片
+    skills:
+      - url: ./prepare-image-generation.mjs
+      - url: ./generate-image.yaml
+      - url: ./save-image-result.mjs
+    iterate_on: generationTasks
+    concurrency: 1                    # 并发生成
+  - url: ./generate-summary.mjs       # 生成总结报告
+
+input_schema:
+  type: object
+  properties:
+    docs:
+      type: array
+      items:
+        type: string
+      description: |
+        要处理的文档路径列表（可选）,必须是文档结构 yaml 中的 path 字段。如果不传或为空数组，则处理所有文档。
+    force:
+      type: boolean
+      default: false
+      description: |
+        是否强制重新生成已有图片（默认只生成缺失的图片）
+
+mode: sequential

package/agents/generate-images/prepare-generation.mjs

@@ -0,0 +1,283 @@
+import { readFile, access, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import { join } from "node:path";
+import { parse as yamlParse } from "yaml";
+import { PATHS } from "../../utils/agent-constants.mjs";
+
+/**
+ * 检查图片目录是否存在
+ * @param {string} key - 图片 key
+ * @returns {Promise<boolean>}
+ */
+async function imageDirectoryExists(key) {
+  const dirPath = join(PATHS.ASSETS_DIR, key);
+  try {
+    const stats = await stat(dirPath);
+    return stats.isDirectory();
+  } catch (_error) {
+    return false;
+  }
+}
+
+/**
+ * 读取图片的 meta 信息
+ * @param {string} key - 图片 key
+ * @returns {Promise<Object|null>} - meta 信息或 null（文件不存在）
+ */
+async function readImageMeta(key) {
+  const metaPath = join(PATHS.ASSETS_DIR, key, ".meta.yaml");
+
+  try {
+    await access(metaPath, constants.F_OK | constants.R_OK);
+    const content = await readFile(metaPath, "utf8");
+    return yamlParse(content);
+  } catch (_error) {
+    return null;
+  }
+}
+
+/**
+ * 检查图片文件是否存在
+ * @param {string} key - 图片 key
+ * @param {string} locale - 语言代码
+ * @returns {Promise<string|null>} - 图片路径或 null（不存在）
+ */
+async function getExistingImagePath(key, locale) {
+  const imagePath = join(PATHS.ASSETS_DIR, key, "images", `${locale}.png`);
+
+  try {
+    await access(imagePath, constants.F_OK | constants.R_OK);
+    return imagePath;
+  } catch (_error) {
+    return null;
+  }
+}
+
+/**
+ * 判断文档 hash 是否发生变化
+ * @param {Array} currentDocs - 当前文档列表
+ * @param {Array} metaDocs - meta 中记录的文档列表
+ * @returns {boolean} - 是否有变化
+ */
+function hasDocumentChanges(currentDocs, metaDocs) {
+  if (!metaDocs || metaDocs.length === 0) {
+    return true;
+  }
+
+  // 将 meta 文档转换为 map（path -> hash）
+  const metaHashMap = new Map(metaDocs.map((doc) => [doc.path, doc.hash]));
+
+  // 检查每个当前文档的 hash
+  for (const doc of currentDocs) {
+    const metaHash = metaHashMap.get(doc.path);
+    if (!metaHash || metaHash !== doc.hash) {
+      return true; // hash 不同或新文档
+    }
+  }
+
+  return false;
+}
+
+/**
+ * 准备生图任务
+ * @param {Object} input - 输入参数
+ * @param {string} input.locale - 主语言
+ * @param {Array} input.slots - 扫描到的 slot 列表
+ * @param {boolean} input.force - 是否强制重新生成
+ * @returns {Promise<Object>} - 任务列表
+ */
+export default async function prepareGeneration(input) {
+  try {
+    const { locale, slots, force = false } = input;
+
+    if (!locale) {
+      throw new Error("缺少主语言参数， 请检查 doc-smith 工作目录是否已初始化，且文件已生成！");
+    }
+
+    if (!slots || slots.length === 0) {
+      return {
+        success: true,
+        locale,
+        generationTasks: [],
+        message: "没有找到需要生成的图片 slot",
+      };
+    }
+
+    const generationTasks = [];
+    let skippedCount = 0;
+
+    // 检查每个 slot
+    for (const slot of slots) {
+      const { key, id, desc, documents } = slot;
+
+      // 检查图片目录是否存在
+      const dirExists = await imageDirectoryExists(key);
+
+      let needsGeneration = false;
+      let isUpdate = false;
+      let existingImagePath = null;
+
+      if (force) {
+        // 强制重新生成
+        needsGeneration = true;
+        isUpdate = dirExists;
+        if (isUpdate) {
+          existingImagePath = await getExistingImagePath(key, locale);
+        }
+      } else if (!dirExists) {
+        // 图片目录不存在，需要生成
+        needsGeneration = true;
+        isUpdate = false;
+      } else {
+        // 图片目录存在，检查 hash 是否变化
+        const meta = await readImageMeta(key);
+
+        if (!meta) {
+          // meta 文件不存在，重新生成
+          needsGeneration = true;
+          isUpdate = false;
+        } else {
+          const hasChanges = hasDocumentChanges(documents, meta.documents);
+
+          if (hasChanges) {
+            // 文档有变化，更新图片
+            needsGeneration = true;
+            isUpdate = true;
+            existingImagePath = await getExistingImagePath(key, locale);
+          } else {
+            // 没有变化，跳过
+            needsGeneration = false;
+            skippedCount++;
+          }
+        }
+      }
+
+      if (needsGeneration) {
+        generationTasks.push({
+          key,
+          id,
+          desc,
+          documents,
+          isUpdate,
+          existingImagePath,
+        });
+      }
+    }
+
+    return {
+      success: true,
+      locale,
+      generationTasks,
+      totalSlots: slots.length,
+      newTasks: generationTasks.filter((t) => !t.isUpdate).length,
+      updateTasks: generationTasks.filter((t) => t.isUpdate).length,
+      skippedTasks: skippedCount,
+      message: `准备生成 ${generationTasks.length} 个图片（新增 ${generationTasks.filter((t) => !t.isUpdate).length}，更新 ${generationTasks.filter((t) => t.isUpdate).length}，跳过 ${skippedCount}）`,
+    };
+  } catch (error) {
+    throw new Error(`准备生图任务时发生错误: ${error.message}`);
+  }
+}
+
+// 添加描述信息
+prepareGeneration.description =
+  "检查已有图片目录和 meta 信息，对比文档 hash，" + "判断哪些图片需要生成或更新，生成任务列表。";
+
+// 定义输入 schema
+prepareGeneration.input_schema = {
+  type: "object",
+  properties: {
+    locale: {
+      type: "string",
+      description: "主语言代码",
+    },
+    slots: {
+      type: "array",
+      description: "扫描到的 slot 列表",
+      items: {
+        type: "object",
+        properties: {
+          key: { type: "string" },
+          id: { type: "string" },
+          desc: { type: "string" },
+          documents: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                path: { type: "string" },
+                hash: { type: "string" },
+                content: { type: "string" },
+              },
+            },
+          },
+        },
+      },
+    },
+    force: {
+      type: "boolean",
+      description: "是否强制重新生成所有图片",
+      default: false,
+    },
+  },
+  required: ["locale", "slots"],
+};
+
+// 定义输出 schema
+prepareGeneration.output_schema = {
+  type: "object",
+  required: ["success"],
+  properties: {
+    success: {
+      type: "boolean",
+      description: "操作是否成功",
+    },
+    locale: {
+      type: "string",
+      description: "主语言代码",
+    },
+    generationTasks: {
+      type: "array",
+      description: "需要生成的任务列表",
+      items: {
+        type: "object",
+        properties: {
+          key: { type: "string" },
+          id: { type: "string" },
+          desc: { type: "string" },
+          documents: { type: "array" },
+          isUpdate: { type: "boolean" },
+          existingImagePath: { type: "string", nullable: true },
+        },
+      },
+    },
+    totalSlots: {
+      type: "number",
+      description: "总 slot 数量",
+    },
+    newTasks: {
+      type: "number",
+      description: "新增任务数量",
+    },
+    updateTasks: {
+      type: "number",
+      description: "更新任务数量",
+    },
+    skippedTasks: {
+      type: "number",
+      description: "跳过的任务数量",
+    },
+    message: {
+      type: "string",
+      description: "操作结果描述",
+    },
+    error: {
+      type: "string",
+      description: "错误代码（失败时存在）",
+    },
+    suggestion: {
+      type: "string",
+      description: "建议操作（失败时存在）",
+    },
+  },
+};