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

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-refine-item.yaml

@@ -0,0 +1,20 @@
+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
+  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
+  parentPath:
+    type: string
+    description: Parent node path, if null indicates it is a top-level node
+required:
+  - title
+  - description
+  - path

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/batch-generate-document.yaml

@@ -6,7 +6,7 @@ skills:
 input_schema:
   type: object
   properties:
-    datasources:
+    detailDataSource:
       type: string
       description: Context for documentation structure generation, used to assist generate documentation structure
     documentExecutionStructure: ../schema/document-execution-structure.yaml

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

@@ -0,0 +1,84 @@
+const PLACEHOLDER = "DIAGRAM_PLACEHOLDER";
+const DEFAULT_DIAGRAMMING_EFFORT = 5;
+const MIN_DIAGRAMMING_EFFORT = 0;
+const MAX_DIAGRAMMING_EFFORT = 10;
+
+export default async function checkGenerateDiagram(
+  {
+    documentContent,
+    locale,
+    feedback,
+    detailFeedback,
+    originalContent,
+    path: docPath,
+    diagramming,
+  },
+  options,
+) {
+  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;
+  }
+
+  let diagrammingEffort = diagramming?.effort
+    ? Number(diagramming?.effort)
+    : DEFAULT_DIAGRAMMING_EFFORT;
+
+  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-diagram.yaml

@@ -9,7 +9,6 @@ reflection:
   is_approved: isValid
   max_iterations: 5
   return_last_on_max_iterations: false
-  custom_error_message: "MUST NOT generate any diagram: validation failed after max iterations."
 input_schema:
   type: object
   properties:

package/agents/update/generate-document.yaml

@@ -16,7 +16,7 @@ input_schema:
     locale:
       type: string
       description: User language, such as zh, en
-    datasources:
+    detailDataSource:
       type: string
       description: Source data and context for document content generation
     targetAudience:
@@ -44,7 +44,7 @@ input_schema:
       description: Additional supplementary information
   required:
     - rules
-    - datasources
+    - detailDataSource
     - originalDocumentStructure
 output_key: content
 afs:
@@ -57,5 +57,5 @@ afs:
           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:
-  - ./generate-diagram.yaml
+# skills:
+#   - ./generate-diagram.yaml

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
@@ -23,6 +23,14 @@ skills:
       max_iterations: 5
       return_last_on_max_iterations: true
     task_title: Generate document for '{{ title }}'
+  - type: transform
+    jsonata: |
+      $merge([
+        $,
+        { "documentContent": content }
+      ])
+  - ./check-generate-diagram.mjs
+  # - ../generate/merge-diagram.yaml
   - ../utils/save-doc.mjs
 input_schema:
   type: object

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
-    datasources:
-      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,8 +1,7 @@
 type: team
 name: updateSingleDocument
 skills:
-  - ../utils/transform-detail-datasources.mjs
+  - ../utils/transform-detail-data-sources.mjs
   - ../update/user-review-document.mjs
-  - ../utils/save-doc.mjs
 iterate_on: selectedDocs
 concurrency: 1

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

@@ -105,6 +105,7 @@ async function showDocumentDetail(content, title) {
       renderer: new markedTerminal(),
     });
 
+    // FIXME: @zhanghan fix error "Could not find the language 'd2', did you forget to load/include a language module?"
     const renderedMarkdown = marked(content);
 
     // Restore original console.error
@@ -121,16 +122,15 @@ async function showDocumentDetail(content, title) {
   }
 }
 
-export default async function userReviewDocument(
-  { content, title, description, ...rest },
-  options,
-) {
+export default async function userReviewDocument({ content, description, ...rest }, options) {
   // Check if document content exists
   if (!content || typeof content !== "string" || content.trim().length === 0) {
     console.log("Please provide document content to review.");
     return { content };
   }
 
+  const title = rest.documentStructure?.find((x) => x.path === rest.path)?.title;
+
   // Print current document headings structure
   printDocumentHeadings(content, title || "Untitled Document");
 
@@ -190,7 +190,7 @@ export default async function userReviewDocument(
     feedbacks.push(feedback.trim());
 
     // Get the updateDocument agent
-    const updateAgent = options.context.agents["updateDocumentDetail"];
+    const updateAgent = options.context.agents["handleDocumentUpdate"];
     if (!updateAgent) {
       console.log(
         "We can't process your feedback right now. The document update feature is temporarily unavailable.",
@@ -208,12 +208,14 @@ export default async function userReviewDocument(
 
     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"];

package/agents/utils/analyze-feedback-intent.yaml

@@ -0,0 +1,29 @@
+name: analyzeFeedbackIntent
+description: Analyze user feedback to determine if data sources are needed for content modifications
+task_render_mode: hide
+instructions:
+  url: ../../prompts/utils/analyze-feedback-intent.md
+input_schema:
+  type: object
+  properties:
+    feedback:
+      type: string
+      description: User feedback for content modifications
+  required:
+    - feedback
+output_schema:
+  type: object
+  properties:
+    needDataSources:
+      type: boolean
+      description: Whether data sources are needed - true for add/edit operations that need context, false for delete/move/reorder operations
+    intentType:
+      type: string
+      description: The primary type of user intention
+    reason:
+      type: string
+      description: Explanation of why data sources are or aren't needed
+  required:
+    - needDataSources
+    - intentType
+    - reason

package/agents/utils/choose-docs.mjs

@@ -6,6 +6,14 @@ import {
   getMainLanguageFiles,
   processSelectedFiles,
 } from "../../utils/docs-finder-utils.mjs";
+import { DOC_ACTION } from "../../utils/constants/index.mjs";
+
+function getFeedbackMessage(action) {
+  if (action === DOC_ACTION.translate) {
+    return "Any specific translation preferences or instructions? (Press Enter to skip):";
+  }
+  return "How would you like to improve this document? (Press Enter to skip)";
+}
 
 export default async function chooseDocs(
   {
@@ -18,12 +26,13 @@ export default async function chooseDocs(
     locale,
     reset = false,
     requiredFeedback = true,
-    title,
+    action,
   },
   options,
 ) {
   let foundItems = [];
   let selectedFiles = [];
+  const docAction = action || (isTranslate ? DOC_ACTION.translate : DOC_ACTION.update);
 
   // If docs is empty or not provided, let user select multiple documents
   if (!docs || docs.length === 0) {
@@ -37,7 +46,9 @@ export default async function chooseDocs(
 
       if (mainLanguageFiles.length === 0) {
         throw new Error(
-          `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`",
+          )}`,
         );
       }
 
@@ -66,7 +77,7 @@ export default async function chooseDocs(
 
       // Let user select multiple files
       selectedFiles = await options.prompts.checkbox({
-        message: title || getActionText(isTranslate, "Select documents to {action}:"),
+        message: getActionText("Select documents to {action}:", docAction),
         source: (term) => {
           if (!term) return choices;
 
@@ -88,7 +99,7 @@ export default async function chooseDocs(
       foundItems = await processSelectedFiles(selectedFiles, documentExecutionStructure, docsDir);
     } catch (error) {
       console.log(
-        getActionText(isTranslate, `\nFailed to select documents to {action}: ${error.message}`),
+        getActionText(`\nFailed to select documents to {action}: ${error.message}`, docAction),
       );
       process.exit(0);
     }
@@ -123,8 +134,7 @@ export default async function chooseDocs(
   // Prompt for feedback if not provided
   let userFeedback = feedback;
   if (!userFeedback && (requiredFeedback || foundItems?.length > 1)) {
-    const feedbackMessage =
-      "How should we improve this document? (Enter to skip, will auto-update from content sources):";
+    const feedbackMessage = getFeedbackMessage(docAction);
 
     userFeedback = await options.prompts.input({
       message: feedbackMessage,

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

@@ -1,3 +1,4 @@
+import { DOC_ACTION } from "../../utils/constants/index.mjs";
 import {
   fileNameToFlatPath,
   findItemByFlatName,
@@ -14,6 +15,7 @@ export default async function findItemByPath(
   let foundItem = null;
   let selectedFileContent = null;
   let docPath = doc;
+  const docAction = isTranslate ? DOC_ACTION.translate : DOC_ACTION.update;
 
   // If docPath is empty, let user select from available documents
   if (!docPath) {
@@ -31,7 +33,7 @@ export default async function findItemByPath(
 
       // Let user select a file
       const selectedFile = await options.prompts.search({
-        message: getActionText(isTranslate, "Select a document to {action}:"),
+        message: getActionText("Select a document to {action}:", docAction),
         source: async (input) => {
           if (!input || input.trim() === "") {
             return mainLanguageFiles.map((file) => ({
@@ -74,8 +76,8 @@ export default async function findItemByPath(
       console.debug(error?.message);
       throw new Error(
         getActionText(
-          isTranslate,
           "Please run 'aigne doc generate' first to generate documents, then select which document to {action}",
+          docAction,
         ),
       );
     }

package/agents/utils/load-sources.mjs

@@ -171,7 +171,7 @@ export default async function loadSources(
             if (dimensions.width < minImageWidth) {
               filteredImageCount++;
               console.log(
-                `Filtered image: ${fileName} (${dimensions.width}x${dimensions.height}px < ${minImageWidth}px minimum)`,
+                `Ignored image: ${fileName} (${dimensions.width}x${dimensions.height}px < ${minImageWidth}px minimum)`,
               );
               return;
             }
@@ -218,8 +218,8 @@ export default async function loadSources(
     0,
   );
 
-  const datasources = splitSourcesToChunks(sourceFiles, INTELLIGENT_SUGGESTION_TOKEN_THRESHOLD).map(
-    (i) => ({ datasources: buildSourcesContent(i) }),
+  const dataSources = splitSourcesToChunks(sourceFiles, INTELLIGENT_SUGGESTION_TOKEN_THRESHOLD).map(
+    (i) => ({ dataSourceChunk: buildSourcesContent(i) }),
   );
 
   const remoteFileList = [];
@@ -290,7 +290,7 @@ export default async function loadSources(
   }
 
   return {
-    datasources,
+    dataSources,
     content,
     originalDocumentStructure,
     files,
@@ -345,12 +345,12 @@ loadSources.input_schema = {
 loadSources.output_schema = {
   type: "object",
   properties: {
-    datasources: {
+    dataSources: {
       type: "array",
       items: {
         type: "object",
         properties: {
-          datasources: { type: "string" },
+          dataSourceChunk: { type: "string" },
         },
       },
     },