【2026 最新】Pizza Bot 教學：用 Agent Inbox 管理長任務、完成通知與人工批准

Pizza Bot 教學先講最重要的邊界：它能讓你離開聊天畫面後，繼續在背景處理長任務；但真正工作的 api-server（後端服務）必須保持運行。若後端就在這台筆電，完全退出桌面程式、停止後端或關機都會中止進行中的工作；若 client 連的是另一台常開主機，筆電離線則不會關掉遠端後端。

Pizza Bot 把 Agent 工作做成一個「收件匣」：任務完成後進 Unread，需要人類批准或補充答案時進 Action。這篇以 2026 年 9 月 19 日發布的 v1.1.0 為準，從下載驗證、模型設定、第一個唯讀任務，一路做到 Skill／MCP、斷線演練、備份與移除；專為第一次接觸 Agent runtime 的讀者寫，不要求你先懂 LangGraph。

Pizza Bot 是什麼？先把它想成 Agent Inbox

一句話記法：Pizza Bot ＝長任務 Thread ＋ checkpoint ＋ Unread／Action 收件匣。Thread 裝工作，checkpoint 保存可回看的狀態，兩個佇列則把「看結果」與「做決定」分開。

傳統同步聊天常讓人留在同一條對話等結果；Pizza Bot 則把每條 Thread 當成可持續的工作單元。短暫斷線後，同一個後端可重播仍保留的事件；重新開啟持久 Thread 時，則能從已落盤的 checkpoint 還原狀態。這是 AI Agent Harness 的一種具體產品形態：模型負責推理，後端保存 checkpoint，Inbox 負責讓人知道下一步該看結果，還是做決定。

• All：全部 Thread。
• Unread：完成、失敗或中斷後，等待你回來查看的工作。
• Action：Agent 已暫停，等待你批准、修改、拒絕或回答的工作。

它也不是單純取代 Linear、Jira 或 Trello。團隊 ticket tracker 的重點是負責人、狀態與共同紀錄；Pizza Bot 的重點是自架、自備模型供應商的通用 Agent 執行與批准收件匣。兩者可以重疊，也可以讓 ticket 系統成為 MCP 工作來源。若你要的是跨裝置但仍綁定單一供應商的協作 Thread，可再比較 Claude Code Projects 雲端 Thread。

Pizza Bot 教學第一關：下載正確版本並核對 SHA-256

先從官方 GitHub Release 下載一個符合平台的安裝檔，以及同頁的 SHA256SUMS。v1.1.0 提供 macOS x64／arm64 的 DMG、ZIP，Windows x64 Setup.exe，以及 Linux x64／arm64 的 deb、rpm。macOS 版本已簽章與 notarize；這一版 Windows 安裝檔與 Linux 套件未簽章，因此 checksum 特別重要。

只驗證你實際下載的檔案，不要直接對缺少其他八個安裝檔的整份清單執行檢查。Apple Silicon Mac 範例如下：

grep '  pizza-bot-oss-1.1.0-macos-arm64.dmg$' SHA256SUMS \
  | shasum -a 256 -c -

Linux 把最後一段換成 sha256sum -c -，並換成你下載的 deb 或 rpm 檔名。Windows PowerShell 可用：

$file = 'pizza-bot-oss-1.1.0-windows-x64-setup.exe'
$expected = (Select-String "$file$" .\SHA256SUMS).Line.Split()[0]
$actual = (Get-FileHash ".\$file" -Algorithm SHA256).Hash.ToLower()
$actual -eq $expected

結果必須是 OK 或 True 才繼續。checksum 能抓出下載損壞或檔案不一致，但不等於第三方安全稽核。安裝後也要自己追蹤 Releases；v1.1.0 發行文件明確寫明尚未設定自動更新。

需要隔離資料？用獨立 PIZZA_DATA_ROOT

安裝版預設把資料放在 ~/.pizza-bot-oss。想做不碰正式資料的實驗，最清楚的方法是從 v1.1.0 原始碼啟動，並指定另一個資料根目錄；這條路需要 Node.js 24 以上。macOS／Linux shell：

git clone --branch v1.1.0 --depth 1 https://github.com/pizza-bot-app/pizza-bot.git
cd pizza-bot
npm install
npm run build
PIZZA_DATA_ROOT="$HOME/pizza-bot-lab" npm run dev

Windows PowerShell 前四行相同，最後改成：

$env:PIZZA_DATA_ROOT = "$HOME\pizza-bot-lab"
npm run dev

依照官方 local data 文件，這個目錄會容納 Thread、checkpoint、記憶、附件、Skill、Plugin、MCP 設定與 logs。請不要同時讓兩個 backend 共用同一份 SQLite 資料根目錄。只想用打包好的桌面版則不需要另裝 Node.js；從原始碼第一次執行 npm run dev 時，若系統沒有可用瀏覽器或快取，predev 可能下載鎖定版 Chrome for Testing，需保持網路連線。

設定模型：雲端供應商或 Ollama

進入 Settings → Providers。官方目前支援 Amazon Bedrock、Anthropic、Google Gemini、OpenAI、OpenRouter 與 Ollama。桌面內建後端可以在設定頁輸入憑證；若是獨立後端，應把密鑰放在後端主機的環境變數或資料根目錄下的 .env.local，UI 只填 ${ENV_VAR} 參照，避免把真正密鑰寫進設定或 shell history。變更 .env 或 .env.local 後，要重新啟動 Pizza Bot／獨立後端才會載入。

想先用本機模型，先啟動 Ollama App／服務；沒有常駐服務的環境可在終端 A 執行 ollama serve。再到終端 B 下載模型並確認 daemon 可連、模型已存在：

ollama pull <model-name>
ollama ls

回到 Pizza Bot 選 Ollama；預設 host 是 http://localhost:11434，其中 localhost 指的是 api-server 所在主機。若 Pizza Bot 後端在遠端，Ollama 也必須在那台主機上運行或可由它連到。模型選型要配合硬體；若後面要做 Skill／MCP 委派，請選 Ollama metadata 有宣告 tools 能力的模型。反過來，使用雲端模型時，prompt、模型輸入輸出與被要求的附件會送往你設定的供應商；「local-first」只表示伺服器與應用狀態預設在本機，不代表資料必然離線。

Pizza Bot 教學實作：完成第一個唯讀背景任務

先建立一個只放測試資料的資料夾，例如三份不含個資的會議筆記。到 Settings → Files 加入這個資料夾，保留預設的 read-only。Pizza Bot 不會自動取得整個 home directory；授權後，資料夾會以 /local/<folder-id>/ 形式出現在 Agent 的檔案系統。模型或 MCP 工具仍可能把可讀內容帶入請求，因此授權前要檢查整個資料夾。

這個 UI 流程直接適用桌面內建後端。若使用 standalone backend，授權路徑指的是後端主機；本機資料夾設定 API 預設關閉。管理者要在一次管理 session 以 PIZZA_ALLOW_LOCAL_FOLDER_CONFIGURATION=1 啟動、加完 grant，再關掉 flag 並重啟後端。

建立 New Thread，貼上這個可檢查輸出的 prompt：

只讀取我剛授權的測試資料夾，不要建立、修改或刪除任何檔案。
1. 列出看到的檔名。
2. 每份文件用一句話摘要。
3. 整理三個共同主題，並在每點後標註依據的檔名。
4. 如果資料不足，直接說不知道。

送出後先看對話串的 streaming 狀態；Activity 只有在 ready Skill 被委派時才會出現子任務。接著切換到另一個 Thread，並停留在那裡直到測試任務結束。短暫重連會用 since 重播後端緩衝區仍保留的事件，再繼續接 live stream；重新開啟持久 Thread 時可從 checkpoint 還原狀態，但這不是永久、完整的 event log。桌面內建後端先用「切換 Thread」測試，不要按 Quit，因為退出桌面程式會一併停止它管理的後端。

當結果出現在 Unread，逐一核對檔名與摘要，不要只看「完成」標記。若任務完成時你正看著同一條 Thread，系統會直接視為已讀，不一定留下 Unread；切去另一條 Thread 才能驗證這個佇列。這一步是在確認模型、檔案授權、背景執行與 Inbox 四層真的串通，而不是只確認 UI 能開。

順手驗證桌面通知

桌面版到 Settings → General → Notifications，打開 Run finished 與 Action required 兩種通知。再跑一次測試任務，切到別的 Thread 並讓它在別處完成；預期同時看到 OS 通知與 Unread。若只把視窗切到背景、卻仍停在原 Thread，OS 通知可能出現，但該 Thread 會被視為已讀。瀏覽器版不提供這組 native notification 設定，且實際彈出仍受作業系統通知權限控制。

加入低權限 Skill 與 MCP：順序不能反

Pizza Bot 的設計是：MCP server 提供工具，Skill 把指令與一小組工具包成可委派的專家。依照官方 Extending 文件，只把 MCP 接上，主 Agent 並不會直接拿到全部工具；至少一個 ready Skill 必須在檔案頂端的 YAML 設定區（frontmatter）宣告完整的 mcp:<server>:<tool>。這也是目前 官方 issue #100 追蹤的 UX 缺口。

為了讓第一次練習真的能跑，使用官方儲存庫內的 mcp-status 範例 Plugin。它只用 Node.js 內建功能提供一個唯讀狀態工具，並附帶相對應的 Skill。桌面安裝版使用者可從 v1.1.0 Release 下載 Source code ZIP，解壓後找到同一個資料夾；先前從原始碼啟動的讀者，可在 repo root 用 macOS／Linux shell 執行：

cd examples/plugins
zip -r "$HOME/mcp-status.zip" mcp-status

到 Plugins 頁選擇這個 ZIP，確認內容後安裝；Windows 也可用檔案總管先把 mcp-status 資料夾壓成 ZIP。安裝完成後，MCP Servers 應出現 connected 的 mcp-status，Skills 應出現 ready 的 health-report。這仍是一段會執行的 Plugin，只因它是 tag-pinned 的第一方小範例，不能推論其他 Plugin 也可信。

用無害工具走一次 Action 批准流程

UI 路徑：在 Skills 頁選 New Skill，Name 填 mcp-status-approval-demo，Description 說明它會回報 MCP 健康狀態，Body 只填下方兩條編號指令；在 Tools 加入 mcp:mcp-status:get_mcp_status，勾選 Approval，再按 Create。UI 儲存會即時重新載入。

檔案路徑：也可在 <PIZZA_DATA_ROOT>/skills/mcp-status-approval-demo/SKILL.md 寫入以下完整內容。最上方兩條 --- 之間是 YAML 設定區（frontmatter）；手動存檔後要重新啟動 Pizza Bot／api-server 才會載入：

---
name: mcp-status-approval-demo
description: Report MCP health, but ask before the status tool runs.
tools:
  - mcp:mcp-status:get_mcp_status
interruptOn:
  "mcp:mcp-status:get_mcp_status":
    allowedDecisions:
      - approve
      - edit
      - reject
---

1. Call get_mcp_status.
2. Summarize server state and tool count.

等它顯示 ready 後，在新的一輪對話要求「請用 mcp-status-approval-demo 回報 MCP 健康狀態」。get_mcp_status 執行前應暫停，Thread 進入 Action；先核對工具名稱與 arguments，再按 Approve。這次工具只讀，回傳的是範例 Plugin 的示範狀態，不是全機系統診斷；目的只是安全地看懂批准卡片。

換成自己的 MCP 時，任何一個宣告的 server 或 tool 不可用，Skill 就不會進入可委派清單。先只放讀取／檢查工具，不用代表「全部工具」的萬用 *；確定需要寫入時，才把那一個有副作用的工具加入 tools 與 interruptOn。這個最小權限思路，也可延伸到 自己搭建 AI Agent Harness。

interruptOn 不是全域保護：沒有列入的 MCP 工具不保證先問你，Settings → Files 的可寫授權也是另一條權限邊界。以 stdio 啟動的 MCP 程序與 Plugin 的生成程序會用目前作業系統帳號的權限執行，不受 Settings → Files 的唯讀授權限制。安裝它們等同信任一段可執行程式。

真正批准有副作用的工具前，要先核對名稱與 arguments（參數），再決定 Approve、Edit 或 Reject。批准後 runtime 可能從節點開頭重跑，所以寫外部系統的工具必須設計成可重試、不重複建立同一筆資料；批准收件匣不保證「同一動作只執行一次」（exactly once）。

四個故障演練：先在唯讀測試環境故意失敗

1. client 斷線

讓唯讀摘要任務執行，切換 Thread 或重新整理 browser client，再回來。短暫斷線時，預期後端仍保留的事件會被補回，畫面繼續接收新事件；持久狀態則從 checkpoint 還原。任務完成時若你不在該 Thread，它會進 Unread。這只證明用戶端重連，不代表後端重啟能續跑，也不保證保留每一幀歷史事件。

2. api-server 停止

只對沒有寫入副作用的測試任務做：在執行中停止 backend，再啟動同一資料根目錄。預期 Thread 與最近 checkpoint 還在，但當時進行中的 step 已終止，不能宣稱自動接續。先看最後輸出，再判斷是否重送，避免未來換成寫入工具後重複操作。

3. 模型不可用

若使用本機 Ollama，可在無敏感資料的測試 Thread 暫停 Ollama 背景服務（daemon），送一個簡單 prompt，確認介面明確顯示 provider／model 錯誤，再恢復服務。不要用撤銷正式 API key 來做演練。恢復後先確認 provider 狀態，再決定是否重送。

4. 批准暫停與重連

再次觸發 mcp-status-approval-demo，先不要批准，離開 Thread 再回來。它應留在 Action，直到你做決定；若桌面 notification 已開，也可同時驗證 action required alert。這個練習只檢查「待批准」狀態能否經過重連保留；正式流程應明確選擇 Approve、Edit 或 Reject，不要依賴自動 timeout。

備份、升級與卸載：App 與資料要分開想

官方 備份指引要求先完全停止 backend，或使用 SQLite-aware snapshot；直接複製正在寫入的 SQLite 檔案可能拿到不一致狀態。以下 macOS／Linux 指令備份預設的 .pizza-bot-oss；若你用前面的隔離實驗目錄，請把最後一個名稱換成 pizza-bot-lab：

backup="$HOME/pizza-bot-backup-$(date +%F).tgz"
umask 077
tar -C "$HOME" -czf "$backup" .pizza-bot-oss
chmod 600 "$backup"

Windows PowerShell 可在完全停止後端後使用系統的 tar.exe；它避開 Compress-Archive 的單檔 2 GB 限制：

$backup = "$HOME\pizza-bot-backup-$(Get-Date -Format yyyy-MM-dd).tgz"
tar.exe -czf $backup -C $HOME .pizza-bot-oss
if ($LASTEXITCODE -ne 0) { throw 'Pizza Bot backup failed' }
icacls $backup /inheritance:r /grant:r "${env:USERNAME}:(R,W)"

這個壓縮檔含對話、附件與設定，還可能同時包含明文的 .env.local 與由 safeStorage 保護的桌面 secrets 檔，應視為高度敏感資料；不要放進公開同步資料夾。升級前保留一份。模型供應商憑證與 MCP 環境變數、已授權的後端主機資料夾，以及用 PIZZA_SKILLS_DIR、PIZZA_PLUGINS_DIR、PIZZA_MEMORIES_DIR 或 PIZZA_MCP_CONFIG 指到外部的資料，都要另外備份與恢復。你可以用 AI Setup Card 記錄版本、模型、資料根目錄與 MCP 來源，之後才知道該恢復什麼。

卸載程式不等於刪除資料。v1.1.0 把應用程式本體與持久化的 PIZZA_DATA_ROOT 分開處理，備份指引也要求備份資料根目錄而不是程式本體。因此，先用作業系統正常移除程式，確認備份可讀，再手動檢查實際的 PIZZA_DATA_ROOT（預設為 ~/.pizza-bot-oss，本篇隔離範例為 ~/pizza-bot-lab）；只有確定要永久清空時才刪除。不要假定移除應用程式會代替刪除個人資料。

目前的限制：好用的 Inbox，仍是年輕的 Harness

• 遠端部署仍是一個信任邊界：v1.1.0 的獨立後端是一個 SQLite 資料根目錄配一個 backend，遠端模式使用共同 bearer token；這組官方文件描述的設定，不提供 ticket 系統常見的每位使用者角色與細緻權限。
• 不是完整沙盒：本機資料夾 grant 有路徑限制，但 MCP／Plugin 是受信任程式，可用你的 OS 權限執行。
• 模型成本可能放大：主 Agent 與 Skill subagent 都會呼叫模型，多個平行委派會增加 token 與費用。
• 仍有早期缺口：截至 2026 年 9 月 20 日，每個 Skill 選不同模型仍在 issue #99，checkpoint retention／vacuum 也仍有 issue #58 的容量案例待處理。
• 公開版的整合目錄更精簡：AWS 發布文說先前有超過 2,000 名 Amazon 使用者用過內部早期版本，也說公開版移除了內部專有的 Skill／MCP 目錄；前一個數字不能當成目前 OSS 版本的使用人數或支援 SLA。

最穩健的定位是：Pizza Bot 是一個把背景 Agent、checkpoint 與人類決策整理成 Inbox 的本機工具；不是把自治、安全、成本與團隊治理一次解決的萬能層。若你偏好已封裝更多自主能力的個人 Agent，可接著比較 Hermes Agent。

想把這條學習路徑拉長，可以從 AlphaLab AI 專區繼續補齊模型與 Agent 基礎；需要系統化練習，則可查看 AlphaLab 課程。

常見問題

1. Pizza Bot 免費嗎？

程式以 Apache 2.0 開源；雲端模型、遠端主機與部分 MCP 服務的費用仍由你自行負擔。

2. 安裝 Pizza Bot 一定要 Node.js 嗎？

不用。官方桌面安裝包已包含所需 runtime；從原始碼或執行獨立後端套件（standalone artifact）才需要 Node.js 24 以上。

3. 關掉筆電後，任務還會繼續嗎？

要看後端在哪裡。若 client 與內建後端都在這台筆電，關機就會中止工作；若 client 連到另一台常開主機，只要那台主機與 api-server 持續運行，筆電可離線。24/7 通常用 standalone backend 部署，但關鍵是後端常開，不是名稱。

4. MCP 顯示 connected，為什麼 Agent 還是不能用？

因為 Pizza Bot 透過 ready Skill 委派 MCP 工具。建立 Skill、宣告正確的 mcp:server:tool，並確認所有依賴都 ready。

5. 使用 Ollama 就能完全離線嗎？

還不一定。除了模型、MCP 工具與資料來源都在本機，你還要確認本機 MCP／Plugin 本身不會向外連線；任何雲端 provider、遠端 MCP，或會發網路請求的本機工具，都會形成外部資料邊界。

6. Action 會攔住所有寫入嗎？

不會。它只攔截 Skill 在 interruptOn 明確列出的 MCP 工具；本機 folder write grant 和受信任 MCP process 是不同權限邊界。

7. 卸載 Pizza Bot 會一起刪除對話嗎？

不要假定會。v1.1.0 把程式本體與 PIZZA_DATA_ROOT 分開處理；卸載後仍要自行檢查實際的資料根目錄（預設為 ~/.pizza-bot-oss），先備份再決定是否清除。

8. Pizza Bot 能取代 Linear 或 Jira 嗎？

通常不能完整取代。它強在個人或單一信任邊界下的通用 Agent 執行；ticket tracker 強在團隊責任、優先順序與系統紀錄。

新手真正要記住的 5 件事

1. 先核對 release checksum，再安裝未簽章平台套件。
2. 把 Pizza Bot 當 Inbox，不要把 client 當執行引擎；api-server 才是背景工作的生命線。
3. 第一個任務只給測試資料夾的唯讀權限。
4. MCP 要經過 Skill 才能被委派；本機資料夾先維持 read-only，有副作用的 MCP 工具逐一設 interruptOn。
5. 先演練斷線、後端停止、模型錯誤與待批准，再交付真正有副作用的工作。