@aigne/doc-smith 0.8.12-beta.6 → 0.8.12-beta.8

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/generate/update-document-structure.yaml

@@ -32,11 +32,17 @@ input_schema:
     - documentStructure
     - feedback
 output_key: message
+afs:
+  modules:
+    - module: system-fs
+      options:
+        mount: /sources
+        path: .
+        description: |
+          Codebase of the project to be documented used as context for document generation,
+          should search and read as needed while generating document content
 skills:
   - ./document-structure-tools/add-document.mjs
   - ./document-structure-tools/delete-document.mjs
   - ./document-structure-tools/update-document.mjs
   - ./document-structure-tools/move-document.mjs
-  - ../update/fs-tools/glob.mjs
-  - ../update/fs-tools/grep.mjs
-  - ../update/fs-tools/read-file.mjs

package/agents/history/view.mjs

@@ -1,4 +1,5 @@
 import chalk from "chalk";
+import { createHash } from "node:crypto";
 import { getHistory } from "../../utils/history-utils.mjs";
 
 export default function viewHistory() {
@@ -35,8 +36,10 @@ export default function viewHistory() {
  * Generate a short hash from timestamp (git-style)
  */
 function generateShortHash(timestamp) {
-  const hash = timestamp.replace(/[-:.TZ]/g, "");
-  return hash.substring(hash.length - 7); // Last 7 chars
+  // Create a deterministic hash from timestamp only
+  // This ensures the same timestamp always produces the same hash
+  const hash = createHash("sha1").update(timestamp).digest("hex");
+  return hash.substring(0, 8); // First 8 chars of SHA1 hash
 }
 
 /**

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/update/generate-document.yaml

@@ -45,10 +45,16 @@ input_schema:
     - datasources
     - originalDocumentStructure
 output_key: content
-skills:
-  - fs-tools/glob.mjs
-  - fs-tools/grep.mjs
-  - fs-tools/read-file.mjs
+afs:
+  modules:
+    - module: system-fs
+      options:
+        mount: /sources
+        path: .
+        description: |
+          Codebase of the project to be documented used as context for document generation,
+          should search and read as needed while generating document content
+# skills:
   # FIXME: @zhanghan temporary disable diagram tool
   # - type: team
   #   task_render_mode: collapse

package/agents/update/index.yaml

@@ -30,6 +30,7 @@ skills:
     default_input:
       requiredFeedback: false
   - ../utils/format-document-structure.mjs
+  - ../media/load-media-description.mjs
   - ../update/check-update-is-single.mjs
   - ../update/save-and-translate-document.mjs
   - url: ../utils/action-success.mjs

package/agents/update/update-document-detail.yaml

@@ -44,9 +44,15 @@ input_schema:
     - originalContent
     - feedback
 output_key: message
+afs:
+  modules:
+    - module: system-fs
+      options:
+        mount: /sources
+        path: .
+        description: |
+          Codebase of the project to be documented used as context for document generation,
+          should search and read as needed while generating document content
 skills:
   - ./document-tools/update-document-content.mjs
-  - ./fs-tools/glob.mjs
-  - ./fs-tools/grep.mjs
-  - ./fs-tools/read-file.mjs
 task_render_mode: collapse

package/agents/update/user-review-document.mjs

@@ -242,7 +242,8 @@ export default async function userReviewDocument(
         console.error(`Stack: ${error.stack}`);
       }
       console.log("\nPlease try rephrasing your feedback or continue with the current content.");
-      break;
+
+      process.exit(0);
     }
   }