@aigne/doc-smith 0.8.15-beta.15 → 0.8.15-beta.16

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.8.15-beta.16](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.15...v0.8.15-beta.16) (2025-11-07)
+
+
+### Features
+
+* support customize diagramming quantity ([#277](https://github.com/AIGNE-io/aigne-doc-smith/issues/277)) ([9d9fa6a](https://github.com/AIGNE-io/aigne-doc-smith/commit/9d9fa6a1f344c93df187f2dc502c5479e304e0f4))
+
 ## [0.8.15-beta.15](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.14...v0.8.15-beta.15) (2025-11-07)
 
 

package/agents/update/check-generate-diagram.mjs

@@ -1,27 +1,82 @@
-const placeholder = "DIAGRAM_PLACEHOLDER";
+const PLACEHOLDER = "DIAGRAM_PLACEHOLDER";
+const DEFAULT_DIAGRAMMING_EFFORT = 5;
+const MIN_DIAGRAMMING_EFFORT = 0;
+const MAX_DIAGRAMMING_EFFORT = 10;
 
 export default async function checkGenerateDiagram(
-  { needDiagram, documentContent, locale },
+  {
+    documentContent,
+    locale,
+    feedback,
+    detailFeedback,
+    originalContent,
+    path: docPath,
+    diagramming,
+  },
   options,
 ) {
-  if (!needDiagram) {
-    return {};
+  let content = documentContent;
+  let diagramSourceCode;
+  let skipGenerateDiagram = false;
+
+  const preCheckAgent = options.context?.agents?.["preCheckGenerateDiagram"];
+
+  const preCheckResult = await options.context.invoke(preCheckAgent, {
+    documentContent,
+    feedback,
+    detailFeedback,
+    previousGenerationContent: originalContent,
+  });
+
+  const totalScore = (preCheckResult.details || []).reduce((acc, curr) => acc + curr.score, 0);
+  if (![false, "false", "", undefined, null].includes(preCheckResult.content)) {
+    content = preCheckResult.content;
   }
 
-  const generateAgent = options.context?.agents?.["generateDiagram"];
-  let content = documentContent;
+  let diagrammingEffort = diagramming?.effort
+    ? Number(diagramming?.effort)
+    : DEFAULT_DIAGRAMMING_EFFORT;
 
-  if (content.includes(placeholder)) {
+  if (Number.isNaN(diagrammingEffort)) {
+    diagrammingEffort = DEFAULT_DIAGRAMMING_EFFORT;
+  } else {
+    diagrammingEffort = Math.min(
+      Math.max(MIN_DIAGRAMMING_EFFORT, diagrammingEffort),
+      MAX_DIAGRAMMING_EFFORT,
+    );
+  }
+
+  if (totalScore <= diagrammingEffort) {
+    skipGenerateDiagram = true;
+  }
+
+  if (skipGenerateDiagram) {
+    content = documentContent;
+  } else {
     try {
-      const { diagramSourceCode } = await options.context.invoke(generateAgent, {
-        documentContent,
+      const generateAgent = options.context?.agents?.["generateDiagram"];
+      ({ diagramSourceCode } = await options.context.invoke(generateAgent, {
+        documentContent: content,
         locale,
-      });
-      content = content.replace(placeholder, diagramSourceCode);
+      }));
     } catch (error) {
-      // FIXME: @zhanghan should regenerate document without diagram
-      content = content.replace(placeholder, "");
-      console.log(`⚠️  Skip generate any diagram: ${error.message}`);
+      diagramSourceCode = "";
+      skipGenerateDiagram = true;
+      console.log(`⚠️  Skip generate any diagram for ${docPath}: ${error.message}`);
+    }
+
+    if (diagramSourceCode && !skipGenerateDiagram) {
+      if (content.includes(PLACEHOLDER)) {
+        content = content.replace(PLACEHOLDER, diagramSourceCode);
+      } else {
+        const mergeAgent = options.context?.agents?.["mergeDiagramToDocument"];
+        ({ content } = await options.context.invoke(mergeAgent, {
+          diagramSourceCode,
+          content,
+        }));
+      }
+    } else {
+      content = documentContent;
     }
   }
 

package/agents/update/generate-document.yaml

@@ -46,19 +46,7 @@ input_schema:
     - rules
     - detailDataSource
     - originalDocumentStructure
-# output_key: content
-output_schema:
-  type: object
-  properties:
-    content:
-      type: string
-      description: Document content
-    needDiagram:
-      type: boolean
-      description: Does this document need to generate diagram?
-  required:
-    - content
-    - detailDataSource
+output_key: content
 afs:
   modules:
     - module: system-fs

package/agents/update/pre-check-generate-diagram.yaml

@@ -0,0 +1,44 @@
+name: preCheckGenerateDiagram
+description: Pre-check for generating diagram
+model:
+  reasoning_effort: 1
+instructions:
+  url: ../../prompts/detail/d2-diagram/pre-check.md
+input_schema:
+  type: object
+  properties:
+    documentContent:
+      type: string
+      description: Source content of the document
+    feedback:
+      type: string
+      description: User generation feedback
+    detailFeedback:
+      type: string
+      description: Current document detail feedback
+    previousGenerationContent:
+      type: string
+      description: Previous document content
+  required:
+    - documentContent
+output_schema:
+  type: object
+  properties:
+    content:
+      type: string
+      description: Document content
+    details:
+      type: array
+      description: Detailed needDiagram score
+      items:
+        type: object
+        properties:
+          type:
+            type: string
+          score:
+            type: number
+          reason:
+            type: string
+  required:
+    - content
+

package/aigne.yaml

@@ -1,6 +1,8 @@
 #!/usr/bin/env aigne
 
 model:
+  # model: aignehub/gpt-5
+  # model: aignehub/claude-sonnet-4-0
   model: aignehub/gemini-2.5-pro # reasoning_effort 128-32768
   # https://github.com/AIGNE-io/aigne-framework/blob/main/models/gemini/src/gemini-chat-model.ts#L115
   reasoning_effort:
@@ -101,6 +103,7 @@ agents:
   - ./agents/generate/merge-diagram.yaml
   - ./agents/update/generate-diagram.yaml
   - ./agents/update/check-generate-diagram.mjs
+  - ./agents/update/pre-check-generate-diagram.yaml
 cli:
   chat: ./agents/chat/index.yaml
   agents:

package/package.json

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

package/prompts/detail/custom/{custom-components.md → custom-components-usage-rules.md}

@@ -1,4 +1,4 @@
-<custom_components_usage>
+<custom_components_usage_rules>
 When generating document details, you can use the following custom components at appropriate locations based on their descriptions and functionality to enhance document presentation:
 
 ## XCard: Individual link display card
@@ -48,11 +48,11 @@ Example 1: Inline Markdown formatting in card content
 
 Example 2: Code block inside card content
 
-```md
+````md
 <x-card data-title="ctrl_break()" data-icon="lucide:keyboard">
   Creates a listener for "ctrl-break" events.
 
-\`\`\`rust
+```rust
 use tokio::signal::windows::ctrl_break;
 
 #[tokio::main]
@@ -62,10 +62,11 @@ stream.recv().await;
 println!("got ctrl-break");
 Ok(())
 }
-\`\`\`
-</x-card>
 ```
 
+````
+
+
 ## XCards: Multiple cards container
 
 Suitable for displaying multiple links using a card list format, providing a richer and more visually appealing presentation.
@@ -80,7 +81,7 @@ Suitable for displaying multiple links using a card list format, providing a ric
 
 ### Usage Rules
 
-- **Visual Consistency**: All <x-card> elements within the same <x-cards> must maintain visual consistency:
+- **Visual Consistency**: All `<x-card>` elements within the same `<x-cards>` must maintain visual consistency:
   - It's recommended to always provide data-icon for each card.
   - Or all cards should have data-image.
   - Avoid mixing (some with icons, some with only images).
@@ -106,6 +107,18 @@ Example 2: Two-column cards with images
 </x-cards>
 ```
 
+Example 3: Replace markdown format multiple links
+
+```md
+For more detailed information on specific features, please refer to the following sections:
+
+<x-cards data-columns="3">
+  <x-card data-title="Using Discussions" data-href="/discussions">Introduce how to use discussions</x-card>
+  <x-card data-title="Using the Blog" data-href="/blog">Introduce how to use the Blog</x-card>
+  <x-card data-title="Using Chat" data-href="/chat">Introduce how to use Chat</x-card>
+</x-cards>
+```
+
 ### Bad Examples
 
 Example 1: Using a single-column layout (`data-columns="1"`) is not allowed
@@ -125,6 +138,15 @@ Example 2: Contains only one `<x-card>` (must include multiple cards)
 </x-cards>
 ```
 
+Example 3: Markdown format multiple links
+
+```md
+For more detailed information on specific features, please refer to the following sections:
+- [Using Discussions](./discussions.md)
+- [Using the Blog](./blog.md)
+- [Using Chat](./chat.md)
+```
+
 ## XField: Structured data field
 
 Suitable for displaying API parameters, return values, context data, and any structured data with metadata in a clean, organized format. Supports nested structures for complex data types.
@@ -517,4 +539,4 @@ Example 6: Missing blank line before x-field-group (violates "Spacing Around" ru
 </x-field-group>
 ```
 
-</custom_components_usage>
+</custom_components_usage_rules>

package/prompts/detail/d2-diagram/pre-check.md

@@ -0,0 +1,23 @@
+<document_content>
+{{documentContent}}
+</document_content>
+
+{% if feedback %}
+<feedback>
+{{feedback}}
+</feedback>
+{% endif %}
+
+{% if detailFeedback %}
+<content_review_feedback>
+{{ detailFeedback }}
+</content_review_feedback>
+{% endif %}
+
+{% if previousGenerationContent %}
+<previous_generation_content>
+{{ previousGenerationContent }}
+</previous_generation_content>
+{% endif %}
+
+{% include "./rules.md" %}

package/prompts/detail/d2-diagram/rules.md

@@ -1,26 +1,44 @@
 <diagram_generation_rules>
-**Generation Workflow**
-1. Use the current `<detail_data_source>`, `<content_review_feedback>`, and `<feedback>` to decide whether this document requires a diagram.
-2. When a diagram is needed, call the `generateDiagram` tool to create it and insert the returned content at the most fitting location in the document.
-3. Check whether the data sources include `<diagram_source_code>`. If not, remove any embedded diagram from the document.
-
-**Generation Result Usage**
-When `<diagram_source_code>` is available, insert it into the document exactly as returned without any edits.
-
-**Generation Requirements**
-1. Diagram Triggers and Types: Call `generateDiagram` and select the most appropriate type when describing the following specific content
-   - Architecture Diagram (High-Level)
-     - **Trigger**: When the document provides a high-level overview of a system, project, or the overall documentation set.
-     - **Content**: Must illustrate the main components, their relationships, and the overall structure.
-   - Structural Diagram (Module-Level)
-     - **Trigger**: When generating the introductory document for a major section or module.
-     - **Content**: Must show the key sub-components, files, or core concepts within that specific module.
-   - Process and Interaction Diagrams (Detailed)
-     - **Trigger**: When the document describes a workflow, a sequence of events, user interactions, or data flow.
-     - **Diagram Type Selection**:
-       - **Flowchart**: Use for step-by-step processes, algorithms, or decision-making logic.
-       - **Sequence Diagram**: Use for time-ordered interactions between different components or actors (e.g., API calls).
-2. Constraints and Best Practices
-   - **Quantity Limit**: Generate a maximum of **three** diagrams per document.
-   - **Relevance**: Ensure every diagram **directly** illustrates a concept explained in the surrounding text. Avoid generating diagrams for simple concepts that are easily understood through text alone.
+
+You must analyze the provided inputs to determine if a diagram is needed and where to insert a placeholder. You must not generate the diagram itself (e.g., no Mermaid, PlantUML, or other code). You are only deciding and placing the placeholder.
+
+## Inputs
+
+- `<document_content>`: The main body of text to be evaluated.
+- `<previous_generation_content>`: The content from the previous run, which may contain DIAGRAM_PLACEHOLDER.
+- `<feedback>`: Specific user instructions for this run (e.g., "add a diagram," "remove the diagram").
+- `<content_review_feedback>`: General automated or human feedback on the content.
+
+## Scoring conditions
+
+- `add`: If `<feedback>` explicitly requests to add a diagram, ignore other conditions, +30000
+- `remove`: If `<feedback>` explicitly requests to remove a diagram, ignore other conditions, -30000
+- `previous-exists`: If `<previous_generation_content>` contains diagram, +21000
+- `path-exclude`: If the document path or filename matches excluded patterns (e.g., `/faq/`, `CHANGELOG`, `release-notes`), -10000
+- `less-words`: If document length <= 200 words AND less than 2 headings, -10000
+- `overview`: If `<document_content>` provides a high-level overview, +3
+- `architectural`: If `<document_content>` contains an architectural description (components/services/layers/modules), +3
+- `workflow`: If `<document_content>` describes a workflow, sequence, user interactions, or data flow, +2
+- `hierarchy`: If `<document_content>` describes a clear hierarchy (linked sub-docs / deeply nested sections), +1
+- `introductory-major`: If `<document_content>` is an introductory page for a major section, +1
+
+## Output Requirements
+- `details` is an array. Each element must include:
+  - `type`: matched scoring condition's type name
+  - `score`: matched scoring condition's score
+  - `reason`: text explaining why this scoring condition is matched
+- `content`: `<document_content>` with placeholder inserted
+  - Identify the most logical insertion point in the `<document_content>`. (This is often after an introductory paragraph or before a list/section that the diagram will explain).
+  - Insert the exact placeholder string: DIAGRAM_PLACEHOLDER
+  - Crucially: Adjust the surrounding text to integrate the placeholder smoothly. Add a lead-in sentence.
+  - Good example: "The following diagram illustrates this data flow:"
+  - Good example: "This architecture is shown in the overview below:"
+  - Bad example: (Just inserting the placeholder with no context).
+  - Return the modified document content.
+    - Keep the original structure of the document, including page headings and hierarchy
+      - Only modify parts of the document text to improve the alignment between diagrams and their context
+      - The output must not include the `document_content` tag
+      - Do not provide any explanations; include only the document content itself
+
 </diagram_generation_rules>
+

package/prompts/detail/d2-diagram/user-prompt.md

@@ -12,26 +12,6 @@ Generate a d2 diagram that represents the following document content:
 
 </user_rules>
 
-<diagram_rules>
-
-1. Diagram Triggers and Types: Select the most appropriate type when describing the following specific content
-   - Architecture Diagram (High-Level)
-     - **Trigger**: When the document provides a high-level overview of a system, project, or the overall documentation set.
-     - **Content**: Must illustrate the main components, their relationships, and the overall structure.
-   - Structural Diagram (Module-Level)
-     - **Trigger**: When generating the introductory document for a major section or module.
-     - **Content**: Must show the key sub-components, files, or core concepts within that specific module.
-   - Process and Interaction Diagrams (Detailed)
-     - **Trigger**: When the document describes a workflow, a sequence of events, user interactions, or data flow.
-     - **Diagram Type Selection**:
-       - **Flowchart**: Use for step-by-step processes, algorithms, or decision-making logic.
-       - **Sequence Diagram**: Use for time-ordered interactions between different components or actors (e.g., API calls).
-2. Constraints and Best Practices
-   - **Keep it Simple**: Avoid overcomplicating the diagram.
-   - **Relevance**: Ensure every diagram **directly** illustrates a concept explained in the surrounding text. Avoid generating diagrams for simple concepts that are easily understood through text alone.
-
-</diagram_rules>
-
 <document_content>
 {{documentContent}}
 </document_content>

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

@@ -37,14 +37,14 @@ Glossary of specialized terms. Please ensure correct spelling when using these t
 Documentation content generation rules:
 {% include "./document-rules.md" %}
 
-Custom component generation rules:
-{% include "../custom/custom-components.md" %}
+{% include "../custom/custom-components-usage-rules.md" %}
 
 Custom code block generation rules:
 {% include "../custom/custom-code-block.md" %}
 
 {% include "../../common/document/media-file-list-usage-rules.md" %}
 
+
 </content_generation_rules>
 
 

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

@@ -7,12 +7,7 @@
 
 ** Output content in {{ locale }} language. **
 
-** Don't generate any diagram in the document, give boolean value in `needDiagram` field & plan a placeholder in document content for diagram (use `DIAGRAM_PLACEHOLDER` as placeholder text). **
-   - Use the current `<detail_data_source>`, `<content_review_feedback>`, and `<feedback>` to decide whether this document requires a diagram.
-   - If `<feedback>` contains a request to add a diagram, set `needDiagram` to true.
-   - If `<feedback>` contains a request to remove a diagram, set `needDiagram` to false.
 
-- **Necessary**: Generate diagrams only when necessary.
 </user_rules>
 
 {% set operation_type = "generating" %}

package/prompts/detail/update/system-prompt.md

@@ -32,14 +32,15 @@ Glossary of specialized terms. Please ensure correct spelling when using these t
 Documentation content optimization rules:
 {% include "../generate/document-rules.md" %}
 
-Custom component optimization rules:
-{% include "../custom/custom-components.md" %}
+{% include "../custom/custom-components-usage-rules.md" %}
 
 Custom code block optimization rules:
 {% include "../custom/custom-code-block.md" %}
 
 {% include "../../common/document/media-file-list-usage-rules.md" %}
 
+{% include "../d2-diagram/rules.md" %}
+
 </content_optimization_rules>
 
 

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

@@ -11,9 +11,9 @@
 {% set operation_type = "optimizing" %}
 {% include "../../common/document/user-preferences.md" %}
 
-<original_page_content>
+<original_document_content>
 {{originalContent}}
-</original_page_content>
+</original_document_content>
 
 {% if needDataSources %}
 <detail_data_source>