RELEASE NOTES · 2026-10-21
Pi 1.2–1.4 更新要點
Pi 在兩週內連續釋出了三個小版本：1.2.0（2026 年 10 月 12 日）、1.3.0（10 月 15 日）和 1.4.0（10 月 21 日）。本頁依據官方 Changelog 與固定版本文件整理，核驗日期為 2026-10-28。逐項英文變更保留在版本檔案。
三個版本都沒有改變本書課程的基本操作。只用內建功能、不寫擴充功能（Extension）的讀者，升級後照常使用即可；寫過擴充功能、自定義主題或改過 models.json 的讀者，需要看下面的「升級時要處理的變化」。
三個版本各改了什麼
| 版本 | 值得關注的變化 | 對使用者的影響 |
|---|---|---|
| 1.2.0 | 設定檔案可宣告 $schema | 編輯 settings.json、models.json 時，編輯器能提示欄位並檢查寫法 |
| 1.2.0 | before_agent_start 事件範圍擴大 | 擴充功能作者需要檢查，詳見下文 |
| 1.2.0 | PI_CLIPBOARD_OSC52=1 | Pi 識別不出遠端工作階段時（例如從另一臺電腦接入 tmux），設定後複製的文字也能回到本地剪貼簿 |
| 1.3.0 | 恢復工作階段保留原來啟用的工具 | 中途啟用的工具不會在 /resume 後消失 |
| 1.3.0 | --model 優先選擇已有憑據的提供商 | 多個提供商都有同名模型時，不再按目錄順序隨機落到沒登入的那一個 |
| 1.3.0 | 切換模型時丟棄舊模型的思考內容 | 新模型不再把上一個模型的推理當成自己的回覆繼續寫 |
| 1.3.0 | /share 可選擇上傳位置 | 新增 sessionShareDestination 設定，取值為 auto、gist 或 radius |
| 1.4.0 | 壓縮摘要按模型輸出上限生成 | 長推理不再讓壓縮以「generation hit the token cap」失敗 |
| 1.4.0 | 中文標點旁的粗體和斜體正常顯示 | 終端機和 HTML 匯出中，**粗體**緊挨全形標點時不再顯示成星號 |
| 1.4.0 | 多項 Windows 修復 | PowerShell 5.1 改寫安裝標記後 pi update 失敗、Windows 不裝在 C 盤時找不到 shell 等問題已修復 |
給設定檔案加上 $schema
1.2.0 起，官方在 https://pi.dev/schemas/ 釋出了設定、模型、按鍵和主題四份 Schema。在設定檔案第一行宣告它，VS Code 等編輯器就能補全欄位、提示說明，並標出拼錯的名稱：
{
"$schema": "https://pi.dev/schemas/settings.schema.json",
"quietStartup": "header"
}models.json 對應 models.schema.json，按鍵設定對應 keybindings.schema.json。這一行只給編輯器使用，不會改變 Pi 的行為。本書在 Pi 1.4.0 的獨立設定中加入這一行後啟動，沒有出現警告。
自定義主題的讀者要多做一步：主題 Schema 已遷到 https://pi.dev/schemas/theme.schema.json，啟動時載入的主題也會按 Schema 校驗。舊主題需要更新 $schema 地址、把複用的顏色放進 vars，並刪除不受支援的後設資料。沒寫過主題可以忽略。
升級時要處理的變化
| 版本 | 變化 | 需要做什麼 |
|---|---|---|
| 1.2.0 | before_agent_start 也會在擴充功能發起的執行前觸發：pi.sendMessage(..., { triggerTurn: true }) 在空閒時啟動的執行，同樣經過這個事件 | 只想處理使用者輸入的處理函式，要先判斷 event.messageType === "user"；"custom" 型別的事件沒有 prompt |
| 1.2.0 | 執行啟動期間視為忙碌：ctx.isIdle() 返回 false，pi.sendMessage() 排進正在啟動的執行，pi.sendUserMessage() 必須指定 deliverAs | 檢查依賴 isIdle() 判斷時機的擴充功能 |
| 1.2.0 | 主題 Schema 遷移，啟動時也做校驗 | 按上一節更新自定義主題 |
| 1.2.0 | pi mcp list --json 改為報告 resources: true，不再給出資源數量 | 解析這項輸出的指令碼需要調整 |
| 1.3.0 | kimi-coding 改用 Chat Completions 協議 | 在 models.json 覆蓋了它的 Base URL 時，地址必須以 /v1 結尾 |
| 1.4.0 | GitHub Copilot 預設模型從已下線的 gpt-5.4 改為 gpt-6.1-sol；小米預設模型改為 mimo-v2.6-pro | 設定裡寫死舊模型名的，改成新名稱或重新用 /model 選擇 |
| 1.4.0 | 擴充功能的 before_provider_headers 不再看到 OpenRouter、NVIDIA NIM 與 OpenCode 的來源標識請求頭 | 隻影響改寫請求頭的擴充功能；返回 null 仍可刪除對應請求頭 |
前兩項是官方標註的 Breaking Changes。本書提供的檢查擴充和工具清單擴充只註冊命令，不使用這些事件；檢查擴充已在 Pi 1.4.0 下重新安裝執行，通知正常。
恢復工作階段會保留哪些工具？
1.3.0 之前，在工作階段中途啟用的工具，恢復工作階段後可能消失。現在 /resume 或 pi --continue 會恢復工作階段當時啟用的工具；啟動時寫的 --tools +名稱／-名稱 在此基礎上增減。
下面三種寫法仍會整套指定工具，不沿用工作階段記錄：--tools 後面寫普通工具名、--no-tools、--no-builtin-tools。這與 Pi 1.1.0 的工具加減寫法規則一致。
做只讀審閱這類練習時，繼續在啟動命令裡寫明完整的只讀工具清單，不要依賴恢復工作階段的預設結果。
壓縮為什麼不再失敗
1.4.0 之前，壓縮摘要和分支摘要有固定的輸出上限。模型推理佔用較多時，摘要還沒寫完就觸頂，壓縮隨之失敗。現在摘要請求改用模型自身的輸出上限。
settings.json 中兩個壓縮設定的含義因此更清楚：
| 設定 | 預設值 | 含義 |
|---|---|---|
compaction.reserveTokens | 16384 | 剩餘上下文低於這個值時開始自動壓縮；不再限制摘要長度 |
compaction.keepRecentTokens | 20000 | 最近這部分內容原樣保留，不進入摘要 |
兩個預設值來自 Pi v1.4.0 固定設定文件。壓縮的整體機制見上下文與壓縮；本課的建議不變，日常使用保持預設值即可。
升級後怎樣核對？
先記錄當前 pi --version，再按生命週期管理中與原安裝方式一致的路徑升級。升級後在普通終端機執行：
pi --version復現本頁對應版本時應顯示 1.4.0；以後直接更新到最新版，可能顯示更高版本，需要繼續查對應日誌。進入 Pi 後，按登入與模型設定做一次無工具連通測試，再確認常用擴充功能能載入、需要的 MCP 伺服器能連接。
2026-10-28，本書在獨立 npm 字首與獨立設定中，用 Pi 1.4.0 重新走了這些課程的實測步驟：
- 安裝並啟動 Pi：版本輸出、全屏啟動、退出和再次啟動。
- 登入與模型設定、從練習目錄開始：
/login、/model、/settings選單和無工具連通測試。 - 更新、退出登入與解除安裝：從 1.1.0 更新到 1.4.0，以及更新後的遷移提示。
- 擴充自己的 Pi：本地包（Package）的安裝、載入和移除。
- 子代理（Subagent）：最小委派復現。
各頁的具體範圍和未實測部分，寫在該頁末尾的核驗說明中。升級後若模型、擴充或 MCP 異常，先保留錯誤與原設定，再按故障排查一次檢查一項。