@aigne/doc-smith 0.8.15-beta.8 → 0.8.15

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## [0.8.15](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.16...v0.8.15) (2025-11-07)
+
+## [0.8.15-beta.16](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.15...v0.8.15-beta.16) (2025-11-07)
+
+
+### Features
+
+* support customize diagramming quantity ([#277](https://github.com/AIGNE-io/aigne-doc-smith/issues/277)) ([9d9fa6a](https://github.com/AIGNE-io/aigne-doc-smith/commit/9d9fa6a1f344c93df187f2dc502c5479e304e0f4))
+
+## [0.8.15-beta.15](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.14...v0.8.15-beta.15) (2025-11-07)
+
+
+### Bug Fixes
+
+* add two-tier thinking effort configuration system ([#273](https://github.com/AIGNE-io/aigne-doc-smith/issues/273)) ([b72d066](https://github.com/AIGNE-io/aigne-doc-smith/commit/b72d066698bae253a9ee2dfa231bf73cd59d7529))
+
+## [0.8.15-beta.14](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.13...v0.8.15-beta.14) (2025-11-06)
+
+
+### Features
+
+* add reasoning effort configuration for customizable AI model settings ([#270](https://github.com/AIGNE-io/aigne-doc-smith/issues/270)) ([9f15638](https://github.com/AIGNE-io/aigne-doc-smith/commit/9f156387120e8705bf16cf611d7f8f39995c36b3))
+* **cli:** enhance auth with short link responses and detailed error reporting for publishing ([#269](https://github.com/AIGNE-io/aigne-doc-smith/issues/269)) ([31cc252](https://github.com/AIGNE-io/aigne-doc-smith/commit/31cc25236667236dfe91543acdd7e8cccff659c5))
+
+
+### Bug Fixes
+
+* use default reasoning effort for existing config ([#272](https://github.com/AIGNE-io/aigne-doc-smith/issues/272)) ([2fc9c89](https://github.com/AIGNE-io/aigne-doc-smith/commit/2fc9c89e383c1c5446f2109a2846e831d1e1e871))
+
+## [0.8.15-beta.13](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.12...v0.8.15-beta.13) (2025-11-05)
+
+
+### Bug Fixes
+
+* make paid deployment more smooth stable ([#266](https://github.com/AIGNE-io/aigne-doc-smith/issues/266)) ([ce8c00a](https://github.com/AIGNE-io/aigne-doc-smith/commit/ce8c00ab3eb045c482e07dc3c4e3bd149e754a06))
+* validate docsDir on init and ensure latest doc on view after publish ([#267](https://github.com/AIGNE-io/aigne-doc-smith/issues/267)) ([e45864d](https://github.com/AIGNE-io/aigne-doc-smith/commit/e45864da4a7fb5b09af2bbffdb7ca93abd74397c))
+
+## [0.8.15-beta.12](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.11...v0.8.15-beta.12) (2025-11-05)
+
+
+### Features
+
+* tune token consumption for update ops with intent analysis ([#264](https://github.com/AIGNE-io/aigne-doc-smith/issues/264)) ([8c53d28](https://github.com/AIGNE-io/aigne-doc-smith/commit/8c53d288346ae622e8841866db1b6fbed9d5023d))
+
+## [0.8.15-beta.11](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.10...v0.8.15-beta.11) (2025-11-04)
+
+
+### Features
+
+* warn on invalid sources and tuning translate messages ([#241](https://github.com/AIGNE-io/aigne-doc-smith/issues/241)) ([bd786ca](https://github.com/AIGNE-io/aigne-doc-smith/commit/bd786cad8b0c6fa837511fdc2982c83b7f0095dd))
+
+
+### Bug Fixes
+
+* avoid useless diagram generate ([#245](https://github.com/AIGNE-io/aigne-doc-smith/issues/245)) ([de7600f](https://github.com/AIGNE-io/aigne-doc-smith/commit/de7600fb5839be9d1f0743adc34fd08c4c11729d))
+* iterate on chunk of datasource to generate structure ([#242](https://github.com/AIGNE-io/aigne-doc-smith/issues/242)) ([0b4db2a](https://github.com/AIGNE-io/aigne-doc-smith/commit/0b4db2a8cac77d6f4a1c197374b9dadbe078346b))
+
+## [0.8.15-beta.10](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.9...v0.8.15-beta.10) (2025-11-03)
+
+
+### Bug Fixes
+
+* remove empty xml tag in prompt ([#239](https://github.com/AIGNE-io/aigne-doc-smith/issues/239)) ([1ec771e](https://github.com/AIGNE-io/aigne-doc-smith/commit/1ec771eb8855bca3730f732a1b68404275633787))
+* standardized variable names and xml tag usage ([#237](https://github.com/AIGNE-io/aigne-doc-smith/pull/237))([00f18b9](https://github.com/AIGNE-io/aigne-doc-smith/commit/00f18b95ba21cd376e369eefb102d2d258e95529))
+
+## [0.8.15-beta.9](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.8...v0.8.15-beta.9) (2025-11-03)
+
+
+### Bug Fixes
+
+* optimize the draw diagram process ([#234](https://github.com/AIGNE-io/aigne-doc-smith/issues/234)) ([7bdc0d9](https://github.com/AIGNE-io/aigne-doc-smith/commit/7bdc0d939df05b9d31e06ea0f0285ed0eafe74ae))
+* simplify document structure merging and add deletion support ([#235](https://github.com/AIGNE-io/aigne-doc-smith/issues/235)) ([7f10242](https://github.com/AIGNE-io/aigne-doc-smith/commit/7f1024294bde241f41034d3e01a542451030cbdc))
+
 ## [0.8.15-beta.8](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.7...v0.8.15-beta.8) (2025-11-01)
 
 

package/agents/evaluate/document-structure.yaml

@@ -2,7 +2,9 @@ name: evaluateDocumentStructure
 description: Evaluates the results generated by the document-structure agent to ensure they meet expectations, especially in scenarios with previous generation results and user feedback.
 instructions:
   url: ../../prompts/evaluate/document-structure.md
-model: openai/gpt-5
+model:
+  model: openai/gpt-5
+  temperature: 1
 # model: anthropic/claude-opus-4-0
 task_render_mode: collapse
 task_title: Evaluate the structure of the documentation

package/agents/evaluate/document.yaml

@@ -2,7 +2,9 @@ name: evaluateDocument
 description: Evaluates the quality of generated document content, ensuring compliance with user-configured goals, audiences, and knowledge level requirements.
 instructions:
   url: ../../prompts/evaluate/document.md
-model: openai/gpt-5
+model:
+  model: openai/gpt-5
+  temperature: 1
 # model: anthropic/claude-opus-4-0
 task_render_mode: collapse
 task_title: Evaluate document for '{{ title }}'

package/agents/evaluate/index.yaml

@@ -16,9 +16,7 @@ skills:
       $merge([
         $,
         {
-          "documentStructure": originalDocumentStructure,
-          "datasources": "",
-          "datasourcesList": ""
+          "documentStructure": originalDocumentStructure
         }
       ])
   - ./document-structure.yaml

package/agents/generate/check-diagram.mjs

@@ -9,7 +9,7 @@ export default async function checkD2DiagramIsValid({ diagramSourceCode }) {
   } catch (err) {
     return {
       isValid: false,
-      error: err.message,
+      diagramError: err.message,
     };
   }
 }

package/agents/generate/generate-structure.yaml

@@ -4,11 +4,9 @@ description: Generate the structure and organization of your documentation
 skills:
   - type: team
     name: generateStructureWorker
-    iterate_on: datasources
+    iterate_on: dataSources
     skills:
       - type: ai
-        model:
-          reasoning_effort: 500
         instructions:
           - role: system
             url: ../../prompts/structure/generate/system-prompt.md
@@ -26,7 +24,7 @@ skills:
             locale:
               type: string
               description: Primary language for documentation (e.g., zh, en, ja)
-            datasources:
+            dataSourceChunk:
               type: string
               description: Project content and context to help generate documentation structure
             targetAudience:
@@ -50,7 +48,7 @@ skills:
               default: general
           required:
             - rules
-            - datasources
+            - dataSourceChunk
         output_schema:
           type: object
           properties:
@@ -60,31 +58,10 @@ skills:
             projectDesc:
               type: string
               description: Brief project description generated from content analysis (under 50 words)
-            add:
+            structures:
               type: array
-              description: List of document structure items to add, null or empty array means no addition
-              items:
-                type: object
-                properties:
-                  index:
-                    type: integer
-                    description: Position to insert the new item, null means append to the end
-                  item: ../schema/document-structure-item.yaml
-                required:
-                  - item
-            update:
-              type: array
-              description: List of document structure items to update, replace the item with the same path, null or empty array means no update
-              items:
-                type: object
-                properties:
-                  path:
-                    type: string
-                    description: Path of the document structure item to update or replace
-                  item: ../schema/document-structure-item.yaml
-                required:
-                  - path
-                  - item
+              description: List of document structure items to add or update
+              items: ../schema/document-structure-item.yaml
 
       - ./utils/merge-document-structures.mjs
 
@@ -92,9 +69,10 @@ skills:
     name: aggregateDocumentStructure
     process: |
       return {
-        documentStructure: options.context.userContext.originalDocumentStructure.map(i => ({
+        documentStructure: options.context.userContext.originalDocumentStructure.map((i, index) => ({
           ...i,
           id: i.title.toLowerCase().replace(/\s+/g, '-'),
+          index
         })),
         projectName: options.context.userContext.projectName,
         projectDesc: options.context.userContext.projectDesc,
@@ -102,37 +80,18 @@ skills:
 
   - type: ai
     name: refineStructure
-    model:
-      reasoning_effort: 500
     instructions:
       - role: system
         url: ../../prompts/structure/review/structure-review-system.md
     output_schema:
       type: object
       properties:
-        refinedStructure:
+        structures:
           type: array
-          description: Optimized document structure array
-          items:
-            type: object
-            description: Document structure item representing a node in the document hierarchy
-            properties:
-              id:
-                type: string
-                description: Unique identifier for the document structure item
-              newIndex:
-                type: integer
-                description: Used for ordering purposes, indicates the new position index of the document structure item
-              newPath:
-                type: string
-                description: The new path of the document structure item if it has been changed, otherwise can be omitted
-              newParentPath:
-                type: string
-                description: The new parentPath of the document structure item if it has been changed, otherwise can be omitted
-            required:
-              - id
+          description: Document structure items that need to be updated or changed
+          items: ../schema/document-structure-refine-item.yaml
       required:
-        - refinedStructure
+        - structures
 
   - type: function
     name: finalizeDocumentStructure
@@ -140,23 +99,18 @@ skills:
       return {
         projectName: input.projectName,
         projectDesc: input.projectDesc,
-        documentStructure: input.documentStructure
-          .map((item) => {
-            const refined = input.refinedStructure?.find(i => i.id === item.id)
+        documentStructure: input.structures.map(refinedItem => {
+          // Find original item to get sourceIds and other fields
+          const originalItem = input.documentStructure.find(orig => orig.id === refinedItem.id)
+
+          const newItem = {
+            title: refinedItem.title,
+            description: refinedItem.description,
+            path: refinedItem.path,
+            parentId: refinedItem.parentPath || null,  // Convert parentPath to parentId
+            sourceIds: originalItem?.sourceIds || [],
+          }
 
-            return {
-              ...item,
-              index: refined?.newIndex || item.index,
-              path: refined?.newPath || item.path,
-              parentId: refined?.newParentPath || item.parentPath,
-            }
-          })
-          .sort((a, b) => a.index - b.index)
-          .map(i => {
-            const newItem = { ...i }
-            delete newItem.index
-            delete newItem.id
-            delete newItem.parentPath
-            return newItem
-          }),
+          return newItem
+        })
       }

package/agents/generate/index.yaml

@@ -38,8 +38,7 @@ skills:
                 'translates': [$map(translateLanguages, function($lang) { {"language": $lang} })]
               }
             ])
-          }),
-          "datasources": ""
+          })
         }
       ])
   - ../utils/format-document-structure.mjs

package/agents/generate/{merge-d2-diagram.yaml → merge-diagram.yaml}

@@ -1,14 +1,15 @@
-name: mergeD2DiagramToDocument
-description: Merge D2 Diagram source code into document
+name: mergeDiagramToDocument
+description: Merge Diagram source code into document
 instructions: |
   You are an AI assistant that helps to merge d2 diagram into document.
 
-  <datasources>
+  <detail_data_source>
   {{ content }}
-  </datasources>
-  <datasources>
+  </detail_data_source>
+
+  <diagram_source_code>
   {{ diagramSourceCode }}
-  </datasources>
+  </diagram_source_code>
 
   Given the source content of a document and the D2 diagram source code, your task is to:
   - **Keep the original content as soon as possible.**

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

@@ -1,48 +1,54 @@
-type: ai
+type: team
 name: updateDocumentStructure
 description: Update documentation structure based on user feedback and intentions using structure modification tools
-instructions:
-  - role: system
-    url: ../../prompts/structure/update/system-prompt.md
-  - role: user
-    url: ../../prompts/structure/update/user-prompt.md
-input_schema:
-  type: object
-  properties:
-    documentStructure: ../schema/document-structure.yaml
-    rules:
-      type: string
-      description: User configuration rules
-    locale:
-      type: string
-      description: User language, e.g. zh, en
-    datasources:
-      type: string
-      description: Context for documentation structure
-    glossary:
-      type: string
-      description: Glossary of terms
-    feedback:
-      type: string
-      description: User feedback for structure modifications
-    userPreferences:
-      type: string
-      description: Your saved preferences for structure and documentation style
-  required:
-    - documentStructure
-    - feedback
-output_key: message
-afs:
-  modules:
-    - module: system-fs
-      options:
-        mount: /sources
-        path: .
-        description: |
-          Codebase of the project to be documented used as context for document generation,
-          should search and read as needed while generating document content
 skills:
-  - ./document-structure-tools/add-document.mjs
-  - ./document-structure-tools/delete-document.mjs
-  - ./document-structure-tools/update-document.mjs
-  - ./document-structure-tools/move-document.mjs
+  - url: ../utils/analyze-feedback-intent.yaml
+  - type: ai
+    instructions:
+      - role: system
+        url: ../../prompts/structure/update/system-prompt.md
+      - role: user
+        url: ../../prompts/structure/update/user-prompt.md
+    input_schema:
+      type: object
+      properties:
+        documentStructure: ../schema/document-structure.yaml
+        rules:
+          type: string
+          description: User configuration rules
+        locale:
+          type: string
+          description: User language, e.g. zh, en
+        dataSourceChunk:
+          type: string
+          description: Context for documentation structure
+        glossary:
+          type: string
+          description: Glossary of terms
+        feedback:
+          type: string
+          description: User feedback for structure modifications
+        userPreferences:
+          type: string
+          description: Your saved preferences for structure and documentation style
+        needDataSources:
+          type: boolean
+          description: Whether data sources are needed for content modifications
+      required:
+        - documentStructure
+        - feedback
+    output_key: message
+    afs:
+      modules:
+        - module: system-fs
+          options:
+            mount: /sources
+            path: .
+            description: |
+              Codebase of the project to be documented used as context for document generation,
+              should search and read as needed while generating document content
+    skills:
+      - ./document-structure-tools/add-document.mjs
+      - ./document-structure-tools/delete-document.mjs
+      - ./document-structure-tools/update-document.mjs
+      - ./document-structure-tools/move-document.mjs

package/agents/generate/user-review-document-structure.mjs

@@ -1,32 +1,9 @@
 import { getActiveRulesForScope } from "../../utils/preferences-utils.mjs";
 import { recordUpdate } from "../../utils/history-utils.mjs";
+import { buildDocumentTree } from "../../utils/docs-finder-utils.mjs";
 
 function formatDocumentStructure(structure) {
-  // Create a map of nodes for easy lookup
-  const nodeMap = new Map();
-  const rootNodes = [];
-
-  // First pass: create node map
-  structure.forEach((node) => {
-    nodeMap.set(node.path, {
-      ...node,
-      children: [],
-    });
-  });
-
-  // Build the tree structure
-  structure.forEach((node) => {
-    if (node.parentId) {
-      const parent = nodeMap.get(node.parentId);
-      if (parent) {
-        parent.children.push(nodeMap.get(node.path));
-      } else {
-        rootNodes.push(nodeMap.get(node.path));
-      }
-    } else {
-      rootNodes.push(nodeMap.get(node.path));
-    }
-  });
+  const { rootNodes } = buildDocumentTree(structure);
 
   function printNode(node, depth = 0) {
     const INDENT_SPACES = "  ";
@@ -140,7 +117,7 @@ export default async function userReviewDocumentStructure({ documentStructure, .
       // Call refineDocumentStructure agent with feedback
       await options.context.invoke(refineAgent, {
         ...rest,
-        datasources: rest.datasources[0].datasources,
+        dataSourceChunk: rest.dataSources[0].dataSourceChunk,
         feedback: feedback.trim(),
         documentStructure: currentStructure,
         userPreferences,

package/agents/generate/utils/merge-document-structures.mjs

@@ -11,44 +11,20 @@ export default async function mergeDocumentStructures(input, options) {
 
   options.context.userContext.originalDocumentStructure ??= [];
 
-  const structure = options.context.userContext.originalDocumentStructure;
+  const originalStructures = [...options.context.userContext.originalDocumentStructure];
 
-  if (input.add) {
-    for (const { index, item } of input.add) {
-      if (index != null && index >= 0 && index < structure.length) {
-        structure.splice(index, 0, item);
+  if (input.structures) {
+    for (const item of input.structures) {
+      const index = originalStructures.findIndex((s) => s.path === item.path);
+      if (index !== -1) {
+        originalStructures[index] = item;
       } else {
-        structure.push(item);
+        originalStructures.push(item);
       }
     }
   }
 
-  if (input.update) {
-    for (const upd of input.update) {
-      const idx = structure.findIndex((i) => i.path === upd.path);
-      if (idx !== -1) {
-        structure[idx] = upd.item;
-      }
-    }
-  }
-
-  if (input.delete) {
-    for (const del of input.delete) {
-      const idx = structure.findIndex((i) => i.path === del.path);
-      if (idx !== -1) {
-        structure.splice(idx, 1);
-      }
-    }
-  }
-
-  options.context.userContext.originalDocumentStructure = structure.map((i, index) => {
-    delete i.index;
-
-    return {
-      index,
-      ...i,
-    };
-  });
+  options.context.userContext.originalDocumentStructure = originalStructures;
 
   return {};
 }

package/agents/init/check.mjs

@@ -6,7 +6,7 @@ export default async function checkNeedGenerate({ docsDir, locale, documentExecu
 
   if (mainLanguageFiles.length === 0) {
     console.log(
-      `No documents found in the docs directory. Please run ${chalk.yellow("`aigne doc generate`")} to generate the documents`,
+      `No documents found in the docs directory. You can generate them with ${chalk.yellow("`aigne doc generate`")}`,
     );
     process.exit(0);
   }

package/agents/init/index.mjs

@@ -4,6 +4,8 @@ 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,
@@ -21,6 +23,8 @@ import {
   validatePath,
 } from "../../utils/utils.mjs";
 import { isRemoteFile } from "../../utils/file-utils.mjs";
+import { validateDocDir } from "./validate.mjs";
+import mapReasoningEffortLevel from "../utils/map-reasoning-effort-level.mjs";
 
 const _PRESS_ENTER_TO_FINISH = "Press Enter to finish";
 
@@ -31,7 +35,23 @@ const _PRESS_ENTER_TO_FINISH = "Press Enter to finish";
  * @param {string} params.fileName - The name of the file.
  * @returns {Promise<Object>}
  */
-export default async function init(
+export default async function init(input, options) {
+  const config = await _init(input, options);
+
+  // Set thinking effort (lite/standard/pro) and map to reasoningEffort
+  options.context.userContext.thinkingEffort =
+    config.thinking?.effort || DEFAULT_THINKING_EFFORT_LEVEL;
+
+  // Set global reasoningEffort based on thinkingEffort
+  options.context.userContext.reasoningEffort = mapReasoningEffortLevel(
+    { level: DEFAULT_REASONING_EFFORT_LEVEL },
+    options,
+  )?.reasoningEffort;
+
+  return config;
+}
+
+async function _init(
   {
     outputPath = ".aigne/doc-smith",
     fileName = "config.yaml",
@@ -64,7 +84,19 @@ export default async function init(
     // Only skip if file exists AND has non-empty content
     if (configContent && configContent.trim() !== "") {
       // load config from file
-      return loadConfig({ config: filePath, appUrl });
+      const config = await loadConfig({ config: filePath, appUrl });
+      const isValid = validateDocDir(config.docsDir);
+      if (typeof isValid === "string") {
+        console.log(
+          `${chalk.red("Invalid docsDir")}: ${isValid}\nPlease check your configuration.`,
+        );
+        process.exit(1);
+      }
+      if (!isValid) {
+        console.log(`${chalk.red("Invalid docsDir")}, please check your configuration.`);
+        process.exit(1);
+      }
+      return config;
     }
   }
 
@@ -241,6 +273,7 @@ export default async function init(
   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`;
 
@@ -424,6 +457,10 @@ export function generateYAML(input) {
     projectDesc: input.projectDesc || "",
     projectLogo: input.projectLogo || "",
 
+    thinking: {
+      effort: input.thinking?.effort || DEFAULT_THINKING_EFFORT_LEVEL,
+    },
+
     // Documentation configuration
     documentPurpose: input.documentPurpose || [],
     targetAudienceTypes: input.targetAudienceTypes || [],
@@ -459,6 +496,19 @@ export function generateYAML(input) {
 
   yaml += `${projectSection}\n\n`;
 
+  const modelSection = yamlStringify({
+    thinking: config.thinking,
+  }).trim();
+
+  yaml += `\
+# AI Thinking Configuration
+# thinking.effort: Determines the depth of reasoning and cognitive effort the AI uses when responding, available options:
+#   - lite: Fast responses with basic reasoning
+#   - standard: Balanced speed and reasoning capability
+#   - pro: In-depth reasoning with longer response times
+${modelSection}
+\n`;
+
   // Add documentation configuration with comments
   yaml += "# =============================================================================\n";
   yaml += "# Documentation Configuration\n";

package/agents/init/validate.mjs

@@ -0,0 +1,16 @@
+import path from "node:path";
+export function validateDocDir(input) {
+  const currentDir = process.cwd();
+  const targetDir = path.resolve(input);
+  const relativePath = path.relative(currentDir, targetDir);
+  if (relativePath.length === 0) {
+    return `Can't use current directory: ${targetDir}`;
+  }
+  if (relativePath.startsWith("..")) {
+    return `Can't use directory outside current directory: ${targetDir}`;
+  }
+  if (path.isAbsolute(relativePath)) {
+    return `Can't use absolute path: ${targetDir}`;
+  }
+  return true;
+}