為什麼首次要下載 720 MB、之後就秒開

為什麼要一次講這個

Pi Agent 有兩件事，讀者最常搞混：

• 第 2 章講的「首次啟動要等 3-8 分鐘」——你剛裝好按 Start，UI 卻半天沒動，log 一直冒紅字，第一個念頭都是「我是不是裝壞了」。
• 第 17 章講的「影片管線需要 720 MB 工具」——AI 幫你錄畫面、配音、剪片、燒字幕，那一整套工具鏈很大。

這兩件事其實是同一件事。首次啟動的 3-8 分鐘就是在下載那 720 MB。這章就把三件事一次串起來：

1. 裝了什麼

   Chromium、Python venv、ffmpeg、字型、rclone——三大塊。

2. 放在哪

   全部在 /data/pi-agent/ 的三個子目錄，你可以真的用 File editor 進去看。

3. 什麼時候會再裝一次

   正常情況：永遠不會。特殊情況：你翻 reset_video_tools 開關、或整個 add-on 被移除重裝，才會重下。

看完你會知道兩件事：什麼時候該讓它裝、什麼時候該叫它重來。前者省你緊張，後者省你自己 exec 進容器手動刪檔案。

video-tools 其實是三個工具的統稱

Pi Agent 內部把「影片管線需要的東西」統稱為 video-tools，但它不是一個東西，是三塊。第 2 章你看到的 720 MB 是這三塊加起來的：

所以嚴格講「首次下載到 /data/pi-agent/」的其實是前兩塊：Chromium 加 Python venv，總計約 600-700 MB，這個數字會因為 Playwright 版本、pip 依賴版本而在 600-720 MB 之間浮動——這就是為什麼你常聽到「大約 720 MB」這種模糊講法。第三塊 ffmpeg 那些是 add-on 映像檔的一部分，你「下載映像檔」那 300 MB 的階段就一起拉下來了。

首次啟動那 3-8 分鐘發生什麼事

你按了 Add-on 頁的 Start 之後，實際發生的事情有兩條線同時跑：

1. 第一條線：pi-web 立刻起來（幾秒鐘）

   你在第 3 章看到的側邊欄按鈕、能點進 UI、能開始跟 AI 聊天——這條線幾秒就好。pi-web 是 Node.js 程式，本身不需要 Chromium、也不需要 Python，跟影片管線是完全兩碼子事。所以你點進去可以馬上聊。

2. 第二條線：video-tools-init 在背景下載（3-8 分鐘）

   啟動腳本 pi-web-start.sh 看到 sentinel 檔 /data/pi-agent/.video-tools-installed 不存在，就會 fork 出一個背景進程叫 video-tools-init.sh。這個腳本按順序做四件事：

   • 建立 Python venv：python3 -m venv /data/pi-agent/venv，約 10 秒
   • 用 pip 裝 playwright / edge-tts / pyyaml / mutagen，約 30 秒-2 分鐘（看網路）
   • 叫 playwright 下載 Chromium 到 /data/pi-agent/playwright-cache/，約 2-6 分鐘（最大隻）
   • 裝完 touch 一個空檔叫 .video-tools-installed，代表「這台我裝過了」

3. 之後每次啟動：跳過

   下次你重啟 add-on、重開 HA、甚至重開機，video-tools-init 一啟動就檢查 sentinel 檔（跟 venv/bin/python3），看到兩個都在就 exit 0 什麼也不做。log 只會出現一行 video-tools-init: already installed (sentinel present) — skipping，秒過。這就是為什麼首次要幾分鐘、之後秒開。

裝在哪：三個位置一次看完

「下載」的東西全部落在 /data/pi-agent/ 這個 HA host 上的目錄裡。你可以用 File editor add-on（或 SSH）進去看，會看到這三個位置：

這裡的關鍵字是 sentinel（哨兵）——這是很多 Docker/Linux 服務常用的手法：不需要真的檢查裝了什麼、也不需要驗證版本，就是一個空檔案代表「這件事做過了」。輕、快、不會被誤判。你如果好奇這個檔的內容，cat .video-tools-installed 出來會是空的，因為它從頭到尾就是 touch 出來的。

重要：這 720 MB 不會被 HA snapshot 備份

這是本章最容易踩雷的一件事，講清楚：Pi Agent 的 config.yaml 有一份 backup_exclude 清單，明講「這幾個 glob pattern 不要放進 HA snapshot」。清單裡有七條，跟本章 720 MB 相關的是這幾個：

• **/venv/** ← 就是這 720 MB 的 Python venv
• **/playwright-cache/** ← 就是這 720 MB 的 Chromium
• **/projects/**/clips/**、**/projects/**/segments/** ← 影片管線產出的中間檔（很大、可重生）
• **/home/**/node_modules/**、**/home/**/.cache/** ← AI 工作目錄的 npm 快取
• **/sessions/*.jsonl.tmp ← 對話寫到一半的暫存檔

特別注意：rclone.conf（Google Drive 授權 token）沒在排除清單裡——它會被備份進 snapshot。這是刻意的：如果 rclone 授權掉了，你 restore 之後所有 push_drive.sh 都會 silently 失敗，很難察覺。所以那個檔案值得那 300 byte 的備份空間。

為什麼要故意排除？兩個原因：

1. 原因一：不排除的話 snapshot 檔會膨脹到 1 GB+

   HA snapshot 預設就是把整個 add-on 的 data 目錄壓縮打包。如果不排除，你每一份 snapshot 都多帶 700 MB 的 Chromium+venv 進去，一份備份至少 1 GB 起跳。用 Google Drive 或 USB 隨身碟保存一年 12 份 snapshot，光 Pi Agent 就吃掉 12 GB，完全沒必要。

2. 原因二：還原後 s6-overlay 會自動再裝一次

   假設你今天整台 HA 掛了、拿 snapshot 還原到新硬體，Pi Agent 那份 snapshot 裡沒有 venv 也沒有 playwright-cache——雖然 sentinel 檔本身有被還原回來，但 video-tools-init 的判斷條件是「sentinel 檔存在 而且 venv/bin/python3 是可執行檔」，兩個要同時成立才跳過安裝。venv 沒了 python3 就沒了，判斷失敗，腳本會照樣重跑那 3-8 分鐘的下載，等於「新機重新裝一份」，環境跟原本完全等價。備份少 700 MB、還原多等 5 分鐘，這筆帳很划算。

那什麼會放進 snapshot？你真正產生的東西：

換句話說：你花心血產生的都在、機器自己下載的都不在。這個切分很乾淨。第 20 章會把備份還原的完整流程講一次。

reset_video_tools 開關的用途與操作

Pi Agent 的 Add-on Configuration 分頁裡有一個特殊開關叫 reset_video_tools。這個開關的意義只有一句話：把 sentinel、venv、playwright-cache 全刪掉，下次啟動重新下載一次。

操作步驟：

1. 打開 Add-on 頁的 Configuration 分頁

   Home Assistant → Settings → Add-ons → Pi Agent → Configuration 分頁（跟你設 log_level、timezone 的同一頁）。

2. 把 reset_video_tools 從 false 改成 true

   它是一個 boolean 開關。UI 上是一個切換按鈕，改成 on（true）。

3. 按 SAVE 存檔

   存了之後 HA 會提示「要重啟 add-on 才生效」。這是預期的。

4. 回 Info 分頁按 RESTART

   重啟時 s6-overlay 的 pi-web/run 讀到 reset_video_tools: true，先跑 rm -rf /data/pi-agent/.video-tools-installed /data/pi-agent/venv /data/pi-agent/playwright-cache，log 會冒一行 reset_video_tools=true — clearing venv + playwright-cache + sentinel。清完就進入正常啟動流程，然後因為 sentinel 沒了，video-tools-init 這個 s6 oneshot 又會跑一次 3-8 分鐘的下載。

5. 不用回去手動關——add-on 會自動幫你翻回 false

   這是 v0.13.0 版加進來的重要行為，很多網路上的舊教學（包括本站早期版本）都寫錯：啟動腳本刪完檔案後，會馬上打一支 Supervisor API（POST /addons/self/options 帶 {"options": {"reset_video_tools": false}}）把這個選項翻回 false，你下次重啟就是正常流程、不會又重下 720 MB。log 會出現一行 reset_video_tools auto-reverted to false 代表成功。如果 Supervisor API 呼叫失敗（例如 SUPERVISOR_TOKEN 沒注入、或 curl 5 秒逾時），log 會冒警告 Could not auto-revert reset_video_tools — turn it OFF manually to avoid re-clearing next boot——這時候才需要你回 Configuration 手動關。多數情況下你完全不用碰。

什麼時候該用 reset_video_tools

這個開關是維修用的逃生口，正常情況不要碰。整理什麼時候該用、什麼時候別碰：

總結一句話：reset 是為「壞了」而存在，不是為「潔癖」而存在。沒故障就別動。

不打算用影片管線，可以省下這 720 MB 嗎

老實答：不能省下。原因跟 Pi Agent 的設計有關：

1. video-tools-init 是 s6-overlay 的 oneshot，沒有 config 開關可以關

   HA add-on 版把 video-tools-init 註冊成 s6-overlay 的一個 oneshot 服務（放在 rootfs/etc/s6-overlay/s6-rc.d/video-tools-init/），跟 pi-web / nginx 三個服務平行啟動——這是刻意的設計，讓 chat 立刻能用、video-tools 在背景慢慢裝。但既然是 s6 oneshot，Configuration 分頁就沒有一個開關可以叫它不要跑。腳本本身也沒有 if VIDEO_PIPELINE_ENABLED 之類的條件檢查（那是 k3s 部署版才有的分支）。

2. 硬要不裝，只有兩條路，都不建議一般使用者走

   （a）自己 fork Woow_ha_pi_agent_add_on，把 rootfs/etc/s6-overlay/s6-rc.d/user/contents.d/video-tools-init 這個檔刪掉，重新 build 一份 image 塞進自己的 add-on repository。（b）不進入 pi-web 就完全不會用到 venv/chromium，等於你「保留檔案但不使用」——720 MB 就在那裡占位不動。這兩條都比想像的麻煩，多數人不會這樣做。

3. 就算跳過 init，映像檔本身還是含 300 MB 的 ffmpeg / 字型 / rclone

   那一塊是烤進 Docker image 的（Dockerfile 直接 apt install 進去），你在 add-on 這一端完全無法選擇不裝。要真的省，得自己 fork 改 Dockerfile 拿掉那些 package，這已經是自製 fork 了。

4. 實務建議：就讓它裝一次

   720 MB 對現在的硬碟（HA 官方最低就要 32 GB）是 2% 左右的空間；下載也就一次的事。「省事」跟「省 2% 空間」比，省事贏。你就當作 add-on 出廠自帶影片能力，日後想用不用另外裝，不用也就佔那點空間。真的空間不夠的話該解決的是硬碟太小，不是砍 Pi Agent 的功能。

怎麼看下載進度、判斷卡住還是慢

下載這 720 MB 期間，你不用瞎等，可以在 Logs 分頁看它跑到哪。Add-on Logs 分頁進去，找開頭是 video-tools-init: 的行（那是 bashio 印的，跟 pi-web 的 log 混在一起顯示）。正常的進度大概像這樣：

[INFO] Starting pi-web on 0.0.0.0:30141 (data: /data/pi-agent, home: /data/pi-agent/home)
[INFO] video-tools-init: first-run install starting (~720MB, may take several minutes)
[INFO] video-tools-init: creating venv at /data/pi-agent/venv
[INFO] video-tools-init: installing python packages into venv
[INFO] video-tools-init: downloading Chromium into /data/pi-agent/playwright-cache (~600MB)
[INFO] video-tools-init: install complete — sentinel written to /data/pi-agent/.video-tools-installed

每一行的意義：

如果你看到 log 卡在某一行超過 10 分鐘、又沒新的錯誤訊息，通常是網路或某個下載源慢。判斷方法：

• 去 HA 主 UI 的 Settings → System → Network 看——有沒有網路。如果沒網路，重點是先修網路，不是等。
• 去 Settings → Add-ons → Pi Agent → Info 看 CPU / Memory——如果 CPU 一直有動、記憶體在漲，代表它有在工作，只是慢。等就對了。
• 如果 log 出現「WARNING: chromium download failed」之類——代表這次首裝失敗了。這種情況不會建立 sentinel，所以下次啟動 video-tools-init 會自動再跑一次，看看網路狀況會不會變好。不用手動 reset。

哪些情況下會（或不會）再下載一次

整理你可能遇到的各種「動 Pi Agent」的情境，會不會觸發重新下載這 720 MB：

看完你應該有底了：你的日常操作（升級、重啟、重開 HA）都不會觸發重下；只有「移除重裝」「還原災難用備份」「主動 reset」這三種情況才會。也就是說平均下來，多數人這一輩子只會看到那個 3-8 分鐘一次而已。

常見卡關

1. 下載卡在 downloading Chromium 那行超過 30 分鐘沒動

   八成是網路問題。Playwright 下載 Chromium 走 Google 的 CDN，某些網路環境（校園網、公司內網、部分 ISP）會慢到爆。判斷：去 HA Info 分頁看 CPU/網路有沒有動，有動就是純慢，等；完全沒動可能是連線斷了。試試：（a）換時段（半夜通常快）；（b）如果 HA 走 VPN 或某些 proxy，暫時繞開；（c）真的完全過不去，開 reset_video_tools 重跑一次。

2. 看到 WARNING: pip install failed 但 log 又繼續往下跑

   這個 warning 意思是「pip 那步炸了但腳本繼續跑」——因為 video-tools-init.sh 每個失敗都 exit 0（不擋 pi-web）。結果就是：pi-web 能用、聊天能用，但影片管線的 skill 一跑一定失敗。判斷：試著跑一個影片管線的 skill，看它報什麼錯。多半是說「找不到 edge-tts」之類。解法：reset_video_tools 重來一次，通常第二次會成功（第一次可能剛好某個 mirror 掛了）。

3. 下載完了但 sentinel 沒建（/data/pi-agent/.video-tools-installed 不存在）

   如果每個 pip / playwright 步驟都成功，但 touch sentinel 失敗，通常是權限問題——data 目錄的擁有者被弄亂了。判斷：ls -la /data/pi-agent/ 看擁有者。正常情況下該資料夾應該是 add-on user 可寫的。解法：先看 log 有沒有 "Permission denied"，有的話最乾淨的做法是 uninstall Pi Agent（選不保留 data）再重裝，讓 HA 重建 volume 的權限。這是核彈選項，但省時間。

4. 影片管線的 skill 跑失敗、log 沒錯誤但影片就是沒出來

   典型「venv 半殘」症狀：Python 模組看似都在但某個依賴壞了，執行時中途 silent crash。判斷：先去 Logs 分頁翻一下 skill 執行時的完整輸出，找 Python traceback。真的看不出來就直接 reset_video_tools——這是這個開關最主要的用途，一次重建 venv 通常就好。

5. 硬碟空間不夠、Pi Agent 拒絕下載

   Chromium + venv 加起來要 700 MB，加上下載暫存還要多一點，建議自由空間至少 2 GB。第 2 章建議整個 HA host 留 3 GB。空間不夠時 pip 會報 No space left on device。解法：（a）先清 /backup/ 底下舊 snapshot；（b）清 /data/pi-agent/clips/ 跟 segments/（影片中間檔，看第 17 章）；（c）清 /data/pi-agent/sessions/ 老對話。清完再 reset 一次重來。

6. reset_video_tools 的自動翻回機制失敗了（每次重啟都重下 720 MB）

   正常情況下 add-on 會呼叫 Supervisor API 把這個開關自動翻回 false，但極少數狀況會失敗——例如某個 Supervisor 版本 bug、或 SUPERVISOR_TOKEN 沒注入（罕見）。判斷：去 Configuration 分頁看 reset_video_tools 是不是還在 true，同時去 Logs 看有沒有 Could not auto-revert reset_video_tools 這行警告。有就手動撥回 false 存檔，下次重啟就秒過了。如果反覆發生，去 Info 分頁看 add-on 版本是不是 < 0.13.0（更舊的版本沒有自動翻回機制），有的話升級。

7. 不想動 config，只想「乾脆清 sentinel 讓它重跑」

   DOCS.md 官方 troubleshoot 段講的比較低科技的做法：不用開 reset_video_tools 開關，直接進 add-on 的 Terminal 分頁（或 docker exec -it addon_woow_ha_pi_agent bash）跑 rm /data/pi-agent/.video-tools-installed，再回 Info 按 RESTART。因為腳本的 sentinel 檢查會失敗，就會重跑一次 3-8 分鐘的安裝。這個方法不會動到 venv/playwright-cache 目錄本身，如果只是 sentinel 檔被誤刪或 corrupted 的救援場景，比 reset 更精準（reset 會連 venv 整個砍掉）。

常見問題