@aigne/doc-smith 0.8.15-beta.9 → 0.8.16-beta

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;
+}

package/agents/publish/publish-docs.mjs

@@ -163,8 +163,13 @@ export default async function publishDocs(
           } else {
             console.log(`\nCreating a new website for your documentation...`);
           }
-          const { appUrl: homeUrl, token: ltToken } = (await deploy(id, paymentLink)) || {};
+          const {
+            appUrl: homeUrl,
+            token: ltToken,
+            sessionId: newSessionId,
+          } = (await deploy(id, paymentLink)) || {};
 
+          sessionId = newSessionId;
           appUrl = homeUrl;
           token = ltToken;
         } catch (error) {
@@ -174,13 +179,7 @@ export default async function publishDocs(
       }
     }
 
-    if (sessionId) {
-      authToken = await getOfficialAccessToken(BASE_URL, false);
-      client = client || new BrokerClient({ baseUrl: BASE_URL, authToken });
-
-      const { vendors } = await client.getSessionDetail(sessionId, false);
-      token = vendors?.find((vendor) => vendor.vendorType === "launcher" && vendor.token)?.token;
-    }
+    appUrl = appUrl ?? CLOUD_SERVICE_URL_PROD;
 
     console.log(`\nPublishing your documentation to ${chalk.cyan(appUrl)}\n`);
 
@@ -264,8 +263,15 @@ export default async function publishDocs(
       await saveValueToConfig("shouldSyncBranding", "", "Should sync branding for documentation");
     } else {
       // If the error is 401 or 403, it means the access token is invalid
-      if (error?.includes("401") || error?.includes("403")) {
-        message = `❌ Publishing failed due to an authorization error. Please run ${chalk.cyan("aigne doc clear")} to reset your credentials and try again.`;
+      try {
+        const obj = JSON.parse(error);
+        message = `❌ Publishing failed with error: \n💡 ${obj.message || error}`;
+      } catch {
+        if (error?.includes("401")) {
+          message = `❌ Publishing failed due to an authorization error: \n💡 Please run ${chalk.cyan("aigne doc clear")} to reset your credentials and try again.`;
+        } else if (error?.includes("403")) {
+          message = `❌ Publishing failed due to an authorization error: \n💡 You’re not the creator of this document (Board ID: ${boardId}). You can change the board ID and try again. \n💡  Or run ${chalk.cyan("aigne doc clear")} to reset your credentials and try again.`;
+        }
       }
     }
 

package/agents/schema/document-execution-structure.yaml

@@ -25,7 +25,7 @@ items:
       type: array
       items:
         type: string
-      description: Associated sourceId from dataSources for subsequent translation and content generation, must come from sourceId in datasources, cannot have fake ids, cannot be empty
+      description: Associated sourceId from `<data_sources>` for subsequent translation and content generation, must come from sourceId in `<data_sources>`, cannot have fake ids, cannot be empty
   required:
     - title
     - description

package/agents/schema/document-structure-item.yaml

@@ -13,7 +13,7 @@ properties:
     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**
+    description: Associated sourceId from `<data_sources>` for subsequent translation and content generation, must come from sourceId in `<data_sources>`, cannot have fake ids, **cannot be empty**
     items:
       type: string
 required:

package/agents/schema/document-structure.yaml

@@ -10,11 +10,13 @@ items:
       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
+      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**
+      description: Associated sourceId from `<data_sources>` for subsequent translation and content generation, must come from sourceId in `<data_sources>`, cannot have fake ids, **cannot be empty**
       items:
         type: string
   required:

package/agents/update/check-generate-diagram.mjs

@@ -1,26 +1,84 @@
-const placeholder = "DIAGRAM_PLACEHOLDER";
+const PLACEHOLDER = "DIAGRAM_PLACEHOLDER";
+const DEFAULT_DIAGRAMMING_EFFORT = 5;
+const MIN_DIAGRAMMING_EFFORT = 0;
+const MAX_DIAGRAMMING_EFFORT = 10;
 
 export default async function checkGenerateDiagram(
-  { needDiagram, documentContent, locale },
+  {
+    documentContent,
+    locale,
+    feedback,
+    detailFeedback,
+    originalContent,
+    path: docPath,
+    diagramming,
+  },
   options,
 ) {
-  if (!needDiagram) {
-    return {};
+  let content = documentContent;
+  let diagramSourceCode;
+  let skipGenerateDiagram = false;
+
+  const preCheckAgent = options.context?.agents?.["preCheckGenerateDiagram"];
+
+  const preCheckResult = await options.context.invoke(preCheckAgent, {
+    documentContent,
+    feedback,
+    detailFeedback,
+    previousGenerationContent: originalContent,
+  });
+
+  const totalScore = (preCheckResult.details || []).reduce((acc, curr) => acc + curr.score, 0);
+  if (![false, "false", "", undefined, null].includes(preCheckResult.content)) {
+    content = preCheckResult.content;
   }
 
-  const generateAgent = options.context?.agents?.["generateDiagram"];
-  let content = documentContent;
+  let diagrammingEffort = diagramming?.effort
+    ? Number(diagramming?.effort)
+    : DEFAULT_DIAGRAMMING_EFFORT;
 
-  try {
-    const { diagramSourceCode } = await options.context.invoke(generateAgent, {
-      documentContent,
-      locale,
-    });
-    content = content.replace(placeholder, diagramSourceCode);
-  } catch (error) {
-    // FIXME: @zhanghan should regenerate document without diagram
-    content = content.replace(placeholder, "");
-    console.log(`⚠️  Skip generate any diagram: ${error.message}`);
+  if (Number.isNaN(diagrammingEffort)) {
+    diagrammingEffort = DEFAULT_DIAGRAMMING_EFFORT;
+  } else {
+    diagrammingEffort = Math.min(
+      Math.max(MIN_DIAGRAMMING_EFFORT, diagrammingEffort),
+      MAX_DIAGRAMMING_EFFORT,
+    );
   }
+
+  if (totalScore <= diagrammingEffort) {
+    skipGenerateDiagram = true;
+  }
+
+  if (skipGenerateDiagram) {
+    content = documentContent;
+  } else {
+    try {
+      const generateAgent = options.context?.agents?.["generateDiagram"];
+      ({ diagramSourceCode } = await options.context.invoke(generateAgent, {
+        documentContent: content,
+        locale,
+      }));
+    } catch (error) {
+      diagramSourceCode = "";
+      skipGenerateDiagram = true;
+      console.log(`⚠️  Skip generate any diagram for ${docPath}: ${error.message}`);
+    }
+
+    if (diagramSourceCode && !skipGenerateDiagram) {
+      if (content.includes(PLACEHOLDER)) {
+        content = content.replace(PLACEHOLDER, diagramSourceCode);
+      } else {
+        const mergeAgent = options.context?.agents?.["mergeDiagramToDocument"];
+        ({ content } = await options.context.invoke(mergeAgent, {
+          diagramSourceCode,
+          content,
+        }));
+      }
+    } else {
+      content = documentContent;
+    }
+  }
+
   return { content };
 }

package/agents/update/generate-document.yaml

@@ -46,19 +46,7 @@ input_schema:
     - rules
     - detailDataSource
     - originalDocumentStructure
-# output_key: content
-output_schema:
-  type: object
-  properties:
-    content:
-      type: string
-      description: Document content
-    needDiagram:
-      type: boolean
-      description: Does this document need to generate diagram?
-  required:
-    - content
-    - detailDataSource
+output_key: content
 afs:
   modules:
     - module: system-fs

package/agents/update/handle-document-update.yaml

@@ -2,7 +2,7 @@ type: team
 name: handleDocumentUpdate
 description: Update a document in a batch
 skills:
-  - ../utils/transform-detail-datasources.mjs
+  - ../utils/transform-detail-data-sources.mjs
   - type: team
     task_render_mode: collapse
     name: generateDocumentContent

package/agents/update/pre-check-generate-diagram.yaml

@@ -0,0 +1,44 @@
+name: preCheckGenerateDiagram
+description: Pre-check for generating diagram
+model:
+  reasoning_effort: 1
+instructions:
+  url: ../../prompts/detail/d2-diagram/pre-check.md
+input_schema:
+  type: object
+  properties:
+    documentContent:
+      type: string
+      description: Source content of the document
+    feedback:
+      type: string
+      description: User generation feedback
+    detailFeedback:
+      type: string
+      description: Current document detail feedback
+    previousGenerationContent:
+      type: string
+      description: Previous document content
+  required:
+    - documentContent
+output_schema:
+  type: object
+  properties:
+    content:
+      type: string
+      description: Document content
+    details:
+      type: array
+      description: Detailed needDiagram score
+      items:
+        type: object
+        properties:
+          type:
+            type: string
+          score:
+            type: number
+          reason:
+            type: string
+  required:
+    - content
+

package/agents/update/update-document-detail.yaml

@@ -1,61 +1,67 @@
-type: ai
+type: team
 name: updateDocumentDetail
 description: Update and optimize document content based on user feedback using diff patches
-instructions:
-  - role: system
-    url: ../../prompts/detail/update/system-prompt.md
-  - role: user
-    url: ../../prompts/detail/update/user-prompt.md
-auto_reorder_system_messages: true
-auto_merge_system_messages: true
-input_schema:
-  type: object
-  properties:
-    originalContent:
-      type: string
-      description: Original markdown content to be updated
-    feedback:
-      type: string
-      description: User feedback for content improvements
-    rules:
-      type: string
-      description: User configuration rules
-    locale:
-      type: string
-      description: User language, e.g. zh, en
-    detailDataSource:
-      type: string
-      description: Context for document content
-    glossary:
-      type: string
-      description: Glossary of terms
-    userPreferences:
-      type: string
-      description: User's saved preferences for content and documentation style
-    targetAudience:
-      type: string
-      description: Target audience for the documentation
-    title:
-      type: string
-      description: Document title
-    description:
-      type: string
-      description: Document description
-  required:
-    - originalContent
-    - 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
-keep_text_in_tool_uses: false
-skills:
-  - ./document-tools/update-document-content.mjs
-  # - ./generate-diagram.yaml
 task_render_mode: collapse
+skills:
+  - url: ../utils/analyze-feedback-intent.yaml
+  - type: ai
+    instructions:
+      - role: system
+        url: ../../prompts/detail/update/system-prompt.md
+      - role: user
+        url: ../../prompts/detail/update/user-prompt.md
+    auto_reorder_system_messages: true
+    auto_merge_system_messages: true
+    input_schema:
+      type: object
+      properties:
+        originalContent:
+          type: string
+          description: Original markdown content to be updated
+        feedback:
+          type: string
+          description: User feedback for content improvements
+        rules:
+          type: string
+          description: User configuration rules
+        locale:
+          type: string
+          description: User language, e.g. zh, en
+        detailDataSource:
+          type: string
+          description: Context for document content
+        glossary:
+          type: string
+          description: Glossary of terms
+        userPreferences:
+          type: string
+          description: User's saved preferences for content and documentation style
+        targetAudience:
+          type: string
+          description: Target audience for the documentation
+        title:
+          type: string
+          description: Document title
+        description:
+          type: string
+          description: Document description
+        needDataSources:
+          type: boolean
+          description: Whether data sources are needed for content modifications
+      required:
+        - originalContent
+        - 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
+    keep_text_in_tool_uses: false
+    skills:
+      - ./document-tools/update-document-content.mjs
+      # - ./generate-diagram.yaml

package/agents/update/update-single-document.yaml

@@ -1,7 +1,7 @@
 type: team
 name: updateSingleDocument
 skills:
-  - ../utils/transform-detail-datasources.mjs
+  - ../utils/transform-detail-data-sources.mjs
   - ../update/user-review-document.mjs
 iterate_on: selectedDocs
 concurrency: 1

package/agents/update/user-review-document.mjs

@@ -132,7 +132,9 @@ export default async function userReviewDocument({ content, description, ...rest
   const title = rest.documentStructure?.find((x) => x.path === rest.path)?.title;
 
   // Print current document headings structure
-  printDocumentHeadings(content, title || "Untitled Document");
+  if (!rest.isChat) {
+    printDocumentHeadings(content, title || "Untitled Document");
+  }
 
   // Initialize shared context with current content
   options.context.userContext.currentContent = content;
@@ -140,54 +142,62 @@ export default async function userReviewDocument({ content, description, ...rest
   const MAX_ITERATIONS = 100;
   const feedbacks = [];
   let iterationCount = 0;
+
+  let feedback = "";
+
   while (iterationCount < MAX_ITERATIONS) {
+    feedback = "";
     iterationCount++;
 
-    // Ask user what they want to do
-    const action = await options.prompts.select({
-      message: "What would you like to do next?",
-      choices: [
-        {
-          name: "View document",
-          value: "view",
-        },
-        {
-          name: "Give feedback",
-          value: "feedback",
-        },
-        {
-          name: "Done",
-          value: "finish",
-        },
-      ],
-    });
+    if (rest.isChat && rest.feedback) {
+      feedback = rest.feedback;
+    } else {
+      // Ask user what they want to do
+      const action = await options.prompts.select({
+        message: "What would you like to do next?",
+        choices: [
+          {
+            name: "View document",
+            value: "view",
+          },
+          {
+            name: "Give feedback",
+            value: "feedback",
+          },
+          {
+            name: "Done",
+            value: "finish",
+          },
+        ],
+      });
 
-    if (action === "finish") {
-      break;
-    } else if (action === "view") {
-      await showDocumentDetail(
-        options.context.userContext.currentContent,
-        title || "Untitled Document",
-      );
-    }
+      if (action === "finish") {
+        break;
+      } else if (action === "view") {
+        await showDocumentDetail(
+          options.context.userContext.currentContent,
+          title || "Untitled Document",
+        );
+      }
 
-    // Ask for feedback
-    const feedback = await options.prompts.input({
-      message:
-        "How would you like to improve this document?\n" +
-        "Examples:\n" +
-        "  • Add troubleshooting section for common errors\n" +
-        "  • Simplify the explanation for beginners\n" +
-        "  • Remove the outdated information about version 1.0\n\n" +
-        "  Your feedback:",
-    });
+      // Ask for feedback
+      feedback = await options.prompts.input({
+        message:
+          "How would you like to improve this document?\n" +
+          "Examples:\n" +
+          "  • Add troubleshooting section for common errors\n" +
+          "  • Simplify the explanation for beginners\n" +
+          "  • Remove the outdated information about version 1.0\n\n" +
+          "  Your feedback:",
+      });
 
-    // If no feedback, finish the loop
-    if (!feedback?.trim()) {
-      break;
-    }
+      // If no feedback, finish the loop
+      if (!feedback?.trim()) {
+        break;
+      }
 
-    feedbacks.push(feedback.trim());
+      feedbacks.push(feedback.trim());
+    }
 
     // Get the updateDocument agent
     const updateAgent = options.context.agents["handleDocumentUpdate"];
@@ -208,13 +218,14 @@ export default async function userReviewDocument({ content, description, ...rest
 
     try {
       // Call updateDocument agent with feedback
-      await options.context.invoke(updateAgent, {
+      const result = await options.context.invoke(updateAgent, {
         ...rest,
         originalContent: options.context.userContext.currentContent,
         feedback: feedback.trim(),
         userPreferences,
         title,
       });
+      options.context.userContext.currentContent = result.content;
 
       // Check if feedback should be saved as user preference
       const feedbackRefinerAgent = options.context.agents["checkFeedbackRefiner"];
@@ -235,6 +246,10 @@ export default async function userReviewDocument({ content, description, ...rest
         options.context.userContext.currentContent,
         title || "Untitled Document",
       );
+
+      if (rest.isChat) {
+        break;
+      }
     } catch (error) {
       console.error("Error processing your feedback:");
       console.error(`Type: ${error.name}`);