初始化嚮導設定

無論透過 Microsoft Store 還是 Desktop 安裝，首次開啟 HagiCode 的 Web 介面時都會自動彈出 初始化嚮導。完成它之後，您會擁有一個可用的預設 Hagicoder 和至少一個專案，可以直接開始第一次會話。

它與 Desktop 的首次使用引導不同

Desktop 首次啟動時的「首次使用引導」（選擇語言、確認法律文件、下載 Hagicode Server）發生在 Web 介面出現之前，見 Desktop 安裝。本頁說明的是之後在 Web 介面裡出現的初始化嚮導。

開始之前

請先確認：

• 已安裝並登入至少一個 Agent CLI。嚮導只會列出執行 Hagicode Server 的這台機器上已偵測到的 CLI，沒有偵測到時無法建立 Hagicoder。支援的 CLI 與安裝方式見 AI Agent CLI 安裝。
• Desktop / Store 使用者：已依 安裝指南 安裝 Node.js 24+ 與 Git。
• 準備好一個要接入的本機儲存庫或工作目錄：步驟 3 會讓您登記它，路徑必須真實存在。

嚮導總覽

嚮導由 4 個步驟組成，左側導覽會顯示目前進度，頂部的徽章顯示「已就緒 N / 3 個步驟」。其中前 3 步是 必要步驟，第 4 步「社群」標記為 可選：

步驟	目標	完成標誌
1. 語言與主題	選擇介面語言，並挑選一組季節配色	點擊「繼續」確認語言
2. Hagicoder	選擇 CLI 與模型，建立預設 Hagicoder	Agent 顯示「Agent已在兜底班組中」
3. 專案	至少登記一個本機專案	專案步驟顯示「專案步驟已完成」
4. 社群（可選）	開始第一次對話，或查看社群入口	點擊「完成」

左下角的「稍後提醒我」會先收起嚮導、之後再提醒；「不再顯示」會關閉自動彈出。兩種方式都可以隨時從頁面頂部的「嚮導」入口重新開啟嚮導，未完成的步驟會保持待完成。

步驟 1：語言與主題

目標：確定介面語言和顏色主題。

1. 在「選擇介面語言」中點選一種語言（支援 10 種）。這裡只會切換應用程式的介面語言，不會影響英雄或專案。
2. 在「選擇顏色主題」中為春、夏、秋、冬任一季節選擇「亮色」或「暗色」變體。選擇後立即生效，之後可以從頁面頂部的主題入口再修改。
3. 點擊「繼續」。確認語言後進入下一步 Hagicoder。

步驟 2：設定 Hagicoder

目標：建立預設 Agent，名字固定為 Hagicoder，並把它加入兜底班組。

如果系統裡已經有 Agent，這一步會提示「找到Agents」或直接顯示「Agent已在兜底班組中」：

• 已有 Agent 但不在兜底班組中時，可以點擊「加入兜底班組」，也可以改為「改為建立新的Agent」。嚮導不會自動替您加入。
• 已經在兜底班組中時，直接點擊「下一步：建立專案」即可。

否則按下面的流程建立：

1. 選擇主要AgentCLI：只顯示本機已偵測到的 CLI，選中的卡片右側會出現勾號。

2. 選擇主要模型：

   • 在清單中選一個現有模型，可用上方的搜尋框依名稱或模型 ID 篩選。
   • 或在「輸入自訂模型」裡手動輸入模型名稱，例如 gpt-5.5、glm-5.1、claude-opus-4-7，建立時後端會重用或新建對應的範本。

   

3. （建議）點擊「執行連線測試」：檢查所選 CLI 是否可用。它 不會 向模型送出提示詞，因此只能確認 CLI 能被呼叫，不能確認模型的回覆。結果為「CLI 可用」即通過；測試失敗或逾時不會阻止建立，但在修正 CLI 之前它可能無法正常運作。

4. （選用）選擇預設頭像：從建議的頭像中點選一個，或點擊「換一批」查看其他選項。

5. 點擊「建立Agent」。成功後頁面顯示「Agent已在兜底班組中」，所選 CLI 與模型會寫入 Hagicoder 的預設設定。

   

6. 點擊「下一步：建立專案」。

支援哪些 CLI

嚮導裡能選的 CLI 取決於本機已安裝並被偵測到的 Agent CLI，不限於某一種。完整的支援範圍與安裝方式以 AI Agent CLI 安裝 為準；其中 Hermes、Gemini、DeepAgents 需要先完成手動安裝或驗證。

常見問題

• 提示「沒有可用的本機 CLI」：請先依 AI Agent CLI 安裝 在這台電腦上安裝並登入 CLI，然後點擊「重新偵測」。也可以點擊「暫時略過」，這一步會保持未完成，嚮導之後還會提醒您。
• 清單裡沒有我的 CLI：確認它已安裝並在執行 Hagicode Server 的環境中可用；Desktop 使用者請重新啟動 Desktop 以重新整理 PATH。
• 連線測試失敗：頁面會顯示失敗原因。常見原因包括 CLI 尚未登入或權杖無效。請先在終端機裡用該 CLI 跑一次最小對話，確認它本身可用，再點擊「再次執行」。
• Agent 已建立，但加入兜底班組失敗：頁面會提供「重試加入兜底班組」，重試只會加入同一個 Agent，不會重複建立。

步驟 3：建立專案

目標：至少登記一個專案，讓後續會話有可讀的工作目錄。嚮導會先偵測是否已經有專案：沒有時顯示登記表單，已有時顯示目前專案摘要。

1. 在「登錄一個本機專案」中填寫 項目名稱（必填）、資料夾路徑（必填）以及選填的 項目描述。欄位與路徑驗證和主介面的「新建項目」對話方塊完全一致。
2. 點擊「建立專案並繼續」。路徑會在儲存時驗證，驗證通過後專案被建立，嚮導自動進入下一步。
3. 專案建立後再回到本步驟，會看到「目前專案摘要」和「專案步驟已完成」的標記。此時可以點擊「繼續」進入社群，也可以點擊「再新增一個專案」登記更多專案（再用「新增專案」儲存，或「取消」返回摘要）。

想先用範例專案體驗？

嚮導裡只提供登記本機專案。「示範項目」位於主介面「新建項目」對話方塊的「示範項目」頁籤：它會自動克隆並註冊官方 MonoSpecs Demo 儲存庫，預設路徑為 data/repos/monospecs-demo，實際目錄以執行階段的資料目錄（DataDir）設定為準。此方式需要 Git，並且能連線到 GitHub。

常見問題

• 提示「專案建立失敗」：確認資料夾路徑正確且真實存在。

步驟 4：社群

目標：確認準備就緒，並選擇下一步做什麼。這一步是可選的。

三個必要步驟都完成後，頁面會顯示「HagiCode 已可以使用」和三個必要步驟的完成狀態：

• 開始第一次對話：點擊後嚮導關閉，工作區中會開啟新增對話視窗。對話需要專案，如果還沒有專案，這裡會提示「請先建立專案」，並提供「前往專案步驟」的按鈕。
• 關於 HagiCode：點擊「開啟關於頁面」會在瀏覽器中開啟官網「關於」頁，那裡彙整了完整的社群入口，嚮導保持開啟。
• 完成：點擊右下角「完成」會關閉嚮導。若還有必要步驟未完成，它們會保持待完成，您可以從頁面頂部的「嚮導」入口重新開啟。

下一步

建立普通會話先用預設唯讀模式讓 AI 讀懂專案，確認方向後再決定是否切換到編輯模式。

建立提案會話需要拆分計畫、評審方案時，使用提案會話把想法變成結構化的實施計畫。