@aigne/doc-smith 0.8.15-beta.4 → 0.8.15-beta.6

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.8.15-beta.6](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.5...v0.8.15-beta.6) (2025-10-30)
+
+
+### Bug Fixes
+
+* ensure document embed image is accessible ([#226](https://github.com/AIGNE-io/aigne-doc-smith/issues/226)) ([47dfc5d](https://github.com/AIGNE-io/aigne-doc-smith/commit/47dfc5d48440f435258c7d4b5629712c7eb886e7))
+
+## [0.8.15-beta.5](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.4...v0.8.15-beta.5) (2025-10-29)
+
+
+### Bug Fixes
+
+* simplify data source input and select tips ([#223](https://github.com/AIGNE-io/aigne-doc-smith/issues/223)) ([069928b](https://github.com/AIGNE-io/aigne-doc-smith/commit/069928bce2b4a70ee5a0444ecff34501e1158e5c))
+
 ## [0.8.15-beta.4](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.15-beta.3...v0.8.15-beta.4) (2025-10-28)
 
 

package/agents/init/index.mjs

@@ -245,25 +245,21 @@ export default async function init(
   input.docsDir = docsDirInput.trim() || `${outputPath}/docs`;
 
   // 8. Content sources
-  console.log("\n🔍 [8/9]: Content Sources");
+  console.log("\n🔍 [8/9]: Data Sources");
+  console.log("Please specify the data source we should analyze to generate your documentation.");
   console.log(
-    "Please specify the folders and files we should analyze to generate your documentation.",
+    `  1. Use paths like ${chalk.green("./src")}, ${chalk.green("./README.md")} or ${chalk.green("!./src/private")}.`,
   );
   console.log(
-    `  1. You can use local file paths like ${chalk.green("./src")}, ${chalk.green("./docs")}, ${chalk.green("./README.md")} (prefix with '!' to ignore a file or folder like ${chalk.green("!./src/private")}).`,
-  );
-  console.log(
-    `  2. You can also use glob patterns like ${chalk.green("src/**/*.js")} or ${chalk.green("docs/**/*.md")} for more specific file matching. (prefix with '!' to ignore a file or folder like ${chalk.green("!private/**/*.js")}).`,
-  );
-  console.log(
-    `  3. You can also use remote url like ${chalk.green("https://example.com/openapi.yaml")}.`,
+    `  2. Use globs like ${chalk.green("src/**/*.js")} or ${chalk.green("!private/**/*.js")} for more specific file matching.`,
   );
+  console.log(`  3. Use URLs like ${chalk.green("https://example.com/openapi.yaml")}.`);
   console.log("💡 If you leave this empty, we will scan the entire directory.");
 
   const sourcePaths = [];
   while (true) {
     const selectedPath = await options.prompts.search({
-      message: "Please enter a file or folder path, or a glob pattern or remote url:",
+      message: "Please enter a valid data source:",
       source: async (input) => {
         if (!input || input.trim() === "") {
           return [

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

@@ -163,31 +163,19 @@ export default async function loadMediaDescription(input, options) {
   let enhancedAssetsContent = "# Available Media Assets for Documentation\n\n";
 
   if (mediaFiles.length > 0) {
-    enhancedAssetsContent += "```yaml\n";
-    enhancedAssetsContent += "assets:\n";
-
-    for (const asset of mediaFiles) {
-      enhancedAssetsContent += `  - name: "${asset.name}"\n`;
-      enhancedAssetsContent += `    path: "${asset.path}"\n`;
-      enhancedAssetsContent += `    type: "${asset.type}"\n`;
-
-      // Add description for images and videos
-      if (asset.type === "image" || asset.type === "video") {
-        const mediaHash = mediaHashMap.get(asset.path);
-        const cachedDesc = cache[mediaHash];
-        if (cachedDesc?.description) {
-          enhancedAssetsContent += `    description: "${cachedDesc.description}"\n`;
-        }
-      }
-
-      // Add dimensions for images and videos
-      if (asset.width && asset.height) {
-        enhancedAssetsContent += `    width: ${asset.width}\n`;
-        enhancedAssetsContent += `    height: ${asset.height}\n`;
+    const assets = mediaFiles.map((x) => {
+      const mediaHash = mediaHashMap.get(x.path);
+      const description = cache[mediaHash]?.description;
+      const result = {
+        name: x.name,
+        path: x.path,
+      };
+      if (description) {
+        result.description = description;
       }
-    }
-
-    enhancedAssetsContent += "```\n";
+      return result;
+    });
+    enhancedAssetsContent += stringify(assets);
   }
 
   return {

package/package.json

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

package/prompts/common/document/media-file-list-usage-rules.md

@@ -0,0 +1,12 @@
+<media_file_list_usage_rules>
+
+**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**
+- 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.
+
+</media_file_list_usage_rules>

package/prompts/detail/generate/system-prompt.md

@@ -45,6 +45,8 @@ Custom code block generation rules:
 
 {% include "../d2-diagram/guide.md" %}
 
+{% include "../../common/document/media-file-list-usage-rules.md" %}
+
 Tool result usage rules:
 - Only use the `"role": "tool"` result as the datasource for document enhancement.
 - Do not include `"role": "agent"` content in the final output.

package/prompts/detail/generate/user-prompt.md

@@ -19,11 +19,11 @@
 
 {{ additionalInformation }}
 
-<media_list>
+<media_file_list>
 {{ assetsContent }}
-</media_list>
+</media_file_list>
+
 
-{% include "../../common/document/media-handling-rules.md" %}
 
 </datasources>
 

package/prompts/detail/update/system-prompt.md

@@ -38,6 +38,8 @@ Custom component optimization rules:
 Custom code block optimization rules:
 {% include "../custom/custom-code-block.md" %}
 
+{% include "../../common/document/media-file-list-usage-rules.md" %}
+
 Diagram generation rules:
 {% include "../d2-diagram/guide.md" %}
 <diagram_generation_rules>

package/prompts/detail/update/user-prompt.md

@@ -21,11 +21,10 @@
 
 {{ additionalInformation }}
 
-<media_list>
+<media_file_list>
 {{ assetsContent }}
-</media_list>
+</media_file_list>
 
-{% include "../../common/document/media-handling-rules.md" %}
 </datasources>
 
 <user_feedback>

package/utils/file-utils.mjs

@@ -408,10 +408,31 @@ async function isTextFile(filePath) {
 export function isRemoteFile(fileUrl) {
   if (typeof fileUrl !== "string") return false;
 
-  if (fileUrl.startsWith("http://") || fileUrl.startsWith("https://")) {
-    return true;
+  try {
+    const url = new URL(fileUrl);
+    // Only accept http and https url
+    if (["http:", "https:"].includes(url.protocol)) {
+      return true;
+    }
+    // other protocol will be treated as bad url
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+export async function isRemoteFileAvailable(fileUrl) {
+  if (!isRemoteFile(fileUrl)) return false;
+
+  try {
+    const res = await fetch(fileUrl, {
+      method: "HEAD",
+    });
+    return res.ok;
+  } catch (error) {
+    debug(`Failed to check HTTP file availability: ${fileUrl} - ${error.message}`);
+    return false;
   }
-  return false;
 }
 
 export async function isRemoteTextFile(fileUrl) {

package/utils/markdown-checker.mjs

@@ -3,9 +3,12 @@ import path from "node:path";
 import remarkGfm from "remark-gfm";
 import remarkLint from "remark-lint";
 import remarkParse from "remark-parse";
+import { isRelative } from "ufo";
 import { unified } from "unified";
 import { visit } from "unist-util-visit";
 import { VFile } from "vfile";
+
+import { isRemoteFile, isRemoteFileAvailable } from "./file-utils.mjs";
 import { validateMermaidSyntax } from "./mermaid-validator.mjs";
 
 /**
@@ -232,6 +235,34 @@ function checkLocalImages(markdown, source, errorMessages, markdownFilePath, bas
   }
 }
 
+async function checkRemoteImages(markdown, source, errorMessages) {
+  const imageRegex = /!\[([^\]]*)\]\(([^)]+)\)/g;
+  let match;
+
+  while (true) {
+    match = imageRegex.exec(markdown);
+    if (match === null) break;
+    const imagePath = match[2].trim();
+    const altText = match[1];
+
+    if (isRelative(imagePath)) continue;
+    if (imagePath.startsWith("/")) continue;
+
+    // Skip data URLs
+    if (/^data:/.test(imagePath)) continue;
+
+    if (isRemoteFile(imagePath)) {
+      const isAvailable = await isRemoteFileAvailable(imagePath);
+      if (isAvailable) continue;
+      else {
+        errorMessages.push(
+          `Found invalid remote image in ${source}: ![${altText}](${imagePath}) - only valid media resources can be used`,
+        );
+      }
+    }
+  }
+}
+
 /**
  * Check content structure and formatting issues
  * @param {string} markdown - The markdown content
@@ -370,7 +401,10 @@ export async function checkMarkdown(markdown, source = "content", options = {})
     // 2. Check local images existence
     checkLocalImages(markdown, source, errorMessages, filePath, baseDir);
 
-    // 3. Check content structure and formatting issues
+    // 3. Check remote images existence
+    await checkRemoteImages(markdown, source, errorMessages);
+
+    // 4. Check content structure and formatting issues
     checkContentStructure(markdown, source, errorMessages);
 
     // Check mermaid code blocks and other custom validations

package/prompts/common/document/media-handling-rules.md

@@ -1,9 +0,0 @@
-<media_handling_rules>
-Media resource usage rules:
-
-- When DataSources contain media resource files, incorporate them appropriately in the generated content
-- Media resources are provided in markdown format, example: ![Resource description](https://xxxx)
-- Display images in markdown format within generated results
-- Based on resource descriptions, place images strategically in contextually relevant positions to enhance the presentation
-- To ensure correct media resource paths, **only use media resources provided in media_list or remote URL media resources**
-</media_handling_rules>