底層架構好奇者向

為什麼要看這篇（不看也行）

先講清楚：99% 時候你不需要這篇。你按著第 2 章裝好、第 3 章從側邊欄打開、用得順順的——不用知道背後跑了什麼。就像你開冷氣不用知道壓縮機的原理。

但有那 1% 的時候會派上用場：

• Logs 出現看不懂的錯——你在 add-on 頁面切到 Log 分頁看到「nginx: [emerg] host not found in upstream」、「s6-rc: fatal: unable to start service pi-web」、「video-tools-init exited with code 1」，這些訊息你查 Google 也查不到 Pi Agent 專屬解法。看完這附錄你會知道每個服務是幹嘛的、失敗代表什麼。
• 想自己 debug 不想等下一版——某個功能怪怪的，你想 SSH 進 add-on 容器看看到底哪出問題。你得先知道有哪些目錄、哪些 process、log 存哪。
• 想改進或客製——你想 fork Pi Agent、想幫上游貢獻、想寫一個 companion add-on。這時你必須理解整條 pipeline。
• 純粹好奇——你是那種買了新設備會拆開看的人，那繼續往下讀就對了。

整體架構：大樓管理員比喻

用一個具體比喻先把層次講清楚，之後每一節再展開。把整套系統想像成一棟大樓：

兩個關鍵設計你要抓住：

1. Ingress 是唯一入口

   你的瀏覽器不能直接連 Pi Agent 的內部服務。所有請求都得經過 HA 的接待櫃檯（Ingress），櫃檯先確認你是登入過的 HA admin，再放行到 Pi Agent 內部。這是為什麼第 3 章強調「側邊欄按鈕自動出現」——那個按鈕背後就是走 Ingress。

2. 戶內是多層次的

   Pi Agent 這個 add-on 容器內部不是只跑一個 process，而是一整組——nginx 站在門口收轉發、pi-web 是主應用、video-tools-init 是首次啟動才會跑的一次性 worker，加上 s6-overlay 這個「家管系統」在背後協調。

s6-overlay 開機順序：家人幾點上班

當 HA Supervisor 按下 Pi Agent 的「啟動」，容器內部發生的事其實有明確順序。s6-overlay（有時寫 s6）是這棟家管系統的核心——它是一套「行程監督工具（process supervisor）」，負責把家人一個個依序叫起來。

這裡有一件看原始碼才發現的細節：實際上 video-tools-init oneshot 沒有被列進 nginx/pi-web 的 dependencies.d——換句話說，s6-overlay 開機時把三個服務平行啟動：video-tools-init 一邊下 720MB Chromium，nginx 跟 pi-web 一邊已經在收請求。所以裝機那 3-8 分鐘的等待時，你其實已經可以打開對話介面聊天，只是影片管線暫時不能用。這是作者刻意的設計取捨（看 rootfs/etc/s6-overlay/scripts/video-tools-init 開頭的註解「Parallel with pi-web」），為了「chat UI 立刻能用、影片工具慢慢裝」，非「等一切齊全才給你進門」。

另外，Supervisor 從外面也會定期打 Watchdog 探針（下一節詳說）——如果 pi-web 卡住、hang 住、或應答變得很慢，Supervisor 會下令重啟整個容器。s6-overlay 這時會按同樣順序再走一次，只不過第 2 步會秒退（sentinel 存在＋${VENV}/bin/python3 可執行都通過才會 skip，這是雙重檢查，避免第一次裝到一半掉線的殘骸誤判成裝好）。

nginx 的角色：HA Ingress 的翻譯官

你可能會覺得「Pi Agent 是個網頁應用，為什麼中間要多一層 nginx？多此一舉」。實際上 nginx 是整個容器裡最微妙、最關鍵的一個服務——它是翻譯官，把 HA Ingress 講的話翻譯給 pi-web 聽。

先看問題：HA 給每個 add-on 分配的 URL 長這樣——

https://homeassistant.local:8123/hassio/ingress/woow_ha_pi_agent/

而 pi-web 這個應用內部只認得「根路徑」（/），它不知道自己被藏在 /hassio/ingress/woow_ha_pi_agent/ 底下。如果不處理，pi-web 產生的 HTML 裡的連結會寫成 /settings 之類的相對路徑，瀏覽器一點就跳到 https://homeassistant.local:8123/settings——404，因為那不在 HA 的路由裡。

nginx 就是負責幫忙「路徑翻譯」的中間人：

1. 收 HA Ingress 進來的請求

   HA 把請求塞給 Pi Agent 容器的 30142 埠（ingress_port: 30142），nginx 監聽那個埠，所以第一手一定收到。

2. 從請求頭部把 Ingress path 取出來

   HA 會在請求裡塞一個叫 X-Ingress-Path 的 HTTP header，內容像 /api/hassio_ingress/A1b2C3d4e5F6g7H8（16-128 字元的隨機字串，每次 HA 重啟會換）。

3. 轉給 pi-web、拿到回覆

   nginx 把請求轉發到 http://127.0.0.1:30141（pi-web 內部埠），pi-web 產出 HTML 回覆。

4. 白名單防禦：先驗證 header 合法

   為了避免有人偽造 X-Ingress-Path 亂射，nginx 用 map $http_x_ingress_path $safe_ingress_path 區塊配合 regex（正則表達式）驗證，只讓格式為 ^/api/hassio_ingress/[A-Za-z0-9_-]{16,128}$ 的過（直接從 nginx.conf 抄的，不是推測）。不符合就強制設成空字串——之後所有 body-rewrite 都變成 no-op，關閉「透過偽造 header 打 XSS」的可能。這是 v0.7.0 為了修 F-01 安全審計加的。

5. 用 sub_filter 改寫 HTML 裡的絕對路徑

   nginx 用 sub_filter 逐字節改寫傳出的 HTML/CSS/JS：把 href="/_next/、src="/_next/、href="/manifest、href="/icons/、CSS 裡的 url(/_next/、還有 RSC flight payload 裡 JSON-escape 的 \"/_next/，通通加上 Ingress 前綴。

6. 但 sub_filter 蓋不到執行期的 JS 呼叫——所以又塞了一個 client-side shim

   這才是這個檔案裡最麻煩的一段。pi-web 的前端 bundle 有 40+ 個絕對路徑的 /api/* 呼叫（fetch、EventSource、XMLHttpRequest），加上 Next.js App Router 的 RSC prefetch（?_rsc=<token>）、history.pushState/replaceState、以及 ReactDOM.preinit()／next/font 執行期塞進 DOM 的 <link>——這些 sub_filter 都攔不到。所以 nginx 額外用 sub_filter 在 </head> 前塞一段 JS，猴子補丁（monkey-patch）window.fetch、EventSource、XMLHttpRequest.prototype.open、history.pushState/replaceState、Element.prototype.setAttribute、HTMLLinkElement/HTMLScriptElement/HTMLImageElement 的 href/src setter，全部繞去補上 window.__INGRESS_PATH__。順便把 navigator.serviceWorker.register stub 成回傳空的假 registration（HA Ingress 底下 PWA service worker 沒意義還會噴 console 錯誤）。這段補丁的迭代史看 CHANGELOG.md v0.5.0～v0.10.4 就知道有多痛。

這一層看起來很囉唆，實際上是把「pi-web 完全不需要知道 HA Ingress」這件事變成真的。pi-web 只管好好當一個 Next.js 應用；nginx 加 sub_filter 加 client-side shim 三層合力把它塞進 HA 的路由架構。這種設計叫 Ingress shim——就像插頭的轉接器，兩邊規格不同時中間放好幾片。

/data/pi-agent/ 目錄地圖

第 20 章已經給過一個簡表，這裡給的是完整版——你 SSH 進 add-on container 進到儲藏室之後，眼前會看到這些：

兩個要記住的原則：

• 值錢的（不能重生的）都在 /data/pi-agent/——sessions、models.json、skills、rclone conf。這也是 HA snapshot 抓的核心。
• 大而可重生的（venv、playwright-cache）刻意被 exclude——如果 snapshot 抓 venv，一個 backup 檔就 500MB 起跳，實務上很痛苦。所以政策是「刪掉這些，還原後首次啟動 video-tools-init 會自動重下載」。

Watchdog 探針：Supervisor 怎麼確認你還活著

Pi Agent 是長時間跑的服務，可能因為 memory leak、無窮迴圈、外部 API 死等而卡住。Watchdog（守望）是 HA Supervisor 用來偵測這種「還在跑但實際上死掉」情況的機制。

Watchdog 是雙面刃：能自動撿回卡住的服務很棒，但如果你的 add-on 本身沒問題只是回應比較慢（例如你叫它處理大量對話歷史），有機會被誤判成「hang」被強制 restart。這時候要嘛加大 timeout（改 config.yaml）、要嘛暫時把 Watchdog 關掉（HA 頁面上有開關）。

Skill 發現流程：AI 怎麼知道有哪些工具

第 14 章講過 Skill 的心智模型（給 AI 讀的工作手冊），這裡講「AI 怎麼發現」——這是很多人納悶的地方：「我 pi install 裝了新 skill，為什麼要重開 session 才生效？」

可能的流程是這樣，發生在每次你按「新對話」的瞬間：

1. Session 建立

   你按新對話，pi-web 建一個新的 session 檔案（sessions/.../*.jsonl）。

2. 掃描 skills 資料夾

   pi-web 開始掃 /data/pi-agent/skills/*/SKILL.md——把每個子資料夾底下的 SKILL.md 檔案讀進來。

3. 解析 YAML frontmatter

   每個 SKILL.md 檔案開頭有一段 YAML frontmatter，長這樣：

   ---
   name: fridge_inventory
   description: 幫使用者盤點冰箱食材、找出快過期的東西
   ---
   
   # 冰箱盤點手藝
   
   ...細節內容...

   pi-web 只讀 name 跟 description——整份 SKILL.md 的內文不會直接塞給 AI，只給摘要。

4. 組成 <available_skills> 塊

   所有 skill 的 name + description 合成一個列表，包在 XML 標籤裡。看起來像：

   <available_skills>
   <skill name="fridge_inventory">
   幫使用者盤點冰箱食材、找出快過期的東西
   </skill>
   <skill name="pitch_video">
   從腳本到 YouTube 可上傳的影片管線
   </skill>
   </available_skills>

5. 貼到 system prompt 開頭

   這個 <available_skills> 塊被貼在 AI 的 system prompt 開頭——AI 開啟對話的第一件事就是看到「這台機器可以呼叫的手藝有這些」。

6. AI 判斷什麼時候用哪個

   之後你講什麼 AI 都會依這份清單判斷「這個問題有沒有適合的 skill 可以叫」。要叫的時候 AI 才會去讀完整的 SKILL.md 內容（透過工具呼叫），拿到細節做事。

這就是為什麼裝新 skill 必須重開 session——已經開的 session 的 system prompt 是舊的、沒把新 skill 塞進去。也是為什麼SKILL.md 的 description 那一行超重要——寫得不好 AI 就不會挑到你這個 skill；寫得好會經常派上用場。

pi-web 的技術棧：主應用到底用什麼寫的

你在瀏覽器看到的整個介面，包括打字區、對話列表、模型下拉、Skills 面板——通通都是 pi-web 這個 Node.js 應用做出來的。它的組成：

幾個技術點值得注意：

• pi-coding-agent SDK 是 in-process 的——這代表 pi-web 崩了 agent 也跟著崩、agent 執行的 tool call（比如寫檔案）是用 pi-web 的權限做的。沒有 daemon 隔離就是為了少一層 IPC。
• 沒有資料庫——對話存 JSONL 檔案、設定存 JSON 檔案，一切都是檔案系統。這是刻意的簡化設計（也讓備份很好處理）。
• chat 走 SSE（Server-Sent Events）——AI 回覆邊產生邊 stream 給你看那種效果，是用 SSE 傳的。這也是為什麼 nginx 那節的 proxy_buffering 一定要關掉——不然回覆會被 nginx 緩到 AI 生完才一次吐出來。

v0.13.0 為什麼把 API key 從 add-on config 搬到 pi-web UI

這是 v0.13.0 版本最大的架構改動，你如果從舊版升上來會發現 add-on Configuration 分頁上原本的 API key 欄位不見了（第 21 章講過這個升級踩雷）。這節從架構角度講「為什麼要搬」。

舊架構（v0.12 之前）：

1. 你在 add-on Configuration 分頁填欄位

   畫面上有 anthropic_api_key、openai_api_key、glm_api_key 一堆欄位。

2. Supervisor 寫到 /data/options.json

   你按存檔，Supervisor 把整個表單序列化成 JSON 寫進容器內的 /data/options.json。

3. 啟動時當環境變數塞給 pi-web

   s6-overlay 開機腳本讀 /data/options.json，把每個欄位變成 ANTHROPIC_API_KEY=... 之類的 env var，然後才 exec pi-web。

4. pi-web 從環境變數讀

   pi-web 啟動時 process.env.ANTHROPIC_API_KEY 拿金鑰。

舊架構的缺點：

• 加新家 provider 就要改 config.yaml 的 schema、發新版才行——動態不了
• 同一家想接兩把 key（工作一把、家用一把）？做不到，一個欄位一個值
• 沒有 Test 按鈕——你貼錯的 key，要等實際發第一封請求才知道 401 錯了
• 動態切換慢——改欄位要 restart add-on 才吃到新值

新架構（v0.13 之後）：

1. 你打開 pi-web 的 Models 面板

   在瀏覽器介面裡，不是 add-on 那邊。

2. 按 Add Provider、填表、按 Test

   第 6 章教過的流程。Test 按下去 pi-web 會實際發一封 API 請求驗證，綠燈才存。

3. pi-web 存到 /data/pi-agent/models.json

   結構化的 JSON，可以裝很多 provider、每 provider 很多 key、每 key 很多 model。

4. 不需要 restart 就生效

   下個 session 就吃到新設定，因為 pi-web 每次開 session 都會 re-read models.json。

新架構的好處：

• 多家、多 key、多 model 都能動態管理
• Test 按鈕可以事先驗證
• 不用重啟 add-on
• UI 上可以做「按這家的 provider 只想用其中某幾個 model」這種細節控制

遷移路徑（更正！）：作者原本以為 v0.13.0 會自動幫你 seed 舊 key 進去models.json——去讀 CHANGELOG.md 跟 DOCS.md 才發現是 hard cut，沒有 auto-migration（原文兩處講兩次「No auto-import」）。升上 v0.13.0 之後每一個 provider 都要你在 pi-web Models 面板重新貼一次 key 加按 Test——舊 options.json 裡的欄位 Supervisor 依新 schema 直接丟掉。models.json 裡舊的 $GLM_API_KEY 之類的環境變數 placeholder 會 resolve 成空字串，每個 chat 都會 401 直到你重貼——這是預期的過渡狀態。

debug 進階技巧：進到容器裡面看

普通的 debug 靠 add-on Log 分頁看訊息就行。進階 debug 得進到容器內部——這裡整理幾招最常用的：

1. 開 debug log level

   在 add-on Configuration 分頁把 log_level 從 info 改成 debug（附錄 A 有詳細等級對照）。改完存檔會自動重啟，重啟後 Log 分頁會有非常詳細的訊息（有時多到眼花，看完記得改回 info）。

2. SSH 進 HA host 再 exec 進容器

   裝 SSH & Web Terminal add-on，或用 HA 的 Advanced SSH。連進去之後跑：

   docker ps | grep pi_agent   # 先看容器實際叫什麼
   docker exec -it addon_<hash>_woow_ha_pi_agent bash

   就進到 Pi Agent 容器內部了。可以 ls /data/pi-agent、cat /etc/nginx/nginx.conf、ps aux 看有哪些 process 在跑。注意這是 read-only 心態——別亂改容器內的檔案（重啟會消失，除非改在 /data 底下）。

3. 看 nginx access log 抓 Ingress path

   容器內：

   tail -f /var/log/nginx/access.log

   可以看每個請求進來的 URL、狀態碼、response time。想確認「HA 有沒有真的把 X-Ingress-Path header 送進來」，看這裡最快。

4. 手動測 edge-tts 是不是能連微軟

   容器內：

   /data/pi-agent/venv/bin/python -m edge_tts --list-voices | head

   能列出聲音就代表網路通、venv 沒壞。列不出來就是「video-tools 半殘」——沿著 第 18 章的重跑機制修復。

5. 手動測 rclone 到 Google Drive

   容器內：

   rclone --config /data/pi-agent/rclone/rclone.conf ls gdrive: | head

   能看到 Google Drive 內容代表授權還沒過期。看到 token expired 之類就是要重新跑 rclone config reconnect（第 19 章結尾提過）。

架構層 troubleshoot 清單

這一節不重複第 22 章的表面症狀，只列「懂架構才能修」的那些：

1. 想在 HA host 上直接動 /data/pi-agent/ 的檔

   症狀：你想在 HA host 用 File Editor 或 SSH 直接 vi 一份 models.json，但找不到那個路徑。
   原因：HA add-on 的 /data 在 host 端不是 /data——實際路徑本文沒從 add-on 原始碼確認（source 只寫「per-addon mount」），大概候選是 /mnt/data/supervisor/addon_configs/<slug>/（HA OS）或 /usr/share/hassio/addon_configs/<slug>/（Supervised）——但這是 Supervisor 決定的、跨版本會變。
   解法：SSH 進 HA host → 兩個路徑都 ls 一下，哪個存在就進去。更穩的做法：直接進 container docker exec -it addon_<hash>_woow_ha_pi_agent bash 然後 vi /data/pi-agent/models.json——容器內的 /data 才是 add-on API 直接綁定的位置，不用猜 host 側 mount point。改完存檔不用重啟 add-on，pi-web 下次 read 就吃到（但影響大的檔改完最好重啟保險）。

2. Ingress 掛：nginx 一直回 403

   症狀：側邊欄按 Pi Agent 按鈕，畫面出現一片空白或 nginx 的 403 錯誤頁。
   原因：nginx 的白名單 regex 沒讓 X-Ingress-Path header 過。可能是 HA 版本更新後 header 格式微改（多了字元、少了 _），或 HA 那邊沒送這個 header 進來。
   解法：容器內 tail -f /var/log/nginx/access.log 看實際請求的 header；如果格式明顯不同（例如 slug 突然有大寫或全形），去 GitHub Woow_ha_pi_agent_add_on 開 issue 貼給作者。臨時解法：重啟 HA 本體讓 Ingress 重發新的 slug。

3. pi-web hang：Watchdog 一直 restart

   症狀：Log 分頁每幾分鐘就跳 s6-rc-init started，代表容器不斷被 Supervisor 重啟。
   原因：pi-web 的 /api/home 端點沒在 60 秒內回 200——可能是 CPU 被吃光、記憶體不夠、Node event loop 卡在某個同步操作。
   解法：（a）先看 HA 主機 CPU/RAM 是不是滿載——Pi 3、太舊的 mini PC 很容易掛；（b）暫時關掉 Watchdog（HA add-on 頁面上有開關）看 pi-web 到底能不能自己撐；（c）開 log_level: debug 抓死前那幾秒在幹嘛；（d）真的搞不定就到 GitHub 開 issue 附上 log。

4. video-tools 半殘：sentinel 有了但 venv 是空的

   症狀：影片管線一叫就爆錯，說找不到 edge-tts 或 Playwright。
   原因：video-tools-init 第一次跑到一半掉線但已經寫了 sentinel 就退出，之後每次都以為裝好了直接跳過。
   解法：add-on Configuration 分頁把 reset_video_tools: true 打勾存檔——這個開關會刪掉 sentinel 讓下次啟動重新跑一次 init。跑完記得回來把開關關掉（不然每次啟動都重下 720MB）。第 18 章那邊有更多這個開關的細節。

5. Skill 裝了但 AI 看不見

   症狀：pi install 說裝成功了，但你在對話裡 AI 就是不會叫。
   原因：Skill 發現流程只在新 session 開始時跑一次——你的舊 session system prompt 沒有這個 skill。
   解法：按「新對話」開新 session。還是看不到就 ls /data/pi-agent/skills/ 確認資料夾真的存在、cat SKILL.md 確認 frontmatter 的 name 跟 description 都在。frontmatter 格式錯誤（YAML 縮排錯之類）會讓整個 skill 被跳過。

常見問題