@aigne/doc-smith 0.2.4 → 0.2.6

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.2.6](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.2.5...v0.2.6) (2025-08-12)
+
+
+### Miscellaneous Chores
+
+* release 0.2.6 ([c5b5ea5](https://github.com/AIGNE-io/aigne-doc-smith/commit/c5b5ea5c404d44f3b0d420f0b57e4ae64ae5d624))
+
+## [0.2.5](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.2.4...v0.2.5) (2025-08-08)
+
+
+### Bug Fixes
+
+* polish cli process ([#17](https://github.com/AIGNE-io/aigne-doc-smith/issues/17)) ([4c94263](https://github.com/AIGNE-io/aigne-doc-smith/commit/4c9426378dff9ca3270bd0e455aa6fb1045f6abb))
+
 ## [0.2.4](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.2.3...v0.2.4) (2025-08-07)
 
 

package/README.md

@@ -206,6 +206,7 @@ aigne doc publish --appUrl https://your-discuss-kit-instance.com
 npx --no doc-smith run --entry-agent init
 npx --no doc-smith run --entry-agent generate
 npx --no doc-smith run --entry-agent update 
+npx --no doc-smith run --entry-agent retranslate 
 npx --no doc-smith run --entry-agent publish
 ```
 

package/agents/check-detail-result.mjs

@@ -1,11 +1,9 @@
+import { checkMarkdown } from "../utils/markdown-checker.mjs";
+
 export default async function checkDetailResult({
   structurePlan,
   reviewContent,
 }) {
-  const linkRegex = /(?<!\!)\[([^\]]+)\]\(([^)]+)\)/g;
-  const tableSeparatorRegex = /^\s*\|\s*-+\s*\|\s*$/;
-  const codeBlockRegex = /^\s+```(?:\w+)?$/;
-
   let isApproved = true;
   const detailFeedback = [];
 
@@ -25,125 +23,22 @@ export default async function checkDetailResult({
     allowedLinks.add(flatPath);
   });
 
-  const checkLinks = (text, source) => {
-    let match;
-    while ((match = linkRegex.exec(text)) !== null) {
-      const link = match[2];
-      const trimLink = link.trim();
-
-      // Only check links that processContent would process
-      // Exclude external links and mailto
-      if (/^(https?:\/\/|mailto:)/.test(trimLink)) continue;
-
-      // Preserve anchors
-      const [path, hash] = trimLink.split("#");
-
-      // Only process relative paths or paths starting with /
-      if (!path) continue;
-
-      // Check if this link is in the allowed links set
-      if (!allowedLinks.has(trimLink)) {
-        isApproved = false;
-        detailFeedback.push(
-          `Found a dead link in ${source}: [${match[1]}](${trimLink}), ensure the link exists in the structure plan path`
-        );
-      }
-    }
-  };
-
-  const performAllChecks = (text, source) => {
-    // Split text into lines once and perform all checks in a single pass
-    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;
+  // Run comprehensive markdown validation with all checks
+  try {
+    const markdownErrors = await checkMarkdown(reviewContent, "result", {
+      allowedLinks,
+    });
 
-    for (let i = 0; i < lines.length; i++) {
-      const line = lines[i];
-      const lineNumber = i + 1;
-
-      // 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 = lineNumber;
-          // Calculate indentation level of the code block marker
-          const match = line.match(/^(\s*)(```)/);
-          codeBlockIndentLevel = match ? match[1].length : 0;
-        } else {
-          // Ending the code block
-          inCodeBlock = false;
-          codeBlockIndentLevel = 0;
-        }
-      } 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
-        if (
-          codeBlockIndentLevel > 0 &&
-          contentIndentLevel < codeBlockIndentLevel
-        ) {
-          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 ${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) {
+    if (markdownErrors.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`
-      );
+      detailFeedback.push(...markdownErrors);
     }
-  };
-
-  // Check content
-  checkLinks(reviewContent, "result");
-  performAllChecks(reviewContent, "result");
+  } catch (error) {
+    isApproved = false;
+    detailFeedback.push(
+      `Found markdown validation error in result: ${error.message}`
+    );
+  }
 
   return {
     isApproved,

package/agents/check-structure-plan.mjs

@@ -1,10 +1,13 @@
 import {
   getCurrentGitHead,
   hasFileChangesBetweenCommits,
+  loadConfigFromFile,
+  saveValueToConfig,
+  getProjectInfo,
 } from "../utils/utils.mjs";
 
 export default async function checkStructurePlan(
-  { originalStructurePlan, feedback, lastGitHead, forceRegenerate, ...rest },
+  { originalStructurePlan, feedback, lastGitHead, ...rest },
   options
 ) {
   // Check if we need to regenerate structure plan
@@ -38,17 +41,13 @@ export default async function checkStructurePlan(
         1. 对于新增的内容，可以根据需要新增节点，或补充到原有节点展示
         2. 谨慎删除节点，除非节点关联 sourceIds 都被删除了
         3. 不能修改原有节点的 path
+        4. 根据最新的 Data Sources 按需要更新节点的 sourceIds，如没有大的变化，可以不更新。
       `;
     }
   }
 
   // If no regeneration needed, return original structure plan
-  if (
-    originalStructurePlan &&
-    !feedback &&
-    !shouldRegenerate &&
-    !forceRegenerate
-  ) {
+  if (originalStructurePlan && !feedback && !shouldRegenerate) {
     return {
       structurePlan: originalStructurePlan,
     };
@@ -62,9 +61,59 @@ export default async function checkStructurePlan(
     ...rest,
   });
 
+  let message = "";
+
+  // Check and save project information if user hasn't modified it
+  if (result.projectName || result.projectDesc) {
+    try {
+      const currentConfig = await loadConfigFromFile();
+      const projectInfo = await getProjectInfo();
+
+      // Check if user has modified project information
+      const userModifiedProjectName =
+        currentConfig?.projectName &&
+        currentConfig.projectName !== projectInfo.name;
+      const userModifiedProjectDesc =
+        currentConfig?.projectDesc &&
+        currentConfig.projectDesc !== projectInfo.description;
+
+      // If user hasn't modified project info and it's not from GitHub, save AI output
+      if (!userModifiedProjectName && !userModifiedProjectDesc) {
+        let hasUpdated = false;
+        // Don't update if the current info is from GitHub (meaningful repository info)
+        if (
+          result.projectName &&
+          result.projectName !== projectInfo.name &&
+          !projectInfo.fromGitHub
+        ) {
+          await saveValueToConfig("projectName", result.projectName);
+          message += `Project name: \`${result.projectName}\``;
+          hasUpdated = true;
+        }
+
+        if (
+          result.projectDesc &&
+          result.projectDesc !== projectInfo.description &&
+          !projectInfo.fromGitHub
+        ) {
+          await saveValueToConfig("projectDesc", result.projectDesc);
+          message += `\nProject description: \`${result.projectDesc}\``;
+          hasUpdated = true;
+        }
+
+        if (hasUpdated) {
+          message = `\n### Auto-updated Project Info to \`.aigne/doc-smith/config.yaml\`\n\n${message}\n\n`;
+        }
+      }
+    } catch (error) {
+      console.warn("Failed to check/save project information:", error.message);
+    }
+  }
+
   return {
     ...result,
     feedback: "", // clear feedback
+    projectInfoMessage: message,
     originalStructurePlan: originalStructurePlan
       ? originalStructurePlan
       : JSON.parse(JSON.stringify(result.structurePlan || [])),

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

@@ -15,9 +15,15 @@ skills:
     reflection:
       reviewer: ./check-detail-result.mjs
       is_approved: isApproved
-      max_iterations: 3
+      max_iterations: 5
       return_last_on_max_iterations: true
     task_title: Generate detail for '{{ title }}'
+  - type: transform
+    jsonata: |
+      $merge([
+        $,
+        { "feedback": "" }
+      ])
   - ./batch-translate.yaml
   - ./save-single-doc.mjs
 input_schema:

package/agents/detail-regenerator.yaml

@@ -27,24 +27,16 @@ skills:
       ])
   - ./find-item-by-path.mjs
   - ./format-structure-plan.mjs
-  - ./detail-generator-and-translate.yaml
+  - url: ./detail-generator-and-translate.yaml
+    default_input:
+      isShowMessage: true
 input_schema:
   type: object
   properties:
-    config:
-      type: string
-      description: Path to the config file
-      default: ./doc-smith/config.yaml
-    # nodeName:
-    #   type: string
-    #   description: Name of the section to generate documentation for
-    #   default: Section
-    # locale:
-    #   type: string
-    #   description: Primary language for documentation (e.g., zh, en)
-    # targetAudience:
+    # config:
     #   type: string
-    #   description: Target audience for the documentation
+    #   description: Path to the config file
+    #   default: ./.aigne/doc-smith/config.yaml
     glossary:
       type: string
       description: Glossary of terms for consistent terminology
@@ -54,49 +46,6 @@ input_schema:
     feedback:
       type: string
       description: Feedback for content improvement
-    # sources:
-    #   type: array
-    #   items:
-    #     type: string
-    #   description: Source code files for documentation generation
-    # sourcesPath:
-    #   type: array
-    #   description: Source code paths
-    #   items:
-    #     type: string
-    #   default:
-    #     - ./
-    # includePatterns:
-    #   type: array
-    #   description: File patterns to include
-    #   items:
-    #     type: string
-    # excludePatterns:
-    #   type: array
-    #   description: File patterns to exclude
-    #   items:
-    #     type: string
-    # outputDir:
-    #   type: string
-    #   description: Output directory for intermediate files
-    #   default: ./doc-smith/output
-    # docsDir:
-    #   type: string
-    #   description: Directory to save generated documentation
-    #   default: ./doc-smith/docs
-    # additionalInformation:
-    #   type: string
-    #   description: Additional context or information for documentation
-    # translateLanguages:
-    #   type: array
-    #   items:
-    #     type: string
-    #     description: Target languages for translation (e.g., zh, en)
-    # labels:
-    #   type: array
-    #   items:
-    #     type: string
-    #     description: Tags or labels for categorization
 output_schema:
   type: object
   properties:

package/agents/docs-generator.yaml

@@ -30,7 +30,8 @@ skills:
                 'translates': [$map(translateLanguages, function($lang) { {"language": $lang} })]
               }
             ])
-          })
+          }),
+          "datasources": ""
         }
       ])
   - ./format-structure-plan.mjs
@@ -40,76 +41,19 @@ skills:
 input_schema:
   type: object
   properties:
-    config:
-      type: string
-      description: Path to the config file
-      default: ./doc-smith/config.yaml
-    # nodeName:
-    #   type: string
-    #   description: Name of the section to generate documentation for
-    #   default: Section
-    # rules:
-    #   type: string
-    #   description: Documentation generation requirements and rules
-    # locale:
-    #   type: string
-    #   description: Primary language for documentation (e.g., zh, en)
-    # sources:
-    #   type: array
-    #   items:
-    #     type: string
-    #   description: Source code files for documentation generation
-    # sourcesPath:
-    #   type: array
-    #   description: Source code paths
-    #   items:
-    #     type: string
-    #   default:
-    #     - ./
-    # includePatterns:
-    #   type: array
-    #   description: File patterns to include
-    #   items:
-    #     type: string
-    # excludePatterns:
-    #   type: array
-    #   description: File patterns to exclude
-    #   items:
-    #     type: string
-    # docsDir:
+    # config:
     #   type: string
-    #   description: Directory to save generated documentation
-    #   default: ./doc-smith/docs
-    # outputDir:
-    #   type: string
-    #   description: Output directory for intermediate files
-    #   default: ./doc-smith/output
-    # translateLanguages:
-    #   type: array
-    #   items:
-    #     type: string
-    #     description: Target languages for translation (e.g., zh, en)
+    #   description: Path to the config file
+    #   default: ./.aigne/doc-smith/config.yaml
     glossary:
       type: string
       description: Glossary of terms for consistent terminology
-    # additionalInformation:
-    #   type: string
-    #   description: Additional context or information for documentation
-    # docsType:
-    #   type: string
-    #   description: Type of documentation (general, getting-started, reference, faq)
-    #   default: general
     feedback:
       type: string
       description: Feedback for structure planning adjustments
     forceRegenerate:
       type: boolean
       description: Force regenerate all documentation
-    # labels:
-    #   type: array
-    #   items:
-    #     type: string
-    #     description: Tags or labels for categorization
   required:
     - config
 mode: sequential

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

@@ -1,11 +1,25 @@
-import { readdir } from "node:fs/promises";
+import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 
+// Helper function to get action-specific text based on isTranslate flag
+function getActionText(isTranslate, baseText) {
+  const action = isTranslate ? "retranslate" : "update";
+  return baseText.replace("{action}", action);
+}
+
 export default async function findItemByPath(
-  { "doc-path": docPath, structurePlanResult, boardId, docsDir },
+  {
+    "doc-path": docPath,
+    structurePlanResult,
+    boardId,
+    docsDir,
+    isTranslate,
+    feedback,
+  },
   options
 ) {
   let foundItem = null;
+  let selectedFileContent = null;
 
   // If docPath is empty, let user select from available documents
   if (!docPath) {
@@ -22,14 +36,12 @@ export default async function findItemByPath(
       );
 
       if (mainLanguageFiles.length === 0) {
-        throw new Error(
-          "Please provide a doc-path parameter to specify which document to update"
-        );
+        throw new Error("No documents found in the docs directory");
       }
 
       // Let user select a file
       const selectedFile = await options.prompts.search({
-        message: "Select a document to update:",
+        message: getActionText(isTranslate, "Select a document to {action}:"),
         source: async (input, { signal }) => {
           if (!input || input.trim() === "") {
             return mainLanguageFiles.map((file) => ({
@@ -51,9 +63,19 @@ export default async function findItemByPath(
       });
 
       if (!selectedFile) {
-        throw new Error(
-          "Please provide a doc-path parameter to specify which document to update"
+        throw new Error("No document selected");
+      }
+
+      // Read the selected .md file content
+      try {
+        const selectedFilePath = join(docsDir, selectedFile);
+        selectedFileContent = await readFile(selectedFilePath, "utf-8");
+      } catch (readError) {
+        console.warn(
+          `⚠️  Could not read content from ${selectedFile}:`,
+          readError.message
         );
+        selectedFileContent = null;
       }
 
       // Convert filename back to path
@@ -71,15 +93,17 @@ export default async function findItemByPath(
         return itemFlattenedPath === flatName;
       });
       if (!foundItemByFile) {
-        throw new Error(
-          "Please provide a doc-path parameter to specify which document to update"
-        );
+        throw new Error("No document found");
       }
 
       docPath = foundItemByFile.path;
     } catch (error) {
+      console.error(error);
       throw new Error(
-        "Please provide a doc-path parameter to specify which document to update"
+        getActionText(
+          isTranslate,
+          "Please provide a doc-path parameter to specify which document to {action}"
+        )
       );
     }
   }
@@ -111,8 +135,33 @@ export default async function findItemByPath(
     );
   }
 
-  // Merge the found item with originalStructurePlan
-  return {
+  // Prompt for feedback if not provided
+  let userFeedback = feedback;
+  if (!userFeedback) {
+    const feedbackMessage = getActionText(
+      isTranslate,
+      "Please provide feedback for the {action} (press Enter to skip):"
+    );
+
+    userFeedback = await options.prompts.input({
+      message: feedbackMessage,
+    });
+  }
+
+  // Merge the found item with originalStructurePlan and add content if available
+  const result = {
     ...foundItem,
   };
+
+  // Add content if we read it from user selection
+  if (selectedFileContent !== null) {
+    result.content = selectedFileContent;
+  }
+
+  // Add feedback to result if provided
+  if (userFeedback && userFeedback.trim()) {
+    result.feedback = userFeedback.trim();
+  }
+
+  return result;
 }