@aigne/doc-smith 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.2.2](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.2.1...v0.2.2) (2025-08-07)
+
+
+### Miscellaneous Chores
+
+* release 0.2.2 ([c3fb52a](https://github.com/AIGNE-io/aigne-doc-smith/commit/c3fb52a78b95676e1c13361b30ebec2914a89fa8))
+
+## [0.2.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.2.0...v0.2.1) (2025-08-06)
+
+
+### Miscellaneous Chores
+
+* release 0.2.1 ([e3a39ae](https://github.com/AIGNE-io/aigne-doc-smith/commit/e3a39aedcee129deae424e96942f9798b9191663))
+
 ## [0.2.0](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.1.4...v0.2.0) (2025-08-05)
 
 

package/README.md

@@ -63,8 +63,10 @@ npx --no doc-smith run --entry-agent init
 # 生成命令
 npx --no doc-smith run --entry-agent generate --model gemini:gemini-2.5-flash
 
+aigne run --path /Users/lban/arcblock/code/aigne-doc-smith/ --entry-agent generate --model gemini:gemini-2.5-flash --input-forceRegenerate=true
+
 # 重新生成单篇
-npx --no doc-smith run --entry-agent update --input-path bitnet-getting-started
+npx --no doc-smith run --entry-agent update --input-doc-path bitnet-getting-started
 
 # 结构规划优化
 npx --no doc-smith run --entry-agent generate --input-feedback "补充节点的 sourceIds，确保所有节点 sourceIds 都有值" --model gemini:gemini-2.5-pro

package/agents/batch-docs-detail-generator.yaml

@@ -1,8 +1,8 @@
 type: team
-name: batch-docs-detail-generator
+name: batchDocsDetailGenerator
 description: 批量生成文档详情
 skills:
-  - ./check-detail-generated.mjs
+  - ./check-detail.mjs
 input_schema:
   type: object
   properties:
@@ -15,4 +15,5 @@ input_schema:
       items: { type: string }
       description: Array of modified files since last generation
 iterate_on: structurePlanResult
+concurrency: 3
 mode: sequential

package/agents/batch-translate.yaml

@@ -1,5 +1,5 @@
 type: team
-name: batch-translate
+name: batchTranslate
 description: 批量翻译文档到多个语言
 skills:
   - type: team

package/agents/{check-detail-generated.mjs → check-detail.mjs}

@@ -8,7 +8,7 @@ import { hasSourceFilesChanged } from "../utils/utils.mjs";
 // Get current script directory
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-export default async function checkDetailGenerated(
+export default async function checkDetail(
   {
     path,
     docsDir,
@@ -17,6 +17,7 @@ export default async function checkDetailGenerated(
     structurePlan,
     modifiedFiles,
     lastGitHead,
+    forceRegenerate,
     ...rest
   },
   options
@@ -104,7 +105,8 @@ export default async function checkDetailGenerated(
     detailGenerated &&
     !sourceIdsChanged &&
     !sourceFilesChanged &&
-    !contentValidationFailed
+    !contentValidationFailed &&
+    forceRegenerate !== "true"
   ) {
     return {
       path,
@@ -115,8 +117,8 @@ export default async function checkDetailGenerated(
   }
 
   const teamAgent = TeamAgent.from({
-    name: "generate-detail",
-    skills: [options.context.agents["detail-generator-and-translate"]],
+    name: "generateDetail",
+    skills: [options.context.agents["detailGeneratorAndTranslate"]],
   });
 
   const result = await options.context.invoke(teamAgent, {

package/agents/{check-structure-planning.mjs → check-structure-plan.mjs}

@@ -3,8 +3,8 @@ import {
   hasFileChangesBetweenCommits,
 } from "../utils/utils.mjs";
 
-export default async function checkStructurePlanning(
-  { originalStructurePlan, feedback, lastGitHead, ...rest },
+export default async function checkStructurePlan(
+  { originalStructurePlan, feedback, lastGitHead, forceRegenerate, ...rest },
   options
 ) {
   // Check if we need to regenerate structure plan
@@ -43,13 +43,18 @@ export default async function checkStructurePlanning(
   }
 
   // If no regeneration needed, return original structure plan
-  if (originalStructurePlan && !feedback && !shouldRegenerate) {
+  if (
+    originalStructurePlan &&
+    !feedback &&
+    !shouldRegenerate &&
+    forceRegenerate !== "true"
+  ) {
     return {
       structurePlan: originalStructurePlan,
     };
   }
 
-  const panningAgent = options.context.agents["reflective-structure-planner"];
+  const panningAgent = options.context.agents["reflectiveStructurePlanner"];
 
   const result = await options.context.invoke(panningAgent, {
     feedback: finalFeedback || "",

package/agents/check-structure-planning-result.yaml

@@ -1,4 +1,4 @@
-name: check-structure-planning-result
+name: checkStructurePlanResult
 description: 对 structure-planning agent 生成的结果进行检查，确保其符合预期，特别是在有上一轮生成结果和用户反馈的场景下。
 instructions:
   url: ../prompts/check-structure-planning-result.md

package/agents/content-detail-generator.yaml

@@ -1,4 +1,4 @@
-name: content-detail-generator
+name: contentDetailGenerator
 description: 通用内容详情生成器，支持网站、文档、书籍、演示文稿等多种场景
 instructions:
   url: ../prompts/content-detail-generator.md

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

@@ -1,5 +1,5 @@
 type: team
-name: detail-generator-and-translate
+name: detailGeneratorAndTranslate
 description: 生成文档详情并翻译
 skills:
   - ./transform-detail-datasources.mjs

package/agents/docs-generator.yaml

@@ -10,16 +10,15 @@ skills:
       skipIfExists: true
   - ./load-config.mjs
   - ./load-sources.mjs
-  - ./check-structure-planning.mjs
-  - type: transform
-    jsonata: |
-      $merge([$, {
-      "saveKey": "structurePlan",
-      "savePath": outputDir,
-      "fileName": "structure-plan.json"
-      }])
-  - ./save-output.mjs
+  - ./check-structure-plan.mjs
+  - url: ./save-output.mjs
+    default_input:
+      saveKey: structurePlan
+      savePath:
+        $get: outputDir
+      fileName: structure-plan.json
   - type: transform
+    name: transformData
     jsonata: |
       $merge([
         $,
@@ -103,6 +102,9 @@ input_schema:
     feedback:
       type: string
       description: Feedback for structure planning adjustments
+    forceRegenerate:
+      type: string
+      description: Force regenerate the documentation
     # labels:
     #   type: array
     #   items:

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

@@ -1,10 +1,89 @@
-export default async function findItemByPath({
-  "doc-path": docPath,
-  structurePlanResult,
-  boardId,
-}) {
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+export default async function findItemByPath(
+  { "doc-path": docPath, structurePlanResult, boardId, docsDir },
+  options
+) {
   let foundItem = null;
 
+  // If docPath is empty, let user select from available documents
+  if (!docPath) {
+    try {
+      // Get all .md files in docsDir
+      const files = await readdir(docsDir);
+
+      // Filter for main language .md files (exclude _sidebar.md and language-specific files)
+      const mainLanguageFiles = files.filter(
+        (file) =>
+          file.endsWith(".md") &&
+          file !== "_sidebar.md" &&
+          !file.match(/\.\w+(-\w+)?\.md$/) // Exclude language-specific files like .en.md, .zh-CN.md, etc.
+      );
+
+      if (mainLanguageFiles.length === 0) {
+        throw new Error(
+          "Please provide a doc-path parameter to specify which document to update"
+        );
+      }
+
+      // Let user select a file
+      const selectedFile = await options.prompts.search({
+        message: "Select a document to update:",
+        source: async (input, { signal }) => {
+          if (!input || input.trim() === "") {
+            return mainLanguageFiles.map((file) => ({
+              name: file,
+              value: file,
+            }));
+          }
+
+          const searchTerm = input.trim().toLowerCase();
+          const filteredFiles = mainLanguageFiles.filter((file) =>
+            file.toLowerCase().includes(searchTerm)
+          );
+
+          return filteredFiles.map((file) => ({
+            name: file,
+            value: file,
+          }));
+        },
+      });
+
+      if (!selectedFile) {
+        throw new Error(
+          "Please provide a doc-path parameter to specify which document to update"
+        );
+      }
+
+      // Convert filename back to path
+      // Remove .md extension
+      const flatName = selectedFile.replace(/\.md$/, "");
+
+      // Try to find matching item by comparing flattened paths
+      let foundItemByFile = null;
+
+      // First try without boardId prefix
+      foundItemByFile = structurePlanResult.find((item) => {
+        const itemFlattenedPath = item.path
+          .replace(/^\//, "")
+          .replace(/\//g, "-");
+        return itemFlattenedPath === flatName;
+      });
+      if (!foundItemByFile) {
+        throw new Error(
+          "Please provide a doc-path parameter to specify which document to update"
+        );
+      }
+
+      docPath = foundItemByFile.path;
+    } catch (error) {
+      throw new Error(
+        "Please provide a doc-path parameter to specify which document to update"
+      );
+    }
+  }
+
   // First try direct path matching
   foundItem = structurePlanResult.find((item) => item.path === docPath);
 

package/agents/input-generator.mjs

@@ -1,37 +1,15 @@
 import { writeFile, mkdir, readFile } from "node:fs/promises";
 import { join, dirname } from "node:path";
+import chalk from "chalk";
+import { validatePath, getAvailablePaths } from "../utils/utils.mjs";
+import {
+  SUPPORTED_LANGUAGES,
+  DOCUMENT_STYLES,
+  TARGET_AUDIENCES,
+} from "../utils/constants.mjs";
 
-// Predefined document generation styles
-const DOCUMENT_STYLES = {
-  actionFirst: {
-    name: "Action-First Style",
-    rules:
-      "Action-first and task-oriented; steps first, copyable examples, minimal context; second person, active voice, short sentences",
-  },
-  conceptFirst: {
-    name: "Concept-First Style",
-    rules:
-      "Why/What before How; precise and restrained, provide trade-offs and comparisons; support with architecture/flow/sequence diagrams",
-  },
-  specReference: {
-    name: "Spec-Reference Style",
-    rules:
-      "Objective and precise, no rhetoric; tables/Schema focused, authoritative fields and defaults; clear error codes and multi-language examples",
-  },
-  custom: {
-    name: "Custom Rules",
-    rules: "Enter your own documentation generation rules",
-  },
-};
-
-// Predefined target audiences
-const TARGET_AUDIENCES = {
-  actionFirst: "Developers, Implementation Engineers, DevOps",
-  conceptFirst:
-    "Architects, Technical Leads, Developers interested in principles",
-  generalUsers: "General Users",
-  custom: "Enter your own target audience",
-};
+// UI constants
+const PRESS_ENTER_TO_FINISH = "Press Enter to finish";
 
 /**
  * Guide users through multi-turn dialogue to collect information and generate YAML configuration
@@ -41,17 +19,21 @@ const TARGET_AUDIENCES = {
  * @returns {Promise<Object>}
  */
 export default async function init(
-  { outputPath = "./doc-smith", fileName = "config.yaml", skipIfExists = false },
+  {
+    outputPath = "./doc-smith",
+    fileName = "config.yaml",
+    skipIfExists = false,
+  },
   options
 ) {
   if (skipIfExists) {
     const filePath = join(outputPath, fileName);
     if (await readFile(filePath, "utf8").catch(() => null)) {
-      return {}
+      return {};
     }
   }
 
-  console.log("🚀 Welcome to AIGNE Doc Smith!");
+  console.log("🚀 Welcome to AIGNE DocSmith!");
   console.log("Let's create your documentation configuration.\n");
 
   // Collect user information
@@ -78,7 +60,6 @@ export default async function init(
   } else {
     // Use predefined style directly
     rules = DOCUMENT_STYLES[styleChoice].rules;
-    console.log(`✅ Selected: ${DOCUMENT_STYLES[styleChoice].name}`);
   }
 
   input.rules = rules.trim();
@@ -104,58 +85,105 @@ export default async function init(
   } else {
     // Use predefined audience directly
     targetAudience = TARGET_AUDIENCES[audienceChoice];
-    console.log(`✅ Selected: ${TARGET_AUDIENCES[audienceChoice]}`);
   }
 
   input.targetAudience = targetAudience.trim();
 
   // 3. Language settings
   console.log("\n🌐 Step 3/6: Primary Language");
-  const localeInput = await options.prompts.input({
-    message:
-      "Primary documentation language (e.g., en, zh, press Enter for 'en'):",
+
+  // Let user select primary language from supported list
+  const primaryLanguageChoice = await options.prompts.select({
+    message: "Choose primary documentation language:",
+    choices: SUPPORTED_LANGUAGES.map((lang) => ({
+      name: `${lang.label} - ${lang.sample}`,
+      value: lang.code,
+    })),
   });
-  input.locale = localeInput.trim() || "en";
+
+  input.locale = primaryLanguageChoice;
 
   // 4. Translation languages
   console.log("\n🔄 Step 4/6: Translation Languages");
-  console.log(
-    "Enter additional languages for translation (press Enter to skip):"
+
+  // Filter out the primary language from available choices
+  const availableTranslationLanguages = SUPPORTED_LANGUAGES.filter(
+    (lang) => lang.code !== primaryLanguageChoice
   );
-  const translateLanguages = [];
-  while (true) {
-    const langInput = await options.prompts.input({
-      message: `Language ${translateLanguages.length + 1} (e.g., zh, ja, fr):`,
-    });
-    if (!langInput.trim()) {
-      break;
-    }
-    translateLanguages.push(langInput.trim());
-  }
-  input.translateLanguages = translateLanguages;
+
+  const translateLanguageChoices = await options.prompts.checkbox({
+    message: "Select translation languages:",
+    choices: availableTranslationLanguages.map((lang) => ({
+      name: `${lang.label} - ${lang.sample}`,
+      value: lang.code,
+    })),
+  });
+
+  input.translateLanguages = translateLanguageChoices;
 
   // 5. Documentation directory
   console.log("\n📁 Step 5/6: Output Directory");
   const docsDirInput = await options.prompts.input({
-    message: `Where to save generated docs (press Enter for '${outputPath}/docs'):`,
+    message: `Where to save generated docs:`,
+    default: `${outputPath}/docs`,
   });
   input.docsDir = docsDirInput.trim() || `${outputPath}/docs`;
 
   // 6. Source code paths
   console.log("\n🔍 Step 6/6: Source Code Paths");
-  console.log(
-    "Enter paths to analyze for documentation (press Enter to use './'):"
-  );
+  console.log("Enter paths to analyze for documentation (e.g., ./src, ./lib)");
+  console.log("💡 If no paths are configured, './' will be used as default");
 
   const sourcePaths = [];
   while (true) {
-    const pathInput = await options.prompts.input({
-      message: `Path ${sourcePaths.length + 1} (e.g., ./src, ./lib):`,
+    const selectedPath = await options.prompts.search({
+      message: "Path:",
+      source: async (input, { signal }) => {
+        if (!input || input.trim() === "") {
+          return [
+            {
+              name: "Press Enter to finish",
+              value: "",
+              description: "",
+            },
+          ];
+        }
+
+        const searchTerm = input.trim();
+
+        // Search for matching files and folders in current directory
+        const availablePaths = getAvailablePaths(searchTerm);
+
+        return [...availablePaths];
+      },
     });
-    if (!pathInput.trim()) {
+
+    // Check if user chose to exit
+    if (
+      !selectedPath ||
+      selectedPath.trim() === "" ||
+      selectedPath === "Press Enter to finish"
+    ) {
       break;
     }
-    sourcePaths.push(pathInput.trim());
+
+    const trimmedPath = selectedPath.trim();
+
+    // Use validatePath to check if path is valid
+    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;
+    }
+
+    sourcePaths.push(trimmedPath);
   }
 
   // If no paths entered, use default
@@ -173,18 +201,17 @@ export default async function init(
     await mkdir(dirPath, { recursive: true });
 
     await writeFile(filePath, yamlContent, "utf8");
-    console.log(`\n🎉 Configuration saved to: ${filePath}`);
+    console.log(`\n🎉 Configuration saved to: ${chalk.cyan(filePath)}`);
     console.log(
       "💡 You can edit the configuration file anytime to modify settings."
     );
     console.log(
-      "🚀 Run 'aigne doc generate' to start documentation generation!"
+      `🚀 Run ${chalk.cyan(
+        "'aigne doc generate'"
+      )} to start documentation generation!`
     );
 
-    return {
-      inputGeneratorStatus: true,
-      inputGeneratorPath: filePath,
-    };
+    return {};
   } catch (error) {
     console.error(`❌ Failed to save configuration file: ${error.message}`);
     return {

package/agents/publish-docs.mjs

@@ -15,10 +15,47 @@ const WELLKNOWN_SERVICE_PATH_PREFIX = "/.well-known/service";
 const DEFAULT_APP_URL = "https://docsmith.aigne.io";
 
 /**
- * Get project name from git repository or current directory
- * @returns {string} - The project name
+ * Get GitHub repository information
+ * @param {string} repoUrl - The repository URL
+ * @returns {Promise<Object>} - Repository information
  */
-function getProjectName() {
+async function getGitHubRepoInfo(repoUrl) {
+  try {
+    // Extract owner and repo from GitHub URL
+    const match = repoUrl.match(
+      /github\.com[\/:]([^\/]+)\/([^\/]+?)(?:\.git)?$/
+    );
+    if (!match) return null;
+
+    const [, owner, repo] = match;
+    const apiUrl = `https://api.github.com/repos/${owner}/${repo}`;
+
+    const response = await fetch(apiUrl);
+    if (!response.ok) return null;
+
+    const data = await response.json();
+    return {
+      name: data.name,
+      description: data.description || "",
+      icon: data.owner?.avatar_url || "",
+    };
+  } catch (error) {
+    console.warn("Failed to fetch GitHub repository info:", error.message);
+    return null;
+  }
+}
+
+/**
+ * Get project information with user confirmation
+ * @param {Object} options - Options object containing prompts
+ * @returns {Promise<Object>} - Project information including name, description, and icon
+ */
+async function getProjectInfo(options) {
+  let repoInfo = null;
+  let defaultName = basename(process.cwd());
+  let defaultDescription = "";
+  let defaultIcon = "";
+
   // Check if we're in a git repository
   try {
     const gitRemote = execSync("git remote get-url origin", {
@@ -28,11 +65,59 @@ function getProjectName() {
 
     // Extract repository name from git remote URL
     const repoName = gitRemote.split("/").pop().replace(".git", "");
-    return repoName;
+    defaultName = repoName;
+
+    // If it's a GitHub repository, try to get additional info
+    if (gitRemote.includes("github.com")) {
+      repoInfo = await getGitHubRepoInfo(gitRemote);
+      if (repoInfo) {
+        defaultDescription = repoInfo.description;
+        defaultIcon = repoInfo.icon;
+      }
+    }
   } catch (error) {
     // Not in git repository or no origin remote, use current directory name
-    return basename(process.cwd());
+    console.warn("No git repository found, using current directory name");
   }
+
+  // Prompt user for project information
+  console.log("\n📋 Project Information for Documentation Platform");
+
+  const projectName = await options.prompts.input({
+    message: "Project name:",
+    default: defaultName,
+    validate: (input) => {
+      if (!input || input.trim() === "") {
+        return "Project name cannot be empty";
+      }
+      return true;
+    },
+  });
+
+  const projectDescription = await options.prompts.input({
+    message: "Project description (optional):",
+    default: defaultDescription,
+  });
+
+  const projectIcon = await options.prompts.input({
+    message: "Project icon URL (optional):",
+    default: defaultIcon,
+    validate: (input) => {
+      if (!input || input.trim() === "") return true;
+      try {
+        new URL(input);
+        return true;
+      } catch {
+        return "Please enter a valid URL";
+      }
+    },
+  });
+
+  return {
+    name: projectName.trim(),
+    description: projectDescription.trim(),
+    icon: projectIcon.trim(),
+  };
 }
 
 /**
@@ -79,8 +164,9 @@ async function getAccessToken(appUrl) {
       const result = await createConnect({
         connectUrl: connectUrl,
         connectAction: "gen-simple-access-key",
-        source: `@aigne/cli doc-smith connect to Discuss Kit`,
+        source: `AIGNE DocSmith connect to Discuss Kit`,
         closeOnSuccess: true,
+        appName: "AIGNE DocSmith",
         openPage: (pageUrl) => open(pageUrl),
       });
 
@@ -119,29 +205,33 @@ async function getAccessToken(appUrl) {
 }
 
 export default async function publishDocs(
-  { docsDir, appUrl, boardId },
+  { docsDir, appUrl, boardId, boardName, boardDesc, boardCover },
   options
 ) {
-  // Check if appUrl is default and not saved in config
+  // Check if DOC_DISCUSS_KIT_URL is set in environment variables
+  const envAppUrl = process.env.DOC_DISCUSS_KIT_URL;
+  const useEnvAppUrl = !!envAppUrl;
+
+  // Use environment variable if available, otherwise use the provided appUrl
+  if (useEnvAppUrl) {
+    appUrl = envAppUrl;
+  }
+
+  // Check if appUrl is default and not saved in config (only when not using env variable)
   const config = await loadConfigFromFile();
   const isDefaultAppUrl = appUrl === DEFAULT_APP_URL;
   const hasAppUrlInConfig = config && config.appUrl;
 
-  if (isDefaultAppUrl && !hasAppUrlInConfig) {
-    console.log("\n=== Document Publishing Platform Selection ===");
-    console.log(
-      "Please select the platform where you want to publish your documents:"
-    );
-
+  if (!useEnvAppUrl && isDefaultAppUrl && !hasAppUrlInConfig) {
     const choice = await options.prompts.select({
-      message: "Select publishing platform:",
+      message: "Select platform to publish your documents:",
       choices: [
         {
-          name: "Use official platform (docsmith.aigne.io) - Documents will be publicly accessible, suitable for open source projects",
+          name: "Publish to docsmith.aigne.io - free, but your documents will be public accessible, recommended for open-source projects",
           value: "default",
         },
         {
-          name: "Use private platform - Deploy your own Discuss Kit instance, suitable for internal documentation",
+          name: "Publish to your own website - you will need to run Discuss Kit by your self ",
           value: "custom",
         },
       ],
@@ -168,34 +258,48 @@ export default async function publishDocs(
 
   const sidebarPath = join(docsDir, "_sidebar.md");
 
-  const boardName = boardId ? "" : getProjectName();
+  let projectInfo = {
+    name: boardName,
+    description: boardDesc,
+    icon: boardCover,
+  };
+
+  // Only get project info if we need to create a new board
+  if (!boardName) {
+    projectInfo = await getProjectInfo(options);
+
+    // save project info to config
+    await saveValueToConfig("boardName", projectInfo.name);
+    await saveValueToConfig("boardDesc", projectInfo.description);
+    await saveValueToConfig("boardCover", projectInfo.icon);
+  }
 
   const { success, boardId: newBoardId } = await publishDocsFn({
     sidebarPath,
     accessToken,
     appUrl,
     boardId,
-    // If boardId is empty, use project name as boardName and auto create board
-    boardName,
-    autoCreateBoard: !boardId,
+    autoCreateBoard: true,
+    // Pass additional project information if available
+    boardName: projectInfo.name,
+    boardDesc: projectInfo.description,
+    boardCover: projectInfo.icon,
   });
 
   // Save values to config.yaml if publish was successful
   if (success) {
-    // Save appUrl to config
-    await saveValueToConfig("appUrl", appUrl);
+    // Save appUrl to config only when not using environment variable
+    if (!useEnvAppUrl) {
+      await saveValueToConfig("appUrl", appUrl);
+    }
 
     // Save boardId to config if it was auto-created
-    if (!boardId && newBoardId) {
+    if (boardId !== newBoardId) {
       await saveValueToConfig("boardId", newBoardId);
     }
   }
 
-  return {
-    publishResult: {
-      success,
-    },
-  };
+  return {};
 }
 
 publishDocs.input_schema = {

package/agents/reflective-structure-planner.yaml

@@ -1,5 +1,5 @@
 type: team
-name: reflective-structure-planner
+name: reflectiveStructurePlanner
 description: A team of agents that plan the structure of the documentation.
 skills:
   - structure-planning.yaml

package/agents/save-docs.mjs

@@ -16,7 +16,6 @@ export default async function saveDocs({
   locale,
 }) {
   const results = [];
-
   // Save current git HEAD to config.yaml for change detection
   try {
     const gitHead = getCurrentGitHead();
@@ -30,25 +29,23 @@ export default async function saveDocs({
     const sidebar = generateSidebar(structurePlan);
     const sidebarPath = join(docsDir, "_sidebar.md");
     await writeFile(sidebarPath, sidebar, "utf8");
-    results.push({ path: sidebarPath, success: true });
   } catch (err) {
-    results.push({ path: "_sidebar.md", success: false, error: err.message });
+    console.error("Failed to save _sidebar.md:", err.message);
   }
 
   // Clean up invalid .md files that are no longer in the structure plan
   try {
-    const cleanupResults = await cleanupInvalidFiles(
+    await cleanupInvalidFiles(
       structurePlan,
       docsDir,
       translateLanguages,
       locale
     );
-    results.push(...cleanupResults);
   } catch (err) {
-    results.push({ path: "cleanup", success: false, error: err.message });
+    console.error("Failed to cleanup invalid .md files:", err.message);
   }
 
-  return { saveDocsResult: results };
+  return {};
 }
 
 /**

package/agents/save-single-doc.mjs

@@ -16,5 +16,5 @@ export default async function saveSingleDoc({
     labels,
     locale,
   });
-  return { saveSingleDocResult: results };
+  return {};
 }

package/agents/structure-planning.yaml

@@ -1,4 +1,4 @@
-name: structure-planning
+name: structurePlanning
 description: 通用结构规划生成器，支持网站、文档、书籍、演示文稿等多种场景
 instructions:
   url: ../prompts/structure-planning.md

package/aigne.yaml

@@ -12,12 +12,12 @@ agents:
   - ./agents/save-docs.mjs
   - ./agents/translate.yaml
   - ./agents/detail-generator-and-translate.yaml
-  - ./agents/check-detail-generated.mjs
+  - ./agents/check-detail.mjs
   - ./agents/transform-detail-datasources.mjs
   - ./agents/batch-translate.yaml
   - ./agents/save-single-doc.mjs
   - ./agents/save-output.mjs
-  - ./agents/check-structure-planning.mjs
+  - ./agents/check-structure-plan.mjs
   - ./agents/content-detail-generator.yaml
   - ./agents/reflective-structure-planner.yaml
   - ./agents/check-structure-planning-result.yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "",
   "publishConfig": {
     "access": "public"
@@ -12,14 +12,16 @@
   "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
   "license": "MIT",
   "dependencies": {
-    "@aigne/anthropic": "^0.10.6",
-    "@aigne/cli": "^1.30.1",
-    "@aigne/core": "^1.43.0",
-    "@aigne/gemini": "^0.8.10",
-    "@aigne/openai": "^0.10.10",
-    "@aigne/publish-docs": "^0.5.2",
+    "@aigne/anthropic": "^0.10.10",
+    "@aigne/cli": "^1.31.0",
+    "@aigne/core": "^1.46.0",
+    "@aigne/gemini": "^0.8.14",
+    "@aigne/openai": "^0.10.14",
+    "@aigne/publish-docs": "^0.5.3",
+    "chalk": "^5.5.0",
     "glob": "^11.0.3",
     "open": "^10.2.0",
+    "terminal-link": "^4.0.0",
     "ufo": "^1.6.1",
     "yaml": "^2.8.0"
   },

package/prompts/structure-planning.md

@@ -30,7 +30,7 @@
 <structure_plan_feedback>
 {{ feedback }}
 
-根据最新的 Data Sources 按需要更新节点的 sourceIds。
+根据最新的 Data Sources 按需要更新节点的 sourceIds，如没有大的变化，可以不更新。
 </structure_plan_feedback>
 
 <review_structure_plan>

package/utils/constants.mjs

@@ -58,3 +58,48 @@ export const DEFAULT_EXCLUDE_PATTERNS = [
   "*.log",
   "**/*test.*",
 ];
+
+// Supported languages for documentation
+export const SUPPORTED_LANGUAGES = [
+  { code: "en", label: "English (en)", sample: "Hello" },
+  { code: "zh-CN", label: "简体中文 (zh-CN)", sample: "你好" },
+  { code: "zh-TW", label: "繁體中文 (zh-TW)", sample: "你好" },
+  { code: "ja", label: "日本語 (ja)", sample: "こんにちは" },
+  { code: "ko", label: "한국어 (ko)", sample: "안녕하세요" },
+  { code: "es", label: "Español (es)", sample: "Hola" },
+  { code: "fr", label: "Français (fr)", sample: "Bonjour" },
+  { code: "de", label: "Deutsch (de)", sample: "Hallo" },
+  { code: "pt-BR", label: "Português (pt-BR)", sample: "Olá" },
+  { code: "ru", label: "Русский (ru)", sample: "Привет" },
+  { code: "it", label: "Italiano (it)", sample: "Ciao" },
+  { code: "ar", label: "العربية (ar)", sample: "مرحبا" },
+];
+
+// Predefined document generation styles
+export const DOCUMENT_STYLES = {
+  developerDocs: {
+    name: "Developer Docs",
+    rules: "Steps-first; copy-paste examples; minimal context; active 'you'.",
+  },
+  userGuide: {
+    name: "User Guide",
+    rules: "Scenario-based; step-by-step; plain language; outcomes & cautions.",
+  },
+  apiReference: {
+    name: "API Reference",
+    rules: "Exact & skimmable; schema-first; clear params/errors/examples.",
+  },
+  custom: {
+    name: "Custom Rules",
+    rules: "Enter your own documentation generation rules",
+  },
+};
+
+// Predefined target audiences
+export const TARGET_AUDIENCES = {
+  actionFirst: "Developers, Implementation Engineers, DevOps",
+  conceptFirst:
+    "Architects, Technical Leads, Developers interested in principles",
+  generalUsers: "General Users",
+  custom: "Enter your own target audience",
+};

package/utils/utils.mjs

@@ -1,8 +1,16 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { execSync } from "node:child_process";
-import { existsSync, mkdirSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  accessSync,
+  constants,
+  statSync,
+} from "node:fs";
 import { parse } from "yaml";
+import chalk from "chalk";
 import {
   DEFAULT_INCLUDE_PATTERNS,
   DEFAULT_EXCLUDE_PATTERNS,
@@ -101,6 +109,7 @@ export async function saveDocWithTranslations({
 
     await fs.writeFile(mainFilePath, finalContent, "utf8");
     results.push({ path: mainFilePath, success: true });
+    console.log(chalk.green(`Saved: ${chalk.cyan(mainFilePath)}`));
 
     // Process all translations
     for (const translate of translates) {
@@ -118,6 +127,7 @@ export async function saveDocWithTranslations({
 
       await fs.writeFile(translatePath, finalTranslationContent, "utf8");
       results.push({ path: translatePath, success: true });
+      console.log(chalk.green(`Saved: ${chalk.cyan(translatePath)}`));
     }
   } catch (err) {
     results.push({ path: docPath, success: false, error: err.message });
@@ -394,3 +404,238 @@ export async function saveValueToConfig(key, value) {
     console.warn(`Failed to save ${key} to config.yaml:`, error.message);
   }
 }
+
+/**
+ * Validate if a path exists and is accessible
+ * @param {string} filePath - The path to validate (can be absolute or relative)
+ * @returns {Object} - Validation result with isValid boolean and error message
+ */
+export function validatePath(filePath) {
+  try {
+    const absolutePath = normalizePath(filePath);
+
+    // Check if path exists
+    if (!existsSync(absolutePath)) {
+      return {
+        isValid: false,
+        error: `Path does not exist: ${filePath}`,
+      };
+    }
+
+    // Check if path is accessible (readable)
+    try {
+      accessSync(absolutePath, constants.R_OK);
+    } catch (accessError) {
+      return {
+        isValid: false,
+        error: `Path is not accessible: ${filePath}`,
+      };
+    }
+
+    return {
+      isValid: true,
+      error: null,
+    };
+  } catch (error) {
+    return {
+      isValid: false,
+      error: `Invalid path format: ${filePath}`,
+    };
+  }
+}
+
+/**
+ * Validate multiple paths and return validation results
+ * @param {Array<string>} paths - Array of paths to validate
+ * @returns {Object} - Validation results with validPaths array and errors array
+ */
+export function validatePaths(paths) {
+  const validPaths = [];
+  const errors = [];
+
+  for (const path of paths) {
+    const validation = validatePath(path);
+    if (validation.isValid) {
+      validPaths.push(path);
+    } else {
+      errors.push({
+        path: path,
+        error: validation.error,
+      });
+    }
+  }
+
+  return {
+    validPaths,
+    errors,
+  };
+}
+
+/**
+ * Check if input is a valid directory and add it to results if so
+ * @param {string} searchTerm - The search term to check
+ * @param {Array} results - The results array to modify
+ */
+function addExactDirectoryMatch(searchTerm, results) {
+  const inputValidation = validatePath(searchTerm);
+  if (inputValidation.isValid) {
+    const stats = statSync(normalizePath(searchTerm));
+    if (stats.isDirectory()) {
+      results.unshift({
+        name: searchTerm,
+        value: searchTerm,
+      });
+    }
+  }
+}
+
+/**
+ * Get available paths for search suggestions based on user input
+ * @param {string} userInput - User's input string
+ * @returns {Array<Object>} - Array of path objects with name, value, and description
+ */
+export function getAvailablePaths(userInput = "") {
+  try {
+    const searchTerm = userInput.trim();
+
+    // If no input, return current directory contents
+    if (!searchTerm) {
+      return getDirectoryContents("./");
+    }
+
+    let results = [];
+
+    // Handle absolute paths
+    if (searchTerm.startsWith("/")) {
+      const dirPath = path.dirname(searchTerm);
+      const fileName = path.basename(searchTerm);
+      results = getDirectoryContents(dirPath, fileName);
+      addExactDirectoryMatch(searchTerm, results);
+    }
+    // Handle relative paths
+    else if (searchTerm.startsWith("./") || searchTerm.startsWith("../")) {
+      // Extract directory path and search term
+      const lastSlashIndex = searchTerm.lastIndexOf("/");
+      if (lastSlashIndex === -1) {
+        // No slash found, treat as current directory search
+        results = getDirectoryContents("./", searchTerm);
+        addExactDirectoryMatch(searchTerm, results);
+      } else {
+        const dirPath = searchTerm.substring(0, lastSlashIndex + 1);
+        const fileName = searchTerm.substring(lastSlashIndex + 1);
+
+        // Validate directory path
+        const validation = validatePath(dirPath);
+        if (!validation.isValid) {
+          return [
+            {
+              name: dirPath,
+              value: dirPath,
+              description: validation.error,
+            },
+          ];
+        }
+
+        results = getDirectoryContents(dirPath, fileName);
+        addExactDirectoryMatch(searchTerm, results);
+      }
+    }
+    // Handle simple file/directory names (search in current directory)
+    else {
+      results = getDirectoryContents("./", searchTerm);
+      addExactDirectoryMatch(searchTerm, results);
+    }
+
+    // Remove duplicates based on value (path)
+    const uniqueResults = [];
+    const seenPaths = new Set();
+
+    for (const item of results) {
+      if (!seenPaths.has(item.value)) {
+        seenPaths.add(item.value);
+        uniqueResults.push(item);
+      }
+    }
+
+    return uniqueResults;
+  } catch (error) {
+    console.warn(
+      `Failed to get available paths for "${userInput}":`,
+      error.message
+    );
+    return [];
+  }
+}
+
+/**
+ * Get directory contents for a specific path
+ * @param {string} dirPath - Directory path to search in
+ * @param {string} searchTerm - Optional search term to filter results
+ * @returns {Array<Object>} - Array of path objects
+ */
+function getDirectoryContents(dirPath, searchTerm = "") {
+  try {
+    const absoluteDirPath = normalizePath(dirPath);
+
+    // Check if directory exists
+    if (!existsSync(absoluteDirPath)) {
+      return [
+        {
+          name: dirPath,
+          value: dirPath,
+          description: "Directory does not exist",
+        },
+      ];
+    }
+
+    const items = [];
+
+    // Read directory contents
+    const entries = readdirSync(absoluteDirPath, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const entryName = entry.name;
+      const relativePath = path.join(dirPath, entryName);
+
+      // Filter by search term if provided
+      if (
+        searchTerm &&
+        !entryName.toLowerCase().includes(searchTerm.toLowerCase())
+      ) {
+        continue;
+      }
+
+      // Skip hidden files and common ignore patterns
+      if (
+        entryName.startsWith(".") ||
+        entryName === "node_modules" ||
+        entryName === ".git" ||
+        entryName === "dist" ||
+        entryName === "build"
+      ) {
+        continue;
+      }
+
+      const isDirectory = entry.isDirectory();
+
+      // Only include directories, skip files
+      if (isDirectory) {
+        items.push({
+          name: relativePath,
+          value: relativePath,
+        });
+      }
+    }
+
+    // Sort alphabetically (all items are directories now)
+    items.sort((a, b) => a.name.localeCompare(b.name));
+
+    return items;
+  } catch (error) {
+    console.warn(
+      `Failed to get directory contents from ${dirPath}:`,
+      error.message
+    );
+    return [];
+  }
+}