@aigne/doc-smith 0.9.7 → 0.9.8-beta

package/docs-mcp/read-doc-content.mjs

@@ -3,6 +3,32 @@ import path from "node:path";
 
 const docsDir = path.join(process.cwd(), "./.aigne/doc-smith", "docs");
 
+/**
+ * Remove base64 encoded images from markdown content
+ * This prevents large binary data from being included in document content
+ * Base64 images are completely removed (not replaced with placeholders) because:
+ * 1. They significantly increase token usage without providing useful information to LLM
+ * 2. Normal image references (file paths) are preserved and should be used instead
+ * 3. Base64 images are typically temporary or erroneous entries
+ *
+ * @param {string} content - Markdown content that may contain base64 images
+ * @returns {string} - Content with base64 images completely removed
+ */
+function removeBase64Images(content) {
+  if (!content || typeof content !== "string") {
+    return content;
+  }
+
+  // Match markdown image syntax with data URLs: ![alt](data:image/...;base64,...)
+  const base64ImageRegex = /!\[([^\]]*)\]\(data:image\/[^)]+\)/g;
+
+  // Completely remove base64 images (including the entire markdown image syntax)
+  // This maximizes token reduction while preserving normal image references
+  const cleanedContent = content.replace(base64ImageRegex, "");
+
+  return cleanedContent;
+}
+
 export default async function readDocContent({ relevantDocPaths, docsDir: customDocsDir }) {
   const targetDocsDir = customDocsDir || docsDir;
   const docContents = [];
@@ -15,7 +41,10 @@ export default async function readDocContent({ relevantDocPaths, docsDir: custom
       const filePath = path.join(targetDocsDir, fileFullName);
 
       // Read the markdown file
-      const content = await fs.readFile(filePath, "utf8");
+      let content = await fs.readFile(filePath, "utf8");
+
+      // Remove base64 encoded images to reduce token usage
+      content = removeBase64Images(content);
 
       docContents.push({
         success: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.9.7",
+  "version": "0.9.8-beta",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"
@@ -26,10 +26,9 @@
   "dependencies": {
     "@aigne/cli": "^1.56.0",
     "@aigne/core": "^1.69.0",
-    "@aigne/publish-docs": "^0.14.1",
+    "@aigne/publish-docs": "^0.14.2",
     "@aigne/secrets": "^0.1.1-beta.3",
-    "@blocklet/payment-broker-client": "^1.22.24",
-    "@terrastruct/d2": "^0.1.33",
+    "@blocklet/payment-broker-client": "^1.22.27",
     "chalk": "^5.5.0",
     "debug": "^4.4.1",
     "diff": "^8.0.2",
@@ -40,6 +39,7 @@
     "glob": "^11.0.3",
     "gpt-tokenizer": "^3.2.0",
     "image-size": "^2.0.2",
+    "sharp": "^0.33.0",
     "is-in-ci": "^2.0.0",
     "isbinaryfile": "^5.0.6",
     "jsdom": "^26.1.0",

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

@@ -0,0 +1,135 @@
+You are an AI assistant specialized in generating clean, modern, professional diagram images.
+
+#  GLOBAL RULES — APPLY TO ALL DIAGRAMS & ALL RATIOS
+
+## VISUAL STYLE (Unified)
+- Modern SaaS product aesthetic
+- Flat vector style, light soft depth (Material Design 2.0 / 3.0)
+- White or light-grey background
+- Open, airy, uncluttered layout
+- No dark backgrounds, neon colors, grunge textures, or heavy borders
+
+## COLORS (Material Design 3)
+- Background: white (#FFFFFF) or very light grey (#F5F5F5)
+- Node cards: pure white (#FFFFFF), rounded corners, soft shadows
+- Primary accents: blue (#2196F3), purple (#9C27B0), teal (#009688), green (#4CAF50)
+- Accent colors: amber (#FFC107), orange (#FF9800)
+- Optional group containers:
+  - Core logic: light blue (#E3F2FD)
+  - AI/external: light purple (#F3E5F5)
+  - Output/success: light green (#E8F5E9)
+- Connectors: blue (#2196F3 or #1976D2), straight or orthogonal
+
+## TYPOGRAPHY & TEXT RULES
+- English only
+- Short labels: 2–5 words, action-oriented
+- No long sentences
+- No text outside nodes
+- No titles, captions, or step numbers
+
+## UNIVERSAL NODE RULES
+- 1 concept per node
+- Merge minor steps when needed
+- Keep node sizes consistent
+- Icons optional (thin-line, ≤20% node area)
+- Architecture diagrams may use larger icons (30–50%)
+
+## FLOW RULES (Universal)
+- ONE start → sequential flow → ONE end
+- Clear, unobstructed main flow
+- Minimal branching
+- Avoid crossings; use orthogonal routing
+- Feedback loops minimal but allowed
+
+## NODE COUNT CONTROL
+- Target: 5–10 nodes
+- Hard maximum: 15 nodes
+- If >10: merge related steps, use grouping containers
+- Must preserve complete logical flow
+
+#  ASPECT RATIO RULES — SELECTED VIA aspectRatio
+
+{% if aspectRatio == "1:1" %}
+## SQUARE (1:1)
+- Canvas: ~1024×1024
+- Primary layout: radial or balanced grid
+- Center main concept; surround related nodes symmetrically
+- Use the full square; avoid tiny central clusters
+
+{% elif aspectRatio == "4:3" or aspectRatio == "5:4" %}
+## PORTRAIT (4:3 or 5:4)
+- Canvas: ~1280×1024 or ~1365×1024
+- Primary layout: vertical (top→bottom)
+- Use height generously; avoid large top/bottom gaps
+- 4:3 supports longer text wrapping
+
+{% elif aspectRatio == "3:2" %}
+## LANDSCAPE (3:2)
+- Canvas: ~1536×1024
+- Primary layout: horizontal (left→right)
+- Use width well; 2–4 vertical lanes recommended
+
+{% elif aspectRatio == "16:9" %}
+## WIDESCREEN (16:9)
+- Canvas: ~1820×1024
+- Strong horizontal layout
+- Ideal for timelines, processes, wide flows
+
+{% elif aspectRatio == "21:9" %}
+## ULTRAWIDE (21:9)
+- Canvas: ~2393×1024
+- Very strong horizontal flow
+- Ideal for multi-lane or multi-actor diagrams
+
+{% endif %}
+
+#  DIAGRAM TYPE RULES — SELECT BASED ON diagramType
+
+{% if diagramType == "flowchart" %}
+## FLOWCHART
+- ONE start → ONE end
+- Dominant main flow, minimal branches
+- Logical grouping recommended:
+  - Initialization
+  - Processing
+  - Validation
+  - Output
+- Optional group containers
+
+{% elif diagramType == "architecture" %}
+## ARCHITECTURE DIAGRAM
+- Layout flexible: horizontal, vertical layers, or radial
+- Use containers or zones for modules/services
+- Icons may be larger and more expressive
+- Emphasize structure and relationships
+
+{% elif diagramType == "intro" %}
+## INTRO / CONCEPT OVERVIEW
+- Radial or hierarchical layout
+- One central idea + surrounding concepts
+- Few connectors required
+
+{% elif diagramType == "guide" %}
+## GUIDE DIAGRAM
+- Simple linear progression
+- Horizontal or vertical based on aspectRatio
+
+{% elif diagramType == "sequence" %}
+## SEQUENCE DIAGRAM
+- Horizontal timeline
+- Vertical lifelines for actors
+- Horizontal message arrows
+
+{% elif diagramType == "network" %}
+## NETWORK DIAGRAM
+- Node-based topology
+- Minimize crossing connections
+- Use relative spatial placement to show relationships
+
+{% endif %}
+
+#  NEGATIVE PROMPT (Unified)
+(no dark background), (no neon colors), (no clutter),  
+(no overcrowding), (no messy lines), (no spaghetti diagram),  
+(no confusing flow), (no diagram title), (no captions),  
+(no long sentences), (no step numbers)

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

@@ -0,0 +1,32 @@
+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.
+
+# Task Parameters:
+- **Diagram Type:** {{ diagramType }}
+- **Visual Style:** {{ diagramStyle }}
+- **Aspect Ratio:** {{ aspectRatio }}
+- **Language:** {{ locale }}
+
+# Your responsibilities:
+1. Read and analyze the document content.
+2. Extract key concepts, steps, relationships, or flow sequences.
+3. Generate a diagram that accurately represents these elements.
+4. Apply all rules from the system prompt.
+5. Labels must be concise (2–5 words).
+6. No titles or explanations outside nodes.
+7. Maintain clarity, structure, and proper layout based on the aspect ratio.
+
+# Document Content:
+
+Now analyze the following document content to understand what should be drawn:
+
+{% if documentSummary %}
+**Document Content (comprehensive summary for diagram generation):**
+{{ documentSummary }}
+{% else %}
+**Document Content (full original content):**
+{{ documentContent }}
+{% endif %}
+
+(Use this content to determine node structure, relationships, and flow.)

package/prompts/detail/generate/user-prompt.md

@@ -49,24 +49,38 @@ User feedback on previous generation:
 </feedback>
 {% endif %}
 
-{% if content %}
+{% if content or originalContent %}
+{% set previousContent = content or originalContent %}
 
 <previous_generation_content>
-{{content}}
+{{previousContent}}
 </previous_generation_content>
 
 <instructions>
-Analyze the previous document content and user feedback, then use available tools to implement the requested improvements while maintaining the document's integrity and style.
-</instructions>
-
-{% elseif originalContent %}
-
-<previous_generation_content>
-{{originalContent}}
-</previous_generation_content>
-
-<instructions>
-Analyze the previous document content and user feedback, then use available tools to implement the requested improvements while maintaining the document's integrity and style.
+Analyze the user feedback carefully.
+
+{% if intentType and intentType in ["addDiagram", "updateDiagram", "deleteDiagram"] %}
+**CRITICAL INSTRUCTION FOR DIAGRAM/IMAGE UPDATES:**
+The user intent is to {{ intentType }} (diagram-related operation). You MUST:
+1. **DO NOT** change the text content.
+2. **DO NOT** rewrite, summarize, or "improve" the existing text.
+3. **DO NOT** use any search tools.
+4. **OUTPUT the `previous_generation_content` VERBATIM (exactly as is).**
+   The system has a dedicated downstream agent that will handle the image generation based on your output. Your job is to preserve the text so the image agent can work on the same context.
+{% else %}
+**CRITICAL INSTRUCTION FOR DIAGRAM/IMAGE UPDATES:**
+If the user feedback is ONLY about updating diagrams, images, or visual styles (e.g., "update diagram", "change image", "use 16:9 ratio", "fix flowchart") and does NOT explicitly ask for text changes:
+1. **DO NOT** change the text content.
+2. **DO NOT** rewrite, summarize, or "improve" the existing text.
+3. **DO NOT** use any search tools.
+4. **OUTPUT the `previous_generation_content` VERBATIM (exactly as is).**
+   The system has a dedicated downstream agent that will handle the image generation based on your output. Your job is to preserve the text so the image agent can work on the same context.
+
+Only if the feedback explicitly requests changes to the text content (e.g., "fix typo", "rewrite introduction", "add info"):
+1. Analyze the previous document content and user feedback.
+2. Use available tools to implement the requested improvements.
+3. Maintain the document's integrity and style.
+{% endif %}
 </instructions>
 
 {% else %}

package/prompts/evaluate/document.md

@@ -17,27 +17,40 @@ Please **strictly adhere** to the evaluation standards defined in `<standards>`
 
 - **Document content to be evaluated**:
 
+{% if allDocumentContentList %}
+<all_document_content>
+{% for documentItem in allDocumentContentList %}
+<document_content file_path="{{ documentItem.path }}">
+{{ documentItem.content }}
 <document_content>
-  {{ content }}
-</document_content>
-
-<document_content_plan>
-  {{ description }}
-</document_content_plan>
-
+{% endfor %}
+</all_document_content>
+
+<current_document_path>
+{{ path }}
+</current_document_path>
+{% else %}
+<current_document_content>
+{{ content }}
+</current_document_content>
+{% endif %}
+
+<current_document_content_plan>
+{{ description }}
+</current_document_content_plan>
 
 - **User Selection**:
 
 <purposes>
-  {{purposes}}
+{{ purposes }}
 </purposes>
 
 <audiences>
-  {{audiences}}
+{{ audiences }}
 </audiences>
 
 <reader_knowledge_level>
-  {{readerKnowledgeLevel}}
+{{ readerKnowledgeLevel }}
 </reader_knowledge_level>
 
 </context>

package/prompts/media/media-description/system-prompt.md

@@ -1,5 +1,5 @@
 <role_and_goal>
-You are an expert at analyzing media files (images and videos) and generating concise, meaningful descriptions for documentation content.
+You are an expert at analyzing media files (images, videos, and SVG graphics) and generating concise, meaningful descriptions for documentation content.
 
 Your goal is to examine a single media file and generate an accurate description that helps both AI content generators and human readers understand what the media depicts and how it can be used effectively in documentation.
 </role_and_goal>
@@ -12,11 +12,13 @@ Your goal is to examine a single media file and generate an accurate description
    - The purpose or context of this media
    - Mood or atmosphere if distinctive
    - For videos: key actions, movements, or transitions
+   - For SVG: analyze the SVG code structure to understand the graphic content
 
 2. **Generate Description**: Create a concise, human-readable description following these principles:
    - Keep it between 2-3 sentences
    - Be specific and descriptive about visual content
    - For videos, describe the key content or action shown
+   - For SVG graphics, describe the visual theme and elements shown, NOT the file paths or code structure
    - Focus on aspects that matter for documentation usage
    - Remain objective - describe what you see, not what you interpret
 </analysis_workflow>
@@ -26,10 +28,16 @@ Your goal is to examine a single media file and generate an accurate description
 - Main subject or focus of the media
 - Key visual elements and composition
 - Context or setting if relevant for understanding
-- Technical aspects if relevant (e.g., "screenshot", "diagram", "illustration", "animation")
+- Technical aspects if relevant (e.g., "screenshot", "diagram", "illustration", "animation", "icon", "logo")
 - Key features or functionality visible
 - Its purpose or functionality
 - Any notable UI elements or features
 - For videos: describe the main action, movement, or narrative
+- For SVG graphics: describe the visual theme, shapes, colors, and what the graphic represents
+
+**What NOT to Include (especially for SVG):**
+- File paths, URLs, or technical references within the SVG code
+- XML/SVG tag structure or implementation details
+- Code-level technical information
 </description_guidelines>
 

package/prompts/media/media-description/user-prompt.md

@@ -4,5 +4,14 @@
 {%if width and height %}
 - Dimensions: {{width}}x{{height}}px
 {%endif%}
+{%if svgContent %}
+
+SVG Content:
+```xml
+{{svgContent}}
+```
+
+Please analyze the SVG code above and describe what visual elements and theme it represents. Focus on the visual appearance and purpose, not the code structure or file paths.
+{%endif%}
 </media_information>
 

package/utils/check-document-has-diagram.mjs

@@ -0,0 +1,97 @@
+import { DIAGRAM_PLACEHOLDER, d2CodeBlockRegex } from "./d2-utils.mjs";
+
+const diagramImageRegex = /<!--\s*DIAGRAM_IMAGE_START:[^>]+-->/g;
+
+/**
+ * Check if document content contains diagram-related content
+ * @param {string} content - Document content to check
+ * @returns {boolean} - True if document contains d2 code blocks, DIAGRAM_PLACEHOLDER, or diagram images
+ */
+export function hasDiagramContent(content) {
+  if (!content || typeof content !== "string") {
+    return false;
+  }
+
+  // Check for DIAGRAM_PLACEHOLDER
+  if (content.includes(DIAGRAM_PLACEHOLDER)) {
+    return true;
+  }
+
+  // Check for D2 code blocks
+  const d2Matches = Array.from(content.matchAll(d2CodeBlockRegex));
+  if (d2Matches.length > 0) {
+    return true;
+  }
+
+  // Check for existing diagram images (DIAGRAM_IMAGE_START markers)
+  const imageMatches = Array.from(content.matchAll(diagramImageRegex));
+  if (imageMatches.length > 0) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Get diagram type labels for a document
+ * @param {string} content - Document content to analyze
+ * @returns {string[]} - Array of diagram type labels (e.g., ["D2", "AI Image", "Placeholder"])
+ */
+export function getDiagramTypeLabels(content) {
+  if (!content || typeof content !== "string") {
+    return [];
+  }
+
+  const labels = [];
+
+  // Check for D2 code blocks
+  const d2Matches = Array.from(content.matchAll(d2CodeBlockRegex));
+  if (d2Matches.length > 0) {
+    labels.push("⛔️ D2");
+  }
+
+  // Check for existing diagram images (AI-generated images)
+  const imageMatches = Array.from(content.matchAll(diagramImageRegex));
+  if (imageMatches.length > 0) {
+    labels.push("🍌 Image");
+  }
+
+  // Check for DIAGRAM_PLACEHOLDER
+  if (content.includes(DIAGRAM_PLACEHOLDER)) {
+    labels.push("Placeholder");
+  }
+
+  return labels;
+}
+
+/**
+ * Format diagram type labels as a suffix string
+ * @param {string[]} labels - Array of diagram type labels
+ * @returns {string} - Formatted suffix string (e.g., " [D2, AI Image]")
+ */
+export function formatDiagramTypeSuffix(labels) {
+  if (!labels || labels.length === 0) {
+    return "";
+  }
+  return ` [${labels.join(", ")}]`;
+}
+
+/**
+ * Check if document content contains banana images (AI-generated images)
+ * Only checks for DIAGRAM_IMAGE_START markers, excludes D2 code blocks and placeholders
+ * @param {string} content - Document content to check
+ * @returns {boolean} - True if document contains banana images
+ */
+export function hasBananaImages(content) {
+  if (!content || typeof content !== "string") {
+    return false;
+  }
+
+  // Check for existing diagram images (DIAGRAM_IMAGE_START markers)
+  const imageMatches = Array.from(content.matchAll(diagramImageRegex));
+  if (imageMatches.length > 0) {
+    return true;
+  }
+
+  return false;
+}

package/utils/constants/index.mjs

@@ -572,3 +572,49 @@ export const REASONING_EFFORT_LEVELS = {
     pro: 2000,
   },
 };
+
+// Diagram styles - visual styles for diagram generation
+export const DIAGRAM_STYLES = {
+  modern: {
+    name: "Modern",
+    description: "Modern, clean, professional style with contemporary design elements",
+    prompt:
+      "Modern, clean, professional diagram style with contemporary design elements, smooth lines, and a professional color scheme",
+  },
+  standard: {
+    name: "Standard Flowchart",
+    description: "Standard flowchart style with traditional symbols and formats",
+    prompt:
+      "Standard flowchart style with traditional symbols (rectangles for processes, diamonds for decisions, arrows for flows), clear and conventional formatting",
+  },
+  "hand-drawn": {
+    name: "Hand-drawn",
+    description: "Hand-drawn style with natural, organic lines and sketch-like appearance",
+    prompt:
+      "Hand-drawn, sketch-like style with natural, organic lines, slightly imperfect shapes, and a casual, approachable appearance",
+  },
+  anthropomorphic: {
+    name: "Anthropomorphic",
+    description: "Anthropomorphic style with personified elements and vivid imagery",
+    prompt:
+      "Anthropomorphic style with personified elements, vivid and lively imagery, characters or objects with human-like features, engaging and memorable",
+  },
+  flat: {
+    name: "Flat Design",
+    description: "Flat design style without shadows or 3D effects",
+    prompt:
+      "Flat design style with no shadows, gradients, or 3D effects, clean geometric shapes, bold colors, and minimalist aesthetics",
+  },
+  minimalist: {
+    name: "Minimalist",
+    description: "Minimalist style with minimal elements and maximum clarity",
+    prompt:
+      "Minimalist style with the fewest possible elements, maximum clarity, simple shapes, ample white space, and essential information only",
+  },
+  "3d": {
+    name: "3D",
+    description: "3D style with three-dimensional effects and perspective",
+    prompt:
+      "3D style with three-dimensional effects, perspective, depth, shadows, and realistic spatial relationships",
+  },
+};