@aigne/doc-smith 0.8.10 → 0.8.11-beta.1

package/biome.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.1.4/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.2.4/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",
@@ -57,5 +57,17 @@
         "organizeImports": "on"
       }
     }
-  }
+  },
+  "overrides": [
+    {
+      "includes": ["**/fixtures/**"],
+
+      "linter": {
+        "enabled": false
+      },
+      "formatter": {
+        "enabled": false
+      }
+    }
+  ]
 }

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

@@ -0,0 +1,101 @@
+# 仕組み
+
+AIGNE DocSmithは、AIGNEフレームワーク内に構築されたマルチAgentシステムで動作します。単一のモノリシックなプロセスではなく、専門的なAI Agentのパイプラインを編成し、各Agentが特定のタスクを担当します。このアプローチにより、ソースコードを完全なドキュメンテーションに変換するための、構造化されたモジュラーなプロセスが可能になります。
+
+このツールは、AIアプリケーションの開発とデプロイのためのプラットフォームを提供する、より大きなAIGNEエコシステムの不可欠な部分です。
+
+![AIGNEエコシステムのアーキテクチャ](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
+
+## ドキュメンテーション生成パイプライン
+
+DocSmithの中核は、ソースコードをいくつかの異なるステージを通じて処理するパイプラインです。各ステージは、1つ以上の専用Agentによって管理されます。通常 `aigne doc generate` コマンドによって開始される主要なワークフローは、次のように視覚化できます。
+
+```d2
+direction: down
+
+Input: {
+  label: "Source Code & Config"
+  shape: rectangle
+}
+
+Pipeline: {
+  label: "Core Generation Pipeline"
+  shape: rectangle
+  grid-columns: 1
+  grid-gap: 40
+
+  Structure-Planning: {
+    label: "1. Structure Planning"
+    shape: rectangle
+  }
+
+  Content-Generation: {
+    label: "2. Content Generation"
+    shape: rectangle
+  }
+
+  Saving: {
+    label: "3. Save Documents"
+    shape: rectangle
+  }
+}
+
+User-Feedback: {
+  label: "User Feedback Loop\n(via --feedback flag)"
+  shape: rectangle
+}
+
+Optional-Steps: {
+  label: "Optional Post-Generation Steps"
+  shape: rectangle
+  grid-columns: 2
+  grid-gap: 40
+  
+  Translation: {
+    label: "Translate\n(aigne doc translate)"
+    shape: rectangle
+  }
+
+  Publishing: {
+    label: "Publish\n(aigne doc publish)"
+    shape: rectangle
+  }
+}
+
+Input -> Pipeline.Structure-Planning
+Pipeline.Structure-Planning -> Pipeline.Content-Generation
+Pipeline.Content-Generation -> Pipeline.Saving
+Pipeline.Saving -> Optional-Steps
+
+User-Feedback -> Pipeline.Structure-Planning: "Refine Structure"
+User-Feedback -> Pipeline.Content-Generation: "Regenerate Content"
+```
+
+1.  **入力分析**: Agentがソースコードとプロジェクト設定（`aigne.yaml`）を読み込むと、プロセスが開始されます。
+
+2.  **構造計画**: Agentがコードベースを分析し、論理的なドキュメント構造を提案します。プロジェクトの構成と指定されたルールに基づいてアウトラインを作成します。
+
+3.  **コンテンツ生成**: 構造が確定すると、コンテンツ生成Agentがドキュメント計画の各セクションに詳細なテキスト、コード例、説明を埋め込みます。
+
+4.  **改良と更新**: `aigne doc update` または `aigne doc generate --feedback` を介して入力を提供すると、特定のAgentがアクティブになり、個々のドキュメントを更新したり、全体的な構造を調整したりします。
+
+5.  **翻訳と公開**: 主要なコンテンツが生成された後、オプションのAgentが多言語翻訳や最終的なドキュメンテーションをウェブプラットフォームに公開するなどのタスクを処理します。
+
+## 主要なAI Agent
+
+DocSmithの機能は、プロジェクトの設定で定義されたAgentのコレクションによって提供されます。各Agentには特定の役割があります。以下の表は、主要なAgentとその機能の一部をリストアップしたものです。
+
+| 機能的役割               | 主要なAgentファイル                                  | 説明                                                                         |
+| ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| **構造計画**             | `generate/generate-structure.yaml`                   | ソースコードを分析し、初期のドキュメントアウトラインを提案します。                         |
+| **構造の改良**           | `generate/refine-document-structure.yaml`            | ユーザーのフィードバックに基づいてドキュメント構造を修正します。                             |
+| **コンテンツ生成**         | `update/batch-generate-document.yaml`, `generate-document.yaml` | 各セクションの詳細なコンテンツでドキュメント構造を埋めます。                                 |
+| **翻訳**                 | `translate/translate-document.yaml`, `translate-multilingual.yaml` | 生成されたドキュメンテーションを複数のターゲット言語に翻訳します。                           |
+| **公開**                 | `publish/publish-docs.mjs`                           | Discuss Kitインスタンスへのドキュメント公開プロセスを管理します。                           |
+| **データI/O**              | `utils/load-sources.mjs`, `utils/save-docs.mjs`      | ソースファイルの読み取りと最終的なマークダウンドキュメントのディスクへの書き込みを担当します。 |
+
+このAgentベースのアーキテクチャにより、ドキュメンテーションプロセスの各ステップを専門ツールで処理でき、構造化され保守可能なワークフローが保証されます。
+
+---
+
+DocSmithが出力の正確性とフォーマットを保証するために講じる対策を理解するには、[品質保証](./advanced-quality-assurance.md)のセクションに進んでください。

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

@@ -0,0 +1,101 @@
+# 運作方式
+
+AIGNE DocSmith 在 AIGNE 框架内建構的多 Agent 系統上運作。它不是單一的整體流程，而是協調一個由專業 AI Agent 組成的管線，其中每個 Agent 負責一項特定任務。這種方法實現了一個結構化和模組化的流程，將原始碼轉換為完整的文件。
+
+該工具是更大的 AIGNE 生態系統中不可或缺的一部分，該生態系統為開發和部署 AI 應用程式提供了一個平台。
+
+![AIGNE 生態系統架構](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
+
+## 文件生成管線
+
+DocSmith 的核心是一個管線，它透過幾個不同階段處理您的原始碼。每個階段都由一個或多個專門的 Agent 管理。主要工作流程通常由 `aigne doc generate` 命令啟動，可視覺化如下：
+
+```d2
+direction: down
+
+Input: {
+  label: "原始碼與設定檔"
+  shape: rectangle
+}
+
+Pipeline: {
+  label: "核心生成管線"
+  shape: rectangle
+  grid-columns: 1
+  grid-gap: 40
+
+  Structure-Planning: {
+    label: "1. 結構規劃"
+    shape: rectangle
+  }
+
+  Content-Generation: {
+    label: "2. 內容生成"
+    shape: rectangle
+  }
+
+  Saving: {
+    label: "3. 儲存文件"
+    shape: rectangle
+  }
+}
+
+User-Feedback: {
+  label: "使用者回饋循環\n(透過 --feedback 旗標)"
+  shape: rectangle
+}
+
+Optional-Steps: {
+  label: "可選的生成後步驟"
+  shape: rectangle
+  grid-columns: 2
+  grid-gap: 40
+  
+  Translation: {
+    label: "翻譯\n(aigne doc translate)"
+    shape: rectangle
+  }
+
+  Publishing: {
+    label: "發布\n(aigne doc publish)"
+    shape: rectangle
+  }
+}
+
+Input -> Pipeline.Structure-Planning
+Pipeline.Structure-Planning -> Pipeline.Content-Generation
+Pipeline.Content-Generation -> Pipeline.Saving
+Pipeline.Saving -> Optional-Steps
+
+User-Feedback -> Pipeline.Structure-Planning: "優化結構"
+User-Feedback -> Pipeline.Content-Generation: "重新生成內容"
+```
+
+1.  **輸入分析**：當 Agent 載入您的原始碼和專案設定（`aigne.yaml`）時，流程便開始了。
+
+2.  **結構規劃**：一個 Agent 會分析程式碼庫，以提出一個合乎邏輯的文件結構。它會根據專案的組成和任何指定的規則來建立大綱。
+
+3.  **內容生成**：結構就位後，內容生成 Agent 會為文件計畫的每個部分填入詳細的文字、程式碼範例和解釋。
+
+4.  **優化與更新**：當您透過 `aigne doc update` 或 `aigne doc generate --feedback` 提供輸入時，會啟動特定的 Agent 來更新個別文件或調整整體結構。
+
+5.  **翻譯與發布**：主要內容生成後，可選的 Agent 會處理多語言翻譯和將最終文件發布到網路平台等任務。
+
+## 關鍵 AI Agent
+
+DocSmith 的功能是由專案設定中定義的一系列 Agent 所提供。每個 Agent 都有特定的角色。下表列出了一些關鍵 Agent 及其功能。
+
+| 功能角色               | 關鍵 Agent 檔案                                      | 描述                                                                         |
+| ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| **結構規劃**           | `generate/generate-structure.yaml`                   | 分析原始碼以提出初始的文件大綱。                                             |
+| **結構優化**         | `generate/refine-document-structure.yaml`            | 根據使用者回饋修改文件結構。                                                 |
+| **內容生成**           | `update/batch-generate-document.yaml`, `generate-document.yaml` | 為文件結構的每個部分填入詳細內容。                                           |
+| **翻譯**               | `translate/translate-document.yaml`, `translate-multilingual.yaml` | 將生成的文件翻譯成多個目標語言。                                             |
+| **發布**               | `publish/publish-docs.mjs`                           | 管理將文件發布到 Discuss Kit 實例的過程。                                    |
+| **資料 I/O**           | `utils/load-sources.mjs`, `utils/save-docs.mjs`      | 負責讀取來源檔案並將最終的 Markdown 文件寫入磁碟。                           |
+
+這種基於 Agent 的架構使得文件流程的每一步都能由專門的工具處理，從而確保了一個結構化且可維護的工作流程。
+
+---
+
+要了解 DocSmith 為確保輸出準確性和格式所採取的措施，請前往 [品質保證](./advanced-quality-assurance.md) 部分。

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

@@ -1,20 +1,20 @@
 # 工作原理
 
-AIGNE DocSmith 在 AIGNE 框架内构建的多 Agent 系统上运行。它并非一个单一的整体进程，而是协调一个由专业化 AI Agent 组成的流水线，其中每个 Agent 负责一项特定任务。这种方法实现了一个结构化和模块化的流程，可将源代码转换为完整的文档。
+AIGNE DocSmith 在一个构建于 AIGNE 框架内的多 Agent 系统上运行。它并非采用单一的整体流程，而是协调一个由专业 AI Agent 组成的流水线，其中每个 Agent 负责一项特定任务。这种方法使得将源代码转换为完整文档的过程变得结构化且模块化。
 
-该工具是更庞大的 AIGNE 生态系统的一个组成部分，该生态系统为开发和部署 AI 应用程序提供了一个平台。
+该工具是更宏大的 AIGNE 生态系统的一个组成部分，该生态系统为开发和部署 AI 应用提供了一个平台。
 
 ![AIGNE 生态系统架构](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
 
 ## 文档生成流水线
 
-DocSmith 的核心是一个通过几个不同阶段处理源代码的流水线。每个阶段都由一个或多个专用 Agent 管理。主要工作流程通常由 `aigne doc generate` 命令启动，其可视化如下：
+DocSmith 的核心是一条通过多个不同阶段处理源代码的流水线。每个阶段都由一个或多个专用 Agent 进行管理。主要工作流程通常由 `aigne doc generate` 命令启动，其过程可直观地表示如下：
 
 ```d2
 direction: down
 
 Input: {
-  label: "源代码和配置"
+  label: "源代码与配置"
   shape: rectangle
 }
 
@@ -71,31 +71,31 @@ User-Feedback -> Pipeline.Structure-Planning: "优化结构"
 User-Feedback -> Pipeline.Content-Generation: "重新生成内容"
 ```
 
-1.  **输入分析**：当 Agent 加载你的源代码和项目配置（`aigne.yaml`）时，该过程开始。
+1.  **输入分析**：当 Agent 加载您的源代码和项目配置（`aigne.yaml`）时，该过程开始。
 
-2.  **结构规划**：一个 Agent 会分析代码库，以提出一个逻辑性的文档结构。它会根据项目的构成和任何指定的规则创建一个大纲。
+2.  **结构规划**：一个 Agent 会分析代码库，以提出一个逻辑化的文档结构。它会根据项目的构成和任何指定的规则创建一个大纲。
 
-3.  **内容生成**：结构就位后，内容生成 Agent 会为文档计划的每个部分填充详细的文本、代码示例和解释。
+3.  **内容生成**：结构确定后，内容生成 Agent 会为文档计划的每个部分填充详细的文本、代码示例和解释。
 
-4.  **优化和更新**：当你通过 `aigne doc update` 或 `aigne doc generate --feedback` 提供输入时，特定的 Agent 会被激活，以更新单个文档或调整整体结构。
+4.  **优化与更新**：当您通过 `aigne doc update` 或 `aigne doc generate --feedback` 提供输入时，特定的 Agent 会被激活以更新单个文档或调整整体结构。
 
-5.  **翻译和发布**：主要内容生成后，可选的 Agent 会处理多语言翻译和将最终文档发布到网络平台等任务。
+5.  **翻译与发布**：在主要内容生成后，可选的 Agent 会处理多语言翻译和将最终文档发布到网络平台等任务。
 
 ## 关键 AI Agent
 
-DocSmith 的功能由项目配置中定义的一组 Agent 提供。每个 Agent 都有特定的角色。下表列出了一些关键 Agent 及其功能。
+DocSmith 的功能由项目配置中定义的一系列 Agent 提供。每个 Agent 都有其特定的角色。下表列出了一些关键 Agent 及其功能。
 
-| 功能角色 | 关键 Agent 文件 | 描述 |
-| --- | --- | --- |
-| **结构规划** | `generate/generate-structure.yaml` | 分析源代码以提出初始文档大纲。 |
-| **结构优化** | `generate/refine-document-structure.yaml` | 根据用户反馈修改文档结构。 |
-| **内容生成** | `update/batch-generate-document.yaml`, `generate-document.yaml` | 为每个部分填充详细内容，以充实文档结构。 |
-| **翻译** | `translate/translate-document.yaml`, `translate-multilingual.yaml` | 将生成的文档翻译成多种目标语言。 |
-| **发布** | `publish/publish-docs.mjs` | 管理将文档发布到 Discuss Kit 实例的过程。 |
-| **数据 I/O** | `utils/load-sources.mjs`, `utils/save-docs.mjs` | 负责读取源文件并将最终的 markdown 文档写入磁盘。 |
+| 功能角色         | 关键 Agent 文件                                      | 描述                                                                          |
+| ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| **结构规划**   | `generate/generate-structure.yaml`                   | 分析源代码以提出初始的文档大纲。                        |
+| **结构优化** | `generate/refine-document-structure.yaml`            | 根据用户反馈修改文档结构。                              |
+| **内容生成**   | `update/batch-generate-document.yaml`, `generate-document.yaml` | 为文档结构的每个部分填充详细内容。             |
+| **翻译**          | `translate/translate-document.yaml`, `translate-multilingual.yaml` | 将生成的文档翻译成多种目标语言。                   |
+| **发布**           | `publish/publish-docs.mjs`                           | 管理将文档发布到 Discuss Kit 实例的过程。                |
+| **数据 I/O**             | `utils/load-sources.mjs`, `utils/save-docs.mjs`      | 负责读取源文件并将最终的 Markdown 文档写入磁盘。 |
 
-这种基于 Agent 的架构使得文档流程的每一步都由一个专门的工具来处理，从而确保了工作流程的结构化和可维护性。
+这种基于 Agent 的架构使得文档流程的每一步都能由一个专门的工具来处理，从而确保了工作流程的结构化和可维护性。
 
 ---
 
-要了解 DocSmith 为确保输出的准确性和格式而采取的措施，请继续阅读[质量保证](./advanced-quality-assurance.md)部分。
+要了解 DocSmith 为确保输出的准确性和格式所采取的措施，请继续阅读 [质量保证](./advanced-quality-assurance.md) 部分。

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

@@ -0,0 +1,96 @@
+# 品質保証
+
+生成されるすべてのドキュメントが機能的、明確、かつプロフェッショナルであることを保証するため、DocSmithには自動品質保証プロセスが組み込まれています。このプロセスは、公開前にMarkdownコンテンツに対して一連のチェックを実行し、リンク切れから不正な形式の図まで、一般的な問題を検出して報告します。
+
+この自動化されたパイプラインは、コンテンツの構造、リンク、メディア、構文を検証し、一貫した品質基準を維持します。
+
+```d2
+direction: down
+
+Input-Markdown-Content: {
+  label: "入力: Markdownコンテンツ"
+  shape: rectangle
+}
+
+QA-Pipeline: {
+  label: "QAパイプライン"
+  shape: rectangle
+  grid-columns: 1
+  grid-gap: 50
+
+  Structural-Checks: {
+    label: "構造チェック"
+    shape: rectangle
+    grid-columns: 2
+    Completeness: "コンテンツが切り捨てられていないことを保証"
+    Code-Blocks: "ブロックの構文とインデントを検証"
+  }
+
+  Content-Validation: {
+    label: "コンテンツ検証"
+    shape: rectangle
+    grid-columns: 2
+    Link-Integrity: "内部リンクを検証"
+    Image-Paths: "ローカル画像の存在を確認"
+    Table-Formatting: "列数が一致するか確認"
+  }
+
+  Syntax-Validation: {
+    label: "構文検証"
+    shape: rectangle
+    grid-columns: 2
+    D2-Diagrams: "D2構文を検証"
+    Markdown-Linting: "スタイルルールを強制"
+  }
+}
+
+Output-Validated-Content-or-Error-Report: {
+  label: "出力: 検証済みコンテンツまたはエラーレポート"
+  shape: rectangle
+}
+
+Input-Markdown-Content -> QA-Pipeline
+QA-Pipeline -> Output-Validated-Content-or-Error-Report
+```
+
+### 主要な検証領域
+
+DocSmithの品質保証プロセスは、ドキュメントの完全性を保証するため、いくつかの主要な領域をカバーしています。
+
+#### コンテンツの構造と完全性
+
+DocSmithは、コンテンツの構造的完全性を保証するために、いくつかのチェックを実行します：
+
+- **不完全なコードブロック**: ` ``` ` で開始されて閉じられていないコードブロックを検出します。
+- **改行の欠落**: 1行に表示されるコンテンツを特定します。これは改行が欠落している可能性を示します。
+- **コンテンツの末尾**: コンテンツが適切な句読点（例：`.`, `)`, `|`, `>`）で終わっていることを確認し、出力が切り捨てられるのを防ぎます。
+- **コードブロックのインデント**: コードブロックのインデントの不整合を分析します。コード行のインデントが開始の ` ``` ` マーカーよりも少ない場合、レンダリングの問題を引き起こす可能性があります。このチェックは、正しいコードの表示を維持するのに役立ちます。
+
+#### リンクとメディアの整合性
+
+- **リンクの整合性**: ドキュメント内のすべての相対リンクは、ドキュメント構造計画と照らし合わせて検証され、リンク切れを防ぎます。これにより、すべての内部ナビゲーションが期待どおりに機能することが保証されます。チェッカーは外部リンク（`http://` または `https://` で始まる）および `mailto:` リンクを無視します。
+
+- **画像の検証**: 画像の破損を避けるため、チェッカーはドキュメントで参照されているローカル画像ファイルがファイルシステムに存在することを確認します。相対パスと絶対パスの両方を解決して、ファイルの存在を確認します。外部リンクのURLやデータURLはチェックされません。
+
+#### 図の構文検証
+
+- **D2図**: DocSmithは、コードをSVG画像にコンパイルしようとすることでD2図の構文を検証します。このプロセスにより、構文エラーが図の破損につながる前に捕捉されます。
+
+#### フォーマットとスタイルの強制
+
+- **テーブルのフォーマット**: ヘッダー、区切り線、データ行の間で列数が一致しないテーブルを検査します。このチェックにより、一般的なテーブルのレンダリング失敗を防ぎます。
+
+- **Markdownリンティング**: 組み込みのリンターが一貫したMarkdown構造を強制します。主要なルールには以下が含まれます：
+
+| ルールID | 説明 |
+|---|---|
+| `no-duplicate-headings` | 同じセクション内で同じ内容の複数の見出しを防ぎます。 |
+| `no-undefined-references` | すべてのリンクと画像の参照が定義されていることを保証します。 |
+| `no-unused-definitions` | 使用されていないリンクや画像の定義にフラグを立てます。 |
+| `no-heading-content-indent` | 見出しの内容の前にインデントを許可しません。 |
+| `no-multiple-toplevel-headings` | ドキュメントごとにトップレベルの見出し（H1）を1つだけ許可します。 |
+| `code-block-style` | コードブロックに一貫したスタイル（例：バッククォートの使用）を強制します。 |
+
+これらのチェックを自動化することで、DocSmithはドキュメントの一貫した基準を維持し、最終的な出力が正確でナビゲート可能であることを保証します。
+
+全体的なアーキテクチャについて詳しく知るには、[仕組み](./advanced-how-it-works.md)のセクションを参照してください。

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

@@ -0,0 +1,96 @@
+# 品質保證
+
+為確保所有生成的文檔功能正常、清晰且專業，DocSmith 整合了一個自動化的品質保證流程。此流程會在發布前對 Markdown 內容執行一系列檢查，以偵測並報告從斷開的連結到格式錯誤的圖表等常見問題。
+
+這個自動化管道會驗證內容結構、連結、媒體和語法，以維持一致的品質標準。
+
+```d2
+direction: down
+
+Input-Markdown-Content: {
+  label: "輸入：Markdown 內容"
+  shape: rectangle
+}
+
+QA-Pipeline: {
+  label: "QA 管道"
+  shape: rectangle
+  grid-columns: 1
+  grid-gap: 50
+
+  Structural-Checks: {
+    label: "結構檢查"
+    shape: rectangle
+    grid-columns: 2
+    Completeness: "確保內容未被截斷"
+    Code-Blocks: "驗證區塊語法與縮排"
+  }
+
+  Content-Validation: {
+    label: "內容驗證"
+    shape: rectangle
+    grid-columns: 2
+    Link-Integrity: "驗證內部連結"
+    Image-Paths: "檢查本地圖片是否存在"
+    Table-Formatting: "匹配欄位數量"
+  }
+
+  Syntax-Validation: {
+    label: "語法驗證"
+    shape: rectangle
+    grid-columns: 2
+    D2-Diagrams: "驗證 D2 語法"
+    Markdown-Linting: "強制執行樣式規則"
+  }
+}
+
+Output-Validated-Content-or-Error-Report: {
+  label: "輸出：已驗證的內容或錯誤報告"
+  shape: rectangle
+}
+
+Input-Markdown-Content -> QA-Pipeline
+QA-Pipeline -> Output-Validated-Content-or-Error-Report
+```
+
+### 核心驗證領域
+
+DocSmith 的品質保證流程涵蓋了幾個關鍵領域，以確保文檔的完整性。
+
+#### 內容結構與完整性
+
+DocSmith 執行多項檢查，以確保內容的結構完整性：
+
+- **不完整的程式碼區塊**：偵測以 ` ``` ` 開啟但未關閉的程式碼區塊。
+- **缺少換行符**：識別出現在單一行上的內容，這可能表示缺少換行符。
+- **內容結尾**：驗證內容是否以適當的標點符號（例如 `.`、`)`、`|`、`>`）結尾，以防止輸出被截斷。
+- **程式碼區塊縮排**：分析程式碼區塊中不一致的縮排。如果某一行程式碼的縮排少於開頭的 ` ``` ` 標記，可能會導致渲染問題。此檢查有助於維持正確的程式碼呈現。
+
+#### 連結與媒體完整性
+
+- **連結完整性**：文檔中的所有相對連結都會根據文檔結構計畫進行驗證，以防止出現無效連結。這確保了所有內部導覽都能如預期般運作。檢查器會忽略外部連結（以 `http://` 或 `https://` 開頭）和 `mailto:` 連結。
+
+- **圖片驗證**：為避免圖片損壞，檢查器會驗證文檔中引用的任何本地圖片檔案是否存在於檔案系統中。它會解析相對和絕對路徑，以確認檔案存在。外部圖片 URL 和資料 URL 不會被檢查。
+
+#### 圖表語法驗證
+
+- **D2 圖表**：DocSmith 透過嘗試將程式碼編譯成 SVG 圖片來驗證 D2 圖表語法。此過程能在語法錯誤導致圖形損壞前捕捉到它們。
+
+#### 格式化與樣式強制執行
+
+- **表格格式化**：檢查表格的標頭、分隔線和資料行之間的欄位數量是否不匹配。此檢查可防止常見的表格渲染失敗。
+
+- **Markdown 語法檢查**：內建的 linter 強制執行一致的 Markdown 結構。主要規則包括：
+
+| Rule ID | Description |
+|---|---|
+| `no-duplicate-headings` | 防止在同一部分中出現內容相同的多個標題。 |
+| `no-undefined-references` | 確保所有連結和圖片引用都已定義。 |
+| `no-unused-definitions` | 標記未使用的連結或圖片定義。 |
+| `no-heading-content-indent` | 不允許在標題內容前縮排。 |
+| `no-multiple-toplevel-headings` | 每個文件只允許一個頂層標題 (H1)。 |
+| `code-block-style` | 強制執行一致的程式碼區塊樣式（例如，使用反引號）。 |
+
+透過自動化這些檢查，DocSmith 維護了文檔的一致標準，確保最終輸出準確且易於導覽。
+
+若要了解更多關於整體架構的資訊，請參閱 [運作方式](./advanced-how-it-works.md) 部分。

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

@@ -1,8 +1,8 @@
 # 质量保证
 
-为确保所有生成的文档功能正常、清晰且专业，DocSmith 集成了一个自动化的质量保证流程。该流程会对 Markdown 内容执行一系列检查，以便在发布前检测并报告从损坏的链接到格式错误的图表等常见问题。
+为确保所有生成的文档功能正常、清晰且专业，DocSmith 引入了自动化的质量保证流程。该流程在发布前对 Markdown 内容执行一系列检查，以检测和报告常见问题，从损坏的链接到格式错误的图表。
 
-此自动化管道会验证内容结构、链接、媒体和语法，以保持一致的质量标准。
+这个自动化管道会验证内容结构、链接、媒体和语法，以保持一致的质量标准。
 
 ```d2
 direction: down
@@ -22,7 +22,7 @@ QA-Pipeline: {
     label: "结构检查"
     shape: rectangle
     grid-columns: 2
-    Completeness: "确保内容未被截断"
+    Completeness: "确保内容不被截断"
     Code-Blocks: "验证块语法和缩进"
   }
 
@@ -45,7 +45,7 @@ QA-Pipeline: {
 }
 
 Output-Validated-Content-or-Error-Report: {
-  label: "输出：验证通过的内容或错误报告"
+  label: "输出：已验证内容或错误报告"
   shape: rectangle
 }
 
@@ -59,38 +59,38 @@ DocSmith 的质量保证流程涵盖了几个关键领域，以确保文档的
 
 #### 内容结构与完整性
 
-DocSmith 会执行多项检查，以确保内容的结构完整性：
+DocSmith 执行多项检查以确保内容的结构完整性：
 
-- **代码块不完整**：检测以 ` ``` ` 开头但未关闭的代码块。
+- **不完整的代码块**：检测以 ` ``` ` 开始但未关闭的代码块。
 - **缺少换行符**：识别出现在单行上的内容，这可能表示缺少换行符。
 - **内容结尾**：验证内容是否以适当的标点符号（例如 `.`、`)`、`|`、`>`）结尾，以防止输出被截断。
-- **代码块缩进**：分析代码块中不一致的缩进。如果某行代码的缩进小于起始的 ` ``` ` 标记，可能会导致渲染问题。此项检查有助于保持正确的代码呈现。
+- **代码块缩进**：分析代码块中不一致的缩进。如果某行代码的缩进小于起始的 ` ``` ` 标记，可能会导致渲染问题。此检查有助于保持正确的代码呈现。
 
 #### 链接与媒体完整性
 
 - **链接完整性**：文档中的所有相对链接都会根据文档结构计划进行验证，以防止出现死链接。这确保了所有内部导航都能正常工作。检查器会忽略外部链接（以 `http://` 或 `https://` 开头）和 `mailto:` 链接。
 
-- **图片验证**：为避免图片损坏，检查器会验证文档中引用的任何本地图片文件是否存在于文件系统中。它会解析相对路径和绝对路径，以确认文件存在。外部图片 URL 和数据 URL 不会被检查。
+- **图片验证**：为避免图片损坏，检查器会验证文档中引用的任何本地图片文件是否存在于文件系统中。它会解析相对路径和绝对路径以确认文件存在。外部图片 URL 和数据 URL 不会被检查。
 
 #### 图表语法验证
 
 - **D2 图表**：DocSmith 通过尝试将代码编译成 SVG 图片来验证 D2 图表语法。这个过程可以在语法错误导致图形损坏之前捕获它们。
 
-#### 格式与样式强制
+#### 格式与样式强制执行
 
-- **表格格式**：检查表格的表头、分隔线和数据行之间的列数是否不匹配。此项检查可防止常见的表格渲染失败。
+- **表格格式化**：检查表格的表头、分隔线和数据行之间的列数是否不匹配。此检查可防止常见的表格渲染失败。
 
-- **Markdown Linting**：内置的 linter 会强制执行一致的 Markdown 结构。关键规则包括：
+- **Markdown 语法检查**：内置的 linter 会强制执行一致的 Markdown 结构。关键规则包括：
 
-| 规则 ID | 描述 |
+| Rule ID | Description |
 |---|---|
 | `no-duplicate-headings` | 防止在同一部分中出现内容相同的多个标题。 |
-| `no-undefined-references` | 确保所有的链接和图片引用都已定义。 |
-| `no-unused-definitions` | 标记未使用的链接或图片定义。 |
-| `no-heading-content-indent` | 不允许在标题内容前缩进。 |
+| `no-undefined-references` | 确保所有链接和图片引用都已定义。 |
+| `no-unused-definitions` | 标记未被使用的链接或图片定义。 |
+| `no-heading-content-indent` | 禁止在标题内容前缩进。 |
 | `no-multiple-toplevel-headings` | 每个文档只允许一个顶级标题 (H1)。 |
-| `code-block-style` | 对代码块强制执行一致的样式（例如，使用反引号）。 |
+| `code-block-style` | 强制代码块使用一致的样式（例如，使用反引号）。 |
 
-通过自动化这些检查，DocSmith 保持了文档的一致标准，确保最终输出准确且易于导航。
+通过自动化这些检查，DocSmith 为文档维护了一致的标准，确保最终输出准确且易于导航。
 
-要了解有关整体架构的更多信息，请参阅 [工作原理](./advanced-how-it-works.md) 部分。
+要了解有关整体架构的更多信息，请参阅[工作原理](./advanced-how-it-works.md)部分。

package/docs/advanced.ja.md

@@ -0,0 +1,16 @@
+# 高度なトピック
+
+内部の仕組みを理解したいユーザー向けに、このセクションではAIGNE DocSmithのアーキテクチャを詳しく解説します。このツールが舞台裏でどのように機能するのかを説明します。このレベルの詳細は一般的な使用には必要ありませんが、動作のカスタマイズやプロジェクトへの貢献に役立ちます。
+
+内部プロセスと品質管理についてより深く理解するために、以下のセクションをご覧ください。
+
+<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)に進んでください。

package/docs/advanced.zh-TW.md

@@ -0,0 +1,16 @@
+# 進階主題
+
+對於希望了解內部機制的用戶，本節將深入探討 AIGNE DocSmith 的架構，說明該工具在幕後的運作方式。雖然一般使用不需要了解這些細節，但對於自訂行為或為專案做出貢獻，這些資訊將會很有價值。
+
+為了更深入了解內部流程和品質控制，請探索以下章節。
+
+<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)。

package/docs/advanced.zh.md

@@ -1,16 +1,16 @@
 # 高级主题
 
-对于希望了解内部机制的用户，本节将深入介绍 AIGNE DocSmith 的架构。它解释了该工具在后台如何运作。虽然一般使用不需要了解这些细节，但对于自定义行为或为项目做贡献而言，这些信息可能很有价值。
+对于希望了解内部机制的用户，本节将深入探讨 AIGNE DocSmith 的架构。它解释了该工具在幕后如何运作。虽然对于一般使用而言，不需要了解这种程度的细节，但它对于自定义行为或为项目做出贡献非常有价值。
 
 要更好地了解内部流程和质量控制，请浏览以下部分。
 
 <x-cards data-columns="2">
   <x-card data-title="工作原理" data-href="/advanced/how-it-works" data-icon="lucide:cpu">
-    DocSmith 的架构概述，解释了 AI Agent 在文档生成流程中的作用。
+    DocSmith 的架构概述，解释了 AI agents 在文档生成管道中的作用。
   </x-card>
   <x-card data-title="质量保证" data-href="/advanced/quality-assurance" data-icon="lucide:shield-check">
-    了解 DocSmith 为确保文档格式正确、无错误而执行的内置检查，包括链接检查和图表验证。
+    了解 DocSmith 执行的内置检查，以确保文档格式良好且无错误，包括链接检查和图表验证。
   </x-card>
 </x-cards>
 
-通过探索这些主题，你可以更全面地了解 DocSmith 的功能。要详细了解所有可用命令及其选项，请继续阅读 [CLI 命令参考](./cli-reference.md)。
+通过探索这些主题，您可以更全面地了解 DocSmith 的功能。有关所有可用命令及其选项的详细分解，请继续阅读 [CLI 命令参考](./cli-reference.md)。