@aigne/doc-smith 0.8.15 → 0.8.16-beta.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"];
@@ -236,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}`);

package/agents/utils/document-icon-generate.yaml

@@ -0,0 +1,52 @@
+name: documentIconGenerate
+description: Generate appropriate Iconify icon names for document structure root nodes based on their title and description
+model:
+  reasoning_effort: low
+task_render_mode: hide
+instructions:
+  url: ../../prompts/common/document-structure/document-icon-generate.md
+input_schema:
+  type: object
+  properties:
+    documentList:
+      type: array
+      items:
+        type: object
+        properties:
+          path:
+            type: string
+            description: Document path for mapping purposes
+          title:
+            type: string
+            description: Document title to analyze for icon selection
+          description:
+            type: string
+            description: Document description to analyze for icon selection
+        required:
+          - path
+          - title
+          - description
+      description: List of root-level document items (parentId is null) that need icons generated
+  required:
+    - documentList
+output_schema:
+  type: object
+  properties:
+    documentList:
+      type: array
+      items:
+        type: object
+        properties:
+          path:
+            type: string
+            description: Document path (same as input for mapping)
+          icon:
+            type: string
+            description: Iconify icon name in the format collection:icon-name (e.g., lucide:book)
+        required:
+          - path
+          - icon
+      description: List of document items with generated Iconify icon names
+  required:
+    - documentList
+

package/agents/utils/document-title-streamline.yaml

@@ -0,0 +1,48 @@
+name: documentTitleStreamline
+description: Streamline document titles by shortening them while preserving meaning for better sidebar navigation
+model:
+  reasoning_effort: low
+task_render_mode: hide
+instructions:
+  url: ../../prompts/common/document-structure/document-title-streamline.md
+input_schema:
+  type: object
+  properties:
+    documentList:
+      type: array
+      items:
+        type: object
+        properties:
+          path:
+            type: string
+            description: Document path for mapping purposes
+          title:
+            type: string
+            description: Document title to streamline
+        required:
+          - path
+          - title
+      description: List of document items with titles to streamline
+  required:
+    - documentList
+output_schema:
+  type: object
+  properties:
+    documentList:
+      type: array
+      items:
+        type: object
+        properties:
+          path:
+            type: string
+            description: Document path (same as input for mapping)
+          title:
+            type: string
+            description: Streamlined document title (max 24 characters for English, 12 characters for character-based languages)
+        required:
+          - path
+          - title
+      description: List of streamlined document items with shortened titles
+  required:
+    - documentList
+

package/agents/utils/generate-document-icon-if-needed.mjs

@@ -0,0 +1,93 @@
+/**
+ * Generate icons for root-level document structure items if they don't have one or if title/description changed
+ * Reusable function for generating document icons in various contexts
+ * Can be called as a standalone function with { documentStructure, originalItems? } or as a function skill with (input, options)
+ * @param {Object|Array} inputOrParams - Either input from previous step (with documentStructure) or params object with documentStructure and optional originalItems
+ * @param {Object} options - Agent options with context
+ * @param {Array<{path: string, title?: string, description?: string}>} [inputOrParams.originalItems] - Original items for comparison (optional, used to detect title/description changes)
+ * @returns {Promise<Object>} - Returns input unchanged (modifies documentStructure in place)
+ */
+export default async function generateDocumentIconIfNeeded(inputOrParams, options) {
+  // Handle both calling patterns:
+  // 1. As function skill: (input, options) where input.documentStructure exists
+  // 2. As standalone function: ({ documentStructure, originalItems? }, options)
+  const documentStructure =
+    inputOrParams?.documentStructure || (Array.isArray(inputOrParams) ? inputOrParams : null);
+  const originalItems = inputOrParams?.originalItems || [];
+
+  if (!documentStructure || !Array.isArray(documentStructure)) {
+    // Return input unchanged if no documentStructure to process
+    return inputOrParams || {};
+  }
+
+  // Create a map of original items by path for quick lookup
+  const originalItemsMap = new Map(
+    originalItems.map((item) => [item.path, { title: item.title, description: item.description }]),
+  );
+
+  // Filter root-level items that need icon generation or update
+  const itemsNeedingIcon = documentStructure.filter((item) => {
+    // Only process root-level items (parentId is null, undefined, or empty string)
+    const isRootLevel = !item.parentId || item.parentId === "null" || item.parentId === "";
+    if (!isRootLevel) return false;
+
+    // Must have title and description for icon generation
+    if (!item.title || !item.description) return false;
+
+    // Check if icon is missing
+    const hasNoIcon = !item.icon;
+
+    // Check if title or description changed (if original item exists)
+    const originalItem = originalItemsMap.get(item.path);
+    const titleChanged = originalItem && originalItem.title !== item.title;
+    const descriptionChanged = originalItem && originalItem.description !== item.description;
+    const contentChanged = titleChanged || descriptionChanged;
+
+    // Generate/update icon if: missing icon OR content changed
+    return hasNoIcon || contentChanged;
+  });
+
+  if (itemsNeedingIcon.length === 0) {
+    return;
+  }
+
+  const documentList = itemsNeedingIcon.map((item) => ({
+    path: item.path,
+    title: item.title,
+    description: item.description,
+  }));
+
+  const iconAgent = options?.context?.agents?.["documentIconGenerate"];
+  if (!iconAgent) {
+    console.warn("⚠️  documentIconGenerate agent not found. Skipping icon generation.");
+    return;
+  }
+
+  try {
+    const iconResult = await options.context.invoke(iconAgent, {
+      documentList,
+    });
+
+    // Update the document items with generated icons using path as the key
+    if (iconResult.documentList && Array.isArray(iconResult.documentList)) {
+      const iconMap = new Map(iconResult.documentList.map((item) => [item.path, item]));
+
+      for (const item of documentStructure) {
+        const iconData = iconMap.get(item.path);
+        if (iconData?.icon) {
+          item.icon = iconData.icon;
+        }
+      }
+    }
+  } catch (error) {
+    console.warn("⚠️  Failed to generate document icons:", error.message);
+    console.warn("Continuing without icons.");
+  }
+
+  // Return input unchanged (documentStructure is modified in place)
+  return inputOrParams || {};
+}
+
+generateDocumentIconIfNeeded.taskTitle = "Generate document icons if needed";
+generateDocumentIconIfNeeded.description =
+  "Generate appropriate Lucide icons for root-level document structure items based on their title and description, or update icon if title/description changed";

package/agents/utils/list-docs.mjs

@@ -0,0 +1,15 @@
+import { getMainLanguageFiles } from "../../utils/docs-finder-utils.mjs";
+import init from "../init/index.mjs";
+
+export default async function listDocs(_, options) {
+  const config = await init({ checkOnly: true }, options);
+
+  // Get all main language .md files in docsDir
+  const mainLanguageFiles = await getMainLanguageFiles(config.docsDir, config.locale);
+
+  return {
+    documents: mainLanguageFiles,
+  };
+}
+
+listDocs.description = "List all available documentation files";

package/agents/utils/streamline-document-titles-if-needed.mjs

@@ -0,0 +1,88 @@
+/**
+ * Check if a string contains character-based language characters (Chinese, Japanese, Korean, etc.)
+ * @param {string} str - String to check
+ * @returns {boolean} - True if string contains character-based language characters
+ */
+function isCharacterBasedLanguage(str) {
+  if (!str) return false;
+  // Check for Chinese, Japanese, Korean, and other character-based languages
+  // Chinese: \u4e00-\u9fff (CJK Unified Ideographs)
+  // Japanese: \u3040-\u309f (Hiragana), \u30a0-\u30ff (Katakana)
+  // Korean: \uac00-\ud7a3 (Hangul Syllables)
+  // Thai: \u0e00-\u0e7f
+  // Arabic: \u0600-\u06ff
+  const characterBasedPattern =
+    /[\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7a3\u0e00-\u0e7f\u0600-\u06ff]/;
+  return characterBasedPattern.test(str);
+}
+
+/**
+ * Get character limit based on language type
+ * @param {string} title - Title to check
+ * @returns {number} - Character limit (24 for English, 12 for character-based languages)
+ */
+function getCharacterLimit(title) {
+  return isCharacterBasedLanguage(title) ? 12 : 24;
+}
+
+/**
+ * Streamline document titles if they exceed length limits
+ * Reusable function for streamlining document titles in various contexts
+ * @param {Object} params
+ * @param {Array<{title: string, path: string}>} params.documentStructure - Document structure array
+ * @param {Object} options - Agent options with context
+ * @returns {Promise<void>} - Modifies documentStructure in place
+ */
+export default async function streamlineDocumentTitlesIfNeeded({ documentStructure }, options) {
+  if (!documentStructure || !Array.isArray(documentStructure)) {
+    return;
+  }
+
+  // Filter items that need streamlining based on character count and language type
+  // English: > 24 characters, Character-based languages (Chinese, Japanese, etc.): > 12 characters
+  const itemsNeedingStreamline = documentStructure.filter((item) => {
+    if (!item.title) return false;
+    const limit = getCharacterLimit(item.title);
+    return item.title.length > limit;
+  });
+
+  if (itemsNeedingStreamline.length === 0) {
+    return;
+  }
+
+  const documentList = itemsNeedingStreamline.map((item) => ({
+    path: item.path,
+    title: item.title,
+  }));
+
+  const streamlineAgent = options?.context?.agents?.["documentTitleStreamline"];
+  if (!streamlineAgent) {
+    console.warn("⚠️  documentTitleStreamline agent not found. Skipping title streamlining.");
+    return;
+  }
+
+  try {
+    const streamlineResult = await options.context.invoke(streamlineAgent, {
+      documentList,
+    });
+
+    // Update the document items with streamlined titles using path as the key
+    if (streamlineResult.documentList && Array.isArray(streamlineResult.documentList)) {
+      const streamlineMap = new Map(streamlineResult.documentList.map((item) => [item.path, item]));
+
+      for (const item of documentStructure) {
+        const streamlined = streamlineMap.get(item.path);
+        if (streamlined) {
+          item.title = streamlined.title;
+        }
+      }
+    }
+  } catch (error) {
+    console.warn("⚠️  Failed to streamline document titles:", error.message);
+    console.warn("Continuing with original titles.");
+  }
+}
+
+streamlineDocumentTitlesIfNeeded.taskTitle = "Streamline document titles if needed";
+streamlineDocumentTitlesIfNeeded.description =
+  "Shorten document titles that exceed length limits to make sidebar navigation less crowded";

package/aigne.yaml

@@ -3,7 +3,7 @@
 model:
   # model: aignehub/gpt-5
   # model: aignehub/claude-sonnet-4-0
-  model: aignehub/gemini-2.5-pro # reasoning_effort 128-32768
+  model: google/gemini-2.5-pro # reasoning_effort 128-32768
   # https://github.com/AIGNE-io/aigne-framework/blob/main/models/gemini/src/gemini-chat-model.ts#L115
   reasoning_effort:
     $get: reasoningEffort
@@ -79,6 +79,12 @@ agents:
   - ./agents/utils/check-feedback-refiner.mjs
   - ./agents/utils/feedback-refiner.yaml
   - ./agents/utils/analyze-feedback-intent.yaml
+  - ./agents/utils/list-docs.mjs
+
+  - ./agents/utils/document-title-streamline.yaml
+  - ./agents/utils/streamline-document-titles-if-needed.mjs
+  - ./agents/utils/document-icon-generate.yaml
+  - ./agents/utils/generate-document-icon-if-needed.mjs
 
   # User Preferences & Chat
   - ./agents/prefs/index.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.8.15",
+  "version": "0.8.16-beta.1",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"
@@ -24,25 +24,22 @@
   "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
   "license": "Elastic-2.0",
   "dependencies": {
-    "@aigne/aigne-hub": "^0.10.5-beta.3",
-    "@aigne/anthropic": "^0.14.5-beta.3",
     "@aigne/cli": "^1.53.1-beta.4",
     "@aigne/core": "^1.65.1-beta.3",
-    "@aigne/gemini": "^0.14.5-beta.3",
-    "@aigne/openai": "^0.16.5-beta.3",
     "@aigne/publish-docs": "^0.12.1",
     "@blocklet/payment-broker-client": "^1.22.8",
     "@terrastruct/d2": "^0.1.33",
     "chalk": "^5.5.0",
-    "cli-highlight": "^2.1.11",
     "debug": "^4.4.1",
     "diff": "^8.0.2",
     "dompurify": "^3.2.6",
+    "fast-deep-equal": "^3.1.3",
     "file-type": "^21.0.0",
     "fs-extra": "^11.3.1",
     "glob": "^11.0.3",
     "gpt-tokenizer": "^3.2.0",
     "image-size": "^2.0.2",
+    "is-in-ci": "^2.0.0",
     "isbinaryfile": "^5.0.6",
     "jsdom": "^26.1.0",
     "marked": "^15.0.12",
@@ -56,7 +53,7 @@
     "remark-gfm": "^4.0.1",
     "remark-lint": "^10.0.1",
     "remark-parse": "^11.0.0",
-    "terminal-link": "^4.0.0",
+    "terminal-link": "^5.0.0",
     "typescript": "^5.9.3",
     "ufo": "^1.6.1",
     "unified": "^11.0.5",

package/prompts/common/document/media-file-list-usage-rules.md

@@ -1,12 +1,18 @@
 <media_file_list_usage_rules>
 
-**Usage Workflow**
+## Media File List Usage Rules
+
+You must use the provided `<media_file_list>` data to determine which media files to use and where to insert them.
+
+### Usage Workflow
+
 1. Read the `<media_file_list>` data and take note of each file's `path` and `description` as references.
 2. Combine those descriptions with the current document's content to decide which images should be used and where they should be inserted.
 3. Confirm that every inserted image path comes from `<media_file_list>`. If a path is missing from that list, replace it with one that is included.
 
-**Usage Requirements**
+### Usage Requirements
 - Insert images with Markdown syntax: `![Descriptive alt text](<path-from-media_file_list>)`.
 - Never invent, reinterpret, fabricate, normalize, or rewrite any media file path under any circumstances.
+ - After inserting a media file, update the surrounding document text to introduce, reference, or describe the media, so the media is properly integrated and its purpose is clear to readers.
 
 </media_file_list_usage_rules>