TRAE Agent 與 SOLO 實戰手冊

按 TRAE 官方學習資料獨立整理的任務導向手冊。涵蓋工作區脈絡、Rules、Agent 與 SOLO 工作流程、子智能體、MCP、Git、驗收、安全沙箱、私隱及疑難排解。產品名稱和介面會更新，使用舊教學前應先核對更新日誌。

TRAE 由脈絡、規則到智能體執行及驗收的工作流程 — 可靠的 TRAE 任務應結合最少而足夠的脈絡、持久規則、明確計劃、受控執行及人工驗收。

1. 選擇合適的工作介面

介面	合適任務	控制方法
編輯器 + Agent	問答、局部修改、除錯、解釋	附上精確脈絡，檢查每項差異
SOLO Agent	多步修改、建置、測試、Git 及端對端交付	高風險或廣泛任務先啟用 Plan
自訂智能體／子智能體	可重用的專業工作	限定角色，只授予必要工具
Cue	編輯器內預測修改	只接受你能理解的建議

較早的官方文章可能使用 Builder、Builder with MCP、SOLO Builder 或 SOLO Coder。現時版本已把相關體驗整合為 Agent 和 SOLO Agent；請以已安裝版本顯示的名稱為準。

2. 安裝、登入及準備專案

從官方網站下載並安裝現行版本的 TRAE。
登入後開啟真實專案資料夾，要求修改前先確認 Git 狀態。
等待工作區索引完成；專案層面的答案過時時，到設定 → 脈絡 → 程式碼索引管理重建索引。
在設定 → 脈絡 → 忽略檔案排除密鑰、產生檔案、依賴套件及無關大型目錄。
先執行唯讀任務：讓 TRAE 解釋技術堆疊、進入點、測試方式及風險，不作修改。

請概述此程式碼庫，找出執行進入點、測試指令、建置指令、資料儲存，
以及絕不能保存密鑰的檔案。暫時不要修改檔案或執行指令。

3. 撰寫可以驗收的任務

寫明成果、證據、範圍、驗收條件，以及必須先確認的動作。

目標：修正管理後台一直停留在「正在登入」的問題。
證據：使用本機測試帳戶在 /admin 重現。
範圍：只限前端認證狀態及登入 API 用戶端。
驗收：登入成功進入後台；錯誤密碼顯示提示；重新整理後保留工作階段；
現有後端測試繼續通過。
安全：不得重設資料庫或修改正式環境設定。
先重現並說明根本原因，再提出計劃。

4. 用 # 加入精確脈絡

引用	用途	例子
`#Code`	目前檔案內的函式或類別	解釋權杖重新整理流程
`#File`	一個或多個指定檔案	比較表格驗證與 API 架構
`#Folder`	限定目錄	梳理認證模組
`#Workspace`	全專案檢索	找出登入端點的所有呼叫方
`#Doc`	已建立索引的本機或網上文件集	按產品規格實作逾時規則
`#Web`	即時網頁搜尋或指定網址	核對目前框架遷移指南

文件集可從網址加入，也可上載支援的本機文字檔案。官方說明會擷取同一路徑下指定深度的頁面。來源更新後應重新整理，並等待索引完成。

#File src/auth/login.ts #File src/auth/session.ts #Doc Authentication Spec
找出載入狀態無法結束的原因，引用相關函式及規格條目。
不要檢查無關的客戶資料目錄。

5. 大範圍執行前使用 Plan

遷移、跨模組功能、安全工作或陌生程式碼庫應在 SOLO 啟用 Plan。可以像編輯文件般修改計劃，直至檔案範圍、測試、回復方案及未決問題清楚。

只制定計劃，內容包括：
1. 重現及根本原因檢查；2. 要修改的檔案及原因；3. 新增或更新的測試；
4. 遷移或回復步驟；5. 阻礙安全實作的問題。
得到批准前不要修改。

6. 使用持久 Rules

專案 Rules 保存程式碼庫慣例，使用者 Rules 保存穩定的個人偏好。規則要簡短、可驗證，不要混入一次性任務內容。官方列出的優先次序為：使用者本次輸入 → 自訂智能體提示 → user_rules.md → project_rules.md。新版亦支援子程式碼庫內的巢狀 Rules 及 AGENTS.md，實際作用範圍請以現行版本為準。

# 專案工程規則
- 使用 pnpm，禁止建立 package-lock.json。
- 聲稱完成前執行 lint 及受影響測試。
- 不得修改 .env、憑證、generated/ 或正式資料。
- 新增依賴套件或修改公開 API 前先詢問。
- 交付時列出新增、修改及未驗證的檔案。

7. 建立聚焦的智能體及子智能體

TRAE 智能體由提示及工具組成。可在 Agent → Create 使用智能產生或手動設定，定義角色、模型、脈絡及工具。SOLO 會在任務匹配時調用子智能體。

名稱：安全審查員
職責：審查目前差異中的認證、授權、注入、密鑰外洩、不安全依賴及破壞性操作。
工具：唯讀程式碼庫、差異及測試工具；不得部署或向外部寫入。
輸出：按嚴重程度列出問題、檔案位置、觸發條件及測試。
除非明確要求，否則不修改程式碼。

優先使用多個職責明確的專業智能體，不要向一個智能體開放所有工具。沒有統一整合負責人時，不要讓多個智能體同時修改同一檔案。

8. 透過 MCP 連接工具

MCP 可向智能體提供外部資料及動作。只加入可信服務，檢查啟動指令、參數、環境變數及工具清單，再把必要工具分配給相應智能體。憑證應放在受支援的密鑰機制內，不要寫入提示或可分享設定。

MCP 安全部署清單：
1. 核對發佈者及安裝指令。
2. 使用非敏感資料測試唯讀工具。
3. 審查寫入、刪除、發佈及付款能力。
4. 限定智能體職責及工作目錄。
5. 匯出或分享智能體/MCP 設定前移除權杖。
6. 工作流程不再需要時停用服務。

TRAE 表示會掃描分享或匯入的智能體及 MCP 設定是否含憑證，但這只是額外防護，不能作為把密鑰放入可匯出檔案的理由。

9. 讓 SOLO 建置、測試及處理 Git

SOLO 可以實作功能、重構、編寫測試、執行建置、審查修改、更新文件及執行 Git 任務。需要清晰批准點時，把程式碼修改與版本控制發佈分開。

按已批准計劃實作。每個邏輯步驟後執行最小相關測試。
最後顯示 git status、總結差異，並列出測試及精確結果。
不要提交、推送、切換分支或修改遠端狀態。

我批准差異後：建立 feature/session-timeout 分支，只暫存已審查檔案，
以簡潔訊息提交，然後在推送前停止。

10. 在實際產品中驗收，而不只看對話

閱讀實際差異，拒絕無關修改。
執行適合專案的 lint、類型檢查、針對性測試及建置。
開啟受影響頁面或服務，檢查成功、錯誤、載入、空白狀態及重新整理。
確認密鑰及除錯資料沒有進入版本控制或智能體脈絡。
要求智能體明確說出尚未驗證的項目。

執行交付審計：開啟修改後的介面，重現原有問題，測試成功及錯誤流程，
檢查主控台與網絡錯誤，並逐項對照驗收條件。
不能只憑 HTTP 200 就報告「完成」。

11. 管理脈絡及長對話

切換到無關任務時壓縮或重設脈絡；壓縮後重新附上權威要求。文件集保存穩定資料，Rules 保存穩定行為，本次提示保存任務決定。智能體記憶只屬便利功能，不能代替事實來源。

繼續前請重新說明：目前目標、已確認決定、修改檔案、測試結果、
未解決風險及下一個安全動作。凡未從程式碼庫或附加資料驗證的內容，
都要標記為推斷。

12. 沙箱、批准及私隱

官方安全指南列出三種模式：設有允許清單的沙箱（預設，適合大部分使用者）、手動執行（每項指令均確認）及自動執行（在沙箱外執行，風險較高）。陌生專案或工具應使用手動批准；破壞性指令、外部寫入、部署及存取憑證必須明確確認。

TRAE 表示程式碼檔案保留在裝置本機；為計算程式碼索引，明文程式碼可能短暫上載，之後刪除，但會保留嵌入及相關中繼資料。對話資料是否保存或使用視乎設定。需要時使用忽略檔案及 Privacy Mode；受監管工作必須核對最新私隱政策。

13. 常見疑難排解

情況	檢查內容
程式碼答案錯誤或過時	重建索引、附上指定檔案、移除互相衝突的舊脈絡
智能體忽略規範	規則作用範圍和優先次序；縮短互相矛盾的規則
指令被阻止	閱讀沙箱原因；只批准準確且安全的指令或縮小範圍
MCP 工具消失	服務程序、設定、憑證、工具分配、日誌及逾時
SOLO 循環或停滯	停止任務、要求狀態摘要、縮小範圍、補充缺少證據
脈絡索引失敗	格式、大小、忽略規則、路徑、網絡及索引狀態
用量或限制異常	現行計劃、模型／模式、Max Mode 及官方計費頁面

14. 官方學習路線

建議依次閱讀官方 SOLO 快速入門、脈絡指南、Rules 最佳做法、自訂 Agent 與 MCP 說明、沙箱指南、資料使用說明及更新日誌。

編輯覆核日期：2026 年 8 月 11 日。本頁是獨立編寫的使用手冊，並非 TRAE 官方文件的複製。使用前請重新核對現行介面、計劃、模型、限制、資料政策及安全行為。