@aigne/doc-smith 0.0.1

package/agents/detail-regenerator.yaml

@@ -0,0 +1,107 @@
+type: team
+name: regenerator
+description: 生成文档详情并翻译
+skills:
+  - ./load-sources.mjs
+  - type: transform
+    jsonata: |
+      $merge([
+        $,
+        {
+          'structurePlan': originalStructurePlan,
+          'structurePlanResult': $map(originalStructurePlan, function($item) {
+            $merge([
+              $item,
+              {
+                'translates': [$map(translateLanguages, function($lang) { {"language": $lang} })]
+              }
+            ])
+          })
+        }
+      ])
+  - type: transform
+    jsonata: |
+      (
+        $array := structurePlanResult;
+        $path := currentPath;
+        $foundItem := $array[path=$path][0];
+        $merge([
+            $foundItem,
+            { "originalStructurePlan": originalStructurePlan }
+            
+        ])
+      )
+  - ./format-structure-plan.mjs
+  - ./detail-generator-and-translate.yaml
+input_schema:
+  type: object
+  properties:
+    nodeName:
+      type: string
+      description: 节点名称
+      default: 部分
+    locale:
+      type: string
+      description: 语言
+    targetAudience:
+      type: string
+      description: 目标受众
+    glossary:
+      type: string
+      description: 术语表
+    currentPath:
+      type: string
+      description: 当前路径
+    feedback:
+      type: string
+      description: 反馈
+    sources:
+      type: array
+      items:
+        type: string
+        description: 源码路径
+    sourcesPath:
+      type: array
+      items:
+        type: string
+        description: 源码路径
+      default:
+        - ./
+    includePatterns:
+      type: array
+      items:
+        type: string
+        description: 包含的文件名
+    excludePatterns:
+      type: array
+      items:
+        type: string
+        description: 排除的文件名
+    outputDir:
+      type: string
+      description: 输出目录
+      default: ./aigne-docs/output
+    docsDir:
+      type: string
+      description: 文档目录
+      default: ./aigne-docs/docs
+    additionalInformation:
+      type: string
+      description: 额外补充信息
+    labels:
+      type: array
+      items:
+        type: string
+        description: 标签
+output_schema:
+  type: object
+  properties:
+    title:
+      type: string
+    description:
+      type: string
+    path:
+      type: string
+    content:
+      type: string
+mode: sequential

package/agents/docs-generator.yaml

@@ -0,0 +1,93 @@
+type: team
+name: generator
+description: 文档生成
+skills:
+  - ./load-sources.mjs
+  - ./check-structure-planning.mjs
+  - type: transform
+    jsonata: |
+      $merge([$, {
+      "saveKey": "structurePlan",
+      "savePath": outputDir,
+      "fileName": "structure-plan.json"
+      }])
+  - ./save-output.mjs
+  - type: transform
+    jsonata: |
+      $merge([
+        $,
+        {
+          'structurePlanResult': $map(structurePlan, function($item) {
+            $merge([
+              $item,
+              {
+                'translates': [$map(translateLanguages, function($lang) { {"language": $lang} })]
+              }
+            ])
+          })
+        }
+      ])
+  - ./format-structure-plan.mjs
+  - ./batch-docs-detail-generator.yaml
+  - ./save-docs.mjs
+
+input_schema:
+  type: object
+  properties:
+    nodeName:
+      type: string
+      description: 节点名称
+      default: Section
+    rules:
+      type: string
+      description: 用户的结构规划的要求和规则
+    locale:
+      type: string
+      description: 用户语言，如 zh、en
+    sources:
+      type: array
+      items:
+        type: string
+      description: 用户生成文档的源码文件
+    sourcesPath:
+      type: array
+      items:
+        type: string
+        description: 源码路径
+      default:
+        - ./
+    docsDir:
+      type: string
+      description: 文档保存目录
+      default: ./aigne-docs/docs
+    outputDir:
+      type: string
+      description: 输出目录
+      default: ./aigne-docs/output
+    translateLanguages:
+      type: array
+      items:
+        type: string
+        description: 翻译语言，如 zh、en
+    glossary:
+      type: string
+      description: 术语表
+    additionalInformation:
+      type: string
+      description: 额外补充信息
+    docsType:
+      type: string
+      description: 文档类型，支持：general、getting-started、reference、faq
+      default: general
+    structurePlanFeedback:
+      type: string
+      description: 结构规划反馈
+    labels:
+      type: array
+      items:
+        type: string
+        description: 标签
+  required:
+    - rules
+    - docsDir
+mode: sequential

package/agents/format-structure-plan.mjs

@@ -0,0 +1,23 @@
+import { stringify } from "yaml";
+
+export default async function formatStructurePlan({ structurePlan }) {
+  // Extract required fields from each item in structurePlan
+  const formattedData = structurePlan.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 {
+    structurePlanYaml: yamlString,
+    structurePlan,
+  };
+}

package/agents/input-generator.mjs

@@ -0,0 +1,142 @@
+import { writeFile, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+
+/**
+ * Guide users through multi-turn dialogue to collect information and generate YAML configuration
+ * @param {Object} params
+ * @param {string} params.outputPath - Output file path
+ * @param {string} params.fileName - File name
+ * @returns {Promise<Object>}
+ */
+export default async function init(
+  { outputPath = "./doc-smith", fileName = "input.yaml" },
+  options
+) {
+  console.log("Welcome to AIGNE Doc Smith!");
+  console.log(
+    "I will help you generate a configuration file through several questions.\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:",
+  });
+  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 to skip):",
+  });
+  input.targetAudience = targetAudienceInput.trim() || "";
+
+  // 3. Language settings
+  console.log("\n=== Language Settings ===");
+  const localeInput = await options.prompts.input({
+    message: "Primary language (e.g., en, zh, press Enter to skip):",
+  });
+  input.locale = localeInput.trim() || "";
+
+  // 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):",
+  });
+  input.translateLanguages = translateInput.trim()
+    ? translateInput.split(",").map((lang) => lang.trim())
+    : [];
+
+  // Generate YAML content
+  const yamlContent = generateYAML(input, outputPath);
+
+  // Save file
+  try {
+    const filePath = join(outputPath, fileName);
+    const dirPath = dirname(filePath);
+
+    // Create directory if it doesn't exist
+    await mkdir(dirPath, { recursive: true });
+
+    await writeFile(filePath, yamlContent, "utf8");
+    console.log(`\n✅ Configuration file saved to: ${filePath}`);
+
+    return {
+      inputGeneratorStatus: true,
+      inputGeneratorPath: filePath,
+      inputGeneratorContent: yamlContent,
+    };
+  } catch (error) {
+    console.error(`❌ Failed to save configuration file: ${error.message}`);
+    return {
+      inputGeneratorStatus: false,
+      inputGeneratorError: error.message,
+    };
+  }
+}
+
+/**
+ * Generate YAML configuration content
+ * @param {Object} input - Input object
+ * @param {string} outputPath - Output path for directory configuration
+ * @returns {string} YAML string
+ */
+function generateYAML(input, outputPath) {
+  let yaml = "";
+
+  // Add rules
+  if (input.rules) {
+    yaml += `rules: |\n`;
+    yaml += `  ${input.rules.split("\n").join("\n  ")}\n\n`;
+  }
+
+  // Add target audience
+  if (input.targetAudience && input.targetAudience.trim()) {
+    yaml += `targetAudience: ${input.targetAudience}\n`;
+  } else {
+    yaml += `# targetAudience: developers  # Target audience for the documentation (e.g., developers, users)\n`;
+  }
+
+  // Add language settings
+  if (input.locale && input.locale.trim()) {
+    yaml += `locale: ${input.locale}\n`;
+  } else {
+    yaml += `# locale: en  # Primary language for the documentation (e.g., en, zh)\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`;
+      }
+    });
+  } else {
+    yaml += `# translateLanguages:  # List of languages to translate the documentation to\n`;
+    yaml += `#   - zh  # Example: Chinese translation\n`;
+    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`;
+  yaml += `sourcesPath:  # Source code paths to analyze\n`;
+  yaml += `  - ./  # Current directory\n`;
+
+  return yaml;
+}
+
+// Execute the function if this file is run directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  inputGenerator({}).catch(console.error);
+}

package/agents/load-sources.mjs

@@ -0,0 +1,329 @@
+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/**",
+  "v1/**",
+  "**/*dist/**",
+  "**/*build/**",
+  "**/*experimental/**",
+  "**/*deprecated/**",
+  "**/*misc/**",
+  "**/*legacy/**",
+  ".git/**",
+  ".github/**",
+  ".next/**",
+  ".vscode/**",
+  "**/*obj/**",
+  "**/*bin/**",
+  "**/*node_modules/**",
+  "*.log",
+];
+
+/**
+ * Load .gitignore patterns from a directory
+ * @param {string} dir - Directory path
+ * @returns {object|null} Ignore instance or null if no .gitignore found
+ */
+async function loadGitignore(dir) {
+  const gitignorePath = path.join(dir, ".gitignore");
+  try {
+    await access(gitignorePath);
+    const gitignoreContent = await readFile(gitignorePath, "utf8");
+    // Create ignore patterns from .gitignore content
+    const ignorePatterns = gitignoreContent
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith("#"))
+      .map((line) => line.replace(/^\//, "")); // Remove leading slash
+
+    return ignorePatterns.length > 0 ? ignorePatterns : null;
+  } catch {
+    // .gitignore file doesn't exist
+    return null;
+  }
+}
+
+/**
+ * Get files using glob patterns
+ * @param {string} dir - Directory to search
+ * @param {string[]} includePatterns - Include patterns
+ * @param {string[]} excludePatterns - Exclude patterns
+ * @param {string[]} gitignorePatterns - .gitignore patterns
+ * @returns {Promise<string[]>} Array of file paths
+ */
+async function getFilesWithGlob(
+  dir,
+  includePatterns,
+  excludePatterns,
+  gitignorePatterns
+) {
+  // Prepare all ignore patterns
+  const allIgnorePatterns = [];
+
+  if (excludePatterns) {
+    allIgnorePatterns.push(...excludePatterns);
+  }
+
+  if (gitignorePatterns) {
+    allIgnorePatterns.push(...gitignorePatterns);
+  }
+
+  // Add default exclusions if not already present
+  const defaultExclusions = ["node_modules/**", "test/**", "temp/**"];
+  for (const exclusion of defaultExclusions) {
+    if (!allIgnorePatterns.includes(exclusion)) {
+      allIgnorePatterns.push(exclusion);
+    }
+  }
+
+  // Convert patterns to be relative to the directory
+  const patterns = includePatterns.map((pattern) => {
+    // If pattern doesn't start with / or **, make it relative to dir
+    if (!pattern.startsWith("/") && !pattern.startsWith("**")) {
+      return `**/${pattern}`; // Use ** to search recursively
+    }
+    return pattern;
+  });
+
+  try {
+    const files = await glob(patterns, {
+      cwd: dir,
+      ignore: allIgnorePatterns.length > 0 ? allIgnorePatterns : undefined,
+      absolute: true,
+      nodir: true, // Only return files, not directories
+      dot: false, // Don't include dot files by default
+      gitignore: true, // Enable .gitignore support
+    });
+
+    return files;
+  } catch (error) {
+    console.warn(
+      `Warning: Error during glob search in ${dir}: ${error.message}`
+    );
+    return [];
+  }
+}
+
+export default async function loadSources({
+  sources = [],
+  sourcesPath = [],
+  includePatterns,
+  excludePatterns,
+  outputDir,
+  docsDir,
+  currentPath,
+  useDefaultPatterns = true,
+} = {}) {
+  let files = Array.isArray(sources) ? [...sources] : [];
+
+  if (sourcesPath) {
+    const paths = Array.isArray(sourcesPath) ? sourcesPath : [sourcesPath];
+    let allFiles = [];
+
+    for (const dir of paths) {
+      try {
+        // Load .gitignore for this directory
+        const gitignorePatterns = await loadGitignore(dir);
+
+        // Prepare patterns
+        let finalIncludePatterns = null;
+        let finalExcludePatterns = null;
+
+        if (useDefaultPatterns) {
+          // Merge with default patterns
+          const userInclude = includePatterns
+            ? Array.isArray(includePatterns)
+              ? includePatterns
+              : [includePatterns]
+            : [];
+          const userExclude = excludePatterns
+            ? Array.isArray(excludePatterns)
+              ? excludePatterns
+              : [excludePatterns]
+            : [];
+
+          finalIncludePatterns = [...DEFAULT_INCLUDE_PATTERNS, ...userInclude];
+          finalExcludePatterns = [...DEFAULT_EXCLUDE_PATTERNS, ...userExclude];
+        } else {
+          // Use only user patterns
+          if (includePatterns) {
+            finalIncludePatterns = Array.isArray(includePatterns)
+              ? includePatterns
+              : [includePatterns];
+          }
+          if (excludePatterns) {
+            finalExcludePatterns = Array.isArray(excludePatterns)
+              ? excludePatterns
+              : [excludePatterns];
+          }
+        }
+
+        // Get files using glob
+        const filesInDir = await getFilesWithGlob(
+          dir,
+          finalIncludePatterns,
+          finalExcludePatterns,
+          gitignorePatterns
+        );
+        allFiles = allFiles.concat(filesInDir);
+      } catch (err) {
+        if (err.code !== "ENOENT") throw err;
+      }
+    }
+
+    files = files.concat(allFiles);
+  }
+
+  files = [...new Set(files)];
+  let allSources = "";
+  const sourceFiles = await Promise.all(
+    files.map(async (file) => {
+      const content = await readFile(file, "utf8");
+      allSources += `// sourceId: ${file}\n${content}\n`;
+      return {
+        sourceId: file,
+        content,
+      };
+    })
+  );
+
+  // 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}`);
+      }
+    }
+  } catch {
+    // The file does not exist, originalStructurePlan remains undefined
+  }
+
+  // Get the last output result of the specified path
+  let content;
+  if (currentPath) {
+    const flatName = currentPath.replace(/^\//, "").replace(/\//g, "-");
+    const fileFullName = `${flatName}.md`;
+    const filePath = path.join(docsDir, fileFullName);
+    try {
+      await access(filePath);
+      content = await readFile(filePath, "utf8");
+    } catch {
+      // The file does not exist, content remains undefined
+    }
+  }
+
+  return {
+    datasourcesList: sourceFiles,
+    datasources: allSources,
+    content,
+    originalStructurePlan,
+    files,
+  };
+}
+
+loadSources.input_schema = {
+  type: "object",
+  properties: {
+    sources: {
+      type: "array",
+      items: { type: "string" },
+      description: "Array of paths to the sources files",
+    },
+    sourcesPath: {
+      anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+      description: "Directory or directories to recursively read files from",
+    },
+    includePatterns: {
+      anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+      description:
+        "Glob patterns to filter files by path or filename. If not set, include all.",
+    },
+    excludePatterns: {
+      anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+      description:
+        "Glob patterns to exclude files by path or filename. If not set, exclude none.",
+    },
+    useDefaultPatterns: {
+      type: "boolean",
+      description:
+        "Whether to use default include/exclude patterns. Defaults to true.",
+    },
+    currentPath: {
+      type: "string",
+      description: "The current path of the document",
+    },
+  },
+  required: [],
+};
+
+loadSources.output_schema = {
+  type: "object",
+  properties: {
+    datasources: {
+      type: "string",
+    },
+    datasourcesList: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          sourceId: { type: "string" },
+          content: { type: "string" },
+        },
+      },
+    },
+    files: {
+      type: "array",
+      items: { type: "string" },
+      description: "Array of file paths that were loaded",
+    },
+  },
+};