@aigne/doc-smith 0.8.14-beta.1 → 0.8.14-beta.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.8.14-beta.2](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.14-beta.1...v0.8.14-beta.2) (2025-10-19)
+
+
+### Bug Fixes
+
+* polish d2-diagram insert result ([#205](https://github.com/AIGNE-io/aigne-doc-smith/issues/205)) ([0098ff0](https://github.com/AIGNE-io/aigne-doc-smith/commit/0098ff08609e0bfe930a1b733b68299d356f73ed))
+
 ## [0.8.14-beta.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.14-beta...v0.8.14-beta.1) (2025-10-17)
 
 

package/agents/generate/draw-diagram.yaml

@@ -10,7 +10,7 @@ input_schema:
   properties:
     documentContent:
       type: string
-      description: The **raw text content** of the current document. (**Note:** This is the original document and **does not include** any existing diagram source code.)
+      description: The **raw text content** of the current document. (**Note:** This is the original document and **does not include** any diagram source code.)
   required:
     - documentContent
 output_schema:

package/agents/update/generate-document.yaml

@@ -75,7 +75,7 @@ skills:
       properties:
         documentContent:
           type: string
-          description: The **raw text content** of the current document. (**Note:** This is the original document and **does not include** any existing diagram source code.)
+          description: The **raw text content** of the current document. (**Note:** This is the original document and **does not include** any diagram source code.)
       required:
         - documentContent
     output_schema:

package/package.json

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

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

@@ -1,25 +1,29 @@
 <diagram_generation_guide>
-1. Diagram Triggers and Types: Use the following guidelines to determine when to generate a diagram and which type to use.
-  - Rule for Skipping Diagrams:
-    - Trigger: Do not generate diagrams for purely textual, reference, or short note documents that describe abstract concepts, simple definitions, or FAQs.
-    - Action: Skip diagram generation entirely.
-  - Architecture Diagram (High-Level)
-    - Trigger: When generating a document that serves as a high-level overview of a system, project, or the entire documentation set.
-    - Action: Create a system architecture diagram.
-    - Content: The diagram should 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.
-    - Action: Create a structural diagram (e.g., a block diagram or mind map).
-    - Content: The diagram should show the key sub-components, files, or 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.
-    - Action: Create the most appropriate diagram type:
-      - 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).
-NOTE:  For documents not skipped by the first rule but not clearly fitting the above categories, you should always attempt to generate at least one Diagram whenever possible to visually represent key structures, relationships, or processes in the content.
 
-2. Constraints and Best Practices
-  - Quantity: Generate a maximum of three (3) diagrams per document to ensure the content remains focused and readable.
-  - Relevance: Ensure every diagram directly illustrates a concept explained in the surrounding text. Avoid generating diagrams for concepts that are easily understood via text alone.
-  - Priority: For complex modules, workflows, or interactions, generate diagrams for each critical part.
+1. Core Principles and Mandatory Constraints
+   - **Absolute Constraint (Mandatory)**: You **must only** call the `generateDiagram` tool to generate a diagram.
+     - **Do not** generate mermaid diagram.
+     - **Do not** generate base64 image.
+     - **Do not** generate fake image url.
+   - **Diagram Failure Handling**: If the `generateDiagram` tool call fails, **omit the diagram entirely** and proceed with generating the text. **Do not** attempt to describe the diagram in words as a replacement.
+
+2. 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).
+3. 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.
+4. Tool result using rules
+   - If the `generateDiagram` tool's result (`diagramSourceCode`) is present, insert the value of `diagramSourceCode` directly into the document as a string.
+   - If the `generateDiagram` tool's result is not present, do not attempt to add any diagrams.
+
 </diagram_generation_guide>

package/prompts/detail/d2-diagram/role-and-personality.md

@@ -1,2 +1,2 @@
 You are an AI diagram generator with the personality of an **ISTJ (The Logistician)**. 
-You are reliable, rule-abiding, and methodical. Your goal is to produce **clear, precise, and logically structured d2-diagram code** that accurately represents the given description. 
+You are reliable, rule-abiding, and methodical. Your goal is to produce **clear, precise, and logically structured d2 diagram code** that accurately represents the given description. 

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

@@ -1,24 +1,29 @@
 <diagram_generation_guide>
-1. Core Principle: Tool Use is Mandatory
-  - You MUST use the drawDiagram tool to generate and embed all diagrams.
-  - NEVER write raw diagram code (e.g., Mermaid syntax) directly into the document.
-  - If a drawDiagram tool call fails, omit the diagram entirely and proceed with generating the text. Do not attempt to describe the diagram in words as a replacement.
 
-2. Diagram Triggers and Types: Use the following guidelines to determine when to generate a diagram and which type to use.
-  - Architecture Diagram (High-Level)
-    - Trigger: When generating a document that serves as a high-level overview of a system, project, or the entire documentation set.
-    - Action: Call drawDiagram to create a system architecture diagram.
-    - Content: The diagram should 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.
-    - Action: Call drawDiagram to create a structural diagram (e.g., a block diagram or mind map).
-    - Content: The diagram should show the key sub-components, files, or 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.
-    - Action: Call drawDiagram to create the most appropriate diagram type:
-      - 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).
+1. Core Principles and Mandatory Constraints
+   - **Absolute Constraint (Mandatory)**: You **must only** call the `generateDiagram` tool to generate a diagram.
+     - **Do not** generate mermaid diagram.
+     - **Do not** generate base64 image.
+     - **Do not** generate fake image url.
+   - **Diagram Failure Handling**: If the `generateDiagram` tool call fails, **omit the diagram entirely** and proceed with generating the text. **Do not** attempt to describe the diagram in words as a replacement.
+
+2. 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).
 3. Constraints and Best Practices
-  - Quantity: Generate a maximum of three (3) diagrams per document to ensure the content remains focused and readable.
-  - 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.
+   - **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.
+4. Tool result using rules
+   - If the `generateDiagram` tool's result (`diagramSourceCode`) is present, insert the value of `diagramSourceCode` directly into the document as a string.
+   - If the `generateDiagram` tool's result is not present, do not attempt to add any diagrams.
+
 </diagram_generation_guide>

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

@@ -35,7 +35,7 @@ Your diagrams should focus on **readability, structural correctness, and practic
    - Avoid unnecessary stylistic complexity that may hinder future maintenance.
 
 **Output Requirements:**
-- Output only valid d2-diagram code.
+- Output only valid d2 diagram code.
 - Do not include explanatory text outside of the code block.
 - Ensure the diagram reflects a clean, professional, technical drawing.
 
@@ -1006,7 +1006,9 @@ Ensure that the shape names used in connections are accurate and match the actua
   User -> CLI: "blocklet init"
   ```
 
-#### If have alt, don't forget to add `shape: sequence_diagram`
+#### Don't forget to add `shape: sequence_diagram` to sequence diagram
+
+> Don't use alt as shape name
 
 - **Bad Practice:**
   ```d2
@@ -1084,12 +1086,12 @@ Ensure that the shape names used in connections are accurate and match the actua
   Blocklet-Service -> Application.Auth-Middleware: "4. Return permissions"
   Application.Auth-Middleware -> Application.Auth-Middleware: "5. Evaluate all rules"
 
-  alt "If Authorized" {
+  "If Authorized" {
     Application.Auth-Middleware -> Application.Protected-Route: "6a. next()"
     Application.Protected-Route -> Client: "7a. 200 OK Response"
   }
 
-  alt "If Forbidden" {
+  "If Forbidden" {
     Application.Auth-Middleware -> Client: "6b. 403 Forbidden Response"
   }
   ```

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

@@ -1,6 +1,6 @@
 Follow the given rules and ISTJ style from your system instructions.
 
-Generate a d2-diagram that represents the following document content:
+Generate a d2 diagram that represents the following document content:
 
 <document_content>
 {{documentContent}}

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

@@ -45,6 +45,10 @@ Custom code block generation rules:
 
 {% include "../d2-diagram/guide.md" %}
 
+Tool result usage rules:
+- Only use the `"role": "tool"` result as the datasource for document enhancement.
+- Do not include `"role": "agent"` content in the final output.
+
 </content_generation_rules>
 
 
@@ -54,5 +58,6 @@ Custom code block generation rules:
 1. Output the complete Markdown content for {{nodeName}}, only the content itself—no explanations or extra information.
 2. Follow the format, structure, tone, and level of detail shown in the examples, strictly adhering to <document_rules>, <content_generation_rules>, and <TONE_STYLE>.
 3. Output in {{locale}} language, ensuring clarity, conciseness, and well-organized structure.
+4. Do not include any self-introduction or conversational text. Output only the documentation content itself.
 
 </output_constraints>

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

@@ -59,7 +59,7 @@ Generate detailed and well-structured document for the current {{nodeName}} base
 
 YOU SHOULD:
 - Use AFS tools `afs_list` `afs_search` or `afs_read` to gather relevant and accurate information to enhance the content.
-- Follow rules in <diagram_generation_guide>: use `generateDiagram` to create and embed a diagram when appropriate, following the diagram generation guidelines.
+- Follow rules in `<diagram_generation_guide>`: use `generateDiagram` tool to create and embed a diagram when appropriate, following the diagram generation guidelines.
 
 <steps>
 1. Analyze the provided document structure and user requirements to plan the content.