@aigne/doc-smith 0.9.10 → 0.9.11-beta

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 @@
+/**
+ * Generate final summary report for image generation tasks
+ * @param {Object} input - Input parameters
+ * @param {string} input.locale - Main language
+ * @param {Array} input.generationTasks - Generation task list (from prepare-generation)
+ * @param {Array} input.processAllSlots - Execution result list (from team iterate)
+ * @param {number} input.newTasks - Number of new tasks
+ * @param {number} input.updateTasks - Number of update tasks
+ * @param {number} input.skippedTasks - Number of skipped tasks
+ * @returns {Object} - Object containing formatted message and statistics
+ */
+export default function generateSummary(input) {
+  const { locale, generationTasks, processAllSlots, newTasks, updateTasks, skippedTasks } = input;
+
+  // If no tasks
+  if (!generationTasks || generationTasks.length === 0) {
+    return {
+      message: `⏭️  No image slots to generate`,
+      summary: {
+        locale,
+        totalTasks: 0,
+        newImages: 0,
+        updatedImages: 0,
+        skippedImages: skippedTasks || 0,
+        successTasks: 0,
+        failedTasks: 0,
+        generatedImages: [],
+      },
+    };
+  }
+
+  // Count successful and failed tasks
+  const results = processAllSlots || [];
+  const successTasks = results.filter((r) => r?.success);
+  const failedTasks = results.filter((r) => r && !r.success);
+
+  const successCount = successTasks.length;
+  const failedCount = failedTasks.length;
+
+  // Generate list of successful image paths (show up to 10)
+  const successPaths = successTasks.map((r) => r.imagePath).filter(Boolean);
+  const displayPaths =
+    successPaths.length > 10
+      ? [...successPaths.slice(0, 10), `... and ${successPaths.length - 10} more images`]
+      : successPaths;
+
+  // Generate list of failed tasks
+  const failedKeys = failedTasks.map((r) => ({
+    key: r.key,
+    error: r.message || r.error || "Unknown error",
+  }));
+
+  // Generate formatted message
+  let message = `
+✅ Image generation tasks completed
+
+📊 **Generation Statistics**:
+   - Main language: ${locale}
+   - Total tasks: ${generationTasks.length}
+   - New images: ${newTasks || 0}
+   - Updated images: ${updateTasks || 0}
+   - Skipped images: ${skippedTasks || 0}
+   - Succeeded: ${successCount}
+   - Failed: ${failedCount}
+`;
+
+  if (successPaths.length > 0) {
+    message += `
+📷 **Generated Images**:
+${displayPaths.map((path) => `   - ${path}`).join("\n")}
+`;
+  }
+
+  if (failedKeys.length > 0) {
+    message += `
+❌ **Failed Tasks**:
+${failedKeys.map((f) => `   - ${f.key}: ${f.error}`).join("\n")}
+`;
+  }
+
+  message += `
+💡 **Tips**:
+   - Images saved to assets/{key}/images/${locale}.png
+   - Metadata saved to 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,
+    },
+  };
+}
+
+// Add description
+generateSummary.description =
+  "Generate final summary report for image generation tasks. " +
+  "Aggregate generation statistics (main language, new/update/skip counts, success/failure tasks, etc.), generate readable formatted message. " +
+  "List generated image paths and failed task information.";
+
+// Define input schema
+generateSummary.input_schema = {
+  type: "object",
+  properties: {
+    locale: {
+      type: "string",
+      description: "Main language code",
+    },
+    generationTasks: {
+      type: "array",
+      description: "Generation task list",
+      items: {
+        type: "object",
+      },
+    },
+    processAllSlots: {
+      type: "array",
+      description: "Execution result list",
+      items: {
+        type: "object",
+        properties: {
+          success: { type: "boolean" },
+          key: { type: "string" },
+          imagePath: { type: "string" },
+          message: { type: "string" },
+          error: { type: "string" },
+        },
+      },
+    },
+    newTasks: {
+      type: "number",
+      description: "Number of new tasks",
+    },
+    updateTasks: {
+      type: "number",
+      description: "Number of update tasks",
+    },
+    skippedTasks: {
+      type: "number",
+      description: "Number of skipped tasks",
+    },
+  },
+};
+
+// Define output schema
+generateSummary.output_schema = {
+  type: "object",
+  required: ["message", "summary"],
+  properties: {
+    message: {
+      type: "string",
+      description: "Formatted summary message containing generation statistics and tips",
+    },
+    summary: {
+      type: "object",
+      description: "Structured statistics data",
+      properties: {
+        locale: {
+          type: "string",
+          description: "Main language code",
+        },
+        totalTasks: {
+          type: "number",
+          description: "Total task count",
+        },
+        newImages: {
+          type: "number",
+          description: "Number of new images",
+        },
+        updatedImages: {
+          type: "number",
+          description: "Number of updated images",
+        },
+        skippedImages: {
+          type: "number",
+          description: "Number of skipped images",
+        },
+        successTasks: {
+          type: "number",
+          description: "Number of successful tasks",
+        },
+        failedTasks: {
+          type: "number",
+          description: "Number of failed tasks",
+        },
+        generatedImages: {
+          type: "array",
+          items: { type: "string" },
+          description: "List of generated image paths",
+        },
+        failedKeys: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              key: { type: "string" },
+              error: { type: "string" },
+            },
+          },
+          description: "List of failed tasks",
+        },
+      },
+    },
+  },
+};

package/agents/generate-images/index.yaml

@@ -0,0 +1,39 @@
+type: team
+name: generateImages
+alias:
+  - gen-images
+description: |
+  Scan AFS image slots in main language documents and batch generate main language images. Supports the following features:
+  - Scan all documents for slots and generate images
+  - Scan specified documents for slots and generate images
+  - Support force regeneration of existing images
+
+skills:
+  - url: ./scan-image-slots.mjs       # Scan slots in main language documents
+  - url: ./prepare-generation.mjs     # Prepare image generation tasks (dedup, check existing images)
+  - type: team
+    name: processAllSlots             # Batch generate images
+    skills:
+      - url: ./prepare-image-generation.mjs
+      - url: ./generate-image.yaml
+      - url: ./save-image-result.mjs
+    iterate_on: generationTasks
+    concurrency: 5                    # Concurrent generation
+  - url: ./generate-summary.mjs       # Generate summary report
+
+input_schema:
+  type: object
+  properties:
+    docs:
+      type: array
+      items:
+        type: string
+      description: |
+        Document path list to process (optional), must be path field from document structure yaml. Processes all documents if not provided or empty array.
+    force:
+      type: boolean
+      default: false
+      description: |
+        Whether to force regenerate existing images (defaults to only generating missing images)
+
+mode: sequential

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

@@ -0,0 +1,286 @@
+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";
+
+/**
+ * Check if image directory exists
+ * @param {string} key - Image 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;
+  }
+}
+
+/**
+ * Read image meta information
+ * @param {string} key - Image key
+ * @returns {Promise<Object|null>} - Meta information or null (if file does not exist)
+ */
+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;
+  }
+}
+
+/**
+ * Check if image file exists
+ * @param {string} key - Image key
+ * @param {string} locale - Language code
+ * @returns {Promise<string|null>} - Image path or null (if not exists)
+ */
+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;
+  }
+}
+
+/**
+ * Determine if document hash has changed
+ * @param {Array} currentDocs - Current document list
+ * @param {Array} metaDocs - Document list recorded in meta
+ * @returns {boolean} - Whether there are changes
+ */
+function hasDocumentChanges(currentDocs, metaDocs) {
+  if (!metaDocs || metaDocs.length === 0) {
+    return true;
+  }
+
+  // Convert meta documents to map (path -> hash)
+  const metaHashMap = new Map(metaDocs.map((doc) => [doc.path, doc.hash]));
+
+  // Check hash of each current document
+  for (const doc of currentDocs) {
+    const metaHash = metaHashMap.get(doc.path);
+    if (!metaHash || metaHash !== doc.hash) {
+      return true; // Hash differs or new document
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Prepare image generation tasks
+ * @param {Object} input - Input parameters
+ * @param {string} input.locale - Main language
+ * @param {Array} input.slots - Scanned slot list
+ * @param {boolean} input.force - Whether to force regeneration
+ * @returns {Promise<Object>} - Task list
+ */
+export default async function prepareGeneration(input) {
+  try {
+    const { locale, slots, force = false } = input;
+
+    if (!locale) {
+      throw new Error(
+        "Missing main language parameter, please check if doc-smith workspace has been initialized and files have been generated!",
+      );
+    }
+
+    if (!slots || slots.length === 0) {
+      return {
+        success: true,
+        locale,
+        generationTasks: [],
+        message: "No image slots found to generate",
+      };
+    }
+
+    const generationTasks = [];
+    let skippedCount = 0;
+
+    // Check each slot
+    for (const slot of slots) {
+      const { key, id, desc, documents } = slot;
+
+      // Check if image directory exists
+      const dirExists = await imageDirectoryExists(key);
+
+      let needsGeneration = false;
+      let isUpdate = false;
+      let existingImagePath = null;
+
+      if (force) {
+        // Force regeneration
+        needsGeneration = true;
+        isUpdate = dirExists;
+        if (isUpdate) {
+          existingImagePath = await getExistingImagePath(key, locale);
+        }
+      } else if (!dirExists) {
+        // Image directory does not exist, needs generation
+        needsGeneration = true;
+        isUpdate = false;
+      } else {
+        // Image directory exists, check if hash changed
+        const meta = await readImageMeta(key);
+
+        if (!meta) {
+          // Meta file does not exist, regenerate
+          needsGeneration = true;
+          isUpdate = false;
+        } else {
+          const hasChanges = hasDocumentChanges(documents, meta.documents);
+
+          if (hasChanges) {
+            // Document has changes, update image
+            needsGeneration = true;
+            isUpdate = true;
+            existingImagePath = await getExistingImagePath(key, locale);
+          } else {
+            // No changes, skip
+            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: `Preparing to generate ${generationTasks.length} images (new: ${generationTasks.filter((t) => !t.isUpdate).length}, update: ${generationTasks.filter((t) => t.isUpdate).length}, skip: ${skippedCount})`,
+    };
+  } catch (error) {
+    throw new Error(`Error preparing image generation tasks: ${error.message}`);
+  }
+}
+
+// Add description
+prepareGeneration.description =
+  "Check existing image directories and meta information, compare document hashes, " +
+  "determine which images need generation or update, and generate task list.";
+
+// Define input schema
+prepareGeneration.input_schema = {
+  type: "object",
+  properties: {
+    locale: {
+      type: "string",
+      description: "Main language code",
+    },
+    slots: {
+      type: "array",
+      description: "Scanned slot list",
+      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: "Whether to force regenerate all images",
+      default: false,
+    },
+  },
+  required: ["locale", "slots"],
+};
+
+// Define output schema
+prepareGeneration.output_schema = {
+  type: "object",
+  required: ["success"],
+  properties: {
+    success: {
+      type: "boolean",
+      description: "Whether operation succeeded",
+    },
+    locale: {
+      type: "string",
+      description: "Main language code",
+    },
+    generationTasks: {
+      type: "array",
+      description: "List of tasks to generate",
+      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: "Total slot count",
+    },
+    newTasks: {
+      type: "number",
+      description: "Number of new tasks",
+    },
+    updateTasks: {
+      type: "number",
+      description: "Number of update tasks",
+    },
+    skippedTasks: {
+      type: "number",
+      description: "Number of skipped tasks",
+    },
+    message: {
+      type: "string",
+      description: "Operation result description",
+    },
+    error: {
+      type: "string",
+      description: "Error code (present on failure)",
+    },
+    suggestion: {
+      type: "string",
+      description: "Suggested action (present on failure)",
+    },
+  },
+};