手刻 Coding Agent 更好玩 - 使用 Pi Agent 玩通雲端地端模型取代 Claude Code

胡嘉璽

研究領域為LLM、Vibe Coding、Context Engineering、量子電腦、容器。喜歡旅遊、重訓、天文、物理、美食、爵士樂及貓咪。

聯絡方式：github/joshhu

第一篇 入門基礎
第1 章 認識Coding Agent 與Pi Agent
1-1 AI Agent 與 Coding Agent 
1-1-1 LLM 與代理人迴圈 
1-1-2 工具呼叫 
1-1-3 Coding Agent 
1-2 Pi Agent：極簡的 Coding Agent
1-2-1 極簡 Harness 的設計理念 
1-2-2 內建工具與實際運作 
1-2-3 客製化路線 
1-3 與 Claude Code 的差異 
1-3-1 刻意不內建的功能 
1-3-2 取捨與適用情境 
1-4 本書的模型路線 
1-4-1 三條雲端路線 
1-4-2 兩條地端路線 
1-4-3 認證與計費的兩種模式 
1-5 本章小結
第2 章 安裝與第一次啟動
2-1 安裝 Pi 
2-1-1 Node.js 環境準備 
2-1-2 五種安裝方式 
2-1-3 安裝與驗證 
2-2 第一次啟動 
2-2-1 啟動畫面解析 
2-2-2 完整快速鍵清單 
2-2-3 認識 ~/.pi/agent 目錄 
2-3 用 ChatGPT 訂閱登入 
2-3-1 /login 流程 
2-3-2 確認可用模型 
2-3-3 憑證存放與登出 
2-4 第一個任務 
2-4-1 練習專案 
2-4-2 摘要任務 
2-4-3 修改任務與 diff 
2-5 本章小結 
第3 章 TUI 介面與互動操作
3-1 讀懂 TUI 畫面 
3-1-1 狀態列逐項解讀 
3-1-2 訊息區的訊息型態 
3-1-3 思考等級與編輯器邊框 
3-2 編輯器輸入技巧 
3-2-1 @ 檔案參照 
3-2-2 多行輸入與貼上圖片 
3-2-3 用 ! 與 !! 執行 shell 指令 
3-2-4 Ctrl+G 外部編輯器 
3-3 斜線指令與按鍵綁定 
3-3-1 斜線指令總覽 
3-3-2 /hotkeys 與自訂按鍵綁定 
3-4 執行中的流程控制 
3-4-1 Steering 與 Follow-up 的差別 
3-4-2 插話：邊做邊修正 
3-4-3 Follow-up 與中斷取回 
3-4-4 派送模式與自動重試 
3-5 本章小結 
第4 章 模型切換與思考等級
4-1 供應商與模型的組織 
4-1-1 用 --list-models 盤點 
4-1-2 模型的完整識別 
4-1-3 已設定供應商的邊界 
4-2 切換模型的三種方式 
4-2-1 啟動參數指定 
4-2-2 /model 選單 
4-2-3 Ctrl+P 循環與 /scoped-models 
4-3 思考等級 
4-3-1 七級與 token 預算 
4-3-2 循環切換的行為 
4-3-3 模型支援的差異 
4-4 模型使用策略 
4-4-1 預設模型與預設等級 
4-4-2 任務與模型的搭配 
4-5 本章小結 
第2 篇 Session 與 Context
第5 章 Session 管理與匯出分享
5-1 Session 的儲存
5-1-1 目錄結構與 JSONL 
5-1-2 sessionDir 與備份 
5-2 接續與管理 
5-2-1 pi -c 與 /resume 挑選器 
5-2-2 /name、/session 與 /new 
5-2-3 --no-session 臨時模式 
5-2-4 用 CLI 旗標精準指定 session 
5-3 匯出與分享 
5-3-1 /export 與 /copy 
5-3-2 /share 上傳 gist 
5-3-3 /import 匯入接續 
5-4 JSONL 格式解析 
5-4-1 entry 的結構 
5-4-2 主要 entry 型態 
5-5 本章小結 
第6 章 Session 樹與分支
6-1 對話樹的形成 
6-1-1 active leaf 與分支 
6-1-2 分支的兩種來源 
6-1-3 分支只影響對話，不影響檔案 
6-2 /tree 導覽 
6-2-1 樹的檢視與移動 
6-2-2 篩選模式 
6-2-3 Shift+L 標籤 
6-2-4 樹狀檢視的實用組合 
6-3 /fork 與 /clone 
6-3-1 三者比較 
6-3-2 /fork 從舊訊息開新 
6-3-3 /clone 複製分支 
6-3-4 一個完整的分支工作流 
6-4 分支摘要與快捷 
6-4-1 切換分支的摘要 
6-4-2 doubleEscapeAction 
6-5 本章小結 
第7 章 Context 與 Compaction
7-1 Context Window 的極限
7-1-1 什麼是Context Window 
7-1-2 觸發壓縮的條件 
7-2 手動與自動壓縮 
7-2-1 /compact 手動壓縮 
7-2-2 自動壓縮的切割點 
7-2-3 CompactionEntry 與摘要格式 
7-2-4 控制Context 的三種策略 
7-3 context 檔案 
7-3-1 AGENTS.md 與 CLAUDE.md 
7-3-2 SYSTEM.md 與 APPEND_SYSTEM.md 
7-4 本章小結 
第3 篇 雲端與地端模型
第8 章 GPT-5.6 打造記帳 Web App
8-1 GPT-5.6 模型家族 
8-1-1 Sol、Terra、Luna 三級 
8-1-2 切換與計費 
8-2 實戰：記帳 Web App 
8-2-1 需求 prompt 與規劃 
8-2-2 後端 API 與 SQLite 
8-2-3 前端統計與圓餅圖 
8-2-4 用 steering 追加 CSV 匯出 
8-2-5 瀏覽器驗收 
8-3 本章小結 
第9 章 Nemotron 3 Ultra 打造台鐵時刻 CLI
9-1 NVIDIA NIM 與 Nemotron 3 Ultra
9-1-1 NIM 微服務與模型定位 
9-1-2 金鑰申請與 Pi 設定 
9-2 實戰：台鐵時刻查詢 CLI 
9-2-1 無金鑰的官方開放資料 
9-2-2 需求 prompt 與規劃 
9-2-3 實作與自我修正 
9-2-4 情境驗證 
9-3 開放權重模型的取用管道 
9-3-1 三類代管服務 
9-3-2 自訂供應商與自行架設 
9-4 本章小結 
第10 章 GLM 5.2 與其他雲端供應商
10-1 GLM 5.2 開放權重程式模型 
10-1-1 模型與授權 
10-1-2 取用管道與 GLM Coding Plan 
10-2 實測：記帳專案的程式碼審查 
10-2-1 審查任務的下法 
10-2-2 審查結果 
10-2-3 用量與計費觀察 
10-3 雲端供應商總覽 
10-3-1 金鑰即開關 
10-3-2 供應商對照表 
10-3-3 各家特色 
10-3-4 申請與驗證 
10-4 憑證管理的優先序 
10-4-1 --api-key 與 /login 
10-4-2 auth.json 的兩種憑證 
10-4-3 金鑰保管守則 
10-5 本章小結 
第11 章 地端模型與 vLLM
11-1 地端模型的價值 
11-1-1 三個理由 
11-1-2 硬體門檻 
11-2 vLLM 推論伺服器 
11-2-1 主機端啟動與驗證 
11-2-2 models.json 註冊 
11-2-3 接上 Pi 
11-2-4 Ollama 與 LM Studio 總覽 
11-3 實戰：統一發票對獎工具 
11-3-1 資料來源與對獎規則 
11-3-2 需求與建置 
11-3-3 六種情境實測 
11-4 地端與雲端的正面對決 
11-4-1 同題實測 
11-4-2 取捨總表 
11-5 本章小結 
第12 章 MLX 與 Apple Silicon
12-1 MLX 與統一記憶體 
12-1-1 統一記憶體的優勢 
12-1-2 MLX 與 mlx-lm 
12-2 模型下載與伺服器 
12-2-1 下載模型 
12-2-2 mlx_lm.server 
12-2-3 記憶體實況 
12-3 接上 Pi 
12-3-1 mlx 供應商設定 
12-3-2 冷熱請求實測 
12-3-3 常見狀況 
12-4 實戰：全程離線的單字卡 CLI 
12-4-1 斷網與證據 
12-4-2 離線建置 
12-4-3 離線實測 
12-4-4 審視與修正 
12-5 單機與區網的分工 
12-5-1 性質對照 
12-5-2 並存的用法 
12-6 本章小結 
第13 章 models.json 進階
13-1 models.json 的結構
13-1-1 供應商欄位 
13-1-2 模型欄位與預設值 
13-1-3 載入與錯誤 
13-2 金鑰與 header 的三種解析 
13-2-1 環境變數插值 
13-2-2 用 shell 指令取金鑰 
13-2-3 金鑰該放哪裡 
13-3 thinkingLevelMap 與 compat 
13-3-1 三個模型的實測對照 
13-3-2 compat 相容性旗標 
13-4 覆寫內建供應商 
13-4-1 baseUrl 走代理 
13-4-2 modelOverrides 
13-4-3 還原設定 
13-5 本章小結 
第4 篇 客製化
第14 章 settings.json 與主題
14-1 兩層設定檔 
14-1-1 專案信任 
14-1-2 合併結果驗證 
14-2 /settings 與常用設定 
14-2-1 模型與思考的進階設定 
14-3 終端機與圖片 
14-3-1 圖片相關設定 
14-3-2 行內顯示實測 
14-3-3 阻擋圖片送出 
14-4 網路與傳輸 
14-4-1 遙測與更新檢查 
14-5 主題的結構 
14-5-1 載入位置與格式 
14-5-2 顏色 token 與色值 
14-5-3 資源陣列與色票 
14-6 打造自訂主題 
14-6-1 複製與改色票 
14-6-2 切換前後對照 
14-6-3 熱重載與退回機制 
14-7 匯出配色 
14-7-1 預設推導配色 
14-7-2 指定匯出配色 
14-8 本章小結 
第15 章 提示範本與技能
15-1 提示範本 
15-1-1 第一個範本 
15-1-2 參數佔位符號 
15-1-3 專案層範本 
15-2 技能 
15-2-1 SKILL.md 的寫法 
15-2-2 漸進式載入 
15-2-3 /skill 指令與強制載入 
15-3 兩組技能實戰 
15-3-1 需求轉規格 
15-3-2 測試優先實作 
15-3-3 繁中 commit message 
15-3-4 驗證與除錯 
15-4 範本、技能與擴充功能的分工 
15-4-1 三者對照 
15-4-2 觸發方式的差異 
15-5 本章小結 
第16 章 現成技能庫
16-1 兩個技能庫 
16-1-1 取向與出處 
16-1-2 收錄的技能 
16-2 兩種安裝方式 
16-2-1 clone 進共用目錄 
16-2-2 settings 指定路徑 
16-2-3 啟動驗收 
16-3 brave-search：補上網路搜尋 
16-3-1 腳本與準備工作 
16-3-2 觸發與實測 
16-4 文件四件組 
16-4-1 品質規定與環境準備 
16-4-2 xlsx 實測 
16-4-3 pdf 實測與延伸 
16-5 skill-creator：用技能產生技能 
16-5-1 產生 inv-check 技能 
16-5-2 產出品質檢驗 
16-6 挑選與安全 
16-6-1 安裝前審閱 
16-6-2 控制載入數量 
16-7 本章小結 
第17 章 套件生態系：現成的都在 npm 上
17-1 社群補上的功能 
17-1-1 官方藝廊 
17-1-2 從 npm 直接搜尋 
17-1-3 安裝前的審閱 
17-2 安裝與管理 
17-2-1 三種安裝來源 
17-2-2 安裝位置與資源載入 
17-2-3 移除與更新 
17-2-4 先試用再決定 
17-3 必裝一：pi-mcp-adapter 
17-3-1 MCP 協定 
17-3-2 接上 MCP 伺服器 
17-3-3 模型呼叫實測 
17-4 必裝二：pi-web-access 
17-4-1 搜尋服務與金鑰 
17-4-2 版本查證實測 
17-5 必裝三：pi-subagents
17-5-1 子代理人的分工 
17-5-2 平行審查實測 
17-5-3 隨附的指令範本 
17-6 其他熱門套件 
17-6-1 下載量排行 
17-6-2 現成與手刻的取捨 
17-7 只載入需要的資源 
17-7-1 過濾語法 
17-7-2 用 pi config 逐項開關 
17-8 團隊上手 
17-8-1 專案層安裝 
17-8-2 信任與自動安裝 
17-9 發佈自己的套件 
17-9-1 套件結構 
17-9-2 打包與本機驗證 
17-9-3 同名資源的優先順序 
17-9-4 技能實測與版本演進 
17-9-5 相依套件的三個層次 
17-10 本章小結 
第18 章 擴充功能入門
18-1 擴充功能是什麼 
18-1-1 取得與生效方式 
18-1-2 兩類能力 
18-1-3 官方範例與安全 
18-2 事件系統 
18-2-1 四類事件 
18-2-2 tool_call 的三條規則 
18-2-3 tool_result 修改結果 
18-2-4 ctx 的互動能力 
18-3 第一個擴充功能：危險指令攔截 
18-3-1 兩級處置的設計 
18-3-2 自訂工具：模型的第五個工具 
18-3-3 三個擴充功能的安裝 
18-4 載入位置與測試 
18-4-1 自動探索位置 
18-4-2 用 -e 快速測試 
18-4-3 settings 指定與排查 
18-5 攔截實測 
18-5-1 高危：直接攔截 
18-5-2 中危：確認框 
18-5-3 /guard 指令 
18-6 熱重載 
18-6-1 新規則實測 
18-6-2 兩種載入方式都能重載 
18-7 第四篇的整合目標 
18-7-1 路線總表 
18-7-2 判斷準則 
18-8 本章小結 
第19 章 擴充功能實戰
19-1 檢查點的設計 
19-1-1 為什麼在 turn_start 建立 
19-2 四種註冊方法 
19-2-1 安裝與日常操作 
19-3 檢查點實測 
19-3-1 讓模型改壞程式 
19-3-2 測試門檻擋下 commit 
19-3-3 還原到檢查點 
19-4 手動檢查點與旗標 
19-4-1 三種對話框的取消行為 
19-4-2 widget 與狀態列的分工 
19-5 測試門檻的使用限制 
19-5-1 同步執行的代價 
19-5-2 測試指令的客製 
19-6 檢查點的邊界 
19-6-1 兩個擴充功能的分工 
19-6-2 開發過程的兩個錯誤 
19-6-3 什麼時候該用檢查點 
19-7 本章小結 
第20 章 oh-my-pi：把 IDE 接進來的 Coding Agent
20-1 omp 的定位與規模 
20-1-1 從 Pi 分出來的路線 
20-1-2 內建工具與收納機制 
20-1-3 工具的基準測試 
20-2 安裝與並存 
20-2-1 安裝與設定精靈 
20-2-2 歡迎畫面與設定繼承 
20-2-3 與 Pi 並存 
20-2-4 模型角色與額度 
20-3 檔案操作的底層設計 
20-3-1 hashline 編輯 
20-3-2 摘要式讀取 
20-3-3 Rust 原生模組 
20-4 內部資源的 URL 介面 
20-4-1 十二種內部網址 
20-4-2 讀取 GitHub PR 
20-4-3 解決合併衝突 
20-4-4 讀取子代理人結果 
20-5 IDE 級能力 
20-5-1 LSP 跨檔案重新命名 
20-5-2 DAP 除錯整合
20-5-3 eval 常駐執行環境 
20-5-4 ast_edit 結構化編輯 
20-6 多代理與規則 
20-6-1 task 子代理人 
20-6-2 advisor 顧問模型 
20-6-3 TTSR 串流規則 
20-6-4 用 /omfg 產生規則 
20-6-5 /review 與 orchestrate 
20-7 context 與記憶 
20-7-1 snapcompact 圖像壓縮 
20-7-2 壓縮後的回讀 
20-7-3 mnemopi 記憶系統 
20-8 對外連線與協作 
20-8-1 web_search 網路搜尋 
20-8-2 browser 瀏覽器控制 
20-8-3 /collab session 分享 
20-8-4 omp commit 原子拆分 
20-9 Pi 與 omp 的選擇 
20-9-1 取捨對照 
20-9-2 分工建議 
20-10 本章小結 
第5 篇 安全與進階應用
第21 章 安全模型與沙箱隔離
21-1 Pi 的安全模型 
21-1-1 沒有內建沙箱 
21-1-2 專案信任的範圍 
21-1-3 信任機制的作用邊界 
21-2 威脅模型 
21-2-1 prompt injection 實測 
21-2-2 為什麼 Pi 防不住 
21-2-3 什麼時候需要隔離 
21-3 隔離方式比較 
21-3-1 適用情境對照 
21-3-2 不能同時使用 
21-4 作業系統層級的沙箱 
21-4-1 安裝與規則設定 
21-4-2 檔案越界測試 
21-4-3 網路越界測試 
21-4-4 這個方案的缺口 
21-5 Gondolin micro-VM
21-5-1 安裝與啟動 
21-5-2 工具在哪裡執行 
21-5-3 workspace 的雙向性 
21-6 容器隔離 
21-6-1 建置映像 
21-6-2 掛載與金鑰 
21-7 OpenShell 政策沙箱 
21-7-1 gateway 與沙箱 
21-7-2 推論閘道：金鑰不進沙箱 
21-7-3 專案檔案的進出 
21-8 本章小結 
第22 章 SDK 實戰：AI 寫作助手 Web App
22-1 SDK 的架構 
22-1-1 隨主套件附帶 
22-1-2 四個核心物件 
22-1-3 憑證的解析順序 
22-2 最小代理人 
22-2-1 建立 session 與訂閱事件 
22-2-2 模型與工具的指定 
22-2-3 事件總覽 
22-3 SessionManager 
22-3-1 in-memory 與持久化 
22-3-2 清單與樹狀操作 
22-4 範例八：規劃與建置 
22-4-1 功能規劃 
22-4-2 devkit 升級到 1.1.0 
22-4-3 交給 Pi 建置 
22-5 用 ResourceLoader 載入 devkit
22-5-1 載入與隔離 
22-5-2 範本的程式化展開 
22-6 網頁實測 
22-6-1 潤稿 
22-6-2 摘要 
22-6-3 工具事件與串流 
22-6-4 結構建議 
22-7 依實測結果調整 
22-7-1 三個修正 
22-7-2 重測驗證 
22-8 處理紀錄與 session 檔 
22-8-1 紀錄頁 
22-8-2 session 檔解剖 
22-9 本章小結 
第23 章 RPC 與 JSON 模式
23-1 四種執行模式 
23-1-1 一個核心、四種介面 
23-1-2 print 模式回顧 
23-2 JSON 事件流 
23-2-1 事件流的輸出 
23-2-2 用 jq 萃取重點 
23-3 範例九：早報的規劃與資料源 
23-3-1 成品規劃 
23-3-2 氣象署的開放資料 
23-3-3 排程資料源的鐵則 
23-4 早報產線 
23-4-1 任務書 
23-4-2 產線腳本 
23-4-3 事件流就是現場 
23-4-4 成品驗收 
23-5 launchd 排程 
23-5-1 排程描述檔 
23-5-2 載入與實測 
23-6 RPC 模式 
23-6-1 指令、回應與事件 
23-6-2 framing 與子協定 
23-7 RPC 實戰：手機遙控器 
23-7-1 架構與實作 
23-7-2 手機實測 
23-7-3 忙碌中的行為 
23-8 本章小結 
第24 章 自訂供應商與 TUI 元件
24-1 供應商的擴充功能路線 
24-1-1 三種模式 
24-1-2 覆寫實測 
24-1-3 新供應商與動態探索 
24-1-4 移除與還原 
24-2 OAuth 與 /login 整合
24-2-1 家庭閘道的情境 
24-2-2 供應商的 oauth 欄位 
24-2-3 /login 實測 
24-2-4 憑證的存放與流向 
24-3 streamSimple 自訂串流 
24-3-1 事件序列 
24-3-2 運勢籤供應商 
24-3-3 context 溢位的正規化 
24-4 pi-tui 午餐抽籤 
24-4-1 元件系統 
24-4-2 抽籤選單實作 
24-4-3 實測 
24-5 三條路線的整合 
24-5-1 同時載入 
24-5-2 發佈給全隊 
24-6 本章小結 
第25 章 跨平台與終端機調校
25-1 Windows 與 WSL 
25-1-1 bash 從哪裡來 
25-1-2 WSL 與 Windows Terminal 
25-2 Android Termux 
25-2-1 安裝來源與步驟 
25-2-2 環境特性與限制 
25-3 從原始碼建置 
25-3-1 取得與建置 
25-3-2 從原始碼執行與 /debug 
25-3-3 測試與參與開發 
25-4 本章小結 
結語