@aigne/doc-smith 0.9.7 → 0.9.8-beta

package/agents/update/sync-images-and-exit.mjs

@@ -0,0 +1,148 @@
+import { syncDiagramToTranslations } from "../../utils/sync-diagram-to-translations.mjs";
+import { readFileContent } from "../../utils/docs-finder-utils.mjs";
+import { getFileName } from "../../utils/utils.mjs";
+import { debug } from "../../utils/debug.mjs";
+
+/**
+ * Sync images to translations and exit if shouldSyncImages is true
+ * Otherwise, passes through input for normal update flow
+ *
+ * This agent combines:
+ * - Image synchronization logic
+ * - Flow routing (sync vs normal update)
+ * - Early exit handling
+ */
+export default async function syncImagesAndExit(input, options) {
+  // If shouldSyncImages is false, pass through for normal update flow
+  if (!input.shouldSyncImages) {
+    return input;
+  }
+
+  // Sync images flow
+  const { selectedDocs = [], docsDir, locale = "en" } = input;
+
+  if (!docsDir) {
+    throw new Error("docsDir is required for image sync. Please ensure config is loaded.");
+  }
+
+  if (!Array.isArray(selectedDocs) || selectedDocs.length === 0) {
+    const actionSuccessAgent = options.context?.agents?.["actionSuccess"];
+    if (actionSuccessAgent) {
+      await options.context.invoke(actionSuccessAgent, {
+        action: "ℹ️  No documents selected for image sync",
+      });
+    }
+    // Exit normally to prevent passing to next steps
+    process.exit(0);
+  }
+
+  const results = {
+    updated: 0,
+    skipped: 0,
+    errors: [],
+  };
+
+  // Process each document
+  for (const doc of selectedDocs) {
+    try {
+      // Use content from doc if available, otherwise read from file
+      let mainContent = doc.content;
+      if (!mainContent) {
+        const mainFileName = getFileName(doc.path, locale);
+        mainContent = await readFileContent(docsDir, mainFileName);
+      }
+
+      if (!mainContent) {
+        debug(`⚠️  Could not read main document: ${doc.path}`);
+        results.skipped++;
+        continue;
+      }
+
+      // Sync images to translation documents
+      const syncResult = await syncDiagramToTranslations(mainContent, doc.path, docsDir, locale);
+
+      results.updated += syncResult.updated;
+      results.skipped += syncResult.skipped;
+      results.errors.push(...syncResult.errors);
+
+      if (syncResult.updated > 0) {
+        debug(`✅ Synced images from ${doc.path} to ${syncResult.updated} translation file(s)`);
+      } else if (syncResult.skipped > 0) {
+        debug(
+          `⏭️  No changes needed for ${doc.path} (${syncResult.skipped} translation file(s) already in sync)`,
+        );
+      }
+    } catch (error) {
+      debug(`❌ Error syncing images for ${doc.path}: ${error.message}`);
+      results.errors.push({
+        doc: doc.path,
+        error: error.message,
+      });
+    }
+  }
+
+  // Generate success message
+  const message = `✅ Image sync completed: ${results.updated} translation file(s) updated, ${results.skipped} skipped${
+    results.errors.length > 0 ? `, ${results.errors.length} error(s)` : ""
+  }`;
+
+  // Show success message
+  const actionSuccessAgent = options.context?.agents?.["actionSuccess"];
+  if (actionSuccessAgent) {
+    await options.context.invoke(actionSuccessAgent, {
+      action: message,
+    });
+  }
+
+  // Exit normally to prevent passing to next steps and avoid validation errors
+  // This ensures a clean exit after successful image sync
+  process.exit(0);
+}
+
+syncImagesAndExit.input_schema = {
+  type: "object",
+  properties: {
+    shouldSyncImages: {
+      type: "boolean",
+      description: "Whether to trigger image sync to translations",
+    },
+    selectedDocs: {
+      type: "array",
+      description: "Array of selected documents to sync images from",
+    },
+    docsDir: {
+      type: "string",
+      description: "Documentation directory where documents are stored",
+    },
+    locale: {
+      type: "string",
+      description: "Main language locale (e.g., 'en', 'zh')",
+      default: "en",
+    },
+  },
+  required: ["shouldSyncImages"],
+};
+
+syncImagesAndExit.output_schema = {
+  type: "object",
+  properties: {
+    message: {
+      type: "string",
+      description: "Summary message of the sync operation",
+    },
+    updated: {
+      type: "number",
+      description: "Number of translation files successfully updated",
+    },
+    skipped: {
+      type: "number",
+      description: "Number of translation files skipped (no changes needed)",
+    },
+    errors: {
+      type: "array",
+      description: "Array of errors encountered during sync",
+    },
+  },
+};
+
+syncImagesAndExit.task_render_mode = "hide";

package/agents/update/update-single/update-single-document-detail.mjs

@@ -4,18 +4,72 @@ import z from "zod";
 import {
   DIAGRAM_PLACEHOLDER,
   replaceD2WithPlaceholder,
-  replacePlaceholderWithD2,
+  replaceDiagramsWithPlaceholder,
 } from "../../../utils/d2-utils.mjs";
 import { userContextAt } from "../../../utils/utils.mjs";
 
 async function getIntentType(input, options) {
   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.
+
+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
+- 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>`;
+</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>`;
   const analyzeUpdateFeedbackIntentAgent = AIAgent.from({
     name: "analyzeUpdateFeedbackIntent",
     description:
@@ -43,11 +97,12 @@ You are a feedback intent analyzer. Your task is to determine which type of cont
   return intentType;
 }
 
-async function saveDoc(input, options, { content }) {
+async function saveDoc(input, options, { content, intentType }) {
   const saveAgent = options.context?.agents?.["saveDoc"];
   await options.context.invoke(saveAgent, {
     ...pick(input, ["path", "docsDir", "labels", "locale"]),
     content,
+    intentType, // Pass intentType so saveDoc can handle translation sync
   });
 }
 
@@ -56,42 +111,70 @@ async function addDiagram(input, options) {
   const currentContent = contentContext.get();
   const generateDiagramAgent = options.context.agents["checkGenerateDiagram"];
   const generateDiagramResult = await options.context.invoke(generateDiagramAgent, {
-    ...pick(input, ["locale", "path", "diagramming", "feedback"]),
+    ...pick(input, ["locale", "path", "docsDir", "diagramming", "feedback"]),
     documentContent: currentContent,
+    originalContent: currentContent,
   });
   const content = generateDiagramResult.content;
   contentContext.set(content);
-  await saveDoc(input, options, { content });
+  // Pass intentType to saveDoc so it can handle translation sync automatically
+  await saveDoc(input, options, { content, intentType: "addDiagram" });
   return { content };
 }
 
 async function updateDiagram(input, options) {
   const contentContext = userContextAt(options, `currentContents.${input.path}`);
   const currentContent = contentContext.get();
-  let [content, previousDiagramContent] = replaceD2WithPlaceholder({
+  let [content] = replaceD2WithPlaceholder({
     content: currentContent,
   });
   const generateAgent = options.context?.agents?.["generateDiagram"];
-  const { diagramSourceCode } = await options.context.invoke(generateAgent, {
+  const result = await options.context.invoke(generateAgent, {
     documentContent: content,
     locale: input.locale,
-    previousDiagramContent,
+    diagramming: input.diagramming || {},
     feedback: input.feedback,
+    originalContent: currentContent, // Pass original content to find existing diagrams
+    path: input.path,
+    docsDir: input.docsDir,
   });
-  content = replacePlaceholderWithD2({
-    content,
-    diagramSourceCode,
-  });
+
+  // generateDiagram now returns { content } with image already inserted
+  // The image replaces DIAGRAM_PLACEHOLDER or D2 code blocks
+  if (result?.content) {
+    content = result.content;
+  }
+
   contentContext.set(content);
-  await saveDoc(input, options, { content });
+  // Pass intentType to saveDoc so it can handle translation sync automatically
+  await saveDoc(input, options, { content, intentType: "updateDiagram" });
   return { content };
 }
 
 async function deleteDiagram(input, options) {
   const contentContext = userContextAt(options, `currentContents.${input.path}`);
   const currentContent = contentContext.get();
-  const [documentContent] = replaceD2WithPlaceholder({
+
+  // Extract diagram index from feedback if provided
+  // This allows deleting a specific diagram when multiple diagrams exist
+  let diagramIndex = input.diagramIndex;
+  if (diagramIndex === undefined && input.feedback) {
+    // Import extractDiagramIndexFromFeedback from replace-d2-with-image.mjs
+    const { extractDiagramIndexFromFeedback } = await import(
+      "../../create/replace-d2-with-image.mjs"
+    );
+    const extractedIndex = extractDiagramIndexFromFeedback(input.feedback);
+    if (extractedIndex !== null) {
+      diagramIndex = extractedIndex;
+    }
+  }
+
+  // Replace all diagrams (D2 code blocks, generated images, Mermaid) with placeholder
+  // If diagramIndex is provided, only replace that specific diagram
+  // This ensures LLM can identify and remove the diagram regardless of its type
+  const documentContent = replaceDiagramsWithPlaceholder({
     content: currentContent,
+    diagramIndex,
   });
   const instructions = `<role>
 Your task is to remove ${DIAGRAM_PLACEHOLDER} and adjust the document context (based on the user's feedback) to make it easier to understand.
@@ -123,8 +206,24 @@ Your task is to remove ${DIAGRAM_PLACEHOLDER} and adjust the document context (b
     documentContent,
     feedback: input.feedback,
   });
+
+  // Delete associated diagram image files
+  if (input.docsDir) {
+    try {
+      const { deleteDiagramImages } = await import("../../../utils/delete-diagram-images.mjs");
+      const { deleted } = await deleteDiagramImages(currentContent, input.path, input.docsDir);
+      if (deleted > 0) {
+        console.log(`Deleted ${deleted} diagram image file(s) for ${input.path}`);
+      }
+    } catch (error) {
+      // Don't fail the operation if image deletion fails
+      console.warn(`Failed to delete diagram images: ${error.message}`);
+    }
+  }
+
   contentContext.set(content);
-  await saveDoc(input, options, { content });
+  // Pass intentType to saveDoc so it can handle translation sync automatically
+  await saveDoc(input, options, { content, intentType: "deleteDiagram" });
 
   return { content };
 }
@@ -149,7 +248,19 @@ async function updateDocument(input, options) {
 }
 
 export default async function updateSingleDocumentDetail(input, options) {
-  const intentType = await getIntentType(input, options);
+  // Use intentType from input if available (analyzed in parent flow),
+  // otherwise fall back to analyzing it here (for backward compatibility)
+  let intentType = input.intentType;
+  if (!intentType && input.feedback) {
+    intentType = await getIntentType(input, options);
+  }
+
+  // If intentType is still null or undefined, default to updateDocument
+  // This ensures that some operation is always performed, even if intent analysis failed
+  // or no explicit intent was provided
+  if (!intentType) {
+    intentType = "updateDocument";
+  }
 
   const fnMap = {
     addDiagram,
@@ -162,5 +273,8 @@ export default async function updateSingleDocumentDetail(input, options) {
     const result = await fnMap[intentType](input, options);
     return result;
   }
-  return {};
+
+  // Fallback: if intentType is not in fnMap, default to updateDocument
+  console.warn(`Unknown intentType: ${intentType}, defaulting to updateDocument`);
+  return await updateDocument(input, options);
 }

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

@@ -0,0 +1,136 @@
+import { AIAgent } from "@aigne/core";
+import z from "zod";
+
+/**
+ * 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
+ */
+export default async function analyzeFeedbackIntent({ feedback, shouldUpdateDiagrams }, options) {
+  // 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" };
+    }
+    return { intentType: null };
+  }
+
+  // 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
+
+  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.
+
+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
+- 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>`;
+
+  try {
+    const analyzeUpdateFeedbackIntentAgent = AIAgent.from({
+      name: "analyzeUpdateFeedbackIntent",
+      description:
+        "Analyze user feedback to determine if document are needed for content modifications",
+      task_render_mode: "hide",
+      instructions,
+      inputSchema: z.object({
+        feedback: z.string().describe("User feedback for content modifications"),
+      }),
+      outputSchema: z.object({
+        intentType: z
+          .enum(["addDiagram", "deleteDiagram", "updateDiagram", "updateDocument"])
+          .describe(
+            "The primary type of user intention: one of addDiagram, deleteDiagram, updateDiagram, updateDocument",
+          ),
+      }),
+    });
+
+    const { intentType } = await options.context.invoke(analyzeUpdateFeedbackIntentAgent, {
+      feedback: feedback.trim(),
+    });
+
+    // 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" };
+    }
+
+    return { intentType };
+  } catch (error) {
+    // 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" };
+    }
+    console.warn(`Failed to analyze feedback intent: ${error.message}`);
+    return { intentType: null };
+  }
+}
+
+analyzeFeedbackIntent.task_render_mode = "hide";