@aigne/doc-smith 0.8.15-beta.6 → 0.8.15-beta.8

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* add web-smith powered web-pages ([#229](https://github.com/AIGNE-io/aigne-doc-smith/issues/229)) ([c3c00c1](https://github.com/AIGNE-io/aigne-doc-smith/commit/c3c00c12f092b125b6adb1a13ed5ff9720fbdab7))
+* support cleaning specific documents ([#231](https://github.com/AIGNE-io/aigne-doc-smith/issues/231)) ([67607c9](https://github.com/AIGNE-io/aigne-doc-smith/commit/67607c9ff3852cc81a29e5a11b2151d26879b000))
+
+
+### Bug Fixes
+
+* tune custom component prompt and batch update history ([#228](https://github.com/AIGNE-io/aigne-doc-smith/issues/228)) ([ab13b97](https://github.com/AIGNE-io/aigne-doc-smith/commit/ab13b9737e5f111d0939f9c39ee76e13c0692a68))
+
 ## [0.8.15-beta.6](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.5...v0.8.15-beta.6) (2025-10-30)
 
 

package/agents/clear/choose-contents.mjs

@@ -10,7 +10,7 @@ const TARGET_METADATA = {
   generatedDocs: {
     label: "Generated Documents",
     description: ({ docsDir }) =>
-      `Delete all generated documents in './${toDisplayPath(docsDir)}'. The documentation structure will be preserved.`,
+      `Select and delete specific generated documents in './${toDisplayPath(docsDir)}'. The documentation structure will be preserved.`,
     agent: "clearGeneratedDocs",
   },
   documentStructure: {
@@ -150,9 +150,9 @@ export default async function chooseContents(input = {}, options = {}) {
   }
 
   const header = hasError
-    ? "Cleanup finished with some issues."
-    : "Cleanup completed successfully!";
-  const detailLines = results.map((item) => `- ${item.message}`).join("\n");
+    ? "🧹 Cleanup finished with some issues.\n"
+    : "🧹 Cleanup completed successfully!\n";
+  const detailLines = results.map((item) => `${item.message}`).join("\n\n");
 
   const suggestions = [];
   results.forEach((result) => {

package/agents/clear/clear-auth-tokens.mjs

@@ -9,7 +9,7 @@ export default async function clearAuthTokens(_input = {}, options = {}) {
   // Check if the file exists
   if (!existsSync(DOC_SMITH_ENV_FILE)) {
     return {
-      message: "No site authorizations found to clear",
+      message: "🔑 No site authorizations found to clear",
     };
   }
 
@@ -23,7 +23,7 @@ export default async function clearAuthTokens(_input = {}, options = {}) {
 
     if (siteHostnames.length === 0) {
       return {
-        message: "No site authorizations found to clear",
+        message: "🔑 No site authorizations found to clear",
       };
     }
 
@@ -58,7 +58,7 @@ export default async function clearAuthTokens(_input = {}, options = {}) {
 
     if (selectedSites.length === 0) {
       return {
-        message: "No sites selected for clearing authorization",
+        message: "🔑 No sites selected for clearing authorization",
       };
     }
 
@@ -68,7 +68,7 @@ export default async function clearAuthTokens(_input = {}, options = {}) {
     if (selectedSites.includes("__ALL__")) {
       // Clear all site authorizations
       await writeFile(DOC_SMITH_ENV_FILE, stringify({}));
-      results.push(`Cleared site authorization for all sites (${siteHostnames.length} sites)`);
+      results.push(`✔ Cleared site authorization for all sites (${siteHostnames.length} sites)`);
       clearedCount = siteHostnames.length;
     } else {
       // Clear site authorizations for selected sites
@@ -79,7 +79,7 @@ export default async function clearAuthTokens(_input = {}, options = {}) {
           // Remove the entire site object
           delete updatedEnvs[hostname];
 
-          results.push(`Cleared site authorization for ${chalk.cyan(hostname)}`);
+          results.push(`✔ Cleared site authorization for ${chalk.cyan(hostname)}`);
           clearedCount++;
         }
       }
@@ -87,8 +87,8 @@ export default async function clearAuthTokens(_input = {}, options = {}) {
       await writeFile(DOC_SMITH_ENV_FILE, stringify(updatedEnvs));
     }
 
-    const header = `Successfully cleared site authorizations!`;
-    const detailLines = results.join("\n");
+    const header = `🔑 Successfully cleared site authorizations!`;
+    const detailLines = results.map((item) => `  ${item}`).join("\n");
 
     const message = [header, "", detailLines, ""].filter(Boolean).join("\n");
 
@@ -99,7 +99,7 @@ export default async function clearAuthTokens(_input = {}, options = {}) {
     };
   } catch (error) {
     return {
-      message: `Failed to clear site authorizations: ${error.message}`,
+      message: `⚠️ Failed to clear site authorizations: ${error.message}`,
       error: true,
     };
   }

package/agents/clear/clear-deployment-config.mjs

@@ -36,12 +36,12 @@ export default async function clearDeploymentConfig(input = {}) {
     }
 
     return {
-      message: `🧹 Cleared appUrl from config file (${displayPath})`,
+      message: `📦 Cleared appUrl from config file (${displayPath})`,
     };
   } catch (error) {
     return {
       error: true,
-      message: `❌ Failed to clear deployment config: ${error.message}`,
+      message: `⚠️ Failed to clear deployment config: ${error.message}`,
     };
   }
 }

package/agents/clear/clear-document-config.mjs

@@ -10,8 +10,8 @@ export default async function clearDocumentConfig({ workDir }) {
     await rm(documentConfigPath, { recursive: true, force: true });
 
     const message = existed
-      ? `Cleared document configuration (${displayPath})`
-      : `Document configuration already empty (${displayPath})`;
+      ? `⚙️ Cleared document configuration (${displayPath})`
+      : `⚙️ Document configuration already empty (${displayPath})`;
 
     const suggestions = existed
       ? ["Run `aigne doc init` to generate a fresh configuration file."]
@@ -25,7 +25,7 @@ export default async function clearDocumentConfig({ workDir }) {
     };
   } catch (error) {
     return {
-      message: `Failed to clear document configuration: ${error.message}`,
+      message: `⚠️ Failed to clear document configuration: ${error.message}`,
       error: true,
       path: displayPath,
     };

package/agents/clear/clear-document-structure.mjs

@@ -16,8 +16,8 @@ export default async function clearDocumentStructure(input = {}, _options = {})
 
     const structureDisplayPath = toDisplayPath(structurePlanPath);
     const structureMessage = structureExists
-      ? `Cleared documentation structure (${structureDisplayPath})`
-      : `Documentation structure already empty (${structureDisplayPath})`;
+      ? `✔ Cleared documentation structure (${structureDisplayPath})`
+      : `• Documentation structure already empty (${structureDisplayPath})`;
 
     results.push({
       type: "structure",
@@ -29,7 +29,7 @@ export default async function clearDocumentStructure(input = {}, _options = {})
     results.push({
       type: "structure",
       error: true,
-      message: `Failed to clear documentation structure: ${error.message}`,
+      message: `✗ Failed to clear documentation structure: ${error.message}`,
     });
   }
 
@@ -41,8 +41,8 @@ export default async function clearDocumentStructure(input = {}, _options = {})
 
       const docsDisplayPath = toDisplayPath(docsDir);
       const docsMessage = docsExists
-        ? `Cleared documents directory (${docsDisplayPath})`
-        : `Documents directory already empty (${docsDisplayPath})`;
+        ? `✔ Cleared documents directory (${docsDisplayPath})`
+        : `• Documents directory already empty (${docsDisplayPath})`;
 
       results.push({
         type: "documents",
@@ -54,7 +54,7 @@ export default async function clearDocumentStructure(input = {}, _options = {})
       results.push({
         type: "documents",
         error: true,
-        message: `Failed to clear documents directory: ${error.message}`,
+        message: `✗ Failed to clear documents directory: ${error.message}`,
       });
     }
   }
@@ -65,14 +65,14 @@ export default async function clearDocumentStructure(input = {}, _options = {})
 
   let header;
   if (errorItems > 0) {
-    header = "Documentation Structure cleanup finished with some issues.";
+    header = "⚠️ Documentation Structure cleanup finished with some issues.";
   } else if (clearedItems > 0) {
-    header = "Documentation Structure cleared successfully!";
+    header = "📖 Documentation Structure cleared successfully!";
   } else {
-    header = "Documentation Structure already empty.";
+    header = "📖 Documentation Structure already empty.";
   }
 
-  const detailLines = results.map((item) => `- ${item.message}`).join("\n");
+  const detailLines = results.map((item) => `  ${item.message}`).join("\n");
   const message = [header, "", detailLines].filter(Boolean).join("\n");
 
   return {

package/agents/clear/clear-generated-docs.mjs

@@ -1,12 +1,19 @@
 import { rm } from "node:fs/promises";
+import { join } from "node:path";
 import { pathExists, resolveToAbsolute, toDisplayPath } from "../../utils/file-utils.mjs";
+import {
+  pathToFlatName,
+  generateFileName,
+  loadDocumentStructure,
+} from "../../utils/docs-finder-utils.mjs";
+import chooseDocs from "../utils/choose-docs.mjs";
 
-export default async function clearGeneratedDocs(input = {}, _options = {}) {
-  const { docsDir } = input;
+export default async function clearGeneratedDocs(input = {}, options = {}) {
+  const { docsDir, outputDir, locale, translateLanguages } = input;
 
   if (!docsDir) {
     return {
-      message: "No generated documents directory specified",
+      message: "📁 No generated documents directory specified",
     };
   }
 
@@ -14,23 +21,104 @@ export default async function clearGeneratedDocs(input = {}, _options = {}) {
   const displayPath = toDisplayPath(generatedDocsPath);
 
   try {
-    const existed = await pathExists(generatedDocsPath);
-    await rm(generatedDocsPath, { recursive: true, force: true });
+    const dirExists = await pathExists(generatedDocsPath);
+    if (!dirExists) {
+      return {
+        message: `📁 Generated documents directory does not exist (${displayPath})`,
+        cleared: false,
+      };
+    }
 
-    const message = existed
-      ? `Cleared generated documents (${displayPath})`
-      : `Generated documents already empty (${displayPath})`;
+    const documentExecutionStructure = (await loadDocumentStructure(outputDir)) || [];
+    // select documents interactively
+    const chooseResult = await chooseDocs(
+      {
+        docs: [], // Empty to trigger interactive selection
+        documentExecutionStructure,
+        docsDir: generatedDocsPath,
+        locale: locale || "en",
+        isTranslate: false,
+        title: "Select documents to delete:",
+        feedback: "Skip feedback",
+        requiredFeedback: false,
+      },
+      options,
+    );
+
+    if (!chooseResult?.selectedDocs || chooseResult.selectedDocs.length === 0) {
+      return {
+        message: "📁 No documents selected for deletion",
+        cleared: false,
+        path: displayPath,
+      };
+    }
+
+    // Extract file names
+    const filesToDelete = new Set();
+    const allLanguages = [locale || "en", ...(translateLanguages || [])];
+
+    for (const selectedDoc of chooseResult.selectedDocs) {
+      // Convert path to flat filename format using utility function
+      const flatName = pathToFlatName(selectedDoc.path);
+
+      // Generate file names for all languages
+      for (const lang of allLanguages) {
+        const fileName = generateFileName(flatName, lang);
+        filesToDelete.add(fileName);
+      }
+    }
+
+    if (filesToDelete.size === 0) {
+      return {
+        message: "📁 No documents were deleted.",
+        cleared: false,
+      };
+    }
+
+    // Delete selected files (including all language versions)
+    const deletedFiles = [];
+    const failedFiles = [];
+    let hasError = false;
+
+    for (const file of filesToDelete) {
+      try {
+        const filePath = join(generatedDocsPath, file);
+        await rm(filePath, { force: true });
+        deletedFiles.push(file);
+      } catch (error) {
+        hasError = true;
+        failedFiles.push({ file, error: error.message });
+      }
+    }
+
+    // Build result message
+    const deletedCount = deletedFiles.length;
+    const failedCount = failedFiles.length;
+
+    let message = "";
+    if (deletedCount > 0) {
+      const lastIndex = deletedFiles.length - 1;
+      message = `📁 Deleted ${deletedCount} document(s) in "${displayPath}":\n${deletedFiles
+        .map((f, i) => `  ${i === lastIndex ? "└─" : "├─"} ${f}`)
+        .join("\n")}`;
+    }
+
+    if (failedCount > 0) {
+      const lastIndex = failedFiles.length - 1;
+      message = `⚠️ Failed to delete ${failedCount} document(s) in "${displayPath}":\n${failedFiles
+        .map((f, i) => `  ${i === lastIndex ? "└─" : "├─"} ${f.file}: ${f.error}`)
+        .join("\n")}`;
+    }
 
     return {
       message,
-      cleared: existed,
-      path: displayPath,
+      cleared: deletedCount > 0,
+      error: hasError,
     };
   } catch (error) {
     return {
-      message: `Failed to clear generated documents: ${error.message}`,
+      message: `⚠️ Failed to clear generated documents: ${error.message}`,
       error: true,
-      path: displayPath,
     };
   }
 }
@@ -46,5 +134,6 @@ clearGeneratedDocs.input_schema = {
   required: ["docsDir"],
 };
 
-clearGeneratedDocs.taskTitle = "Clear all generated documents";
-clearGeneratedDocs.description = "Clear the generated documents directory";
+clearGeneratedDocs.taskTitle = "Clear generated documents";
+clearGeneratedDocs.description =
+  "Select and delete specific generated documents from the docs directory";

package/agents/clear/clear-media-description.mjs

@@ -11,7 +11,7 @@ export default async function clearMediaDescription(_input = {}, options = {}) {
   // Check if the cache file exists
   if (!existsSync(cacheFilePath)) {
     return {
-      message: "No media descriptions found to clear",
+      message: "🖼️ No media descriptions found to clear",
     };
   }
 
@@ -26,7 +26,7 @@ export default async function clearMediaDescription(_input = {}, options = {}) {
 
     if (mediaHashes.length === 0) {
       return {
-        message: "No media descriptions found to clear",
+        message: "🖼️ No media descriptions found to clear",
       };
     }
 
@@ -68,7 +68,7 @@ export default async function clearMediaDescription(_input = {}, options = {}) {
 
     if (selectedHashes.length === 0) {
       return {
-        message: "No media files selected for clearing descriptions",
+        message: "🖼️ No media files selected for clearing descriptions",
       };
     }
 
@@ -84,7 +84,7 @@ export default async function clearMediaDescription(_input = {}, options = {}) {
           lastUpdated: new Date().toISOString(),
         }),
       );
-      results.push(`Cleared descriptions for all media files (${mediaHashes.length} files)`);
+      results.push(`✔ Cleared descriptions for all media files (${mediaHashes.length} files)`);
       clearedCount = mediaHashes.length;
     } else {
       // Clear descriptions for selected files
@@ -94,7 +94,7 @@ export default async function clearMediaDescription(_input = {}, options = {}) {
         if (updatedCache[hash]) {
           const filename = path.basename(updatedCache[hash].path);
           delete updatedCache[hash];
-          results.push(`Cleared description for ${chalk.cyan(filename)}`);
+          results.push(`✔ Cleared description for ${chalk.cyan(filename)}`);
           clearedCount++;
         }
       }
@@ -108,8 +108,8 @@ export default async function clearMediaDescription(_input = {}, options = {}) {
       );
     }
 
-    const header = `✨ Successfully cleared media descriptions`;
-    const detailLines = results.join("\n");
+    const header = `🖼️ Successfully cleared media descriptions`;
+    const detailLines = results.map((item) => `  ${item}`).join("\n");
 
     const message = [header, "", detailLines, ""].filter(Boolean).join("\n");
 

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,162 @@
+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)
+            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)
+            add:
+              type: array
+              description: List of document structure items to add, null or empty array means no addition
+              items:
+                type: object
+                properties:
+                  index:
+                    type: integer
+                    description: Position to insert the new item, null means append to the end
+                  item: ../schema/document-structure-item.yaml
+                required:
+                  - item
+            update:
+              type: array
+              description: List of document structure items to update, replace the item with the same path, null or empty array means no update
+              items:
+                type: object
+                properties:
+                  path:
+                    type: string
+                    description: Path of the document structure item to update or replace
+                  item: ../schema/document-structure-item.yaml
+                required:
+                  - path
+                  - item
+
+      - ./utils/merge-document-structures.mjs
+
+  - type: function
+    name: aggregateDocumentStructure
+    process: |
+      return {
+        documentStructure: options.context.userContext.originalDocumentStructure.map(i => ({
+          ...i,
+          id: i.title.toLowerCase().replace(/\s+/g, '-'),
+        })),
+        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:
+        refinedStructure:
+          type: array
+          description: Optimized document structure array
+          items:
+            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
+              newIndex:
+                type: integer
+                description: Used for ordering purposes, indicates the new position index of the document structure item
+              newPath:
+                type: string
+                description: The new path of the document structure item if it has been changed, otherwise can be omitted
+              newParentPath:
+                type: string
+                description: The new parentPath of the document structure item if it has been changed, otherwise can be omitted
+            required:
+              - id
+      required:
+        - refinedStructure
+
+  - type: function
+    name: finalizeDocumentStructure
+    process: |
+      return {
+        projectName: input.projectName,
+        projectDesc: input.projectDesc,
+        documentStructure: input.documentStructure
+          .map((item) => {
+            const refined = input.refinedStructure?.find(i => i.id === item.id)
+
+            return {
+              ...item,
+              index: refined?.newIndex || item.index,
+              path: refined?.newPath || item.path,
+              parentId: refined?.newParentPath || item.parentPath,
+            }
+          })
+          .sort((a, b) => a.index - b.index)
+          .map(i => {
+            const newItem = { ...i }
+            delete newItem.index
+            delete newItem.id
+            delete newItem.parentPath
+            return newItem
+          }),
+      }