@aigne/doc-smith 0.8.11-beta.2 → 0.8.11-beta.4

package/.release-please-manifest.json

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

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.8.11-beta.4](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.11-beta.3...v0.8.11-beta.4) (2025-09-30)
+
+
+### Features
+
+* add check-only option for agents with selection input ([#147](https://github.com/AIGNE-io/aigne-doc-smith/issues/147)) ([3340988](https://github.com/AIGNE-io/aigne-doc-smith/commit/3340988e67ffef7e1087d560930b3cf98c860693))
+
+
+### Bug Fixes
+
+* improve error handling in choose-docs utility ([#145](https://github.com/AIGNE-io/aigne-doc-smith/issues/145)) ([7052ffc](https://github.com/AIGNE-io/aigne-doc-smith/commit/7052ffc106817144bff815422dced7faa4dfc3e8))
+* translation prompt tuned; translate comments only in code blocks ([#149](https://github.com/AIGNE-io/aigne-doc-smith/issues/149)) ([30ce2c0](https://github.com/AIGNE-io/aigne-doc-smith/commit/30ce2c0e43c01b6588b4ada84aafecfd83c1b23b))
+
+## [0.8.11-beta.3](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.11-beta.2...v0.8.11-beta.3) (2025-09-29)
+
+
+### Bug Fixes
+
+* add evaluation agents cil entry ([#143](https://github.com/AIGNE-io/aigne-doc-smith/issues/143)) ([016096a](https://github.com/AIGNE-io/aigne-doc-smith/commit/016096af6c0cec0b86fc538e1f0b7b42e928451b))
+
 ## [0.8.11-beta.2](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.11-beta.1...v0.8.11-beta.2) (2025-09-27)
 
 

package/agents/clear/index.yaml

@@ -7,6 +7,7 @@ skills:
   - url: ../init/index.mjs
     default_input:
       skipIfExists: true
+      checkOnly: true
   - ./choose-contents.mjs
 input_schema:
   type: object

package/agents/evaluate/index.yaml

@@ -5,6 +5,7 @@ skills:
   - url: ../init/index.mjs
     default_input:
       skipIfExists: true
+      checkOnly: true
   - ../utils/load-sources.mjs
   - ../utils/format-document-structure.mjs
   - type: transform

package/agents/init/index.mjs

@@ -32,9 +32,32 @@ const _PRESS_ENTER_TO_FINISH = "Press Enter to finish";
  * @returns {Promise<Object>}
  */
 export default async function init(
-  { outputPath = ".aigne/doc-smith", fileName = "config.yaml", skipIfExists = false, appUrl },
+  {
+    outputPath = ".aigne/doc-smith",
+    fileName = "config.yaml",
+    skipIfExists = false,
+    appUrl,
+    checkOnly = false,
+  },
   options,
 ) {
+  // Check if we're in checkOnly mode
+  if (checkOnly) {
+    const filePath = join(outputPath, fileName);
+    const configContent = await readFile(filePath, "utf8").catch(() => null);
+
+    if (!configContent || configContent.trim() === "") {
+      console.log(`⚠️ No configuration found.`);
+      console.log(
+        `🚀 Run ${chalk.cyan("aigne doc init")} to set up your documentation configuration.`,
+      );
+      process.exit(0);
+    }
+
+    // Config exists, load and return it
+    return loadConfig({ config: filePath, appUrl });
+  }
+
   if (skipIfExists) {
     const filePath = join(outputPath, fileName);
     const configContent = await readFile(filePath, "utf8").catch(() => null);

package/agents/publish/index.yaml

@@ -8,6 +8,7 @@ skills:
   - url: ../init/index.mjs
     default_input:
       skipIfExists: true
+      checkOnly: true
   - publish-docs.mjs
 input_schema:
   type: object

package/agents/translate/index.yaml

@@ -5,6 +5,7 @@ skills:
   - url: ../init/index.mjs
     default_input:
       skipIfExists: true
+      checkOnly: true
   - ../utils/load-sources.mjs
   - type: transform
     task_render_mode: hide

package/agents/update/index.yaml

@@ -7,6 +7,7 @@ skills:
   - url: ../init/index.mjs
     default_input:
       skipIfExists: true
+      checkOnly: true
   - ../utils/load-sources.mjs
   - type: transform
     task_render_mode: hide

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

@@ -1,6 +1,7 @@
 type: team
 name: updateSingleDocument
 skills:
+  - ../utils/transform-detail-datasources.mjs
   - ../update/user-review-document.mjs
   - type: transform
     task_render_mode: hide

package/agents/utils/choose-docs.mjs

@@ -34,18 +34,33 @@ export default async function chooseDocs(
       );
 
       if (mainLanguageFiles.length === 0) {
-        throw new Error("No documents found in the docs directory");
+        throw new Error(
+          "No documents found in the docs directory. Please run `aigne docs generate` to generate the documents",
+        );
       }
 
+      // Convert files to choices with titles
+      const choices = mainLanguageFiles.map((file) => {
+        // Convert filename to flat path to find corresponding document structure item
+        const flatName = file.replace(/\.md$/, "").replace(/\.\w+(-\w+)?$/, "");
+        const docItem = documentExecutionStructure.find((item) => {
+          const itemFlattenedPath = item.path.replace(/^\//, "").replace(/\//g, "-");
+          return itemFlattenedPath === flatName;
+        });
+
+        // Use title if available, otherwise fall back to filename
+        const displayName = docItem?.title || file;
+
+        return {
+          name: displayName,
+          value: file,
+        };
+      });
+
       // Let user select multiple files
       selectedFiles = await options.prompts.checkbox({
         message: getActionText(isTranslate, "Select documents to {action}:"),
         source: (term) => {
-          const choices = mainLanguageFiles.map((file) => ({
-            name: file,
-            value: file,
-          }));
-
           if (!term) return choices;
 
           return choices.filter((choice) => choice.name.toLowerCase().includes(term.toLowerCase()));
@@ -65,12 +80,8 @@ export default async function chooseDocs(
       // Process selected files and convert to found items
       foundItems = await processSelectedFiles(selectedFiles, documentExecutionStructure, docsDir);
     } catch (error) {
-      console.error(error);
       throw new Error(
-        getActionText(
-          isTranslate,
-          "Please provide a docs parameter to specify which documents to {action}",
-        ),
+        getActionText(isTranslate, `\nFailed to select documents to {action}: ${error.message}`),
       );
     }
   } else {

package/aigne.yaml

@@ -79,6 +79,10 @@ agents:
 
   # Evaluation
   - ./agents/evaluate/index.yaml
+  - ./agents/evaluate/generate-report.mjs
+  - ./agents/evaluate/document-structure.yaml
+  - ./agents/evaluate/document.yaml
+  - ./agents/evaluate/code-snippet.mjs
 cli:
   chat: ./agents/chat/index.yaml
   agents:
@@ -89,6 +93,7 @@ cli:
     - ./agents/translate/index.yaml
     - ./agents/clear/index.yaml
     - ./agents/prefs/index.mjs
+    - ./agents/evaluate/index.yaml
 mcp_server:
   agents:
     - ./docs-mcp/get-docs-structure.mjs

package/package.json

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

package/prompts/detail/update-document.md

@@ -95,7 +95,7 @@ parentId: {{parentId}}
 </current_document>
 
 <datasources>
-{{ datasources }}
+{{ detailDataSources }}
 
 {{ additionalInformation }}
 

package/prompts/translate/code-block.md

@@ -0,0 +1,16 @@
+<code_block_rules>
+The following formats are considered Code Blocks:
+  - Wrapped with ```
+  - Supports configurations: language, title, icon, where title and icon are optional
+  - content can be code, command line examples, text or any other content
+
+<code_block_sample>
+```{language} [{title}] [icon={icon}]
+{content}
+```
+</code_block_sample>
+
+Code Block Translation: 
+- For D2 code blocks, only translate labels
+- For other language code blocks, **only translate comments starting with #, keep all other content unchanged without translation**
+</code_block_rules>

package/prompts/translate/translate-document.md

@@ -1,26 +1,26 @@
 <role_and_goal>
-You are a professional translator proficient in multiple languages, skilled in accurate and standardized bilingual conversion.
+
+You are an **Elite Polyglot Localization and Translation Specialist** with extensive professional experience across multiple domains. Your core mission is to produce translations that are not only **100% accurate** to the source meaning but are also **natively fluent, highly readable, and culturally appropriate** in the target language.
+
+Core Mandates:
+
+1. Semantic Fidelity (Accuracy): The translation must perfectly and comprehensively convey the **entire meaning, tone, and nuance** of the source text. **No omission, addition, or distortion of the original content** is permitted.
+2. Native Fluency and Style: The resulting text must adhere strictly to the target language's **grammar, syntax, and idiomatic expressions**. The translation must **sound like it was originally written by a native speaker**, completely **free of grammatical errors** or "translationese" (literal, stiff, or unnatural phrasing).
+3. Readability and Flow: The final output must be **smooth, logical, and highly readable**. Sentences must flow naturally, ensuring a pleasant and coherent reading experience for the target audience.
+4. Localization and Clarity: Where a **literal (word-for-word) translation** of a term, phrase, or idiom would be **uncommon, confusing, or ambiguous** in the target language, you must apply **localization best practices**. This means translating the **concept** into the most **idiomatic, common, and easily understandable expression** in the target language.
+5. Versatility and Scope: You are proficient in handling **any pair of requested languages** (e.g., Chinese $\leftrightarrow$ English, English $\leftrightarrow$ Japanese) and are adept at translating diverse **document types**, including but not limited to: **Technical Manuals, Business Reports, Marketing Copy/Ads, Legal Documents, Academic Papers, and General Correspondence.**
 </role_and_goal>
 
 <translation_rules>
 Translation Requirements:
 
-- **Accurate Conveyance**: Accurately convey the facts and context of the original text, ensuring complete coverage.
-- **Avoid Exaggeration**: Avoid using emotionally charged or subjective words (for example, "excited" or "shocked").
-- **Follow Language Standards**: Ensure correct punctuation and grammar, and express ideas naturally and fluently.
-- **Preserve Original Structure**: Translate only the content portions without modifying tags or introducing any extra content or punctuation. Do not add markdown syntax at the outermost level. Ensure the translated structure matches the original, preserving line breaks and blank lines from the source.
-- **Strictly Protect Markdown Syntax**: All Markdown syntax characters, including but not limited to `|` and `-` in tables, `*` and `-` in lists, `#` in headings, `` ` `` in code blocks, etc., must be **copied exactly**, with no modification, addition, deletion, or merging. Table separators (e.g., `|---|---|---|`) must match the original column count and format exactly, with separator columns matching table data columns.
-- **Follow Translation Process**: Include literal translation, optimization, and omission checking to ensure the final output meets all requirements.
-- **Use Terminology Reference**: Ensure accuracy and consistency of professional terminology.
-- **Preserve Terms**: Retain specific terms in their original form, avoiding translation.
-
-Translation Process:
-
-- **Literal Translation**: Translate the original text word by word and sentence by sentence into the target language, ensuring every word's meaning is accurately conveyed.
-- **Optimization**: Based on the literal translation, ensure the text stays faithful to the original meaning while making it more natural and aligned with **{{ language }}** usage.
-- **Check for Omissions**: Compare the original with the literal translation to correct any meaning distortions or omissions.
-- **Format Check**: Compare the original with the literal translation to ensure the translated content is complete. If the original is in Markdown format, verify that the format matches the original.
-- **Final Output**: Output the optimized translation result, ensuring compliance with the above requirements (do not output the literal translation content).
+- Avoid Exaggeration: Avoid using emotionally charged or subjective words (for example, "excited" or "shocked").
+- Preserve Original Structure: Translate only the content portions without modifying tags or introducing any extra content or punctuation. Do not add markdown syntax at the outermost level. Ensure the translated structure matches the original, preserving line breaks and blank lines from the source.
+- Strictly Protect Markdown Syntax: All Markdown syntax characters, including but not limited to `|` and `-` in tables, `*` and `-` in lists, `#` in headings, `` ` `` in code blocks, etc., must be **copied exactly**, with no modification, addition, deletion, or merging. Table separators (e.g., `|---|---|---|`) must match the original column count and format exactly, with separator columns matching table data columns.
+- Use Terminology Reference: Ensure accuracy and consistency of professional terminology.
+- Preserve Terms: Retain specific terms in their original form, avoiding translation.
+
+{% include "./code-block.md" %}
 </translation_rules>
 
 
@@ -57,6 +57,9 @@ Terms to preserve (do not translate):
 </terms>
 
 <example>
+<example_item>
+**Special Note**: Keep table separators `|---|---|---|` unchanged from the original
+
 <before_translate>
 | Name | Type | Description |
 |---|---|---|
@@ -71,9 +74,10 @@ Terms to preserve (do not translate):
 | `id` | `string` | 要更新的 Webhook 端点的唯一标识符。 |
 | `data` | `PartialDeep<ABTNodeClient.WebhookEndpointStateInput>` | 包含要更新的 Webhook 端点字段的对象。 |
 </after_translate>
+</example_item>
 
-**Special Note**: Keep table separators `|---|---|---|` unchanged from the original
-
+<example_item>
+**Special Note**: All x-field component attributes must maintain the original format. Only translate the description content within data-desc attributes or x-field-desc elements
 <before_translate>
 
 <x-field data-name="teamDid" data-type="string" data-required="true" data-desc="The DID of the team or Blocklet managing the webhook."></x-field>
@@ -89,8 +93,100 @@ Terms to preserve (do not translate):
     <x-field-desc markdown>您的 **API 密钥**，用于身份验证。请从 `设置 > API 密钥` 部分生成一个。</x-field-desc>
 </x-field>
 </after_translate>
+</example_item>
+
+<example_item>
+**Special Note**: In code blocks, only translate comments while keeping all other code content (variables, functions, syntax) unchanged
+
+<before_translate>
+```xxx
+// Initialize the API client
+const client = new APIClient({
+  apiKey: 'your-api-key', // Replace with your actual API key
+  baseUrl: 'https://api.example.com'
+});
+
+const errorMessage = 'Failed to fetch user data';
+const successMessage = 'User data retrieved successfully';
+
+// Send request to get user data
+async function getUserData(userId) {
+  console.log('Starting user data fetch for ID:', userId);
+
+  try {
+    // Fetch user information from the API
+    const result = await client.get(`/users/${userId}`);
+    console.log('API response received');
+    console.log(successMessage);
+    return result;
+  } catch (error) {
+    console.error('Error occurred:', error.message);
+    throw new Error(errorMessage);
+  }
+}
+```
+</before_translate>
+
+<after_translate>
+```xxx
+// 初始化 API 客户端
+const client = new APIClient({
+  apiKey: 'your-api-key', // 替换为您的实际 API 密钥
+  baseUrl: 'https://api.example.com'
+});
+
+const errorMessage = 'Failed to fetch user data';
+const successMessage = 'User data retrieved successfully';
+
+// 发送请求获取用户数据
+async function getUserData(userId) {
+  console.log('Starting user data fetch for ID:', userId);
+
+  try {
+    // 从 API 获取用户信息
+    const result = await client.get(`/users/${userId}`);
+    console.log('API response received');
+    console.log(successMessage);
+    return result;
+  } catch (error) {
+    console.error('Error occurred:', error.message);
+    throw new Error(errorMessage);
+  }
+}
+```
+</after_translate>
+</example_item>
+
+<example_item>
+**Special Note**: **Command execution and log printing** should untranslated
+
+<before_translate>
+```text Timeout Error Message
+Blocklet Server failed to stop within 5 minutes
+You can stop blocklet server with blocklet stop --force
+```
+
+```bash Success Output
+$ cli log
+
+Cache for server cleared: [list of cleared cache keys]
+```
+</before_translate>
+
+<after_translate>
+```text 超时错误消息
+Blocklet Server failed to stop within 5 minutes
+You can stop blocklet server with blocklet stop --force
+```
+
+```bash 成功输出
+$ cli log
+
+Cache for server cleared: [list of cleared cache keys]
+```
+</after_translate>
+</example_item>
 
-**Special Note**: All x-field component attributes must maintain the original format. Only translate the description content within data-desc attributes or x-field-desc elements
 </example>
 
 Original text as follows:

package/tests/agents/init/init.test.mjs

@@ -1438,6 +1438,128 @@ describe("init", () => {
     });
   });
 
+  describe("checkOnly parameter", () => {
+    test("should exit silently when checkOnly is true and config exists", async () => {
+      const tempDir = await createTempDir();
+
+      try {
+        // Create existing config file
+        const configPath = join(tempDir, "config.yaml");
+        const existingConfig = `projectName: "Test Project"
+locale: "en"
+documentPurpose:
+  - getStarted
+targetAudienceTypes:
+  - developers`;
+        await fs.writeFile(configPath, existingConfig, "utf8");
+
+        // The function should continue normally when config exists
+        // No mocking needed as it doesn't log or exit in this case
+        const result = await init(
+          {
+            outputPath: tempDir,
+            fileName: "config.yaml",
+            checkOnly: true,
+          },
+          { prompts: {} }, // Options not needed for checkOnly
+        );
+
+        // Should return loaded config
+        expect(result).toBeDefined();
+        expect(result.projectName).toBe("Test Project");
+        expect(result.locale).toBe("en");
+      } finally {
+        await cleanupTempDir(tempDir);
+      }
+    });
+
+    test("should show reminder and exit when checkOnly is true and config doesn't exist", async () => {
+      const tempDir = await createTempDir();
+
+      try {
+        // Mock console.log and process.exit
+        const originalLog = console.log;
+        const originalExit = process.exit;
+        const logMessages = [];
+        let exitCalled = false;
+        let exitCode = null;
+
+        console.log = (...args) => logMessages.push(args.join(" "));
+        process.exit = (code) => {
+          exitCalled = true;
+          exitCode = code;
+          throw new Error("process.exit called"); // Prevent actual exit
+        };
+
+        try {
+          await expect(
+            init(
+              {
+                outputPath: tempDir,
+                fileName: "config.yaml",
+                checkOnly: true,
+              },
+              { prompts: {} },
+            ),
+          ).rejects.toThrow("process.exit called");
+
+          // Should log reminder messages
+          expect(logMessages.some((msg) => msg.includes("No configuration found"))).toBe(true);
+          expect(logMessages.some((msg) => msg.includes("aigne doc init"))).toBe(true);
+
+          // Should call process.exit(0)
+          expect(exitCalled).toBe(true);
+          expect(exitCode).toBe(0);
+        } finally {
+          console.log = originalLog;
+          process.exit = originalExit;
+        }
+      } finally {
+        await cleanupTempDir(tempDir);
+      }
+    });
+
+    test("should not interfere with normal workflow when checkOnly is false", async () => {
+      const tempDir = await createTempDir();
+
+      try {
+        const mockPrompts = createMockPrompts({
+          checkbox_1: ["getStarted"],
+          checkbox_2: ["developers"],
+          select_3: "domainFamiliar",
+          select_4: "balancedCoverage",
+          select_5: "en",
+          checkbox_6: [],
+          input_7: join(tempDir, "docs"),
+          search: "",
+        });
+
+        const options = { prompts: mockPrompts };
+
+        const result = await init(
+          {
+            outputPath: tempDir,
+            fileName: "config.yaml",
+            checkOnly: false, // Explicit false
+          },
+          options,
+        );
+
+        expect(result).toBeDefined();
+
+        // Check that config file was created normally
+        const configPath = join(tempDir, "config.yaml");
+        const configExists = await fs
+          .access(configPath)
+          .then(() => true)
+          .catch(() => false);
+        expect(configExists).toBe(true);
+      } finally {
+        await cleanupTempDir(tempDir);
+      }
+    });
+  });
+
   describe("Advanced source path scenarios", () => {
     test("should handle source path validation and duplicate detection", async () => {
       const tempDir = await createTempDir();

package/tests/agents/utils/choose-docs.test.mjs

@@ -183,12 +183,7 @@ describe("chooseDocs utility", () => {
       locale: "en",
     };
 
-    await expect(chooseDocs(input, mockOptions)).rejects.toThrow(
-      "Please provide a docs parameter to specify which documents to update",
-    );
-    expect(consoleErrorSpy).toHaveBeenCalledWith(
-      new Error("No documents found in the docs directory"),
-    );
+    await expect(chooseDocs(input, mockOptions)).rejects.toThrow();
   });
 
   test("should throw error when no documents selected interactively", async () => {
@@ -202,9 +197,7 @@ describe("chooseDocs utility", () => {
       locale: "en",
     };
 
-    await expect(chooseDocs(input, mockOptions)).rejects.toThrow(
-      "Please provide a docs parameter to specify which documents to update",
-    );
+    await expect(chooseDocs(input, mockOptions)).rejects.toThrow();
   });
 
   // CHECKBOX VALIDATION TESTS

package/tests/utils/docs-finder-utils.test.mjs

@@ -15,6 +15,7 @@ import {
 describe("docs-finder-utils", () => {
   let readdirSpy;
   let readFileSpy;
+  let accessSpy;
   let joinSpy;
   let consoleWarnSpy;
 
@@ -22,6 +23,7 @@ describe("docs-finder-utils", () => {
     // Mock file system operations
     readdirSpy = spyOn(fs, "readdir").mockResolvedValue([]);
     readFileSpy = spyOn(fs, "readFile").mockResolvedValue("test content");
+    accessSpy = spyOn(fs, "access").mockResolvedValue(undefined);
     joinSpy = spyOn(path, "join").mockImplementation((...paths) => paths.join("/"));
 
     // Mock console methods
@@ -31,6 +33,7 @@ describe("docs-finder-utils", () => {
   afterEach(() => {
     readdirSpy?.mockRestore();
     readFileSpy?.mockRestore();
+    accessSpy?.mockRestore();
     joinSpy?.mockRestore();
     consoleWarnSpy?.mockRestore();
   });
@@ -606,11 +609,20 @@ describe("docs-finder-utils", () => {
     });
 
     test("getMainLanguageFiles should handle readdir errors", async () => {
+      accessSpy.mockResolvedValue(undefined); // Directory exists
       readdirSpy.mockRejectedValue(new Error("Permission denied"));
 
       await expect(getMainLanguageFiles("/denied", "en")).rejects.toThrow("Permission denied");
     });
 
+    test("getMainLanguageFiles should throw non-ENOENT access errors", async () => {
+      const permissionError = new Error("Permission denied");
+      permissionError.code = "EACCES";
+      accessSpy.mockRejectedValue(permissionError);
+
+      await expect(getMainLanguageFiles("/denied", "en")).rejects.toThrow("Permission denied");
+    });
+
     test("processSelectedFiles should handle empty document structure", async () => {
       readFileSpy.mockResolvedValue("content");
 

package/utils/docs-finder-utils.mjs

@@ -1,4 +1,4 @@
-import { readdir, readFile } from "node:fs/promises";
+import { access, readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 
 /**
@@ -120,6 +120,17 @@ export async function readFileContent(docsDir, fileName) {
  * @returns {Promise<string[]>} Array of main language .md files ordered by documentExecutionStructure
  */
 export async function getMainLanguageFiles(docsDir, locale, documentExecutionStructure = null) {
+  // Check if docsDir exists
+  try {
+    await access(docsDir);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+
+    throw error;
+  }
+
   const files = await readdir(docsDir);
 
   // Filter for main language .md files (exclude _sidebar.md)