@aigne/doc-smith 0.8.15-beta.7 → 0.8.15-beta.9

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.8.15-beta.9](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.8...v0.8.15-beta.9) (2025-11-03)
+
+
+### Bug Fixes
+
+* optimize the draw diagram process ([#234](https://github.com/AIGNE-io/aigne-doc-smith/issues/234)) ([7bdc0d9](https://github.com/AIGNE-io/aigne-doc-smith/commit/7bdc0d939df05b9d31e06ea0f0285ed0eafe74ae))
+* simplify document structure merging and add deletion support ([#235](https://github.com/AIGNE-io/aigne-doc-smith/issues/235)) ([7f10242](https://github.com/AIGNE-io/aigne-doc-smith/commit/7f1024294bde241f41034d3e01a542451030cbdc))
+
+## [0.8.15-beta.8](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.7...v0.8.15-beta.8) (2025-11-01)
+
+
+### Features
+
+* smarter structure generation with team-based architecture ([#225](https://github.com/AIGNE-io/aigne-doc-smith/issues/225)) ([eb3404a](https://github.com/AIGNE-io/aigne-doc-smith/commit/eb3404a8889364912a077e84688cfcd48d69ef47))
+
 ## [0.8.15-beta.7](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.6...v0.8.15-beta.7) (2025-10-31)
 
 

package/agents/evaluate/index.yaml

@@ -16,9 +16,7 @@ skills:
       $merge([
         $,
         {
-          "documentStructure": originalDocumentStructure,
-          "datasources": "",
-          "datasourcesList": ""
+          "documentStructure": originalDocumentStructure
         }
       ])
   - ./document-structure.yaml

package/agents/generate/check-diagram.mjs

@@ -9,7 +9,7 @@ export default async function checkD2DiagramIsValid({ diagramSourceCode }) {
   } catch (err) {
     return {
       isValid: false,
-      error: err.message,
+      diagramError: err.message,
     };
   }
 }

package/agents/generate/check-need-generate-structure.mjs

@@ -3,7 +3,7 @@ import { getActiveRulesForScope } from "../../utils/preferences-utils.mjs";
 import { getProjectInfo, loadConfigFromFile, saveValueToConfig } from "../../utils/utils.mjs";
 
 export default async function checkNeedGenerateStructure(
-  { originalDocumentStructure, forceRegenerate, isLargeContext, ...rest },
+  { originalDocumentStructure, forceRegenerate, ...rest },
   options,
 ) {
   // Check if originalDocumentStructure is empty and prompt user
@@ -53,11 +53,7 @@ export default async function checkNeedGenerateStructure(
     };
   }
 
-  // Performance optimization: Using both structured output and tools with the Gemini model can cause redundant calls.
-  // Only use tools when the context is very large.
-  const generateStructureAgent = isLargeContext
-    ? options.context.agents["generateStructure"]
-    : options.context.agents["generateStructureWithoutTools"];
+  const generateStructureAgent = options.context.agents["generateStructure"];
 
   const structureRules = getActiveRulesForScope("structure", []);
   const globalRules = getActiveRulesForScope("global", []);
@@ -72,7 +68,6 @@ export default async function checkNeedGenerateStructure(
     originalDocumentStructure,
     userPreferences,
     feedback: finalFeedback || "",
-    isLargeContext,
   });
 
   let message = "";

package/agents/generate/generate-structure.yaml

@@ -1,68 +1,120 @@
+type: team
 name: generateStructure
 description: Generate the structure and organization of your documentation
-instructions:
-  - role: system
-    url: ../../prompts/structure/generate/system-prompt.md
-  - role: user
-    url: ../../prompts/structure/generate/user-prompt.md
 skills:
-  - ./document-structure-tools/generate-sub-structure.mjs
-task_render_mode: collapse
-task_title: Generate the structure of the documentation
-tool_calls_concurrency: 5
-input_schema:
-  type: object
-  properties:
-    rules:
-      type: string
-      description: Your specific requirements for documentation structure
-    locale:
-      type: string
-      description: Primary language for documentation (e.g., zh, en, ja)
-    datasources:
-      type: string
-      description: Project content and context to help generate documentation structure
-    targetAudience:
-      type: string
-      description: Target audience for the documentation
-    nodeName:
-      type: string
-      description: Specific section or page name to focus on
-    glossary:
-      type: string
-      description: Glossary for consistent terminology
-    feedback:
-      type: string
-      description: Tell us how to improve the documentation structure
-    userPreferences:
-      type: string
-      description: Your saved preferences for structure and documentation style
-    docsType:
-      type: string
-      description: "Documentation type (options: general, getting-started, reference, faq)"
-      default: general
-  required:
-    - rules
-    - datasources
-output_schema:
-  type: object
-  properties:
-    projectName:
-      type: string
-      description: Project name identified from your content sources
-    projectDesc:
-      type: string
-      description: Brief project description generated from content analysis (under 50 words)
-    documentStructure: ../schema/document-structure.yaml
-    documentStructureTree:
-      type: string
-      description: |
-        Visual tree structure showing documentation hierarchy with indented levels for easy review:
-        ```
-        - Home
-          - Getting Started
-            - Installation
-              - Requirements
-        ```
-  required:
-    - documentStructure
+  - type: team
+    name: generateStructureWorker
+    iterate_on: datasources
+    skills:
+      - type: ai
+        model:
+          reasoning_effort: 500
+        instructions:
+          - role: system
+            url: ../../prompts/structure/generate/system-prompt.md
+          - role: user
+            url: ../../prompts/structure/generate/user-prompt.md
+        task_render_mode: collapse
+        task_title: Generate the structure of the documentation
+        tool_calls_concurrency: 5
+        input_schema:
+          type: object
+          properties:
+            rules:
+              type: string
+              description: Your specific requirements for documentation structure
+            locale:
+              type: string
+              description: Primary language for documentation (e.g., zh, en, ja)
+            dataSourceChunk:
+              type: string
+              description: Project content and context to help generate documentation structure
+            targetAudience:
+              type: string
+              description: Target audience for the documentation
+            nodeName:
+              type: string
+              description: Specific section or page name to focus on
+            glossary:
+              type: string
+              description: Glossary for consistent terminology
+            feedback:
+              type: string
+              description: Tell us how to improve the documentation structure
+            userPreferences:
+              type: string
+              description: Your saved preferences for structure and documentation style
+            docsType:
+              type: string
+              description: "Documentation type (options: general, getting-started, reference, faq)"
+              default: general
+          required:
+            - rules
+            - dataSourceChunk
+        output_schema:
+          type: object
+          properties:
+            projectName:
+              type: string
+              description: Project name identified from your content sources
+            projectDesc:
+              type: string
+              description: Brief project description generated from content analysis (under 50 words)
+            structures:
+              type: array
+              description: List of document structure items to add or update
+              items: ../schema/document-structure-item.yaml
+
+      - ./utils/merge-document-structures.mjs
+
+  - type: function
+    name: aggregateDocumentStructure
+    process: |
+      return {
+        documentStructure: options.context.userContext.originalDocumentStructure.map((i, index) => ({
+          ...i,
+          id: i.title.toLowerCase().replace(/\s+/g, '-'),
+          index
+        })),
+        projectName: options.context.userContext.projectName,
+        projectDesc: options.context.userContext.projectDesc,
+      }
+
+  - type: ai
+    name: refineStructure
+    model:
+      reasoning_effort: 500
+    instructions:
+      - role: system
+        url: ../../prompts/structure/review/structure-review-system.md
+    output_schema:
+      type: object
+      properties:
+        structures:
+          type: array
+          description: Document structure items that need to be updated or changed
+          items: ../schema/document-structure-refine-item.yaml
+      required:
+        - structures
+
+  - type: function
+    name: finalizeDocumentStructure
+    process: |
+      return {
+        projectName: input.projectName,
+        projectDesc: input.projectDesc,
+        documentStructure: input.structures.map(refinedItem => {
+          // Find original item to get sourceIds and other fields
+          const originalItem = input.documentStructure.find(orig => orig.id === refinedItem.id)
+
+          const newItem = {
+            title: refinedItem.title,
+            description: refinedItem.description,
+            path: refinedItem.path,
+            parentId: refinedItem.parentPath || null,  // Convert parentPath to parentId
+            sourceIds: originalItem?.sourceIds || [],
+          }
+
+          return newItem
+        })
+      }

package/agents/generate/index.yaml

@@ -38,8 +38,7 @@ skills:
                 'translates': [$map(translateLanguages, function($lang) { {"language": $lang} })]
               }
             ])
-          }),
-          "datasources": ""
+          })
         }
       ])
   - ../utils/format-document-structure.mjs

package/agents/generate/{merge-d2-diagram.yaml → merge-diagram.yaml}

@@ -1,14 +1,15 @@
-name: mergeD2DiagramToDocument
-description: Merge D2 Diagram source code into document
+name: mergeDiagramToDocument
+description: Merge Diagram source code into document
 instructions: |
   You are an AI assistant that helps to merge d2 diagram into document.
 
-  <datasources>
+  <detail_dataSource>
   {{ content }}
-  </datasources>
-  <datasources>
+  </detail_dataSource>
+
+  <diagramSourceCode>
   {{ diagramSourceCode }}
-  </datasources>
+  </diagramSourceCode>
 
   Given the source content of a document and the D2 diagram source code, your task is to:
   - **Keep the original content as soon as possible.**

package/agents/generate/update-document-structure.yaml

@@ -16,7 +16,7 @@ input_schema:
     locale:
       type: string
       description: User language, e.g. zh, en
-    datasources:
+    dataSourceChunk:
       type: string
       description: Context for documentation structure
     glossary:

package/agents/generate/user-review-document-structure.mjs

@@ -140,6 +140,7 @@ export default async function userReviewDocumentStructure({ documentStructure, .
       // Call refineDocumentStructure agent with feedback
       await options.context.invoke(refineAgent, {
         ...rest,
+        dataSourceChunk: rest.datasources[0].dataSourceChunk,
         feedback: feedback.trim(),
         documentStructure: currentStructure,
         userPreferences,

package/agents/generate/utils/merge-document-structures.mjs

@@ -0,0 +1,30 @@
+export default async function mergeDocumentStructures(input, options) {
+  if (input.projectName) {
+    options.context.userContext.projectName = input.projectName;
+  }
+  if (input.projectDesc) {
+    options.context.userContext.projectDesc = input.projectDesc;
+  }
+
+  input.projectName = options.context.userContext.projectName;
+  input.projectDesc = options.context.userContext.projectDesc;
+
+  options.context.userContext.originalDocumentStructure ??= [];
+
+  const originalStructures = options.context.userContext.originalDocumentStructure;
+
+  if (input.structures) {
+    for (const item of input.structures) {
+      const old = originalStructures.find((s) => s.path === item.path);
+      if (old) {
+        Object.assign(old, item);
+      } else {
+        originalStructures.push(item);
+      }
+    }
+  }
+
+  options.context.userContext.originalDocumentStructure = originalStructures;
+
+  return {};
+}

package/agents/schema/document-structure-item.yaml

@@ -0,0 +1,23 @@
+type: object
+description: Document structure item representing a node in the document hierarchy
+properties:
+  title:
+    type: string
+  description:
+    type: string
+  path:
+    type: string
+    description: Path in URL format, cannot be empty, cannot contain spaces or special characters, must start with /, no need to include language level, e.g., /zh/about should return /about
+  parentPath:
+    type: string
+    description: Parent node path, if null indicates it is a top-level node
+  sourceIds:
+    type: array
+    description: Associated sourceId from dataSources for subsequent translation and content generation, must come from sourceId in datasources, cannot have fake ids, **cannot be empty**
+    items:
+      type: string
+required:
+  - title
+  - description
+  - path
+  - sourceIds

package/agents/schema/document-structure-refine-item.yaml

@@ -0,0 +1,20 @@
+type: object
+description: Document structure item representing a node in the document hierarchy
+properties:
+  id:
+    type: string
+    description: Unique identifier for the document structure item
+  title:
+    type: string
+  description:
+    type: string
+  path:
+    type: string
+    description: Path in URL format, cannot be empty, cannot contain spaces or special characters, must start with /, no need to include language level, e.g., /zh/about should return /about
+  parentPath:
+    type: string
+    description: Parent node path, if null indicates it is a top-level node
+required:
+  - title
+  - description
+  - path

package/agents/schema/document-structure.yaml

@@ -10,9 +10,7 @@ items:
       type: string
       description: Path in URL format, cannot be empty, cannot contain spaces or special characters, must start with /, no need to include language level, e.g., /zh/about should return /about
     parentId:
-      type:
-        - string
-        - "null"
+      type: string
       description: Parent node path, if null indicates it is a top-level node
     sourceIds:
       type: array

package/agents/update/batch-generate-document.yaml

@@ -6,7 +6,7 @@ skills:
 input_schema:
   type: object
   properties:
-    datasources:
+    detailDataSource:
       type: string
       description: Context for documentation structure generation, used to assist generate documentation structure
     documentExecutionStructure: ../schema/document-execution-structure.yaml

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

@@ -0,0 +1,26 @@
+const placeholder = "DIAGRAM_PLACEHOLDER";
+
+export default async function checkGenerateDiagram(
+  { needDiagram, documentContent, locale },
+  options,
+) {
+  if (!needDiagram) {
+    return {};
+  }
+
+  const generateAgent = options.context?.agents?.["generateDiagram"];
+  let content = documentContent;
+
+  try {
+    const { diagramSourceCode } = await options.context.invoke(generateAgent, {
+      documentContent,
+      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}`);
+  }
+  return { content };
+}

package/agents/update/generate-diagram.yaml

@@ -9,7 +9,6 @@ reflection:
   is_approved: isValid
   max_iterations: 5
   return_last_on_max_iterations: false
-  custom_error_message: "MUST NOT generate any diagram: validation failed after max iterations."
 input_schema:
   type: object
   properties:

package/agents/update/generate-document.yaml

@@ -16,7 +16,7 @@ input_schema:
     locale:
       type: string
       description: User language, such as zh, en
-    datasources:
+    detailDataSource:
       type: string
       description: Source data and context for document content generation
     targetAudience:
@@ -44,9 +44,21 @@ input_schema:
       description: Additional supplementary information
   required:
     - rules
-    - datasources
+    - detailDataSource
     - originalDocumentStructure
-output_key: content
+# 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
 afs:
   modules:
     - module: system-fs
@@ -57,5 +69,5 @@ afs:
           Codebase of the project to be documented used as context for document generation,
           should search and read as needed while generating document content
 keep_text_in_tool_uses: false
-skills:
-  - ./generate-diagram.yaml
+# skills:
+#   - ./generate-diagram.yaml

package/agents/update/handle-document-update.yaml

@@ -23,6 +23,14 @@ skills:
       max_iterations: 5
       return_last_on_max_iterations: true
     task_title: Generate document for '{{ title }}'
+  - type: transform
+    jsonata: |
+      $merge([
+        $,
+        { "documentContent": content }
+      ])
+  - ./check-generate-diagram.mjs
+  # - ../generate/merge-diagram.yaml
   - ../utils/save-doc.mjs
 input_schema:
   type: object

package/agents/update/update-document-detail.yaml

@@ -23,7 +23,7 @@ input_schema:
     locale:
       type: string
       description: User language, e.g. zh, en
-    datasources:
+    detailDataSource:
       type: string
       description: Context for document content
     glossary:
@@ -57,5 +57,5 @@ afs:
 keep_text_in_tool_uses: false
 skills:
   - ./document-tools/update-document-content.mjs
-  - ./generate-diagram.yaml
+  # - ./generate-diagram.yaml
 task_render_mode: collapse

package/agents/update/update-single-document.yaml

@@ -3,6 +3,5 @@ name: updateSingleDocument
 skills:
   - ../utils/transform-detail-datasources.mjs
   - ../update/user-review-document.mjs
-  - ../utils/save-doc.mjs
 iterate_on: selectedDocs
 concurrency: 1

package/agents/update/user-review-document.mjs

@@ -105,6 +105,7 @@ async function showDocumentDetail(content, title) {
       renderer: new markedTerminal(),
     });
 
+    // FIXME: @zhanghan fix error "Could not find the language 'd2', did you forget to load/include a language module?"
     const renderedMarkdown = marked(content);
 
     // Restore original console.error
@@ -121,16 +122,15 @@ async function showDocumentDetail(content, title) {
   }
 }
 
-export default async function userReviewDocument(
-  { content, title, description, ...rest },
-  options,
-) {
+export default async function userReviewDocument({ content, description, ...rest }, options) {
   // Check if document content exists
   if (!content || typeof content !== "string" || content.trim().length === 0) {
     console.log("Please provide document content to review.");
     return { content };
   }
 
+  const title = rest.documentStructure?.find((x) => x.path === rest.path)?.title;
+
   // Print current document headings structure
   printDocumentHeadings(content, title || "Untitled Document");
 
@@ -190,7 +190,7 @@ export default async function userReviewDocument(
     feedbacks.push(feedback.trim());
 
     // Get the updateDocument agent
-    const updateAgent = options.context.agents["updateDocumentDetail"];
+    const updateAgent = options.context.agents["handleDocumentUpdate"];
     if (!updateAgent) {
       console.log(
         "We can't process your feedback right now. The document update feature is temporarily unavailable.",
@@ -213,6 +213,7 @@ export default async function userReviewDocument(
         originalContent: options.context.userContext.currentContent,
         feedback: feedback.trim(),
         userPreferences,
+        title,
       });
 
       // Check if feedback should be saved as user preference