@aigne/doc-smith 0.9.9-beta → 0.9.9-beta.1

package/agents/utils/analyze-feedback-intent.mjs

@@ -1,88 +1,108 @@
 import { AIAgent } from "@aigne/core";
 import z from "zod";
+import { diagramImageWithPathRegex } from "../../utils/d2-utils.mjs";
+
+/**
+ * Detect existing diagram in document content using regex
+ * Uses generic regex patterns to detect diagram images inserted by the system
+ * @param {string} documentContent - Document content to analyze
+ * @returns {Object|null} - Diagram info if found, null otherwise
+ */
+function detectExistingDiagram(documentContent) {
+  if (!documentContent || typeof documentContent !== "string") {
+    return null;
+  }
+
+  // Use generic regex to detect diagram image blocks with special markers
+  // Format: <!-- DIAGRAM_IMAGE_START:type:aspectRatio -->![alt](path)<!-- DIAGRAM_IMAGE_END -->
+  const pathMatches = Array.from(documentContent.matchAll(diagramImageWithPathRegex));
+
+  if (pathMatches.length > 0) {
+    // Currently each document has only one diagram, so use the first one
+    const firstPathMatch = pathMatches[0];
+    const imagePath = firstPathMatch[4]; // Path is in capture group 4 (groups: 1=type, 2=aspectRatio, 3=timestamp, 4=path)
+    const fullMatch = firstPathMatch[0];
+
+    return {
+      path: imagePath,
+      index: 0,
+      markdown: fullMatch,
+    };
+  }
+
+  return null;
+}
 
 /**
  * Analyze user feedback to determine the intent type for document updates
- * Returns one of: "addDiagram", "deleteDiagram", "updateDiagram", "updateDocument"
- * Returns null if feedback is empty or invalid
+ * Supports two modes:
+ * - Global mode (no documentContent): Only analyzes feedback to determine intentType
+ * - Single document mode (with documentContent): Detects diagrams and provides full analysis
+ * Returns: { intentType, diagramInfo, generationMode, changes }
  */
-export default async function analyzeFeedbackIntent({ feedback, shouldUpdateDiagrams }, options) {
+export default async function analyzeFeedbackIntent(
+  { feedback, shouldUpdateDiagrams, documentContent },
+  options,
+) {
+  // Check if documentContent is available (single document mode vs global mode)
+  const hasDocumentContent =
+    documentContent && typeof documentContent === "string" && documentContent.trim();
+
   // Check if feedback exists and is not empty
   // If feedback is empty and --diagram flag is set, default to updateDiagram
-  // Otherwise return null
   if (!feedback || typeof feedback !== "string" || !feedback.trim()) {
     // If --diagram flag is set, default to updateDiagram (user wants to update diagrams)
     if (shouldUpdateDiagrams) {
-      return { intentType: "updateDiagram" };
+      const diagramInfo = hasDocumentContent ? detectExistingDiagram(documentContent) : null;
+      return {
+        intentType: "updateDiagram",
+        diagramInfo,
+        generationMode: diagramInfo ? "image-to-image" : "add-new",
+        changes: [],
+      };
     }
-    return { intentType: null };
+    // No feedback and no flag - return minimal structure
+    const diagramInfo = hasDocumentContent ? detectExistingDiagram(documentContent) : null;
+    return {
+      intentType: null,
+      diagramInfo,
+      generationMode: null,
+      changes: [],
+    };
   }
 
-  // Always analyze user feedback first, even if --diagram flag is set
-  // This ensures user's explicit intent (e.g., "remove image", "delete diagram") is respected
-  // The --diagram flag should only be a hint, not override explicit user commands
+  // Step 1: Detect existing diagram only if documentContent is available (single document mode)
+  const diagramInfo = hasDocumentContent ? detectExistingDiagram(documentContent) : null;
 
-  const instructions = `<role>
-You are a feedback intent analyzer. Your task is to determine which type of content modifications are needed based on the user's feedback.
+  // Step 2: Build instructions with diagram context (only in single document mode)
+  let diagramContextSection = "";
+  if (hasDocumentContent) {
+    if (diagramInfo) {
+      diagramContextSection = `The document contains an existing diagram: ${diagramInfo.path}`;
+    } else {
+      diagramContextSection = `The document does not contain any diagram images.`;
+    }
+  }
 
-You must analyze the user's feedback and classify it into one of the following intent types:
-- addDiagram: User wants to add a new diagram/image/chart
-- deleteDiagram: User wants to remove/delete a diagram/image/chart
+  const instructions = `Analyze the user feedback and classify the intent:
+
+**Intent Types:**
+- addDiagram: User wants to add/create a new diagram/image/chart
+- deleteDiagram: User wants to remove/delete an existing diagram/image/chart
 - updateDiagram: User wants to modify/update an existing diagram/image/chart
-- updateDocument: User wants to update document content (text, sections, etc.) without diagram operations
-</role>
-
-<intent_classification_rules>
-**deleteDiagram** - Use this when user explicitly wants to remove or delete a diagram/image/chart:
-- Keywords: remove, delete, 删除, 移除, 去掉, 清除
-- Combined with: diagram, image, picture, chart, graph, 图表, 图片, 图, 架构图
-- Examples:
-  - "Remove the diagram"
-  - "Delete the image"
-  - "删除这张图片"
-  - "Remove the second diagram"
-  - "去掉架构图"
-  - "Remove image from page 3"
-  - "Delete the chart showing the flow"
-
-**addDiagram** - Use this when user wants to add a new diagram:
-- Keywords: add, create, insert, 添加, 创建, 插入
-- Combined with: diagram, image, picture, chart, graph, 图表, 图片, 图
-- Examples:
-  - "Add a diagram showing the architecture"
-  - "Create a flow chart"
-  - "添加一个架构图"
-
-**updateDiagram** - Use this when user wants to modify an existing diagram:
-- Keywords: update, modify, change, improve, 更新, 修改, 改进
-- Combined with: diagram, image, picture, chart, graph, 图表, 图片, 图
-- Examples:
-  - "Update the diagram to show the new process"
-  - "Modify the chart to include more details"
-  - "更新架构图"
-
-**updateDocument** - Use this for all other content modifications:
-- Text changes, section updates, content improvements
-- No mention of diagrams/images/charts
-- Examples:
-  - "Update the introduction section"
-  - "Fix the typo in paragraph 2"
-  - "Improve the explanation"
-</intent_classification_rules>
-
-<user_feedback>
-{{feedback}}
-</user_feedback>
-
-<analysis_guidelines>
-1. Pay close attention to action verbs (remove, delete, add, update, etc.)
-2. Identify the target object (diagram, image, chart, or general content)
-3. If feedback mentions removing/deleting a diagram/image/chart → deleteDiagram
-4. If feedback mentions adding a diagram/image/chart → addDiagram
-5. If feedback mentions updating a diagram/image/chart → updateDiagram
-6. If feedback is about general content without diagram references → updateDocument
-7. When in doubt, prioritize the most explicit action mentioned in the feedback
-</analysis_guidelines>`;
+- updateDocument: User wants to update text/content (not diagram-related)
+
+${diagramContextSection ? `**Context:** ${diagramContextSection}` : ""}
+
+**User Feedback:**
+${feedback.trim()}
+
+**For updateDiagram, determine generationMode:**
+- "image-to-image": Diagram exists AND user describes changes (default when diagram exists)
+- "text-only": User explicitly requests regenerating from text only
+- "add-new": No existing diagram
+
+Analyze the feedback and return the intent type, generationMode (if applicable), and any specific changes mentioned.`;
 
   try {
     const analyzeUpdateFeedbackIntentAgent = AIAgent.from({
@@ -93,6 +113,14 @@ You must analyze the user's feedback and classify it into one of the following i
       instructions,
       inputSchema: z.object({
         feedback: z.string().describe("User feedback for content modifications"),
+        diagramInfo: z
+          .object({
+            path: z.string(),
+            index: z.number(),
+            markdown: z.string(),
+          })
+          .nullable()
+          .describe("Existing diagram information if found, null otherwise"),
       }),
       outputSchema: z.object({
         intentType: z
@@ -100,36 +128,125 @@ You must analyze the user's feedback and classify it into one of the following i
           .describe(
             "The primary type of user intention: one of addDiagram, deleteDiagram, updateDiagram, updateDocument",
           ),
+        generationMode: z
+          .enum(["image-to-image", "text-only", "add-new", "remove-image"])
+          .optional()
+          .describe(
+            "Generation mode for diagram operations. Only relevant for addDiagram/updateDiagram. 'image-to-image' for modifying existing, 'text-only' for regenerating from text, 'add-new' for creating new.",
+          ),
+        changes: z
+          .array(z.string())
+          .optional()
+          .describe(
+            "Specific changes mentioned in feedback (e.g., ['add node: database', 'modify style: modern']). Only relevant for updateDiagram.",
+          ),
       }),
     });
 
-    const { intentType } = await options.context.invoke(analyzeUpdateFeedbackIntentAgent, {
+    const llmInput = {
       feedback: feedback.trim(),
-    });
+      diagramInfo,
+    };
+    const llmResult = await options.context.invoke(analyzeUpdateFeedbackIntentAgent, llmInput);
+
+    // Handle case where LLM returns null, undefined, or invalid result
+    if (!llmResult || typeof llmResult !== "object") {
+      throw new Error(`LLM returned invalid result: ${JSON.stringify(llmResult)}`);
+    }
+
+    let { intentType, generationMode, changes } = llmResult;
+
+    // If LLM returned null/undefined intentType, try to infer from feedback content
+    if (!intentType) {
+      const feedbackLower = feedback.toLowerCase();
+      const hasDiagramTerms =
+        feedbackLower.includes("图") ||
+        feedbackLower.includes("diagram") ||
+        feedbackLower.includes("chart") ||
+        feedbackLower.includes("节点") ||
+        feedbackLower.includes("node");
+
+      if (hasDiagramTerms && diagramInfo) {
+        intentType = "updateDiagram";
+      } else if (hasDiagramTerms && !diagramInfo) {
+        intentType = "addDiagram";
+      } else {
+        intentType = "updateDocument";
+      }
+    }
 
     // If --diagram flag is set and user didn't explicitly request delete/add,
     // default to updateDiagram (for backward compatibility)
-    // But if user explicitly requested delete/add, respect that intent
     if (
       shouldUpdateDiagrams &&
       intentType &&
       !["deleteDiagram", "addDiagram"].includes(intentType)
     ) {
-      return { intentType: "updateDiagram" };
+      intentType = "updateDiagram";
     }
 
-    return { intentType };
+    // Set default generationMode based on intentType and diagramInfo if not provided by LLM
+    if (!generationMode) {
+      if (intentType === "deleteDiagram") {
+        generationMode = "remove-image";
+      } else if (intentType === "addDiagram") {
+        generationMode = "add-new";
+      } else if (intentType === "updateDiagram") {
+        generationMode = diagramInfo ? "image-to-image" : "add-new";
+      }
+    }
+
+    // Ensure we always have a valid intentType at this point
+    if (!intentType) {
+      intentType = "updateDocument";
+      generationMode = generationMode || null;
+    }
+
+    return {
+      intentType,
+      diagramInfo,
+      generationMode,
+      changes: changes || [],
+    };
   } catch (error) {
+    console.warn(`[analyzeFeedbackIntent] Failed to analyze feedback intent: ${error.message}`);
+
     // If analysis fails and --diagram flag is set, default to updateDiagram
-    // Otherwise return null to fall back to default document update flow
     if (shouldUpdateDiagrams) {
-      console.warn(
-        `Failed to analyze feedback intent, defaulting to updateDiagram due to --diagram flag: ${error.message}`,
-      );
-      return { intentType: "updateDiagram" };
+      return {
+        intentType: "updateDiagram",
+        diagramInfo,
+        generationMode: diagramInfo ? "image-to-image" : "add-new",
+        changes: [],
+      };
     }
-    console.warn(`Failed to analyze feedback intent: ${error.message}`);
-    return { intentType: null };
+
+    // Fallback: try to infer intent from feedback content
+    const feedbackLower = feedback.toLowerCase();
+    const hasDiagramTerms =
+      feedbackLower.includes("图") ||
+      feedbackLower.includes("diagram") ||
+      feedbackLower.includes("chart") ||
+      feedbackLower.includes("节点") ||
+      feedbackLower.includes("node");
+
+    let fallbackIntentType = "updateDocument";
+    let fallbackGenerationMode = null;
+
+    if (hasDiagramTerms && diagramInfo) {
+      fallbackIntentType = "updateDiagram";
+      fallbackGenerationMode = "image-to-image";
+    } else if (hasDiagramTerms && !diagramInfo) {
+      fallbackIntentType = "addDiagram";
+      fallbackGenerationMode = "add-new";
+    }
+
+    return {
+      intentType: fallbackIntentType,
+      diagramInfo,
+      generationMode: fallbackGenerationMode,
+      changes: [],
+    };
   }
 }
 

package/agents/utils/check-detail-result.mjs

@@ -1,7 +1,20 @@
 import { buildAllowedLinksFromStructure } from "../../utils/docs-finder-utils.mjs";
 import { checkMarkdown } from "../../utils/markdown-checker.mjs";
 
-export default async function checkDetailResult({ documentStructure, reviewContent, docsDir }) {
+export default async function checkDetailResult({
+  documentStructure,
+  reviewContent,
+  docsDir,
+  isApproved: preApproved,
+}) {
+  // If already approved (e.g., --diagram mode), skip validation
+  if (preApproved === true) {
+    return {
+      isApproved: true,
+      detailFeedback: "",
+    };
+  }
+
   if (!reviewContent || reviewContent.trim() === "") {
     return {
       isApproved: false,

package/agents/utils/choose-docs.mjs

@@ -9,7 +9,6 @@ import {
 } from "../../utils/docs-finder-utils.mjs";
 import {
   hasDiagramContent,
-  hasBananaImages,
   getDiagramTypeLabels,
   formatDiagramTypeSuffix,
 } from "../../utils/check-document-has-diagram.mjs";
@@ -37,7 +36,6 @@ export default async function chooseDocs(
     action,
     shouldUpdateDiagrams = false,
     shouldAutoSelectDiagrams = false,
-    shouldSyncImages = false,
   },
   options,
 ) {
@@ -59,41 +57,8 @@ export default async function chooseDocs(
         );
       }
 
-      // If --diagram-sync flag is set, filter documents by banana images only
-      if (shouldSyncImages) {
-        debug("🔄 Filtering documents with banana images...");
-
-        // Read content for all files and filter by banana images only
-        const filesWithImages = [];
-        for (const fileName of mainLanguageFiles) {
-          const content = await readFileContent(docsDir, fileName);
-          if (content && hasBananaImages(content)) {
-            filesWithImages.push(fileName);
-          }
-        }
-
-        if (filesWithImages.length === 0) {
-          debug("ℹ️  No documents found with banana images (DIAGRAM_IMAGE_START markers).");
-          return {
-            selectedDocs: [],
-            feedback: "",
-            selectedPaths: [],
-          };
-        }
-
-        debug(`✅ Found ${filesWithImages.length} document(s) with banana images.`);
-        debug("📋 Auto-selecting all documents with banana images...");
-        // Show diagram types for each document
-        for (const file of filesWithImages) {
-          const content = await readFileContent(docsDir, file);
-          const diagramLabels = content ? getDiagramTypeLabels(content) : [];
-          const diagramSuffix = formatDiagramTypeSuffix(diagramLabels);
-          debug(`   • ${file}${diagramSuffix}`);
-        }
-        selectedFiles = filesWithImages;
-      }
       // If --diagram flag is set, filter documents by diagram content
-      else if (shouldUpdateDiagrams) {
+      if (shouldUpdateDiagrams) {
         debug("🔄 Filtering documents with diagram content...");
 
         // Read content for all files and filter by diagram content
@@ -257,14 +222,9 @@ export default async function chooseDocs(
   }
 
   // Prompt for feedback if not provided
-  // Skip feedback prompt if --diagram, --diagram-all, or --diagram-sync flag is set
+  // Skip feedback prompt if --diagram or --diagram-all flag is set
   let userFeedback = feedback;
-  if (
-    !userFeedback &&
-    (requiredFeedback || foundItems?.length > 1) &&
-    !shouldUpdateDiagrams &&
-    !shouldSyncImages
-  ) {
+  if (!userFeedback && (requiredFeedback || foundItems?.length > 1) && !shouldUpdateDiagrams) {
     const feedbackMessage = getFeedbackMessage(docAction);
 
     userFeedback = await options.prompts.input({

package/agents/utils/save-doc-translation.mjs

@@ -1,8 +1,4 @@
 import { saveDocTranslation as _saveDocTranslation } from "../../utils/utils.mjs";
-import { readFileContent } from "../../utils/docs-finder-utils.mjs";
-import { getFileName } from "../../utils/utils.mjs";
-import { debug } from "../../utils/debug.mjs";
-import { syncDiagramToTranslations } from "../../utils/sync-diagram-to-translations.mjs";
 
 export default async function saveDocTranslation({
   path,
@@ -11,7 +7,6 @@ export default async function saveDocTranslation({
   language,
   labels,
   isShowMessage = false,
-  locale,
 }) {
   await _saveDocTranslation({
     path,
@@ -21,34 +16,8 @@ export default async function saveDocTranslation({
     labels,
   });
 
-  // Sync diagram images from main document to translations
-  // This ensures all images (including diagrams) in the main document are synced to translation files
-  if (path && docsDir && locale) {
-    try {
-      // Read main document content (it should already be saved)
-      const mainFileName = getFileName(path, locale);
-      const mainContent = await readFileContent(docsDir, mainFileName);
-
-      if (mainContent) {
-        const syncResult = await syncDiagramToTranslations(
-          mainContent,
-          path,
-          docsDir,
-          locale,
-          "sync",
-        );
-
-        if (syncResult.updated > 0) {
-          debug(
-            `✅ Synced diagram images to ${syncResult.updated} translation file(s) after translation`,
-          );
-        }
-      }
-    } catch (error) {
-      // Don't fail the translation if sync fails
-      debug(`⚠️  Failed to sync diagram images after translation: ${error.message}`);
-    }
-  }
+  // Note: Diagram image translation is now handled by translate-diagram-images.mjs
+  // in the translate workflow, which compares timestamps and only translates when needed
 
   if (isShowMessage) {
     const message = `✅ Translation completed successfully.`;

package/agents/utils/save-doc.mjs

@@ -1,6 +1,5 @@
 import { shutdownMermaidWorkerPool } from "../../utils/mermaid-worker-pool.mjs";
 import { saveDoc as _saveDoc } from "../../utils/utils.mjs";
-import { debug } from "../../utils/debug.mjs";
 
 export default async function saveDoc({
   path,
@@ -22,42 +21,9 @@ export default async function saveDoc({
     locale,
   });
 
-  // Sync diagram changes to translation documents if needed
-  // Only sync for diagram-related operations (addDiagram, updateDiagram, deleteDiagram)
-  if (
-    docsDir &&
-    path &&
-    intentType &&
-    ["addDiagram", "updateDiagram", "deleteDiagram"].includes(intentType)
-  ) {
-    try {
-      const { syncDiagramToTranslations } = await import(
-        "../../utils/sync-diagram-to-translations.mjs"
-      );
-
-      // Determine operation type for sync
-      // deleteDiagram -> "delete" (process even if 0 diagrams)
-      // addDiagram/updateDiagram -> "update" (skip if 0 diagrams)
-      const operationType = intentType === "deleteDiagram" ? "delete" : "update";
-
-      const syncResult = await syncDiagramToTranslations(
-        content,
-        path,
-        docsDir,
-        locale || "en",
-        operationType,
-      );
-
-      if (syncResult.updated > 0) {
-        debug(
-          `✅ Synced diagram changes to ${syncResult.updated} translation file(s) for ${intentType}`,
-        );
-      }
-    } catch (error) {
-      // Don't fail the operation if sync fails
-      debug(`⚠️  Failed to sync diagram to translations: ${error.message}`);
-    }
-  }
+  // Note: Diagram image translation is handled separately during translate operation
+  // In update/add operations, we only update the main document with timestamp
+  // Translation documents will be updated during translate operation when timestamps differ
 
   if (isShowMessage) {
     // Shutdown mermaid worker pool to ensure clean exit

package/aigne.yaml

@@ -80,6 +80,7 @@ agents:
   - ./agents/utils/feedback-refiner.yaml
   - ./agents/utils/analyze-structure-feedback-intent.yaml
   - ./agents/utils/analyze-document-feedback-intent.yaml
+  - ./agents/utils/analyze-feedback-intent.mjs
 
   - ./agents/utils/document-title-streamline.yaml
   - ./agents/utils/streamline-document-titles-if-needed.mjs
@@ -112,8 +113,7 @@ agents:
   - ./agents/update/generate-diagram.yaml
   - ./agents/update/check-generate-diagram.mjs
   - ./agents/update/pre-check-generate-diagram.yaml
-  - ./agents/update/check-sync-image-flag.mjs
-  - ./agents/update/sync-images-and-exit.mjs
+  - ./agents/localize/translate-diagram.yaml
 cli:
   chat: ./agents/chat/index.mjs
   agents:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.9.9-beta",
+  "version": "0.9.9-beta.1",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"

package/prompts/detail/diagram/generate-image-user.md

@@ -1,3 +1,51 @@
+{% if useImageToImage and existingImage %}
+# Image-to-Image Generation Mode
+
+Your task is to **update an existing diagram** based on the current document content and user feedback.
+
+**CRITICAL INSTRUCTIONS:**
+1. **Use the existing image as the primary reference** - maintain its overall structure, layout, and visual style
+2. **Analyze the document content** to understand what changes are needed
+3. **Apply user feedback** to modify the diagram appropriately
+4. **Maintain visual consistency** - keep the same style, color scheme, and general layout unless explicitly requested to change
+5. **Make maximum changes** where needed - update content, add/remove elements, adjust relationships based on the document
+6. **Preserve what works** - keep elements that are still accurate and relevant
+
+**Task Parameters:**
+- **Diagram Type:** {{ diagramType }}
+- **Visual Style:** {{ diagramStyle }} (maintain consistency with existing image unless feedback requests change)
+- **Aspect Ratio:** {{ aspectRatio }}
+- **Language:** English
+
+**Existing Diagram:**
+[The existing diagram image is provided as input to the model]
+
+**Document Content:**
+{% if documentSummary %}
+{{ documentSummary }}
+{% else %}
+{{ documentContent }}
+{% endif %}
+
+**User Feedback:**
+{{ feedback if feedback else "Update the diagram to match the current document content." }}
+
+**Your responsibilities:**
+1. Analyze the existing diagram structure, style, and layout
+2. Review the document content to identify what needs to be updated
+3. Apply user feedback to modify the diagram
+4. Maintain visual consistency with the original design where appropriate
+5. Update the diagram to accurately reflect the current document content
+6. Make necessary changes while preserving the overall visual style and structure
+
+**Style Consistency:**
+- Keep the same visual style as the existing image unless user feedback explicitly requests a style change
+- Maintain color scheme, node shapes, and layout patterns
+- Preserve the overall aesthetic and design language
+
+{% else %}
+# Standard Text-to-Image Generation Mode
+
 Your task is to create a professional diagram image based on the document content below.
 
 Please follow **all global rules, styles, aspect ratio logic, and diagram-type rules** defined in the system prompt.
@@ -30,3 +78,4 @@ Now analyze the following document content to understand what should be drawn:
 {% endif %}
 
 (Use this content to determine node structure, relationships, and flow.)
+{% endif %}

package/utils/d2-utils.mjs

@@ -12,15 +12,22 @@ export const DIAGRAM_PLACEHOLDER = "DIAGRAM_PLACEHOLDER";
 
 // Diagram image regex patterns for reuse across the codebase
 // Pattern 1: Match only the start marker (for checking existence)
-export const diagramImageStartRegex = /<!--\s*DIAGRAM_IMAGE_START:[^>]+-->/g;
+export const diagramImageStartRegex =
+  /<!--\s*DIAGRAM_IMAGE_START:([A-Za-z0-9_-]+):(\d+:\d+)(:\d+)?\s*-->/g;
 
 // Pattern 2: Match full diagram image block without capturing image path (for finding/replacing)
+// Supports both old format (without aspectRatio) and new format (with aspectRatio)
 export const diagramImageBlockRegex =
-  /<!--\s*DIAGRAM_IMAGE_START:[^>]+-->\s*[\s\S]*?<!--\s*DIAGRAM_IMAGE_END\s*-->/g;
+  /<!--\s*DIAGRAM_IMAGE_START:([A-Za-z0-9_-]+)(?::(\d+:\d+))?(:\d+)?\s*-->\s*[\s\S]*?<!--\s*DIAGRAM_IMAGE_END\s*-->/g;
 
 // Pattern 3: Match full diagram image block with image path capture (for extracting paths)
+// Compatible with old format (without timestamp): <!-- DIAGRAM_IMAGE_START:type:aspectRatio -->
 export const diagramImageWithPathRegex =
-  /<!--\s*DIAGRAM_IMAGE_START:[^>]+-->\s*!\[[^\]]*\]\(([^)]+)\)\s*<!--\s*DIAGRAM_IMAGE_END\s*-->/g;
+  /<!--\s*DIAGRAM_IMAGE_START:([A-Za-z0-9_-]+):(\d+:\d+)(:\d+)?\s*-->\s*!\[[^\]]*\]\(([^)]+)\)\s*<!--\s*DIAGRAM_IMAGE_END\s*-->/g;
+
+// Pattern 4: Match full diagram image block with all details (type, aspectRatio, timestamp, path, altText)
+export const diagramImageFullRegex =
+  /<!--\s*DIAGRAM_IMAGE_START:([A-Za-z0-9_-]+):(\d+:\d+)(:\d+)?\s*-->\s*!\[([^\]]*)\]\(([^)]+)\)\s*<!--\s*DIAGRAM_IMAGE_END\s*-->/g;
 
 export async function ensureTmpDir() {
   const tmpDir = path.join(DOC_SMITH_DIR, TMP_DIR);

package/utils/delete-diagram-images.mjs

@@ -2,6 +2,7 @@ import { unlink } from "node:fs/promises";
 import { join, dirname, normalize } from "node:path";
 import fs from "fs-extra";
 import { debug } from "./debug.mjs";
+import { diagramImageWithPathRegex } from "./d2-utils.mjs";
 
 /**
  * Extract image file paths from markdown content
@@ -19,11 +20,10 @@ export async function extractDiagramImagePaths(content, path, docsDir) {
   const imagePaths = [];
 
   // Pattern to match: <!-- DIAGRAM_IMAGE_START:... -->![alt](path)<!-- DIAGRAM_IMAGE_END -->
-  const { diagramImageWithPathRegex } = await import("./d2-utils.mjs");
-  const matches = Array.from(content.matchAll(diagramImageWithPathRegex));
+  const matches = Array.from((content || "").matchAll(diagramImageWithPathRegex));
 
   for (const match of matches) {
-    const imagePath = match[1];
+    const imagePath = match[4] || ""; // Path is in capture group 4 (groups: 1=type, 2=aspectRatio, 3=timestamp, 4=path)
 
     // Resolve absolute path
     // If imagePath is relative, resolve from document location