初始設定 | ArcBlock

本指南將逐步引導您完成 AIGNE DocSmith 的互動式設定過程。此程序會在您首次執行 aigne doc create 時自動執行，但您也可以手動啟動。設定的目標是建立一個 config.yaml 檔案，用以儲存您產生文件的偏好設定。

如何開始設定程序

若要手動開始設定，請在終端機中導覽至您專案的根目錄，並執行以下指令：

aigne doc init

aigne doc init

此指令將啟動一個包含 9 個步驟的互動式問卷，用以設定您的文件。

設定步驟

設定過程將會提示您一系列問題。以下各節將詳細說明每個步驟。

步驟 1：定義文件目的

第一步是確立您文件的主要目標。此選擇會影響所產生內容的語氣、結構和重點。

提示： 📝 [1/9]: 您希望您的文件幫助讀者達成什麼目標？

您可以從以下清單中選擇一個或多個選項：

選項	名稱	說明
`getStarted`	快速入門	幫助新使用者在 30 分鐘內從零開始到正常運作。
`completeTasks`	完成特定任務	引導使用者完成常見的工作流程和使用案例。
`findAnswers`	快速找到答案	為所有功能和 API 提供可搜尋的參考資料。
`understandSystem`	理解系統	解釋其運作原理以及設計決策背後的原因。
`solveProblems`	解決問題	幫助使用者進行故障排除並修復問題。
`mixedPurpose`	混合目的	全面涵蓋多種需求。

步驟 2：識別目標受眾

接下來，請指定您文件的主要讀者。這有助於將語言和技術深度調整到適當的水平。

提示： 👥 [2/9]: 誰會閱讀您的文件？

您可以從此清單中選擇多個受眾：

選項	名稱	說明
`endUsers`	終端使用者（非技術人員）	使用產品但不編寫程式碼的人。
`developers`	進行整合的開發人員	將產品加入其專案的工程師。
`devops`	DevOps/基礎架構人員	部署、監控和維護系統的團隊。
`decisionMakers`	技術決策者	評估技術以決定是否實施的架構師或技術主管。
`supportTeams`	支援團隊	幫助他人使用產品的人員。
`mixedTechnical`	混合技術受眾	開發人員、DevOps 和其他技術使用者的組合。

步驟 3：指定讀者知識水平

請指出您受眾的預期知識水平。這能確保內容以有效的方式呈現，避免提供過於基礎或過於複雜的資訊。

提示： 🧠 [3/9]: 您的讀者對您的專案已經了解多少？

請選擇最能描述您讀者的選項：

選項	名稱	說明
`completeBeginners`	完全的初學者	完全不熟悉該領域或技術。
`domainFamiliar`	熟悉領域，但對工具陌生	了解問題領域，但對此特定解決方案感到陌生。
`experiencedUsers`	有經驗的使用者	需要參考資料或進階主題的常規使用者。
`emergencyTroubleshooting`	緊急/故障排除	遇到問題並需要快速修復的使用者。
`exploringEvaluating`	探索/評估	試圖判斷該工具是否符合其需求的使用者。

步驟 4：設定文件深度

請選擇文件的詳細程度。此參數決定了所產生內容的範圍和細節層級。

提示： 📊 [4/9]: 您的文件應該有多詳細？

請選擇以下其中一個級別：

選項	名稱	說明
`essentialOnly`	僅包含必要內容	簡潔地涵蓋最常見的 80% 使用案例。
`balancedCoverage`	平衡的涵蓋範圍	提供足夠的深度和實用範例。
`comprehensive`	全面	涵蓋所有功能、邊界情況和進階場景。
`aiDecide`	讓 AI 決定	工具會分析程式碼的複雜度，以建議適當的深度。

步驟 5：選擇主要語言

請選擇您文件的主要語言。系統將偵測您作業系統的語言，並建議其為預設語言。

提示： 🌐 [5/9]: 您的文件的主要語言是什麼？

您可以從支援的 12 種語言清單中選擇，包括英文、簡體中文和西班牙文。

步驟 6：選擇翻譯語言

請選擇您希望將文件翻譯成的其他語言。

提示： 🔄 [6/9]: 我們應該將文件翻譯成哪些語言？

您可以從支援的選項中選擇多種語言，不包括上一步選擇的主要語言。

步驟 7：定義文件目錄

請指定儲存所產生文件檔案的資料夾。

提示： 📁 [7/9]: 我們應該將您的文件儲存在哪裡？

預設路徑為 .aigne/doc-smith/docs。您可以接受此預設值或提供不同的路徑。

步驟 8：指定內容來源

請指出工具應分析哪些檔案、資料夾或 URL 來產生文件。您可以新增多個路徑，並使用 glob 模式進行更精確的檔案匹配。

提示： 🔍 [8/9]: 資料來源

系統將提示您輸入檔案路徑（例如 ./src）、glob 模式（例如 src/**/*.js）或 URL（例如 https://example.com/openapi.yaml）。如果未提供任何路徑，工具將預設分析整個專案目錄。

步驟 9：提供自訂規則

此為選用步驟，可讓您提供具體指示或限制，供 AI 在內容生成過程中遵循。

提示： 📋 [9/9]: 您對您的文件是否有任何自訂規則或要求？（選用，按 Enter 鍵跳過）

您可以輸入任何要求，例如語氣、風格或要排除的內容。例如：「著重技術準確性，避免使用行銷術語。」

config.yaml 檔案

在您回答完所有問題後，DocSmith 會將您的回答儲存到一個名為 config.yaml 的設定檔中，該檔案位於您專案的 .aigne/doc-smith/ 目錄下。此檔案將作為未來所有文件產生的藍圖，並且可以隨時手動編輯。

以下是一個產生的 config.yaml 檔案範例：

config.yaml

# 用於文件發布的專案資訊
projectName: AIGNE DocSmith
projectDesc: AIGNE DocSmith 是一款功能強大、由 AI 驅動的文件產生工具...
projectLogo: https://docsmith.aigne.io/image-bin/uploads/9645caf64b4232699982c4d940b03b90.svg

# AI 思考設定
thinking:
  effort: standard

# =============================================================================
# 文件設定
# =============================================================================

# 目的：您希望讀者達成的最主要成果是什麼？
documentPurpose:
  - getStarted
  - completeTasks

# 目標受眾：誰最常閱讀這份文件？
targetAudienceTypes:
  - endUsers

# 讀者知識水平：讀者在閱讀文件時通常具備哪些知識？
readerKnowledgeLevel: completeBeginners

# 文件深度：文件應該有多全面？
documentationDepth: comprehensive

# 自訂規則：定義具體的文件產生規則和要求
rules: |
  避免使用模糊或空洞的詞語，這些詞語無法提供可衡量或具體的細節...

# 目標受眾：描述您的具體目標受眾及其特徵
targetAudience: |

# 語言設定
locale: en
translateLanguages:
  - zh
  - zh-TW
  - ja

# 路徑
docsDir: ./docs  # 儲存所產生文件的目錄。
sourcesPath:  # 要分析的原始碼路徑。
  - ./README.md
  - ./agents

# 圖片篩選設定
media:
  minImageWidth: 800

總結與後續步驟

設定完成後，您將看到一則確認訊息，顯示您新設定檔的路徑。

設定完成

儲存初始設定後，您現在已準備好建立您的文件。

建立文件

了解如何執行建立程序以建立您的第一份文件。

管理偏好設定

了解如何隨時檢視和修改您已儲存的設定。