@aigne/doc-smith 0.8.10 → 0.8.11-beta.1

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

@@ -0,0 +1,15 @@
+type: team
+name: updateSingleDocument
+skills:
+  - ../update/user-review-document.mjs
+  - type: transform
+    task_render_mode: hide
+    jsonata: |
+      $merge([
+        $,
+        { "feedback": "" }
+      ])
+  - ../translate/translate-multilingual.yaml
+  - ../utils/save-single-doc.mjs
+iterate_on: selectedDocs
+concurrency: 1

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

@@ -0,0 +1,248 @@
+import { marked } from "marked";
+import markedTerminal from "marked-terminal";
+import { getActiveRulesForScope } from "../../utils/preferences-utils.mjs";
+
+function extractMarkdownHeadings(content) {
+  if (!content || typeof content !== "string") {
+    return [];
+  }
+
+  const headings = [];
+
+  try {
+    // Use marked's lexer to tokenize the content
+    const tokens = marked.lexer(content);
+
+    // Extract heading tokens
+    function processTokens(tokenArray) {
+      for (const token of tokenArray) {
+        if (token.type === "heading") {
+          headings.push({
+            level: token.depth,
+            text: token.text.trim(),
+            prefix: "  ".repeat(token.depth - 1) + "📄".repeat(1),
+          });
+        }
+        // Process nested tokens if they exist (for lists, block quotes, etc.)
+        if (token.tokens) {
+          processTokens(token.tokens);
+        }
+      }
+    }
+
+    processTokens(tokens);
+  } catch (error) {
+    // If marked fails, fall back to regex but log the issue
+    console.warn(
+      "Failed to parse markdown with marked library, falling back to regex:",
+      error.message,
+    );
+    return extractMarkdownHeadingsFallback(content);
+  }
+
+  return headings;
+}
+
+// Fallback function using the original regex approach
+function extractMarkdownHeadingsFallback(content) {
+  const lines = content.split("\n");
+  const headings = [];
+
+  for (const line of lines) {
+    const match = line.match(/^(#{1,6})\s+(.+)$/);
+    if (match) {
+      const level = match[1].length;
+      const text = match[2].trim();
+      headings.push({
+        level,
+        text,
+        prefix: "  ".repeat(level - 1) + "📄".repeat(1),
+      });
+    }
+  }
+
+  return headings;
+}
+
+function printDocumentHeadings(content, title) {
+  console.log(`\n  ${"-".repeat(50)}`);
+  console.log(`  Current Document: ${title}`);
+  console.log(`  ${"-".repeat(50)}`);
+
+  const headings = extractMarkdownHeadings(content);
+
+  if (headings.length === 0) {
+    console.log("  This document has no headings.");
+  } else {
+    headings.forEach((heading) => {
+      console.log(`${heading.prefix} ${heading.text} (H${heading.level})`);
+    });
+  }
+  console.log();
+}
+
+async function showDocumentDetail(content, title) {
+  if (!content || typeof content !== "string" || content.trim().length === 0) {
+    console.log("There's no content to display.");
+    return;
+  }
+
+  try {
+    // Temporarily suppress console.error to hide language warnings
+    const originalError = console.error;
+    console.error = (message) => {
+      // Only suppress cli-highlight language warnings
+      if (
+        typeof message === "string" &&
+        message.toLowerCase().includes("Could not find the language")
+      ) {
+        return;
+      }
+      originalError(message);
+    };
+
+    marked.setOptions({
+      renderer: new markedTerminal(),
+    });
+
+    const renderedMarkdown = marked(content);
+
+    // Restore original console.error
+    console.error = originalError;
+
+    console.log(`\nDocument: ${title || "Untitled Document"}`);
+    console.log("=".repeat(50));
+    console.log(renderedMarkdown);
+  } catch (_error) {
+    console.log("\nFalling back to plain text display (marked-terminal not available):\n");
+    console.log(`Document: ${title || "Untitled Document"}`);
+    console.log("=".repeat(50));
+    console.log(content);
+  }
+}
+
+export default async function userReviewDocument(
+  { content, title, 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 };
+  }
+
+  // Print current document headings structure
+  printDocumentHeadings(content, title || "Untitled Document");
+
+  let currentContent = content;
+
+  const MAX_ITERATIONS = 100;
+  let iterationCount = 0;
+  while (iterationCount < MAX_ITERATIONS) {
+    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 (action === "finish") {
+      break;
+    } else if (action === "view") {
+      await showDocumentDetail(currentContent, title || "Untitled Document");
+    }
+
+    // Ask for feedback
+    const feedback = await options.prompts.input({
+      message:
+        "How would you like to improve this document?\n" +
+        "  • Add, modify, or remove content\n" +
+        "  • Improve clarity, accuracy, or completeness\n" +
+        "  • Adjust tone, style, or technical level\n\n" +
+        "  Your feedback:",
+    });
+
+    // If no feedback, finish the loop
+    if (!feedback?.trim()) {
+      break;
+    }
+
+    // Get the updateDocument agent
+    const updateAgent = options.context.agents["updateDocumentDetail"];
+    if (!updateAgent) {
+      console.log(
+        "We can't process your feedback right now. The document update feature is temporarily unavailable.",
+      );
+      console.log("Please try again later or contact support if this continues.");
+      break;
+    }
+
+    // Get user preferences
+    const contentRules = getActiveRulesForScope("document", [rest.path]);
+    const globalRules = getActiveRulesForScope("global");
+    const allApplicableRules = [...contentRules, ...globalRules];
+    const ruleTexts = allApplicableRules.map((rule) => rule.rule);
+    const userPreferences = ruleTexts.length > 0 ? ruleTexts.join("\n\n") : "";
+
+    try {
+      // Call updateDocument agent with feedback
+      const result = await options.context.invoke(updateAgent, {
+        ...rest,
+        originalContent: currentContent,
+        feedback: feedback.trim(),
+        userPreferences,
+      });
+
+      if (result.updatedContent) {
+        currentContent = result.updatedContent;
+        console.log(`\n✅ ${result.operationSummary || "Document updated successfully"}\n`);
+      } else {
+        console.log("\n❌ We couldn't update the document. Please try rephrasing your feedback.\n");
+      }
+
+      // Check if feedback should be saved as user preference
+      const feedbackRefinerAgent = options.context.agents["checkFeedbackRefiner"];
+      if (feedbackRefinerAgent) {
+        try {
+          await options.context.invoke(feedbackRefinerAgent, {
+            documentContentFeedback: feedback.trim(),
+            stage: "document_refine",
+          });
+        } catch (refinerError) {
+          console.warn("We couldn't save your feedback as a preference:", refinerError.message);
+          console.warn("Your feedback was applied, but we couldn't save it as a preference.");
+        }
+      }
+
+      // Print updated document headings structure
+      printDocumentHeadings(currentContent, title || "Untitled Document");
+    } catch (error) {
+      console.error("Error processing your feedback:");
+      console.error(`Type: ${error.name}`);
+      console.error(`Message: ${error.message}`);
+      if (error.stack) {
+        console.error(`Stack: ${error.stack}`);
+      }
+      console.log("\nPlease try rephrasing your feedback or continue with the current content.");
+      break;
+    }
+  }
+
+  return { content: currentContent };
+}
+
+userReviewDocument.taskTitle = "User review and modify document content";

package/agents/utils/choose-docs.mjs

@@ -16,6 +16,7 @@ export default async function chooseDocs(
     feedback,
     locale,
     reset = false,
+    requiredFeedback = true,
   },
   options,
 ) {
@@ -102,8 +103,9 @@ export default async function chooseDocs(
 
   // Prompt for feedback if not provided
   let userFeedback = feedback;
-  if (!userFeedback) {
-    const feedbackMessage = "How should we improve this document? (press Enter to skip):";
+  if (!userFeedback && (requiredFeedback || foundItems?.length > 1)) {
+    const feedbackMessage =
+      "How should we improve this document? (Enter to skip, will auto-update from content sources):";
 
     userFeedback = await options.prompts.input({
       message: feedbackMessage,

package/agents/utils/format-document-structure.mjs

@@ -1,8 +1,18 @@
 import { stringify } from "yaml";
 
-export default async function formatDocumentStructure({ documentStructure }) {
+export default async function formatDocumentStructure({
+  documentStructure,
+  originalDocumentStructure,
+}) {
+  if (!documentStructure && !originalDocumentStructure) {
+    return {
+      documentStructureYaml: "",
+      documentStructure: [],
+    };
+  }
+
   // Extract required fields from each item in documentStructure
-  const formattedData = documentStructure.map((item) => ({
+  const formattedData = (documentStructure || originalDocumentStructure)?.map((item) => ({
     title: item.title,
     path: item.path,
     parentId: item.parentId,

package/agents/utils/load-document-all-content.mjs

@@ -0,0 +1,84 @@
+import { readdirSync } from "node:fs";
+import { findItemByPath, readFileContent } from "../../utils/docs-finder-utils.mjs";
+
+/**
+ * Loads a document's content along with all its translations from the docs directory.
+ *
+ * This function finds a document by its path in the document structure, then searches
+ * for all translation files in the docs directory that match the document's naming pattern.
+ * Translation files are identified by the pattern: {flatName}.{language-code}.md
+ *
+ * @param {Object} params - The parameters object
+ * @param {string} params.path - The document path to find in the structure
+ * @param {string} params.docsDir - The directory containing document files and translations
+ * @param {Object} params.documentStructure - The document structure object to search in
+ * @returns {Promise<Object>} An object containing the document data with translations
+ * @throws {Error} Throws an error if the document path is not found in the structure
+ */
+export default async function loadDocumentAllContent({ path, docsDir, documentStructure }) {
+  // Find the document item by path in the document structure
+  const result = await findItemByPath(documentStructure, path, null, docsDir);
+
+  if (!result) {
+    throw new Error(`Document with path "${path}" not found in documentStructure`);
+  }
+
+  // Convert path to flat filename format (remove leading slash, replace slashes with dashes)
+  // e.g., "/api/users" becomes "api-users"
+  const flatName = result.path.replace(/^\//, "").replace(/\//g, "-");
+
+  // Arrays to store translation data in different formats
+  const translations = [];
+  const translationsString = [];
+
+  try {
+    // Read all files in the docs directory
+    const files = readdirSync(docsDir);
+
+    // Filter files to find translation files matching the pattern:
+    // - Starts with the flat name
+    // - Ends with .md
+    // - Is not the main document file (flatName.md)
+    // - Matches language pattern: .{language-code}.md (e.g., .en.md, .zh-CN.md)
+    const translationFiles = files.filter(
+      (file) =>
+        file.startsWith(`${flatName}.`) &&
+        file.endsWith(".md") &&
+        file !== `${flatName}.md` &&
+        file.match(/\.\w+(-\w+)?\.md$/),
+    );
+
+    // Process each translation file
+    for (const file of translationFiles) {
+      const content = await readFileContent(docsDir, file);
+      if (content) {
+        // Extract language code from filename (e.g., "en" from "doc.en.md" or "zh-CN" from "doc.zh-CN.md")
+        const langMatch = file.match(/\.(\w+(-\w+)?)\.md$/);
+        if (langMatch) {
+          const language = langMatch[1];
+          // Store translation in structured format
+          translations.push({
+            language,
+            translation: content,
+          });
+
+          // Store translation in XML-like string format for prompt templates
+          translationsString.push(`<${language}>\n${content}\n</${language}>`);
+        }
+      }
+    }
+  } catch (error) {
+    console.warn(`⚠️  Could not read translation files from ${docsDir}:`, error.message);
+  }
+
+  // Return the original document result enhanced with translation data
+  return {
+    ...result,
+    // FIXME: @zhanghan use anthoer way to evaluate translationQuality
+    // translates: translations, // Array of translation objects with language and content
+    translationsString: translationsString.join("\n\n"), // Combined translations as formatted string
+  };
+}
+
+// Hide this function from task rendering in the UI
+loadDocumentAllContent.taskRenderMode = "hide";

package/agents/utils/load-sources.mjs

@@ -1,6 +1,9 @@
 import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
-import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_INCLUDE_PATTERNS } from "../../utils/constants.mjs";
+import {
+  DEFAULT_EXCLUDE_PATTERNS,
+  DEFAULT_INCLUDE_PATTERNS,
+} from "../../utils/constants/index.mjs";
 import { getFilesWithGlob, loadGitignore } from "../../utils/file-utils.mjs";
 import {
   getCurrentGitHead,

package/aigne.yaml

@@ -6,41 +6,79 @@ chat_model:
   # name: gemini-2.5-flash
   temperature: 0.8
 agents:
+  # Initialization
+  - ./agents/init/index.mjs
+
+  # Document Structure Generation
   - ./agents/generate/generate-structure.yaml
-  - ./agents/update/batch-generate-document.yaml
-  - ./agents/utils/load-sources.mjs
-  - ./agents/utils/save-docs.mjs
-  - ./agents/translate/translate-document.yaml
-  - ./agents/update/generate-and-translate-document.yaml
-  - ./agents/update/check-document.mjs
-  - ./agents/utils/transform-detail-datasources.mjs
-  - ./agents/translate/translate-multilingual.yaml
-  - ./agents/utils/save-single-doc.mjs
-  - ./agents/utils/save-output.mjs
+  - ./agents/generate/update-document-structure.yaml
   - ./agents/generate/check-need-generate-structure.mjs
-  - ./agents/update/generate-document.yaml
   - ./agents/generate/refine-document-structure.yaml
   - ./agents/generate/check-document-structure.yaml
-  - ./agents/init/index.mjs
+  - ./agents/generate/user-review-document-structure.mjs
   - ./agents/generate/index.yaml
+  
+  # Document Structure Tools
+  - ./agents/generate/document-structure-tools/add-document.mjs
+  - ./agents/generate/document-structure-tools/delete-document.mjs
+  - ./agents/generate/document-structure-tools/update-document.mjs
+  - ./agents/generate/document-structure-tools/move-document.mjs
+
+  # Document Content Generation & Updates
+  - ./agents/update/batch-generate-document.yaml
+  - ./agents/update/generate-document.yaml
+  - ./agents/update/generate-and-translate-document.yaml
+  - ./agents/update/check-document.mjs
+  - ./agents/update/update-document-detail.yaml
+  - ./agents/update/user-review-document.mjs
+  - ./agents/update/batch-update-document.yaml
+  - ./agents/update/update-single-document.yaml
+  - ./agents/update/check-update-is-single.mjs
   - ./agents/update/index.yaml
+
+
+  # Translation
+  - ./agents/translate/translate-document.yaml
+  - ./agents/translate/translate-multilingual.yaml
+  - ./agents/translate/choose-language.mjs
+  - ./agents/translate/index.yaml
+
+  # Publishing
   - ./agents/publish/publish-docs.mjs
-  - ./agents/utils/format-document-structure.mjs
   - ./agents/publish/index.yaml
+
+  # Clear/Cleanup
+  - ./agents/clear/choose-contents.mjs
+  - ./agents/clear/clear-document-structure.mjs
+  - ./agents/clear/clear-generated-docs.mjs
+  - ./agents/clear/clear-document-config.mjs
+  - ./agents/clear/clear-auth-tokens.mjs
+
+  # Utilities
+  - ./agents/utils/load-sources.mjs
+  - ./agents/utils/save-docs.mjs
+  - ./agents/utils/transform-detail-datasources.mjs
+  - ./agents/utils/save-single-doc.mjs
+  - ./agents/utils/save-output.mjs
+  - ./agents/utils/format-document-structure.mjs
   - ./agents/utils/find-item-by-path.mjs
-  - ./agents/translate/index.yaml
-  - ./agents/translate/choose-language.mjs
+  - ./agents/utils/check-feedback-refiner.mjs
+  - ./agents/utils/feedback-refiner.yaml
+
+  # User Preferences & Chat
+  - ./agents/prefs/index.mjs
+  - ./agents/chat/index.yaml
+
+  # Documentation MCP Server
   - ./docs-mcp/get-docs-structure.mjs
   - ./docs-mcp/get-docs-detail.mjs
   - ./docs-mcp/docs-search.yaml
   - ./docs-mcp/analyze-docs-relevance.yaml
   - ./docs-mcp/read-doc-content.mjs
   - ./docs-mcp/analyze-content-relevance.yaml
-  - ./agents/utils/check-feedback-refiner.mjs
-  - ./agents/utils/feedback-refiner.yaml
-  - ./agents/prefs/index.mjs
-  - ./agents/chat/index.yaml
-  - ./agents/generate/user-review-document-structure.mjs
+
+  # Evaluation
+  - ./agents/evaluate/index.yaml
 cli:
   chat: ./agents/chat/index.yaml
   agents:
@@ -49,6 +87,7 @@ cli:
     - ./agents/update/index.yaml
     - ./agents/publish/index.yaml
     - ./agents/translate/index.yaml
+    - ./agents/clear/index.yaml
     - ./agents/prefs/index.mjs
 mcp_server:
   agents: