@aigne/doc-smith 0.1.3 → 0.2.0

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+## Related Issue
+
+<!-- Use keywords like fixes, closes, resolves, relates to link the issue. In principle, all PRs should be associated with an issue -->
+
+### Major Changes
+
+<!--
+  @example:
+    1. Fixed xxx
+    2. Improved xxx
+    3. Adjusted xxx
+-->
+
+### Screenshots
+
+<!-- If the changes are related to the UI, whether CLI or WEB, screenshots should be included -->
+
+### Test Plan
+
+<!-- If this change is not covered by automated tests, what is your test case collection? Please write it as a to-do list below -->
+
+### Checklist
+
+- [ ] This change requires documentation updates, and I have updated the relevant documentation. If the documentation has not been updated, please create a documentation update issue and link it here
+- [ ] The changes are already covered by tests, and I have adjusted the test coverage for the changed parts
+- [ ] The newly added code logic is also covered by tests
+- [ ] This change adds dependencies, and they are placed in dependencies and devDependencies
+- [ ] This change includes adding or updating npm dependencies, and it does not result in multiple versions of the same dependency [check the diff of pnpm-lock.yaml]

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.2.0](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.1.4...v0.2.0) (2025-08-05)
+
+
+### Features
+
+* support automatic init configuration when calling agents ([24d29db](https://github.com/AIGNE-io/aigne-doc-smith/commit/24d29db4dd86709750aa22ff649e7dacc4124126))
+* update docs when sources changed ([#9](https://github.com/AIGNE-io/aigne-doc-smith/issues/9)) ([4adcecf](https://github.com/AIGNE-io/aigne-doc-smith/commit/4adcecfb32e72c9e88d0b0bd8ce0a91022847ca7))
+
+## [0.1.4](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.1.3...v0.1.4) (2025-08-04)
+
+
+### Miscellaneous Chores
+
+* release 0.1.4 ([4122cf5](https://github.com/AIGNE-io/aigne-doc-smith/commit/4122cf5cc0285bef2b96803f393e744121d22acf))
+
 ## [0.1.3](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.1.2...v0.1.3) (2025-08-04)
 
 

package/README.md

@@ -61,13 +61,13 @@ Contributions are welcome! Please feel free to submit a pull request or open an
 npx --no doc-smith run --entry-agent init
 
 # 生成命令
-npx --no doc-smith run --entry-agent generator --model gemini:gemini-2.5-flash
+npx --no doc-smith run --entry-agent generate --model gemini:gemini-2.5-flash
 
 # 重新生成单篇
-npx --no doc-smith run --entry-agent regenerator --input-path bitnet-getting-started
+npx --no doc-smith run --entry-agent update --input-path bitnet-getting-started
 
 # 结构规划优化
-npx --no doc-smith run --entry-agent generator --input-feedback "补充节点的 sourceIds，确保所有节点 sourceIds 都有值" --model gemini:gemini-2.5-pro
+npx --no doc-smith run --entry-agent generate --input-feedback "补充节点的 sourceIds，确保所有节点 sourceIds 都有值" --model gemini:gemini-2.5-pro
 
 
 # 发布文档

package/agents/batch-docs-detail-generator.yaml

@@ -10,5 +10,9 @@ input_schema:
       type: string
       description: 结构规划的上下文，用于辅助结构规划
     structurePlanResult: ./schema/structure-plan-result.yaml
+    modifiedFiles:
+      type: array
+      items: { type: string }
+      description: Array of modified files since last generation
 iterate_on: structurePlanResult
 mode: sequential

package/agents/check-detail-generated.mjs

@@ -3,12 +3,22 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { TeamAgent } from "@aigne/core";
 import checkDetailResult from "./check-detail-result.mjs";
+import { hasSourceFilesChanged } from "../utils/utils.mjs";
 
 // Get current script directory
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 export default async function checkDetailGenerated(
-  { path, docsDir, sourceIds, originalStructurePlan, structurePlan, ...rest },
+  {
+    path,
+    docsDir,
+    sourceIds,
+    originalStructurePlan,
+    structurePlan,
+    modifiedFiles,
+    lastGitHead,
+    ...rest
+  },
   options
 ) {
   // Check if the detail file already exists
@@ -61,6 +71,21 @@ export default async function checkDetailGenerated(
     }
   }
 
+  // Check if source files have changed since last generation
+  let sourceFilesChanged = false;
+  if (sourceIds && sourceIds.length > 0 && modifiedFiles) {
+    sourceFilesChanged = hasSourceFilesChanged(sourceIds, modifiedFiles);
+
+    if (sourceFilesChanged) {
+      console.log(`Source files changed for ${path}, will regenerate`);
+    }
+  }
+
+  // If lastGitHead is not set, regenerate
+  if (!lastGitHead) {
+    sourceFilesChanged = true;
+  }
+
   // If file exists, check content validation
   let contentValidationFailed = false;
   if (detailGenerated && fileContent && structurePlan) {
@@ -74,8 +99,13 @@ export default async function checkDetailGenerated(
     }
   }
 
-  // If file exists, sourceIds haven't changed, and content validation passes, no need to regenerate
-  if (detailGenerated && !sourceIdsChanged && !contentValidationFailed) {
+  // If file exists, sourceIds haven't changed, source files haven't changed, and content validation passes, no need to regenerate
+  if (
+    detailGenerated &&
+    !sourceIdsChanged &&
+    !sourceFilesChanged &&
+    !contentValidationFailed
+  ) {
     return {
       path,
       docsDir,

package/agents/check-detail-result.mjs

@@ -51,49 +51,35 @@ export default async function checkDetailResult({
     }
   };
 
-  const checkTableSeparators = (text, source) => {
-    // Split text into lines and check each line
+  const performAllChecks = (text, source) => {
+    // Split text into lines once and perform all checks in a single pass
     const lines = text.split("\n");
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i];
-      if (tableSeparatorRegex.test(line)) {
-        isApproved = false;
-        detailFeedback.push(
-          `Found an incorrect table separator in ${source} at line ${
-            i + 1
-          }: ${line.trim()}`
-        );
-      }
-    }
-  };
 
-  const checkSingleLine = (text, source) => {
-    // Count newline characters to check if content is only on one line
-    const newlineCount = (text.match(/\n/g) || []).length;
-    if (newlineCount === 0 && text.trim().length > 0) {
-      isApproved = false;
-      detailFeedback.push(
-        `Found single line content in ${source}: content appears to be on only one line, check for missing line breaks`
-      );
-    }
-  };
-
-  const checkCodeBlockIndentation = (text, source) => {
-    // Split text into lines and check each line
-    const lines = text.split("\n");
+    // State variables for different checks
     let inCodeBlock = false;
     let codeBlockIndentLevel = 0;
     let codeBlockStartLine = 0;
+    let inMermaidBlock = false;
+    let mermaidStartLine = 0;
 
     for (let i = 0; i < lines.length; i++) {
       const line = lines[i];
+      const lineNumber = i + 1;
 
-      // Check if this line is a code block marker
+      // Check table separators
+      if (tableSeparatorRegex.test(line)) {
+        isApproved = false;
+        detailFeedback.push(
+          `Found an incorrect table separator in ${source} at line ${lineNumber}: ${line.trim()}`
+        );
+      }
+
+      // Check code block markers and indentation
       if (codeBlockRegex.test(line)) {
         if (!inCodeBlock) {
           // Starting a new code block
           inCodeBlock = true;
-          codeBlockStartLine = i + 1;
+          codeBlockStartLine = lineNumber;
           // Calculate indentation level of the code block marker
           const match = line.match(/^(\s*)(```)/);
           codeBlockIndentLevel = match ? match[1].length : 0;
@@ -102,11 +88,8 @@ export default async function checkDetailResult({
           inCodeBlock = false;
           codeBlockIndentLevel = 0;
         }
-        continue;
-      }
-
-      // If we're inside a code block, check if content has proper indentation
-      if (inCodeBlock) {
+      } else if (inCodeBlock) {
+        // If we're inside a code block, check if content has proper indentation
         const contentIndentLevel = line.match(/^(\s*)/)[1].length;
 
         // If code block marker has indentation, content should have at least the same indentation
@@ -116,23 +99,51 @@ export default async function checkDetailResult({
         ) {
           isApproved = false;
           detailFeedback.push(
-            `Found code block with inconsistent indentation in ${source} at line ${codeBlockStartLine}: code block marker has ${codeBlockIndentLevel} spaces indentation but content at line ${
-              i + 1
-            } has only ${contentIndentLevel} spaces indentation`
+            `Found code block with inconsistent indentation in ${source} at line ${codeBlockStartLine}: code block marker has ${codeBlockIndentLevel} spaces indentation but content at line ${lineNumber} has only ${contentIndentLevel} spaces indentation`
           );
           // Reset to avoid multiple errors for the same code block
           inCodeBlock = false;
           codeBlockIndentLevel = 0;
         }
       }
+
+      // Check mermaid block markers
+      if (/^\s*```mermaid\s*$/.test(line)) {
+        inMermaidBlock = true;
+        mermaidStartLine = lineNumber;
+      } else if (inMermaidBlock && /^\s*```\s*$/.test(line)) {
+        inMermaidBlock = false;
+      } else if (inMermaidBlock) {
+        // If we're inside a mermaid block, check for backticks in node labels
+        // Check for node definitions with backticks in labels
+        // Pattern: A["label with backticks"] or A{"label with backticks"}
+        const nodeLabelRegex =
+          /[A-Za-z0-9_]+\["([^"]*`[^"]*)"\]|[A-Za-z0-9_]+{"([^}]*`[^}]*)"}/g;
+        let match;
+
+        while ((match = nodeLabelRegex.exec(line)) !== null) {
+          const label = match[1] || match[2];
+          isApproved = false;
+          detailFeedback.push(
+            `Found backticks in Mermaid node label in ${source} at line ${lineNumber}: "${label}" - backticks in node labels cause rendering issues in Mermaid diagrams`
+          );
+        }
+      }
+    }
+
+    // Check single line content (this needs to be done after the loop)
+    const newlineCount = (text.match(/\n/g) || []).length;
+    if (newlineCount === 0 && text.trim().length > 0) {
+      isApproved = false;
+      detailFeedback.push(
+        `Found single line content in ${source}: content appears to be on only one line, check for missing line breaks`
+      );
     }
   };
 
   // Check content
   checkLinks(reviewContent, "result");
-  checkTableSeparators(reviewContent, "result");
-  checkSingleLine(reviewContent, "result");
-  checkCodeBlockIndentation(reviewContent, "result");
+  performAllChecks(reviewContent, "result");
 
   return {
     isApproved,

package/agents/check-structure-planning.mjs

@@ -1,15 +1,49 @@
-import { dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-
-// Get current script directory
-const __dirname = dirname(fileURLToPath(import.meta.url));
+import {
+  getCurrentGitHead,
+  hasFileChangesBetweenCommits,
+} from "../utils/utils.mjs";
 
 export default async function checkStructurePlanning(
-  { originalStructurePlan, feedback, ...rest },
+  { originalStructurePlan, feedback, lastGitHead, ...rest },
   options
 ) {
-  // If originalStructurePlan exists, return directly
-  if (originalStructurePlan && !feedback) {
+  // Check if we need to regenerate structure plan
+  let shouldRegenerate = false;
+  let finalFeedback = feedback;
+
+  // If no feedback and originalStructurePlan exists, check for git changes
+  if (originalStructurePlan) {
+    // If no lastGitHead, regenerate by default
+    if (!lastGitHead) {
+      shouldRegenerate = true;
+    } else {
+      // Check if there are relevant file changes since last generation
+      const currentGitHead = getCurrentGitHead();
+      if (currentGitHead && currentGitHead !== lastGitHead) {
+        const hasChanges = hasFileChangesBetweenCommits(
+          lastGitHead,
+          currentGitHead
+        );
+        if (hasChanges) {
+          shouldRegenerate = true;
+        }
+      }
+    }
+
+    if (shouldRegenerate) {
+      finalFeedback = `
+      ${finalFeedback || ""}
+      
+      根据最新的 DataSources 更新结构规划：
+        1. 对于新增的内容，可以根据需要新增节点，或补充到原有节点展示
+        2. 谨慎删除节点，除非节点关联 sourceIds 都被删除了
+        3. 不能修改原有节点的 path
+      `;
+    }
+  }
+
+  // If no regeneration needed, return original structure plan
+  if (originalStructurePlan && !feedback && !shouldRegenerate) {
     return {
       structurePlan: originalStructurePlan,
     };
@@ -18,7 +52,7 @@ export default async function checkStructurePlanning(
   const panningAgent = options.context.agents["reflective-structure-planner"];
 
   const result = await options.context.invoke(panningAgent, {
-    feedback: feedback || "",
+    feedback: finalFeedback || "",
     originalStructurePlan,
     ...rest,
   });

package/agents/detail-regenerator.yaml

@@ -4,6 +4,9 @@ alias:
   - up
 description: Optimize and regenerate individual document content and translations
 skills:
+  - url: ./input-generator.mjs
+    default_input:
+      skipIfExists: true
   - ./load-config.mjs
   - ./load-sources.mjs
   - type: transform

package/agents/docs-generator.yaml

@@ -5,6 +5,9 @@ alias:
   - g
 description: Automatically generates comprehensive project documentation
 skills:
+  - url: ./input-generator.mjs
+    default_input:
+      skipIfExists: true
   - ./load-config.mjs
   - ./load-sources.mjs
   - ./check-structure-planning.mjs

package/agents/input-generator.mjs

@@ -1,6 +1,38 @@
-import { writeFile, mkdir } from "node:fs/promises";
+import { writeFile, mkdir, readFile } from "node:fs/promises";
 import { join, dirname } from "node:path";
 
+// Predefined document generation styles
+const DOCUMENT_STYLES = {
+  actionFirst: {
+    name: "Action-First Style",
+    rules:
+      "Action-first and task-oriented; steps first, copyable examples, minimal context; second person, active voice, short sentences",
+  },
+  conceptFirst: {
+    name: "Concept-First Style",
+    rules:
+      "Why/What before How; precise and restrained, provide trade-offs and comparisons; support with architecture/flow/sequence diagrams",
+  },
+  specReference: {
+    name: "Spec-Reference Style",
+    rules:
+      "Objective and precise, no rhetoric; tables/Schema focused, authoritative fields and defaults; clear error codes and multi-language examples",
+  },
+  custom: {
+    name: "Custom Rules",
+    rules: "Enter your own documentation generation rules",
+  },
+};
+
+// Predefined target audiences
+const TARGET_AUDIENCES = {
+  actionFirst: "Developers, Implementation Engineers, DevOps",
+  conceptFirst:
+    "Architects, Technical Leads, Developers interested in principles",
+  generalUsers: "General Users",
+  custom: "Enter your own target audience",
+};
+
 /**
  * Guide users through multi-turn dialogue to collect information and generate YAML configuration
  * @param {Object} params
@@ -9,48 +41,125 @@ import { join, dirname } from "node:path";
  * @returns {Promise<Object>}
  */
 export default async function init(
-  { outputPath = "./doc-smith", fileName = "config.yaml" },
+  { outputPath = "./doc-smith", fileName = "config.yaml", skipIfExists = false },
   options
 ) {
-  console.log("Welcome to AIGNE Doc Smith!");
-  console.log(
-    "I will help you generate a configuration file through several questions.\n"
-  );
+  if (skipIfExists) {
+    const filePath = join(outputPath, fileName);
+    if (await readFile(filePath, "utf8").catch(() => null)) {
+      return {}
+    }
+  }
+
+  console.log("🚀 Welcome to AIGNE Doc Smith!");
+  console.log("Let's create your documentation configuration.\n");
 
   // Collect user information
   const input = {};
 
-  // 1. Document generation rules
-  console.log("=== Document Generation Rules ===");
-  const rulesInput = await options.prompts.input({
-    message: "Please describe the document generation rules and requirements:",
+  // 1. Document generation rules with style selection
+  console.log("📝 Step 1/6: Document Generation Rules");
+
+  // Let user select a document style
+  const styleChoice = await options.prompts.select({
+    message: "Choose your documentation style:",
+    choices: Object.entries(DOCUMENT_STYLES).map(([key, style]) => ({
+      name: `${style.name} - ${style.rules}`,
+      value: key,
+    })),
   });
-  input.rules = rulesInput.trim();
 
-  // 2. Target audience
-  console.log("\n=== Target Audience ===");
-  const targetAudienceInput = await options.prompts.input({
-    message:
-      "What is the target audience? (e.g., developers, users, press Enter for default 'developers'):",
+  let rules;
+  if (styleChoice === "custom") {
+    // User wants to input custom rules
+    rules = await options.prompts.input({
+      message: "Enter your custom documentation rules:",
+    });
+  } else {
+    // Use predefined style directly
+    rules = DOCUMENT_STYLES[styleChoice].rules;
+    console.log(`✅ Selected: ${DOCUMENT_STYLES[styleChoice].name}`);
+  }
+
+  input.rules = rules.trim();
+
+  // 2. Target audience selection
+  console.log("\n👥 Step 2/6: Target Audience");
+
+  // Let user select target audience
+  const audienceChoice = await options.prompts.select({
+    message: "Who is your target audience?",
+    choices: Object.entries(TARGET_AUDIENCES).map(([key, audience]) => ({
+      name: audience,
+      value: key,
+    })),
   });
-  input.targetAudience = targetAudienceInput.trim() || "developers";
+
+  let targetAudience;
+  if (audienceChoice === "custom") {
+    // User wants to input custom audience
+    targetAudience = await options.prompts.input({
+      message: "Enter your custom target audience:",
+    });
+  } else {
+    // Use predefined audience directly
+    targetAudience = TARGET_AUDIENCES[audienceChoice];
+    console.log(`✅ Selected: ${TARGET_AUDIENCES[audienceChoice]}`);
+  }
+
+  input.targetAudience = targetAudience.trim();
 
   // 3. Language settings
-  console.log("\n=== Language Settings ===");
+  console.log("\n🌐 Step 3/6: Primary Language");
   const localeInput = await options.prompts.input({
-    message: "Primary language (e.g., en, zh, press Enter for default 'en'):",
+    message:
+      "Primary documentation language (e.g., en, zh, press Enter for 'en'):",
   });
   input.locale = localeInput.trim() || "en";
 
   // 4. Translation languages
-  console.log("\n=== Translation Settings ===");
-  const translateInput = await options.prompts.input({
-    message:
-      "Translation language list (comma-separated, e.g., zh,en, press Enter to skip):",
+  console.log("\n🔄 Step 4/6: Translation Languages");
+  console.log(
+    "Enter additional languages for translation (press Enter to skip):"
+  );
+  const translateLanguages = [];
+  while (true) {
+    const langInput = await options.prompts.input({
+      message: `Language ${translateLanguages.length + 1} (e.g., zh, ja, fr):`,
+    });
+    if (!langInput.trim()) {
+      break;
+    }
+    translateLanguages.push(langInput.trim());
+  }
+  input.translateLanguages = translateLanguages;
+
+  // 5. Documentation directory
+  console.log("\n📁 Step 5/6: Output Directory");
+  const docsDirInput = await options.prompts.input({
+    message: `Where to save generated docs (press Enter for '${outputPath}/docs'):`,
   });
-  input.translateLanguages = translateInput.trim()
-    ? translateInput.split(",").map((lang) => lang.trim())
-    : [];
+  input.docsDir = docsDirInput.trim() || `${outputPath}/docs`;
+
+  // 6. Source code paths
+  console.log("\n🔍 Step 6/6: Source Code Paths");
+  console.log(
+    "Enter paths to analyze for documentation (press Enter to use './'):"
+  );
+
+  const sourcePaths = [];
+  while (true) {
+    const pathInput = await options.prompts.input({
+      message: `Path ${sourcePaths.length + 1} (e.g., ./src, ./lib):`,
+    });
+    if (!pathInput.trim()) {
+      break;
+    }
+    sourcePaths.push(pathInput.trim());
+  }
+
+  // If no paths entered, use default
+  input.sourcesPath = sourcePaths.length > 0 ? sourcePaths : ["./"];
 
   // Generate YAML content
   const yamlContent = generateYAML(input, outputPath);
@@ -64,12 +173,17 @@ export default async function init(
     await mkdir(dirPath, { recursive: true });
 
     await writeFile(filePath, yamlContent, "utf8");
-    console.log(`\n✅ Configuration file saved to: ${filePath}`);
+    console.log(`\n🎉 Configuration saved to: ${filePath}`);
+    console.log(
+      "💡 You can edit the configuration file anytime to modify settings."
+    );
+    console.log(
+      "🚀 Run 'aigne doc generate' to start documentation generation!"
+    );
 
     return {
       inputGeneratorStatus: true,
       inputGeneratorPath: filePath,
-      inputGeneratorContent: yamlContent,
     };
   } catch (error) {
     console.error(`❌ Failed to save configuration file: ${error.message}`);
@@ -121,11 +235,13 @@ function generateYAML(input, outputPath) {
     yaml += `#   - en  # Example: English translation\n`;
   }
 
-  // Add default directory and source path configurations
-  yaml += `docsDir: ${outputPath}/docs  # Directory to save generated documentation\n`;
-  yaml += `outputDir: ${outputPath}/output  # Directory to save output files\n`;
+  // Add directory and source path configurations
+  yaml += `docsDir: ${input.docsDir}  # Directory to save generated documentation\n`;
+  // yaml += `outputDir: ${outputPath}/output  # Directory to save output files\n`;
   yaml += `sourcesPath:  # Source code paths to analyze\n`;
-  yaml += `  - ./  # Current directory\n`;
+  input.sourcesPath.forEach((path) => {
+    yaml += `  - ${path}\n`;
+  });
 
   return yaml;
 }

package/agents/load-config.mjs

@@ -24,6 +24,7 @@ export default async function loadConfig({ config }) {
       sourcesPath: ["./"],
       docDir: "./doc-smith/docs",
       outputDir: "./doc-smith/output",
+      lastGitHead: parsedConfig.lastGitHead || "",
       ...parsedConfig,
     };
   } catch (error) {