QGIS 的 AI Agent：完整指南
AI Agent 是 
中的一個聊天面板。你輸入任務，它就會在你已經開啟的專案中運作，包含專案的 layer、CRS、選取範圍與畫面上的顯示範圍。這是我們打造的工具，所以本指南介紹的是我們自己的產品。
本指南涵蓋你的第一次 run、agent 能觸及的範圍、決定其行為的兩個 chip，以及如何復原一次不想要的 run。
一句 prompt 能做的事
四句話，依序輸入到同一個面板中，在同一個專案裡。以下內容沒有任何一項是手動準備的。
安裝與登入
在 QGIS 中，開啟 Plugins -> Manage and Install Plugins，搜尋 AI Agent，然後點選 Install。它可在 QGIS 3.28 以後版本（含 QGIS 4）於 Windows、macOS 與 Linux 上執行。
從 TerraLab 工具列開啟面板，點選 Sign in / Sign up。瀏覽器會開啟，你可以建立帳戶，plugin 會自行完成連線。不需要 API key，不需要信用卡，一開始就有免費的 run 可用。
你的第一次 run
描述結果，而不是操作流程
「依高度為建築物著色」比「開啟屬性、選擇分級 renderer、選取高度欄位」是更好的 prompt。agent 會在動手之前先讀取專案，所以指名 layer、欄位與路徑通常是白打的字。
閱讀步驟，而不只是答案
訊息下方的一行灰字會統計工作量：4 steps, 39.6s。展開它，每一次工具呼叫連同其參數與回傳結果都會列出來。這是你分辨「真正正確的結果」與「看起來合理的結果」的方法。
在它提問時回答
一次 run 可能會停在一張帶有二到四個選項的小卡片上。我們的例子問了兩次：畫面範圍內有 6,355 個 OSM 特徵，而 3,124 棟建築物中只有 117 棟帶有高度標籤。這兩次都是工作中真正的分岔點，事後在 trace 中都看得到。
檢查發生了什麼變更
答案下方的 chip 會列出這次 run 建立或動到的 layer。點選其中一個會出現常見的 QGIS 選單：在 Layers 面板中顯示、縮放至該 layer、開啟屬性表、layer 屬性。
一句 prompt 就是一次 run，不論它需要多少個 QGIS 步驟。一次 run 最多執行 60 次工具呼叫或 40 分鐘後會自動停止，因此偏離軌道的任務不會無止盡地執行下去。
agent 能觸及的範圍
資料。 本機檔案、遠端檔案、WFS、WMS、XYZ、STAC 與 COG 影像、OpenStreetMap 資料擷取、地理編碼、路線規劃。把一個 GeoPackage 拖放到面板上，它就會以 layer 的形式載入。
分析。 任何 Processing 演算法，參數名稱與已知的陷阱都是查出來的，而不是用猜的。緩衝區（Buffer）、join、分區統計、拓樸檢查、以 OSM 道路計算等時圈、沿線的高程剖面。
製圖。 樣式（Symbology）、分類與分級 renderer、標籤，含地圖、圖例、比例尺與指北針的版面配置，再匯出成 PDF 或 PNG。
編輯。 新增、更新與刪除特徵，幾何修復，頂點編輯，合併與分割，全都在一個可以回復的真實 QGIS 編輯工作階段中進行。
回答問題。 某個 QGIS 設定的位置，以及如何手動完成這件事，來自官方 QGIS 文件，並附上連結。問它如何修正無效的幾何，你會得到一個答案，而不是一次 run。
如果安裝了 AI Edit 或 AI Segmentation，agent 也能操作它們：用一句 prompt 轉換影像，或將某個區域內某類物件的每個實例向量化。
它會檢查自己的工作
在 Medium effort 以上，agent 會 render 地圖並檢視自己產出的結果。在版面配置那次 run 中，它正是這麼做的：判斷結果難以閱讀，並在完成前修正了繪製順序。
這是值得留意的行為，好壞兩面都是。它回報了 3,124 棟建築物中只有 186 棟有可用的高度，而不是默默地為一個充滿空值的欄位套用樣式。但它也可能自信滿滿地犯錯，所以 trace 仍然是該讀的東西。
保持掌控
有三樣東西介於模型與你的專案之間。
permission chip，位在輸入框 + 旁邊，決定它何時會停下來詢問。
| 層級 | 它會在以下情況前詢問 |
|---|---|
| Ask first | 每一次變更 |
| Balanced（預設） | 刪除與覆寫 |
| Autopilot | 不詢問，除了消耗 credit 與執行 Python |
Autopilot 是工作階段（session）層級的選擇：QGIS 重新啟動後會回到 Balanced，不論你上次選了什麼。有兩件事在任何層級都一定會詢問：任何消耗 credit 的事，以及執行原始 Python（你會在它執行前先看到程式碼）。
approval card 就是「詢問」實際呈現的樣子。一句話說明即將發生的事、你的回答，決定之後就會收合成一行，讓一次很長的 run 仍然易讀。
復原（Undo）。 每一次 run 都會留下一個 checkpoint。面板標題列上的箭頭會開啟清單，最新的排在最前面，你的專案目前所在的那一列會打勾。
選擇其中一列，專案就會回到那個狀態。還原時會先擷取離開前的狀態，所以這個動作本身也能被復原，Ctrl+Alt+Z 則不用開啟任何東西就能往回一步。checkpoint 是以 run 為單位，而不是以單一工具呼叫為單位。
給它正確的情境資訊
agent 已經會讀取專案：layer 名稱、類型、CRS、特徵數量、欄位名稱、範圍、畫布、你的選取範圍。你額外提供的，才是它看不到的部分。
- 附加一張照片、一個資料檔案，或本專案的一個 layer。
- 直接把 layer 從 QGIS 的 Layers 面板拖到這個面板上。
- 把檔案拖放到面板的任何位置：資料會以 layer 載入，圖片則會送給模型。
- 在訊息中輸入
@，可以指名一個資料來源或你已安裝的某個 QGIS plugin。
每個專案都保有自己的對話。標題列上的放大鏡可依標題與訊息內容搜尋，一段對話也能匯出成 Markdown。
兩個值得調整的設定
Effort，也就是 Send 按鈕前面的那個 chip，並不是模型選擇器。它指的是你要買多少「思考量」。
| 層級 | 它做的事 | 方案 |
|---|---|---|
| Instant | 盡可能立刻開始動手，不做規劃也不做研究 | Free |
| Medium | 會規劃、檢查自己的結果、查閱演算法與文件 | Pro |
| High | 對較困難的任務進行更深入的規劃、研究，並能自行判斷方向 | Pro |
Instant 適合「這個專案是什麼 CRS」這類問題，以及單一的樣式變更。本指南中的每一次 run，包括提問與自我檢查，都是 Medium 產出的。High 則適合那種你原本會空出一整個下午來做的任務。
Connectors，Settings 的第一頁，決定資料的來源。共 39 個資料來源，預設開啟 10 個：OpenStreetMap、Overture、Natural Earth、NASA、Copernicus、Planetary Computer、各國家測繪機構等等。每一個都會在你開啟前說明它需要什麼，而大多數什麼都不需要。
你已安裝的 QGIS plugin 也會出現在同一頁，讓 agent 能依名稱使用它們。
Personalisation 是另一個值得一看的頁面。AI 該怎麼稱呼你、你的工作內容、一段關於你工作的說明、固定指示、你的 GIS 經驗、公制或英制、新 layer 該如何命名，以及它在對話之間保留的筆記。
哪些內容會離開你的電腦
每則訊息都會傳送到我們的託管服務。傳送的內容包括：你的請求、專案的描述（CRS、範圍，以及每個 layer 的名稱、類型、幾何類型、可見性、特徵數量、欄位名稱與範圍，加上目前作用中 layer 的一列樣本資料）、專案檔案路徑、你近期的 Processing run、最新的 QGIS 警告，以及你附加的任何內容。
不會傳送的內容：你的 raster 與 vector 檔案內容、專案檔案本身、特徵幾何、完整的屬性表，以及任何你沒有詢問過的專案。你的啟用金鑰不會出現在任何工具結果中，layer URI 中的資料庫密碼會從每一個結果與 traceback 中移除。
Free 與 Pro
Free 方案每月提供 10 次 run，使用快速模型，具備所有工具、所有 connector 與所有 QGIS plugin，供個人使用。Pro 方案每月 49 歐元、250 次 run：困難任務使用 Pro 模型、可用 Medium 與 High effort、具備記憶與固定指示、更長的 run、可商業使用。
沒有任何東西是以工具呼叫次數計費的。60 個步驟的 run 和 3 個步驟的 run 花費相同。
常見問題
它會弄壞我的專案嗎？
它會改變你的專案，這正是重點所在，而這個變更是可以復原的。Balanced 會在任何具破壞性的動作前詢問，即使你核准了不該核准的事，run 的 checkpoint 也能把專案還原。不過在一次長時間的工作階段前，還是建議先儲存專案，就像進行任何一批編輯前一樣。
它會把 Python 寫進我的 QGIS 嗎？
當任務需要時，它可以執行 Python，而這也是唯一一件在每個層級（包括 Autopilot）都會詢問的事。你會在程式碼執行前先看到它。
它出錯時會怎樣？
它是一個語言模型，所以可能會出錯，而且是自信滿滿地出錯。這正是活動區塊存在的意義：展開它，檢視它選用的參數與回傳的數字。我們自己的 run 就回報了 3,124 棟建築物中只有 186 棟有可用的高度，這種資訊值得在你信任這張地圖之前先讀一遍。
一次 run 要花多久？
問問題只需要幾秒，真正的工作則需要幾分鐘。在本指南中：底圖 43 秒，建築物及其高度漸層 6 分 30 秒，版面配置 2 分 37 秒，每個問題不到一分鐘。擷取資料的過程中，QGIS 仍然可以正常使用。
它可以離線使用嗎？
不行。沒有本機模型，也沒有離線模式。plugin 在你的電腦上執行，模型則在我們這邊執行。
我的資料會被用來訓練模型嗎？
不會。這個服務只負責規劃 QGIS 的步驟，僅此而已。
它是開放原始碼的嗎？
plugin 是，採用 GPL-2.0-or-later 授權：工具執行器、權限模型、檔案與網路防護機制、面板皆是。所以在你電腦上執行的部分完全可供稽核。但託管服務、其 prompt 與開放資料目錄則不是。
重點整理
描述結果，而不是操作流程。agent 會先讀取專案，所以指名 layer 與路徑通常是白打的字。
一句 prompt 就是一次 run，不論花費多少步驟，它會在 60 次工具呼叫或 40 分鐘時自動停止。
活動區塊就是這個產品的核心。展開它，才是你分辨「真正正確的結果」與「看起來合理的結果」的方法。
每一次 run 都會留下一個 checkpoint，而還原這個動作本身也能被復原，所以核准了讓你後悔的事並不是死路一條。
Effort 買到的是規劃與檢查，而不是不同的「個性」。Instant 直接回答，Medium 動手並驗證，High 先思考。
Connectors 決定它能找到什麼資料。開啟你的國家測繪機構，比任何 prompt 用字都更有價值。
