對話裡的思考塊、工具卡片、diff 是什麼

為什麼要學會看這些方塊

還記得 第 7 章開第一個對話時，那些「AI 回答上下多出來的東西」嗎？灰色可以按 ▶ 展開的、白色像卡片的、紅一段綠一段像考卷改錯的——那些不是介面裝飾，也不是 bug，而是 Pi Agent 跟一般 ChatGPT 網頁最大的差別：它把 AI「內心的想法」和「動手做的紀錄」通通攤在你面前。

會看的人可以做到：

• 答案怪怪的時候，展開思考塊追出 AI 是哪一步想歪了。
• AI 說「我幫你讀了 configuration.yaml」的時候，展開工具卡確認它到底讀了哪個檔、有沒有讀對。
• AI 提議改設定檔之前，展開 diff 逐行檢查再決定接不接受——這是「你允許 AI 動你的家」之前最後一道人眼把關。

不會看的人：AI 亂改配置檔弄壞 HA、跑錯指令、讀了不該讀的檔，你都是事後才發現。所以這一章的目標很單純：看到每一種方塊，你都能一秒說出「這是什麼、要不要展開」。

三種特殊區塊的分工（一句話版）

先給一張總覽，之後每一節會逐一拆解。看完這張表你就有心智模型，後面的細節都是掛在這張表上的補充：

思考塊（Reasoning block）詳解

思考塊是三種區塊裡最容易被忽略的一種——因為它預設是收起的，很多人根本不知道它可以點開。

長什麼樣

灰色底、標題寫「Thinking」或「思考中」（依語言設定），左邊有一個小三角 ▶ 或 +。它出現在 AI 正式回答的上方，代表「AI 是先想過這一段，才給你下面那個答案」。點一下 ▶ 展開，就會看到 AI 逐步推理的內容，通常是一大段自言自語的文字。

什麼時候會出現

只有 reasoning（推理）模型才會有。第 12 章會完整拆解各家的差異，這裡先給一張快速對照，看得懂圖 9-1 的思考塊來自哪家就夠了：

非 reasoning 模型（GLM-4-Flash、GPT-4o、Claude Haiku 3.5、Kimi K2-Instruct 那種）就沒有思考塊——它們是「直接吐答案不留過程」。

展開能讀到什麼

會看到 AI 在給你正式答案前的推理過程，例如：「使用者想要一個晚上 10 點關客廳燈的自動化。我需要用 time 觸發，動作是 light.turn_off，還要考慮如果沒人在家的話⋯⋯」這種一連串的自言自語。有時候長達幾百字，有時候只有兩三行。

什麼時候該讀

• 答案怪怪的、跟你預期差很多，想追蹤 AI 為什麼這樣回。
• 想學它的分析框架（例如 AI 怎麼把「晚上 10 點關燈」分解成觸發／條件／動作）。
• 想確認 AI 有沒有考慮到某個特殊條件（例如「有人在家才不要關」）。

什麼時候可以不用讀

• 一般家用問題、AI 回得對且乾淨。
• 只是問一個查詢型的問題（「HA 支援幾種 domain」這種）。
• 反正你也不打算採用這個答案。

為什麼有時候明明選了 reasoning 模型卻看不到思考塊

三個可能：

1. 第 6 章教的 reasoning 勾選沒打勾——GLM-4.6 的 model entry 進階區塊有一個 reasoning checkbox，那才是使用者面向的開關；沒勾的話 pi-web 收得到思考內容但不會展開顯示。
2. Provider 底下的 thinkingFormat 選錯——這是 provider 層的欄位（不是 model 層），OpenAI 相容端點通常留 openai，GLM 選 zai、DeepSeek 選 deepseek、Qwen 選 qwen；Anthropic 走內建 SDK 不用選。設錯的話 pi-web 拆不出 reasoning_content，就會把思考文字整段塞進正式答案或直接吃掉。
3. 你選到了 provider 底下的非 reasoning 模型——例如智譜的下拉裡除了 GLM-4.6 還有 GLM-4-Flash，後者不是 reasoning；Groq 上的 Kimi K2 只有 Instruct 沒有 Thinking。看模型名字對照一下。

工具卡片（Tool call）詳解

工具卡片是三種區塊裡最重要的一種——因為它代表「AI 真的動了東西」，你必須知道它動了什麼。

長什麼樣

白色的卡片、上方寫「Tool: xxx」或「Calling xxx」，中間有一個小區塊列出輸入（parameters）與輸出（result）的摘要。點卡片可以展開看完整內容。有些卡片跑到一半會顯示「Running⋯⋯」轉圈，跑完會亮綠燈（成功）或紅燈（失敗）。

什麼時候會出現

AI 需要「動手做」而不只是「回答文字」時。動手包含：讀你貼過來的檔案、跑一段 bash 指令、抓網頁、查天氣、搜資料庫等。哪一種工具會被叫出來，取決於你裝了哪些 skill（第 16 章會教你自己寫 skill）以及 AI 覺得該不該用。

常見的工具名稱速查（pi coding agent 內建 7 支）

Pi Agent 的核心 agent（@earendil-works/pi-coding-agent）內建工具只有這 7 支，卡片上顯示的就是這幾個字，全小寫：

展開能讀到什麼

兩塊：實際傳給工具的參數（例如 read 的 path 是什麼、bash 的 command 是什麼）、以及工具回傳的結果（檔案內容、指令輸出、grep 命中行等）。這是「AI 到底做了什麼」的證據，比 AI 自己說的更可靠。

什麼時候該讀

• AI 說「我讀了 xxx」的時候，展開對應的 read 卡確認它讀對了。
• 看到 write／edit 這類會動檔案的，一定要展開看，尤其是 path 對不對；edit 還要看 old_string 是不是真的來自原檔。
• 看到 bash 卡片，展開看指令有沒有危險字（rm -rf、chmod 777、curl | sh）。
• AI 給的結論跟你預期不同，想追工具的原始輸出，看是不是資料本來就是那樣。

Inline diff 詳解（改檔前的最後把關）

Inline diff 是三種區塊裡最需要你「動眼看」的一種——因為它是「AI 給你的修改提案」，你點頭它才會改。

長什麼樣

一段一段的紅色（- 開頭，被刪除的行）＋ 綠色（+ 開頭，新增的行）程式碼區塊，中間夾著沒變的白色行做為對照。跟 GitHub 的 pull request diff 是同一種東西。

什麼時候會出現

AI 提議改你貼上去的檔案時。例如你把 configuration.yaml 貼進對話說「幫我加個 MQTT integration」，AI 就會回一段 diff 給你看要在第幾行插什麼、刪什麼。

展開能讀到什麼

完整的變更 patch。有的版本會把 diff 折起來只顯示前後幾行，點「展開」可以看到 full context。旁邊通常會有一個「Apply」或「Copy」按鈕。

什麼時候該讀

每一次都要讀。沒有例外。這是「你允許 AI 動你的檔案」之前的最後一道人眼把關。

怎麼採用 diff（三種方式）

1. 方式 A：手動複製整段修改後版本

   最保守。pi-web 的 diff／工具卡片右上角有一個 Copy 按鈕（i18n 標籤 i18n.copy，中文介面會顯示「複製」），另外有 Show details / Hide details 展開完整 patch，還有 Compare HEAD 可以跟 git 已存的版本比對。把改完後的內容複製起來，自己去 configuration.yaml 貼上取代原本內容即可。適合「不信任 AI 自動改檔」或「只想套用其中一部分」的情境。

2. 方式 B：叫 AI 用 edit 或 write 工具直接改

   回一句「幫我寫進去」，AI 通常會呼叫 edit（做局部替換、保留其他行）或 write（整份覆蓋）工具改檔。優先讓它用 edit——出錯範圍限縮在改動那幾行。這時候你要盯緊那張工具卡片：展開看 path 是不是你想的那個檔、內容有沒有跟 diff 對上。適合「已經看過 diff 覺得沒問題」的情境。

3. 方式 C：說「不要」讓 AI 另外想

   如果你看完 diff 覺得方向錯了、或有一段不能刪，直接回覆「這樣不對，我要保留 xxx」「請改用 yyy 方式」。AI 會重新生一段 diff。這是最省事的迭代方式，比自己去改半天再貼回來快多了。

一個真實例子的解剖

假設你問 AI：「幫我加一個晚上 10 點自動關客廳燈的自動化」。用 GLM-4.6（勾了 reasoning）＋ 裝了 home-assistant-best-practices skill（skill 本身不含新工具，但會給 AI 一份 HA-flavor system prompt，讓它知道要用 edit 而不是 write 蓋掉整個 automations.yaml）。AI 的回應會依序長成這樣：

看到沒？如果你不會讀這些區塊，你只會看到最後那句「已經幫你加了」——聽起來很爽，實際上你完全不知道它有沒有動對檔、有沒有寫錯 entity_id、有沒有把原本的自動化蓋掉。會讀的人可以在第 3 步 diff 就攔下錯誤，不必等 HA 出問題才回頭找。

這些區塊會不會占很多 context（會不會很花錢）

會。而且比你想的多。三種區塊都算 tokens（就是 AI provider 計費的單位）：

省 tokens 的三個原則（第 12 章會詳講）：

1. 只在需要深想的時候用 reasoning 模型。家用日常問題（「查一下今天天氣」「開客廳燈」）用非 reasoning 的 GLM-4-Flash 就好，快又便宜、還沒思考塊佔位。
2. 叫 AI 讀檔前先想它需不需要讀整份。如果只是要改一段，可以說「只讀第 X 到第 Y 行」，別讓它把整個 automations.yaml（可能幾千行）通通拉進 context。
3. 對話變太長就開新 session。前面累積的思考塊、工具輸出都會被帶進每一輪的 context，一路加下去 tokens 會爆。pi-web 底部有一個 contextUsage 指標（顯示 % used / contextWindow tokens）——本版沒有明文的黃／紅門檻，建議自己抓 60% 就準備新 session、80% 一定要開新的，不要撐到 100% 才被 provider 拒單。

關掉思考塊顯示（純看答案）

有些人覺得思考塊很吵、佔畫面又看不習慣，想關掉。老實說：截至本文寫作時的 pi-web 0.8.4（本教學 pin 的版本），沒有 UI 開關可以直接隱藏思考塊——它預設就已經是收起的（左邊 ▶ 那個），除非你點開否則本來就不佔位。想更進一步做視覺化淨化，只有兩條路：

• 回到 第 6 章把 model entry 的 reasoning 勾勾拿掉——這樣 pi-web 就不會把思考內容當獨立區塊 render 出來，會直接吞掉。缺點：GLM-4.6 這種模型即使你關掉顯示，provider 那邊還是照算 reasoning_content 的 output tokens，錢一樣付。
• 直接換非 reasoning 模型——把模型下拉切到 GLM-4-Flash、GPT-4o、Claude Haiku 3.5、Kimi K2-Instruct 那類，AI 根本不會想、也沒思考塊。這才是唯一真正省 tokens 的做法。

另一種折衷：把「重要的深度問題」跟「日常快問快答」分兩個 session 用不同模型。深度那個開 GLM-4.6 展開思考塊看它推理；日常那個用 GLM-4-Flash 秒答不留過程。這樣兩邊都爽。

常見卡關

1. 思考塊點不開、按了沒反應

   先看 AI 有沒有跑完——右下角的送出鈕如果還在轉圈，代表答案還在生，思考塊要等它結束才會可展開。等它跑完還是點不開，按 F12 開瀏覽器 devtools 看 Console 有沒有紅字。九成是瀏覽器擴充套件擋 JS，試無痕視窗（Incognito）看看有沒有解。

2. 工具卡片顯示 error（紅燈）

   展開卡片看 output 欄位的錯誤訊息（pi-web 內部欄位叫 isError）。常見原因：檔案路徑錯（AI 拼錯 /config/automations.yaml 或缺前面的斜線）、bash 指令 exit ≠ 0（權限不夠、指令找不到）、edit 的 old_string 對不上原檔（AI hallucinate 了一段不存在的行）。看到訊息後回覆 AI「這個 tool 失敗了，訊息是⋯⋯，改用別的方式」，讓它重試。

3. Diff 貼上去對不齊、YAML 縮排錯

   pi-web 的 diff render 有時候有 whitespace 顯示問題（tab 跟 space 看起來一樣但貼出去差很多）。解法：叫 AI 「請重新輸出完整檔案內容而不是 diff」，然後整份複製貼上取代。或叫它用 write／edit 工具直接寫進去，避開你手動複製這一步。

4. 我明明選了 GLM-4.6 為什麼沒有思考塊

   去 Models 面板檢查 provider 的 thinkingFormat 有沒有設 zai（第 6 章教過的欄位）。沒設或設錯的話，pi-web 收得到思考內容但不知道要拆出來顯示，就會全部塞進正式答案裡或者直接吃掉。改完 provider 設定要新開一個 session 才會生效。

5. 工具卡卡在「Running⋯⋯」轉圈很久

   大部分工具幾秒內會結束，超過 30 秒還在轉的話通常是 bash 指令跑太久（find /、ffmpeg 這種）或 read 一個超大檔（read 有 max lines 限制但真的 GB 級檔還是會慢）。pi coding agent 本身沒有內建 web_fetch 工具，所以「網頁抓不下來」在原生 7 支工具裡不會發生——除非你另外裝了 skill 加進來，那就要看那顆 skill 的實作。點卡片右上角有時候有 Cancel 按鈕；沒有的話重新整理頁面（Session 會保住不會不見，只是那次 tool call 會標記 isError）。

6. Diff 一直都不出現，AI 只給我一段程式碼

   Diff 只有在「AI 認得出你原本檔案內容」時才會產生。如果你只丟一句「幫我寫一個 automation」而沒有貼原本的 automations.yaml，AI 沒有「舊版」可以對照，只能給你「新版全文」。想看 diff 就先把原檔貼進來當 baseline。

常見問題