@aigne/doc-smith 0.1.4 → 0.2.1

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.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.2.0...v0.2.1) (2025-08-06)
+
+
+### Miscellaneous Chores
+
+* release 0.2.1 ([e3a39ae](https://github.com/AIGNE-io/aigne-doc-smith/commit/e3a39aedcee129deae424e96942f9798b9191663))
+
+## [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/README.md

@@ -63,8 +63,10 @@ npx --no doc-smith run --entry-agent init
 # 生成命令
 npx --no doc-smith run --entry-agent generate --model gemini:gemini-2.5-flash
 
+aigne run --path /Users/lban/arcblock/code/aigne-doc-smith/ --entry-agent generate --model gemini:gemini-2.5-flash --input-forceRegenerate=true
+
 # 重新生成单篇
-npx --no doc-smith run --entry-agent update --input-path bitnet-getting-started
+npx --no doc-smith run --entry-agent update --input-doc-path bitnet-getting-started
 
 # 结构规划优化
 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

@@ -1,8 +1,8 @@
 type: team
-name: batch-docs-detail-generator
+name: batchDocsDetailGenerator
 description: 批量生成文档详情
 skills:
-  - ./check-detail-generated.mjs
+  - ./check-detail.mjs
 input_schema:
   type: object
   properties:
@@ -10,5 +10,10 @@ 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
+concurrency: 3
 mode: sequential

package/agents/batch-translate.yaml

@@ -1,5 +1,5 @@
 type: team
-name: batch-translate
+name: batchTranslate
 description: 批量翻译文档到多个语言
 skills:
   - type: team

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-detail-generated.mjs → check-detail.mjs}

@@ -3,12 +3,23 @@ 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 },
+export default async function checkDetail(
+  {
+    path,
+    docsDir,
+    sourceIds,
+    originalStructurePlan,
+    structurePlan,
+    modifiedFiles,
+    lastGitHead,
+    forceRegenerate,
+    ...rest
+  },
   options
 ) {
   // Check if the detail file already exists
@@ -61,6 +72,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 +100,14 @@ 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 &&
+    forceRegenerate !== "true"
+  ) {
     return {
       path,
       docsDir,
@@ -85,8 +117,8 @@ export default async function checkDetailGenerated(
   }
 
   const teamAgent = TeamAgent.from({
-    name: "generate-detail",
-    skills: [options.context.agents["detail-generator-and-translate"]],
+    name: "generateDetail",
+    skills: [options.context.agents["detailGeneratorAndTranslate"]],
   });
 
   const result = await options.context.invoke(teamAgent, {

package/agents/check-structure-plan.mjs

@@ -0,0 +1,72 @@
+import {
+  getCurrentGitHead,
+  hasFileChangesBetweenCommits,
+} from "../utils/utils.mjs";
+
+export default async function checkStructurePlan(
+  { originalStructurePlan, feedback, lastGitHead, forceRegenerate, ...rest },
+  options
+) {
+  // 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 &&
+    forceRegenerate !== "true"
+  ) {
+    return {
+      structurePlan: originalStructurePlan,
+    };
+  }
+
+  const panningAgent = options.context.agents["reflectiveStructurePlanner"];
+
+  const result = await options.context.invoke(panningAgent, {
+    feedback: finalFeedback || "",
+    originalStructurePlan,
+    ...rest,
+  });
+
+  return {
+    ...result,
+    feedback: "", // clear feedback
+    originalStructurePlan: originalStructurePlan
+      ? originalStructurePlan
+      : JSON.parse(JSON.stringify(result.structurePlan || [])),
+  };
+}

package/agents/check-structure-planning-result.yaml

@@ -1,4 +1,4 @@
-name: check-structure-planning-result
+name: checkStructurePlanResult
 description: 对 structure-planning agent 生成的结果进行检查，确保其符合预期，特别是在有上一轮生成结果和用户反馈的场景下。
 instructions:
   url: ../prompts/check-structure-planning-result.md

package/agents/content-detail-generator.yaml

@@ -1,4 +1,4 @@
-name: content-detail-generator
+name: contentDetailGenerator
 description: 通用内容详情生成器，支持网站、文档、书籍、演示文稿等多种场景
 instructions:
   url: ../prompts/content-detail-generator.md

package/agents/detail-generator-and-translate.yaml

@@ -1,5 +1,5 @@
 type: team
-name: detail-generator-and-translate
+name: detailGeneratorAndTranslate
 description: 生成文档详情并翻译
 skills:
   - ./transform-detail-datasources.mjs

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,18 +5,20 @@ 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
-  - type: transform
-    jsonata: |
-      $merge([$, {
-      "saveKey": "structurePlan",
-      "savePath": outputDir,
-      "fileName": "structure-plan.json"
-      }])
-  - ./save-output.mjs
+  - ./check-structure-plan.mjs
+  - url: ./save-output.mjs
+    default_input:
+      saveKey: structurePlan
+      savePath:
+        $get: outputDir
+      fileName: structure-plan.json
   - type: transform
+    name: transformData
     jsonata: |
       $merge([
         $,
@@ -100,6 +102,9 @@ input_schema:
     feedback:
       type: string
       description: Feedback for structure planning adjustments
+    forceRegenerate:
+      type: string
+      description: Force regenerate the documentation
     # labels:
     #   type: array
     #   items:

package/agents/find-item-by-path.mjs

@@ -1,10 +1,89 @@
-export default async function findItemByPath({
-  "doc-path": docPath,
-  structurePlanResult,
-  boardId,
-}) {
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+export default async function findItemByPath(
+  { "doc-path": docPath, structurePlanResult, boardId, docsDir },
+  options
+) {
   let foundItem = null;
 
+  // If docPath is empty, let user select from available documents
+  if (!docPath) {
+    try {
+      // Get all .md files in docsDir
+      const files = await readdir(docsDir);
+
+      // Filter for main language .md files (exclude _sidebar.md and language-specific files)
+      const mainLanguageFiles = files.filter(
+        (file) =>
+          file.endsWith(".md") &&
+          file !== "_sidebar.md" &&
+          !file.match(/\.\w+(-\w+)?\.md$/) // Exclude language-specific files like .en.md, .zh-CN.md, etc.
+      );
+
+      if (mainLanguageFiles.length === 0) {
+        throw new Error(
+          "Please provide a doc-path parameter to specify which document to update"
+        );
+      }
+
+      // Let user select a file
+      const selectedFile = await options.prompts.search({
+        message: "Select a document to update:",
+        source: async (input, { signal }) => {
+          if (!input || input.trim() === "") {
+            return mainLanguageFiles.map((file) => ({
+              name: file,
+              value: file,
+            }));
+          }
+
+          const searchTerm = input.trim().toLowerCase();
+          const filteredFiles = mainLanguageFiles.filter((file) =>
+            file.toLowerCase().includes(searchTerm)
+          );
+
+          return filteredFiles.map((file) => ({
+            name: file,
+            value: file,
+          }));
+        },
+      });
+
+      if (!selectedFile) {
+        throw new Error(
+          "Please provide a doc-path parameter to specify which document to update"
+        );
+      }
+
+      // Convert filename back to path
+      // Remove .md extension
+      const flatName = selectedFile.replace(/\.md$/, "");
+
+      // Try to find matching item by comparing flattened paths
+      let foundItemByFile = null;
+
+      // First try without boardId prefix
+      foundItemByFile = structurePlanResult.find((item) => {
+        const itemFlattenedPath = item.path
+          .replace(/^\//, "")
+          .replace(/\//g, "-");
+        return itemFlattenedPath === flatName;
+      });
+      if (!foundItemByFile) {
+        throw new Error(
+          "Please provide a doc-path parameter to specify which document to update"
+        );
+      }
+
+      docPath = foundItemByFile.path;
+    } catch (error) {
+      throw new Error(
+        "Please provide a doc-path parameter to specify which document to update"
+      );
+    }
+  }
+
   // First try direct path matching
   foundItem = structurePlanResult.find((item) => item.path === docPath);