> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 AI 代理

> 與 AI 聊天以建置您的 BRICKS 應用程式

AI 代理是 CTOR 的核心。它可以讀取和寫入檔案、編輯程式碼、執行 shell 指令，以及透過聊天介面搜尋您的專案。

本頁介紹**專案工作階段**，繫於單一 BRICKS 應用程式。若要進行建立新專案等工作區層級的工作流程，請參閱[開始聊天](/zh-Hant/ctor/guide/main-chat)。

## 建立工作階段

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 金鑰的服務商。請參閱[設定](/zh-Hant/ctor/reference/settings)以設定您的 API 金鑰。

## 設定思考深度

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

| 等級 | 預算           | 使用情境             |
| -- | ------------ | ---------------- |
| 關閉 | —            | 快速回應、簡單任務        |
| 高  | \~16k tokens | 大多數任務，速度與深度的良好平衡 |
| 最大 | \~32k tokens | 複雜推理、架構決策        |

<Info>
  **最大**思考深度僅適用於支援擴展思考的模型：Claude Opus 4.6、GPT-5.3 Codex、GPT-5.2 Codex 和 GPT-5.2。
</Info>

## 傳送訊息

在輸入列中輸入訊息，然後按 **Ctrl+Enter**（或點擊傳送按鈕）。使用 **Shift+Enter** 換行。

代理會即時串流回應。您可以看到：

* **文字回應**，支援完整的 Markdown 渲染和語法醒目標示
* **思考區塊**，顯示模型的推理過程（可展開，需啟用[顯示思考內容](/zh-Hant/ctor/reference/settings#advanced)）
* **工具呼叫**，以可展開的區塊顯示工具名稱和參數
* **工具結果**，顯示每個工具執行的輸出

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

## 提及檔案

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

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

## 使用技能

在輸入列中輸入 `/` 以觸發技能指令自動完成。選取技能後，會將 `/skill-name` 引用插入訊息中。

所選技能會以可移除的標籤顯示在輸入列中。引用會以一般文字送出；代理會依據技能描述及您的需求，自行決定是否載入該技能。

如需建立和管理技能的詳細資訊，請參閱[技能參考](/zh-Hant/ctor/reference/skills)。

## 附加圖片

點擊圖片附件按鈕或從剪貼簿貼上圖片。支援格式：PNG、JPG、JPEG、WebP、GIF。

圖片會以 base64 編碼內容的形式連同文字訊息一起傳送給模型。

若您的模型不支援圖片，請在設定中指定[備援視覺模型](/zh-Hant/ctor/reference/settings#備援視覺模型)。CTOR 接著會以該模型把每個附件描述成文字，因此即使使用不支援視覺的模型，附件按鈕仍可使用。

## 語音輸入

以口述方式輸入訊息，而不需打字。請先在 [**設定** > **進階** > **實驗性功能**](/zh-Hant/ctor/reference/settings#實驗性功能) 中啟用 **語音輸入**。此功能使用 Apple Speech，因此需要 macOS 26 或更新版本以及麥克風存取權——選項與按鈕僅在支援的 Mac 上顯示。

啟用後，輸入列中會出現一個麥克風按鈕：

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

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

## 檢視訊息

在 [**設定** > **進階**](/zh-Hant/ctor/reference/settings#進階) 中啟用 **顯示訊息按鈕**，即可在輸入列中加入 **訊息** 按鈕。點選該按鈕會開啟 **訊息詳情** 面板，顯示目前工作階段與模型往來的訊息，並分為 **主要代理** 分頁以及每個作用中[子代理](#子代理)各自的分頁。

使用面板標題列的 **Markdown** 或 **JSON** 按鈕即可匯出訊息——CTOR 會開啟原生儲存對話框，讓您選擇檔案的寫入位置。

## 工具呼叫和審核

代理有六個內建工具：`read_file`、`write_file`、`edit_file`、`bash`、`glob` 和 `grep`。

當代理執行 `bash` 指令時，您會看到審核提示：

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

<Tip>
  在**設定** > **代理**中啟用**自動核准 bash 指令**，可跳過所有 bash 指令的審核提示。
</Tip>

<Warning>
  符合[危險指令模式](/zh-Hant/ctor/reference/sandbox#危險指令偵測)的指令——`sudo`、`rm -rf`、改寫歷史的 `git`、`curl ... | sh` 等——即使啟用自動核准或專案處於沙箱模式，仍會以紅色邊框和**危險指令**標籤顯示提示。
</Warning>

如果您已設定 [MCP 伺服器](/zh-Hant/ctor/reference/mcp)，其工具也會與內建工具一起提供給代理使用。

## TypeScript 語言伺服器工具

在 [**設定** > **進階** > **實驗性功能**](/zh-Hant/ctor/reference/settings#實驗性功能) 中啟用 **Language Server Tools**，可為每個專案提供行程內的 TypeScript 語言服務。此選項預設停用；開啟後，代理可以取得單一檔案或整個專案的型別與語法診斷、跳到符號的定義位置，並列出整個專案中對該符號的所有參照。

每次對 `.ts`、`.tsx`、`.cts` 或 `.mts` 原始程式碼執行 `edit_file` 或 `write_file` 後，CTOR 也會自動對該檔案執行診斷，並在工具區塊中呈現結果：

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

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

## 工作區設定檔

[沙箱模式](/zh-Hant/ctor/reference/sandbox)選擇器旁的標籤會顯示代理目前作用於哪個 BRICKS 工作區。在專案聊天中，此標籤為唯讀——CTOR 會以專案的 `workspaceId` 比對您已驗證的[設定檔](/zh-Hant/ctor/guide/authentication#多個設定檔支援)，找不到對應時則會退回使用作用中的設定檔。

若要讓代理在不同工作區執行，請先從**設定 → 帳號**或從[主聊天](/zh-Hant/ctor/guide/main-chat#切換工作區設定檔)輸入列切換設定檔，再開啟專案。

## 建立工作階段分支

點擊最後一則助理訊息底部的 **Fork** 按鈕，即可將目前的工作階段複製為新的工作階段。CTOR 會複製完整的對話歷程，在標題後方加上「 (fork)」，並立即切換到新的工作階段。

一條 **Forked from {title}** 分隔線會標示複製歷程與新訊息之間的邊界，即使側邊欄收合也能清楚看到分支起始位置。

當代理正在串流回應或等待工具審核時，此按鈕會隱藏——分支不應擷取尚未完成的回合。

專案工作階段與主聊天工作階段均可使用此功能。

## 子代理

代理可以將任務委派給專門的子代理。子代理以專注的工具集和指示執行，非常適合程式碼庫探索或程式碼審查等有範圍限制的任務。

您可以從側邊欄管理子代理。如需建立和設定子代理的詳細說明，請參閱[子代理參考](/zh-Hant/ctor/reference/sub-agents)。

## 本機裝置

點擊輸入列中的**本機裝置**按鈕，掃描您本機網路上的 [BRICKS Foundation](/zh-Hant/foundation) 裝置與 [BRICKS Buttress](/zh-Hant/buttress) 伺服器。對話框會以平行方式進行兩種掃描，其中一邊失敗不會清空另一邊的清單。

Foundation 裝置列會顯示位址、版本與下列標記：

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

支援 CDP 的裝置列還有一個 **DevTools** 按鈕。點選即可將該裝置的 Chrome DevTools 檢查器以分頁形式在[右側面板](/zh-Hant/ctor/reference/right-panel#devtools)中開啟——若系統提示，請先輸入裝置通行碼。若該裝置是前景專案執行中的預覽，DevTools 會改為停靠在[預覽分頁](/zh-Hant/ctor/reference/preview#停靠預覽的-devtools)中。

Buttress 伺服器列以紫色強調色與專屬標記呈現：

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

點擊任一卡片可切換選取狀態，支援多選，但兩種類型互斥（選取 Buttress 伺服器會清除 Foundation 的選取，反之亦然）。

底部按鈕會依選取項目改變：

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

## 後續步驟

<Card title="部署您的應用程式" icon="rocket" href="/zh-Hant/ctor/guide/deployment">
  將您的應用程式發布至 BRICKS 伺服器。
</Card>