@aigne/doc-smith 0.6.0 → 0.7.1

package/agents/load-sources.mjs

@@ -2,7 +2,11 @@ import { access, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_INCLUDE_PATTERNS } from "../utils/constants.mjs";
 import { getFilesWithGlob, loadGitignore } from "../utils/file-utils.mjs";
-import { getCurrentGitHead, getModifiedFilesBetweenCommits } from "../utils/utils.mjs";
+import {
+  getCurrentGitHead,
+  getModifiedFilesBetweenCommits,
+  isGlobPattern,
+} from "../utils/utils.mjs";
 
 export default async function loadSources({
   sources = [],
@@ -24,7 +28,12 @@ export default async function loadSources({
 
     for (const dir of paths) {
       try {
-        // Check if the path is a file or directory
+        if (typeof dir !== "string") {
+          console.warn(`Invalid source path: ${dir}`);
+          continue;
+        }
+
+        // First try to access as a file or directory
         const stats = await stat(dir);
 
         if (stats.isFile()) {
@@ -78,7 +87,31 @@ export default async function loadSources({
           allFiles = allFiles.concat(filesInDir);
         }
       } catch (err) {
-        if (err.code !== "ENOENT") throw err;
+        if (err.code === "ENOENT") {
+          // Path doesn't exist as file or directory, try as glob pattern
+          try {
+            // Check if it looks like a glob pattern
+            const isGlobPatternResult = isGlobPattern(dir);
+
+            if (isGlobPatternResult) {
+              // Use glob to find matching files from current working directory
+              const { glob } = await import("glob");
+              const matchedFiles = await glob(dir, {
+                absolute: true,
+                nodir: true, // Only files, not directories
+                dot: false, // Don't include hidden files
+              });
+
+              if (matchedFiles.length > 0) {
+                allFiles = allFiles.concat(matchedFiles);
+              }
+            }
+          } catch (globErr) {
+            console.warn(`Failed to process glob pattern "${dir}": ${globErr.message}`);
+          }
+        } else {
+          throw err;
+        }
       }
     }
 
@@ -206,11 +239,31 @@ export default async function loadSources({
   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;
+    // Helper function to determine file type from extension
+    const getFileType = (filePath) => {
+      const ext = path.extname(filePath).toLowerCase();
+      const imageExts = [".jpg", ".jpeg", ".png", ".gif", ".bmp", ".webp", ".svg"];
+      const videoExts = [".mp4", ".mov", ".avi", ".mkv", ".webm", ".m4v"];
+
+      if (imageExts.includes(ext)) return "image";
+      if (videoExts.includes(ext)) return "video";
+      return "media";
+    };
+
+    const mediaYaml = mediaFiles.map((file) => ({
+      name: file.name,
+      path: file.path,
+      type: getFileType(file.path),
+    }));
+
+    assetsContent += "```yaml\n";
+    assetsContent += "assets:\n";
+    mediaYaml.forEach((asset) => {
+      assetsContent += `  - name: "${asset.name}"\n`;
+      assetsContent += `    path: "${asset.path}"\n`;
+      assetsContent += `    type: "${asset.type}"\n`;
+    });
+    assetsContent += "```\n";
   }
 
   // Count words and lines in allSources

package/agents/publish-docs.mjs

@@ -1,16 +1,33 @@
 import { basename, join } from "node:path";
 import { publishDocs as publishDocsFn } from "@aigne/publish-docs";
 import chalk from "chalk";
+import fs from "fs-extra";
+
 import { getAccessToken } from "../utils/auth-utils.mjs";
-import { DISCUSS_KIT_STORE_URL } from "../utils/constants.mjs";
+import { DISCUSS_KIT_STORE_URL, TMP_DIR, TMP_DOCS_DIR } from "../utils/constants.mjs";
+import { beforePublishHook, ensureTmpDir } from "../utils/kroki-utils.mjs";
 import { getGithubRepoUrl, loadConfigFromFile, saveValueToConfig } from "../utils/utils.mjs";
 
 const DEFAULT_APP_URL = "https://docsmith.aigne.io";
 
 export default async function publishDocs(
-  { docsDir, appUrl, boardId, projectName, projectDesc, projectLogo },
+  { docsDir: rawDocsDir, appUrl, boardId, projectName, projectDesc, projectLogo },
   options,
 ) {
+  // move work dir to tmp-dir
+  await ensureTmpDir();
+
+  const docsDir = join(".aigne", "doc-smith", TMP_DIR, TMP_DOCS_DIR);
+  await fs.rm(docsDir, { recursive: true, force: true });
+  await fs.mkdir(docsDir, {
+    recursive: true,
+  });
+  await fs.cp(rawDocsDir, docsDir, { recursive: true });
+
+  // ----------------- trigger beforePublishHook -----------------------------
+  await beforePublishHook({ docsDir });
+
+  // ----------------- main publish process flow -----------------------------
   // Check if DOC_DISCUSS_KIT_URL is set in environment variables
   const envAppUrl = process.env.DOC_DISCUSS_KIT_URL;
   const useEnvAppUrl = !!envAppUrl;
@@ -87,6 +104,8 @@ export default async function publishDocs(
     ].filter((lang, index, arr) => arr.indexOf(lang) === index), // Remove duplicates
   };
 
+  let message;
+
   try {
     const { success, boardId: newBoardId } = await publishDocsFn({
       sidebarPath,
@@ -98,7 +117,7 @@ export default async function publishDocs(
       boardName: projectInfo.name,
       boardDesc: projectInfo.description,
       boardCover: projectInfo.icon,
-      mediaFolder: docsDir,
+      mediaFolder: rawDocsDir,
       cacheFilePath: join(".aigne", "doc-smith", "upload-cache.yaml"),
       boardMeta,
     });
@@ -114,18 +133,14 @@ export default async function publishDocs(
       if (boardId !== newBoardId) {
         await saveValueToConfig("boardId", newBoardId);
       }
-      const message = `✅ Documentation Published Successfully!`;
-      return {
-        message,
-      };
+      message = `✅ Documentation Published Successfully!`;
     }
-
-    return {};
   } catch (error) {
-    return {
-      message: `❌ Failed to publish docs: ${error.message}`,
-    };
+    message = `❌ Failed to publish docs: ${error.message}`;
   }
+  // clean up tmp work dir
+  await fs.rm(docsDir, { recursive: true, force: true });
+  return message ? { message } : {};
 }
 
 publishDocs.input_schema = {

package/agents/retranslate.yaml

@@ -58,7 +58,7 @@ input_schema:
       type: array
       items:
         type: string
-      description: Languages to translate to
+      description: "Languages to translate to, available languages are: en, zh, zh-TW, ja, fr, de, es, it, ru, ko, pt, ar"
     feedback:
       type: string
       description: Feedback for translation improvement

package/agents/team-publish-docs.yaml

@@ -13,6 +13,6 @@ skills:
 input_schema:
   type: object
   properties:
-    appUrl: 
+    appUrl:
       type: string
-      description: target website URL where the documentation will be published
+      description: target website URL where the documentation will be published (optional - if not provided, will prompt for interactive input)

package/aigne.yaml

@@ -41,6 +41,7 @@ agents:
   - ./agents/feedback-refiner.yaml
   - ./agents/manage-prefs.mjs
 cli:
+  chat: ./agents/chat.yaml
   agents:
     - ./agents/input-generator.mjs
     - ./agents/docs-generator.yaml

package/docs/_sidebar.md

@@ -0,0 +1,17 @@
+* [Overview](/overview.md)
+* [Getting Started](/getting-started.md)
+* [Core Features](/features.md)
+  * [Generate Documentation](/features-generate-documentation.md)
+  * [Update and Refine](/features-update-and-refine.md)
+  * [Translate Documentation](/features-translate-documentation.md)
+  * [Publish Your Docs](/features-publish-your-docs.md)
+* [CLI Command Reference](/cli-reference.md)
+* [Configuration Guide](/configuration.md)
+  * [LLM Setup](/configuration-llm-setup.md)
+  * [Language Support](/configuration-language-support.md)
+  * [Managing Preferences](/configuration-preferences.md)
+  * [Interactive Setup](/configuration-interactive-setup.md)
+* [Advanced Topics](/advanced.md)
+  * [How It Works](/advanced-how-it-works.md)
+  * [Quality Assurance](/advanced-quality-assurance.md)
+* [Changelog](/changelog.md)

package/docs/advanced-how-it-works.md

@@ -0,0 +1,104 @@
+---
+labels: ["Reference"]
+---
+
+# How It Works
+
+AIGNE DocSmith provides a sophisticated, automated documentation solution by leveraging a multi-agent system built on the AIGNE Framework. Instead of relying on a single, monolithic AI, DocSmith orchestrates a pipeline of specialized AI agents, each an expert in its specific task. This collaborative approach ensures the generation of structured, detailed, and high-quality documentation directly from your source code.
+
+## Architectural Overview
+
+DocSmith is an integral part of the AIGNE ecosystem, a comprehensive platform for AI application development. It seamlessly integrates with other AIGNE components, utilizing the platform's core AI capabilities and infrastructure.
+
+![AIGNE Ecosystem Architecture](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
+
+At its core, DocSmith operates as a pipeline, processing your source code through several distinct stages, each managed by one or more dedicated AI agents.
+
+## The Documentation Generation Pipeline
+
+The entire process, from analyzing your code to publishing the final documents, follows a structured pipeline. This ensures consistency and allows for targeted refinements at any stage.
+
+```d2
+direction: down
+
+"Source Code & Config": {
+  shape: step
+  label: "Input: Source Code & Configuration"
+}
+
+"Structure Planning": {
+  shape: step
+  label: "1. Structure Planning"
+}
+
+"Content Generation": {
+  shape: step
+  label: "2. Content Generation"
+}
+
+"Saving & Output": {
+  shape: step
+  label: "3. Saving & Output"
+}
+
+"Optional Processes": {
+  shape: diamond
+  label: "4. Optional Processes"
+}
+
+"Translation": {
+  shape: step
+  label: "Translation"
+}
+
+"Publishing": {
+  shape: step
+  label: "Publishing"
+}
+
+"Feedback Loop": {
+  shape: callout
+  label: "User Feedback Loop"
+}
+
+"Source Code & Config" -> "Structure Planning"
+"Structure Planning" -> "Content Generation"
+"Content Generation" -> "Saving & Output"
+"Saving & Output" -> "Optional Processes"
+
+"Optional Processes" -> "Translation": "Translate Docs"
+"Optional Processes" -> "Publishing": "Publish Docs"
+
+"Structure Planning" <- "Feedback Loop": "Refine Structure"
+"Content Generation" <- "Feedback Loop": "Regenerate Content"
+
+```
+
+1.  **Input Analysis**: The process begins with agents like `load-sources` and `load-config`, which gather your source code, configuration files (`aigne.yaml`), and any user-defined rules.
+
+2.  **Structure Planning**: The `reflective-structure-planner` agent analyzes the codebase to propose a comprehensive and logical document structure. It considers your specified target audience, rules, and feedback to create an optimal outline.
+
+3.  **Content Generation**: Once the structure is approved, the `content-detail-generator` and `batch-docs-detail-generator` agents take over. They populate each section of the document plan with detailed, high-quality content, ensuring technical accuracy and adherence to the defined style.
+
+4.  **Refinement and Updates**: If you provide feedback using `aigne doc update` or `aigne doc generate --feedback`, the `detail-regenerator` and `feedback-refiner` agents are activated. They intelligently update specific documents or adjust the overall structure based on your input.
+
+5.  **Translation and Publishing**: Finally, optional agents like `translate` and `publish-docs` handle multi-language translation and publishing to Discuss Kit platforms, completing the end-to-end workflow.
+
+## Key AI Agents
+
+DocSmith's power comes from its team of specialized agents. While many agents work behind the scenes, here are some of the key players in the documentation pipeline:
+
+| Agent Role | Primary Function | Governing File(s) |
+|---|---|---|
+| **Structure Planner** | Analyzes source code and rules to generate the overall documentation outline. | `structure-planning.yaml`, `reflective-structure-planner.yaml` |
+| **Content Generator** | Writes detailed content for each individual document section based on the plan. | `content-detail-generator.yaml`, `batch-docs-detail-generator.yaml` |
+| **Translation Agent** | Translates generated documentation into multiple target languages. | `translate.yaml`, `batch-translate.yaml` |
+| **Refinement Agent** | Regenerates or modifies content and structure based on user feedback. | `detail-regenerator.yaml`, `feedback-refiner.yaml` |
+| **Publishing Agent** | Manages the process of publishing documents to Discuss Kit instances. | `publish-docs.mjs`, `team-publish-docs.yaml` |
+| **Configuration Loader** | Reads and interprets the project's configuration from `aigne.yaml`. | `load-config.mjs` |
+
+This modular, agent-based architecture makes DocSmith highly flexible and robust, allowing each step of the process to be optimized independently.
+
+---
+
+Now that you understand the mechanics behind DocSmith, learn about the measures in place to guarantee high-quality output in the [Quality Assurance](./advanced-quality-assurance.md) section.

package/docs/advanced-how-it-works.zh.md

@@ -0,0 +1,104 @@
+---
+labels: ["Reference"]
+---
+
+# 工作原理
+
+AIGNE DocSmith 基于 AIGNE 框架构建的多 Agent 系统，提供了一套精密的自动化文档解决方案。 DocSmith 并非依赖单一、庞大的 AI，而是通过协调一系列专业的 AI Agent 组成的流水线，每个 Agent 都是其特定任务的专家。 这种协作方式确保了能够直接从您的源代码生成结构化、详细且高质量的文档。
+
+## 架构概述
+
+DocSmith 是 AIGNE 生态系统不可或缺的一部分，AIGNE 是一个用于 AI 应用开发的综合平台。 它与其他 AIGNE 组件无缝集成，利用平台的核心 AI 能力和基础设施。
+
+![AIGNE Ecosystem Architecture](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
+
+DocSmith 的核心是一个处理流水线，它将您的源代码经过几个不同阶段的处理，每个阶段都由一个或多个专用的 AI Agent 管理。
+
+## 文档生成流水线
+
+从分析代码到发布最终文档的整个过程，都遵循一个结构化的流水线。 这确保了过程的一致性，并允许在任何阶段进行有针对性的优化。
+
+```d2
+direction: down
+
+"Source Code & Config": {
+  shape: step
+  label: "输入：源代码与配置"
+}
+
+"Structure Planning": {
+  shape: step
+  label: "1. 结构规划"
+}
+
+"Content Generation": {
+  shape: step
+  label: "2. 内容生成"
+}
+
+"Saving & Output": {
+  shape: step
+  label: "3. 保存与输出"
+}
+
+"Optional Processes": {
+  shape: diamond
+  label: "4. 可选流程"
+}
+
+"Translation": {
+  shape: step
+  label: "翻译"
+}
+
+"Publishing": {
+  shape: step
+  label: "发布"
+}
+
+"Feedback Loop": {
+  shape: callout
+  label: "用户反馈循环"
+}
+
+"Source Code & Config" -> "Structure Planning"
+"Structure Planning" -> "Content Generation"
+"Content Generation" -> "Saving & Output"
+"Saving & Output" -> "Optional Processes"
+
+"Optional Processes" -> "Translation": "翻译文档"
+"Optional Processes" -> "Publishing": "发布文档"
+
+"Structure Planning" <- "Feedback Loop": "优化结构"
+"Content Generation" <- "Feedback Loop": "重新生成内容"
+
+```
+
+1.  **输入分析**：该过程始于 `load-sources` 和 `load-config` 等 Agent，它们负责收集您的源代码、配置文件（`aigne.yaml`）以及任何用户定义的规则。
+
+2.  **结构规划**：`reflective-structure-planner` Agent 会分析代码库，以提出一个全面且逻辑清晰的文档结构。它会考虑您指定的目标受众、规则和反馈，以创建最佳大纲。
+
+3.  **内容生成**：一旦结构获得批准，`content-detail-generator` 和 `batch-docs-detail-generator` Agent 就会接手。它们会用详细、高质量的内容填充文档计划的每个部分，确保技术准确性并遵循定义的风格。
+
+4.  **优化与更新**：如果您使用 `aigne doc update` 或 `aigne doc generate --feedback` 提供反馈，`detail-regenerator` 和 `feedback-refiner` Agent 将被激活。它们会根据您的输入智能地更新特定文档或调整整体结构。
+
+5.  **翻译与发布**：最后，像 `translate` 和 `publish-docs` 这样的可选 Agent 会处理多语言翻译和发布到 Discuss Kit 平台的工作，从而完成端到端的工作流。
+
+## 关键 AI Agent
+
+DocSmith 的强大之处在于其专业的 Agent 团队。虽然许多 Agent 在幕后工作，但以下是文档生成流水线中的一些关键角色：
+
+| Agent 角色 | 主要功能 | 相关文件 |
+|---|---|---|
+| **结构规划器** | 分析源代码和规则，以生成整体的文档大纲。 | `structure-planning.yaml`, `reflective-structure-planner.yaml` |
+| **内容生成器** | 根据计划为每个文档部分撰写详细内容。 | `content-detail-generator.yaml`, `batch-docs-detail-generator.yaml` |
+| **Translation Agent** | 将生成的文档翻译成多种目标语言。 | `translate.yaml`, `batch-translate.yaml` |
+| **Refinement Agent** | 根据用户反馈重新生成或修改内容和结构。 | `detail-regenerator.yaml`, `feedback-refiner.yaml` |
+| **Publishing Agent** | 管理将文档发布到 Discuss Kit 实例的过程。 | `publish-docs.mjs`, `team-publish-docs.yaml` |
+| **配置加载器** | 从 `aigne.yaml` 读取并解释项目的配置。 | `load-config.mjs` |
+
+这种模块化的、基于 Agent 的架构使 DocSmith 变得高度灵活和健壮，允许流程的每一步都可以独立优化。
+
+---
+
+现在您已经了解了 DocSmith 背后的工作机制，接下来请在 [质量保证](./advanced-quality-assurance.md) 部分了解为确保高质量输出而采取的措施。

package/docs/advanced-quality-assurance.md

@@ -0,0 +1,64 @@
+---
+labels: ["Reference"]
+---
+
+# Quality Assurance
+
+To ensure your documentation is consistently high-quality, DocSmith includes a powerful automated quality assurance pipeline. These built-in checks run automatically during the generation and update processes to detect and report common issues—from broken links to formatting errors—before they reach your readers.
+
+The process validates multiple aspects of your content to maintain structural integrity and accuracy.
+
+```d2
+direction: right
+
+Input: "Markdown Content"
+
+QA_Pipeline: "DocSmith QA Pipeline" {
+  shape: package
+  
+  Checks: {
+    grid-columns: 2
+    "Structural Integrity": "Incomplete code blocks & inconsistent indentation"
+    "Link & Asset Health": "Dead links & missing local images"
+    "Diagram Validation": "D2 syntax checks"
+    "Markdown Linting": "Table formatting & standard rules"
+  }
+}
+
+Output: "Validated Documentation"
+
+Input -> QA_Pipeline: "Analyzed"
+QA_Pipeline -> Output: "Generated"
+```
+
+### Content and Structural Integrity
+
+DocSmith analyzes the fundamental structure of your markdown files to catch issues that often lead to rendering failures or confusing output.
+
+- **Incomplete Code Blocks**: The validator ensures that every code block opened with ` ``` ` is properly closed. Unclosed blocks can cause large portions of a document to render incorrectly.
+- **Inconsistent Indentation**: Code blocks with inconsistent indentation are flagged. This is particularly important for code samples where indentation is syntactically significant and for preventing unexpected rendering issues.
+- **Content Completeness**: The system checks if the content appears to be truncated by verifying that it ends with appropriate punctuation (e.g., `.`, `)`, `|`). This helps catch incomplete generation results.
+
+### Link and Asset Validation
+
+Broken links and missing images can degrade the user experience. DocSmith validates these resources automatically to ensure they are always available to the reader.
+
+- **Dead Link Checking**: All internal links are cross-referenced against the paths defined in your project's structure plan. Any link pointing to a non-existent page is reported as a dead link.
+- **Local Image Verification**: For local images (i.e., those not hosted on an external server), the system checks that the referenced image file exists at the specified relative or absolute path.
+
+### Diagram Validation
+
+To ensure that all diagrams render correctly, DocSmith specifically validates the syntax of D2 code blocks. Before processing, the D2 content is checked for syntactical correctness. If an error is found, it is flagged to prevent a broken diagram from being published.
+
+### Markdown Formatting and Linting
+
+Beyond major structural issues, DocSmith lints the markdown for formatting consistency and correctness, leveraging established standards to enforce a clean and readable style. Key checks include:
+
+| Check Category | Description |
+|---|---|
+| **Table Formatting** | Verifies that the number of columns in a table's header, separator line, and data rows are consistent. Mismatched column counts are a common cause of broken tables. |
+| **Heading Issues** | Detects duplicate headings within the same document or headings that use improper indentation, which can break the document outline. |
+| **Reference Validation** | Checks for undefined references, such as using a link reference `[text][ref]` without defining `[ref]: url` elsewhere. |
+| **Code Block Style** | Ensures consistent usage of code block markers for better readability and parsing. |
+
+This automated quality assurance layer is a core part of DocSmith's architecture, designed to minimize manual review and ensure that your documentation is always accurate, professional, and reliable. To learn more about the overall generation process, see [How It Works](./advanced-how-it-works.md).

package/docs/advanced-quality-assurance.zh.md

@@ -0,0 +1,64 @@
+---
+labels: ["Reference"]
+---
+
+# 质量保证
+
+为确保您的文档始终保持高质量，DocSmith 内置了一个强大的自动化质量保证流程。这些内置检查在生成和更新过程中自动运行，以检测并报告常见问题（从链接失效到格式错误），从而在问题影响到读者之前予以解决。
+
+该流程会验证您内容的多个方面，以保持结构的完整性和准确性。
+
+```d2
+direction: right
+
+Input: "Markdown 内容"
+
+QA_Pipeline: "DocSmith QA 流程" {
+  shape: package
+  
+  Checks: {
+    grid-columns: 2
+    "结构完整性": "代码块不完整和缩进不一致"
+    "链接和资源健康状况": "失效链接和本地图片缺失"
+    "图表验证": "D2 语法检查"
+    "Markdown 语法检查": "表格格式和标准规则"
+  }
+}
+
+Output: "经验证的文档"
+
+Input -> QA_Pipeline: "分析"
+QA_Pipeline -> Output: "生成"
+```
+
+### 内容和结构完整性
+
+DocSmith 会分析 Markdown 文件的基本结构，以捕获那些经常导致渲染失败或输出混乱的问题。
+
+- **代码块不完整**：验证器会确保每个以 ` ``` ` 开始的代码块都已正确关闭。未关闭的代码块可能导致文档的大部分内容无法正确渲染。
+- **缩进不一致**：系统会标记出缩进不一致的代码块。这对于缩进具有语法意义的代码示例以及防止意外的渲染问题尤为重要。
+- **内容完整性**：系统通过验证内容是否以适当的标点符号（例如 `.`、`)`、`|`）结尾，来检查内容是否被截断。这有助于捕获不完整的生成结果。
+
+### 链接和资源验证
+
+失效链接和缺失图片会降低用户体验。DocSmith 会自动验证这些资源，以确保读者始终可以访问它们。
+
+- **失效链接检查**：所有内部链接都会与您项目结构计划中定义的路径进行交叉引用。任何指向不存在页面的链接都将被报告为失效链接。
+- **本地图片验证**：对于本地图片（即未托管在外部服务器上的图片），系统会检查引用的图片文件是否存在于指定的相对或绝对路径中。
+
+### 图表验证
+
+为确保所有图表都能正确渲染，DocSmith 会专门验证 D2 代码块的语法。在处理之前，系统会检查 D2 内容的语法正确性。如果发现错误，系统会进行标记，以防止发布损坏的图表。
+
+### Markdown 格式化与语法检查
+
+除了主要的结构性问题，DocSmith 还会对 Markdown 进行语法检查，以确保格式的一致性和正确性，并利用既定标准来强制执行清晰易读的风格。关键检查包括：
+
+| 检查类别 | 描述 |
+|---|---|
+| **表格格式化** | 验证表格的表头、分隔线和数据行中的列数是否一致。列数不匹配是导致表格损坏的常见原因。 |
+| **标题问题** | 检测同一文档中的重复标题或使用不当缩进的标题，这些问题可能会破坏文档大纲。 |
+| **引用验证** | 检查未定义的引用，例如使用了链接引用 `[text][ref]`，但未在其他地方定义 `[ref]: url`。 |
+| **代码块样式** | 确保一致地使用代码块标记，以提高可读性和解析效率。 |
+
+这个自动化的质量保证层是 DocSmith 架构的核心部分，旨在最大限度地减少人工审查，并确保您的文档始终准确、专业且可靠。要了解有关整体生成流程的更多信息，请参阅[工作原理](./advanced-how-it-works.md)。

package/docs/advanced.md

@@ -0,0 +1,28 @@
+---
+labels: ["Reference"]
+---
+
+# Advanced Topics
+
+For those who wish to look under the hood, this section provides a deeper dive into the architecture of AIGNE DocSmith. Here, you'll learn how the tool functions, its place within the AIGNE ecosystem, and the internal mechanisms it uses to generate high-quality documentation.
+
+While a deep understanding of these topics isn't necessary for general use, it can be valuable for customizing behavior, troubleshooting issues, or contributing to the project.
+
+## The AIGNE Ecosystem
+
+AIGNE DocSmith is not a standalone tool; it is a key component of the [AIGNE Framework](https://www.aigne.io/en/framework), a comprehensive platform for AI application development. This integration allows DocSmith to leverage the platform's advanced AI capabilities and robust infrastructure. The following diagram illustrates how DocSmith fits into the broader ecosystem.
+
+![AIGNE Ecosystem Architecture](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
+
+To better understand the internal processes and quality controls, explore the following sections.
+
+<x-cards data-columns="2">
+  <x-card data-title="How It Works" data-href="/advanced/how-it-works" data-icon="lucide:cpu">
+    An architectural overview of DocSmith, explaining the role of AI agents in the documentation generation pipeline.
+  </x-card>
+  <x-card data-title="Quality Assurance" data-href="/advanced/quality-assurance" data-icon="lucide:shield-check">
+    Understand the built-in checks DocSmith performs to ensure high-quality, well-formatted, and error-free documentation.
+  </x-card>
+</x-cards>
+
+By exploring these topics, you can gain a more complete understanding of DocSmith's capabilities. For a detailed breakdown of all available commands and their options, proceed to the [CLI Command Reference](./cli-reference.md).

package/docs/advanced.zh.md

@@ -0,0 +1,28 @@
+---
+labels: ["Reference"]
+---
+
+# 高级主题
+
+对于希望深入了解其内部机制的用户，本节将深入解析 AIGNE DocSmith 的架构。在这里，你将了解到该工具的运作方式、其在 AIGNE 生态系统中的定位，以及它用于生成高质量文档的内部机制。
+
+虽然深入理解这些主题对于一般使用并非必要，但它对于自定义行为、排查问题或为项目做出贡献非常有价值。
+
+## AIGNE 生态系统
+
+AIGNE DocSmith 并非一个独立的工具，而是 [AIGNE 框架](https://www.aigne.io/en/framework) 的关键组件，该框架是一个用于 AI 应用开发的综合平台。这种集成使 DocSmith 能够利用该平台的先进 AI 功能和强大的基础设施。下图展示了 DocSmith 如何融入更广泛的生态系统。
+
+![AIGNE 生态系统架构](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
+
+要更好地了解其内部流程和质量控制，请浏览以下章节。
+
+<x-cards data-columns="2">
+  <x-card data-title="工作原理" data-href="/advanced/how-it-works" data-icon="lucide:cpu">
+    DocSmith 的架构概览，解释了 AI Agent 在文档生成流程中的作用。
+  </x-card>
+  <x-card data-title="质量保证" data-href="/advanced/quality-assurance" data-icon="lucide:shield-check">
+    了解 DocSmith 为确保文档高质量、格式良好且无错误而执行的内置检查。
+  </x-card>
+</x-cards>
+
+通过探索这些主题，你可以更全面地了解 DocSmith 的功能。要获取所有可用命令及其选项的详细说明，请参阅 [CLI 命令参考](./cli-reference.md)。