第一篇 入門基礎
第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 本章小結?
結語?

序言

Coding Agent 在過去兩年改變了軟體開發的生態系： 你描述要什麼，Coding Agent 讀取檔案、撰寫程式、執行指令、修正錯誤，直到做出成果，幾乎讓工程師置身事外。市面上的主流選擇是Claude Code 這類大而全的產品，功能齊全、整合度深，但你總是得照著它的規矩來開發，有時還會「降智」或是「停用」。是它替你決定了大部分的事。很多人一開始使用Claude Code 會安裝大量的Agent Skill 及MCP，但在使用長時間後，就會開始刪，因為真正最適合的東西不見得要又多又腫。

?

在使用Claude Code 這一類的Coding Agent 之後，一直有一個想法，就是有沒有一個極簡的小小Agent，只要具備基本的Read、Write、Edit、Bash 工具，其它要用的工具，用外掛的方式裝入，例如Agent Skill，而更多的功能如MCP，Sub Agent 等，在需要的時候再加入，甚至不同的Agent 可以使用不同廠商、雲端、地端的模型，這樣不就是一個極簡，完全為自己量身打造訂製Coding Agent 嗎？

?

Pi Agent 就是你夢寐以求的這種工具，像樂高積木一樣給你基本的模組，可以蓋出各種多彩多姿的大樓！ Pi Agent 採取另一種設計：核心只有四個工具，其餘一切（MCP、子代理人、權限控管、計畫模式）都留給使用者用技能、擴充功能與套件自己補上。這個設計把「工具該有什麼」的決定權還給你，也是書名「手刻更好玩」的由來：這本書的內容就是組裝一套屬於自己的工作環境。

?

本書的功能就是親手把這個量身訂做的Coding Agent 建立起來的過程，每一個功能都先實際操作過。一開始你會因為它的功能過於簡單而擔心，但當你慢慢加上Extensions、Packages、Agent Skills 之後，你會發現開發一個應用程式，竟然每一個過程、元件、想法、實作都是為這個應用程式完全符合，就是一個「剛剛好」的哲學，讓Pi Agent 成為開放社群最被大家喜歡的Coding Agent。開放社群還有一個Opencode，但走的路線是Claude Code 的大而全，反而不是想要自己手刻的首選。

?

另外最棒的就是跨模型廠商的應用， 雲端用GPT-5.6 與550B 參數的Nemotron 3 Ultra，地端用120B 的vLLM 部署與Apple Silicon 上的MLX，你在書裡看到的能力就是這些工具的真實水準。當然如果你有購買任何廠商的APIKey，那就是連Claude、Gemini、甚至最紅的Kimi-k3、DeepSeek、GLM-5.2 都非常通用，而且讓這些模型一起幫你工作，不必受限於某一個廠商。如果你是公司要部署私有雲，那麼開放權重社群的巨量地端模型更可以搭配使用。

?

你只要有一台能開啟終端機的電腦（本書以macOS 為主要環境，Windows與Linux 的差異在第二十五章介紹）、Node.js 環境、一個ChatGPT Plus 或Pro訂閱帳號。NVIDIA NIM 與其他雲端供應商的金鑰都能免費使用，筆者建議是macOS，你會操作起來更方便。

?

Coding Agent 好用讓大家開始思考自己手刻的可能性，但真的要從頭開始，必須熟悉Deep Agent、LangChain、LangGraph 這一類的框架，如果想要有更高效的Coding Agent，你可能還需要具備開發Rust 的能力，但手刻的好玩不必重新造輪子，樂高積木的方式反而適中，我自己是在整個過程中玩的非常開心，希望能和你分享這個樂趣。

?

胡嘉璽

2026/07/20

於三總汀州院區W616 病房