@aigne/doc-smith 0.8.16-beta → 0.8.16-beta.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.8.16-beta.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.16-beta...v0.8.16-beta.1) (2025-11-11)
+
+
+### Features
+
+* add document icon generation functionality and update schemas ([#286](https://github.com/AIGNE-io/aigne-doc-smith/issues/286)) ([3e20fda](https://github.com/AIGNE-io/aigne-doc-smith/commit/3e20fdaf8a6e4713ed0756f52c620180c8b47f35))
+* support auto open evaluation report ([#287](https://github.com/AIGNE-io/aigne-doc-smith/issues/287)) ([93a64d5](https://github.com/AIGNE-io/aigne-doc-smith/commit/93a64d5bfb4602532efe5cc33cc90494e2b0cb48))
+
+
+### Bug Fixes
+
+* tune prompts increase document expressiveness ([#284](https://github.com/AIGNE-io/aigne-doc-smith/issues/284)) ([eb79742](https://github.com/AIGNE-io/aigne-doc-smith/commit/eb79742d0782405d6143ac0271359cd8ae97286b))
+
 ## [0.8.16-beta](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15...v0.8.16-beta) (2025-11-10)
 
 

package/agents/evaluate/generate-report.mjs

@@ -1,6 +1,9 @@
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { pick } from "@aigne/core/utils/type-utils.js";
+import isInCi from "is-in-ci";
+import openTerminal from "open";
+
 import { DOC_SMITH_DIR } from "../../utils/constants/index.mjs";
 import {
   copyHtmlReportTemplate,
@@ -35,6 +38,7 @@ export default async function generateEvaluationReport({
   readerKnowledgeLevel,
   documentationDepth,
   targetAudience,
+  open = true,
 }) {
   const timestamp = new Date().toISOString();
   const timestampForFolder = generateTimestampForFolder();
@@ -69,6 +73,9 @@ export default async function generateEvaluationReport({
 
   // Generate success message
   const message = generateReportSuccessMessage(toRelativePath(jsonReportPath), htmlReportPath);
+  if (open && !isInCi) {
+    openTerminal(htmlReportPath);
+  }
 
   return {
     message,

package/agents/evaluate/index.yaml

@@ -37,3 +37,9 @@ skills:
     mode: sequential
   - ./generate-report.mjs
 mode: sequential
+input_schema:
+  type: object
+  properties:
+    open:
+      type: boolean
+      description: Auto open generated report

package/agents/generate/check-need-generate-structure.mjs

@@ -96,8 +96,10 @@ export default async function checkNeedGenerateStructure(
           result.projectName !== projectInfo.name &&
           !projectInfo.fromGitHub
         ) {
-          await saveValueToConfig("projectName", result.projectName);
-          message += `Project name: \`${result.projectName}\``;
+          // Remove leading and trailing spaces (middle spaces are preserved and count toward limit)
+          const trimmedProjectName = result.projectName.trim();
+          await saveValueToConfig("projectName", trimmedProjectName);
+          message += `Project name: \`${trimmedProjectName}\``;
           hasUpdated = true;
         }
 
@@ -106,8 +108,10 @@ export default async function checkNeedGenerateStructure(
           result.projectDesc !== projectInfo.description &&
           !projectInfo.fromGitHub
         ) {
-          await saveValueToConfig("projectDesc", result.projectDesc);
-          message += `\nProject description: \`${result.projectDesc}\``;
+          // Remove leading and trailing spaces (middle spaces are preserved and count toward limit)
+          const trimmedProjectDesc = result.projectDesc.trim();
+          await saveValueToConfig("projectDesc", trimmedProjectDesc);
+          message += `\nProject description: \`${trimmedProjectDesc}\``;
           hasUpdated = true;
         }
 

package/agents/generate/document-structure-tools/add-document.mjs

@@ -4,6 +4,7 @@ import {
   validateAddDocumentInput,
 } from "../../../types/document-structure-schema.mjs";
 import streamlineDocumentTitlesIfNeeded from "../../utils/streamline-document-titles-if-needed.mjs";
+import generateDocumentIconIfNeeded from "../../utils/generate-document-icon-if-needed.mjs";
 
 export default async function addDocument(input, options) {
   // Validate input using Zod schema
@@ -63,6 +64,9 @@ export default async function addDocument(input, options) {
   // Add the document to the structure first
   const updatedStructure = [...documentStructure, newDocument];
 
+  // Generate icon for root-level documents if needed
+  await generateDocumentIconIfNeeded({ documentStructure: updatedStructure }, options);
+
   const successMessage = `addDocument executed successfully.
   Successfully added document '${title}' with path '${path}'.
   Check if the latest version of documentStructure meets user feedback, if so, just return 'success'.`;

package/agents/generate/document-structure-tools/update-document.mjs

@@ -4,6 +4,7 @@ import {
   validateUpdateDocumentInput,
 } from "../../../types/document-structure-schema.mjs";
 import streamlineDocumentTitlesIfNeeded from "../../utils/streamline-document-titles-if-needed.mjs";
+import generateDocumentIconIfNeeded from "../../utils/generate-document-icon-if-needed.mjs";
 
 export default async function updateDocument(input, options) {
   // Validate input using Zod schema
@@ -55,6 +56,16 @@ export default async function updateDocument(input, options) {
   const updatedStructure = [...documentStructure];
   updatedStructure[documentIndex] = updatedDocument;
 
+  // Generate/update icon for root-level documents if needed
+  // Pass original document for comparison to detect title/description changes
+  await generateDocumentIconIfNeeded(
+    {
+      documentStructure: updatedStructure,
+      originalItems: [originalDocument],
+    },
+    options,
+  );
+
   const updates = [];
   if (title !== undefined) updates.push(`title to '${title}'`);
   if (description !== undefined) updates.push("description");

package/agents/generate/draw-diagram.yaml

@@ -2,9 +2,9 @@ name: drawDiagram
 description: Generate a D2 diagram from document content.
 instructions:
   - role: system
-    url: ../../prompts/detail/d2-diagram/system-prompt.md
+    url: ../../prompts/detail/diagram/system-prompt.md
   - role: user
-    url: ../../prompts/detail/d2-diagram/user-prompt.md
+    url: ../../prompts/detail/diagram/user-prompt.md
 input_schema:
   type: object
   properties:

package/agents/generate/generate-structure.yaml

@@ -54,10 +54,10 @@ skills:
           properties:
             projectName:
               type: string
-              description: Project name identified from your content sources
+              description: Project name identified from your content sources. Max 40 characters (any language, each character = 1). Leading/trailing spaces removed. Generate complete name within limit.
             projectDesc:
               type: string
-              description: Brief project description generated from content analysis (under 50 words)
+              description: Brief project description from content analysis. Max 160 characters (any language, each character = 1). Leading/trailing spaces removed. Generate complete description within limit.
             structures:
               type: array
               description: List of document structure items to add or update
@@ -109,6 +109,7 @@ skills:
             path: refinedItem.path,
             parentId: refinedItem.parentPath || null,  // Convert parentPath to parentId
             sourceIds: originalItem?.sourceIds || [],
+            ...(refinedItem.icon && { icon: refinedItem.icon }), // Preserve icon if updated during refinement
           }
 
           return newItem

package/agents/init/index.mjs

@@ -403,8 +403,9 @@ async function _init(
 
   // Save project info to config
   const projectInfo = await getProjectInfo();
-  input.projectName = projectInfo.name;
-  input.projectDesc = projectInfo.description;
+  // Remove leading and trailing spaces (middle spaces are preserved and count toward limit)
+  input.projectName = projectInfo.name.trim();
+  input.projectDesc = projectInfo.description.trim();
   input.projectLogo = projectInfo.icon;
 
   // Generate YAML content
@@ -453,8 +454,9 @@ export function generateYAML(input) {
   // Create the main configuration object that will be safely serialized
   const config = {
     // Project information (safely handled by yaml library)
-    projectName: input.projectName || "",
-    projectDesc: input.projectDesc || "",
+    // Remove leading and trailing spaces (middle spaces are preserved and count toward limit)
+    projectName: (input.projectName || "").trim(),
+    projectDesc: (input.projectDesc || "").trim(),
     projectLogo: input.projectLogo || "",
 
     thinking: {

package/agents/media/load-media-description.mjs

@@ -160,9 +160,10 @@ export default async function loadMediaDescription(input, options) {
   }
 
   // Build enhanced assetsContent with descriptions
-  let enhancedAssetsContent = "# Available Media Assets for Documentation\n\n";
+  let enhancedAssetsContent;
 
   if (mediaFiles.length > 0) {
+    enhancedAssetsContent = "# Available Media Assets for Documentation\n\n";
     const assets = mediaFiles.map((x) => {
       const mediaHash = mediaHashMap.get(x.path);
       const description = cache[mediaHash]?.description;

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

@@ -16,6 +16,9 @@ properties:
     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
+  icon:
+    type: string
+    description: Lucide icon name for root-level documents (just support lucide:icon-name, not support other icon collections)
 required:
   - title
   - description

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

@@ -14,6 +14,9 @@ properties:
   parentPath:
     type: string
     description: Parent node path, if null indicates it is a top-level node
+  icon: 
+    type: string
+    description: Iconify icon name, e.g., lucide:book, lucide:rocket, lucide:* etc.
 required:
   - title
   - description

package/agents/schema/document-structure.yaml

@@ -19,6 +19,9 @@ items:
       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
+    icon:
+      type: string
+      description: Lucide icon name for root-level documents (just support lucide:icon-name, not support other icon collections)
   required:
     - title
     - description

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

@@ -3,7 +3,7 @@ description: Pre-check for generating diagram
 model:
   reasoning_effort: 1
 instructions:
-  url: ../../prompts/detail/d2-diagram/pre-check.md
+  url: ../../prompts/detail/diagram/pre-check.md
 input_schema:
   type: object
   properties:

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/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/aigne.yaml

@@ -83,6 +83,8 @@ agents:
 
   - ./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.16-beta",
+  "version": "0.8.16-beta.1",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"
@@ -24,17 +24,12 @@
   "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",
@@ -44,6 +39,7 @@
     "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",
@@ -57,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>