@aigne/doc-smith 0.9.7-beta.3 → 0.9.8-alpha.0

package/agents/evaluate/document.yaml

@@ -10,6 +10,9 @@ task_title: Evaluate document for '{{ title }}'
 input_schema:
   type: object
   properties:
+    path:
+      type: string
+      description: Document path to be evaluated
     content:
       type: string
       description: Document content to be evaluated
@@ -28,6 +31,9 @@ input_schema:
     readerKnowledgeLevel:
       type: string
       description: User-selected reader knowledge level
+    allDocumentContentList:
+      type: array
+      description: All document content list for better evaluate
   required:
     - content
     - description

package/agents/evaluate/index.yaml

@@ -20,6 +20,7 @@ skills:
         }
       ])
   - ./document-structure.yaml
+  - ../utils/load-all-document-content.mjs
   - type: team
     name: batchEvaluateDocument
     skills:

package/agents/init/index.mjs

@@ -2,32 +2,16 @@ 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 } from "../../utils/conflict-detector.mjs";
 import {
   DEFAULT_REASONING_EFFORT_LEVEL,
   DEFAULT_THINKING_EFFORT_LEVEL,
-  DEPTH_RECOMMENDATION_LOGIC,
-  DOCUMENT_STYLES,
-  DOCUMENTATION_DEPTH,
-  PURPOSE_TO_KNOWLEDGE_MAPPING,
-  READER_KNOWLEDGE_LEVELS,
-  SUPPORTED_LANGUAGES,
-  TARGET_AUDIENCES,
+  DIAGRAM_STYLES,
 } from "../../utils/constants/index.mjs";
-import { isRemoteFile } from "../../utils/file-utils.mjs";
 import loadConfig from "../../utils/load-config.mjs";
-import {
-  detectSystemLanguage,
-  getAvailablePaths,
-  getProjectInfo,
-  isGlobPattern,
-  validatePath,
-} from "../../utils/utils.mjs";
+import { detectSystemLanguage, getProjectInfo } from "../../utils/utils.mjs";
 import mapReasoningEffortLevel from "../utils/map-reasoning-effort-level.mjs";
 import { validateDocDir } from "./validate.mjs";
 
-const _PRESS_ENTER_TO_FINISH = "Press Enter to finish";
-
 /**
  * Guides the user through a multi-turn dialog to generate a YAML configuration file.
  * @param {Object} params
@@ -58,16 +42,13 @@ export default async function init(input, options) {
   };
 }
 
-async function _init(
-  {
-    outputPath = ".aigne/doc-smith",
-    fileName = "config.yaml",
-    skipIfExists = false,
-    appUrl,
-    checkOnly = false,
-  },
-  options,
-) {
+async function _init({
+  outputPath = ".aigne/doc-smith",
+  fileName = "config.yaml",
+  skipIfExists = false,
+  appUrl,
+  checkOnly = false,
+}) {
   // Check if we're in checkOnly mode
   if (checkOnly) {
     const filePath = join(outputPath, fileName);
@@ -107,307 +88,24 @@ async function _init(
     }
   }
 
-  console.log("🚀 Welcome to AIGNE DocSmith!");
-  console.log("Let's set up your documentation preferences.\n");
-
   const input = {};
 
-  const purposeChoices = await options.prompts.checkbox({
-    message: "📝 [1/9]: What should your documentation help readers achieve?",
-    choices: Object.entries(DOCUMENT_STYLES)
-      .filter(([key]) => key !== "custom")
-      .map(([key, style]) => ({
-        name: `${style.name}`,
-        description: style.description,
-        value: key,
-      })),
-    validate: (input) => {
-      if (input.length === 0) {
-        return "You must choose at least one goal for your documentation.";
-      }
-      return true;
-    },
-  });
-
-  let prioritizedPurposes = purposeChoices;
-  if (purposeChoices.length === 1 && purposeChoices.includes("mixedPurpose")) {
-    const topPriorities = await options.prompts.checkbox({
-      message: "🎯 Which is most important? (Select up to 2 priorities)",
-      choices: Object.entries(DOCUMENT_STYLES)
-        .filter(([key]) => key !== "custom" && key !== "mixedPurpose")
-        .map(([key, style]) => ({
-          name: `${style.name}`,
-          description: style.description,
-          value: key,
-        })),
-      validate: (input) => {
-        if (input.length === 0) {
-          return "You must choose at least one priority.";
-        }
-        if (input.length > 2) {
-          return "You may only choose up to 2 priorities.";
-        }
-        return true;
-      },
-    });
-
-    prioritizedPurposes = topPriorities;
-  }
-
-  input.documentPurpose = prioritizedPurposes;
-
-  const audienceChoices = await options.prompts.checkbox({
-    message: "👥 [2/9]: Who will be reading your documentation?",
-    choices: Object.entries(TARGET_AUDIENCES)
-      .filter(([key]) => key !== "custom")
-      .map(([key, audience]) => ({
-        name: `${audience.name}`,
-        description: audience.description,
-        value: key,
-      })),
-    validate: (input) => {
-      if (input.length === 0) {
-        return "You must choose at least one audience.";
-      }
-      return true;
-    },
-  });
-
-  input.targetAudienceTypes = audienceChoices;
-
-  const mappedPurpose = prioritizedPurposes.find(
-    (purpose) => PURPOSE_TO_KNOWLEDGE_MAPPING[purpose],
-  );
-  const defaultKnowledge = mappedPurpose ? PURPOSE_TO_KNOWLEDGE_MAPPING[mappedPurpose] : null;
-
-  const { filteredOptions: filteredKnowledgeOptions } = getFilteredOptions(
-    "readerKnowledgeLevel",
-    { documentPurpose: prioritizedPurposes, targetAudienceTypes: audienceChoices },
-    READER_KNOWLEDGE_LEVELS,
-  );
-
-  const knowledgeChoice = await options.prompts.select({
-    message: "🧠 [3/9]: How much do your readers already know about your project?",
-    choices: Object.entries(filteredKnowledgeOptions).map(([key, level]) => ({
-      name: `${level.name}`,
-      description: level.description,
-      value: key,
-    })),
-    default: defaultKnowledge,
-  });
-
-  // Save reader knowledge level choice as key
-  input.readerKnowledgeLevel = knowledgeChoice;
-
-  // 4. Documentation depth - how comprehensive should the documentation be?
-  // Determine default based on priority: Purpose > Audience > Knowledge Level
-  const getDepthDefault = () => {
-    // Check priority order: purposes -> audiences -> knowledgeLevels
-    const checks = [
-      () => {
-        const purpose = prioritizedPurposes.find((p) => DEPTH_RECOMMENDATION_LOGIC.purposes[p]);
-        return purpose ? DEPTH_RECOMMENDATION_LOGIC.purposes[purpose] : null;
-      },
-      () => {
-        const audience = audienceChoices.find((a) => DEPTH_RECOMMENDATION_LOGIC.audiences[a]);
-        return audience ? DEPTH_RECOMMENDATION_LOGIC.audiences[audience] : null;
-      },
-      () => DEPTH_RECOMMENDATION_LOGIC.knowledgeLevels[knowledgeChoice] || null,
-    ];
-
-    return checks.find((check) => check())?.() || null;
-  };
-
-  const defaultDepth = getDepthDefault();
-
-  // Filter documentation depth options based on all previous selections
-  const { filteredOptions: filteredDepthOptions } = getFilteredOptions(
-    "documentationDepth",
-    {
-      documentPurpose: prioritizedPurposes,
-      targetAudienceTypes: audienceChoices,
-      readerKnowledgeLevel: knowledgeChoice,
-    },
-    DOCUMENTATION_DEPTH,
-  );
-
-  const depthChoice = await options.prompts.select({
-    message: "📊 [4/9]: How detailed should your documentation be?",
-    choices: Object.entries(filteredDepthOptions).map(([key, depth]) => ({
-      name: `${depth.name}`,
-      description: depth.description,
-      value: key,
-    })),
-    default: defaultDepth,
-  });
-
-  // Save documentation depth choice as key
-  input.documentationDepth = depthChoice;
-
-  // 5. Language settings
-  // Detect system language and use as default
-  const systemLanguage = detectSystemLanguage();
-
-  // Let user select primary language from supported list
-  const primaryLanguageChoice = await options.prompts.select({
-    message: "🌐 [5/9]: What is the main language of your documentation?",
-    choices: SUPPORTED_LANGUAGES.map((lang) => ({
-      name: `${lang.label} - ${lang.sample}`,
-      value: lang.code,
-    })),
-    default: systemLanguage,
-  });
-
-  input.locale = primaryLanguageChoice;
-
-  // 6. Translation languages
-  // Filter out the primary language from available choices
-  const availableTranslationLanguages = SUPPORTED_LANGUAGES.filter(
-    (lang) => lang.code !== primaryLanguageChoice,
-  );
-
-  const translateLanguageChoices = await options.prompts.checkbox({
-    message: "🔄 [6/9]: What languages should we translate to?",
-    choices: availableTranslationLanguages.map((lang) => ({
-      name: `${lang.label} - ${lang.sample}`,
-      value: lang.code,
-    })),
-  });
-
-  input.translateLanguages = translateLanguageChoices;
-
-  // 7. Documentation directory
-  const docsDirInput = await options.prompts.input({
-    message: `📁 [7/9]: Where should we save your documentation?`,
-    default: `${outputPath}/docs`,
-    validate: validateDocDir,
-  });
-  input.docsDir = docsDirInput.trim() || `${outputPath}/docs`;
-
-  // 8. Content sources
-  console.log("🔍 [8/9]: Data Sources");
-  console.log("Please specify the data source we should analyze to generate your documentation.");
-  console.log(
-    `  1. Use paths like ${chalk.green("./src")}, ${chalk.green("./README.md")} or ${chalk.green("!./src/private")}.`,
-  );
-  console.log(
-    `  2. Use globs like ${chalk.green("src/**/*.js")} or ${chalk.green(
-      "!private/**/*.js",
-    )} for more specific file matching.`,
-  );
-  console.log(`  3. Use URLs like ${chalk.green("https://example.com/openapi.yaml")}.`);
-  console.log("💡 If you leave this empty, we will scan the entire directory.");
-
-  const sourcePaths = [];
-  while (true) {
-    const selectedPath = await options.prompts.search({
-      message: "Please enter a valid data source:",
-      source: async (input) => {
-        if (!input || input.trim() === "") {
-          return [
-            {
-              name: "",
-              value: "",
-              description: _PRESS_ENTER_TO_FINISH,
-            },
-          ];
-        }
-
-        let isIgnore = false;
-        const searchTerm = input.trim();
-        let cleanSearchTerm = searchTerm;
-        if (cleanSearchTerm.startsWith("!")) {
-          isIgnore = true;
-          cleanSearchTerm = searchTerm.slice(1);
-        }
-
-        // Search for matching files and folders in current directory
-        const availablePaths = getAvailablePaths(cleanSearchTerm);
-
-        // Also add option to use as glob pattern
-        const options = [...availablePaths].map((x) => ({
-          ...x,
-          name: isIgnore ? `!${x.name}` : x.name,
-          value: isIgnore ? `!${x.value}` : x.value,
-        }));
-
-        // 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: "Use this glob pattern for file matching.",
-          });
-        }
-
-        if (!isIgnore && isRemoteFile(searchTerm)) {
-          options.push({
-            name: searchTerm,
-            value: searchTerm,
-            description: "Use this remote url for content source.",
-          });
-        }
-
-        return options;
-      },
-    });
-
-    // Check if user chose to exit
-    if (!selectedPath || selectedPath.trim() === "" || selectedPath === _PRESS_ENTER_TO_FINISH) {
-      break;
-    }
-
-    const trimmedPath = selectedPath.trim();
+  // 5. Language settings - use system language detection as default
+  // const systemLanguage = detectSystemLanguage();
+  // FIXME: 临时使用中文，框架优化后需要修改
+  input.locale = "zh";
 
-    // Check if it's a glob pattern
-    const isGlobPatternResult = isGlobPattern(trimmedPath);
+  // 6. Translation languages - default to empty
+  input.translateLanguages = [];
 
-    if (isRemoteFile(trimmedPath)) {
-      // For remote urls, just add them without validation
-      if (sourcePaths.includes(trimmedPath)) {
-        console.log(`⚠️ URL already exists: ${trimmedPath}`);
-        continue;
-      }
-      sourcePaths.push(trimmedPath);
-    } else 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 {
-      const cleanTrimmedPath = trimmedPath.startsWith("!") ? trimmedPath.slice(1) : trimmedPath;
-      // Use validatePath to check if path is valid for regular paths
-      const validation = validatePath(cleanTrimmedPath);
-
-      if (!validation.isValid) {
-        console.log(`⚠️ ${validation.error}`);
-        continue;
-      }
-
-      // Avoid duplicate paths
-      if (sourcePaths.includes(trimmedPath)) {
-        console.log(`⚠️ Path already exists: ${trimmedPath}`);
-        continue;
-      }
-
-      sourcePaths.push(trimmedPath);
-    }
-  }
+  // 7. Documentation directory - use default value
+  input.docsDir = `${outputPath}/docs`;
 
-  // If no paths entered, use default
-  input.sourcesPath = sourcePaths.length > 0 ? sourcePaths : ["./"];
+  // 8. Content sources - use "./" as default
+  input.sourcesPath = ["./"];
 
-  // 9. Custom rules - any specific requirements for the documentation?
-  const rulesInput = await options.prompts.input({
-    message:
-      "📋 [9/9]: Do you have any custom rules or requirements for your documentation? (Optional, press Enter to skip)",
-    default: "",
-  });
-  input.rules = rulesInput.trim();
+  // 9. Custom rules - default to empty
+  input.rules = "";
 
   // Save project info to config
   const projectInfo = await getProjectInfo();
@@ -468,12 +166,6 @@ export function generateYAML(input) {
       effort: input.thinking?.effort || DEFAULT_THINKING_EFFORT_LEVEL,
     },
 
-    // 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: input.rules || "",
     targetAudience: "",
@@ -516,65 +208,6 @@ export function generateYAML(input) {
 ${modelSection}
 \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";
-  Object.entries(DOCUMENT_STYLES).forEach(([key, style]) => {
-    if (key !== "custom") {
-      yaml += `#   ${key.padEnd(16)} - ${style.name}: ${style.description}\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";
-  Object.entries(TARGET_AUDIENCES).forEach(([key, audience]) => {
-    if (key !== "custom") {
-      yaml += `#   ${key.padEnd(16)} - ${audience.name}: ${audience.description}\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";
-  Object.entries(READER_KNOWLEDGE_LEVELS).forEach(([key, level]) => {
-    yaml += `#   ${key.padEnd(20)} - ${level.name}: ${level.description}\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";
-  Object.entries(DOCUMENTATION_DEPTH).forEach(([key, depth]) => {
-    yaml += `#   ${key.padEnd(18)} - ${depth.name}: ${depth.description}\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";
   const rulesSection = yamlStringify({ rules: config.rules }).trim();
@@ -621,6 +254,21 @@ ${modelSection}
   }).trim();
   yaml += `# minImageWidth: Only images wider than this value (in pixels) will be used in the page generation.\n${mediaInfoSection}\n`;
 
+  // Diagramming configuration
+  yaml += "\n# Diagramming Configuration\n";
+  yaml +=
+    "# diagramming.effort: AI effort level for diagramming, 0-10, larger value means fewer diagrams\n";
+  yaml += "diagramming:\n";
+  yaml += "  effort: 5  # AI effort level for diagramming, 0-10, large is less diagram\n";
+  yaml +=
+    "  # Default diagram style: The primary style to use when no style is specified in feedback\n";
+  yaml += "  # This style will be applied if feedback doesn't specify a different style\n";
+  yaml += "  # Available options:\n";
+  Object.entries(DIAGRAM_STYLES).forEach(([key, style]) => {
+    yaml += `  #   ${key.padEnd(16)} - ${style.name}: ${style.description}\n`;
+  });
+  yaml += '  # style: "modern"\n';
+
   return yaml;
 }
 

package/agents/localize/index.yaml

@@ -39,14 +39,14 @@ skills:
 input_schema:
   type: object
   properties:
-    glossary:
-      type: string
-      description: Glossary file for consistent terminology (use @filename.md)
+    # glossary:
+    #   type: string
+    #   description: Glossary file for consistent terminology (use @filename.md)
     docs:
       type: array
       items:
         type: string
-      description: Documents to translate
+      description: Documents to update, use document path in document structure to specify
     langs:
       type: array
       items:

package/agents/media/batch-generate-media-description.yaml

@@ -25,6 +25,8 @@ input_schema:
             type: string
           type:
             type: string
+          svgContent:
+            type: string
           mediaFile:
             type: array
             items:

package/agents/media/generate-media-description.yaml

@@ -29,6 +29,9 @@ input_schema:
     type:
       type: string
       description: Media type (image/video)
+    svgContent:
+      type: string
+      description: SVG content
     mediaFile:
       type: array
       items:

package/agents/media/load-media-description.mjs

@@ -6,6 +6,7 @@ import { parse, stringify } from "yaml";
 import { getMediaDescriptionCachePath } from "../../utils/file-utils.mjs";
 
 const SIZE_THRESHOLD = 10 * 1024 * 1024; // 10MB
+const SVG_SIZE_THRESHOLD = 50 * 1024; // 50KB for SVG files
 
 // Supported MIME types for Gemini AI
 const SUPPORTED_IMAGE_TYPES = new Set([
@@ -16,6 +17,8 @@ const SUPPORTED_IMAGE_TYPES = new Set([
   "image/heif",
 ]);
 
+const SUPPORTED_SVG_TYPES = new Set(["image/svg+xml"]);
+
 const SUPPORTED_VIDEO_TYPES = new Set([
   "video/mp4",
   "video/mpeg",
@@ -60,10 +63,10 @@ async function calculateMediaHash(absolutePath) {
 export default async function loadMediaDescription(input, options) {
   const { mediaFiles = [], docsDir } = input;
 
-  // Filter to get image and video files with supported MIME types
+  // Filter to get image, video and svg files with supported MIME types
   const mediaFilesToProcess = mediaFiles.filter((file) => {
     if (file.type === "image") {
-      return SUPPORTED_IMAGE_TYPES.has(file.mimeType);
+      return SUPPORTED_IMAGE_TYPES.has(file.mimeType) || SUPPORTED_SVG_TYPES.has(file.mimeType);
     }
     if (file.type === "video") {
       return SUPPORTED_VIDEO_TYPES.has(file.mimeType);
@@ -101,19 +104,45 @@ export default async function loadMediaDescription(input, options) {
     mediaHashMap.set(mediaFile.path, mediaHash);
 
     if (!cache[mediaHash]) {
-      mediaToDescribe.push({
-        ...mediaFile,
-        hash: mediaHash,
-        path: mediaFile.path,
-        mediaFile: [
-          {
-            type: "local",
-            path: absolutePath,
-            filename: mediaFile.name,
-            mimeType: mediaFile.mimeType,
-          },
-        ],
-      });
+      const isSvg = SUPPORTED_SVG_TYPES.has(mediaFile.mimeType);
+
+      if (isSvg) {
+        // For SVG files, check size and read content
+        try {
+          const stats = await stat(absolutePath);
+          if (stats.size > SVG_SIZE_THRESHOLD) {
+            console.warn(
+              `SVG file ${mediaFile.path} exceeds ${SVG_SIZE_THRESHOLD / 1024}KB limit, skipping`,
+            );
+            continue;
+          }
+
+          const svgContent = await readFile(absolutePath, "utf8");
+          mediaToDescribe.push({
+            ...mediaFile,
+            hash: mediaHash,
+            path: mediaFile.path,
+            svgContent,
+          });
+        } catch (error) {
+          console.warn(`Failed to read SVG file ${mediaFile.path}:`, error.message);
+        }
+      } else {
+        // For non-SVG media files, use mediaFile field
+        mediaToDescribe.push({
+          ...mediaFile,
+          hash: mediaHash,
+          path: mediaFile.path,
+          mediaFile: [
+            {
+              type: "local",
+              path: absolutePath,
+              filename: mediaFile.name,
+              mimeType: mediaFile.mimeType,
+            },
+          ],
+        });
+      }
     }
   }
 

package/agents/publish/index.yaml

@@ -11,6 +11,7 @@ skills:
       checkOnly: true
   - url: ../init/check.mjs
   - url: ../utils/load-sources.mjs
+  - ../utils/save-sidebar.mjs
   - ../utils/ensure-document-icons.mjs
   - translate-meta.mjs
   - publish-docs.mjs

package/agents/publish/publish-docs.mjs

@@ -16,7 +16,7 @@ import {
   TMP_DIR,
   TMP_DOCS_DIR,
 } from "../../utils/constants/index.mjs";
-import { beforePublishHook, ensureTmpDir } from "../../utils/d2-utils.mjs";
+import { ensureTmpDir } from "../../utils/d2-utils.mjs";
 import { deploy } from "../../utils/deploy.mjs";
 import { getGithubRepoUrl, loadConfigFromFile, saveValueToConfig } from "../../utils/utils.mjs";
 import updateBranding from "../utils/update-branding.mjs";
@@ -53,9 +53,6 @@ export default async function publishDocs(
     });
     await fs.cp(rawDocsDir, docsDir, { recursive: true });
 
-    // ----------------- trigger beforePublishHook -----------------------------
-    await beforePublishHook({ docsDir });
-
     // ----------------- main publish process flow -----------------------------
     // Check if DOC_DISCUSS_KIT_URL is set in environment variables
     const useEnvAppUrl = !!(