@aigne/doc-smith 0.1.4 → 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,13 @@
 # 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)
 
 

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) {

package/agents/load-sources.mjs

@@ -1,67 +1,14 @@
 import { access, readFile } from "node:fs/promises";
 import path from "node:path";
 import { glob } from "glob";
-
-// Default file patterns for inclusion and exclusion
-const DEFAULT_INCLUDE_PATTERNS = [
-  "*.py",
-  "*.js",
-  "*.jsx",
-  "*.ts",
-  "*.tsx",
-  "*.go",
-  "*.java",
-  "*.pyi",
-  "*.pyx",
-  "*.c",
-  "*.cc",
-  "*.cpp",
-  "*.h",
-  "*.md",
-  "*.rst",
-  "*.json",
-  "*Dockerfile",
-  "*Makefile",
-  "*.yaml",
-  "*.yml",
-];
-
-const DEFAULT_EXCLUDE_PATTERNS = [
-  "aigne-docs/**",
-  "doc-smith/**",
-  "assets/**",
-  "data/**",
-  "images/**",
-  "public/**",
-  "static/**",
-  "**/vendor/**",
-  "temp/**",
-  "**/*docs/**",
-  "**/*doc/**",
-  "**/*venv/**",
-  "*.venv/**",
-  "*test*",
-  "**/*test/**",
-  "**/*tests/**",
-  "**/*examples/**",
-  "**/playgrounds/**",
-  "v1/**",
-  "**/dist/**",
-  "**/*build/**",
-  "**/*experimental/**",
-  "**/*deprecated/**",
-  "**/*misc/**",
-  "**/*legacy/**",
-  ".git/**",
-  ".github/**",
-  ".next/**",
-  ".vscode/**",
-  "**/*obj/**",
-  "**/*bin/**",
-  "**/*node_modules/**",
-  "*.log",
-  "**/*test.*",
-];
+import {
+  getCurrentGitHead,
+  getModifiedFilesBetweenCommits,
+} from "../utils/utils.mjs";
+import {
+  DEFAULT_INCLUDE_PATTERNS,
+  DEFAULT_EXCLUDE_PATTERNS,
+} from "../utils/constants.mjs";
 
 /**
  * Load .gitignore patterns from a directory
@@ -158,6 +105,7 @@ export default async function loadSources({
   "doc-path": docPath,
   boardId,
   useDefaultPatterns = true,
+  lastGitHead,
 } = {}) {
   let files = Array.isArray(sources) ? [...sources] : [];
 
@@ -224,9 +172,11 @@ export default async function loadSources({
   const sourceFiles = await Promise.all(
     files.map(async (file) => {
       const content = await readFile(file, "utf8");
-      allSources += `// sourceId: ${file}\n${content}\n`;
+      // Convert absolute path to relative path from project root
+      const relativePath = path.relative(process.cwd(), file);
+      allSources += `// sourceId: ${relativePath}\n${content}\n`;
       return {
-        sourceId: file,
+        sourceId: relativePath,
         content,
       };
     })
@@ -280,12 +230,34 @@ export default async function loadSources({
     }
   }
 
+  // Get git change detection data
+  let modifiedFiles = [];
+  let currentGitHead = null;
+
+  if (lastGitHead) {
+    try {
+      currentGitHead = getCurrentGitHead();
+      if (currentGitHead && currentGitHead !== lastGitHead) {
+        modifiedFiles = getModifiedFilesBetweenCommits(
+          lastGitHead,
+          currentGitHead
+        );
+        console.log(
+          `Detected ${modifiedFiles.length} modified files since last generation`
+        );
+      }
+    } catch (error) {
+      console.warn("Failed to detect git changes:", error.message);
+    }
+  }
+
   return {
     datasourcesList: sourceFiles,
     datasources: allSources,
     content,
     originalStructurePlan,
     files,
+    modifiedFiles,
   };
 }
 
@@ -324,6 +296,10 @@ loadSources.input_schema = {
       type: "string",
       description: "The board ID for boardId-flattenedPath format matching",
     },
+    lastGitHead: {
+      type: "string",
+      description: "The git HEAD from last generation for change detection",
+    },
   },
   required: [],
 };
@@ -349,5 +325,10 @@ loadSources.output_schema = {
       items: { type: "string" },
       description: "Array of file paths that were loaded",
     },
+    modifiedFiles: {
+      type: "array",
+      items: { type: "string" },
+      description: "Array of modified files since last generation",
+    },
   },
 };

package/agents/publish-docs.mjs

@@ -9,8 +9,10 @@ import { homedir } from "node:os";
 import { parse, stringify } from "yaml";
 import { execSync } from "node:child_process";
 import { basename } from "node:path";
+import { loadConfigFromFile, saveValueToConfig } from "../utils/utils.mjs";
 
 const WELLKNOWN_SERVICE_PATH_PREFIX = "/.well-known/service";
+const DEFAULT_APP_URL = "https://docsmith.aigne.io";
 
 /**
  * Get project name from git repository or current directory
@@ -116,51 +118,50 @@ async function getAccessToken(appUrl) {
   return accessToken;
 }
 
-/**
- * Save boardId to config.yaml file if it was auto-created
- * @param {string} boardId - The original boardId (may be empty)
- * @param {string} newBoardId - The boardId returned from publishDocsFn
- */
-async function saveBoardIdToInput(boardId, newBoardId) {
-  // Only save if boardId was auto-created
-  if (!boardId && newBoardId) {
-    try {
-      const docSmithDir = join(process.cwd(), "doc-smith");
-      if (!existsSync(docSmithDir)) {
-        mkdirSync(docSmithDir, { recursive: true });
-      }
-
-      const inputFilePath = join(docSmithDir, "config.yaml");
-      let fileContent = "";
-
-      // Read existing file content if it exists
-      if (existsSync(inputFilePath)) {
-        fileContent = await readFile(inputFilePath, "utf8");
-      }
-
-      // Check if boardId already exists in the file
-      const boardIdRegex = /^boardId:\s*.*$/m;
-      const newBoardIdLine = `boardId: ${newBoardId}`;
-
-      if (boardIdRegex.test(fileContent)) {
-        // Replace existing boardId line
-        fileContent = fileContent.replace(boardIdRegex, newBoardIdLine);
-      } else {
-        // Add boardId to the end of file
-        if (fileContent && !fileContent.endsWith("\n")) {
-          fileContent += "\n";
-        }
-        fileContent += newBoardIdLine + "\n";
-      }
+export default async function publishDocs(
+  { docsDir, appUrl, boardId },
+  options
+) {
+  // Check if appUrl is default and not saved in config
+  const config = await loadConfigFromFile();
+  const isDefaultAppUrl = appUrl === DEFAULT_APP_URL;
+  const hasAppUrlInConfig = config && config.appUrl;
+
+  if (isDefaultAppUrl && !hasAppUrlInConfig) {
+    console.log("\n=== Document Publishing Platform Selection ===");
+    console.log(
+      "Please select the platform where you want to publish your documents:"
+    );
 
-      await writeFile(inputFilePath, fileContent);
-    } catch (error) {
-      console.warn("Failed to save board ID to config.yaml:", error.message);
+    const choice = await options.prompts.select({
+      message: "Select publishing platform:",
+      choices: [
+        {
+          name: "Use official platform (docsmith.aigne.io) - Documents will be publicly accessible, suitable for open source projects",
+          value: "default",
+        },
+        {
+          name: "Use private platform - Deploy your own Discuss Kit instance, suitable for internal documentation",
+          value: "custom",
+        },
+      ],
+    });
+
+    if (choice === "custom") {
+      appUrl = await options.prompts.input({
+        message: "Please enter your Discuss Kit platform URL:",
+        validate: (input) => {
+          try {
+            new URL(input);
+            return true;
+          } catch {
+            return "Please enter a valid URL";
+          }
+        },
+      });
     }
   }
-}
 
-export default async function publishDocs({ docsDir, appUrl, boardId }) {
   const accessToken = await getAccessToken(appUrl);
 
   process.env.DOC_ROOT_DIR = docsDir;
@@ -179,8 +180,16 @@ export default async function publishDocs({ docsDir, appUrl, boardId }) {
     autoCreateBoard: !boardId,
   });
 
-  // Save boardId to config.yaml if it was auto-created
-  await saveBoardIdToInput(boardId, newBoardId);
+  // Save values to config.yaml if publish was successful
+  if (success) {
+    // Save appUrl to config
+    await saveValueToConfig("appUrl", appUrl);
+
+    // Save boardId to config if it was auto-created
+    if (!boardId && newBoardId) {
+      await saveValueToConfig("boardId", newBoardId);
+    }
+  }
 
   return {
     publishResult: {
@@ -199,9 +208,7 @@ publishDocs.input_schema = {
     appUrl: {
       type: "string",
       description: "The url of the app",
-      default:
-        // "https://bbqawfllzdt3pahkdsrsone6p3wpxcwp62vlabtawfu.did.abtnet.io",
-        "https://www.staging.arcblock.io",
+      default: DEFAULT_APP_URL,
     },
     boardId: {
       type: "string",

package/agents/save-docs.mjs

@@ -1,5 +1,6 @@
 import { writeFile, readdir, unlink } from "node:fs/promises";
 import { join } from "node:path";
+import { getCurrentGitHead, saveGitHeadToConfig } from "../utils/utils.mjs";
 
 /**
  * @param {Object} params
@@ -16,6 +17,14 @@ export default async function saveDocs({
 }) {
   const results = [];
 
+  // Save current git HEAD to config.yaml for change detection
+  try {
+    const gitHead = getCurrentGitHead();
+    await saveGitHeadToConfig(gitHead);
+  } catch (err) {
+    console.warn("Failed to save git HEAD:", err.message);
+  }
+
   // Generate _sidebar.md
   try {
     const sidebar = generateSidebar(structurePlan);

package/agents/team-publish-docs.yaml

@@ -5,6 +5,9 @@ alias:
   - p
 description: Publish the documentation to Discuss Kit
 skills:
+  - url: ./input-generator.mjs
+    default_input:
+      skipIfExists: true
   - load-config.mjs
   - publish-docs.mjs
 input_schema:

package/agents/transform-detail-datasources.mjs

@@ -1,14 +1,28 @@
+import { normalizePath, toRelativePath } from "../utils/utils.mjs";
+
 export default function transformDetailDatasources({
   sourceIds,
   datasourcesList,
 }) {
-  // Build a map for fast lookup
+  // Build a map for fast lookup, with path normalization for compatibility
   const dsMap = Object.fromEntries(
-    (datasourcesList || []).map((ds) => [ds.sourceId, ds.content])
+    (datasourcesList || []).map((ds) => {
+      const normalizedSourceId = normalizePath(ds.sourceId);
+      return [normalizedSourceId, ds.content];
+    })
   );
-  // Collect formatted contents in order
+
+  // Collect formatted contents in order, with path normalization
   const contents = (sourceIds || [])
-    .filter((id) => dsMap[id])
-    .map((id) => `// sourceId: ${id}\n${dsMap[id]}\n`);
+    .filter((id) => {
+      const normalizedId = normalizePath(id);
+      return dsMap[normalizedId];
+    })
+    .map((id) => {
+      const normalizedId = normalizePath(id);
+      const relativeId = toRelativePath(id);
+      return `// sourceId: ${relativeId}\n${dsMap[normalizedId]}\n`;
+    });
+
   return { detailDataSources: contents.join("") };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "",
   "publishConfig": {
     "access": "public"

package/prompts/check-structure-planning-result.md

@@ -17,7 +17,7 @@
 ```
 {{ feedback }}
 
-根据最新的 Data Sources 按需要更新节点的 sourceIds ,更新至状态。
+根据最新的 Data Sources 按需要更新节点的 sourceIds。
 ```
 </context>
 

package/prompts/structure-planning.md

@@ -30,7 +30,7 @@
 <structure_plan_feedback>
 {{ feedback }}
 
-根据最新的 Data Sources 按需要更新节点的 sourceIds ,更新至状态。
+根据最新的 Data Sources 按需要更新节点的 sourceIds。
 </structure_plan_feedback>
 
 <review_structure_plan>

package/utils/constants.mjs

@@ -0,0 +1,60 @@
+// Default file patterns for inclusion and exclusion
+export const DEFAULT_INCLUDE_PATTERNS = [
+  "*.py",
+  "*.js",
+  "*.jsx",
+  "*.ts",
+  "*.tsx",
+  "*.go",
+  "*.java",
+  "*.pyi",
+  "*.pyx",
+  "*.c",
+  "*.cc",
+  "*.cpp",
+  "*.h",
+  "*.md",
+  "*.rst",
+  "*.json",
+  "*Dockerfile",
+  "*Makefile",
+  "*.yaml",
+  "*.yml",
+];
+
+export const DEFAULT_EXCLUDE_PATTERNS = [
+  "aigne-docs/**",
+  "doc-smith/**",
+  "assets/**",
+  "data/**",
+  "images/**",
+  "public/**",
+  "static/**",
+  "**/vendor/**",
+  "temp/**",
+  "**/*docs/**",
+  "**/*doc/**",
+  "**/*venv/**",
+  "*.venv/**",
+  "*test*",
+  "**/*test/**",
+  "**/*tests/**",
+  "**/*examples/**",
+  "**/playgrounds/**",
+  "v1/**",
+  "**/dist/**",
+  "**/*build/**",
+  "**/*experimental/**",
+  "**/*deprecated/**",
+  "**/*misc/**",
+  "**/*legacy/**",
+  ".git/**",
+  ".github/**",
+  ".next/**",
+  ".vscode/**",
+  "**/*obj/**",
+  "**/*bin/**",
+  "**/*node_modules/**",
+  "*.log",
+  "**/*test.*",
+];

package/utils/utils.mjs

@@ -1,5 +1,34 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { parse } from "yaml";
+import {
+  DEFAULT_INCLUDE_PATTERNS,
+  DEFAULT_EXCLUDE_PATTERNS,
+} from "./constants.mjs";
+
+/**
+ * Normalize path to absolute path for consistent comparison
+ * @param {string} filePath - The path to normalize
+ * @returns {string} - Absolute path
+ */
+export function normalizePath(filePath) {
+  return path.isAbsolute(filePath)
+    ? filePath
+    : path.resolve(process.cwd(), filePath);
+}
+
+/**
+ * Convert path to relative path from current working directory
+ * @param {string} filePath - The path to convert
+ * @returns {string} - Relative path
+ */
+export function toRelativePath(filePath) {
+  return path.isAbsolute(filePath)
+    ? path.relative(process.cwd(), filePath)
+    : filePath;
+}
 
 export function processContent({ content }) {
   // Match markdown regular links [text](link), exclude images ![text](link)
@@ -95,3 +124,273 @@ export async function saveDocWithTranslations({
   }
   return results;
 }
+
+/**
+ * Get current git HEAD commit hash
+ * @returns {string} - The current git HEAD commit hash
+ */
+export function getCurrentGitHead() {
+  try {
+    return execSync("git rev-parse HEAD", {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "ignore"],
+    }).trim();
+  } catch (error) {
+    // Not in git repository or git command failed
+    console.warn("Failed to get git HEAD:", error.message);
+    return null;
+  }
+}
+
+/**
+ * Save git HEAD to config.yaml file
+ * @param {string} gitHead - The current git HEAD commit hash
+ */
+export async function saveGitHeadToConfig(gitHead) {
+  if (!gitHead) {
+    return; // Skip if no git HEAD available
+  }
+
+  try {
+    const docSmithDir = path.join(process.cwd(), "doc-smith");
+    if (!existsSync(docSmithDir)) {
+      mkdirSync(docSmithDir, { recursive: true });
+    }
+
+    const inputFilePath = path.join(docSmithDir, "config.yaml");
+    let fileContent = "";
+
+    // Read existing file content if it exists
+    if (existsSync(inputFilePath)) {
+      fileContent = await fs.readFile(inputFilePath, "utf8");
+    }
+
+    // Check if lastGitHead already exists in the file
+    const lastGitHeadRegex = /^lastGitHead:\s*.*$/m;
+    const newLastGitHeadLine = `lastGitHead: ${gitHead}`;
+
+    if (lastGitHeadRegex.test(fileContent)) {
+      // Replace existing lastGitHead line
+      fileContent = fileContent.replace(lastGitHeadRegex, newLastGitHeadLine);
+    } else {
+      // Add lastGitHead to the end of file
+      if (fileContent && !fileContent.endsWith("\n")) {
+        fileContent += "\n";
+      }
+      fileContent += newLastGitHeadLine + "\n";
+    }
+
+    await fs.writeFile(inputFilePath, fileContent);
+  } catch (error) {
+    console.warn("Failed to save git HEAD to config.yaml:", error.message);
+  }
+}
+
+/**
+ * Check if files have been modified between two git commits
+ * @param {string} fromCommit - Starting commit hash
+ * @param {string} toCommit - Ending commit hash (defaults to HEAD)
+ * @param {Array<string>} filePaths - Array of file paths to check
+ * @returns {Array<string>} - Array of modified file paths
+ */
+export function getModifiedFilesBetweenCommits(
+  fromCommit,
+  toCommit = "HEAD",
+  filePaths = []
+) {
+  try {
+    // Get all modified files between commits
+    const modifiedFiles = execSync(
+      `git diff --name-only ${fromCommit}..${toCommit}`,
+      {
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "ignore"],
+      }
+    )
+      .trim()
+      .split("\n")
+      .filter(Boolean);
+
+    // Filter to only include files we care about
+    if (filePaths.length === 0) {
+      return modifiedFiles;
+    }
+
+    return modifiedFiles.filter((file) =>
+      filePaths.some((targetPath) => {
+        const absoluteFile = normalizePath(file);
+        const absoluteTarget = normalizePath(targetPath);
+        return absoluteFile === absoluteTarget;
+      })
+    );
+  } catch (error) {
+    console.warn(
+      `Failed to get modified files between ${fromCommit} and ${toCommit}:`,
+      error.message
+    );
+    return [];
+  }
+}
+
+/**
+ * Check if any source files have changed based on modified files list
+ * @param {Array<string>} sourceIds - Source file paths
+ * @param {Array<string>} modifiedFiles - List of modified files between commits
+ * @returns {boolean} - True if any source files have changed
+ */
+export function hasSourceFilesChanged(sourceIds, modifiedFiles) {
+  if (!sourceIds || sourceIds.length === 0 || !modifiedFiles) {
+    return false; // No source files or no modified files
+  }
+
+  return modifiedFiles.some((modifiedFile) =>
+    sourceIds.some((sourceId) => {
+      const absoluteModifiedFile = normalizePath(modifiedFile);
+      const absoluteSourceId = normalizePath(sourceId);
+      return absoluteModifiedFile === absoluteSourceId;
+    })
+  );
+}
+
+/**
+ * Check if there are any added or deleted files between two git commits that match the include/exclude patterns
+ * @param {string} fromCommit - Starting commit hash
+ * @param {string} toCommit - Ending commit hash (defaults to HEAD)
+ * @param {Array<string>} includePatterns - Include patterns to match files
+ * @param {Array<string>} excludePatterns - Exclude patterns to filter files
+ * @returns {boolean} - True if there are relevant added/deleted files
+ */
+export function hasFileChangesBetweenCommits(
+  fromCommit,
+  toCommit = "HEAD",
+  includePatterns = DEFAULT_INCLUDE_PATTERNS,
+  excludePatterns = DEFAULT_EXCLUDE_PATTERNS
+) {
+  try {
+    // Get file changes with status (A=added, D=deleted, M=modified)
+    const changes = execSync(
+      `git diff --name-status ${fromCommit}..${toCommit}`,
+      {
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "ignore"],
+      }
+    )
+      .trim()
+      .split("\n")
+      .filter(Boolean);
+
+    // Only check for added (A) and deleted (D) files
+    const addedOrDeletedFiles = changes
+      .filter((line) => {
+        const [status, filePath] = line.split(/\s+/);
+        return (status === "A" || status === "D") && filePath;
+      })
+      .map((line) => line.split(/\s+/)[1]);
+
+    if (addedOrDeletedFiles.length === 0) {
+      return false;
+    }
+
+    // Check if any of the added/deleted files match the include patterns and don't match exclude patterns
+    return addedOrDeletedFiles.some((filePath) => {
+      // Check if file matches any include pattern
+      const matchesInclude = includePatterns.some((pattern) => {
+        // Convert glob pattern to regex for matching
+        const regexPattern = pattern
+          .replace(/\./g, "\\.")
+          .replace(/\*/g, ".*")
+          .replace(/\?/g, ".");
+        const regex = new RegExp(regexPattern);
+        return regex.test(filePath);
+      });
+
+      if (!matchesInclude) {
+        return false;
+      }
+
+      // Check if file matches any exclude pattern
+      const matchesExclude = excludePatterns.some((pattern) => {
+        // Convert glob pattern to regex for matching
+        const regexPattern = pattern
+          .replace(/\./g, "\\.")
+          .replace(/\*/g, ".*")
+          .replace(/\?/g, ".");
+        const regex = new RegExp(regexPattern);
+        return regex.test(filePath);
+      });
+
+      return !matchesExclude;
+    });
+  } catch (error) {
+    console.warn(
+      `Failed to check file changes between ${fromCommit} and ${toCommit}:`,
+      error.message
+    );
+    return false;
+  }
+}
+
+/**
+ * Load config from config.yaml file
+ * @returns {Promise<Object|null>} - The config object or null if file doesn't exist
+ */
+export async function loadConfigFromFile() {
+  const configPath = path.join(process.cwd(), "doc-smith", "config.yaml");
+
+  try {
+    if (!existsSync(configPath)) {
+      return null;
+    }
+
+    const configContent = await fs.readFile(configPath, "utf8");
+    return parse(configContent);
+  } catch (error) {
+    console.warn("Failed to read config file:", error.message);
+    return null;
+  }
+}
+
+/**
+ * Save value to config.yaml file
+ * @param {string} key - The config key to save
+ * @param {string} value - The value to save
+ */
+export async function saveValueToConfig(key, value) {
+  if (!value) {
+    return; // Skip if no value provided
+  }
+
+  try {
+    const docSmithDir = path.join(process.cwd(), "doc-smith");
+    if (!existsSync(docSmithDir)) {
+      mkdirSync(docSmithDir, { recursive: true });
+    }
+
+    const configPath = path.join(docSmithDir, "config.yaml");
+    let fileContent = "";
+
+    // Read existing file content if it exists
+    if (existsSync(configPath)) {
+      fileContent = await fs.readFile(configPath, "utf8");
+    }
+
+    // Check if key already exists in the file
+    const keyRegex = new RegExp(`^${key}:\\s*.*$`, "m");
+    const newKeyLine = `${key}: ${value}`;
+
+    if (keyRegex.test(fileContent)) {
+      // Replace existing key line
+      fileContent = fileContent.replace(keyRegex, newKeyLine);
+    } else {
+      // Add key to the end of file
+      if (fileContent && !fileContent.endsWith("\n")) {
+        fileContent += "\n";
+      }
+      fileContent += newKeyLine + "\n";
+    }
+
+    await fs.writeFile(configPath, fileContent);
+  } catch (error) {
+    console.warn(`Failed to save ${key} to config.yaml:`, error.message);
+  }
+}