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

package/.github/workflows/publish-docs.yml

@@ -2,6 +2,7 @@ name: publish docs
 
 env:
   GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
 
 permissions:
   contents: write

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.8.11"
+  ".": "0.8.12-beta.1"
 }

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.8.12-beta.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.12-beta...v0.8.12-beta.1) (2025-10-08)
+
+
+### Features
+
+* add history tracking and make translation optional during update ([#165](https://github.com/AIGNE-io/aigne-doc-smith/issues/165)) ([e1d3d97](https://github.com/AIGNE-io/aigne-doc-smith/commit/e1d3d97c7e57c1c663c0478870aab7421de9d4bc))
+
+
+### Bug Fixes
+
+* split generate/update document & structure to system & user ([#159](https://github.com/AIGNE-io/aigne-doc-smith/issues/159)) ([ad1802d](https://github.com/AIGNE-io/aigne-doc-smith/commit/ad1802d1aecefc414ab3d1217a9ba31655479e86))
+
+## [0.8.12-beta](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.11...v0.8.12-beta) (2025-10-07)
+
+
+### Bug Fixes
+
+* read file tool should support relative path ([#162](https://github.com/AIGNE-io/aigne-doc-smith/issues/162)) ([cf1291b](https://github.com/AIGNE-io/aigne-doc-smith/commit/cf1291b0be5b51db15d052310c30b0552a4092e1))
+
 ## [0.8.11](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.11-beta.7...v0.8.11) (2025-10-05)
 
 

package/agents/generate/check-diagram.mjs

@@ -0,0 +1,40 @@
+import { checkContent } from "../../utils/d2-utils.mjs";
+
+export default async function checkD2DiagramIsValid({ diagramSourceCode }) {
+  try {
+    await checkContent({ content: diagramSourceCode });
+    return {
+      isValid: true,
+    };
+  } catch (err) {
+    return {
+      isValid: false,
+      error: err.message,
+    };
+  }
+}
+
+checkD2DiagramIsValid.input_schema = {
+  type: "object",
+  properties: {
+    diagramSourceCode: {
+      type: "string",
+      description: "Source code of d2 diagram",
+    },
+  },
+  required: ["diagramSourceCode"],
+};
+checkD2DiagramIsValid.output_schema = {
+  type: "object",
+  properties: {
+    isValid: {
+      type: "boolean",
+      description: "Indicates whether the provided d2 diagram source passes validation",
+    },
+    error: {
+      type: "string",
+      description: "Validation error details when the diagram does not pass",
+    },
+  },
+  required: ["isValid"],
+};

package/agents/generate/draw-diagram.yaml

@@ -0,0 +1,23 @@
+name: drawDiagram
+description: Generate a D2 diagram from document content.
+instructions:
+  - role: system
+    url: ../../prompts/detail/d2-diagram/system-prompt.md
+  - role: user
+    url: ../../prompts/detail/d2-diagram/user-prompt.md
+input_schema:
+  type: object
+  properties:
+    documentContent:
+      type: string
+      description: The **raw text content** of the current document. (**Note:** This is the original document and **does not include** any existing diagram source code.)
+  required:
+    - documentContent
+output_schema:
+  type: object
+  properties:
+    diagramSourceCode:
+      type: string
+      description: The **diagram source code** generated from the input text.
+  required:
+    - diagramSourceCode

package/agents/generate/generate-structure.yaml

@@ -1,7 +1,11 @@
 name: generateStructure
 description: Generate the structure and organization of your documentation
 instructions:
-  url: ../../prompts/structure/generate-structure-system.md
+  - role: system
+    url: ../../prompts/structure/generate/system-prompt.md
+  - role: user
+    url: ../../prompts/structure/generate/user-prompt.md
+
 input_schema:
   type: object
   properties:

package/agents/generate/merge-d2-diagram.yaml

@@ -7,7 +7,7 @@ instructions: |
   {{ content }}
   </datasources>
   <datasources>
-  {{ d2DiagramSourceCode }}
+  {{ diagramSourceCode }}
   </datasources>
 
   Given the source content of a document and the D2 diagram source code, your task is to:
@@ -22,12 +22,12 @@ input_schema:
     content:
       type: string
       description: Source content of the document
-    d2DiagramSourceCode:
+    diagramSourceCode:
       type: string
       description: Source content of D2 Diagram
   required:
     - content
-    - d2DiagramSourceCode
+    - diagramSourceCode
 output_schema:
   type: object
   properties:

package/agents/generate/update-document-structure.yaml

@@ -2,7 +2,10 @@ type: ai
 name: updateDocumentStructure
 description: Update documentation structure based on user feedback and intentions using structure modification tools
 instructions:
-  url: ../../prompts/structure/update-document-structure.md
+  - role: system
+    url: ../../prompts/structure/update/system-prompt.md
+  - role: user
+    url: ../../prompts/structure/update/user-prompt.md
 input_schema:
   type: object
   properties:
@@ -33,4 +36,4 @@ skills:
   - ./document-structure-tools/add-document.mjs
   - ./document-structure-tools/delete-document.mjs
   - ./document-structure-tools/update-document.mjs
-  - ./document-structure-tools/move-document.mjs
+  - ./document-structure-tools/move-document.mjs

package/agents/generate/user-review-document-structure.mjs

@@ -1,4 +1,5 @@
 import { getActiveRulesForScope } from "../../utils/preferences-utils.mjs";
+import { recordUpdate } from "../../utils/history-utils.mjs";
 
 function formatDocumentStructure(structure) {
   // Build a tree structure for better display
@@ -158,6 +159,12 @@ export default async function userReviewDocumentStructure({ documentStructure, .
         }
       }
 
+      // Record update in history
+      recordUpdate({
+        operation: "structure_update",
+        feedback: feedback.trim(),
+      });
+
       // Print current documentation structure in a user-friendly format
       printDocumentStructure(currentStructure);
     } catch (error) {

package/agents/generate/wrap-diagram-code.mjs

@@ -0,0 +1,35 @@
+import { wrapCode } from "../../utils/d2-utils.mjs";
+
+export default async function wrapDiagramCode({ diagramSourceCode }) {
+  try {
+    const result = await wrapCode({ content: diagramSourceCode });
+    return {
+      diagramSourceCode: result,
+    };
+  } catch {
+    return {
+      diagramSourceCode,
+    };
+  }
+}
+
+wrapDiagramCode.input_schema = {
+  type: "object",
+  properties: {
+    diagramSourceCode: {
+      type: "string",
+      description: "Source code of d2 diagram",
+    },
+  },
+  required: ["diagramSourceCode"],
+};
+wrapDiagramCode.output_schema = {
+  type: "object",
+  properties: {
+    diagramSourceCode: {
+      type: "string",
+      description: "Source code of d2 diagram",
+    },
+  },
+  required: ["diagramSourceCode"],
+};

package/agents/history/index.yaml

@@ -0,0 +1,6 @@
+name: "history"
+description: "View and manage document update history"
+tasks:
+  - name: "view"
+    description: "View update history in compact format"
+    agent: "viewHistory"

package/agents/history/view.mjs

@@ -0,0 +1,75 @@
+import chalk from "chalk";
+import { getHistory } from "../../utils/history-utils.mjs";
+
+export default function viewHistory() {
+  const history = getHistory();
+
+  if (!history.entries || history.entries.length === 0) {
+    console.log(chalk.yellow("\nNo update history found\n"));
+    return {};
+  }
+
+  console.log(chalk.cyan("\n📜 Update History\n"));
+
+  history.entries.forEach((entry) => {
+    // Format: <short-hash> <date> <operation> <feedback>
+    const hash = generateShortHash(entry.timestamp);
+    const date = formatRelativeDate(entry.timestamp);
+    const operation = entry.operation;
+
+    // Handle document path (now a string)
+    const documentInfo = entry.documentPath ? chalk.dim(` (${entry.documentPath})`) : "";
+
+    // Git-style oneline format
+    console.log(
+      `${chalk.yellow(hash)} ${chalk.dim(date)} ${chalk.cyan(operation)}${documentInfo}: ${entry.feedback}`,
+    );
+  });
+
+  console.log(); // Empty line at end
+
+  return {};
+}
+
+/**
+ * Generate a short hash from timestamp (git-style)
+ */
+function generateShortHash(timestamp) {
+  const hash = timestamp.replace(/[-:.TZ]/g, "");
+  return hash.substring(hash.length - 7); // Last 7 chars
+}
+
+/**
+ * Format date in relative time (git-style)
+ */
+function formatRelativeDate(timestamp) {
+  const date = new Date(timestamp);
+  const now = new Date();
+  const diffMs = now - date;
+  const diffSecs = Math.floor(diffMs / 1000);
+  const diffMins = Math.floor(diffSecs / 60);
+  const diffHours = Math.floor(diffMins / 60);
+  const diffDays = Math.floor(diffHours / 24);
+
+  if (diffSecs < 60) {
+    return `${diffSecs} seconds ago`;
+  }
+  if (diffMins < 60) {
+    return `${diffMins} minute${diffMins === 1 ? "" : "s"} ago`;
+  }
+  if (diffHours < 24) {
+    return `${diffHours} hour${diffHours === 1 ? "" : "s"} ago`;
+  }
+  if (diffDays < 7) {
+    return `${diffDays} day${diffDays === 1 ? "" : "s"} ago`;
+  }
+  // Show actual date for older entries
+  return date.toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+    year: date.getFullYear() !== now.getFullYear() ? "numeric" : undefined,
+  });
+}
+
+viewHistory.description = "View update history in compact format";
+viewHistory.taskTitle = "View update history";

package/agents/translate/index.yaml

@@ -32,6 +32,7 @@ skills:
     name: batchTranslateDocument
     skills:
       - ../translate/translate-multilingual.yaml
+      - url: ./record-translation-history.mjs
       - url: ../utils/save-single-doc.mjs
         default_input:
           isTranslate: true
@@ -42,7 +43,7 @@ skills:
       stage: translation_refine
   - url: ../utils/action-success.mjs
     default_input:
-      action: "✅ Translation completed"
+      action: '✅ Translation completed'
 input_schema:
   type: object
   properties:
@@ -58,7 +59,7 @@ input_schema:
       type: array
       items:
         type: string
-      description: "Target languages (available: en, zh, zh-TW, ja, fr, de, es, it, ru, ko, pt, ar)"
+      description: 'Target languages (available: en, zh, zh-TW, ja, fr, de, es, it, ru, ko, pt, ar)'
     feedback:
       type: string
       description: Tell us how to improve the translation style

package/agents/translate/record-translation-history.mjs

@@ -0,0 +1,19 @@
+import { recordUpdate } from "../../utils/history-utils.mjs";
+
+export default function recordTranslationHistory({ feedback, path }) {
+  // Skip if no feedback provided
+  if (!feedback?.trim()) {
+    return {};
+  }
+
+  // Record translation history for this document
+  recordUpdate({
+    operation: "translation_update",
+    feedback: feedback.trim(),
+    documentPath: path,
+  });
+
+  return {};
+}
+
+recordTranslationHistory.task_render_mode = "hide";

package/agents/translate/translate-multilingual.yaml

@@ -47,4 +47,5 @@ output_schema:
           translation:
             type: string
 iterate_on: translates
-mode: sequential
+concurrency: 3
+

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

@@ -2,6 +2,6 @@
 type: team
 name: batchUpdateDocument
 skills:
-  - ../update/generate-and-translate-document.yaml
+  - ../update/handle-document-update.yaml
 iterate_on: selectedDocs
 concurrency: 5

package/agents/update/check-document.mjs

@@ -112,7 +112,7 @@ export default async function checkDocument(
 
   const teamAgent = TeamAgent.from({
     name: "generateDocument",
-    skills: [options.context.agents["generateAndTranslateDocument"]],
+    skills: [options.context.agents["handleDocumentUpdate"]],
   });
 
   const result = await options.context.invoke(teamAgent, {

package/agents/update/fs-tools/read-file.mjs

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import fsPromises from "node:fs/promises";
-import path from "node:path";
+import path, { isAbsolute } from "node:path";
 
 /**
  * Detects if a file is likely binary by checking for null bytes
@@ -199,6 +199,8 @@ export default async function readFile({ path: filePath, offset, limit, encoding
   let result = {};
   let error = null;
 
+  if (filePath && !isAbsolute(filePath)) filePath = path.join(process.cwd(), filePath);
+
   try {
     // Validate file path first (this checks if it's absolute)
     const pathError = validateFilePath(filePath);

package/agents/update/generate-document.yaml

@@ -1,7 +1,10 @@
 name: generateDocument
 description: Comprehensive content generator for documentation that creates detailed, high-quality document content from various data sources with intelligent analysis.
 instructions:
-  url: ../../prompts/detail/generate-document.md
+  - role: system
+    url: ../../prompts/detail/generate/system-prompt.md
+  - role: user
+    url: ../../prompts/detail/generate/user-prompt.md
 input_schema:
   type: object
   properties:
@@ -46,27 +49,30 @@ skills:
   - fs-tools/glob.mjs
   - fs-tools/grep.mjs
   - fs-tools/read-file.mjs
-  - type: team
-    task_render_mode: collapse
-    name: generateD2DiagramContent
-    skills:
-      - ../generate/generate-d2-diagram.yaml
-    reflection:
-      reviewer: ../generate/check-d2-diagram-valid.mjs
-      is_approved: isValid
-      max_iterations: 5
-      return_last_on_max_iterations: true
-    input_schema:
-      type: object
-      properties:
-        documentContent:
-          type: string
-          description: Source code of current document (without the D2 diagram)
-      required:
-        - documentContent
-    output_schema:
-      type: object
-      properties:
-        d2DiagramSourceCode:
-          type: string
-          description: Source code for the D2 diagram
+  # FIXME: @zhanghan temporary disable diagram tool
+  # - type: team
+  #   task_render_mode: collapse
+  #   name: generateDiagram
+  #   skills:
+  #     - ../generate/draw-diagram.yaml
+  #     - ../generate/wrap-diagram-code.mjs
+  #   reflection:
+  #     reviewer: ../generate/check-diagram.mjs
+  #     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:
+  #       documentContent:
+  #         type: string
+  #         description: The **raw text content** of the current document. (**Note:** This is the original document and **does not include** any existing diagram source code.)
+  #     required:
+  #       - documentContent
+  #   output_schema:
+  #     type: object
+  #     properties:
+  #       diagramSourceCode:
+  #         type: string
+  #         description: The **diagram source code** generated from the input text.

package/agents/update/{generate-and-translate-document.yaml → handle-document-update.yaml}

@@ -1,6 +1,6 @@
 type: team
-name: generateAndTranslateDocument
-description: Generate and translate documents
+name: handleDocumentUpdate
+description: Update a document in a batch
 skills:
   - ../utils/transform-detail-datasources.mjs
   - type: team
@@ -23,15 +23,6 @@ skills:
       max_iterations: 5
       return_last_on_max_iterations: true
     task_title: Generate document for '{{ title }}'
-  - type: transform
-    task_render_mode: hide
-    jsonata: |
-      $merge([
-        $,
-        { "feedback": "" }
-      ])
-  - ../translate/translate-multilingual.yaml
-  - ../utils/save-single-doc.mjs
 input_schema:
   type: object
   properties:

package/agents/update/index.yaml

@@ -31,6 +31,7 @@ skills:
       requiredFeedback: false
   - ../utils/format-document-structure.mjs
   - ../update/check-update-is-single.mjs
+  - ../update/save-and-translate-document.mjs
   - url: ../utils/action-success.mjs
     default_input:
       action: "✅ Documents updated successfully"

package/agents/update/save-and-translate-document.mjs

@@ -0,0 +1,101 @@
+import { recordUpdate } from "../../utils/history-utils.mjs";
+
+export default async function saveAndTranslateDocument(input, options) {
+  const { selectedDocs, docsDir, translateLanguages, locale } = input;
+
+  // Saves a document with optional translation data
+  const saveDocument = async (doc, translates = null, isTranslate = false) => {
+    const saveAgent = options.context.agents["saveSingleDoc"];
+
+    return await options.context.invoke(saveAgent, {
+      path: doc.path,
+      content: doc.content,
+      docsDir: docsDir,
+      locale: locale,
+      translates: translates || doc.translates,
+      labels: doc.labels,
+      isTranslate: isTranslate,
+    });
+  };
+
+  // Only prompt user if translation is actually needed
+  let shouldTranslate = false;
+  if (
+    Array.isArray(translateLanguages) &&
+    translateLanguages.filter((lang) => lang !== locale).length > 0
+  ) {
+    const choice = await options.prompts.select({
+      message: "Document update completed. Would you like to translate these documents now?",
+      choices: [
+        {
+          name: "Review documents first, translate later",
+          value: "no",
+        },
+        {
+          name: "Translate now",
+          value: "yes",
+        },
+      ],
+    });
+    shouldTranslate = choice === "yes";
+  }
+
+  // Process documents in batches for better performance
+  const batchSize = 3;
+  for (let i = 0; i < selectedDocs.length; i += batchSize) {
+    const batch = selectedDocs.slice(i, i + batchSize);
+
+    const savePromises = batch.map(async (doc) => {
+      try {
+        await saveDocument(doc);
+
+        // Record history for each document if feedback is provided
+        if (doc.feedback?.trim()) {
+          recordUpdate({
+            operation: "document_update",
+            feedback: doc.feedback.trim(),
+            documentPath: doc.path,
+          });
+          // clear feedback
+          doc.feedback = "";
+        }
+      } catch (error) {
+        console.error(`❌ Failed to save document ${doc.path}:`, error.message);
+      }
+    });
+
+    await Promise.all(savePromises);
+  }
+
+  // Return results if user chose to skip translation
+  if (!shouldTranslate) {
+    return {};
+  }
+
+  // Translate documents in batches
+  const translateAgent = options.context.agents["translateMultilingual"];
+
+  for (let i = 0; i < selectedDocs.length; i += batchSize) {
+    const batch = selectedDocs.slice(i, i + batchSize);
+
+    const translatePromises = batch.map(async (doc) => {
+      try {
+        const result = await options.context.invoke(translateAgent, {
+          ...input, // Pass context for translation
+          content: doc.content,
+          translates: doc.translates,
+          title: doc.title,
+        });
+
+        // Save the translated content
+        await saveDocument(doc, result.translates, true);
+      } catch (error) {
+        console.error(`❌ Failed to translate document ${doc.path}:`, error.message);
+      }
+    });
+
+    await Promise.all(translatePromises);
+  }
+
+  return {};
+}

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

@@ -2,7 +2,11 @@ type: ai
 name: updateDocumentDetail
 description: Update and optimize document content based on user feedback using diff patches
 instructions:
-  url: ../../prompts/detail/update-document.md
+  - role: system
+    url: ../../prompts/detail/update/system-prompt.md
+  - role: user
+    url: ../../prompts/detail/update/user-prompt.md
+
 input_schema:
   type: object
   properties:

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

@@ -3,14 +3,5 @@ name: updateSingleDocument
 skills:
   - ../utils/transform-detail-datasources.mjs
   - ../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
+concurrency: 1

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

@@ -138,6 +138,7 @@ export default async function userReviewDocument(
   options.context.userContext.currentContent = content;
 
   const MAX_ITERATIONS = 100;
+  const feedbacks = [];
   let iterationCount = 0;
   while (iterationCount < MAX_ITERATIONS) {
     iterationCount++;
@@ -185,6 +186,8 @@ export default async function userReviewDocument(
       break;
     }
 
+    feedbacks.push(feedback.trim());
+
     // Get the updateDocument agent
     const updateAgent = options.context.agents["updateDocumentDetail"];
     if (!updateAgent) {
@@ -242,7 +245,7 @@ export default async function userReviewDocument(
     }
   }
 
-  return { content: options.context.userContext.currentContent };
+  return { content: options.context.userContext.currentContent, feedback: feedbacks.join(". ") };
 }
 
 userReviewDocument.taskTitle = "User review and modify document content";