使用 AI 代理

AI 代理是 CTOR 的核心。它可以讀取和寫入檔案、編輯程式碼、執行 shell 指令，以及透過聊天介面搜尋您的專案。 本頁介紹專案工作階段，繫於單一 BRICKS 應用程式。若要進行建立新專案等工作區層級的工作流程，請參閱開始聊天。

​

建立工作階段

1. 在側邊欄中選取應用程式
2. 點擊新增工作階段

工作階段會持久儲存，並根據您的第一則訊息自動命名。每個工作階段都有自己的對話歷程和模型選擇。

​

選擇模型

點擊輸入列中的模型選擇器來挑選 AI 模型。模型依服務商分組：

• Anthropic —Claude Sonnet 4.6、Claude Opus 4.6、Claude Haiku 4.5
• OpenAI —GPT-5.3 Codex、GPT-5.2 Codex、GPT-5.2、GPT-5.1 Codex Mini
• OpenAI Codex —GPT-5.3 Codex、GPT-5.2 Codex
• Google —Gemini 3 Flash、Gemini 3 Pro
• GitHub Copilot —來自各服務商的多種模型
• OpenAI Compatible 端點 —具有每個端點模型清單的自訂端點（Ollama、vLLM、LM Studio 等）

清單中只會顯示已設定 API 金鑰的服務商。請參閱設定以設定您的 API 金鑰。

​

設定思考深度

點擊模型選擇器旁邊的思考選擇器，以控制代理的推理深度：

​

傳送訊息

在輸入列中輸入訊息，然後按 Ctrl+Enter（或點擊傳送按鈕）。使用 Shift+Enter 換行。 代理會即時串流回應。您可以看到：

• 文字回應，支援完整的 Markdown 渲染和語法醒目標示
• 思考區塊，顯示模型的推理過程（可展開，需啟用顯示思考內容）
• 工具呼叫，以可展開的區塊顯示工具名稱和參數
• 工具結果，顯示每個工具執行的輸出

點擊中止可隨時停止正在執行的回應。

​

提及檔案

在輸入列中輸入 @ 以搜尋專案中的檔案。選取檔案後，其路徑會包含在您的訊息中，讓代理知道要處理哪些檔案。

• 在資料夾名稱後輸入 / 可瀏覽目錄
• 使用方向鍵導覽，按 Enter 或 Tab 選取
• 最多顯示 20 個結果

​

使用技能

在輸入列中輸入 / 以觸發技能指令自動完成。選取技能後，會將 /skill-name 引用插入訊息中。 所選技能會以可移除的標籤顯示在輸入列中。引用會以一般文字送出；代理會依據技能描述及您的需求，自行決定是否載入該技能。 如需建立和管理技能的詳細資訊，請參閱技能參考。

​

附加圖片

點擊圖片附件按鈕或從剪貼簿貼上圖片。支援格式：PNG、JPG、JPEG、WebP、GIF。 圖片會以 base64 編碼內容的形式連同文字訊息一起傳送給模型。 若您的模型不支援圖片，請在設定中指定備援視覺模型。CTOR 接著會以該模型把每個附件描述成文字，因此即使使用不支援視覺的模型，附件按鈕仍可使用。

​

語音輸入

以口述方式輸入訊息，而不需打字。請先在 設定 > 進階 > 實驗性功能 中啟用 語音輸入，並授予麥克風存取權。 啟用後，輸入列中會出現一個麥克風按鈕：

• 按一下按鈕開始口述，再按一下即可停止。
• 或按住按鈕進行口述，放開即可停止。

您的語音會即時轉錄到輸入列中。檢視並編輯文字後，照常傳送訊息。在設定中以語音語言選擇辨識語言；預設採用應用程式語言。

​

選擇語音引擎

CTOR 會以下列兩種引擎其中之一進行轉錄：

• Apple Speech — 於裝置端執行且無須下載任何內容，需要 macOS 26 或更新版本。
• Whisper — 可在 macOS、Windows 與 Linux 上執行。同樣於裝置端轉錄，但需先下載執行環境與模型。

在 macOS 26 或更新版本上兩者皆可使用，可藉由設定中的語音引擎一列選擇，該平台預設為 Apple Speech。其他平台一律使用 Whisper。

​

設定 Whisper

Whisper 需要兩項下載，各自在 設定 > 進階 > 實驗性功能 中有對應的一列：

1. Whisper 執行環境 — 語音辨識引擎。點選下載並觀看進度列，取消可中止下載。準備就緒後該列會顯示已安裝，有新版執行環境時則提供更新。
2. 模型下載 — 於 Whisper 模型中選取的模型檔案。請先挑選大小：Tiny、Base、Small、Medium 或 Large v3 Turbo。模型越大轉錄越準確，但執行較慢且占用更多磁碟空間，預設為 Base。

下載內容會先經過驗證才安裝。若想釋出磁碟空間，可用移除刪除其中任一項。 在 Windows 與 Linux 上，加速一列可挑選要下載的 Whisper 建置版本——Auto、CPU、Vulkan 或 CUDA。Auto 會偵測您的機器支援的最快選項並在選單中標示；若加速建置版本運作異常，請改選 CPU。macOS 的建置版本一律使用 Metal，因此該列不會出現。 若在執行環境或模型安裝完成前點選麥克風按鈕，CTOR 會提供開啟設定捷徑，讓您完成設定。 使用 Whisper 時，您也可以將語音語言設為自動（偵測），在您說話時偵測所使用的語言，而不必固定於單一語言。Apple Speech 需要明確的語言，因此該選項僅在使用 Whisper 時顯示。

​

檢視訊息

在 設定 > 進階 中啟用 顯示訊息按鈕，即可在輸入列中加入 訊息 按鈕。點選該按鈕會開啟 訊息詳情 面板，顯示目前工作階段與模型往來的訊息，並分為 主要代理 分頁以及每個作用中子代理各自的分頁。 使用面板標題列的 Markdown 或 JSON 按鈕即可匯出訊息——CTOR 會開啟原生儲存對話框，讓您選擇檔案的寫入位置。

​

工具呼叫和審核

代理有六個內建工具：read_file、write_file、edit_file、bash、glob 和 grep。 當代理執行 bash 指令時，您會看到審核提示：

• 點擊執行以執行指令
• 點擊拒絕以拒絕執行

如果您已設定 MCP 伺服器，其工具也會與內建工具一起提供給代理使用。

​

TypeScript 語言伺服器工具

在 設定 > 進階 > 實驗性功能 中啟用 Language Server Tools，可為每個專案提供行程內的 TypeScript 語言服務。此選項預設停用；開啟後，代理可以取得單一檔案或整個專案的型別與語法診斷、跳到符號的定義位置，並列出整個專案中對該符號的所有參照。 每次對 .ts、.tsx、.cts 或 .mts 原始程式碼執行 edit_file 或 write_file 後，CTOR 也會自動對該檔案執行診斷，並在工具區塊中呈現結果：

• 收合的標頭會顯示錯誤 / 警告計數晶片（例如 2 errors），讓您不需展開即可看到問題
• 展開後，差異下方會列出逐行清單，包含 L<line>:<col>、嚴重度、TS<code> 與訊息

代理會在工具結果文字中讀到相同的診斷，並被指示在宣告任務完成前先修復這些問題。語言服務以專案為範圍，首次使用時才會延遲建立，並在 tsconfig.json 變動時重建。當選項關閉時，編輯與寫入結果與先前完全相同。

​

網路研究

當問題超出代理既有知識範圍時—例如最新的說明文件、套件版本、發行說明、API，或你在對話中貼上的網頁—代理可以搜尋網路並讀取網頁。 這由兩項能力構成：

• 網路搜尋 — 代理提出研究問題，取得綜整後的答案以及答案所依據的來源。每則結果會列出實際執行的搜尋查詢，以及編號的來源清單，含每個引用網頁的標題與網域。
• 讀取網址 — 代理最多可讀取 20 個公開的 http(s) 網頁（包含說明文件與 PDF），並依其內容回答問題。代理會用它追查搜尋找到的來源，或消化你貼進對話的連結。付費牆後方或封鎖自動讀取的網頁會逐一回報狀態，而不會讓整次呼叫失敗。

研究工作是在獨立的呼叫中以快速模型執行，而非使用你對話所用的模型，因此在進階模型上的工作階段不會為每次搜尋支付該模型的費率。結果為唯讀，因此不需要核准，在規劃模式中同樣可用。子代理也會繼承這兩項能力。 請求由 BRICKS AI 提供服務；若對話正在 Vertex AI 供應商上執行，則改用你自己的 Vertex AI 專案—此時搜尋費用會記在該專案上。若其中一條路徑無法使用，CTOR 會改用另一條。兩者皆未設定時，這些能力不會出現，代理會在沒有它們的情況下運作。 若要關閉，請在設定 > 進階中調整網路搜尋工具。此選項預設啟用。

​

Codemode

透過 Codemode，代理可以撰寫一段呼叫其他工具的簡短 JavaScript 程式，而不必逐一呼叫每個工具。代理會用它平行執行彼此獨立的呼叫、把一個結果串接到下一個呼叫，或從大型結果中只擷取需要的部分。只有指令碼輸出的內容會進入對話，因此大型工具結果不會塞滿上下文。 指令碼在隔離的沙箱中執行。指令碼本身沒有檔案系統、網路或計時器——它所做的一切都透過代理的工具進行，因此指令審核、規劃模式、沙箱規則和你的 hooks 都會套用到每個呼叫，就像直接呼叫一樣。指令碼也可以：

• 呼叫 MCP 伺服器提供的工具，包括代理尚未載入對話中的工具（先搜尋後再呼叫）
• 使用你在設定中設定的供應商與 API 金鑰來產生圖片及執行分類器
• 保留少量數值供下一個指令碼使用。保存的數值會跟著對話走，因此倒轉或分支工作階段時也會一併倒轉

少數工具不能從指令碼呼叫，因為它們需要獨立的一輪或會啟動其他工作：向你提問、規劃核准、產生子代理，以及管理其他工作階段與排程。 工具區塊會顯示指令碼，以及它所發出呼叫的即時清單，每個呼叫都附有狀態與耗時。 Codemode 適用於主代理、專案代理和子代理。在代理檔案中設有 tools 清單的子代理，只有在清單列出 codemode 時才能使用。若要關閉，請在設定 > 代理中調整 Codemode。此選項預設啟用。

​

工作區設定檔

沙箱模式選擇器旁的標籤會顯示代理目前作用於哪個 BRICKS 工作區。在專案聊天中，此標籤為唯讀——CTOR 會以專案的 workspaceId 比對您已驗證的設定檔，找不到對應時則會退回使用作用中的設定檔。 若要讓代理在不同工作區執行，請先從設定 → 帳號或從主聊天輸入列切換設定檔，再開啟專案。

​

建立工作階段分支

點擊最後一則助理訊息底部的 Fork 按鈕，即可將目前的工作階段複製為新的工作階段。CTOR 會複製完整的對話歷程，在標題後方加上「 (fork)」，並立即切換到新的工作階段。 一條 Forked from 分隔線會標示複製歷程與新訊息之間的邊界，即使側邊欄收合也能清楚看到分支起始位置。 當代理正在串流回應或等待工具審核時，此按鈕會隱藏——分支不應擷取尚未完成的回合。 專案工作階段與主聊天工作階段均可使用此功能。

​

子代理

代理可以將任務委派給專門的子代理。子代理以專注的工具集和指示執行，非常適合程式碼庫探索或程式碼審查等有範圍限制的任務。 您可以從 Plugins 面板的 Agents 分頁管理子代理。如需建立和設定子代理的詳細說明，請參閱 plugins 參考與子代理參考。

​

本機裝置

點擊輸入列中的本機裝置按鈕，掃描您本機網路上的 BRICKS Foundation 裝置與 BRICKS Buttress 伺服器。對話框會以平行方式進行兩種掃描，其中一邊失敗不會清空另一邊的清單。 Foundation 裝置列會顯示位址、版本與下列標記：

• 此工作區 — 裝置已綁定至與目前專案相同的工作區
• CDP — 裝置支援 Chrome DevTools Protocol
• Workspace 驗證 — 裝置支援工作區驗證

支援 CDP 的裝置列還有一個 DevTools 按鈕。點選即可將該裝置的 Chrome DevTools 檢查器以分頁形式在面板中開啟。當您已登入該裝置的工作區時，CTOR 會自動以工作區驗證開啟 DevTools。當工作區驗證無法使用且該裝置已設定通行碼時，CTOR 會改為提示輸入通行碼。當兩者皆無法使用時，CTOR 會告知您在該裝置上設定通行碼，或將其登入工作區。若該裝置是前景專案執行中的預覽，DevTools 會改為停靠在模擬器分頁中。 Buttress 伺服器列以紫色強調色與專屬標記呈現：

• JWT required ／ open — 伺服器是否已繫結至工作區、是否需要工作區 JWT
• verified ／ UDP only — HTTP /buttress/info 探測是否成功，或僅看到 UDP 通告
• 此工作區 — 伺服器已繫結至與目前專案相同的工作區

點擊任一卡片可切換選取狀態，支援多選，但兩種類型互斥（選取 Buttress 伺服器會清除 Foundation 的選取，反之亦然）。 頁尾左側一律會有開啟裝置面板按鈕，可在下方面板中開啟裝置分頁——與此對話框相同的工作區裝置清單，不必保持對話框開啟或選取任何項目即可瀏覽。 頁尾右側的按鈕會依選取項目改變：

• Foundation 裝置 → 檢查或綁定會插入由 bricks-cli 技能執行的 /bricks-cli 提示。綁定會將應用程式關聯到選取的裝置，並快速更新最新編譯的設定—不會建立新版本。
• Buttress 伺服器 → 請代理進行整合會插入 /bricks-ctor 提示，附上各選取伺服器的識別資訊、工作區相符狀態與通告中的 generator 能力。整合規則由 bricks-ctor 技能提供 — 包括各 generator 類型的模型建議、標準的自動探索 buttressConnectionSettings，以及 iOS 模擬器注意事項（UDP 探索僅在實機上運作）。

​

後續步驟