@aigne/doc-smith 0.8.12-beta.7 → 0.8.12-beta.9

package/package.json

@@ -1,10 +1,22 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.8.12-beta.7",
+  "version": "0.8.12-beta.9",
   "description": "AI-driven documentation generation tool built on the AIGNE Framework",
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "agents",
+    "assets/report-template",
+    "docs-mcp",
+    "prompts",
+    "types",
+    "utils",
+    "aigne.yaml",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "main": "index.js",
   "type": "module",
   "bin": "aigne.yaml",
@@ -18,7 +30,7 @@
     "@aigne/core": "^1.61.0",
     "@aigne/gemini": "^0.14.0",
     "@aigne/openai": "^0.16.0",
-    "@aigne/publish-docs": "^0.11.0",
+    "@aigne/publish-docs": "^0.12.0",
     "@blocklet/payment-broker-client": "^1.21.10",
     "@terrastruct/d2": "^0.1.33",
     "chalk": "^5.5.0",
@@ -29,17 +41,20 @@
     "fs-extra": "^11.3.1",
     "glob": "^11.0.3",
     "gpt-tokenizer": "^3.2.0",
+    "image-size": "^2.0.2",
     "isbinaryfile": "^5.0.6",
     "jsdom": "^26.1.0",
     "marked": "^15.0.12",
     "marked-terminal": "^7.3.0",
     "mermaid": "^11.9.0",
     "open": "^10.2.0",
+    "p-limit": "^7.1.1",
     "p-map": "^7.0.3",
     "p-retry": "^7.0.0",
     "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/prompts/common/document/role-and-personality.md

@@ -6,10 +6,12 @@ Your key strengths include:
   - Versatile Writing Style: You're not confined to specific technical domains and can adapt your language style to meet diverse documentation needs—whether technical specifications, user guides, product descriptions, or business process documentation.
   - Quality-Driven Approach: You consistently pursue top-tier documentation quality, ensuring accuracy, completeness, consistency, readability, and practicality. You pay attention to detail and strive for precision in every expression.
   - User-Centric Perspective: You think from the target reader's viewpoint, anticipating their potential questions and confusion, addressing them proactively in the documentation to enhance user experience and value.
+  - Tool Usage Capability: You can call available tools as needed based on context to query information, gather data, or generate visuals, ensuring the documentation is accurate, complete, and visually clear.
 
 **Your process must reflect ISTJ traits:**
 
 1.  **Fact-Driven:** Adhere strictly to the provided technical specifications. Do not infer or embellish information.
 2.  **Structured and Orderly:** Organize the content logically with clear headings, subheadings, lists, and tables. Present information sequentially where appropriate (e.g., installation steps).
 3.  **Clarity and Precision:** Use precise, unambiguous language. Define technical terms clearly. Avoid marketing jargon or emotionally charged words.
-4.  **Practical and Helpful:** Focus on providing practical examples, code snippets, and clear instructions that a user can directly apply.
+4.  **Practical and Helpful:** Focus on providing practical examples, code snippets, and clear instructions that a user can directly apply.
+5.  **Tool Utilization:** Actively call tools as needed, potentially multiple times, to obtain complete information from AFS (AIGNE File System) or generate Diagrams. Do not embed Mermaid or other diagram markup directly; include diagrams only via generateDiagram tool responses.

package/prompts/detail/d2-diagram/guide.md

@@ -1,5 +1,8 @@
 <diagram_generation_guide>
 1. Diagram Triggers and Types: Use the following guidelines to determine when to generate a diagram and which type to use.
+  - Rule for Skipping Diagrams:
+    - Trigger: Do not generate diagrams for purely textual, reference, or short note documents that describe abstract concepts, simple definitions, or FAQs.
+    - Action: Skip diagram generation entirely.
   - Architecture Diagram (High-Level)
     - Trigger: When generating a document that serves as a high-level overview of a system, project, or the entire documentation set.
     - Action: Create a system architecture diagram.
@@ -13,7 +16,10 @@
     - Action: Create the most appropriate diagram type:
       - Flowchart: Use for step-by-step processes, algorithms, or decision-making logic.
       - Sequence Diagram: Use for time-ordered interactions between different components or actors (e.g., API calls).
+NOTE:  For documents not skipped by the first rule but not clearly fitting the above categories, you should always attempt to generate at least one Diagram whenever possible to visually represent key structures, relationships, or processes in the content.
+
 2. Constraints and Best Practices
   - Quantity: Generate a maximum of three (3) diagrams per document to ensure the content remains focused and readable.
-  - Relevance: Ensure every diagram directly illustrates a concept explained in the surrounding text. Avoid generating diagrams for simple concepts that are easily understood through text alone.
+  - Relevance: Ensure every diagram directly illustrates a concept explained in the surrounding text. Avoid generating diagrams for concepts that are easily understood via text alone.
+  - Priority: For complex modules, workflows, or interactions, generate diagrams for each critical part.
 </diagram_generation_guide>

package/prompts/detail/d2-diagram/user-prompt.md

@@ -1,4 +1,7 @@
 Follow the given rules and ISTJ style from your system instructions.
 
 Generate a d2-diagram that represents the following document content:
+
+<document_content>
 {{documentContent}}
+</document_content>

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

@@ -1,6 +1,9 @@
 <role_and_goal>
 {% include "../../common/document/role-and-personality.md" %}
 
+
+**Fact Verification Rule:**
+Do not assume or infer any facts on your own. Treat all information as unknown until verified. Whenever possible, actively search and retrieve relevant, real-time information from **AFS (AIGNE File System)** or other available tools. Base your content strictly on the verified results from these searches or tool calls, rather than relying on memory or assumptions.
 </role_and_goal>
 
 
@@ -40,11 +43,7 @@ Custom component generation rules:
 Custom code block generation rules:
 {% include "../custom/custom-code-block.md" %}
 
-Diagram generation rules:
 {% include "../d2-diagram/guide.md" %}
-<diagram_generation_rules>
-{% include "../d2-diagram/system-prompt.md" %}
-</diagram_generation_rules>
 
 </content_generation_rules>
 
@@ -52,8 +51,8 @@ Diagram generation rules:
 
 <output_constraints>
 
-1. Output detailed text content for {{nodeName}}.
-2. Output {{nodeName}} content directly without including other information.
-3. Reference the style from examples only, **output content in {{locale}} language**
+1. Output the complete Markdown content for {{nodeName}}, only the content itself—no explanations or extra information.
+2. Follow the format, structure, tone, and level of detail shown in the examples, strictly adhering to <document_rules>, <content_generation_rules>, and <TONE_STYLE>.
+3. Output in {{locale}} language, ensuring clarity, conciseness, and well-organized structure.
 
 </output_constraints>

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

@@ -53,9 +53,18 @@ User feedback on previous generation:
 </feedback>
 {% endif %}
 
-{% include "../../common/afs/afs-tools-usage.md" %}
 
 <instructions>
-Generate detailed document for the current {{nodeName}} based on user-provided information: current {{nodeName}} details (including title, description, path), DataSources, documentStructure (overall structural planning), and other relevant information.
-{% include "../../common/afs/use-afs-instruction.md" %}
+Generate detailed and well-structured document for the current {{nodeName}} based on user-provided information: current {{nodeName}} details (including title, description, path), DataSources, documentStructure (overall structural planning), and other relevant information.
+
+YOU SHOULD:
+- Use AFS tools `afs_list` `afs_search` or `afs_read` to gather relevant and accurate information to enhance the content.
+- Follow rules in <diagram_generation_guide>: use `generateDiagram` to create and embed a diagram when appropriate, following the diagram generation guidelines.
+
+<steps>
+1. Analyze the provided document structure and user requirements to plan the content.
+2. Use AFS tools (`afs_list`/`afs_search`/`afs_read`) to search and gather relevant and accurate information to enhance the content.
+3. Use `generateDiagram` to create and embed a diagram when appropriate, following the diagram generation guidelines.
+4. Write clear, concise, and well-structured content for each section based on the planned structure and gathered information.
+</steps>
 </instructions>

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

@@ -32,9 +32,7 @@
 {{feedback}}
 </user_feedback>
 
-{% include "../../common/afs/afs-tools-usage.md" %}
 
 <instructions>
 Analyze the original document content and user feedback, then use available tools to implement the requested improvements while maintaining the document's integrity and style.
-{% include "../../common/afs/use-afs-instruction.md" %}
 </instructions>

package/prompts/evaluate/document-structure.md

@@ -31,16 +31,16 @@ You must **precisely map** the correspondence between each module in the structu
 Start from a **baseline of 80 points**. Evaluate by logging every key observation in `details` with one of five **levels**. Each level contributes a fixed delta; sum all deltas and add them to the baseline (clamp the final score to 0–100). Treat every key point independently so strengths and gaps can stack.
 
 **Level catalog (use consistently across all dimensions):**
-- `Excellent` — Exceptional: fully satisfies the dimension with clear, actionable outputs; scoring +10.
-- `Good` — Strong: aligns well with the dimension with only minor gaps apply +2 points; scoring +2.
-- `Meets` — Adequate: acceptable baseline coverage without notable strengths or weaknesses; scoring +0.
-- `Minor` — Problematic: specific deficiencies that reduce usefulness and require fixes; scoring -2.
-- `Critical` — Failing: fundamental issues that prevent the dimension from being met; scoring -10.
+- `Excellent` — Exceptional: fully satisfies the dimension with clear, actionable outputs.
+- `Good` — Strong: aligns well with the dimension with only minor gaps.
+- `Meets` — Adequate: acceptable baseline coverage without notable strengths or weaknesses.
+- `Minor` — Problematic: specific deficiencies that reduce usefulness and require fixes.
+- `Critical` — Failing: fundamental issues that prevent the dimension from being met.
 
 Apply these levels to the following key points. Create a separate detail entry for each observation; if the same issue repeats (e.g., multiple typos), record multiple entries at the appropriate level.
 
 1. **Purpose Coverage** — Evaluate every selected purpose, paying special attention to declared priorities:
-  - `Excellent`: The structure provides dedicated modules, explicit workflows, and measurable steps that achieve the purpose end-to-end scoring +10.
+  - `Excellent`: The structure provides dedicated modules, explicit workflows, and measurable steps that achieve the purpose end-to-end.
   - `Good`: The purpose is clearly mapped to modules with practical guidance and minimal omissions.
   - `Meets`: The purpose appears in general sections or implicit references but lacks targeted treatment.
   - `Minor`: Important sub-tasks or ordering for the purpose are missing or incomplete, reducing utility.
@@ -82,7 +82,6 @@ Strictly follow these steps:
 
 <output_constraints>
 
-- `baseline` must be fixed at 80
 - `details` is an array. Each element must include:
   - `dimension`: one of `purposeCoverage`, `audienceCoverage`, `coverageDepth`
   - `level`: one of `excellent`, `good`, `meets`, `minor`, `critical`

package/prompts/evaluate/document.md

@@ -48,73 +48,66 @@ Please **strictly adhere** to the evaluation standards defined in `<standards>`
 
 <standards>
 
-Start from a **baseline of 80 points**. Evaluate by logging every key observation in `details` using one of five **levels**. Each level corresponds to a fixed score delta: +10, +2, 0, -2, -10 respectively. Sum deltas with the baseline and clamp the final score to 0–100. Treat each key point independently so strengths and gaps can stack. When the same issue recurs (e.g., multiple typos), create multiple entries.
+Start from a **baseline of 80 points**. Evaluate by logging every key observation in `details` using one of five **levels**. Each level corresponds to a fixed score delta. Sum deltas with the baseline and clamp the final score to 0–100. Treat each key point independently so strengths and gaps can stack. When the same issue recurs (e.g., multiple typos), create multiple entries.
 
 **Level catalog (use consistently across all dimensions):**
-- `Excellent` — Exceptional output that fully satisfies the dimension with clear, actionable results; scoring +10.
-- `Good` — Strong and mostly complete alignment with the dimension; minor gaps only; scoring +2.
-- `Meets` — Satisfactory baseline coverage without significant strengths or faults; scoring +0.
-- `Minor` — Specific problems that reduce usefulness and should be corrected; scoring -2.
-- `Critical` — Fundamental failures that prevent the dimension from being met; scoring -10.
+- `Excellent` — Exceptional output that fully satisfies the dimension with clear, actionable results.
+- `Good` — Strong and mostly complete alignment with the dimension; minor gaps only.
+- `Meets` — Satisfactory baseline coverage without significant strengths or faults.
+- `Minor` — Specific problems that reduce usefulness and should be corrected.
+- `Critical` — Fundamental failures that prevent the dimension from being met.
 
 Apply these levels to the following evaluation dimensions:
 
-1. **Readability** — Language clarity, grammar, spelling, and fluency.
+1. **Readability** — Language clarity, grammar, spelling, and fluency. **MUST evaluate on every document**
    - `Excellent`: Text is polished, natural, and easy to read; terminology is well chosen and consistent.
    - `Good`: Minor slips (occasional typos or awkward phrasing) that do not impede understanding.
    - `Meets`: Understandable but plain or mechanical; no major errors.
    - `Minor`: Noticeable grammar or spelling mistakes in specific sentences that need fixes.
    - `Critical`: Language prevents comprehension or is unusable.
 
-2. **Coherence** — Logical flow, transitions, and absence of contradictions.
+2. **Coherence** — Logical flow, transitions, and absence of contradictions. **MUST evaluate on every document**
    - `Excellent`: Clear, well-ordered flow with explicit transitions and consistent argumentation.
    - `Good`: Mostly coherent with small gaps in transitions or sequencing.
    - `Meets`: Functional flow but requires reader inference to connect ideas.
    - `Minor`: Local ordering problems or small contradictions that confuse the reader.
    - `Critical`: Structural contradictions or ordering failures that break the document's logic.
 
-3. **Content Quality** — Coverage, accuracy, examples, and actionable detail relative to the plan (`description`).
+3. **Content Quality** — Coverage, accuracy, examples, and actionable detail relative to the plan (`description`). **MUST evaluate on every document**
    - `Excellent`: Content fully implements the plan with accurate, actionable guidance and relevant examples.
    - `Good`: Most planned items are addressed with only minor missing details.
    - `Meets`: Baseline coverage is present but lacks depth or practical instructions.
    - `Minor`: Certain sections are missing, incorrect, or ambiguous and should be corrected.
    - `Critical`: Core content is wrong or absent, failing to deliver planned outcomes.
 
-4. **Consistency** — Terminology, style, formatting, and references.
+4. **Consistency** — Terminology, style, formatting, and references. **MUST evaluate on every document**
    - `Excellent`: Terms, style, and formatting are uniform and purposeful across the document.
    - `Good`: Largely consistent with only isolated mismatches that do not impede understanding.
    - `Meets`: Acceptable uniformity but lacks deliberate stylistic cohesion.
    - `Minor`: Specific term or formatting inconsistencies that should be standardized.
    - `Critical`: Pervasive inconsistency that undermines trust in the content.
 
-5. **Purpose Alignment** — Relevance to user-selected purposes (document only needs to satisfy at least one when multiples exist).
-   - `Excellent`: The document supplies targeted sections, validation steps, and clear calls-to-action that realize the chosen purpose scoring +10.
+5. **Purpose Alignment** — Relevance to user-selected purposes (document only needs to satisfy at least one when multiples exist). (Conditional Rule Application: When evaluating this document, first determine if its content (topic, type, format, etc.) is highly relevant to the scope of this evaluation rule. Apply this specific criterion only if the content is deemed relevant.)
+   - `Excellent`: The document supplies targeted sections, validation steps, and clear calls-to-action that realize the chosen purpose.
    - `Good`: Purpose is clearly addressed but may lack polish or some validation details.
    - `Meets`: Purpose is present in general terms but lacks concrete steps or targeted content.
    - `Minor`: Key components required by the purpose are missing or incomplete.
    - `Critical`: Document fails to address the selected purpose or pursues a different objective.
 
-6. **Audience Alignment** — Tone, assumptions, and artifacts for target persona(s).
+6. **Audience Alignment** — Tone, assumptions, and artifacts for target persona(s). (Conditional Rule Application: When evaluating this document, first determine if its content (topic, type, format, etc.) is highly relevant to the scope of this evaluation rule. Apply this specific criterion only if the content is deemed relevant.)
    - `Excellent`: Messaging, examples, and precautions are tailored to each audience persona and their needs.
    - `Good`: Tone and examples suit the audience with only minor mismatches.
    - `Meets`: Document is generally usable by audiences but lacks persona-specific guidance.
    - `Minor`: Sections explicitly mismatch audience skill levels or expectations and should be revised.
    - `Critical`: Document is pitched at the wrong audience and cannot be used meaningfully.
 
-7. **Knowledge Level Alignment** — Depth versus reader expertise.
+7. **Knowledge Level Alignment** — Depth versus reader expertise. (Conditional Rule Application: When evaluating this document, first determine if its content (topic, type, format, etc.) is highly relevant to the scope of this evaluation rule. Apply this specific criterion only if the content is deemed relevant.)
    - `Excellent`: Material offers layered explanations, optional deep dives, and matches expected expertise.
    - `Good`: Overall depth fits the reader with small areas that are slightly over- or under-advanced.
-   - `Meets`: Baseline depth is acceptable but uneven across topics scoring 0.
+   - `Meets`: Baseline depth is acceptable but uneven across topics.
    - `Minor`: Specific sections are noticeably too shallow or too advanced and need rework.
    - `Critical`: The document's level is consistently misaligned with reader expertise.
 
-8. **Navigability** — Link accuracy, anchor availability, and cross-reference integrity.
-   - `Excellent`: TOC, anchors, and cross-links are accurate and make navigation effortless.
-   - `Good`: Navigation and links are mostly correct with minor issues scoring +2.
-   - `Meets`: Basic navigation exists but lacks robust anchors or enhancements.
-   - `Minor`: Some broken or mismatched links and missing anchors that should be fixed.
-   - `Critical`: Multiple broken links or mislabeled sections make navigation unreliable.
-
 </standards>
 
 <rules>
@@ -136,10 +129,8 @@ Strictly follow these steps:
 </rules>
 
 <output_constraints>
-
-- `baseline` must be fixed at 80
 - `details` is an array. Each element must include:
-  - `dimension`: one of `readability`, `coherence`, `contentQuality`, `consistency`, `purposeAlignment`, `audienceAlignment`, `knowledgeLevelAlignment`, `navigability`
+  - `dimension`: one of `readability`, `coherence`, `contentQuality`, `consistency`, `purposeAlignment`, `audienceAlignment`, `knowledgeLevelAlignment`
   - `level`: one of `excellent`, `good`, `meets`, `minor`, `critical`
   - `topic`: short identifier for the passage/section being judged
   - `line`: integer line number within the source document (use 0 if unknown)

package/prompts/media/media-description/system-prompt.md

@@ -0,0 +1,35 @@
+<role_and_goal>
+You are an expert at analyzing media files (images and videos) and generating concise, meaningful descriptions for documentation content.
+
+Your goal is to examine a single media file and generate an accurate description that helps both AI content generators and human readers understand what the media depicts and how it can be used effectively in documentation.
+</role_and_goal>
+
+<analysis_workflow>
+1. **Analyze**: Examine the media file carefully and identify:
+   - The main subject or component being shown
+   - Key visual elements (colors, composition, style)
+   - Notable features or functionality visible
+   - The purpose or context of this media
+   - Mood or atmosphere if distinctive
+   - For videos: key actions, movements, or transitions
+
+2. **Generate Description**: Create a concise, human-readable description following these principles:
+   - Keep it between 2-3 sentences
+   - Be specific and descriptive about visual content
+   - For videos, describe the key content or action shown
+   - Focus on aspects that matter for documentation usage
+   - Remain objective - describe what you see, not what you interpret
+</analysis_workflow>
+
+<description_guidelines>
+**What to Include:**
+- Main subject or focus of the media
+- Key visual elements and composition
+- Context or setting if relevant for understanding
+- Technical aspects if relevant (e.g., "screenshot", "diagram", "illustration", "animation")
+- Key features or functionality visible
+- Its purpose or functionality
+- Any notable UI elements or features
+- For videos: describe the main action, movement, or narrative
+</description_guidelines>
+

package/prompts/media/media-description/user-prompt.md

@@ -0,0 +1,8 @@
+<media_information>
+- File: {{name}}
+- Type: {{type}}
+{%if width and height %}
+- Dimensions: {{width}}x{{height}}px
+{%endif%}
+</media_information>
+

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

@@ -21,8 +21,6 @@ Initial Documentation Structure:
 {{ feedback }}
 </user_feedback>
 
-{% include "../../common/afs/afs-tools-usage.md" %}
-
 <instructions>
 
 Objectives:
@@ -41,6 +39,4 @@ Processing workflow:
 Rules:
 ** All changes must be made using Tools. **
 ** Carefully check if the latest version of documentStructure data meets user requirements, must avoid duplicate Tool calls. **
-
-{% include "../../common/afs/use-afs-instruction.md" %}
 </instructions>

package/utils/constants/index.mjs

@@ -548,110 +548,3 @@ export const DOC_SMITH_DIR = ".aigne/doc-smith";
 export const TMP_DIR = ".tmp";
 export const TMP_DOCS_DIR = "docs";
 export const TMP_ASSETS_DIR = "assets";
-
-// Default evaluation scoring weights
-export const DEFAULT_EVALUATION_WEIGHTS = {
-  evaluationConfig: {
-    accuracy: {
-      weight: 0.35,
-      description: "Technical correctness of the documentation.",
-      subDimensions: {
-        signatureConsistency: {
-          weight: 0.5,
-          description:
-            "Function signatures match the source code (e.g., OpenAPI spec, TypeScript types).",
-        },
-        linkValidity: {
-          weight: 0.25,
-          description: "No broken internal links or invalid cross-references.",
-        },
-        codeExampleIntegrity: {
-          weight: 0.25,
-          description:
-            "All code blocks are syntactically valid and labeled with the correct language.",
-        },
-      },
-    },
-    coverage: {
-      weight: 0.35,
-      description: "Completeness of documentation for all public components.",
-      subDimensions: {
-        apiCoverage: {
-          weight: 0.4,
-          description: "Percentage of exported functions/classes documented.",
-        },
-        paramReturnCoverage: {
-          weight: 0.3,
-          description: "Percentage of function parameters and return values described.",
-        },
-        changeTracking: {
-          weight: 0.3,
-          description:
-            "All new or modified code since the last commit is reflected in the documentation.",
-        },
-      },
-    },
-    readability: {
-      weight: 0.15,
-      description: "Ease of understanding for human readers.",
-      subDimensions: {
-        clarityScore: {
-          weight: 0.28,
-          description:
-            "Overall clarity including reading coherence, logical flow and translation quality.",
-        },
-        consistency: {
-          weight: 0.12,
-          description: "Terminology, style and formatting are unified and professional.",
-        },
-        contentQuality: {
-          weight: 0.24,
-          description:
-            "Accurate and complete content that adds value with sufficient detail and examples.",
-        },
-        purposeAlignment: {
-          weight: 0.14,
-          description:
-            "Content matches the intended purpose such as quick start, API reference or troubleshooting.",
-        },
-        audienceAlignment: {
-          weight: 0.12,
-          description:
-            "Language and examples match the target audience (e.g., developers, non-technical users).",
-        },
-        knowledgeLevelAlignment: {
-          weight: 0.1,
-          description: "Depth and difficulty fit the readers' knowledge level.",
-        },
-      },
-    },
-    structure: {
-      weight: 0.15,
-      description: "Organization and navigability of the documentation.",
-      subDimensions: {
-        navigability: {
-          weight: 0.2,
-          description: "Table of contents entries correctly link to headings.",
-        },
-        informationScent: {
-          weight: 0.2,
-          description:
-            "Key pages such as Quick Start can be reached within three clicks from the homepage.",
-        },
-        purposeCoverage: {
-          weight: 0.25,
-          description:
-            "Structure covers all selected documentation goals without forcing them into a single page.",
-        },
-        audienceCoverage: {
-          weight: 0.2,
-          description: "Structure covers the main intended audience groups.",
-        },
-        coverageDepthAlignment: {
-          weight: 0.15,
-          description: "Overall balance of conciseness, depth and breadth meets user expectations.",
-        },
-      },
-    },
-  },
-};

package/utils/file-utils.mjs

@@ -558,3 +558,89 @@ export function getStructurePlanPath(workDir) {
   const cwd = workDir || process.cwd();
   return path.join(cwd, ".aigne", "doc-smith", "output", "structure-plan.json");
 }
+
+// Shared extension → MIME type mapping table
+const EXT_TO_MIME = {
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".gif": "image/gif",
+  ".bmp": "image/bmp",
+  ".webp": "image/webp",
+  ".svg": "image/svg+xml",
+  ".heic": "image/heic",
+  ".heif": "image/heif",
+  ".mp4": "video/mp4",
+  ".mpeg": "video/mpeg",
+  ".mpg": "video/mpg",
+  ".mov": "video/mov",
+  ".avi": "video/avi",
+  ".flv": "video/x-flv",
+  ".mkv": "video/x-matroska",
+  ".webm": "video/webm",
+  ".wmv": "video/wmv",
+  ".m4v": "video/x-m4v",
+  ".3gpp": "video/3gpp",
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".pdf": "application/pdf",
+  ".doc": "application/msword",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".xls": "application/vnd.ms-excel",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".ppt": "application/vnd.ms-powerpoint",
+  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  ".txt": "text/plain",
+  ".json": "application/json",
+  ".xml": "application/xml",
+  ".html": "text/html",
+  ".css": "text/css",
+  ".js": "application/javascript",
+  ".zip": "application/zip",
+  ".rar": "application/x-rar-compressed",
+  ".7z": "application/x-7z-compressed",
+};
+
+// Build reverse mapping: MIME → extensions
+const MIME_TO_EXTS = Object.entries(EXT_TO_MIME).reduce((acc, [ext, mime]) => {
+  const key = mime.toLowerCase();
+  if (!acc[key]) {
+    acc[key] = [];
+  }
+  acc[key].push(ext);
+  return acc;
+}, {});
+
+/**
+ * Get MIME type from file path based on extension
+ * @param {string} filePath - File path
+ * @returns {string} MIME type
+ */
+export function getMimeType(filePath) {
+  const ext = path.extname(filePath || "").toLowerCase();
+  return EXT_TO_MIME[ext] || "application/octet-stream";
+}
+
+/**
+ * Get file extension (without dot) from content type
+ * Handles content types with parameters (e.g., "image/jpeg; charset=utf-8")
+ * @param {string} contentType - Content type string
+ * @returns {string} File extension without dot
+ */
+export function getExtnameFromContentType(contentType) {
+  if (!contentType) return "";
+  const base = String(contentType).split(";")[0].trim().toLowerCase();
+  const exts = MIME_TO_EXTS[base];
+  if (exts?.length) return exts[0].slice(1); // Remove leading dot
+  const parts = base.split("/");
+  return parts[1] || "";
+}
+
+/**
+ * Get media description cache file path
+ * @returns {string} Absolute path to media-description.yaml
+ */
+export function getMediaDescriptionCachePath() {
+  const cwd = process.cwd();
+  return path.join(cwd, ".aigne", "doc-smith", "media-description.yaml");
+}

package/utils/markdown-checker.mjs

@@ -1,14 +1,11 @@
 import fs from "node:fs";
 import path from "node:path";
-import pMap from "p-map";
 import remarkGfm from "remark-gfm";
 import remarkLint from "remark-lint";
 import remarkParse from "remark-parse";
 import { unified } from "unified";
 import { visit } from "unist-util-visit";
 import { VFile } from "vfile";
-import { KROKI_CONCURRENCY } from "./constants/index.mjs";
-import { checkContent, isValidCode } from "./d2-utils.mjs";
 import { validateMermaidSyntax } from "./mermaid-validator.mjs";
 
 /**
@@ -378,7 +375,6 @@ export async function checkMarkdown(markdown, source = "content", options = {})
 
     // Check mermaid code blocks and other custom validations
     const mermaidChecks = [];
-    const d2ChecksList = [];
     visit(ast, "code", (node) => {
       if (node.lang) {
         const line = node.position?.start?.line || "unknown";
@@ -467,12 +463,6 @@ export async function checkMarkdown(markdown, source = "content", options = {})
             specialCharMatch = nodeWithSpecialCharsRegex.exec(mermaidContent);
           }
         }
-        if (isValidCode(node.lang)) {
-          d2ChecksList.push({
-            content: node.value,
-            line,
-          });
-        }
       }
     });
 
@@ -524,16 +514,6 @@ export async function checkMarkdown(markdown, source = "content", options = {})
     // Wait for all mermaid checks to complete
     await Promise.all(mermaidChecks);
 
-    await pMap(
-      d2ChecksList,
-      async ({ content, line }) =>
-        checkContent({ content }).catch((err) => {
-          const errorMessage = err?.message || String(err) || "Unknown d2 syntax error";
-          errorMessages.push(`Found D2 syntax error in ${source} at line ${line}: ${errorMessage}`);
-        }),
-      { concurrency: KROKI_CONCURRENCY },
-    );
-
     // Run markdown linting rules
     await processor.run(ast, file);
 

package/utils/request.mjs

@@ -0,0 +1,7 @@
+export async function requestWithAuthToken(url, options, authToken) {
+  const response = await fetch(url, {
+    ...options,
+    headers: { ...options.headers, Authorization: `Bearer ${authToken}` },
+  });
+  return response.json();
+}