@aigne/doc-smith 0.8.6 → 0.8.7

package/agents/{check-detail.mjs → update/check-document.mjs}

@@ -2,19 +2,19 @@ import { access, readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { TeamAgent } from "@aigne/core";
-import { hasSourceFilesChanged } from "../utils/utils.mjs";
-import checkDetailResult from "./check-detail-result.mjs";
+import { hasSourceFilesChanged } from "../../utils/utils.mjs";
+import checkDetailResult from "../utils/check-detail-result.mjs";
 
 // Get current script directory
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-export default async function checkDetail(
+export default async function checkDocument(
   {
     path,
     docsDir,
     sourceIds,
-    originalStructurePlan,
-    structurePlan,
+    originalDocumentStructure,
+    documentStructure,
     modifiedFiles,
     forceRegenerate,
     ...rest
@@ -36,11 +36,11 @@ export default async function checkDetail(
     detailGenerated = false;
   }
 
-  // Check if sourceIds have changed by comparing with original structure plan
+  // Check if sourceIds have changed by comparing with original document structure
   let sourceIdsChanged = false;
-  if (originalStructurePlan && sourceIds) {
-    // Find the original node in the structure plan
-    const originalNode = originalStructurePlan.find((node) => node.path === path);
+  if (originalDocumentStructure && sourceIds) {
+    // Find the original node in the document structure
+    const originalNode = originalDocumentStructure.find((node) => node.path === path);
 
     if (originalNode?.sourceIds) {
       const originalSourceIds = originalNode.sourceIds;
@@ -82,9 +82,9 @@ export default async function checkDetail(
   // If file exists, check content validation
   let contentValidationFailed = false;
   let validationResult = {};
-  if (detailGenerated && fileContent && structurePlan) {
+  if (detailGenerated && fileContent && documentStructure) {
     validationResult = await checkDetailResult({
-      structurePlan,
+      documentStructure,
       reviewContent: fileContent,
       docsDir,
     });
@@ -111,8 +111,8 @@ export default async function checkDetail(
   }
 
   const teamAgent = TeamAgent.from({
-    name: "generateDetail",
-    skills: [options.context.agents["detailGeneratorAndTranslate"]],
+    name: "generateDocument",
+    skills: [options.context.agents["generateAndTranslateDocument"]],
   });
 
   const result = await options.context.invoke(teamAgent, {
@@ -120,8 +120,8 @@ export default async function checkDetail(
     docsDir,
     path,
     sourceIds,
-    originalStructurePlan,
-    structurePlan,
+    originalDocumentStructure,
+    documentStructure,
     detailFeedback: contentValidationFailed ? validationResult.detailFeedback : "",
   });
 
@@ -133,4 +133,4 @@ export default async function checkDetail(
   };
 }
 
-checkDetail.taskTitle = "Check if '{{ title }}' needs regeneration";
+checkDocument.taskTitle = "Check if '{{ title }}' needs generate or update";

package/agents/{detail-generator-and-translate.yaml → update/generate-and-translate-document.yaml}

@@ -1,16 +1,16 @@
 type: team
-name: detailGeneratorAndTranslate
-description: 生成文档详情并翻译
+name: generateAndTranslateDocument
+description: Generate document and translate
 skills:
-  - ./transform-detail-datasources.mjs
+  - ../utils/transform-detail-datasources.mjs
   - type: team
     task_render_mode: collapse
-    name: detailGenerate
+    name: generateDocumentContent
     skills:
-      - url: ./find-user-preferences-by-path.mjs
+      - url: ../utils/find-user-preferences-by-path.mjs
         default_input:
           scope: document
-      - ./content-detail-generator.yaml
+      - ../update/generate-document.yaml
       - type: transform
         jsonata: |
           $merge([
@@ -18,11 +18,11 @@ skills:
             { "reviewContent": content }
           ])
     reflection:
-      reviewer: ./check-detail-result.mjs
+      reviewer: ../utils/check-detail-result.mjs
       is_approved: isApproved
       max_iterations: 5
       return_last_on_max_iterations: true
-    task_title: Generate detail for '{{ title }}'
+    task_title: Generate document for '{{ title }}'
   - type: transform
     task_render_mode: hide
     jsonata: |
@@ -30,63 +30,63 @@ skills:
         $,
         { "feedback": "" }
       ])
-  - ./batch-translate.yaml
-  - ./save-single-doc.mjs
+  - ../translate/translate-multilingual.yaml
+  - ../utils/save-single-doc.mjs
 input_schema:
   type: object
   properties:
     nodeName:
       type: string
-      description: 节点名称
+      description: Node name
       default: Section
     locale:
       type: string
-      description: 语言
+      description: Language
     targetAudience:
       type: string
-      description: 目标受众
+      description: Target audience
     glossary:
       type: string
-      description: 术语表
+      description: Glossary
     doc-path:
       type: string
-      description: 当前路径
+      description: Current path
     feedback:
       type: string
-      description: 反馈
+      description: Feedback
     sources:
       type: array
       items:
         type: string
-        description: 源码路径
+        description: Source code path
     sourcesPath:
       type: array
       items:
         type: string
-        description: 源码路径
+        description: Source code path
       default:
         - ./
     includePatterns:
       type: array
       items:
         type: string
-        description: 包含的文件名
+        description: Included file names
     excludePatterns:
       type: array
       items:
         type: string
-        description: 排除的文件名
+        description: Excluded file names
     outputDir:
       type: string
-      description: 输出目录
+      description: Output directory
       default: ./aigne-docs/output
     docsDir:
       type: string
-      description: 文档目录
+      description: Documentation directory
       default: ./aigne-docs/docs
     additionalInformation:
       type: string
-      description: 额外补充信息
+      description: Additional information
 output_schema:
   type: object
   properties:

package/agents/update/generate-document.yaml

@@ -0,0 +1,50 @@
+name: generateDocument
+description: Comprehensive content generator for documentation that creates detailed, high-quality document content from various data sources with intelligent analysis.
+instructions:
+  url: ../../prompts/detail/generate-document.md
+input_schema:
+  type: object
+  properties:
+    rules:
+      type: string
+      description: User's content generation rules and requirements
+    locale:
+      type: string
+      description: User language, such as zh, en
+    datasources:
+      type: string
+      description: Source data and context for document content generation
+    targetAudience:
+      type: string
+      description: Target audience for document content
+    nodeName:
+      type: string
+      description: Document node name for content generation
+    originalDocumentStructure: ../schema/document-structure.yaml
+    title:
+      type: string
+    description:
+      type: string
+    path:
+      type: string
+    parentId:
+      type:
+        - string
+        - "null"
+    glossary:
+      type: string
+      description: Glossary
+    additionalInformation:
+      type: string
+      description: Additional supplementary information
+  required:
+    - rules
+    - datasources
+    - originalDocumentStructure
+output_schema:
+  type: object
+  properties:
+    content:
+      type: string
+  required:
+    - content

package/agents/{detail-regenerator.yaml → update/index.yaml}

@@ -4,19 +4,18 @@ alias:
   - up
 description: Update specific documents and their translations
 skills:
-  - url: ./input-generator.mjs
+  - url: ../init/index.mjs
     default_input:
       skipIfExists: true
-  - ./load-config.mjs
-  - ./load-sources.mjs
+  - ../utils/load-sources.mjs
   - type: transform
     task_render_mode: hide
     jsonata: |
       $merge([
         $,
         {
-          'structurePlan': originalStructurePlan,
-          'structurePlanResult': $map(originalStructurePlan, function($item) {
+          'documentStructure': originalDocumentStructure,
+          'documentExecutionStructure': $map(originalDocumentStructure, function($item) {
             $merge([
               $item,
               {
@@ -26,18 +25,18 @@ skills:
           })
         }
       ])
-  - ./find-items-by-paths.mjs
-  - ./format-structure-plan.mjs
+  - ../utils/choose-docs.mjs
+  - ../utils/format-document-structure.mjs
   - type: team
-    name: batchDocsUpdate
+    name: batchUpdateDocument
     skills:
-      - ./detail-generator-and-translate.yaml
+      - ../update/generate-and-translate-document.yaml
     iterate_on: selectedDocs
     concurrency: 3
-  - url: ./check-feedback-refiner.mjs
+  - url: ../utils/check-feedback-refiner.mjs
     default_input:
       stage: document_refine
-  - url: ./action-success.mjs
+  - url: ../utils/action-success.mjs
     default_input:
       action: "✅ Documents updated successfully"
 input_schema:

package/agents/{action-success.mjs → utils/action-success.mjs}

@@ -1,4 +1,4 @@
-import { shutdownMermaidWorkerPool } from "../utils/mermaid-worker-pool.mjs";
+import { shutdownMermaidWorkerPool } from "../../utils/mermaid-worker-pool.mjs";
 
 export default async function actionSuccess({ action }) {
   // Shutdown mermaid worker pool to ensure clean exit

package/agents/{check-detail-result.mjs → utils/check-detail-result.mjs}

@@ -1,6 +1,6 @@
-import { checkMarkdown } from "../utils/markdown-checker.mjs";
+import { checkMarkdown } from "../../utils/markdown-checker.mjs";
 
-export default async function checkDetailResult({ structurePlan, reviewContent, docsDir }) {
+export default async function checkDetailResult({ documentStructure, reviewContent, docsDir }) {
   if (!reviewContent || reviewContent.trim() === "") {
     return {
       isApproved: false,
@@ -13,7 +13,7 @@ export default async function checkDetailResult({ structurePlan, reviewContent,
 
   // Create a set of allowed links, including both original paths and processed .md paths
   const allowedLinks = new Set();
-  structurePlan.forEach((item) => {
+  documentStructure.forEach((item) => {
     // Add original path
     allowedLinks.add(item.path);
 

package/agents/{check-feedback-refiner.mjs → utils/check-feedback-refiner.mjs}

@@ -1,12 +1,12 @@
 import { stringify } from "yaml";
-import { addPreferenceRule, readPreferences } from "../utils/preferences-utils.mjs";
+import { addPreferenceRule, readPreferences } from "../../utils/preferences-utils.mjs";
 
 export default async function checkFeedbackRefiner(
-  { feedback, stage, selectedPaths, structurePlanFeedback },
+  { feedback, stage, selectedPaths, documentStructureFeedback },
   options,
 ) {
   // If feedback is empty, no need to save user preferences
-  if (!feedback && !structurePlanFeedback) {
+  if (!feedback && !documentStructureFeedback) {
     return {};
   }
 
@@ -18,7 +18,7 @@ export default async function checkFeedbackRefiner(
   const activePreferencesYaml =
     activePreferences.length > 0 ? stringify({ rules: activePreferences }, { indent: 2 }) : "";
 
-  const feedbackToUse = feedback || structurePlanFeedback;
+  const feedbackToUse = feedback || documentStructureFeedback;
   const result = await options.context.invoke(options.context.agents["feedbackRefiner"], {
     feedback: feedbackToUse,
     stage,
@@ -60,9 +60,9 @@ checkFeedbackRefiner.input_schema = {
       type: "string",
       description: "User feedback to refine",
     },
-    structurePlanFeedback: {
+    documentStructureFeedback: {
       type: "string",
-      description: "Feedback from structure planning stage",
+      description: "Feedback from document structure stage",
     },
     stage: {
       type: "string",

package/agents/{find-items-by-paths.mjs → utils/choose-docs.mjs}

@@ -4,10 +4,19 @@ import {
   getActionText,
   getMainLanguageFiles,
   processSelectedFiles,
-} from "../utils/docs-finder-utils.mjs";
-
-export default async function selectedDocs(
-  { docs, structurePlanResult, boardId, docsDir, isTranslate, feedback, locale, reset = false },
+} from "../../utils/docs-finder-utils.mjs";
+
+export default async function chooseDocs(
+  {
+    docs,
+    documentExecutionStructure,
+    boardId,
+    docsDir,
+    isTranslate,
+    feedback,
+    locale,
+    reset = false,
+  },
   options,
 ) {
   let foundItems = [];
@@ -17,7 +26,11 @@ export default async function selectedDocs(
   if (!docs || docs.length === 0) {
     try {
       // Get all main language .md files in docsDir
-      const mainLanguageFiles = await getMainLanguageFiles(docsDir, locale, structurePlanResult);
+      const mainLanguageFiles = await getMainLanguageFiles(
+        docsDir,
+        locale,
+        documentExecutionStructure,
+      );
 
       if (mainLanguageFiles.length === 0) {
         throw new Error("No documents found in the docs directory");
@@ -49,7 +62,7 @@ export default async function selectedDocs(
       }
 
       // Process selected files and convert to found items
-      foundItems = await processSelectedFiles(selectedFiles, structurePlanResult, docsDir);
+      foundItems = await processSelectedFiles(selectedFiles, documentExecutionStructure, docsDir);
     } catch (error) {
       console.error(error);
       throw new Error(
@@ -63,7 +76,7 @@ export default async function selectedDocs(
     // Process the provided docs array
     for (const docPath of docs) {
       const foundItem = await findItemByPath(
-        structurePlanResult,
+        documentExecutionStructure,
         docPath,
         boardId,
         docsDir,
@@ -71,7 +84,7 @@ export default async function selectedDocs(
       );
 
       if (!foundItem) {
-        console.warn(`⚠️  Item with path "${docPath}" not found in structurePlanResult`);
+        console.warn(`⚠️  Item with path "${docPath}" not found in documentExecutionStructure`);
         continue;
       }
 
@@ -81,7 +94,9 @@ export default async function selectedDocs(
     }
 
     if (foundItems.length === 0) {
-      throw new Error("None of the specified document paths were found in structurePlanResult");
+      throw new Error(
+        "None of the specified document paths were found in documentExecutionStructure",
+      );
     }
   }
 

package/agents/{docs-fs.yaml → utils/docs-fs-actor.yaml}

@@ -2,7 +2,9 @@ type: team
 name: docs_fs_actor
 description: File system operations for documentation management
 skills:
-  - ./load-config.mjs
+  - url: ../init/index.mjs
+    default_input:
+      skipIfExists: true
   - url: ./fs.mjs
     default_input:
       rootDir:

package/agents/{feedback-refiner.yaml → utils/feedback-refiner.yaml}

@@ -1,9 +1,7 @@
 name: feedbackRefiner
 description: Learn from your feedback to improve future documentation
-
-# The instructions file contains the core logic (the prompt) for this Agent.
 instructions:
-  url: ../prompts/feedback-refiner.md
+  url: ../../prompts/utils/feedback-refiner.md
 
 input_schema:
   type: object
@@ -13,7 +11,7 @@ input_schema:
       description: Tell us what you think about the documentation
     stage:
       type: string
-      description: Which part of the process this feedback is about (structure_planning, document_refine, translation_refine)
+      description: Which part of the process this feedback is about (document_structure, document_refine, translation_refine)
     paths:
       type: array
       items:

package/agents/{find-item-by-path.mjs → utils/find-item-by-path.mjs}

@@ -5,10 +5,10 @@ import {
   getActionText,
   getMainLanguageFiles,
   readFileContent,
-} from "../utils/docs-finder-utils.mjs";
+} from "../../utils/docs-finder-utils.mjs";
 
 export default async function findItemByPath(
-  { doc, structurePlanResult, boardId, docsDir, isTranslate, feedback, locale },
+  { doc, documentExecutionStructure, boardId, docsDir, isTranslate, feedback, locale },
   options,
 ) {
   let foundItem = null;
@@ -19,7 +19,11 @@ export default async function findItemByPath(
   if (!docPath) {
     try {
       // Get all main language .md files in docsDir
-      const mainLanguageFiles = await getMainLanguageFiles(docsDir, locale, structurePlanResult);
+      const mainLanguageFiles = await getMainLanguageFiles(
+        docsDir,
+        locale,
+        documentExecutionStructure,
+      );
 
       if (mainLanguageFiles.length === 0) {
         throw new Error("No documents found in the docs directory");
@@ -59,7 +63,7 @@ export default async function findItemByPath(
       const flatName = fileNameToFlatPath(selectedFile);
 
       // Try to find matching item by comparing flattened paths
-      const foundItemByFile = findItemByFlatName(structurePlanResult, flatName);
+      const foundItemByFile = findItemByFlatName(documentExecutionStructure, flatName);
 
       if (!foundItemByFile) {
         throw new Error("No document found");
@@ -78,10 +82,16 @@ export default async function findItemByPath(
   }
 
   // Use the utility function to find item and read content
-  foundItem = await findItemByPathUtil(structurePlanResult, docPath, boardId, docsDir, locale);
+  foundItem = await findItemByPathUtil(
+    documentExecutionStructure,
+    docPath,
+    boardId,
+    docsDir,
+    locale,
+  );
 
   if (!foundItem) {
-    throw new Error(`Item with path "${docPath}" not found in structurePlanResult`);
+    throw new Error(`Item with path "${docPath}" not found in documentExecutionStructure`);
   }
 
   // Prompt for feedback if not provided

package/agents/{find-user-preferences-by-path.mjs → utils/find-user-preferences-by-path.mjs}

@@ -1,4 +1,4 @@
-import { getActiveRulesForScope } from "../utils/preferences-utils.mjs";
+import { getActiveRulesForScope } from "../../utils/preferences-utils.mjs";
 
 export default async function findUserPreferencesByPath({ path, scope }) {
   // Get global rules (always applicable)

package/agents/utils/format-document-structure.mjs

@@ -0,0 +1,25 @@
+import { stringify } from "yaml";
+
+export default async function formatDocumentStructure({ documentStructure }) {
+  // Extract required fields from each item in documentStructure
+  const formattedData = documentStructure.map((item) => ({
+    title: item.title,
+    path: item.path,
+    parentId: item.parentId,
+    description: item.description,
+  }));
+
+  // Convert to YAML string
+  const yamlString = stringify(formattedData, {
+    indent: 2,
+    lineWidth: 120,
+    minContentWidth: 20,
+  });
+
+  return {
+    documentStructureYaml: yamlString,
+    documentStructure,
+  };
+}
+
+formatDocumentStructure.task_render_mode = "hide";

package/agents/{load-sources.mjs → utils/load-sources.mjs}

@@ -1,12 +1,12 @@
-import { access, readFile, stat } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
-import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_INCLUDE_PATTERNS } from "../utils/constants.mjs";
-import { getFilesWithGlob, loadGitignore } from "../utils/file-utils.mjs";
+import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_INCLUDE_PATTERNS } from "../../utils/constants.mjs";
+import { getFilesWithGlob, loadGitignore } from "../../utils/file-utils.mjs";
 import {
   getCurrentGitHead,
   getModifiedFilesBetweenCommits,
   isGlobPattern,
-} from "../utils/utils.mjs";
+} from "../../utils/utils.mjs";
 
 export default async function loadSources({
   sources = [],
@@ -172,48 +172,61 @@ export default async function loadSources({
     }),
   );
 
-  // Get the last structure plan result
-  let originalStructurePlan;
-  const structurePlanPath = path.join(outputDir, "structure-plan.json");
-  try {
-    await access(structurePlanPath);
-    const structurePlanResult = await readFile(structurePlanPath, "utf8");
-    if (structurePlanResult) {
-      try {
-        originalStructurePlan = JSON.parse(structurePlanResult);
-      } catch (err) {
-        console.error(`Failed to parse structure-plan.json: ${err.message}`);
+  // Get the last document structure
+  let originalDocumentStructure;
+  if (outputDir) {
+    const documentStructurePath = path.join(outputDir, "structure-plan.json");
+    try {
+      const documentExecutionStructure = await readFile(documentStructurePath, "utf8");
+      if (documentExecutionStructure?.trim()) {
+        try {
+          // Validate that the content looks like JSON before parsing
+          const trimmedContent = documentExecutionStructure.trim();
+          if (trimmedContent.startsWith("{") || trimmedContent.startsWith("[")) {
+            originalDocumentStructure = JSON.parse(documentExecutionStructure);
+          } else {
+            console.warn(`structure-plan.json contains non-JSON content, skipping parse`);
+          }
+        } catch (err) {
+          console.error(`Failed to parse structure-plan.json: ${err.message}`);
+        }
+      }
+    } catch (err) {
+      if (err.code !== "ENOENT") {
+        console.warn(`Error reading structure-plan.json: ${err.message}`);
       }
+      // The file does not exist or is not readable, originalDocumentStructure remains undefined
     }
-  } catch {
-    // The file does not exist, originalStructurePlan remains undefined
   }
 
   // Get the last output result of the specified path
   let content;
-  if (docPath && !reset) {
-    let fileFullName;
-
+  if (docPath && !reset && docsDir) {
     // First try direct path matching (original format)
     const flatName = docPath.replace(/^\//, "").replace(/\//g, "-");
-    fileFullName = `${flatName}.md`;
+    const fileFullName = `${flatName}.md`;
     let filePath = path.join(docsDir, fileFullName);
 
     try {
-      await access(filePath);
       content = await readFile(filePath, "utf8");
-    } catch {
+    } catch (err) {
+      if (err.code !== "ENOENT") {
+        console.warn(`Error reading document file ${filePath}: ${err.message}`);
+      }
+
       // If not found and boardId is provided, try boardId-flattenedPath format
       if (boardId && docPath.startsWith(`${boardId}-`)) {
         // Extract the flattened path part after boardId-
         const flattenedPath = docPath.substring(boardId.length + 1);
-        fileFullName = `${flattenedPath}.md`;
-        filePath = path.join(docsDir, fileFullName);
+        const boardIdFileFullName = `${flattenedPath}.md`;
+        filePath = path.join(docsDir, boardIdFileFullName);
 
         try {
-          await access(filePath);
           content = await readFile(filePath, "utf8");
-        } catch {
+        } catch (boardIdErr) {
+          if (boardIdErr.code !== "ENOENT") {
+            console.warn(`Error reading document file ${filePath}: ${boardIdErr.message}`);
+          }
           // The file does not exist, content remains undefined
         }
       }
@@ -286,7 +299,7 @@ export default async function loadSources({
     datasourcesList: sourceFiles,
     datasources: allSources,
     content,
-    originalStructurePlan,
+    originalDocumentStructure,
     files,
     modifiedFiles,
     totalWords,