@aigne/doc-smith 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.6.0](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.5.1...v0.6.0) (2025-08-27)
+
+
+### Features
+
+* complete support for media processing before publish ([#63](https://github.com/AIGNE-io/aigne-doc-smith/issues/63)) ([5257ca1](https://github.com/AIGNE-io/aigne-doc-smith/commit/5257ca1756f47487b65a1813949e547b6fc51aca))
+
 ## [0.5.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.5.0...v0.5.1) (2025-08-26)
 
 

package/agents/check-detail-result.mjs

@@ -1,6 +1,6 @@
 import { checkMarkdown } from "../utils/markdown-checker.mjs";
 
-export default async function checkDetailResult({ structurePlan, reviewContent }) {
+export default async function checkDetailResult({ structurePlan, reviewContent, docsDir }) {
   let isApproved = true;
   const detailFeedback = [];
 
@@ -24,6 +24,7 @@ export default async function checkDetailResult({ structurePlan, reviewContent }
   try {
     const markdownErrors = await checkMarkdown(reviewContent, "result", {
       allowedLinks,
+      baseDir: docsDir,
     });
 
     if (markdownErrors.length > 0) {

package/agents/check-detail.mjs

@@ -85,6 +85,7 @@ export default async function checkDetail(
     const validationResult = await checkDetailResult({
       structurePlan,
       reviewContent: fileContent,
+      docsDir,
     });
 
     if (!validationResult.isApproved) {

package/agents/load-sources.mjs

@@ -86,17 +86,55 @@ export default async function loadSources({
   }
 
   files = [...new Set(files)];
+
+  // Define media file extensions
+  const mediaExtensions = [
+    ".jpg",
+    ".jpeg",
+    ".png",
+    ".gif",
+    ".bmp",
+    ".webp",
+    ".svg",
+    ".mp4",
+    ".mov",
+    ".avi",
+    ".mkv",
+    ".webm",
+    ".m4v",
+  ];
+
+  // Separate source files from media files
+  const sourceFiles = [];
+  const mediaFiles = [];
   let allSources = "";
-  const sourceFiles = await Promise.all(
+
+  await Promise.all(
     files.map(async (file) => {
-      const content = await readFile(file, "utf8");
-      // Convert absolute path to relative path from project root
-      const relativePath = path.relative(process.cwd(), file);
-      allSources += `// sourceId: ${relativePath}\n${content}\n`;
-      return {
-        sourceId: relativePath,
-        content,
-      };
+      const ext = path.extname(file).toLowerCase();
+
+      if (mediaExtensions.includes(ext)) {
+        // This is a media file
+        const relativePath = path.relative(docsDir, file);
+        const fileName = path.basename(file);
+        const description = path.parse(fileName).name;
+
+        mediaFiles.push({
+          name: fileName,
+          path: relativePath,
+          description,
+        });
+      } else {
+        // This is a source file
+        const content = await readFile(file, "utf8");
+        const relativePath = path.relative(process.cwd(), file);
+        allSources += `// sourceId: ${relativePath}\n${content}\n`;
+
+        sourceFiles.push({
+          sourceId: relativePath,
+          content,
+        });
+      }
     }),
   );
 
@@ -164,6 +202,17 @@ export default async function loadSources({
     }
   }
 
+  // Generate assets content from media files
+  let assetsContent = "# Available Media Assets for Documentation\n\n";
+
+  if (mediaFiles.length > 0) {
+    const mediaMarkdown = mediaFiles
+      .map((file) => `![${file.description}](${file.path})`)
+      .join("\n\n");
+
+    assetsContent += mediaMarkdown;
+  }
+
   // Count words and lines in allSources
   let totalWords = 0;
   let totalLines = 0;
@@ -188,6 +237,7 @@ export default async function loadSources({
     modifiedFiles,
     totalWords,
     totalLines,
+    assetsContent,
   };
 }
 
@@ -257,6 +307,10 @@ loadSources.output_schema = {
       items: { type: "string" },
       description: "Array of modified files since last generation",
     },
+    assetsContent: {
+      type: "string",
+      description: "Markdown content for available media assets",
+    },
   },
 };
 

package/agents/publish-docs.mjs

@@ -98,6 +98,8 @@ export default async function publishDocs(
       boardName: projectInfo.name,
       boardDesc: projectInfo.description,
       boardCover: projectInfo.icon,
+      mediaFolder: docsDir,
+      cacheFilePath: join(".aigne", "doc-smith", "upload-cache.yaml"),
       boardMeta,
     });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "",
   "publishConfig": {
     "access": "public"
@@ -12,13 +12,13 @@
   "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
   "license": "MIT",
   "dependencies": {
-    "@aigne/aigne-hub": "^0.6.9",
-    "@aigne/anthropic": "^0.11.9",
-    "@aigne/cli": "^1.41.0",
-    "@aigne/core": "^1.55.0",
-    "@aigne/gemini": "^0.9.9",
-    "@aigne/openai": "^0.12.3",
-    "@aigne/publish-docs": "^0.5.7",
+    "@aigne/aigne-hub": "^0.6.10",
+    "@aigne/anthropic": "^0.11.10",
+    "@aigne/cli": "^1.41.1",
+    "@aigne/core": "^1.55.1",
+    "@aigne/gemini": "^0.9.10",
+    "@aigne/openai": "^0.12.4",
+    "@aigne/publish-docs": "^0.6.0",
     "chalk": "^5.5.0",
     "dompurify": "^3.2.6",
     "glob": "^11.0.3",

package/prompts/content-detail-generator.md

@@ -16,6 +16,11 @@
 {{ detailDataSources }}
 
 {{ additionalInformation }}
+
+<media_list>
+{{ assetsContent }}
+</media_list>
+
 </datasources>
 
 <terms>
@@ -93,7 +98,6 @@ parentId: {{parentId}}
 - 媒体资源以 markdown 格式提供，示例：![资源描述](https://xxxx)
 - 在生成结果中以 markdown 格式展示图片
 - 根据资源描述，在上下文相关的位置，合理的展示图片，让结果展示效果更丰富
-- 只使用完整的远程图片URL（如 https://example.com/image.jpg），禁止使用相对路径（如 ./images/photo.png 或 ../assets/logo.png），确保发布后图片能正常访问
 
 </media_rules>
 

package/prompts/document/detail-generator.md

@@ -27,6 +27,7 @@
 - **代码块原子性**：将每个代码块（例如 ```mermaid ... ```）视为一个**不可分割的原子单元**。必须一次性完整生成，从开始标记（```mermaid）到结束标记（```）之间的所有内容都不能省略或截断。
 - **确保 Markdown 语法**：Markdown 格式正确，特别是表格的分隔线（例如 `|---|---|---|`），需要与表格数据列数一致。
 - README 文件只做参考，你需要从代码中获取最新、最完整的信息
+- 忽略详情顶部的标签信息，这是程序处理的，不需要在生成时输出
 </document_rules>
 
 <TONE_STYLE>

package/tests/check-detail-result.test.mjs

@@ -45,10 +45,59 @@ describe("checkDetailResult", () => {
     expect(result.detailFeedback).toContain("dead link");
   });
 
-  test("should approve content with image syntax", async () => {
+  test("should approve content with external image syntax", async () => {
     const structurePlan = [];
     const reviewContent =
-      "This is an image ![MCP Go Logo](/logo.png).\n\nThis has proper structure.";
+      "This is an image ![MCP Go Logo](https://example.com/logo.png).\n\nThis has proper structure.";
+    const result = await checkDetailResult({ structurePlan, reviewContent });
+    expect(result.isApproved).toBe(true);
+    expect(result.detailFeedback).toBe("");
+  });
+
+  test("should approve content with valid local image path", async () => {
+    const structurePlan = [];
+    const reviewContent =
+      "This is a valid image ![Test Image](./README.md).\n\nThis has proper structure.";
+    const docsDir = "/Users/lban/arcblock/code/aigne-doc-smith";
+    const result = await checkDetailResult({ structurePlan, reviewContent, docsDir });
+    expect(result.isApproved).toBe(true);
+    expect(result.detailFeedback).toBe("");
+  });
+
+  test("should reject content with invalid local image path", async () => {
+    const structurePlan = [];
+    const reviewContent =
+      "This is an invalid image ![Non-existent Image](./nonexistent.png).\n\nThis has proper structure.";
+    const docsDir = "/Users/lban/arcblock/code/aigne-doc-smith";
+    const result = await checkDetailResult({ structurePlan, reviewContent, docsDir });
+    expect(result.isApproved).toBe(false);
+    expect(result.detailFeedback).toContain("Found invalid local image");
+    expect(result.detailFeedback).toContain("only valid media resources can be used");
+  });
+
+  test("should approve content with absolute image path that exists", async () => {
+    const structurePlan = [];
+    const reviewContent =
+      "This is an absolute image ![Test Image](/Users/lban/arcblock/code/aigne-doc-smith/README.md).\n\nThis has proper structure.";
+    const result = await checkDetailResult({ structurePlan, reviewContent });
+    expect(result.isApproved).toBe(true);
+    expect(result.detailFeedback).toBe("");
+  });
+
+  test("should reject content with absolute image path that doesn't exist", async () => {
+    const structurePlan = [];
+    const reviewContent =
+      "This is an invalid absolute image ![Non-existent Image](/path/to/nonexistent.png).\n\nThis has proper structure.";
+    const result = await checkDetailResult({ structurePlan, reviewContent });
+    expect(result.isApproved).toBe(false);
+    expect(result.detailFeedback).toContain("Found invalid local image");
+    expect(result.detailFeedback).toContain("only valid media resources can be used");
+  });
+
+  test("should approve content with external image URL", async () => {
+    const structurePlan = [];
+    const reviewContent =
+      "This is an external image ![External Image](https://example.com/image.png).\n\nThis has proper structure.";
     const result = await checkDetailResult({ structurePlan, reviewContent });
     expect(result.isApproved).toBe(true);
     expect(result.detailFeedback).toBe("");

package/utils/auth-utils.mjs

@@ -91,7 +91,7 @@ export async function getAccessToken(appUrl) {
       source: `AIGNE DocSmith connect to Discuss Kit`,
       closeOnSuccess: true,
       appName: "AIGNE DocSmith",
-      appLogo: "https://www.aigne.io/image-bin/uploads/a7910a71364ee15a27e86f869ad59009.svg",
+      appLogo: "https://docsmith.aigne.io/image-bin/uploads/a7910a71364ee15a27e86f869ad59009.svg",
       openPage: (pageUrl) => open(pageUrl),
     });
 

package/utils/constants.mjs

@@ -86,15 +86,27 @@ export const DEFAULT_INCLUDE_PATTERNS = [
   "*.yml",
   "*Dockerfile",
   "*Makefile",
+  // Media files
+  "*.jpg",
+  "*.jpeg",
+  "*.png",
+  "*.gif",
+  "*.bmp",
+  "*.webp",
+  "*.svg",
+  "*.mp4",
+  "*.mov",
+  "*.avi",
+  "*.mkv",
+  "*.webm",
+  "*.m4v",
 ];
 
 export const DEFAULT_EXCLUDE_PATTERNS = [
   "**/aigne-docs/**",
   "**/doc-smith/**",
   "**/.aigne/**",
-  "**/assets/**",
   "**/data/**",
-  "**/images/**",
   "**/public/**",
   "**/static/**",
   "**/vendor/**",

package/utils/markdown-checker.mjs

@@ -1,3 +1,5 @@
+import fs from "node:fs";
+import path from "node:path";
 import remarkGfm from "remark-gfm";
 import remarkLint from "remark-lint";
 import remarkParse from "remark-parse";
@@ -159,6 +161,72 @@ function checkCodeBlockIndentation(codeBlockContent, codeBlockIndent, source, er
   }
 }
 
+/**
+ * Check for local images and verify their existence
+ * @param {string} markdown - The markdown content
+ * @param {string} source - Source description for error reporting
+ * @param {Array} errorMessages - Array to push error messages to
+ * @param {string} [markdownFilePath] - Path to the markdown file for resolving relative paths
+ * @param {string} [baseDir] - Base directory for resolving relative paths (alternative to markdownFilePath)
+ */
+function checkLocalImages(markdown, source, errorMessages, markdownFilePath, baseDir) {
+  const imageRegex = /!\[([^\]]*)\]\(([^)]+)\)/g;
+  let match;
+
+  while ((match = imageRegex.exec(markdown)) !== null) {
+    const imagePath = match[2].trim();
+    const altText = match[1];
+
+    // Skip external URLs (http/https)
+    if (/^https?:\/\//.test(imagePath)) continue;
+
+    // Skip data URLs
+    if (/^data:/.test(imagePath)) continue;
+
+    // Check if it's a local path
+    if (!imagePath.startsWith("/") && !imagePath.includes("://")) {
+      // It's a relative local path, check if file exists
+      try {
+        let resolvedPath;
+        if (markdownFilePath) {
+          // Resolve relative to the markdown file's directory
+          const markdownDir = path.dirname(markdownFilePath);
+          resolvedPath = path.resolve(markdownDir, imagePath);
+        } else if (baseDir) {
+          // Resolve relative to the provided base directory
+          resolvedPath = path.resolve(baseDir, imagePath);
+        } else {
+          // Fallback to current working directory
+          resolvedPath = path.resolve(imagePath);
+        }
+
+        if (!fs.existsSync(resolvedPath)) {
+          errorMessages.push(
+            `Found invalid local image in ${source}: ![${altText}](${imagePath}) - only valid media resources can be used`,
+          );
+        }
+      } catch {
+        errorMessages.push(
+          `Found invalid local image in ${source}: ![${altText}](${imagePath}) - only valid media resources can be used`,
+        );
+      }
+    } else if (imagePath.startsWith("/")) {
+      // Absolute local path
+      try {
+        if (!fs.existsSync(imagePath)) {
+          errorMessages.push(
+            `Found invalid local image in ${source}: ![${altText}](${imagePath}) - only valid media resources can be used`,
+          );
+        }
+      } catch {
+        errorMessages.push(
+          `Found invalid local image in ${source}: ![${altText}](${imagePath}) - only valid media resources can be used`,
+        );
+      }
+    }
+  }
+}
+
 /**
  * Check content structure and formatting issues
  * @param {string} markdown - The markdown content
@@ -224,7 +292,7 @@ function checkContentStructure(markdown, source, errorMessages) {
   }
 
   // Check if content ends with proper punctuation (indicating completeness)
-  const validEndingPunctuation = [".", "。", ")", "|"];
+  const validEndingPunctuation = [".", "。", ")", "|", "*"];
   const trimmedText = markdown.trim();
   const hasValidEnding = validEndingPunctuation.some((punct) => trimmedText.endsWith(punct));
 
@@ -241,6 +309,8 @@ function checkContentStructure(markdown, source, errorMessages) {
  * @param {string} [source] - Source description for error reporting (e.g., "result")
  * @param {Object} [options] - Additional options for validation
  * @param {Array} [options.allowedLinks] - Set of allowed links for link validation
+ * @param {string} [options.filePath] - Path to the markdown file for resolving relative image paths
+ * @param {string} [options.baseDir] - Base directory for resolving relative image paths (alternative to filePath)
  * @returns {Promise<Array<string>>} - Array of error messages in check-detail-result format
  */
 export async function checkMarkdown(markdown, source = "content", options = {}) {
@@ -248,8 +318,8 @@ export async function checkMarkdown(markdown, source = "content", options = {})
   const errorMessages = [];
 
   try {
-    // Extract allowed links from options
-    const { allowedLinks } = options;
+    // Extract allowed links, file path, and base directory from options
+    const { allowedLinks, filePath, baseDir } = options;
 
     // Create unified processor with markdown parsing and linting
     // Use individual rules instead of presets to have better control
@@ -292,7 +362,10 @@ export async function checkMarkdown(markdown, source = "content", options = {})
       checkDeadLinks(markdown, source, allowedLinks, errorMessages);
     }
 
-    // 2. Check content structure and formatting issues
+    // 2. Check local images existence
+    checkLocalImages(markdown, source, errorMessages, filePath, baseDir);
+
+    // 3. Check content structure and formatting issues
     checkContentStructure(markdown, source, errorMessages);
 
     // Check mermaid code blocks and other custom validations
@@ -319,30 +392,35 @@ export async function checkMarkdown(markdown, source = "content", options = {})
         // Check for backticks in node labels
         const nodeLabelRegex = /[A-Za-z0-9_]+\["([^"]*`[^"]*)"\]|[A-Za-z0-9_]+{"([^}]*`[^}]*)"}/g;
         let match;
-        while ((match = nodeLabelRegex.exec(mermaidContent)) !== null) {
+        match = nodeLabelRegex.exec(mermaidContent);
+        while (match !== null) {
           const label = match[1] || match[2];
           errorMessages.push(
             `Found backticks in Mermaid node label in ${source} at line ${line}: "${label}" - backticks in node labels cause rendering issues in Mermaid diagrams`,
           );
+          match = nodeLabelRegex.exec(mermaidContent);
         }
 
         // Check for numbered list format in edge descriptions
         const edgeDescriptionRegex = /--\s*"([^"]*)"\s*-->/g;
         let edgeMatch;
-        while ((edgeMatch = edgeDescriptionRegex.exec(mermaidContent)) !== null) {
+        edgeMatch = edgeDescriptionRegex.exec(mermaidContent);
+        while (edgeMatch !== null) {
           const description = edgeMatch[1];
           if (/^\d+\.\s/.test(description)) {
             errorMessages.push(
               `Unsupported markdown: list - Found numbered list format in Mermaid edge description in ${source} at line ${line}: "${description}" - numbered lists in edge descriptions are not supported`,
             );
           }
+          edgeMatch = edgeDescriptionRegex.exec(mermaidContent);
         }
 
         // Check for numbered list format in node labels (for both [] and {} syntax)
         const nodeLabelWithNumberRegex =
           /[A-Za-z0-9_]+\["([^"]*\d+\.\s[^"]*)"\]|[A-Za-z0-9_]+{"([^}]*\d+\.\s[^}]*)"}/g;
         let numberMatch;
-        while ((numberMatch = nodeLabelWithNumberRegex.exec(mermaidContent)) !== null) {
+        numberMatch = nodeLabelWithNumberRegex.exec(mermaidContent);
+        while (numberMatch !== null) {
           const label = numberMatch[1] || numberMatch[2];
           // Check if the label contains numbered list format
           if (/\d+\.\s/.test(label)) {
@@ -350,12 +428,14 @@ export async function checkMarkdown(markdown, source = "content", options = {})
               `Unsupported markdown: list - Found numbered list format in Mermaid node label in ${source} at line ${line}: "${label}" - numbered lists in node labels cause rendering issues`,
             );
           }
+          numberMatch = nodeLabelWithNumberRegex.exec(mermaidContent);
         }
 
         // Check for special characters in node labels that should be quoted
         const nodeWithSpecialCharsRegex = /([A-Za-z0-9_]+)\[([^\]]*[(){}:;,\-\s.][^\]]*)\]/g;
         let specialCharMatch;
-        while ((specialCharMatch = nodeWithSpecialCharsRegex.exec(mermaidContent)) !== null) {
+        specialCharMatch = nodeWithSpecialCharsRegex.exec(mermaidContent);
+        while (specialCharMatch !== null) {
           const nodeId = specialCharMatch[1];
           const label = specialCharMatch[2];
 
@@ -373,6 +453,7 @@ export async function checkMarkdown(markdown, source = "content", options = {})
               );
             }
           }
+          specialCharMatch = nodeWithSpecialCharsRegex.exec(mermaidContent);
         }
       }
     });
@@ -431,7 +512,6 @@ export async function checkMarkdown(markdown, source = "content", options = {})
     // Format messages in check-detail-result style
     file.messages.forEach((message) => {
       const line = message.line || "unknown";
-      const _column = message.column || "unknown";
       const reason = message.reason || "Unknown markdown issue";
       const ruleId = message.ruleId || message.source || "markdown";
 

package/utils/utils.mjs

@@ -149,8 +149,8 @@ export function getCurrentGitHead() {
  * @param {string} gitHead - The current git HEAD commit hash
  */
 export async function saveGitHeadToConfig(gitHead) {
-  if (!gitHead) {
-    return; // Skip if no git HEAD available
+  if (!gitHead || process.env.NODE_ENV === 'test' || process.env.BUN_TEST) {
+    return; // Skip if no git HEAD available or in test environment
   }
 
   try {