AI 助手

12. AI 助手

Lantide Data 內建 AI 副駕駛（Agent），可理解你的工作狀態並直接操作 IDE（建立 SQL 分頁、執行查詢、編輯 Plan / Report）。五階段分析流程見 §1.3；第一次完整體驗見 §2。

12.1 開啟 AI 面板

點擊畫面右側 icon 列底部的 Astroid 圖示（AI 助手），即可展開 AI 對話面板。

• 後續啟動： 面板預設收合，需手動點擊 Astroid 展開。首次啟動體驗（自動展開、Welcome Dialog）見 §2.1。
• 背景執行： 再次點擊 Astroid 收起面板，或切換至 Export Tasks，不會停止進行中的 Agent 回應；對話區僅隱藏，串流在背景繼續（詳見 §12.2）。

12.1.1 Agent 與 Ask 模式

聊天輸入區底部可在 Agent 與 Ask 之間切換（英文 UI；預設 Agent）。模式會跟著目前對話 session 保留，直到你手動切換。

Ask 開啟時，輸入框 placeholder 會提示 Agent 不會編輯你的 artifacts。若模型仍嘗試寫入工具，系統會拒絕（ASK_MODE_DENIED），對話中可看到被擋下的工具呼叫。

與工具列動作的關係： 在 Ask 下點 Generate HTML Report、Resolve Comments 或 Approve & Execute，會提示切回 Agent；可選 Switch & Continue 自動切換並繼續，或取消。

不是 MCP Observe： 外部連線的 Observe 只約束外部 Agent，且不暫停內建 Agent。內建 Ask 只約束內建聊天工具，且不影響你在編輯器裡手動改檔。兩者設定與文案分開，見 §13.5。

若你希望 Agent「改 Plan／補 HTML 一段」，請切回 Agent 再送訊息。

12.2 AI 生成中操作防護

當 AI 正在生成回應時，部分操作可能會中斷生成過程。為了防止你意外打斷 AI，系統在下列操作上加入了確認防護機制——執行時會彈出確認對話框，讓你決定是否繼續：

如果你選擇取消，操作不會執行，AI 繼續正常生成。

生成期間輸入框仍可編輯：你可以先草擬下一則文字、mention 或貼上圖片，但 Enter 不會送出第二個請求；Shift+Enter 仍可換行。右下角按鈕此時是 Stop generation，只停止目前生成，不會清除草稿。生成結束後，Enter 才恢復送出。

不會中斷生成的操作：

提示： 當 AI 未在生成時，受保護操作不會顯示確認對話框，直接執行。

12.3 設定 AI 連線設定檔（Profile）

使用 AI 助手前，需要先設定連線。首次啟動時，系統會自動建立一個 OpenAI 預設 Profile（預設官方 Base URL、API Key 為空），WelcomePanel 會提供「Open AI Settings」按鈕引導你完成設定。

1. 在 AI 面板中點擊設定圖示（齒輪），或點擊 WelcomePanel 的「Open AI Settings」按鈕，開啟設定視窗。
2. 點擊「新增 Profile」（或編輯預設 Profile），選擇連線類型：

• Ollama — 連接本機執行的 Ollama 模型服務。
• OpenAI — 連接 OpenAI 官方 API（預設 Base URL 固定為官方 endpoint），需填入 API 金鑰；填入後可透過 Refresh 拉取模型列表。若你使用其他相容端點或非 OpenAI 供應商，請改用 Custom 並自行填寫 Base URL。
• Custom — 自訂 OpenAI 相容的 API 端點。

3. 填入對應的設定資訊（服務網址、API 金鑰等），然後選擇模型：

• OpenAI 模式： Base URL 為官方預設（唯讀）；填入 API Key 後可拉取模型清單並選擇模型（或手動輸入）。若舊版設定曾指向 Anthropic 等非 OpenAI endpoint，請改選 Custom。
• Ollama / Custom 模式： Model 欄位旁有 Refresh 按鈕，點擊自動從伺服器拉取可用模型清單。若拉取失敗或清單為空，會自動降級為手動文字輸入。

4. 儲存後，將該 Profile 設為使用中。

你可以建立多個 Profile，並隨時從面板頂部的下拉選單切換。設定完成後，WelcomePanel 會自動從引導狀態切換為簡短歡迎詞。

Secondary model（次要模型）： 在 AI 設定列表底部可另選 Secondary model 下拉選單。預設為 Same as active model（與目前使用中 Profile 相同）；亦可指定另一個已設定的 Profile。次要模型用於對話自動命名與 知識抽取等背景任務，不取代主對話模型。僅列出已完整設定（含模型）的 Profile 供選擇。

OpenAI / Custom Profile 可在設定中將 Vision（貼圖） 設為「自動偵測」、「支援」或「不支援」，用於判斷能否把截圖送給模型。

OpenAI / Custom Profile 亦可設定 Reasoning effort（可選）：Auto（預設；已知支援 reasoning effort 的 GPT／OpenAI 模型解析為 Medium，Claude、未知 Custom endpoint 保留 provider default；GLM 類模型沿用其 binary thinking policy）、Off（盡力關閉推理）、Low / Medium / High（開啟並調節強度）。若 provider 明確拒絕此參數，系統會移除參數重試一次並繼續對話。Ollama Profile 不顯示此欄。 對話自動命名與知識抽取等背景任務不會套用此設定（避免額外成本）。

所有 Profile（含 Ollama）可選填 Max Output Tokens（k tokens）：限制單次回覆的輸出上限。留空為 auto（依模型能力與當前 Agent 狀態預設，再由系統夾限；HTML 報告任務另有較高下限）。數值過小時長報告較易觸發 §12.13 的 Output Truncated；過大則受模型與狀態上限約束。背景次要任務不使用此欄。

對話執行與歷史控制

在 AI Settings 的 Secondary model 下方，可為目前工作區調整兩項對話偏好；變更會立即儲存，下一則新訊息才會套用。這些是本機的工作區偏好：會隨 Full backup 與 Application backup 備份，但不會寫進 Workspace export，也不會同步到其他工作區。

History depth 會保留最近回合的完整內容，其餘保留回合改為可信的執行摘要：5 rounds 為 2 完整 + 3 摘要、10 rounds 為 4 + 6、20 rounds 為 8 + 12。若選 10 / 20 rounds 而目前模型 context window 偏小，介面會提示風險；這是提示，不會阻止你選擇。

12.3.1 在對話中貼上圖片（Vision）

僅 OpenAI 與 Custom 連線支援在聊天輸入框貼上截圖（Ollama 不支援）。

1. 在輸入框內 Ctrl/Cmd+V 貼上剪貼簿中的圖片（例如 BI 截圖、錯誤畫面）。
2. 圖片會出現在輸入框上方的待送縮圖列（48×48）；點縮圖右上角 × 可移除尚未送出的圖片。
3. 可附加文字後按 Send；最多 4 張 圖/則訊息。
4. 送出後，圖片會顯示在用戶氣泡內上方（48×48），文字在下方。
5. 點擊已送出的縮圖可開啟大圖預覽；可放大／縮小（50%–300%）、複製圖片，或關閉預覽。

從 Reference Visual 複製圖片： Agent 的 read_reference 只讀 Markdown 文字與圖片連結，看不到圖像素。若需要 Agent（內建 Chat 或外部 Agent）實際看某一張圖：

1. 開啟 Reference，切到 Visual。
2. 在圖片上右鍵 → Copy image。
3. 回到對話輸入框 Ctrl/Cmd+V 貼上（外部 Agent 則貼到其聊天視窗）。

限制與說明：

• 僅當輪送給模型「看」圖；之後對話輪次不會自動帶上歷史圖片（若需再分析請重新貼圖）。
• 若模型不支援 Vision，系統會提示；確認後可僅送文字（圖片不會進模型，氣泡中也不會保留縮圖）。
• 已送出的訊息無法刪除氣泡內圖片；重新產生（regenerate）含圖訊息時僅重送文字。
• 尚未送出的圖片會保留 24 小時 pending lease，不會因另一則 Agent stream 結束而被清除；按縮圖 × 會立即釋放該待送圖片。

12.4 Agent 狀態指示器

AI 面板的 Top Bar 下方有一個固定狀態列，即時顯示 AI Agent 當前所處的工作狀態。狀態會隨著你的操作（聚焦/取消聚焦專案、切換分頁、變更 Plan 狀態等）自動更新，無需手動觸發。

點擊狀態列右側的 ? 按鈕，可開啟說明對話框，詳細了解每種狀態下 Agent 的能力範圍。

提示： 狀態指示器的計算邏輯與後端完全同步——你在前端看到的狀態，就是 Agent 實際運作的狀態。Agent 在不同狀態下可使用的工具不同（例如 SQL Tab 操作僅在 Quick Analysis 與 Executing 狀態下可用）。進入 Executing 狀態後，Agent 會先讀取 Plan，再詢問你偏好的分析執行模式（前台／混合）。後台代理分析（chat-only）僅在 Quick Analysis 提供。

提示： 當 Executing 狀態下 Agent 處於閒置（例如因中斷、超時等原因停止回應），狀態描述會切換為「Paused」提示。此時回到 Plan 分頁，點擊工具列的 Continue 按鈕即可恢復執行（詳見 11.6 節）。

12.5 兩種分析模式：快速分析 vs 專案分析

AI 助手支援兩種分析工作流程，會根據你當前的狀態自動選擇適當的模式：

快速分析模式（無需建立專案）

當你沒有聚焦任何專案時（狀態列顯示 Quick Analysis），如果向 AI 提出資料分析需求，AI 會先詢問你偏好哪種工作方式：

• 快速分析 — 可選前台 SQL 分頁、後台代理分析（chat-only） 或混合模式；適合一次性查詢或快速驗證想法。
• 專案分析 — AI 引導你建立專案，進入結構化的「計畫 → 執行 → 報告」工作流程。

提示： 如果你只是問一個簡單的 SQL 問題（例如「怎麼用 DuckDB 做 PIVOT？」），AI 會直接回答，不會要求你選擇模式。

專案分析模式（結構化工作流程）

當你已聚焦某個專案時，AI 會自動進入專案分析模式。完整流程（接題 → Plan → 批註 → Execute → Report）見 §2.4–§2.7。

兩種分析執行模式（Plan Executing）

當 Plan 進入 Executing 狀態後，AI 會先讀取 Plan，再透過互動問題詢問你偏好的分析執行方式：

後台代理分析（chat-only、不操作編輯器） 僅在 Quick Analysis 提供；Plan Executing 僅提供前台／混合二選一。若專案 Plan 在規劃階段宣告 background_materialized 策略，Executing 時請選 混合模式。

進入 Executing 後，Agent 的典型啟動順序為：讀取 Plan → 詢問執行模式 → 寫入 Todo → 依模式執行 SQL（Pipeline 階段必走 SQL tab）。

AI 只會在 Executing 階段 詢問一次執行模式（同一段對話內）。若你曾在 Quick Analysis 選過後台模式，按下 Execute 開始新 Plan 時仍會重新詢問前台／混合。若你已表達過 Executing 偏好，AI 會直接沿用，不會重複詢問。

Plan 與 Report 的配對關係

每個 Plan 執行完成後會產出一份獨立的 Report，兩者一對一配對（Plan 1 → Report 1，依此類推）。

• AI 在完成所有分析步驟後，會一次性產出完整報告，同時自動將 Plan 標記為已完成（Executed）。
• AI 不會修改舊的 Report。 執行新 Plan 時只會生成新的 Report；微調已產出 Report 須透過批註或對話指示修訂。

Plan 與 Report 的增量編輯

當 AI 需要修改 Plan 或 Report 的部分內容時（例如根據你的批註修訂某段分析步驟），AI 會優先使用增量編輯（找到需要修改的段落，僅替換該段落），而非整份文件覆寫。這帶來兩個好處：

• 更精準： 只改動需要修改的部分，不會影響其餘內容。
• 即時同步： 如果你正在編輯器中檢視 Plan 或 Report，修改後的內容會即時反映在編輯器中，無需手動重新開啟。

提示： 如果你在快速分析過程中發現需求越來越複雜（如需要多步驟分析、產出正式報告），AI 會主動建議你升級為專案模式。

12.6 AI 直接操作你的 IDE（UICommand）

這是 Lantide Data AI 最強大的能力——Agent 不只是「出一張嘴的顧問」，而是能直接操作你的 IDE 的副駕駛。

AI 可以執行的操作：

查詢執行與步驟記憶（Quick Analysis 後台／Executing 混合模式）：

• run_query / run_sql_tab：Plan Executing 時必須傳 purpose（≤40 字，本步意圖，寫入 Query Step Ledger）。run_query 另依上下文推斷是否物化；多步時可用 result_label 供 FROM 引用。
• 步驟亦記入對話級 Query Step Ledger；可選在正文寫 [[QUERY_STEP]] 補充 pitfalls。
• 系統 prompt 會注入 Recent Query Steps 摘要（不含完整 SQL）。回溯完整 SQL 的三級路徑：(1) query_result(result_id=...)（結果仍在記憶體時）；(2) get_cache_source(cache_name=...|tab_id=...|result_id=...)（結果已 spill 或過期、但快取仍存在）；(3) list_query_steps(include_sql=true) 列出本對話步驟。人類亦可於 Data → Cached 右鍵 查看 SQL（與 get_cache_source 同源解析）。

所有操作都在你眼前發生 — 當 AI 建立一個 SQL Tab 時，你會看到新分頁出現；當 AI 執行查詢時，你會看到結果顯示在結果面板中。你隨時可以接管或修改 AI 的工作。手動 SQL 或快速分析範例見 §2.8、§12.5。

提示（Agent 查詢工具）： 探索／試錯階段以 validate_query 輕量驗證 SQL 可執行（不回傳資料列）；正式取數以 run_query 取得預覽，最多 200 行。後台查詢在多步分析、多表 JOIN 或複雜 CTE 時會物化為快取，供後續 FROM "步驟名" 引用；前台 SQL 分頁則一律物化。你可在 Data → Cached 右鍵 查看 SQL 審閱來源。歷史對話若仍顯示舊工具名 test_query，僅為舊紀錄展示。

提示（SQL Server 大結果）： 對 SQL Server／Azure SQL，若遠端估計超過 500,000 列，validate_query 可能回傳 warning_required 與 warning_id；run_query／run_sql_tab 須在你確認後帶 large_remote_warning_id 重試。Agent 會透過 ask_user 請你決定是否繼續。

注意： AI 的所有操作都是唯讀的——它可以建立 SQL Tab 並執行 SELECT 查詢，但無法修改你的原始資料檔案。

12.7 AI 提問互動（ask_user）

在分析過程中，AI 可能需要你做出選擇或確認。此時 AI 會在對話中顯示一個互動問題區塊：

• 如果 AI 提供了選項按鈕，你只需點擊對應的按鈕即可回答。
• 如果 AI 需要自由文字回覆，你可以在輸入框中輸入回答。

常見的 AI 提問場景：

• 「你想要快速分析，還是建立專案進行結構化分析？」（模式選擇）
• 「請選擇你偏好的分析執行模式：前台自動分析 / 混合模式」（Executing 階段；Quick Analysis 另可選後台代理分析）
• 「確認要將 Plan 標記為已完成嗎？此操作無法撤銷。」
• 「有多個相關的表，你想優先分析哪一個？」
• 「探索配額已用盡，是否繼續探索？」（選項：Continue exploring / Stop for now）
• Plan Grilling（口徑對齊）： Plan 草案寫完後、或分析方向大改時，Agent 一次只問一個決策（指標口徑、分母、篩選邊界、粒度等），並標出建議答案；你確認後共識會寫進 Plan。這與上方「選模式／選表」同屬 ask_user，但節奏固定為一次一題、先查可查事實再問決策。見 §2.5。

提示： AI 的提問會在對話氣泡中以明顯的互動區塊呈現，與一般文字回覆區分開來。如果你沒有回答，AI 會等待你的回覆而不會自行推進。超過 5 分鐘未回覆會自動超時。偏好裡的 Clarifying questions（§15.3.1）調節一般澄清積極度；Grilling 則是 Plan 對齊的結構化流程，兩者互補。

12.8 與 AI 對話：詢問資料、產生 SQL

設定完成後，你可以直接在對話框中輸入問題，例如：

• 「這個資料集有哪些欄位？」
• 「為什麼這條 SQL 會報錯？」
• 「幫我分析每個月的銷售總額變化趨勢」

AI 助手會自動參考你目前工作區的資料結構（表名、欄位名），提供貼合你實際資料的回答。根據問題的複雜度，AI 可能會：

• 直接回答：簡單問題直接給出答案或 SQL 範例。
• 建立 SQL Tab 並執行：複雜分析需求會在你的 IDE 中建立分頁、撰寫並執行查詢（詳見 12.6 節）。
• 詢問你的偏好：需要確認時透過互動問題提問（詳見 12.7 節）。

提示： AI 助手在回答過程中可能會以 validate_query 驗證 SQL、或以 run_query 執行查詢取得預覽，這些操作都是唯讀的，不會修改你的資料。驗證不會回傳資料列；執行查詢的預覽上限為 200 行（見 §12.6）。

提示（回看歷史結果）： 使用 query_result 讀取先前 run_query 的結果時，回應可含 sql 摘要與 cached_table_name（若已物化），便於在對話壓縮後仍追溯查詢定義。

提示（含 Markdown 批註情境）： Plan / Report 批註存於 sidecar（*.annotations.json）；Agent 透過 read_plan / read_report 取得含 mark 的磁碟正文與 annotation_summary（詳見 §11.8）。

在訊息中引用工作區物件（beta）

在聊天輸入框輸入 @ 可開啟最近使用的物件；繼續輸入名稱會搜尋目前工作區。可引用：Project、Plan、Report、HTML Report、Reference、持久 SQL Tab，以及資料表／資料檔。資料表涵蓋 Cached、MCP 已物化表、已連線資料庫表、初始／Additional／Cloud folder 中可查詢的檔案或工作表。選取後會插入不可拆開的 mention chip；Agent 會依物件的穩定識別資訊定位，不只依畫面上的名稱猜測。

• ↑／↓ 選擇，Enter 或 Tab 插入，Esc 關閉清單並保留原本的 @文字。
• 每則訊息最多 10 個物件；可用 Backspace／Delete 整顆刪除。
• 同一工作區複製貼上會保留可用的 chip；跨工作區或已刪除／封存的物件會個別降級為純文字，其餘內容不受影響。
• Recent 只記錄人工選取、開啟與聚焦，不會因 Agent 背景操作改變；封存或失效物件不會繼續出現在清單。
• 也可從側邊欄將支援的 Project、文件、持久 SQL Tab 或資料列拖曳到聊天輸入框；若不便拖曳，在該列右鍵選 Add to chat。這兩種方式都插入同一種可驗證的 mention，不會自動開檔、讀取完整內容或提高 Agent 權限。External agent mode（Execute／Admin）啟用時，資料表列的 Add to chat 改為 Copy table name，複製 SQL 編輯器可用的 quoted 表名。
• 暫不支援直接提及整個 data source／workspace、臨時 SQL Tab、批註或 OS 檔案；請改選其中的可查詢表／檔案，或以文字說明。

若 @ 清單無法載入，可按 Retry；這不影響輸入或送出純文字。若送出時物件剛好已被刪除／封存，該回合不會寫入對話或啟動 Agent，請移除失效 chip 或重新搜尋後再送出。關閉 feature flag 時，新訊息不提供物件候選，但既有對話仍會以 chip 或安全的文字 projection 顯示。

12.9 AI 數據分析工具

除了 SQL 查詢之外，AI Agent 還內建了一組統計與機器學習分析工具，能直接在對話中為你完成進階數據分析——無需安裝額外套件。

使用方式： 你只需要用自然語言描述分析需求（例如「幫我檢定這兩組數據是否有顯著差異」），AI 會自動選擇合適的工具。在執行任何分析工具之前，AI 一定會先向你確認（透過 ask_user 互動問題），你同意後才會執行。

可用的分析能力：

分析結果呈現： AI 會在對話中以結構化格式呈現分析結果，包含統計量、p 值、效果量與文字解讀，讓你不需要查閱統計教科書就能理解結論。

提示： 在快速分析或專案執行階段，AI 會先用 SQL 準備數據，再透過 activate_analysis 啟用所需的統計工具並執行。規劃 Plan 階段僅做資料探索與修訂計畫，不執行統計分析。無論哪個階段，執行分析前 AI 都會先向你確認參數。

提示： 分析工具的計算結果僅在對話中呈現，不會修改你的原始資料或快取表。

12.10 AI 分析方法論（Analysis Methodology）

AI Agent 內建結構化分析方法論，能自動識別你的分析場景並套用對應的最佳實踐——你不需要手動指定方法論，AI 會自動判斷並應用。

場景識別： AI 會將你的分析需求歸類為以下場景之一，並據此決定分析策略與驗證重點：

分析品質保障： 根據識別的場景，AI 會在 Plan 中加入驗證 checkpoint、在統計結果中報告效果量與顯著性，並在 Report 附帶 limitations。漏斗分析的 stage 定義、分母與最大流失等要求，已於 §1.3、§2.5、§2.7 示範。

12.11 AI 自動感知的上下文（Context Engine）

每次你發送訊息給 AI 時，系統會自動將以下資訊打包傳送，讓 AI 完整理解你的工作狀態——你不需要額外操作，一切自動進行：

這代表什麼？

• 你不需要告訴 AI「我在寫什麼 SQL」 — 它已經看到你當前分頁的內容。
• 你不需要重複解釋專案背景 — 聚焦專案後，AI 自動知道你在做哪個分析、Plan 的進度如何。
• 你可以直接說「幫我用 clean_orders 這張表」 — AI 已知道你有哪些快取表、每張表有哪些欄位。
• 你不需要手動複製錯誤訊息 — 當查詢失敗時，AI 會自動看到完整的報錯內容與觸發的 SQL，你只需說「為什麼這條 SQL 報錯？」即可獲得修正建議。
• Markdown 分頁的批註走 sidecar + MD mark — Agent 讀取磁碟正文（含 mark）與 annotation_summary（詳見 §11.8）。
• Agent Memory — 僅在總開關開啟且內容已寫入知識檔時，模型才會帶入你的長期記憶；佇列中待核准項不會注入（詳見第 13 章）。

效能優化： 系統採用分層傳遞策略——每次對話時僅自動傳送精簡摘要（工作區名稱、活躍分頁標題、快取表清單等），AI 需要深入了解時會自動呼叫內部工具取得完整上下文（欄位定義、SQL 內容、專案檔案等），無需你額外操作。這大幅降低了每次對話的 token 消耗，同時確保 AI 在需要時仍能取得完整資訊。

進階： 送給模型的系統提示詞分為核心規則、當前工作狀態指引與上下文摘要；完整可呼叫的工具列表由模型收到的 function 定義提供，而非在狀態指引中重複列舉。

隱私說明： 上下文資料僅在你發送訊息的當下組裝並傳送給你設定的 AI 模型服務（Ollama / OpenAI / Custom），不會儲存在任何第三方伺服器。

12.12 Context Usage 圓環

AI 輸入框的右側（Send 按鈕旁）有一個小型的 Context Usage 圓環，讓你即時掌握當前對話的 token 消耗狀況：

• 圓環以弧形進度條呈現 context 使用比例——弧越長表示消耗越多。
• 將滑鼠移到圓環上，tooltip 會顯示詳細數值，例如 42.3% · 18.5K / 43.7K context used。
• 僅在 AI 回覆過至少一次（有 token 用量資料）後才會出現。
• 切換到新對話時，圓環會重置。

提示： 如果你在 AI Profile 設定中指定了自訂 context window 大小（≥ 1024 tokens），圓環的分母會使用你的自訂值，而非模型回報的預設值。

提示： 當你切換或編輯 AI Profile 的模型 / context window 設定後，圓環會自動清除舊值並重新取得最新用量，確保顯示的數據與當前模型一致。

12.13 對話 Token 用量與截斷警告

系統會自動管理每次 AI 回覆的輸出 token 上限，盡可能避免回應被截斷。當遇到極端情況時，對話中會出現以醒目的琥珀色邊框標示的警告訊息：

提示： 大多數情況下你不會看到這些警告。系統會在背景自動進行接續嘗試，僅在自動接續仍無法完成時才顯示警告。若長回覆經常被截斷，可在 Profile 提高 Max Output Tokens（§12.3），或縮短單次任務範圍。

12.14 AI 思考過程與工具調用的即時呈現

AI 助手在回覆過程中可能會經歷多個步驟——思考、呼叫工具、取得結果、再繼續回覆。這些步驟會按照實際發生的時序逐段堆疊在對話中，讓你隨時掌握 AI 正在做什麼。

五種區塊類型：

對話中的 fenced code block：

多行 ````` 程式碼區塊在串流完成後可將滑鼠移入區塊，右上角會出現工具按鈕（由左至右：Open in new SQL tab → Copy）：

• 串流中：最後一段正文尚在輸出時，工具列不顯示；完成後才出現。
• 觸控裝置（v1 限制）：無 hover 能力時工具列可能不可見；請待串流完成後改用桌面滑鼠操作，或手動建立 SQL 分頁貼上內容。

串流中的行為：

• Thinking 與 Tool Call 區塊有最大高度限制，超出時會自動向下滾動並在底部加上漸層淡出效果，確保不會佔據整個畫面。
• 寫作型工具參數跑字期間，小窗約顯示三行並自動折行（不出現橫向捲軸），內容持續增長時往下滾；工具結束後收合為一行摘要，展開詳情時仍為可橫向捲動的單行／預格式化檢視。若你按 Stop，已顯示的部分參數會保留在該 Tool Call 區塊中。
• 串流完成後，Thinking 與 Tool Call 區塊會自動折疊，只留下一行摘要（如「Thinking (12 lines）」或「tool_call: show_tables」／validate_query 的 SQL 摘要），讓你專注於最終回覆。需要時點擊即可展開查看。

對話捲動：

• 新訊息到達時，對話區會自動跟隨捲至底部。
• 若你向上捲動閱讀（含在 Thinking / Tool 區塊內捲動），自動跟隨會暫停，右下角出現圓形向下箭頭按鈕。
• 只要自動跟隨已暫停，該按鈕一定顯示（即使你已手動捲到最底部）。
• 暫停後需點擊按鈕或發送新訊息才恢復跟隨；Agent 生成結束不會自動跳回最新訊息。
• 點擊按鈕可恢復跟隨並捲至最新訊息，按鈕隨即隱藏。

Tool Call 自動分組收合：

當 AI 連續發出 3 次以上的 tool call，系統會自動將這些呼叫收合為一個 「N tool calls」 分組，避免大量展開的工具區塊佔滿對話畫面。點擊分組標題即可展開查看每筆 tool call 的詳細內容。

活動指示器（Activity Indicator）：

在 AI 回覆過程中，有些階段 AI 正在運作但尚未產出可見的文字（例如工具呼叫執行中、多輪迭代間重新呼叫 LLM 時）。為了消除「畫面停住」的體感，系統會在這些靜默期自動顯示 trailing spinner 與狀態文字提示（如「Processing tool calls...」、「Thinking...」），告知你 Agent 仍在正常運作中。spinner 在工具呼叫期間也會持續顯示，直到工具回傳結果後才清除狀態提示，避免閃爍。此外，當 AI 回覆的文字串流暫停超過數秒時（例如模型在內部整理工具呼叫），系統也會自動顯示「Working...」spinner，確保你知道 AI 仍在正常運作。

提示： 停止按鈕採用中性灰色設計，降低視覺突兀感，讓你在需要時才注意到它。

檔案變更條（File changes）：

當一則 AI 回覆在該回合內成功寫入工作區檔案時，訊息底部（正文與 Copy / Fork 操作列之間）會出現 檔案變更條，彙總本則回覆影響的資源——無需展開多個 Tool Call 即可追蹤 Agent 動了哪些檔。

撤回限制與語意：

• 安全模式： 若你在 Agent 寫入後又手動編輯過該檔正文，系統會偵測內容已偏離 Agent 寫入結果而阻擋撤回，並提示衝突；可選擇 Revert anyway 強制覆寫回本則開始前內容（會丟失之後的手動／其他 Agent 改動）。
• 停止生成： 中途 Stop 後，已成功寫入的檔案仍會出現變更條並可 Undo（含 HTML 多 chunk 部分完成的情況）。
• 新建檔： Agent 在本則回覆內新建的 Plan / Report / SQL tab / HTML，撤回時清空內容但保留檔案與分頁列（不刪檔、不關 tab）。
• add_report 連帶： 若本則回覆的 add_report 已使 Plan 進入 Executed，撤回該 Report 列時可能因 Plan 狀態副作用而被阻擋（不可 force）；需依提示手動處理 Plan 狀態。
• 範圍： 撤回僅針對單則 assistant 回覆內的寫入，不跨 message、不跨對話；與 git 無關。
• 重新載入對話： 已撤回的列會標示為已還原；歷史對話重新開啟後仍可看到變更條與統計。

提示： 批註 Resolve、Query Step Ledger、run_query 物化快取、Reference 檔寫入等不在檔案變更條範圍內。Plan 進度 sidecar（Todo）由 Progress 面板呈現，見 §11.6。

訊息操作列（Message Actions）：

每則 AI 回覆的訊息氣泡右側外緣會顯示操作按鈕：

僅在回覆已完成持久化後顯示 Fork 圖示。若回覆在中途被停止、或工具回合尚未寫入完成，則無法分支。

提示： 來源對話若有進行中的 ask_user 互動，你仍可在其他已完成的回覆上 Fork；來源對話的提問不受影響。

提示： 如果你使用的模型（如 DeepSeek-R1、QwQ）會在回覆中夾帶 <think> 標籤，系統會自動攔截這些標籤並將其內容正確歸類為 Thinking 區塊，不會出現在正文中。

12.15 對話管理（新增 / 切換 / 刪除 / 清除全部）

• 新增對話： 點擊 AI 面板頂部的「新增」按鈕，開啟一個全新的對話（空白上下文）。
• 分支對話（Fork）： 在已完成 AI 回覆的操作列點擊 Fork 圖示，會複製截至該則回覆的完整對話紀錄（含工具軌跡）到新對話，並自動切換過去。與「新增對話」的差異在於 Fork 保留既有上下文，適合平行探索不同假設而不弄丟原分析線。
• 自動命名： 新對話的第一條訊息發出後，系統會自動以 LLM 生成一個簡明的對話標題，即時顯示在對話歷史列表中。若自動命名失敗，系統會以訊息前幾個字作為 fallback 標題。Fork 產生的對話標題以 Fork · 為前綴。
• 手動重命名： 將游標移至 Top Bar 的對話標題區域，會出現鉛筆圖示。點擊後進入 inline 編輯模式（文字自動反白全選），修改完按 Enter 確認或按 Escape 取消。標題最長 60 字。修改後即時同步至對話歷史列表。
• 切換對話： 點擊 Top Bar 的歷史圖示，彈出浮層選單，可搜尋、瀏覽並切換至之前的對話。對話按日期分組顯示（Today / Yesterday / Earlier），當前活躍的對話以高亮標示。
• 刪除對話： 在對話歷史浮層中點擊刪除按鈕，移除不需要的對話。
• 清除全部歷史： 在對話歷史浮層的搜尋框下方，點擊 Clear All History 按鈕，可一次清除所有歷史對話。系統會顯示二次確認提示，確認後會刪除所有對話但保留當前正在進行的對話。

每個工作區的對話記錄是獨立的。

12.16 連線狀態指示

AI 面板頂部有一個連線狀態指示燈：

• 綠色 — 連線正常，可以開始對話。
• 紅色 / 灰色 — 連線異常。點擊可查看錯誤詳情，請檢查 Profile 設定是否正確。

[圖片] AI 對話面板：對話介面、Agent 狀態指示器與連線狀態

[圖片] AI 設定視窗：Profile 設定畫面

設計說明： 分析模式與 ask_user 見 Agent 時代的數據分析工作流 §二、§十；統計工具與方法論護欄見 Agent 時代的數據分析工作流 §十一；Context 工程見 Prompt 與 Context 工程。