@aigne/doc-smith 0.9.7 → 0.9.8-alpha.0

package/agents/utils/handle-diagram-operations.mjs

@@ -0,0 +1,263 @@
+import { AIAgent } from "@aigne/core";
+import { pick } from "@aigne/core/utils/type-utils.js";
+import z from "zod";
+import {
+  DIAGRAM_PLACEHOLDER,
+  replaceD2WithPlaceholder,
+  replaceDiagramsWithPlaceholder,
+} from "../../utils/d2-utils.mjs";
+import { readFileContent } from "../../utils/docs-finder-utils.mjs";
+import { getFileName, userContextAt } from "../../utils/utils.mjs";
+import { debug } from "../../utils/debug.mjs";
+
+/**
+ * Read current document content from file system
+ * Reuses the same logic as initCurrentContent but returns the content
+ * First checks userContext, then reads from file if not in context
+ */
+async function readCurrentContent(input, options) {
+  const { path, docsDir, locale = "en" } = input;
+
+  if (!path || !docsDir) {
+    return null;
+  }
+
+  // First check if content is already in userContext
+  const contentContext = userContextAt(options, `currentContents.${path}`);
+  const existingContent = contentContext.get();
+  if (existingContent) {
+    return existingContent;
+  }
+
+  // If not in context, read from file (same logic as initCurrentContent)
+  try {
+    const fileName = getFileName(path, locale);
+    const content = await readFileContent(docsDir, fileName);
+
+    if (!content) {
+      console.warn(`⚠️  Could not read content from ${fileName}`);
+      return null;
+    }
+
+    // Set in userContext for future use
+    contentContext.set(content);
+
+    return content;
+  } catch (error) {
+    console.warn(`Failed to read current content for ${path}: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Save document content
+ */
+async function saveDoc(input, options, { content, intentType }) {
+  const saveAgent = options.context?.agents?.["saveDoc"];
+  if (!saveAgent) {
+    console.warn("saveDoc agent not found");
+    return;
+  }
+  await options.context.invoke(saveAgent, {
+    ...pick(input, ["path", "docsDir", "labels", "locale"]),
+    content,
+    intentType, // Pass intentType so saveDoc can handle translation sync
+  });
+}
+
+/**
+ * Handle addDiagram intent
+ */
+async function addDiagram(input, options) {
+  // readCurrentContent will check userContext first, then read from file if needed
+  const currentContent = await readCurrentContent(input, options);
+  if (!currentContent) {
+    throw new Error(`Could not read current content for ${input.path}`);
+  }
+
+  const contentContext = userContextAt(options, `currentContents.${input.path}`);
+
+  const generateDiagramAgent = options.context.agents["checkGenerateDiagram"];
+  if (!generateDiagramAgent) {
+    throw new Error("checkGenerateDiagram agent not found");
+  }
+
+  const generateDiagramResult = await options.context.invoke(generateDiagramAgent, {
+    ...pick(input, ["locale", "diagramming", "feedback", "path", "docsDir"]),
+    documentContent: currentContent,
+    originalContent: currentContent,
+  });
+
+  const content = generateDiagramResult.content;
+  contentContext.set(content);
+  // Pass intentType to saveDoc so it can handle translation sync automatically
+  await saveDoc(input, options, { content, intentType: "addDiagram" });
+  return { content };
+}
+
+/**
+ * Handle updateDiagram intent
+ */
+async function updateDiagram(input, options) {
+  // readCurrentContent will check userContext first, then read from file if needed
+  const currentContent = await readCurrentContent(input, options);
+  if (!currentContent) {
+    throw new Error(`Could not read current content for ${input.path}`);
+  }
+
+  const contentContext = userContextAt(options, `currentContents.${input.path}`);
+
+  let [content] = replaceD2WithPlaceholder({
+    content: currentContent,
+  });
+
+  const generateAgent = options.context?.agents?.["generateDiagram"];
+  if (!generateAgent) {
+    throw new Error("generateDiagram agent not found");
+  }
+
+  const result = await options.context.invoke(generateAgent, {
+    documentContent: content,
+    locale: input.locale,
+    diagramming: input.diagramming || {},
+    feedback: input.feedback,
+    originalContent: currentContent, // Pass original content to find existing diagrams
+    path: input.path,
+    docsDir: input.docsDir,
+  });
+
+  // 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);
+  // Pass intentType to saveDoc so it can handle translation sync automatically
+  await saveDoc(input, options, { content, intentType: "updateDiagram" });
+  return { content };
+}
+
+/**
+ * Handle deleteDiagram intent
+ */
+async function deleteDiagram(input, options) {
+  // readCurrentContent will check userContext first, then read from file if needed
+  const currentContent = await readCurrentContent(input, options);
+  if (!currentContent) {
+    throw new Error(`Could not read current content for ${input.path}`);
+  }
+
+  const contentContext = userContextAt(options, `currentContents.${input.path}`);
+
+  // 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;
+      debug(`Extracted diagram index ${diagramIndex} from feedback: "${input.feedback}"`);
+    }
+  }
+
+  // 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.
+</role>
+
+<document_content>
+{{documentContent}}
+</document_content>
+
+<user_feedback>
+{{feedback}}
+</user_feedback>
+
+<output_constraints>
+- Do not provide any explanations; include only the document content itself
+</output_constraints>`;
+
+  const deleteAgent = AIAgent.from({
+    name: "deleteDiagram",
+    description: "Remove a diagram from the document content",
+    task_render_mode: "hide",
+    instructions,
+    inputSchema: z.object({
+      documentContent: z.string().describe("Source content of the document"),
+      feedback: z.string().describe("User feedback for content modifications"),
+    }),
+    outputKey: "message",
+  });
+
+  const { message: content } = await options.context.invoke(deleteAgent, {
+    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) {
+        debug(`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);
+  // Pass intentType to saveDoc so it can handle translation sync automatically
+  await saveDoc(input, options, { content, intentType: "deleteDiagram" });
+
+  return { content };
+}
+
+/**
+ * Handle diagram operations based on intent type
+ * Supports: addDiagram, updateDiagram, deleteDiagram
+ */
+export default async function handleDiagramOperations(
+  { intentType, path, docsDir, locale, feedback, diagramming, labels },
+  options,
+) {
+  if (!intentType || !["addDiagram", "updateDiagram", "deleteDiagram"].includes(intentType)) {
+    throw new Error(`Invalid intent type for diagram operations: ${intentType}`);
+  }
+
+  const input = {
+    path,
+    docsDir,
+    locale,
+    feedback,
+    diagramming,
+    labels,
+  };
+
+  const fnMap = {
+    addDiagram,
+    updateDiagram,
+    deleteDiagram,
+  };
+
+  if (fnMap[intentType]) {
+    const result = await fnMap[intentType](input, options);
+    return result;
+  }
+
+  throw new Error(`Unsupported intent type: ${intentType}`);
+}
+
+handleDiagramOperations.task_render_mode = "hide";

package/agents/utils/load-all-document-content.mjs

@@ -0,0 +1,30 @@
+import pMap from "p-map";
+import { findItemByPath } from "../../utils/docs-finder-utils.mjs";
+
+/**
+ * Loads all document content from the file system based on the provided document structure.
+ *
+ * @async
+ * @function loadAllDocumentContent
+ * @param {Object} params - The parameters object
+ * @param {string} params.docsDir - The root directory path where documents are located
+ * @param {Array<Object>} params.documentStructure - The document structure array containing items with path information
+ * @param {string} params.documentStructure[].path - The file path of each document item
+ * @returns {Promise<Array>} returns.allDocumentContentList - An array of document content items loaded from the file system
+ * @example
+ * const result = await loadAllDocumentContent({
+ *   docsDir: './docs',
+ *   documentStructure: [{ path: 'readme.md' }, { path: 'guide.md' }]
+ * });
+ */
+export default async function loadAllDocumentContent({ docsDir, documentStructure = [] }) {
+  const allDocumentContentList = await pMap(documentStructure, async (item) => {
+    const itemResult = await findItemByPath(documentStructure, item.path, null, docsDir);
+    return itemResult;
+  });
+  return {
+    allDocumentContentList,
+  };
+}
+
+loadAllDocumentContent.taskRenderMode = "hide";

package/agents/utils/load-sources.mjs

@@ -157,8 +157,8 @@ export default async function loadSources(
             mediaItem.width = dimensions.width;
             mediaItem.height = dimensions.height;
 
-            // Filter out images with width less than minImageWidth
-            if (dimensions.width < minImageWidth) {
+            // Filter out images with width less than minImageWidth, but not SVG images
+            if (dimensions.width < minImageWidth && mediaItem.mimeType !== "image/svg+xml") {
               filteredImageCount++;
               console.log(
                 `Ignored image: ${fileName} (${dimensions.width}x${dimensions.height}px < ${minImageWidth}px minimum)`,

package/agents/utils/post-generate.mjs

@@ -16,6 +16,8 @@ export default async function postGenerate({
   translateLanguages = [],
   locale,
   projectInfoMessage,
+  isChat,
+  feedback,
 }) {
   const _results = [];
   // Save current git HEAD to config.yaml for change detection
@@ -33,12 +35,21 @@ export default async function postGenerate({
     console.error("Failed to cleanup invalid .md files:", err.message);
   }
 
-  const message = `
+  let message = `
 ✅ Documentation generated successfully! (\`${documentStructure.length}\` documents → \`${docsDir}\`)
-${projectInfoMessage || ""}
+${projectInfoMessage || ""} `;
+
+  if (!isChat) {
+    message += `
 🚀 Next: Make your documentation live and generate a shareable link, run: \`aigne doc publish\`
 💡 Optional: Update specific document (\`aigne doc update\`) or refine documentation structure (\`aigne doc create\`)
-  `;
+    `;
+  }
+
+  if (isChat && feedback) {
+    message = `User feedback: ${feedback}
+The documentation structure and relevant documents have been updated according to the user's feedback. All feedback has been fully processed.`;
+  }
 
   // Shutdown mermaid worker pool to ensure clean exit
   try {

package/agents/utils/read-current-document-content.mjs

@@ -0,0 +1,46 @@
+import { readFileContent } from "../../utils/docs-finder-utils.mjs";
+import { getFileName } from "../../utils/utils.mjs";
+
+/**
+ * Read current document content from file system
+ * Used when skipping document generation (e.g., for diagram-only updates)
+ * Only reads content if intentType is diagram-related, otherwise returns input unchanged
+ */
+export default async function readCurrentDocumentContent(input) {
+  const { path, docsDir, locale = "en", intentType } = input;
+
+  // Only read content if intentType is diagram-related
+  // Otherwise, return input unchanged to allow document generation to proceed
+  if (!intentType || !["addDiagram", "updateDiagram", "deleteDiagram"].includes(intentType)) {
+    return input;
+  }
+
+  if (!path || !docsDir) {
+    return input;
+  }
+
+  try {
+    // Read document content using the same utility as other parts of the system
+    const fileName = getFileName(path, locale);
+    const content = await readFileContent(docsDir, fileName);
+
+    if (!content) {
+      console.warn(`⚠️  Could not read content from ${fileName}`);
+      return input;
+    }
+
+    // Return content as both content, documentContent, and originalContent
+    // This matches the structure expected by downstream agents
+    return {
+      ...input,
+      content,
+      documentContent: content,
+      originalContent: content,
+    };
+  } catch (error) {
+    console.warn(`Failed to read current content for ${path}: ${error.message}`);
+    return input;
+  }
+}
+
+readCurrentDocumentContent.task_render_mode = "hide";

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

@@ -1,4 +1,8 @@
 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,
@@ -7,6 +11,7 @@ export default async function saveDocTranslation({
   language,
   labels,
   isShowMessage = false,
+  locale,
 }) {
   await _saveDocTranslation({
     path,
@@ -16,6 +21,35 @@ 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}`);
+    }
+  }
+
   if (isShowMessage) {
     const message = `✅ Translation completed successfully.`;
     return { message };

package/agents/utils/save-doc.mjs

@@ -1,5 +1,6 @@
 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,
@@ -9,6 +10,8 @@ export default async function saveDoc({
   locale,
   feedback,
   isShowMessage = false,
+  intentType,
+  originalContent,
   ...rest
 }) {
   await _saveDoc({
@@ -19,6 +22,43 @@ 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}`);
+    }
+  }
+
   if (isShowMessage) {
     // Shutdown mermaid worker pool to ensure clean exit
     try {
@@ -39,6 +79,8 @@ export default async function saveDoc({
     locale,
     feedback,
     isShowMessage,
+    intentType,
+    originalContent,
     ...rest,
   };
 }

package/agents/utils/save-sidebar.mjs

@@ -2,10 +2,14 @@ import { join } from "node:path";
 import fs from "fs-extra";
 import { buildDocumentTree } from "../../utils/docs-finder-utils.mjs";
 
-export default async function saveSidebar({ documentStructure, docsDir }) {
+export default async function saveSidebar({
+  documentStructure,
+  originalDocumentStructure,
+  docsDir,
+}) {
   // Generate _sidebar.md
   try {
-    const sidebar = generateSidebar(documentStructure);
+    const sidebar = generateSidebar(documentStructure || originalDocumentStructure);
     const sidebarPath = join(docsDir, "_sidebar.md");
 
     await fs.ensureDir(docsDir);
@@ -16,14 +20,23 @@ export default async function saveSidebar({ documentStructure, docsDir }) {
   return {};
 }
 
-// Recursively generate sidebar text, the link path is the flattened file name
+// Recursively generate sidebar text
 function walk(nodes, indent = "") {
   let out = "";
   for (const node of nodes) {
-    const relPath = node.path.replace(/^\//, "");
-    const flatFile = `${relPath.split("/").join("-")}.md`;
     const realIndent = node.parentId === null ? "" : indent;
-    out += `${realIndent}* [${node.title}](/${flatFile})\n`;
+
+    // If path already ends with .md, use it directly
+    let linkPath;
+    if (node.path.endsWith(".md")) {
+      linkPath = node.path.startsWith("/") ? node.path : `/${node.path}`;
+    } else {
+      // Otherwise, convert to flattened file name
+      const relPath = node.path.replace(/^\//, "");
+      linkPath = `/${relPath.split("/").join("-")}.md`;
+    }
+
+    out += `${realIndent}* [${node.title}](${linkPath})\n`;
 
     if (node.children && node.children.length > 0) {
       out += walk(node.children, `${indent}  `);

package/agents/utils/skip-if-content-exists.mjs

@@ -0,0 +1,27 @@
+/**
+ * Determine whether to skip document generation when the document already exists.
+ * If intentType is diagram-related *and* content is already present, mark that
+ * generation should be skipped so downstream agents can short-circuit.
+ */
+export default async function skipIfContentExists(input) {
+  const { intentType, content } = input;
+
+  const isDiagramIntent =
+    intentType && ["addDiagram", "updateDiagram", "deleteDiagram"].includes(intentType);
+  const shouldSkipGeneration = Boolean(isDiagramIntent && content);
+
+  return {
+    ...input,
+    skipGenerateDocument: shouldSkipGeneration,
+    // Ensure downstream steps have content available when skipping
+    ...(shouldSkipGeneration
+      ? {
+          content,
+          documentContent: content,
+          originalContent: content,
+        }
+      : {}),
+  };
+}
+
+skipIfContentExists.task_render_mode = "hide";

package/aigne.yaml

@@ -1,13 +1,18 @@
 #!/usr/bin/env aigne
 
 model:
-  # model: gemini-3-pro-preview
-  model: gemini-2.5-pro
+  model: gemini-3-pro-preview
+  # model: gemini-2.5-pro
   temperature: 0.8
   # https://github.com/AIGNE-io/aigne-framework/blob/main/models/gemini/src/gemini-chat-model.ts#L115
   reasoning_effort:
     $get: reasoningEffort
 agents:
+  # - ./_exp_/index.yaml
+  # - ./_exp_/generateStructureOrchestrator.yaml
+
+  - ./agentic-agents/create/index.yaml
+
   # Initialization
   - ./agents/init/index.mjs
 
@@ -19,6 +24,7 @@ agents:
   - ./agents/create/check-document-structure.yaml
   - ./agents/create/user-review-document-structure.mjs
   - ./agents/create/index.yaml
+  - ./agentic-agents/structure/index.yaml
 
   # Documentation Structure Tools
   - ./agents/create/document-structure-tools/add-document.mjs
@@ -105,10 +111,15 @@ agents:
   - ./agents/evaluate/code-snippet.mjs
 
   # Diagram
-  - ./agents/create/merge-diagram.yaml
+  - ./agents/create/analyze-diagram-type.mjs
+  - ./agents/create/analyze-diagram-type-llm.yaml
+  - ./agents/create/generate-diagram-image.yaml
+  - ./agents/create/replace-d2-with-image.mjs
   - ./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
 cli:
   chat: ./agents/chat/index.mjs
   agents:
@@ -133,6 +144,7 @@ cli:
       alias: ["remove", "rm"]
       url: ./agents/create/user-remove-document/index.yaml
     - ./agents/clear/index.yaml
+    - ./agentic-agents/create/index.yaml
 mcp_server:
   agents:
     - ./docs-mcp/get-docs-structure.mjs