@aigne/doc-smith 0.8.13-beta → 0.8.14-beta

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.8.14-beta](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.13...v0.8.14-beta) (2025-10-16)
+
+
+### Features
+
+* **file-utils:** add comprehensive file type detection and image upload functionality ([#200](https://github.com/AIGNE-io/aigne-doc-smith/issues/200)) ([ab7aae3](https://github.com/AIGNE-io/aigne-doc-smith/commit/ab7aae33ed9b5209e824ba91fbf9c94d37187d83))
+
+
+### Bug Fixes
+
+* use `output` field present tool result to enhance LLM understanding ([#202](https://github.com/AIGNE-io/aigne-doc-smith/issues/202)) ([511178d](https://github.com/AIGNE-io/aigne-doc-smith/commit/511178de7a88fdecf2136f90035d87957e23b23f))
+
+## [0.8.13](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.13-beta...v0.8.13) (2025-10-16)
+
+
+### Miscellaneous Chores
+
+* release 0.8.13 ([496e30f](https://github.com/AIGNE-io/aigne-doc-smith/commit/496e30f60d7e78602ffdc0fc070bf09ce4415fde))
+
 ## [0.8.13-beta](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.12...v0.8.13-beta) (2025-10-16)
 
 

package/agents/generate/check-diagram.mjs

@@ -1,8 +1,8 @@
 import { checkContent } from "../../utils/d2-utils.mjs";
 
-export default async function checkD2DiagramIsValid({ diagramSourceCode }) {
+export default async function checkD2DiagramIsValid({ output }) {
   try {
-    await checkContent({ content: diagramSourceCode });
+    await checkContent({ content: output });
     return {
       isValid: true,
     };
@@ -17,12 +17,12 @@ export default async function checkD2DiagramIsValid({ diagramSourceCode }) {
 checkD2DiagramIsValid.input_schema = {
   type: "object",
   properties: {
-    diagramSourceCode: {
+    output: {
       type: "string",
       description: "Source code of d2 diagram",
     },
   },
-  required: ["diagramSourceCode"],
+  required: ["output"],
 };
 checkD2DiagramIsValid.output_schema = {
   type: "object",

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

@@ -4,11 +4,11 @@ export default async function wrapDiagramCode({ diagramSourceCode }) {
   try {
     const result = await wrapCode({ content: diagramSourceCode });
     return {
-      diagramSourceCode: result,
+      output: result,
     };
   } catch {
     return {
-      diagramSourceCode,
+      output: diagramSourceCode,
     };
   }
 }
@@ -26,10 +26,10 @@ wrapDiagramCode.input_schema = {
 wrapDiagramCode.output_schema = {
   type: "object",
   properties: {
-    diagramSourceCode: {
+    output: {
       type: "string",
       description: "Source code of d2 diagram",
     },
   },
-  required: ["diagramSourceCode"],
+  required: ["output"],
 };

package/agents/publish/publish-docs.mjs

@@ -1,9 +1,8 @@
-import { basename, extname, join } from "node:path";
+import { basename, join } from "node:path";
 import { publishDocs as publishDocsFn } from "@aigne/publish-docs";
 import { BrokerClient } from "@blocklet/payment-broker-client/node";
 import chalk from "chalk";
 import fs from "fs-extra";
-import slugify from "slugify";
 
 import { getAccessToken, getOfficialAccessToken } from "../../utils/auth-utils.mjs";
 import {
@@ -15,8 +14,6 @@ import {
 } from "../../utils/constants/index.mjs";
 import { beforePublishHook, ensureTmpDir } from "../../utils/d2-utils.mjs";
 import { deploy } from "../../utils/deploy.mjs";
-import { getExtnameFromContentType } from "../../utils/file-utils.mjs";
-import { uploadFiles } from "../../utils/upload-files.mjs";
 import {
   getGithubRepoUrl,
   isHttp,
@@ -24,6 +21,7 @@ import {
   saveValueToConfig,
 } from "../../utils/utils.mjs";
 import updateBranding from "../utils/update-branding.mjs";
+import { downloadAndUploadImage } from "../../utils/file-utils.mjs";
 
 const BASE_URL = process.env.DOC_SMITH_BASE_URL || CLOUD_SERVICE_URL_PROD;
 
@@ -175,46 +173,22 @@ export default async function publishDocs(
       description: projectDesc || config?.projectDesc || "",
       icon: projectLogo || config?.projectLogo || "",
     };
+    let finalPath = null;
 
     // Handle project logo download if it's a URL
     if (projectInfo.icon && isHttp(projectInfo.icon)) {
-      const tempFilePath = join(docsDir, slugify(basename(projectInfo.icon)));
-      const initialExt = extname(projectInfo.icon);
-      let ext = initialExt;
-
-      try {
-        const response = await fetch(projectInfo.icon);
-        const blob = await response.blob();
-        const arrayBuffer = await blob.arrayBuffer();
-        const buffer = Buffer.from(arrayBuffer);
-
-        if (response.ok) {
-          if (!ext) {
-            const contentType = response.headers.get("content-type");
-            ext = getExtnameFromContentType(contentType);
-          }
-
-          const finalPath = ext ? `${tempFilePath}.${ext}` : tempFilePath;
-          fs.writeFileSync(finalPath, buffer);
-
-          const filePath = join(process.cwd(), finalPath);
-          const { results: uploadResults } = await uploadFiles({
-            appUrl,
-            filePaths: [filePath],
-            accessToken,
-            concurrency: 1,
-          });
-
-          // FIXME: 暂时保持使用绝对路径，需要修改为相对路径 @pengfei
-          projectInfo.icon = uploadResults?.[0]?.url || projectInfo.icon;
-        }
-      } catch (error) {
-        console.warn(`Failed to download project logo from ${projectInfo.icon}: ${error.message}`);
-      }
+      const { url: uploadedImageUrl, downloadFinalPath } = await downloadAndUploadImage(
+        projectInfo.icon,
+        docsDir,
+        appUrl,
+        accessToken,
+      );
+      projectInfo.icon = uploadedImageUrl;
+      finalPath = downloadFinalPath;
     }
 
     if (shouldWithBranding) {
-      updateBranding({ appUrl, projectInfo, accessToken });
+      updateBranding({ appUrl, projectInfo, accessToken, finalPath });
     }
 
     // Construct boardMeta object

package/agents/utils/update-branding.mjs

@@ -1,5 +1,4 @@
 import { stat } from "node:fs/promises";
-import { resolve } from "node:path";
 import chalk from "chalk";
 import { joinURL } from "ufo";
 
@@ -8,12 +7,11 @@ import {
   CLOUD_SERVICE_URL_PROD,
   CLOUD_SERVICE_URL_STAGING,
   DISCUSS_KIT_DID,
-  DOC_SMITH_DIR,
 } from "../../utils/constants/index.mjs";
 import { requestWithAuthToken } from "../../utils/request.mjs";
 import { uploadFiles } from "../../utils/upload-files.mjs";
 
-export default async function updateBranding({ appUrl, projectInfo, accessToken }) {
+export default async function updateBranding({ appUrl, projectInfo, accessToken, finalPath }) {
   try {
     const origin = new URL(appUrl).origin;
     if ([CLOUD_SERVICE_URL_PROD, CLOUD_SERVICE_URL_STAGING].includes(origin)) {
@@ -43,15 +41,19 @@ export default async function updateBranding({ appUrl, projectInfo, accessToken
     );
 
     if (res.success) {
+      if (!finalPath) {
+        console.warn("\n🔄 Skipped updating branding for missing logo file\n");
+        return;
+      }
+
       try {
-        const projectLogoPath = resolve(process.cwd(), DOC_SMITH_DIR, projectInfo.icon);
-        const projectLogoStat = await stat(projectLogoPath);
+        const projectLogoStat = await stat(finalPath);
 
         if (projectLogoStat.isFile()) {
           // Upload to blocklet logo endpoint
           await uploadFiles({
             appUrl: origin,
-            filePaths: [projectLogoPath],
+            filePaths: [finalPath],
             accessToken,
             concurrency: 1,
             endpoint: `${origin}/.well-known/service/blocklet/logo/upload/square/${componentInfo.did}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.8.13-beta",
+  "version": "0.8.14-beta",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"
@@ -38,6 +38,7 @@
     "debug": "^4.4.1",
     "diff": "^8.0.2",
     "dompurify": "^3.2.6",
+    "file-type": "^21.0.0",
     "fs-extra": "^11.3.1",
     "glob": "^11.0.3",
     "gpt-tokenizer": "^3.2.0",
@@ -54,7 +55,6 @@
     "remark-gfm": "^4.0.1",
     "remark-lint": "^10.0.1",
     "remark-parse": "^11.0.0",
-    "slugify": "^1.6.6",
     "terminal-link": "^4.0.0",
     "ufo": "^1.6.1",
     "unified": "^11.0.5",

package/utils/file-utils.mjs

@@ -1,11 +1,16 @@
 import { execSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { access, readFile, stat } from "node:fs/promises";
-import path from "node:path";
+import path, { join } from "node:path";
 import { glob } from "glob";
+import fs from "fs-extra";
 import { isBinaryFile } from "isbinaryfile";
 import { encode } from "gpt-tokenizer";
+import { fileTypeFromBuffer } from "file-type";
+import { gunzipSync } from "node:zlib";
 import { isGlobPattern } from "./utils.mjs";
 import { INTELLIGENT_SUGGESTION_TOKEN_THRESHOLD } from "./constants/index.mjs";
+import { uploadFiles } from "./upload-files.mjs";
 
 /**
  * Check if a directory is inside a git repository using git command
@@ -644,3 +649,182 @@ export function getMediaDescriptionCachePath() {
   const cwd = process.cwd();
   return path.join(cwd, ".aigne", "doc-smith", "media-description.yaml");
 }
+
+/**
+ * Detect file type from buffer with comprehensive fallback strategy
+ * @param {Buffer} buffer - File buffer
+ * @param {string} contentType - HTTP Content-Type header
+ * @param {string} url - Original URL (for fallback)
+ * @returns {Promise<{ext: string, mime: string}>} File extension and MIME type
+ */
+export async function detectFileType(buffer, contentType, url = "") {
+  // 1. Try file-type for binary images (PNG, JPG, WebP, GIF, etc.)
+  try {
+    const fileType = await fileTypeFromBuffer(buffer);
+    if (fileType) {
+      return {
+        ext: fileType.ext,
+        mime: fileType.mime,
+      };
+    }
+  } catch (error) {
+    console.debug("file-type detection failed:", error.message);
+  }
+
+  // 2. Check for SVG/SVGZ
+  const svgResult = await detectSvgType(buffer, contentType);
+  if (svgResult) {
+    return svgResult;
+  }
+
+  // 3. Fallback to Content-Type
+  if (contentType) {
+    const ext = getExtnameFromContentType(contentType);
+    if (ext) {
+      return {
+        ext,
+        mime: contentType.split(";")[0].trim(),
+      };
+    }
+  }
+
+  // 4. Fallback to URL extension
+  if (url) {
+    const urlExt = path.extname(url).toLowerCase();
+    if (urlExt) {
+      return {
+        ext: urlExt.slice(1), // Remove leading dot
+        mime: getMimeType(url),
+      };
+    }
+  }
+
+  // 5. Default fallback
+  return {
+    ext: "bin",
+    mime: "application/octet-stream",
+  };
+}
+
+/**
+ * Detect SVG/SVGZ file type
+ * @param {Buffer} buffer - File buffer
+ * @param {string} contentType - HTTP Content-Type header
+ * @returns {Promise<{ext: string, mime: string} | null>} SVG info or null
+ */
+async function detectSvgType(buffer, contentType) {
+  // Check Content-Type first
+  if (contentType?.includes("image/svg+xml")) {
+    return {
+      ext: "svg",
+      mime: "image/svg+xml",
+    };
+  }
+
+  try {
+    let text = "";
+
+    // Check if it's gzipped (SVGZ)
+    if (buffer.length >= 2 && buffer[0] === 0x1f && buffer[1] === 0x8b) {
+      try {
+        const decompressed = gunzipSync(buffer);
+        text = decompressed.toString("utf8");
+        if (isSvgContent(text)) {
+          return {
+            ext: "svgz",
+            mime: "image/svg+xml",
+          };
+        }
+      } catch {
+        // Not gzipped, continue with regular text detection
+      }
+    }
+
+    // Try as regular text
+    if (!text) {
+      text = buffer.toString("utf8");
+    }
+
+    if (isSvgContent(text)) {
+      return {
+        ext: "svg",
+        mime: "image/svg+xml",
+      };
+    }
+  } catch (error) {
+    console.debug("SVG detection failed:", error.message);
+  }
+
+  return null;
+}
+
+/**
+ * Check if text content is SVG
+ * @param {string} text - Text content
+ * @returns {boolean} True if SVG
+ */
+function isSvgContent(text) {
+  if (!text || typeof text !== "string") return false;
+
+  // Remove BOM and trim
+  const cleanText = text.replace(/^\uFEFF/, "").trim();
+
+  // Check for SVG root element
+  return /^<\?xml\s+[^>]*>\s*<svg/i.test(cleanText) || /^<svg/i.test(cleanText);
+}
+
+/**
+ * Download and upload a remote image URL
+ * @param {string} imageUrl - The remote image URL
+ * @param {string} docsDir - Directory to save temporary files
+ * @param {string} appUrl - Application URL for upload
+ * @param {string} accessToken - Access token for upload
+ * @returns {Promise<{url: string, downloadFinalPath: string | null}>} The uploaded image URL and final path if failed
+ */
+export async function downloadAndUploadImage(imageUrl, docsDir, appUrl, accessToken) {
+  let downloadFinalPath = null;
+
+  try {
+    // 1. Download with timeout control
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 30000); // 30s timeout
+
+    const response = await fetch(imageUrl, {
+      signal: controller.signal,
+    });
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    // 2. Convert to Buffer for file type detection
+    const blob = await response.blob();
+    const arrayBuffer = await blob.arrayBuffer();
+    const buffer = Buffer.from(arrayBuffer);
+
+    // 3. Detect file type with comprehensive fallback
+    const contentType = response.headers.get("content-type");
+    const { ext } = await detectFileType(buffer, contentType, imageUrl);
+
+    // 4. Generate random filename and save file
+    const randomId = randomBytes(16).toString("hex");
+    const tempFilePath = join(docsDir, `temp-logo-${randomId}`);
+    downloadFinalPath = ext ? `${tempFilePath}.${ext}` : tempFilePath;
+    fs.writeFileSync(downloadFinalPath, buffer);
+
+    // 5. Upload and get URL
+    const { results: uploadResults } = await uploadFiles({
+      appUrl,
+      filePaths: [downloadFinalPath],
+      accessToken,
+      concurrency: 1,
+    });
+
+    // 6. Return uploaded URL
+    return { url: uploadResults?.[0]?.url || imageUrl, downloadFinalPath };
+  } catch (error) {
+    console.warn(`Failed to download and upload image from ${imageUrl}: ${error.message}`);
+    return { url: imageUrl, downloadFinalPath: null };
+  }
+}