- 日期：2026-09-03（user 於 FR-072 錄影片④實測 agent 包 0.2.31 時提出）
- 狀態：Phase 0 白話需求；design.md 由分析棒產出（方案對照）
- 鐵證：CM-1533 出 0.2.32 換版時實際踩到——新目錄首裝＝新 compose project，舊容器佔固定 container_name 導致新版建不出，installer fallback 把失敗讀成成功；新 volume 空 → 憑證消失 → 雲端 409 拒新註冊。runner 手動搬憑證救回。
§1
現況（0.2.31，190 實查）
- 客戶解 tar.gz 到家目錄，在解壓目錄內
sudo ./install.sh
- 解壓目錄＝安裝目錄：compose、.env（token＋儲存憑證，600）、certs-in/、content/、factory/、install-*.log 全在裡面；
/usr/local/bin/guidant-agent-compose 指回該目錄
- 完成畫面要特別印「🔴 請勿刪除」——設計缺陷的訊號
- 對照主產品：
/srv/guidant-ai（資料）＋/etc/guidant-ai/install.conf（設定）＋/usr/local/bin/guidant（CLI），解壓目錄用完可刪
§2
問題
- 客戶直覺「解壓目錄＝暫存」，裝完順手刪 → compose/.env/憑證/profile 全沒，CLI 失效
- 家目錄屬個別使用者：帳號停用/家目錄清理/權限變更都波及服務
- 升級路徑不清：新版解到另一目錄，舊 .env/憑證怎麼接手？（prev_* 沿用邏輯依賴「舊目錄還在」）；且 CM-1533 證明「新目錄首裝」會撞固定 container_name 靜默失敗
§3
期望（user）
- 安裝目錄固定系統路徑（
/srv/guidant-agent 或 /opt/guidant-agent）、設定 /etc/guidant-agent/、CLI 指固定路徑
- install.sh 從解壓目錄搬/複製需要的檔，解壓目錄與 tar.gz 用完可刪
- 升級＝解新包 → install.sh 偵測既有安裝 → 沿用 .env/憑證/volume → 換 image
- uninstall 對應調整；FR-072
reset-190.sh 探測/清理路徑同步（已預留 /etc/guidant-agent* /opt/guidant-agent /var/lib/guidant-agent /home/*/guidant-agent-compose-*）
- 相容：舊形態已裝客戶要能被新 install.sh 偵測並遷移
§4
分析棒要產出（design.md）
- 方案選項：目錄落點（/srv vs /opt）、搬遷 vs 就地、升級/遷移策略（含 CM-1533 的 container_name 撞名與 volume 接手）
- 影響範圍：agent 包打包腳本（源碼在 evidence-agent repo
deploy/；BE repo grep guidant-agent-compose）、BE repo
- 文件影響：
docs/user-manual/agent/03-install.md、07-upgrade.md、onprem/10-optional-features.md §10.5、FR-072 影片④
- 順帶：CM-1533 runner 建議的兩條——installer ⑥ fallback 補「容器 image tag == 本次要裝 tag」判定；換版正規路徑該是
upgrade 子命令而非新目錄首裝（文件是否引導到位）
§5
座標
- agent 源碼：
~/Projects/Billows/Audit-Manager/evidence-agent/deploy/（install.sh／docker-compose.yml／README）
- 190 現有 0.2.32 安裝可實查（
ssh guidantai@192.168.50.190，唯讀）；0.2.31 舊目錄同在
- 主產品 installer 範本：BE
scripts/installer/install.sh（資料目錄/etc/CLI 三分離＋沿用模式＋upgrade）