@aigne/doc-smith 0.6.0 → 0.7.1

package/README.md

@@ -103,7 +103,7 @@ Optimize specific documents with targeted feedback:
 aigne doc update
 
 # Update a specific document
-aigne doc update --doc-path /faq --feedback "Add more comprehensive FAQ entries"
+aigne doc update --docs overview.md --feedback "Add more comprehensive FAQ entries"
 ```
 
 **Interactive Mode:** When run without parameters, `aigne doc update` will present an interactive menu for you to select which document to regenerate and provide feedback.
@@ -122,6 +122,29 @@ aigne doc generate --feedback "Add more detailed installation guide and troubles
 
 **Structure Optimization:** Use `aigne doc generate` with `--feedback` to refine the overall documentation structure, add new sections, or reorganize existing content.
 
+#### Document Translation
+
+Translate existing documentation to multiple languages:
+
+```bash
+# Translate specific documents to multiple languages
+aigne doc translate --langs zh --langs ja --docs examples.md --docs overview.md
+
+# Interactive translation with document and language selection
+aigne doc translate
+```
+
+**Command Parameters:**
+- `--langs`: Specify target languages (can be used multiple times)
+- `--docs`: Specify document paths to translate (can be used multiple times)
+- `--feedback`: Provide feedback for translation improvement
+- `--glossary`: Use a glossary file for consistent terminology (@path/to/glossary.md)
+
+**Interactive Mode:** When run without parameters, `aigne doc translate` will present interactive menus to:
+- Select documents to translate from your documentation
+- Choose target languages from 12 supported languages
+- Add new translation languages to your configuration
+
 #### Publishing to Discuss Kit
 
 Publish your documentation to Discuss Kit platforms:
@@ -185,6 +208,15 @@ aigne doc generate --feedback "Remove About section and add API Reference"
 
 # Update specific document
 aigne doc update --doc-path /faq --feedback "Add more comprehensive FAQ entries"
+
+# Translate documents to multiple languages
+aigne doc translate --langs zh --langs ja --docs examples.md --docs overview.md
+
+# Interactive translation (select documents and languages)
+aigne doc translate
+
+# Translate with custom glossary and feedback
+aigne doc translate --glossary @glossary.md --feedback "Use technical terminology consistently"
 ```
 
 ### Publishing and Integration
@@ -198,17 +230,3 @@ aigne doc publish --appUrl https://your-discuss-kit-instance.com
 
 
 ```
-
-### Development Commands
-
-```shell
-# Development and debugging commands using npx to run local code
-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 translate 
-npx --no doc-smith run --entry-agent publish
-```
-
-**Development Mode:** These commands use `npx` to run the local code version for development and debugging purposes, bypassing the globally installed CLI.
-

package/agents/chat.yaml

@@ -0,0 +1,30 @@
+type: ai
+name: chat
+description: Start interactive document generation assistant
+instructions: |
+  You are a professional document generation assistant that helps users create, modify, and manage documentation through interactive chat. Your primary role is to understand user requirements and intelligently call upon various specialized skills to complete documentation tasks efficiently.
+
+  Core Capabilities:
+  - Generate comprehensive documentation from user inputs and specifications
+  - Regenerate and refine document details based on feedback
+  - Translate and localize documentation content
+  - Publish and manage team documentation workflows
+  - Provide interactive guidance throughout the document creation process
+
+  Interaction Guidelines:
+  - Engage users in a professional yet friendly manner
+  - Ask clarifying questions to understand specific documentation needs
+  - Suggest appropriate skills and workflows based on user requests
+  - Provide clear explanations of available capabilities and processes
+  - Maintain context throughout multi-step documentation tasks
+  - Offer proactive suggestions for improving document quality and structure
+input_key: message
+memory: true
+skills:
+  - ./input-generator.mjs
+  - ./docs-generator.yaml
+  - ./detail-regenerator.yaml
+  - ./team-publish-docs.yaml
+  - ./retranslate.yaml
+  - ./docs-fs.yaml
+  - ./exit.mjs

package/agents/check-structure-plan.mjs

@@ -63,7 +63,7 @@ export default async function checkStructurePlan(
         1. 对于新增的内容，可以根据需要新增节点，或补充到原有节点展示
         2. 谨慎删除节点，除非节点关联 sourceIds 都被删除了
         3. 不能修改原有节点的 path
-        4. 根据最新的 Data Sources 按需要更新节点的 sourceIds，如没有大的变化，可以不更新。
+        4. 根据最新的 Data Sources 可以按需要更新节点的 sourceIds。
       `;
     }
   }

package/agents/docs-fs.yaml

@@ -0,0 +1,25 @@
+type: team
+name: docs_fs_actor
+description: File system operations for documentation management
+skills:
+  - ./load-config.mjs
+  - url: ./fs.mjs
+    default_input:
+      rootDir:
+        $get: docsDir
+input_schema:
+  type: object
+  properties:
+    action:
+      type: "string"
+      enum: ["read_file", "write_file", "delete_file", "list_directory"]
+      description:
+        "The file system action to perform, available actions are: read_file, write_file, delete_file, list_directory"
+    path:
+      type: "string"
+      description: "The path to the file or directory to operate on"
+    content:
+      type: "string"
+      description: "The content to write to the file, required for write_file action"
+  required: ["action", "path"]
+task_render_mode: hide

package/agents/exit.mjs

@@ -0,0 +1,6 @@
+export default async function exit() {
+  process.exit(0);
+}
+
+exit.description =
+  "Exit the chat session. Equivalent to saying goodbye, quit, exit, close, or see you. Must print a bye message before calling this tool, as it will exit the process immediately.";

package/agents/feedback-refiner.yaml

@@ -41,8 +41,12 @@ output_schema:
     limitToInputPaths:
       type: boolean
       description: Whether to limit to the "paths specified in current input" when used subsequently
+    reason:
+      type: string
+      description: Explanation of why the save decision was made and how the rule and scope were derived
   required:
     - rule
     - scope
     - save
-    - limitToInputPaths
+    - limitToInputPaths
+    - reason

package/agents/find-items-by-paths.mjs

@@ -26,10 +26,16 @@ export default async function selectedDocs(
       // Let user select multiple files
       selectedFiles = await options.prompts.checkbox({
         message: getActionText(isTranslate, "Select documents to {action}:"),
-        choices: mainLanguageFiles.map((file) => ({
-          name: file,
-          value: file,
-        })),
+        source: (term) => {
+          const choices = mainLanguageFiles.map((file) => ({
+            name: file,
+            value: file,
+          }));
+
+          if (!term) return choices;
+
+          return choices.filter((choice) => choice.name.toLowerCase().includes(term.toLowerCase()));
+        },
         validate: (answer) => {
           if (answer.length === 0) {
             return "Please select at least one document";

package/agents/fs.mjs

@@ -0,0 +1,60 @@
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export default async function fs({ rootDir, action, path, content }) {
+  if (!rootDir) throw new Error("Root directory is not specified");
+
+  path = join(rootDir, path);
+
+  switch (action) {
+    case "read_file":
+      return {
+        status: "ok",
+        path,
+        content: await readFile(path, "utf-8"),
+      };
+    case "write_file": {
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, content || "");
+      return {
+        status: "ok",
+        path,
+        content,
+      };
+    }
+    case "delete_file":
+      await rm(path, { recursive: true, force: true });
+      return {
+        status: "ok",
+        path,
+      };
+    case "list_directory":
+      return {
+        status: "ok",
+        entries: await readdir(path, { withFileTypes: true }).then((list) =>
+          list.map((entry) => ({
+            path: join(entry.parentPath, entry.name),
+            isDirectory: entry.isDirectory(),
+          })),
+        ),
+      };
+  }
+}
+
+fs.input_schema = {
+  type: "object",
+  properties: {
+    action: {
+      type: "string",
+      enum: ["read_file", "write_file", "delete_file", "list_directory"],
+      description:
+        "The file system action to perform, available actions are: read_file, write_file, delete_file, list_directory",
+    },
+    path: { type: "string", description: "The path to the file or directory to operate on" },
+    content: {
+      type: "string",
+      description: "The content to write to the file, required for write_file action",
+    },
+  },
+  required: ["action", "path"],
+};

package/agents/input-generator.mjs

@@ -1,6 +1,7 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import chalk from "chalk";
+import { stringify as yamlStringify } from "yaml";
 import { getFilteredOptions, validateSelection } from "../utils/conflict-detector.mjs";
 import {
   DEPTH_RECOMMENDATION_LOGIC,
@@ -15,6 +16,7 @@ import {
   detectSystemLanguage,
   getAvailablePaths,
   getProjectInfo,
+  isGlobPattern,
   validatePath,
 } from "../utils/utils.mjs";
 
@@ -34,7 +36,9 @@ export default async function init(
 ) {
   if (skipIfExists) {
     const filePath = join(outputPath, fileName);
-    if (await readFile(filePath, "utf8").catch(() => null)) {
+    const configContent = await readFile(filePath, "utf8").catch(() => null);
+    // Only skip if file exists AND has non-empty content
+    if (configContent && configContent.trim() !== "") {
       return {};
     }
   }
@@ -228,19 +232,20 @@ export default async function init(
   // 8. Source code paths
   console.log("\n🔍 [8/8]: Source Code Paths");
   console.log("Enter paths to analyze for documentation (e.g., ./src, ./lib)");
+  console.log("💡 You can also enter glob patterns (e.g., src/**/*.js, **/*.md)");
   console.log("💡 If no paths are configured, './' will be used as default");
 
   const sourcePaths = [];
   while (true) {
     const selectedPath = await options.prompts.search({
-      message: "Path:",
+      message: "Path or glob pattern:",
       source: async (input) => {
         if (!input || input.trim() === "") {
           return [
             {
-              name: "Press Enter to finish",
+              name: "",
               value: "",
-              description: "",
+              description: _PRESS_ENTER_TO_FINISH,
             },
           ];
         }
@@ -250,32 +255,58 @@ export default async function init(
         // Search for matching files and folders in current directory
         const availablePaths = getAvailablePaths(searchTerm);
 
-        return [...availablePaths];
+        // Also add option to use as glob pattern
+        const options = [...availablePaths];
+
+        // Check if input looks like a glob pattern
+        const isGlobPatternResult = isGlobPattern(searchTerm);
+        if (isGlobPatternResult) {
+          // If it looks like a glob pattern, allow direct input
+          options.push({
+            name: searchTerm,
+            value: searchTerm,
+            description: "This input will be used as a glob pattern for file matching",
+          });
+        }
+
+        return options;
       },
     });
 
     // Check if user chose to exit
-    if (!selectedPath || selectedPath.trim() === "" || selectedPath === "Press Enter to finish") {
+    if (!selectedPath || selectedPath.trim() === "" || selectedPath === _PRESS_ENTER_TO_FINISH) {
       break;
     }
 
     const trimmedPath = selectedPath.trim();
 
-    // Use validatePath to check if path is valid
-    const validation = validatePath(trimmedPath);
+    // Check if it's a glob pattern
+    const isGlobPatternResult = isGlobPattern(trimmedPath);
 
-    if (!validation.isValid) {
-      console.log(`⚠️ ${validation.error}`);
-      continue;
-    }
+    if (isGlobPatternResult) {
+      // For glob patterns, just add them without validation
+      if (sourcePaths.includes(trimmedPath)) {
+        console.log(`⚠️ Pattern already exists: ${trimmedPath}`);
+        continue;
+      }
+      sourcePaths.push(trimmedPath);
+    } else {
+      // Use validatePath to check if path is valid for regular paths
+      const validation = validatePath(trimmedPath);
+
+      if (!validation.isValid) {
+        console.log(`⚠️ ${validation.error}`);
+        continue;
+      }
 
-    // Avoid duplicate paths
-    if (sourcePaths.includes(trimmedPath)) {
-      console.log(`⚠️ Path already exists: ${trimmedPath}`);
-      continue;
-    }
+      // Avoid duplicate paths
+      if (sourcePaths.includes(trimmedPath)) {
+        console.log(`⚠️ Path already exists: ${trimmedPath}`);
+        continue;
+      }
 
-    sourcePaths.push(trimmedPath);
+      sourcePaths.push(trimmedPath);
+    }
   }
 
   // If no paths entered, use default
@@ -324,114 +355,142 @@ export default async function init(
  * @param {Object} input - Input object
  * @returns {string} YAML string
  */
-function generateYAML(input) {
-  let yaml = "";
+export function generateYAML(input) {
+  // Create the main configuration object that will be safely serialized
+  const config = {
+    // Project information (safely handled by yaml library)
+    projectName: input.projectName || "",
+    projectDesc: input.projectDesc || "",
+    projectLogo: input.projectLogo || "",
+
+    // Documentation configuration
+    documentPurpose: input.documentPurpose || [],
+    targetAudienceTypes: input.targetAudienceTypes || [],
+    readerKnowledgeLevel: input.readerKnowledgeLevel || "",
+    documentationDepth: input.documentationDepth || "",
+
+    // Custom rules and target audience (empty for user to fill)
+    rules: "",
+    targetAudience: "",
+
+    // Language settings
+    locale: input.locale || "en",
+    translateLanguages: input.translateLanguages?.filter((lang) => lang.trim()) || [],
+
+    // Paths
+    docsDir: input.docsDir || "./aigne/doc-smith/docs",
+    sourcesPath: input.sourcesPath || [],
+  };
 
-  // Add project information at the beginning
-  yaml += `# Project information for documentation publishing\n`;
-  yaml += `projectName: ${input.projectName || ""}\n`;
-  yaml += `projectDesc: ${input.projectDesc || ""}\n`;
-  yaml += `projectLogo: ${input.projectLogo || ""}\n`;
-  yaml += `\n`;
+  // Generate comments and structure
+  let yaml = "# Project information for documentation publishing\n";
 
-  // Add documentation configuration choices with all available options
-  yaml += `# =============================================================================\n`;
-  yaml += `# Documentation Configuration\n`;
-  yaml += `# =============================================================================\n\n`;
+  // Serialize the project info section safely
+  const projectSection = yamlStringify({
+    projectName: config.projectName,
+    projectDesc: config.projectDesc,
+    projectLogo: config.projectLogo,
+  }).trim();
+
+  yaml += `${projectSection}\n\n`;
+
+  // Add documentation configuration with comments
+  yaml += "# =============================================================================\n";
+  yaml += "# Documentation Configuration\n";
+  yaml += "# =============================================================================\n\n";
 
   // Document Purpose with all available options
-  yaml += `# Purpose: What's the main outcome you want readers to achieve?\n`;
-  yaml += `# Available options (uncomment and modify as needed):\n`;
+  yaml += "# Purpose: What's the main outcome you want readers to achieve?\n";
+  yaml += "# Available options (uncomment and modify as needed):\n";
   Object.entries(DOCUMENT_STYLES).forEach(([key, style]) => {
     if (key !== "custom") {
       yaml += `#   ${key.padEnd(16)} - ${style.name}: ${style.description}\n`;
     }
   });
-  yaml += `documentPurpose:\n`;
-  if (input.documentPurpose && input.documentPurpose.length > 0) {
-    input.documentPurpose.forEach((purpose) => {
-      yaml += `  - ${purpose}\n`;
-    });
-  }
-  yaml += `\n`;
+
+  // Safely serialize documentPurpose
+  const documentPurposeSection = yamlStringify({ documentPurpose: config.documentPurpose }).trim();
+  yaml += `${documentPurposeSection.replace(/^documentPurpose:/, "documentPurpose:")}\n\n`;
 
   // Target Audience Types with all available options
-  yaml += `# Target Audience: Who will be reading this most often?\n`;
-  yaml += `# Available options (uncomment and modify as needed):\n`;
+  yaml += "# Target Audience: Who will be reading this most often?\n";
+  yaml += "# Available options (uncomment and modify as needed):\n";
   Object.entries(TARGET_AUDIENCES).forEach(([key, audience]) => {
     if (key !== "custom") {
       yaml += `#   ${key.padEnd(16)} - ${audience.name}: ${audience.description}\n`;
     }
   });
-  yaml += `targetAudienceTypes:\n`;
-  if (input.targetAudienceTypes && input.targetAudienceTypes.length > 0) {
-    input.targetAudienceTypes.forEach((audience) => {
-      yaml += `  - ${audience}\n`;
-    });
-  }
-  yaml += `\n`;
+
+  // Safely serialize targetAudienceTypes
+  const targetAudienceTypesSection = yamlStringify({
+    targetAudienceTypes: config.targetAudienceTypes,
+  }).trim();
+  yaml += `${targetAudienceTypesSection.replace(/^targetAudienceTypes:/, "targetAudienceTypes:")}\n\n`;
 
   // Reader Knowledge Level with all available options
-  yaml += `# Reader Knowledge Level: What do readers typically know when they arrive?\n`;
-  yaml += `# Available options (uncomment and modify as needed):\n`;
+  yaml += "# Reader Knowledge Level: What do readers typically know when they arrive?\n";
+  yaml += "# Available options (uncomment and modify as needed):\n";
   Object.entries(READER_KNOWLEDGE_LEVELS).forEach(([key, level]) => {
     yaml += `#   ${key.padEnd(20)} - ${level.name}: ${level.description}\n`;
   });
-  yaml += `readerKnowledgeLevel: ${input.readerKnowledgeLevel || ""}\n`;
-  yaml += `\n`;
+
+  // Safely serialize readerKnowledgeLevel
+  const readerKnowledgeLevelSection = yamlStringify({
+    readerKnowledgeLevel: config.readerKnowledgeLevel,
+  }).trim();
+  yaml += `${readerKnowledgeLevelSection.replace(/^readerKnowledgeLevel:/, "readerKnowledgeLevel:")}\n\n`;
 
   // Documentation Depth with all available options
-  yaml += `# Documentation Depth: How comprehensive should the documentation be?\n`;
-  yaml += `# Available options (uncomment and modify as needed):\n`;
+  yaml += "# Documentation Depth: How comprehensive should the documentation be?\n";
+  yaml += "# Available options (uncomment and modify as needed):\n";
   Object.entries(DOCUMENTATION_DEPTH).forEach(([key, depth]) => {
     yaml += `#   ${key.padEnd(18)} - ${depth.name}: ${depth.description}\n`;
   });
-  yaml += `documentationDepth: ${input.documentationDepth || ""}\n`;
-  yaml += `\n`;
+
+  // Safely serialize documentationDepth
+  const documentationDepthSection = yamlStringify({
+    documentationDepth: config.documentationDepth,
+  }).trim();
+  yaml += `${documentationDepthSection.replace(/^documentationDepth:/, "documentationDepth:")}\n\n`;
 
   // Custom Documentation Rules and Requirements
-  yaml += `# Custom Rules: Define specific documentation generation rules and requirements\n`;
-  yaml += `rules: |\n`;
-  yaml += `  \n\n`;
+  yaml += "# Custom Rules: Define specific documentation generation rules and requirements\n";
+  const rulesSection = yamlStringify({ rules: config.rules }).trim();
+  // Use literal style for multiline strings
+  yaml += `${rulesSection.replace(/rules: ''/, "rules: |\n  ")}\n\n`;
 
   // Target Audience Description
-  yaml += `# Target Audience: Describe your specific target audience and their characteristics\n`;
-  yaml += `targetAudience: |\n`;
-  yaml += `  \n\n`;
+  yaml += "# Target Audience: Describe your specific target audience and their characteristics\n";
+  const targetAudienceSection = yamlStringify({ targetAudience: config.targetAudience }).trim();
+  // Use literal style for multiline strings
+  yaml += `${targetAudienceSection.replace(/targetAudience: ''/, "targetAudience: |\n  ")}\n\n`;
 
   // Glossary Configuration
-  yaml += `# Glossary: Define project-specific terms and definitions\n`;
-  yaml += `# glossary: "@glossary.md"  # Path to markdown file containing glossary definitions\n`;
-  yaml += `\n`;
-
-  // Add language settings
-  yaml += `locale: ${input.locale}\n`;
-
-  // Add translation languages
-  if (
-    input.translateLanguages &&
-    input.translateLanguages.length > 0 &&
-    input.translateLanguages.some((lang) => lang.trim())
-  ) {
-    yaml += `translateLanguages:\n`;
-    input.translateLanguages.forEach((lang) => {
-      if (lang.trim()) {
-        yaml += `  - ${lang}\n`;
-      }
-    });
+  yaml += "# Glossary: Define project-specific terms and definitions\n";
+  yaml += '# glossary: "@glossary.md"  # Path to markdown file containing glossary definitions\n\n';
+
+  // Language settings - safely serialize
+  const localeSection = yamlStringify({ locale: config.locale }).trim();
+  yaml += `${localeSection.replace(/^locale:/, "locale:")}\n`;
+
+  // Translation languages
+  if (config.translateLanguages.length > 0) {
+    const translateLanguagesSection = yamlStringify({
+      translateLanguages: config.translateLanguages,
+    }).trim();
+    yaml += `${translateLanguagesSection.replace(/^translateLanguages:/, "translateLanguages:")}\n`;
   } else {
-    yaml += `# translateLanguages:  # List of languages to translate the documentation to\n`;
-    yaml += `#   - zh  # Example: Chinese translation\n`;
-    yaml += `#   - en  # Example: English translation\n`;
+    yaml += "# translateLanguages:  # List of languages to translate the documentation to\n";
+    yaml += "#   - zh  # Example: Chinese translation\n";
+    yaml += "#   - en  # Example: English translation\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`;
-  input.sourcesPath.forEach((path) => {
-    yaml += `  - ${path}\n`;
-  });
+  // Directory and source path configurations - safely serialize
+  const docsDirSection = yamlStringify({ docsDir: config.docsDir }).trim();
+  yaml += `${docsDirSection.replace(/^docsDir:/, "docsDir:")}  # Directory to save generated documentation\n`;
+
+  const sourcesPathSection = yamlStringify({ sourcesPath: config.sourcesPath }).trim();
+  yaml += `${sourcesPathSection.replace(/^sourcesPath:/, "sourcesPath:  # Source code paths to analyze")}\n`;
 
   return yaml;
 }

package/agents/load-config.mjs

@@ -31,11 +31,6 @@ export default async function loadConfig({ config, appUrl }) {
     const processedConfig = processConfigFields(parsedConfig);
 
     return {
-      nodeName: "Section",
-      locale: "en",
-      sourcesPath: ["./"],
-      docsDir: "./.aigne/doc-smith/docs",
-      outputDir: "./.aigne/doc-smith/output",
       lastGitHead: parsedConfig.lastGitHead || "",
       ...parsedConfig,
       ...processedConfig,