@aigne/doc-smith 0.9.6-beta → 0.9.6-beta.2

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

@@ -0,0 +1,29 @@
+name: analyzeStructureFeedbackIntent
+description: Analyze user feedback to determine if data sources are needed for structure modifications
+task_render_mode: hide
+instructions:
+  url: ../../prompts/utils/analyze-structure-feedback-intent.md
+input_schema:
+  type: object
+  properties:
+    feedback:
+      type: string
+      description: User feedback for structure 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/check-detail-result.mjs

@@ -1,4 +1,5 @@
 import { checkMarkdown } from "../../utils/markdown-checker.mjs";
+import { buildAllowedLinksFromStructure } from "../../utils/docs-finder-utils.mjs";
 
 export default async function checkDetailResult({ documentStructure, reviewContent, docsDir }) {
   if (!reviewContent || reviewContent.trim() === "") {
@@ -12,20 +13,7 @@ export default async function checkDetailResult({ documentStructure, reviewConte
   const detailFeedback = [];
 
   // Create a set of allowed links, including both original paths and processed .md paths
-  const allowedLinks = new Set();
-  documentStructure.forEach((item) => {
-    // Add original path
-    allowedLinks.add(item.path);
-
-    // Add processed .md path (same logic as processContent in utils.mjs)
-    let processedPath = item.path;
-    if (processedPath.startsWith(".")) {
-      processedPath = processedPath.replace(/^\./, "");
-    }
-    let flatPath = processedPath.replace(/^\//, "").replace(/\//g, "-");
-    flatPath = `./${flatPath}.md`;
-    allowedLinks.add(flatPath);
-  });
+  const allowedLinks = buildAllowedLinksFromStructure(documentStructure);
 
   // Run comprehensive markdown validation with all checks
   try {

package/agents/utils/load-sources.mjs

@@ -1,27 +1,42 @@
-import { readFile } from "node:fs/promises";
 import { statSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import imageSize from "image-size";
+import {
+  DEFAULT_EXCLUDE_PATTERNS,
+  DEFAULT_INCLUDE_PATTERNS,
+  INTELLIGENT_SUGGESTION_TOKEN_THRESHOLD,
+} from "../../utils/constants/index.mjs";
+import { loadDocumentStructure } from "../../utils/docs-finder-utils.mjs";
 import {
   buildSourcesContent,
-  loadFilesFromPaths,
-  readFileContents,
+  calculateTokens,
   getMimeType,
   isRemoteFile,
-  calculateTokens,
+  loadFilesFromPaths,
+  readFileContents,
 } from "../../utils/file-utils.mjs";
+import { isOpenAPISpecFile } from "../../utils/openapi/index.mjs";
 import {
   getCurrentGitHead,
   getModifiedFilesBetweenCommits,
   toRelativePath,
 } from "../../utils/utils.mjs";
-import {
-  INTELLIGENT_SUGGESTION_TOKEN_THRESHOLD,
-  DEFAULT_EXCLUDE_PATTERNS,
-  DEFAULT_INCLUDE_PATTERNS,
-} from "../../utils/constants/index.mjs";
-import { isOpenAPISpecFile } from "../../utils/openapi/index.mjs";
-import { loadDocumentStructure } from "../../utils/docs-finder-utils.mjs";
+
+const imageExts = [".jpg", ".jpeg", ".png", ".gif", ".bmp", ".webp", ".svg", ".heic", ".heif"];
+const videoExts = [
+  ".mp4",
+  ".mpeg",
+  ".mpg",
+  ".mov",
+  ".avi",
+  ".flv",
+  ".mkv",
+  ".webm",
+  ".wmv",
+  ".m4v",
+  ".3gpp",
+];
 
 export default async function loadSources(
   {
@@ -77,7 +92,13 @@ export default async function loadSources(
       .filter(Boolean);
     const allFiles = await loadFilesFromPaths(pickSourcesPath, {
       includePatterns,
-      excludePatterns: [...new Set([...(excludePatterns || []), ...customExcludePatterns])],
+      excludePatterns: [
+        ...new Set([
+          ...(excludePatterns || []),
+          ...customExcludePatterns,
+          ...videoExts.map((x) => `**/*${x}`),
+        ]),
+      ],
       useDefaultPatterns,
       defaultIncludePatterns: DEFAULT_INCLUDE_PATTERNS,
       defaultExcludePatterns: DEFAULT_EXCLUDE_PATTERNS,
@@ -90,26 +111,9 @@ export default async function loadSources(
 
   // Define media file extensions
   const mediaExtensions = [
-    ".jpg",
-    ".jpeg",
-    ".png",
-    ".gif",
-    ".bmp",
-    ".webp",
-    ".svg",
-    ".heic",
-    ".heif",
-    ".mp4",
-    ".mpeg",
-    ".mpg",
-    ".mov",
-    ".avi",
-    ".flv",
-    ".mkv",
-    ".webm",
-    ".wmv",
-    ".m4v",
-    ".3gpp",
+    ...imageExts,
+    // ignore video temporary
+    // ...videoExts
   ];
 
   // Separate source files from media files
@@ -119,20 +123,6 @@ export default async function loadSources(
   // Helper function to determine file type from extension
   const getFileType = (filePath) => {
     const ext = path.extname(filePath).toLowerCase();
-    const imageExts = [".jpg", ".jpeg", ".png", ".gif", ".bmp", ".webp", ".svg", ".heic", ".heif"];
-    const videoExts = [
-      ".mp4",
-      ".mpeg",
-      ".mpg",
-      ".mov",
-      ".avi",
-      ".flv",
-      ".mkv",
-      ".webm",
-      ".wmv",
-      ".m4v",
-      ".3gpp",
-    ];
 
     if (imageExts.includes(ext)) return "image";
     if (videoExts.includes(ext)) return "video";

package/aigne.yaml

@@ -68,6 +68,7 @@ agents:
   - ./agents/clear/clear-media-description.mjs
 
   # Utilities
+  - ./agents/utils/add-translates-to-structure.mjs
   - ./agents/utils/load-sources.mjs
   - ./agents/utils/post-generate.mjs
   - ./agents/utils/save-sidebar.mjs
@@ -79,7 +80,8 @@ agents:
   - ./agents/utils/find-item-by-path.mjs
   - ./agents/utils/check-feedback-refiner.mjs
   - ./agents/utils/feedback-refiner.yaml
-  - ./agents/utils/analyze-feedback-intent.yaml
+  - ./agents/utils/analyze-structure-feedback-intent.yaml
+  - ./agents/utils/analyze-document-feedback-intent.yaml
 
   - ./agents/utils/document-title-streamline.yaml
   - ./agents/utils/streamline-document-titles-if-needed.mjs
@@ -126,6 +128,13 @@ cli:
         - url: ./agents/history/view.mjs
           name: view
           alias: ["log", "list"]
+    - name: add-document
+      alias: ["add"]
+      url: ./agents/create/user-add-document/index.yaml
+    - name: remove-document
+      alias: ["remove", "rm"]
+      url: ./agents/create/user-remove-document/index.yaml
+    - ./agents/clear/index.yaml
 mcp_server:
   agents:
     - ./docs-mcp/get-docs-structure.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.9.6-beta",
+  "version": "0.9.6-beta.2",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"

package/prompts/detail/custom/custom-components/x-cards-usage-rules.md

@@ -5,7 +5,7 @@ XCards is multiple `<x-card>` container, suitable for displaying multiple links
 
 ### Attributes
 
-- `data-columns` (optional): Must be an **integer ≥ 2**. Values below 2 are disallowed. Default is 2.
+- `data-columns` (required): must be an integer ≥ 2; no upper bound.
 
 ### Children
 
@@ -20,20 +20,21 @@ XCards is multiple `<x-card>` container, suitable for displaying multiple links
 
 ### Good Examples
 
-- Example 1: Three-column cards with icons
+- Example 1: Two-column cards with images
   ```md
-  <x-cards data-columns="3">
-    <x-card data-title="Feature 1" data-icon="lucide:rocket">Description of Feature 1.</x-card>
-    <x-card data-title="Feature 2" data-icon="lucide:bolt">Description of Feature 2.</x-card>
-    <x-card data-title="Feature 3" data-icon="material-symbols:rocket-outline">Description of Feature 3.</x-card>
+  <x-cards data-columns="2">
+    <x-card data-title="Card A" data-image="https://picsum.photos/id/10/300/300">Content A</x-card>
+    <x-card data-title="Card B" data-image="https://picsum.photos/id/11/300/300">Content B</x-card>
   </x-cards>
   ```
 
-- Example 2: Two-column cards with images
+- Example 2: Four-column cards with icons
   ```md
-  <x-cards data-columns="2">
-    <x-card data-title="Card A" data-image="https://picsum.photos/id/10/300/300">Content A</x-card>
-    <x-card data-title="Card B" data-image="https://picsum.photos/id/11/300/300">Content B</x-card>
+  <x-cards data-columns="4">
+    <x-card data-title="Feature 1" data-icon="lucide:rocket">Description of Feature 1.</x-card>
+    <x-card data-title="Feature 2" data-icon="lucide:bolt">Description of Feature 2.</x-card>
+    <x-card data-title="Feature 3" data-icon="material-symbols:rocket-outline">Description of Feature 3.</x-card>
+    <x-card data-title="Feature 4" data-icon="lucide:star">Description of Feature 4.</x-card>
   </x-cards>
   ```
 
@@ -72,4 +73,11 @@ XCards is multiple `<x-card>` container, suitable for displaying multiple links
   - [Using the Blog](./blog.md)
   - [Using Chat](./chat.md)
   ```
+
+- Example 4: Missing `data-columns` attribute (required)
+  <x-cards>
+    <x-card data-title="Feature 1" data-icon="lucide:rocket">Description of Feature 1.</x-card>
+    <x-card data-title="Feature 2" data-icon="lucide:bolt">Description of Feature 2.</x-card>
+  </x-cards>
+  
 </x-card-usage-rules>

package/prompts/structure/find-documents-to-add-links.md

@@ -0,0 +1,52 @@
+# Task: Find Documents to Add Links
+
+Determine which existing documents should link to newly added documents.
+
+## Input
+
+<documentStructure>
+{{originalDocumentStructure}}
+</documentStructure>
+
+<newDocuments>
+{{newDocuments}}
+</newDocuments>
+
+<userFeedback>
+{{allFeedback}}
+</userFeedback>
+
+## Steps
+
+1. **Check <userFeedback> first.**  
+   - If users explicitly specify linking (e.g., “link FAQ from About”), follow exactly.
+2. **Analyze <documentStructure>.**  
+   Identify existing documents that should link to those in <newDocuments> using the rules below.
+3. For each qualifying document, add a non-empty `newLinks` array containing new document paths.
+4. Output only these updated documents (subset of <documentStructure>) as `documentsWithNewLinks`.
+
+Each item in `documentsWithNewLinks` must:
+- Be an existing document from <documentStructure>
+- Retain all original properties (`path`, `title`, `description`, `parentId`, `icon`, `sourceIds`)
+- Include `newLinks: string[]`
+
+## Linking Rules (in priority order)
+
+1. **User Instructions** — Follow explicit <userFeedback>.  
+2. **Parent–Child** — If a new document’s `parentId` equals a document’s `path`, the parent links to it.  
+3. **Semantic Similarity** — Link thematically related documents (e.g., “About” ↔ “Team”).  
+4. **Navigation Context** — Documents in the same navigation group may link.  
+5. **Hierarchy** — Sibling or section documents may cross-link.  
+6. **Relevance** — Add links only when it improves navigation logically.
+
+## Output Format
+
+```json
+{
+  "documentsWithNewLinks": [
+    {
+      "path": "/existing-document",
+      "newLinks": ["/new-document-1", "/new-document-2"]
+    }
+  ]
+}

package/prompts/utils/analyze-document-feedback-intent.md

@@ -0,0 +1,54 @@
+<role>
+You are a feedback intent analyzer for **document content modifications**. Your task is to determine the intent type of user feedback regarding content-level operations inside a document, and whether external data sources are needed.
+</role>
+
+<input>
+feedback: {{feedback}}
+</input>
+
+<analysis_rules>
+If the feedback contains any document-level (structure) operations, return an error (document content edits cannot include structure changes).
+
+Scope: Only analyze feedback related to document content (e.g. sections, text, images).  
+
+**Intent types:**
+
+1. add - Adding new sections or content inside a document
+2. edit - Modifying existing content, titles, descriptions, components
+3. delete - Removing sections or content
+4. move - Moving sections to different positions within the document
+5. reorder - Changing the order of sections at the same level
+6. mixed - Combination of multiple intent types
+
+**Data source rules:**
+
+- add/edit -> needDataSources = true
+- delete/move/reorder -> needDataSources = false
+- mixed -> needDataSources = true if any add/edit is included
+
+**Decision logic:**
+
+- Only consider document content operations.
+- If any add or edit operation exists -> needDataSources = true
+- If only delete, move, or reorder operations exist -> needDataSources = false
+- When uncertain, default to needDataSources = true
+</analysis_rules>
+
+<output_rules>
+Normal output:
+
+{
+  "error": false,
+  "needDataSources": boolean,
+  "intentType": "add" | "edit" | "delete" | "move" | "reorder" | "mixed",
+  "reason": "Explanation of why data sources are or aren't needed based on page content operations."
+}
+
+Error output (if document-level operations are detected):
+
+{
+  "error": true,
+  "needDataSources": false,
+  "reason": "Feedback mixes document-content edits with document-structure operations. When analyzing document content, structure changes are not allowed. Please split into separate feedback items."
+}
+</output_rules>

package/prompts/utils/analyze-structure-feedback-intent.md

@@ -0,0 +1,43 @@
+<role>
+You are a feedback intent analyzer for **document structure modifications**. Your task is to determine the intent type of user feedback regarding document-level operations and whether external data sources are needed.
+</role>
+
+<input>
+feedback: {{feedback}}
+</input>
+
+<analysis_rules>
+Scope: Only analyze feedback related to document structure. Ignore any content-level operations inside document (e.g. sections, text, images).
+
+**intent types:**
+
+1. add - Adding new documents
+2. edit - Modifying document-level properties (e.g., path, parentId, title of the document itself)
+3. delete - Removing documents
+4. move - Moving documents to different positions or parent sections
+5. reorder - Changing the order of documents
+6. mixed - Combination of multiple intent types
+
+**Data source rules:**
+
+- add/edit -> needDataSources = true
+- delete/move/reorder -> needDataSources = false
+- mixed -> needDataSources = true if any add/edit is included
+
+**Decision logic:**
+
+- Only consider document-level operations in the feedback.
+- If any add or edit operation exists -> needDataSources = true
+- If only delete, move, or reorder operations exist -> needDataSources = false
+- When uncertain, default to needDataSources = true
+</analysis_rules>
+
+<output_rules>
+Return a JSON object:
+
+{
+  "needDataSources": boolean,
+  "intentType": "add" | "edit" | "delete" | "move" | "reorder" | "mixed",
+  "reason": "Explanation of why data sources are or aren't needed based on document-level operations."
+}
+</output_rules>

package/types/document-schema.mjs

@@ -4,6 +4,7 @@ import { zodToJsonSchema } from "zod-to-json-schema";
 // Update document content schemas
 export const updateDocumentContentInputSchema = z.object({
   diffPatch: z.string().min(1, "Diff patch is required"),
+  path: z.string().min(1, "Path is required for concurrent document updates"),
 });
 
 export const updateDocumentContentOutputSchema = z.object({
@@ -18,6 +19,7 @@ export const getUpdateDocumentContentInputJsonSchema = () => {
   const schema = zodToJsonSchema(updateDocumentContentInputSchema);
   if (schema.properties) {
     schema.properties.diffPatch.description = "Diff patch string to apply to the original content";
+    schema.properties.path.description = "Document path";
   }
   return schema;
 };

package/types/document-structure-schema.mjs

@@ -33,12 +33,13 @@ export const addDocumentOutputSchema = z.object({
 // Delete document schemas
 export const deleteDocumentInputSchema = z.object({
   path: z.string().min(1, "Path is required"),
+  recursive: z.boolean().optional(),
 });
 
 export const deleteDocumentOutputSchema = z.object({
   documentStructure: documentStructureSchema,
   message: z.string().optional(),
-  deletedDocument: documentItemSchema.optional(),
+  deletedDocuments: z.array(documentItemSchema).optional(),
   error: z.object({ message: z.string() }).optional(),
 });
 
@@ -113,6 +114,8 @@ export const getDeleteDocumentInputJsonSchema = () => {
   const schema = zodToJsonSchema(deleteDocumentInputSchema);
   if (schema.properties) {
     schema.properties.path.description = "URL path of the document to delete";
+    schema.properties.recursive.description =
+      "If true, recursively delete all child documents. If false or not provided, deletion will fail if child documents exist.";
   }
   return schema;
 };
@@ -123,7 +126,8 @@ export const getDeleteDocumentOutputJsonSchema = () => {
     schema.properties.documentStructure.description =
       "Updated documentation structure array with the document removed";
     schema.properties.message.description = "Success message describing the operation result";
-    schema.properties.deletedDocument.description = "The deleted document object";
+    schema.properties.deletedDocuments.description =
+      "Array of deleted document objects (includes all recursively deleted child documents if recursive=true)";
     schema.properties.error.description =
       "Error object containing error message if operation failed";
   }

package/utils/docs-finder-utils.mjs

@@ -1,5 +1,7 @@
 import { access, readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
+import chalk from "chalk";
+import pLimit from "p-limit";
 import { pathExists } from "./file-utils.mjs";
 
 /**
@@ -324,6 +326,40 @@ export async function loadDocumentStructure(outputDir) {
   }
 }
 
+/**
+ * Build allowed links set from document structure
+ * Includes both original paths and processed .md paths for link validation
+ * @param {Array} documentStructure - Array of documentation structure items with path property
+ * @returns {Set<string>} Set of allowed link paths
+ */
+export function buildAllowedLinksFromStructure(documentStructure) {
+  const allowedLinks = new Set();
+
+  if (!Array.isArray(documentStructure)) {
+    return allowedLinks;
+  }
+
+  documentStructure.forEach((item) => {
+    if (!item?.path) {
+      return;
+    }
+
+    // Add original path
+    allowedLinks.add(item.path);
+
+    // Add processed .md path (same logic as processContent in utils.mjs)
+    let processedPath = item.path;
+    if (processedPath.startsWith(".")) {
+      processedPath = processedPath.replace(/^\./, "");
+    }
+    let flatPath = processedPath.replace(/^\//, "").replace(/\//g, "-");
+    flatPath = `./${flatPath}.md`;
+    allowedLinks.add(flatPath);
+  });
+
+  return allowedLinks;
+}
+
 /**
  * Build a tree structure from a flat document structure array using parentId
  * @param {Array} documentStructure - Flat array of document structure items with path and parentId
@@ -358,3 +394,128 @@ export function buildDocumentTree(documentStructure) {
 
   return { rootNodes, nodeMap };
 }
+
+/**
+ * Build checkbox choices from tree structure with visual hierarchy
+ * @param {Array} nodes - Array of tree nodes
+ * @param {string} prefix - Current prefix for indentation
+ * @param {number} depth - Current depth level (0 for root)
+ * @param {Object} context - Context object containing locale, docsDir, etc.
+ * @param {string} context.locale - Main language locale (e.g., 'en', 'zh', 'fr')
+ * @param {string} [context.docsDir] - Docs directory path for file existence check
+ * @returns {Promise<Array>} Array of choice objects
+ */
+export async function buildChoicesFromTree(nodes, prefix = "", depth = 0, context = {}) {
+  const { locale = "en", docsDir } = context;
+  const choices = [];
+
+  // Limit concurrent file checks to 50 per level to avoid overwhelming the file system
+  const limit = pLimit(50);
+
+  // Process nodes with controlled concurrency while maintaining order
+  const nodePromises = nodes.map((node, i) =>
+    limit(async () => {
+      const isLastSibling = i === nodes.length - 1;
+      const hasChildren = node.children && node.children.length > 0;
+
+      // Build the tree prefix - top level nodes don't have ├─ or └─
+      const treePrefix = depth === 0 ? "" : prefix + (isLastSibling ? "└─ " : "├─ ");
+      const flatName = pathToFlatName(node.path);
+      const filename = generateFileName(flatName, locale);
+
+      // Check file existence if docsDir is provided
+      let fileExists = true;
+      let missingFileText = "";
+      if (docsDir) {
+        const filePath = join(docsDir, filename);
+        fileExists = await pathExists(filePath);
+        if (!fileExists) {
+          missingFileText = chalk.red(" - file not found");
+        }
+      }
+
+      // warningText only shows when file exists, missingFileText has higher priority
+      const warningText =
+        fileExists && hasChildren ? chalk.yellow(" - will cascade delete all child documents") : "";
+
+      const displayName = `${treePrefix}${node.title} (${filename})${warningText}${missingFileText}`;
+
+      const choice = {
+        name: displayName,
+        value: node.path,
+        short: node.title,
+        disabled: !fileExists,
+      };
+
+      // Recursively process children
+      let childChoices = [];
+      if (hasChildren) {
+        const childPrefix = depth === 0 ? "" : prefix + (isLastSibling ? "   " : "│  ");
+        childChoices = await buildChoicesFromTree(node.children, childPrefix, depth + 1, context);
+      }
+
+      return { choice, childChoices };
+    }),
+  );
+
+  // Wait for all nodes at this level to complete, maintaining order
+  const results = await Promise.all(nodePromises);
+
+  // Build choices array in order
+  for (const { choice, childChoices } of results) {
+    choices.push(choice);
+    if (childChoices.length > 0) {
+      choices.push(...childChoices);
+    }
+  }
+
+  return choices;
+}
+
+/**
+ * Format document structure for printing
+ * @param {Array} structure - Document structure array
+ * @returns {Object} Object containing rootNodes and printNode function
+ */
+function formatDocumentStructure(structure) {
+  const { rootNodes } = buildDocumentTree(structure);
+
+  function printNode(node, depth = 0) {
+    const INDENT_SPACES = "  ";
+    const FOLDER_ICON = "  📁";
+    const FILE_ICON = "  📄";
+    const indent = INDENT_SPACES.repeat(depth);
+    const prefix = depth === 0 ? FOLDER_ICON : FILE_ICON;
+
+    console.log(`${indent}${prefix} ${node.title}`);
+
+    if (node.children && node.children.length > 0) {
+      node.children.forEach((child) => {
+        printNode(child, depth + 1);
+      });
+    }
+  }
+
+  return { rootNodes, printNode };
+}
+
+/**
+ * Print document structure in a user-friendly format
+ * @param {Array} structure - Document structure array
+ */
+export function printDocumentStructure(structure) {
+  console.log(`\n  ${"-".repeat(50)}`);
+  console.log("  Current Documentation Structure");
+  console.log(`  ${"-".repeat(50)}`);
+
+  const { rootNodes, printNode } = formatDocumentStructure(structure);
+
+  if (rootNodes.length === 0) {
+    console.log("  No documentation structure found.");
+  } else {
+    rootNodes.forEach((node) => {
+      printNode(node);
+    });
+  }
+  console.log();
+}