@aigne/doc-smith 0.8.12-beta.7 → 0.8.12-beta.9

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [0.8.12-beta.9](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.12-beta.8...v0.8.12-beta.9) (2025-10-15)
+
+
+### Features
+
+* **branding:** support updating branding information during publish doc ([#190](https://github.com/AIGNE-io/aigne-doc-smith/issues/190)) ([1918cae](https://github.com/AIGNE-io/aigne-doc-smith/commit/1918cae6ceefd24d76b6086730b6e0d038057cb6))
+* support translate meta in publish ([#189](https://github.com/AIGNE-io/aigne-doc-smith/issues/189)) ([3a34e38](https://github.com/AIGNE-io/aigne-doc-smith/commit/3a34e38f4283d4b2a19a88e426a8b49f0dd52bb6))
+
+
+### Bug Fixes
+
+* generate d2 diagram by tool use ([#184](https://github.com/AIGNE-io/aigne-doc-smith/issues/184)) ([0d04349](https://github.com/AIGNE-io/aigne-doc-smith/commit/0d04349d14cde62388467f755dedc10b74d14980))
+
+## [0.8.12-beta.8](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.12-beta.7...v0.8.12-beta.8) (2025-10-14)
+
+
+### Features
+
+* **media:** support filter and describe and use media files with AI ([#185](https://github.com/AIGNE-io/aigne-doc-smith/issues/185)) ([230271d](https://github.com/AIGNE-io/aigne-doc-smith/commit/230271d70ce2e701be8d6c6e3bdc27f5fadc6cf7))
+
+
+### Bug Fixes
+
+* update evaluate page template ([#182](https://github.com/AIGNE-io/aigne-doc-smith/issues/182)) ([aef2104](https://github.com/AIGNE-io/aigne-doc-smith/commit/aef21049ded2f1ddfe9309dac67d6db1a026d3f6))
+
 ## [0.8.12-beta.7](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.12-beta.6...v0.8.12-beta.7) (2025-10-12)
 
 

package/agents/clear/choose-contents.mjs

@@ -1,5 +1,10 @@
 import { getDocSmithEnvFilePath } from "../../utils/auth-utils.mjs";
-import { getConfigFilePath, getStructurePlanPath, toDisplayPath } from "../../utils/file-utils.mjs";
+import {
+  getConfigFilePath,
+  getMediaDescriptionCachePath,
+  getStructurePlanPath,
+  toDisplayPath,
+} from "../../utils/file-utils.mjs";
 
 const TARGET_METADATA = {
   generatedDocs: {
@@ -36,6 +41,14 @@ const TARGET_METADATA = {
       `Delete appUrl from './${toDisplayPath(getConfigFilePath(workDir))}'.`,
     agent: "clearDeploymentConfig",
   },
+  mediaDescription: {
+    label: "media file descriptions",
+    description: () =>
+      `Delete AI-generated descriptions in './${toDisplayPath(
+        getMediaDescriptionCachePath(),
+      )}' (will regenerate on next generation).`,
+    agent: "clearMediaDescription",
+  },
 };
 
 const TARGET_KEYS = Object.keys(TARGET_METADATA);

package/agents/clear/clear-media-description.mjs

@@ -0,0 +1,129 @@
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import chalk from "chalk";
+import { parse, stringify } from "yaml";
+import { getMediaDescriptionCachePath } from "../../utils/file-utils.mjs";
+
+export default async function clearMediaDescription(_input = {}, options = {}) {
+  const cacheFilePath = getMediaDescriptionCachePath();
+
+  // Check if the cache file exists
+  if (!existsSync(cacheFilePath)) {
+    return {
+      message: "No media descriptions found to clear",
+    };
+  }
+
+  try {
+    // Read existing cache
+    const cacheContent = await readFile(cacheFilePath, "utf8");
+    const parsedCache = parse(cacheContent);
+    const cache = parsedCache?.descriptions || {};
+
+    // Get all media files from cache
+    const mediaHashes = Object.keys(cache);
+
+    if (mediaHashes.length === 0) {
+      return {
+        message: "No media descriptions found to clear",
+      };
+    }
+
+    // Build choices from cache - extract filename from path
+    const choices = mediaHashes.map((hash) => {
+      const mediaPath = cache[hash]?.path || "unknown";
+      const filename = path.basename(mediaPath);
+      const description = cache[hash]?.description || "";
+      const truncatedDesc =
+        description.length > 80 ? `${description.slice(0, 80)}...` : description;
+
+      return {
+        name: filename,
+        description: truncatedDesc,
+        value: hash,
+        checked: false,
+      };
+    });
+
+    // Add an option to clear all media descriptions
+    choices.push({
+      name: chalk.red("🗑️  Clear ALL media descriptions"),
+      value: "__ALL__",
+      checked: false,
+    });
+
+    let selectedHashes = [];
+
+    if (options?.prompts?.checkbox) {
+      selectedHashes = await options.prompts.checkbox({
+        message: "Select media files to clear descriptions:",
+        choices,
+        validate: (answer) => (answer.length > 0 ? true : "Please select at least one item."),
+      });
+    } else {
+      // If no prompts available, clear all
+      selectedHashes = ["__ALL__"];
+    }
+
+    if (selectedHashes.length === 0) {
+      return {
+        message: "No media files selected for clearing descriptions",
+      };
+    }
+
+    const results = [];
+    let clearedCount = 0;
+
+    if (selectedHashes.includes("__ALL__")) {
+      // Clear all media descriptions
+      await writeFile(
+        cacheFilePath,
+        stringify({
+          descriptions: {},
+          lastUpdated: new Date().toISOString(),
+        }),
+      );
+      results.push(`Cleared descriptions for all media files (${mediaHashes.length} files)`);
+      clearedCount = mediaHashes.length;
+    } else {
+      // Clear descriptions for selected files
+      const updatedCache = { ...cache };
+
+      for (const hash of selectedHashes) {
+        if (updatedCache[hash]) {
+          const filename = path.basename(updatedCache[hash].path);
+          delete updatedCache[hash];
+          results.push(`Cleared description for ${chalk.cyan(filename)}`);
+          clearedCount++;
+        }
+      }
+
+      await writeFile(
+        cacheFilePath,
+        stringify({
+          descriptions: updatedCache,
+          lastUpdated: new Date().toISOString(),
+        }),
+      );
+    }
+
+    const header = `✨ Successfully cleared media descriptions`;
+    const detailLines = results.join("\n");
+
+    const message = [header, "", detailLines, ""].filter(Boolean).join("\n");
+
+    return {
+      message,
+      clearedCount,
+    };
+  } catch (error) {
+    return {
+      message: `Error clearing media descriptions: ${error.message}`,
+      error: true,
+    };
+  }
+}
+
+clearMediaDescription.taskTitle = "Clear media file descriptions";
+clearMediaDescription.description = "Clear AI-generated descriptions for media files";

package/agents/clear/index.yaml

@@ -21,4 +21,6 @@ input_schema:
           - documentStructure
           - generatedDocs
           - documentConfig
-          - authTokens
+          - authTokens
+          - deploymentConfig
+          - mediaDescription

package/agents/evaluate/code-snippet.mjs

@@ -38,32 +38,37 @@ export default async function evaluateDocumentCode({ content }) {
   const checkList = await pMap(
     checkPromiseList,
     async (item) => {
-      const result = await pRetry(() => lintCode(item), {
-        onFailedAttempt: ({ error, attemptNumber, retriesLeft }) => {
-          debug(
-            `Attempt ${attemptNumber} failed: ${error.message}. There are ${retriesLeft} retries left.`,
-          );
-        },
-        retries: 3,
-      });
-      // lint occurs error, ignore
-      if (!result.success) {
-        debug("Lint failed", item, result);
-        return [];
-      }
+      try {
+        const result = await pRetry(() => lintCode(item), {
+          onFailedAttempt: ({ error, attemptNumber, retriesLeft }) => {
+            debug(
+              `Attempt ${attemptNumber} failed: ${error.message}. There are ${retriesLeft} retries left.`,
+            );
+          },
+          retries: 3,
+        });
+        // lint occurs error, ignore
+        if (!result.success) {
+          debug("Lint failed", item, result);
+          return [];
+        }
 
-      if (!result.issues || result.issues.length === 0) {
-        debug("Lint result empty issues", item, result);
+        if (!result.issues || result.issues.length === 0) {
+          debug("Lint result empty issues", item, result);
+          return [];
+        }
+
+        errorCount += 1;
+        return result.issues.map((x) => {
+          return {
+            ...x,
+            level: severityMapLevel[x.severity],
+          };
+        });
+      } catch (error) {
+        debug("Lint occurred error", error);
         return [];
       }
-
-      errorCount += 1;
-      return result.issues.map((x) => {
-        return {
-          ...x,
-          level: severityMapLevel[x.severity],
-        };
-      });
     },
     { concurrency: 5 },
   );
@@ -71,7 +76,6 @@ export default async function evaluateDocumentCode({ content }) {
 
   return {
     codeEvaluation: {
-      baseline: 100,
       details: checkListResult,
       totalCount,
       ignoreCount,

package/agents/evaluate/document-structure.yaml

@@ -32,9 +32,6 @@ output_schema:
     structureEvaluation:
       type: object
       properties:
-        baseline:
-          type: integer
-          description: Baseline score of selected purposes
         details:
           type: array
           items:
@@ -64,7 +61,6 @@ output_schema:
               - description
           description: List of detailed evaluations for each purpose dimension
       required:
-        - baseline
         - details
   required:
     - structureEvaluation

package/agents/evaluate/document.yaml

@@ -39,9 +39,6 @@ output_schema:
     documentEvaluation:
       type: object
       properties:
-        baseline:
-          type: integer
-          description: Fixed baseline score (80)
         details:
           type: array
           description: Detailed observations contributing to the final score
@@ -50,7 +47,7 @@ output_schema:
             properties:
               dimension:
                 type: string
-                enum: [readability, coherence, contentQuality, consistency, purposeAlignment, audienceAlignment, knowledgeLevelAlignment, navigability]
+                enum: [readability, coherence, contentQuality, consistency, purposeAlignment, audienceAlignment, knowledgeLevelAlignment]
                 description: Dimension associated with this observation
               level:
                 type: string
@@ -72,7 +69,6 @@ output_schema:
               - line
               - description
       required:
-        - baseline
         - details
   required:
     - documentEvaluation

package/agents/generate/index.yaml

@@ -42,6 +42,7 @@ skills:
         }
       ])
   - ../utils/format-document-structure.mjs
+  - ../media/load-media-description.mjs
   - ../update/batch-generate-document.yaml
   - url: ../utils/check-feedback-refiner.mjs
     default_input:

package/agents/init/index.mjs

@@ -418,6 +418,10 @@ export function generateYAML(input) {
     // Paths
     docsDir: input.docsDir || "./aigne/doc-smith/docs",
     sourcesPath: input.sourcesPath || [],
+    media: {
+      // Image filtering settings
+      minImageWidth: input.minImageWidth || 800,
+    },
   };
 
   // Generate comments and structure
@@ -530,6 +534,12 @@ export function generateYAML(input) {
   const sourcesPathSection = yamlStringify({ sourcesPath: config.sourcesPath }).trim();
   yaml += `${sourcesPathSection.replace(/^sourcesPath:/, "sourcesPath:  # Source code paths to analyze")}\n`;
 
+  // Image filtering settings
+  const mediaInfoSection = yamlStringify({
+    media: config.media,
+  }).trim();
+  yaml += `# minImageWidth: Only images wider than this value (in pixels) will be used in page generation\n${mediaInfoSection}\n`;
+
   return yaml;
 }
 

package/agents/media/batch-generate-media-description.yaml

@@ -0,0 +1,44 @@
+type: team
+name: batchGenerateMediaDescription
+description: Batch generate media (image/video) descriptions with concurrency
+skills:
+  - url: ./generate-media-description.yaml
+task_render_mode: collapse
+task_title: Generate Media Description
+input_schema:
+  type: object
+  properties:
+    mediaToDescribe:
+      type: array
+      items:
+        type: object
+        properties:
+          name:
+            type: string
+          width:
+            type: number
+          height:
+            type: number
+          hash:
+            type: string
+          path:
+            type: string
+          type:
+            type: string
+          mediaFile:
+            type: array
+            items:
+              type: object
+              properties:
+                type:
+                  type: string
+                path:
+                  type: string
+                filename:
+                  type: string
+                mimeType:
+                  type: string
+      description: Array of media files (images/videos) that need descriptions
+iterate_on: mediaToDescribe
+concurrency: 5
+mode: sequential

package/agents/media/generate-media-description.yaml

@@ -0,0 +1,47 @@
+name: generateMediaDescription
+description: Generate description for a single media file (image/video)
+model: "google/gemini-2.5-flash"
+modalities: ["text", "image"]
+instructions:
+  - role: system
+    url: ../../prompts/media/media-description/system-prompt.md
+  - role: user
+    url: ../../prompts/media/media-description/user-prompt.md
+input_file_key: mediaFile
+include_input_in_output: true
+input_schema:
+  type: object
+  properties:
+    name:
+      type: string
+      description: Media file name
+    width:
+      type: number
+      description: Media width in pixels
+    height:
+      type: number
+      description: Media height in pixels
+    hash:
+      type: string
+    path:
+      type: string
+      description: Media path
+    type:
+      type: string
+      description: Media type (image/video)
+    mediaFile:
+      type: array
+      items:
+        type: object
+        properties:
+          type:
+            type: string
+          path:
+            type: string
+          filename:
+            type: string
+          mimeType:
+            type: string
+  required:
+    - name
+output_key: description

package/agents/media/load-media-description.mjs

@@ -0,0 +1,238 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parse, stringify } from "yaml";
+import { getMediaDescriptionCachePath } from "../../utils/file-utils.mjs";
+
+const SIZE_THRESHOLD = 10 * 1024 * 1024; // 10MB
+
+// Supported MIME types for Gemini AI
+const SUPPORTED_IMAGE_TYPES = new Set([
+  "image/png",
+  "image/jpeg",
+  "image/webp",
+  "image/heic",
+  "image/heif",
+]);
+
+const SUPPORTED_VIDEO_TYPES = new Set([
+  "video/mp4",
+  "video/mpeg",
+  "video/mov",
+  "video/avi",
+  "video/x-flv",
+  "video/mpg",
+  "video/webm",
+  "video/wmv",
+  "video/3gpp",
+]);
+
+/**
+ * Calculate hash for a media file
+ * For files < 10MB: use file content
+ * For files >= 10MB: use path + size + mtime to avoid memory issues
+ * @param {string} absolutePath - The absolute path to the media file
+ * @returns {Promise<string>} - The hash of the file
+ */
+async function calculateMediaHash(absolutePath) {
+  const stats = await stat(absolutePath);
+
+  if (stats.size < SIZE_THRESHOLD) {
+    // Small file: use full content
+    const content = await readFile(absolutePath);
+    return createHash("sha256").update(content).digest("hex");
+  }
+
+  // Large file: use path + size + mtime
+  const hashInput = `${absolutePath}:${stats.size}:${stats.mtimeMs}`;
+  return createHash("sha256").update(hashInput).digest("hex");
+}
+
+/**
+ * Load media descriptions from cache and generate new ones if needed
+ * @param {Object} input - Input parameters
+ * @param {Array} input.mediaFiles - Array of media file objects from load-sources
+ * @param {string} input.docsDir - Base directory for documentation
+ * @param {Object} options - Agent options
+ * @returns {Promise<Object>} - Updated assetsContent with media descriptions
+ */
+export default async function loadMediaDescription(input, options) {
+  const { mediaFiles = [], docsDir } = input;
+
+  // Filter to get image and video files with supported MIME types
+  const mediaFilesToProcess = mediaFiles.filter((file) => {
+    if (file.type === "image") {
+      return SUPPORTED_IMAGE_TYPES.has(file.mimeType);
+    }
+    if (file.type === "video") {
+      return SUPPORTED_VIDEO_TYPES.has(file.mimeType);
+    }
+    return false;
+  });
+
+  // Path to media description cache file
+  const cacheFilePath = getMediaDescriptionCachePath();
+
+  // Load existing cache
+  let cache = {};
+  if (existsSync(cacheFilePath)) {
+    try {
+      const cacheContent = await readFile(cacheFilePath, "utf8");
+      const parsedCache = parse(cacheContent);
+      cache = parsedCache?.descriptions || {};
+    } catch (error) {
+      console.warn("Failed to read media description cache:", error.message);
+    }
+  }
+
+  // Find media files without descriptions
+  const mediaToDescribe = [];
+  const mediaHashMap = new Map();
+
+  const absoluteDocsDir = path.resolve(process.cwd(), docsDir);
+
+  // Only process media files that need AI description
+  for (const mediaFile of mediaFilesToProcess) {
+    // Convert relative path to absolute path for consistent hashing
+    // mediaFiles.path is relative to docsDir
+    const absolutePath = path.join(absoluteDocsDir, mediaFile.path);
+    const mediaHash = await calculateMediaHash(absolutePath);
+    mediaHashMap.set(mediaFile.path, mediaHash);
+
+    if (!cache[mediaHash]) {
+      mediaToDescribe.push({
+        ...mediaFile,
+        hash: mediaHash,
+        path: mediaFile.path,
+        mediaFile: [
+          {
+            type: "local",
+            path: absolutePath,
+            filename: mediaFile.name,
+            mimeType: mediaFile.mimeType,
+          },
+        ],
+      });
+    }
+  }
+
+  // Generate descriptions for media files without cache - use team agent for concurrent processing
+  const newDescriptions = {};
+  if (mediaToDescribe.length > 0) {
+    try {
+      // Use batch team agent for concurrent processing
+      const results = await options.context.invoke(
+        options.context.agents["batchGenerateMediaDescription"],
+        {
+          mediaToDescribe,
+        },
+      );
+
+      // Process results - results is an array of individual results
+      if (Array.isArray(results?.mediaToDescribe)) {
+        for (const result of results.mediaToDescribe) {
+          if (result?.hash && result?.description) {
+            newDescriptions[result.hash] = {
+              path: result.path,
+              description: result.description,
+              generatedAt: new Date().toISOString(),
+            };
+          }
+        }
+      }
+
+      // Merge new descriptions into cache
+      Object.assign(cache, newDescriptions);
+
+      // Save updated cache
+      await mkdir(path.dirname(cacheFilePath), { recursive: true });
+      const cacheYaml = stringify({
+        descriptions: cache,
+        lastUpdated: new Date().toISOString(),
+      });
+      await writeFile(cacheFilePath, cacheYaml, "utf8");
+
+      console.log(`Generated descriptions for ${Object.keys(newDescriptions).length} media files`);
+    } catch (error) {
+      console.error("Failed to generate media descriptions:", error.message);
+    }
+  }
+
+  // Build enhanced assetsContent with descriptions
+  let enhancedAssetsContent = "# Available Media Assets for Documentation\n\n";
+
+  if (mediaFiles.length > 0) {
+    enhancedAssetsContent += "```yaml\n";
+    enhancedAssetsContent += "assets:\n";
+
+    for (const asset of mediaFiles) {
+      enhancedAssetsContent += `  - name: "${asset.name}"\n`;
+      enhancedAssetsContent += `    path: "${asset.path}"\n`;
+      enhancedAssetsContent += `    type: "${asset.type}"\n`;
+
+      // Add description for images and videos
+      if (asset.type === "image" || asset.type === "video") {
+        const mediaHash = mediaHashMap.get(asset.path);
+        const cachedDesc = cache[mediaHash];
+        if (cachedDesc?.description) {
+          enhancedAssetsContent += `    description: "${cachedDesc.description}"\n`;
+        }
+      }
+
+      // Add dimensions for images and videos
+      if (asset.width && asset.height) {
+        enhancedAssetsContent += `    width: ${asset.width}\n`;
+        enhancedAssetsContent += `    height: ${asset.height}\n`;
+      }
+    }
+
+    enhancedAssetsContent += "```\n";
+  }
+
+  return {
+    ...input,
+    assetsContent: enhancedAssetsContent,
+    mediaFiles,
+  };
+}
+
+loadMediaDescription.input_schema = {
+  type: "object",
+  properties: {
+    mediaFiles: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          name: { type: "string" },
+          path: { type: "string" },
+          type: { type: "string" },
+          width: { type: "number" },
+          height: { type: "number" },
+          mimeType: { type: "string" },
+        },
+      },
+      description: "Array of media file objects (images/videos)",
+    },
+    docsDir: {
+      type: "string",
+      description: "Base directory for documentation",
+    },
+  },
+  required: ["mediaFiles", "docsDir"],
+};
+
+loadMediaDescription.output_schema = {
+  type: "object",
+  properties: {
+    assetsContent: {
+      type: "string",
+      description: "Enhanced assets content with media descriptions",
+    },
+    mediaFiles: {
+      type: "array",
+      description: "Array of media file objects",
+    },
+  },
+};

package/agents/publish/index.yaml

@@ -9,6 +9,7 @@ skills:
     default_input:
       skipIfExists: true
       checkOnly: true
+  - translate-meta.mjs
   - publish-docs.mjs
 input_schema:
   type: object
@@ -16,3 +17,6 @@ input_schema:
     appUrl:
       type: string
       description: Website URL where docs will be published (optional - leave empty for interactive setup)
+    with-branding:
+      type: boolean
+      description: Update your website branding (title, description, logo)