@aigne/doc-smith 0.8.6 → 0.8.7

package/.aigne/doc-smith/output/structure-plan.json

@@ -136,11 +136,7 @@
     "description": "Understand the built-in checks DocSmith performs to ensure high-quality, well-formatted, and error-free documentation, including link checking and diagram validation.",
     "path": "/advanced/quality-assurance",
     "parentId": "/advanced",
-    "sourceIds": [
-      "utils/markdown-checker.mjs",
-      "utils/mermaid-validator.mjs",
-      "utils/kroki-utils.mjs"
-    ]
+    "sourceIds": ["utils/markdown-checker.mjs", "utils/mermaid-validator.mjs", "utils/d2-utils.mjs"]
   },
   {
     "title": "Changelog",

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.8.7](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.6...v0.9.0) (2025-09-12)
+
+
+### Features
+
+* support defining API parameters with field element ([#104](https://github.com/AIGNE-io/aigne-doc-smith/issues/104)) ([2296ead](https://github.com/AIGNE-io/aigne-doc-smith/commit/2296ead15a00aaf809b3854bf349361f0213f522))
+
 ## [0.8.6](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.5...v0.8.6) (2025-09-11)
 
 

package/README.md

@@ -1,7 +1,7 @@
 [![GitHub star chart](https://img.shields.io/github/stars/AIGNE-io/aigne-doc-smith?style=flat-square)](https://star-history.com/#AIGNE-io/aigne-doc-smith)
 [![Open Issues](https://img.shields.io/github/issues-raw/AIGNE-io/aigne-doc-smith?style=flat-square)](https://github.com/AIGNE-io/aigne-doc-smith/issues)
 [![codecov](https://codecov.io/gh/AIGNE-io/aigne-doc-smith/graph/badge.svg?token=95TQO2NKYC)](https://codecov.io/gh/AIGNE-io/aigne-doc-smith)
-[![NPM Version](https://img.shields.io/npm/v/@aigne/core)](https://www.npmjs.com/package/@aigne/doc-smith)
+[![NPM Version](https://img.shields.io/npm/v/@aigne/doc-smith)](https://www.npmjs.com/package/@aigne/doc-smith)
 
 # AIGNE DocSmith
 
@@ -17,7 +17,7 @@ As shown in the diagram, DocSmith integrates seamlessly with other [AIGNE](https
 
 ## Features
 
-- **Automated Structure Planning:** Intelligently analyzes your codebase to generate a comprehensive and logical document structure.
+- **Automated Generate Document Structure:** Intelligently analyzes your codebase to generate a comprehensive and logical document structure.
 - **AI-Powered Content Generation:** Populates the document structure with detailed, high-quality content.
 - **Multi-Language Support:** Seamlessly translates your documentation into 12 languages including English, Chinese, Japanese, Korean, Spanish, French, German, Portuguese, Russian, Italian, and Arabic.
 - **AIGNE Hub Integration:** Use [AIGNE Hub](https://www.aigne.io/en/hub) as your LLM provider without needing your own API keys, with easy switching between different large language models.
@@ -185,7 +185,7 @@ aigne doc update --docs overview.md --feedback "Add more comprehensive FAQ entri
 
 **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.
 
-#### Optimize Structure Planning
+#### Optimize Document Structure
 
 Improve the overall documentation structure based on feedback:
 

package/agents/{chat.yaml → chat/index.yaml}

@@ -21,10 +21,10 @@ instructions: |
 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
+  - ../init/index.mjs
+  - ../generate/index.yaml
+  - ../update/index.yaml
+  - ../publish/index.yaml
+  - ../translate/index.yaml
+  - ../utils/docs-fs-actor.yaml
+  - ../utils/exit.mjs

package/agents/generate/check-document-structure.yaml

@@ -0,0 +1,30 @@
+name: checkDocumentStructure
+description: Check the Document Structure to ensure it meets expectations, especially in scenarios with previous generation results and user feedback.
+instructions:
+  url: ../../prompts/structure/check-document-structure.md
+input_schema:
+  type: object
+  properties:
+    documentStructure:
+      $ref: ../schema/document-structure.yaml
+      description: Newly generated document structure.
+    originalDocumentStructure:
+      $ref: ../schema/document-structure.yaml
+      description: Previous generation's document structure for comparison. If it doesn't exist, the check passes by default.
+    feedback:
+      type: string
+      description: User feedback provided for the previous generation's results.
+  required:
+    - documentStructure
+output_schema:
+  type: object
+  properties:
+    isValid:
+      type: boolean
+      description: Whether the check passes. true indicates pass, false indicates failure.
+    structureReviewFeedback:
+      type: string
+      description: Detailed explanation of the check results. If it fails, clearly specify which parts do not meet requirements.
+  required:
+    - isValid
+    - structureReviewFeedback

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

@@ -1,25 +1,25 @@
 import { access } from "node:fs/promises";
 import { join } from "node:path";
-import { getActiveRulesForScope } from "../utils/preferences-utils.mjs";
+import { getActiveRulesForScope } from "../../utils/preferences-utils.mjs";
 import {
   getCurrentGitHead,
   getProjectInfo,
   hasFileChangesBetweenCommits,
   loadConfigFromFile,
   saveValueToConfig,
-} from "../utils/utils.mjs";
+} from "../../utils/utils.mjs";
 
-export default async function checkStructurePlan(
-  { originalStructurePlan, feedback, lastGitHead, docsDir, forceRegenerate, ...rest },
+export default async function checkNeedGenerateStructure(
+  { originalDocumentStructure, feedback, lastGitHead, docsDir, forceRegenerate, ...rest },
   options,
 ) {
-  // Check if we need to regenerate structure plan
+  // Check if we need to regenerate document structure
   let shouldRegenerate = false;
   let finalFeedback = feedback;
   let submittedFeedback = feedback;
 
-  // Prompt for feedback if originalStructurePlan exists and no feedback provided
-  if (originalStructurePlan && !feedback) {
+  // Prompt for feedback if originalDocumentStructure exists and no feedback provided
+  if (originalDocumentStructure && !feedback) {
     const userFeedback = await options.prompts.input({
       message: "How can we improve the documentation structure? (press Enter to skip):",
     });
@@ -30,8 +30,8 @@ export default async function checkStructurePlan(
     }
   }
 
-  // If no feedback and originalStructurePlan exists, check for git changes
-  if (originalStructurePlan) {
+  // If no feedback and originalDocumentStructure exists, check for git changes
+  if (originalDocumentStructure) {
     // If no lastGitHead, check if _sidebar.md exists to determine if we should regenerate
     if (!lastGitHead) {
       try {
@@ -78,16 +78,16 @@ export default async function checkStructurePlan(
     `;
   }
 
-  // If no regeneration needed, return original structure plan
-  if (originalStructurePlan && !finalFeedback && !shouldRegenerate) {
+  // If no regeneration needed, return original document structure
+  if (originalDocumentStructure && !finalFeedback && !shouldRegenerate) {
     return {
-      structurePlan: originalStructurePlan,
+      documentStructure: originalDocumentStructure,
     };
   }
 
-  const panningAgent = options.context.agents["structurePlanning"];
+  const panningAgent = options.context.agents["refineDocumentStructure"];
 
-  // Get user preferences for structure planning and global scope
+  // Get user preferences for document structure and global scope
   const structureRules = getActiveRulesForScope("structure", []);
   const globalRules = getActiveRulesForScope("global", []);
 
@@ -100,7 +100,7 @@ export default async function checkStructurePlan(
 
   const result = await options.context.invoke(panningAgent, {
     feedback: finalFeedback || "",
-    originalStructurePlan,
+    originalDocumentStructure,
     userPreferences,
     ...rest,
   });
@@ -155,12 +155,12 @@ export default async function checkStructurePlan(
   return {
     ...result,
     feedback: "", // clear feedback
-    structurePlanFeedback: submittedFeedback,
+    documentStructureFeedback: submittedFeedback,
     projectInfoMessage: message,
-    originalStructurePlan: originalStructurePlan
-      ? originalStructurePlan
-      : JSON.parse(JSON.stringify(result.structurePlan || [])),
+    originalDocumentStructure: originalDocumentStructure
+      ? originalDocumentStructure
+      : JSON.parse(JSON.stringify(result.documentStructure || [])),
   };
 }
 
-checkStructurePlan.taskTitle = "Check if structure plan needs regeneration";
+checkNeedGenerateStructure.taskTitle = "Check if document structure needs generate or update";

package/agents/{structure-planning.yaml → generate/generate-structure.yaml}

@@ -1,7 +1,7 @@
-name: structurePlanGenerator
-description: Plan the structure and organization of your documentation
+name: generateStructure
+description: Generate the structure and organization of your documentation
 instructions:
-  url: ../prompts/structure-planning.md
+  url: ../../prompts/structure/generate-structure.md
 input_schema:
   type: object
   properties:
@@ -13,7 +13,7 @@ input_schema:
       description: Primary language for documentation (e.g., zh, en, ja)
     datasources:
       type: string
-      description: Project content and context to help plan structure
+      description: Project content and context to help generate document structure
     targetAudience:
       type: string
       description: Target audience for the documentation
@@ -45,8 +45,8 @@ output_schema:
     projectDesc:
       type: string
       description: Brief project description generated from content analysis (under 50 words)
-    structurePlan: ./schema/structure-plan.yaml
-    structurePlanTree:
+    documentStructure: ../schema/document-structure.yaml
+    documentStructureTree:
       type: string
       description: |
         Visual tree structure showing documentation hierarchy with indented levels for easy review:

package/agents/{docs-generator.yaml → generate/index.yaml}

@@ -5,15 +5,14 @@ alias:
   - g
 description: Generate complete documentation for your project
 skills:
-  - url: ./input-generator.mjs
+  - url: ../init/index.mjs
     default_input:
       skipIfExists: true
-  - ./load-config.mjs
-  - ./load-sources.mjs
-  - ./check-structure-plan.mjs
-  - url: ./save-output.mjs
+  - ../utils/load-sources.mjs
+  - ./check-need-generate-structure.mjs
+  - url: ../utils/save-output.mjs
     default_input:
-      saveKey: structurePlan
+      saveKey: documentStructure
       savePath:
         $get: outputDir
       fileName: structure-plan.json
@@ -24,7 +23,7 @@ skills:
       $merge([
         $,
         {
-          'structurePlanResult': $map(structurePlan, function($item) {
+          'documentExecutionStructure': $map(documentStructure, function($item) {
             $merge([
               $item,
               {
@@ -35,12 +34,12 @@ skills:
           "datasources": ""
         }
       ])
-  - ./format-structure-plan.mjs
-  - ./batch-docs-detail-generator.yaml
-  - url: ./check-feedback-refiner.mjs
+  - ../utils/format-document-structure.mjs
+  - ../update/batch-generate-document.yaml
+  - url: ../utils/check-feedback-refiner.mjs
     default_input:
-      stage: structure_planning
-  - ./save-docs.mjs
+      stage: document_structure
+  - ../utils/save-docs.mjs
 
 input_schema:
   type: object

package/agents/generate/refine-document-structure.yaml

@@ -0,0 +1,12 @@
+type: team
+name: refineDocumentStructure
+description: A team of agents that generate the structure of the documentation.
+skills:
+  - generate-structure.yaml
+task_title: Generate the structure of the documentation
+task_render_mode: collapse
+reflection:
+  reviewer: check-document-structure.yaml
+  is_approved: isValid
+  max_iterations: 3
+  return_last_on_max_iterations: true

package/agents/{input-generator.mjs → init/index.mjs}

@@ -2,7 +2,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 } from "../utils/conflict-detector.mjs";
+import { getFilteredOptions } from "../../utils/conflict-detector.mjs";
 import {
   DEPTH_RECOMMENDATION_LOGIC,
   DOCUMENT_STYLES,
@@ -11,14 +11,15 @@ import {
   READER_KNOWLEDGE_LEVELS,
   SUPPORTED_LANGUAGES,
   TARGET_AUDIENCES,
-} from "../utils/constants.mjs";
+} from "../../utils/constants.mjs";
+import loadConfig from "../../utils/load-config.mjs";
 import {
   detectSystemLanguage,
   getAvailablePaths,
   getProjectInfo,
   isGlobPattern,
   validatePath,
-} from "../utils/utils.mjs";
+} from "../../utils/utils.mjs";
 
 // UI constants
 const _PRESS_ENTER_TO_FINISH = "Press Enter to finish";
@@ -31,7 +32,7 @@ const _PRESS_ENTER_TO_FINISH = "Press Enter to finish";
  * @returns {Promise<Object>}
  */
 export default async function init(
-  { outputPath = ".aigne/doc-smith", fileName = "config.yaml", skipIfExists = false },
+  { outputPath = ".aigne/doc-smith", fileName = "config.yaml", skipIfExists = false, appUrl },
   options,
 ) {
   if (skipIfExists) {
@@ -39,7 +40,8 @@ export default async function init(
     const configContent = await readFile(filePath, "utf8").catch(() => null);
     // Only skip if file exists AND has non-empty content
     if (configContent && configContent.trim() !== "") {
-      return {};
+      // load config from file
+      return loadConfig({ config: filePath, appUrl });
     }
   }
 
@@ -340,6 +342,11 @@ export default async function init(
     console.log("💡 You can edit the configuration file anytime to modify settings.\n");
     console.log(`🚀 Ready to generate docs? Run: ${chalk.cyan("aigne doc generate")}\n`);
 
+    // load config from file
+    if (skipIfExists) {
+      return loadConfig({ config: filePath, appUrl });
+    }
+
     return {};
   } catch (error) {
     console.error(`❌ Failed to save configuration file: ${error.message}`);

package/agents/{manage-prefs.mjs → prefs/index.mjs}

@@ -1,4 +1,4 @@
-import { readPreferences, removeRule, writePreferences } from "../utils/preferences-utils.mjs";
+import { readPreferences, removeRule, writePreferences } from "../../utils/preferences-utils.mjs";
 
 /**
  * List all user preferences with formatted display

package/agents/{team-publish-docs.yaml → publish/index.yaml}

@@ -5,10 +5,9 @@ alias:
   - p
 description: Publish your documentation online
 skills:
-  - url: ./input-generator.mjs
+  - url: ../init/index.mjs
     default_input:
       skipIfExists: true
-  - load-config.mjs
   - publish-docs.mjs
 input_schema:
   type: object

package/agents/{publish-docs.mjs → publish/publish-docs.mjs}

@@ -1,13 +1,14 @@
 import { basename, join } from "node:path";
+
 import { publishDocs as publishDocsFn } from "@aigne/publish-docs";
 import chalk from "chalk";
 import fs from "fs-extra";
 
-import { getAccessToken } from "../utils/auth-utils.mjs";
-import { DISCUSS_KIT_STORE_URL, TMP_DIR, TMP_DOCS_DIR } from "../utils/constants.mjs";
-import { deploy } from "../utils/deploy.mjs";
-import { beforePublishHook, ensureTmpDir } from "../utils/kroki-utils.mjs";
-import { getGithubRepoUrl, loadConfigFromFile, saveValueToConfig } from "../utils/utils.mjs";
+import { getAccessToken } from "../../utils/auth-utils.mjs";
+import { DISCUSS_KIT_STORE_URL, TMP_DIR, TMP_DOCS_DIR } from "../../utils/constants.mjs";
+import { beforePublishHook, ensureTmpDir } from "../../utils/d2-utils.mjs";
+import { deploy } from "../../utils/deploy.mjs";
+import { getGithubRepoUrl, loadConfigFromFile, saveValueToConfig } from "../../utils/utils.mjs";
 
 const DEFAULT_APP_URL = "https://docsmith.aigne.io";
 

package/agents/schema/{structure-plan-result.yaml → document-execution-structure.yaml}

@@ -8,7 +8,7 @@ items:
       type: string
     path:
       type: string
-      description: 路径，以 RUL 的格式返回，不能为空, 必须以 / 开头，不需要包含语言层级，比如 /zh/about 直接返回 /about
+      description: Path in URL format, cannot be empty, must start with /, no need to include language level, e.g., /zh/about should return /about
     parentId:
       type:
         - string
@@ -20,12 +20,12 @@ items:
         properties:
           language:
             type: string
-            description: 语言代码，比如 zh, en, ja 等
+            description: Language code, such as zh, en, ja, etc.
     sourceIds:
       type: array
       items:
         type: string
-      description: 关联的 dataSources 中的 sourceId，用于后续的翻译和内容生成，必须来自 datasources 中的 sourceId，不能有虚假的 id, 不能为空
+      description: Associated sourceId from dataSources for subsequent translation and content generation, must come from sourceId in datasources, cannot have fake ids, cannot be empty
   required:
     - title
     - description

package/agents/schema/document-structure.yaml

@@ -0,0 +1,26 @@
+type: array
+items:
+  type: object
+  properties:
+    title:
+      type: string
+    description:
+      type: string
+    path:
+      type: string
+      description: Path in URL format, cannot be empty, cannot contain spaces or special characters, must start with /, no need to include language level, e.g., /zh/about should return /about
+    parentId:
+      type:
+        - string
+        - "null"
+      description: Parent node path, if null indicates it is a top-level node
+    sourceIds:
+      type: array
+      description: Associated sourceId from dataSources for subsequent translation and content generation, must come from sourceId in datasources, cannot have fake ids, **cannot be empty**
+      items:
+        type: string
+  required:
+    - title
+    - description
+    - path
+    - sourceIds

package/agents/{language-selector.mjs → translate/choose-language.mjs}

@@ -1,5 +1,5 @@
-import { SUPPORTED_LANGUAGES } from "../utils/constants.mjs";
-import { loadConfigFromFile, saveValueToConfig } from "../utils/utils.mjs";
+import { SUPPORTED_LANGUAGES } from "../../utils/constants.mjs";
+import { loadConfigFromFile, saveValueToConfig } from "../../utils/utils.mjs";
 
 /**
  * Interactive language selector for translation from configured languages
@@ -9,7 +9,7 @@ import { loadConfigFromFile, saveValueToConfig } from "../utils/utils.mjs";
  * @param {Object} options - Options object with prompts
  * @returns {Promise<Object>} Selected languages
  */
-export default async function languageSelector({ langs, locale, selectedDocs }, options) {
+export default async function chooseLanguage({ langs, locale, selectedDocs }, options) {
   let selectedLanguages = [];
 
   // Load existing config to get current translation languages
@@ -19,7 +19,7 @@ export default async function languageSelector({ langs, locale, selectedDocs },
   // Get primary language from config or parameter
   const primaryLanguage = locale || existingConfig?.locale || "en";
 
-  // Filter out the primary language from available choices (like input-generator.mjs)
+  // Filter out the primary language from available choices (like init.mjs)
   const availableTranslationLanguages = SUPPORTED_LANGUAGES.filter(
     (lang) => lang.code !== primaryLanguage,
   );
@@ -90,7 +90,7 @@ export default async function languageSelector({ langs, locale, selectedDocs },
   };
 }
 
-languageSelector.input_schema = {
+chooseLanguage.input_schema = {
   type: "object",
   properties: {
     langs: {

package/agents/{retranslate.yaml → translate/index.yaml}

@@ -2,19 +2,18 @@ type: team
 name: translate
 description: Translate documents into other languages
 skills:
-  - url: ./input-generator.mjs
+  - url: ../init/index.mjs
     default_input:
       skipIfExists: true
-  - ./load-config.mjs
-  - ./load-sources.mjs
+  - ../utils/load-sources.mjs
   - type: transform
     task_render_mode: hide
     jsonata: |
       $merge([
         $,
         {
-          'structurePlan': originalStructurePlan,
-          'structurePlanResult': $map(originalStructurePlan, function($item) {
+          'documentStructure': originalDocumentStructure,
+          'documentExecutionStructure': $map(originalDocumentStructure, function($item) {
             $merge([
               $item,
               {
@@ -24,23 +23,23 @@ skills:
           })
         }
       ])
-  - url: ./find-items-by-paths.mjs
+  - url: ../utils/choose-docs.mjs
     default_input:
       isTranslate: true
-  - ./language-selector.mjs
+  - ../translate/choose-language.mjs
   - type: team
-    name: batchDocsTranslate
+    name: batchTranslateDocument
     skills:
-      - ./batch-translate.yaml
-      - url: ./save-single-doc.mjs
+      - ../translate/translate-multilingual.yaml
+      - url: ../utils/save-single-doc.mjs
         default_input:
           isTranslate: true
     iterate_on: selectedDocs
     concurrency: 3
-  - url: ./check-feedback-refiner.mjs
+  - url: ../utils/check-feedback-refiner.mjs
     default_input:
       stage: translation_refine
-  - url: ./action-success.mjs
+  - url: ../utils/action-success.mjs
     default_input:
       action: "✅ Translation completed"
 input_schema:

package/agents/{translate.yaml → translate/translate-document.yaml}

@@ -1,7 +1,8 @@
-name: translateDoc
+name: translateDocument
 description: Translate content to another language
 instructions:
-  url: ../prompts/translator.md
+  url: ../../prompts/translate/translate-document.md
+task_render_mode: collapse
 input_schema:
   type: object
   properties:

package/agents/{batch-translate.yaml → translate/translate-multilingual.yaml}

@@ -1,15 +1,15 @@
 type: team
-name: batchTranslate
-description: 批量翻译文档到多个语言
+name: translateMultilingual
+description: Batch translate documents to multiple languages
 skills:
   - type: team
     task_render_mode: collapse
     name: translate
     skills:
-      - url: ./find-user-preferences-by-path.mjs
+      - url: ../utils/find-user-preferences-by-path.mjs
         default_input:
           scope: translation
-      - ./translate.yaml
+      - ../translate/translate-document.yaml
       - type: transform
         jsonata: |
           $merge([
@@ -17,7 +17,7 @@ skills:
             { "reviewContent": translation }
           ])
     reflection:
-      reviewer: ./check-detail-result.mjs
+      reviewer: ../utils/check-detail-result.mjs
       is_approved: isApproved
       max_iterations: 5
       return_last_on_max_iterations: true

package/agents/update/batch-generate-document.yaml

@@ -0,0 +1,19 @@
+type: team
+name: batchGenerateDocument
+description: Batch generate document details
+skills:
+  - ./check-document.mjs
+input_schema:
+  type: object
+  properties:
+    datasources:
+      type: string
+      description: Context for document structure generation, used to assist generate document structure
+    documentExecutionStructure: ../schema/document-execution-structure.yaml
+    modifiedFiles:
+      type: array
+      items: { type: string }
+      description: Array of modified files since last generation
+iterate_on: documentExecutionStructure
+concurrency: 3
+mode: sequential