--- title: "Agent 獨立更新 — 設計文件 v1.1 (FR-172)" brand: "Guidant AI · **FR-172** 設計 v1.1" eyebrow: "FR-172 · 設計文件 v1.1 · 2026-11-03 · 實作中異動" h1: "設計 v1.1：190 實測後的異動" subtitle: "對照 v1.0（design.md，2026-11-01 定稿）；推翻 D9，其餘決策不變" lede: "🔴 **這份只記 v1.0 定稿後、實作與 190 實測期間對設計本身做的改動。** 推翻一條（D9 兩步改一步），補定六條（維護模式、主控台立即檢查、更新包清理、同版重套、測試包出包、升級中鎖畫面）。v1.0 原文保留在 [design.md](design.md) 不動。現況（版號、程式、流程）看 [FINAL-SPEC.md](FINAL-SPEC.md)。" chips: [ {text: "v1.0 → v1.1", kind: accent}, {text: "推翻 D9", kind: warn}, {text: "補定 6 條", kind: accent}, {text: "2026-11-03 結案", kind: ok}, ] footer: "FR-172 設計文件 v1.1 · 2026-11-03 · v1.0 見 design.md · 現況見 FINAL-SPEC.md" --- ## 版本 {#versions nav="版本"} | 版本 | 日期 | 檔案 | 內容 | |---|---|---|---| | v1.0 | 2026-11-01 | [design.md](design.md) | 定稿：決策 D1～D12、兩條版本線、一輪更新時序圖、19 張卡 10 批 | | **v1.1** | 2026-11-03 | 本頁 | 190 實測 24 條回饋後開修正案 FR-172.1（10 張卡 3 批）；推翻 D9；補定維護模式、立即檢查、更新包清理、同版重套、測試包出包、鎖畫面時機 | --- ## 1. 為什麼有 v1.1 {#why nav="為什麼"} v1.0 的 19 張卡做完、出 1.28.0／Agent 1.5.0 後，決策者在 190 實際升級三輪，提出 24 條回饋（`handoff/190-test-feedback.md`）。其中大部分是文案與版面，但有六件是設計層的： - **兩步更新太麻煩**：v1.0 D9 定「預先下載 → 更新選取的台」兩步，決策者實測後要一步完成。 - **升級中 Agent 照常收工作、主控台照常可點**：v1.0 沒定「升級中」狀態，換容器那一刻才斷。 - **主控台「立即檢查」不會真的查**：v1.0 只讓主控台讀主系統上次的結果，新版發布了主控台仍說「已是最新」。 - **更新包一直堆**：主系統的 Agent 包只在下載新包時才清；主系統自己的升級包成功後也留著。 - **190 升到最新後就沒有東西可測**：每看一次升級畫面就要再出一版。 - **SeaweedFS 殭屍行程**：健康檢查每 10 秒留一個殭屍，約 3 小時撞到行程數上限。 --- ## 2. 決策異動 {#decisions nav="決策異動"} | # | v1.0 | v1.1 | 理由 | 決策者裁示 | |---|---|---|---|---| | **D9（推翻）** | Agent 區「預先下載 → 更新選取的台」兩步，勾選框下載完才出現 | **一步完成**：一開始就能勾選；按「更新選取的 N 台到 X」時，主系統手上沒有 X 的包就先下載（有進度、可取消），下載完自動推；「預先下載」保留為選用 | 兩步的理由（誰按、何時下載要有紀錄）改由下載稽核記按的人滿足，不必拆兩步 | 2026-11-03 | | 補定 | — | **「手上有包」不等於「手上是最新」**：判斷能不能直接推，要比「手上的包」與「上次檢查到、相容的最新版」，手上較舊就先下載。Agent 主控台回「有沒有新版」也用同一個判斷 | 主系統留著舊包時，只看「有沒有包」會拿舊包推，每台都回「沒有落後」 | 2026-11-03（190 實測） | | 補定 | — | **下載中再有人按更新，併進待推清單、不覆蓋**：每筆各記自己的台、排程時間與操作者，下載完逐筆推 | 覆蓋的話，更新中心勾 5 台下載中、Agent 主控台按 1 台，5 台就不會被推 | 2026-11-03（自動資安檢查） | | 補定 | — | **Agent 升級中＝維護模式**：一收到 `/update`（含下載中、等工作做完、主機在跑）就停收新工作；主控台整頁鎖住只顯示進度，完成自動恢復、不必重新登入（session 落地） | 升級中還能派工、主控台還能點，換容器時斷線 | 2026-11-03 | | 補定 | — | **主控台「立即檢查」＝請主系統當下查更新站**（全機 5 分鐘節流）；與主系統斷線時只給離線上傳 | 新版發布後主控台仍說「已是最新」 | 2026-11-03 | | 補定 | v1.0 D7：保留「各台最舊＋最新」兩份，下載時才清 | **整批推送全部成功後就清**用不到的 Agent 包；主系統自己升級成功後 `incoming/` 只留清單（重試會重新下載） | 兩版包各 1.7 GB 一直佔著 | 2026-11-03 | | 補定 | — | **測試機同版重套**：兩個開關都開才放行——主系統 `PRODUCT_UPDATE_ALLOW_SAME_VERSION=1`（`guidant.env`，主機升級腳本也讀）、Agent `AGENT_UPDATE_ALLOW_SAME_VERSION=1`（Agent `.env`，compose 轉進容器，主機升級腳本也讀）；降版、跨主版號照擋；**任何出貨範本都不放這兩個鍵** | 測試機升到最新後要能重看升級流程，不必一直出新版 | 2026-11-03 | | 補定 | — | SeaweedFS 兩個容器 `init: true`（docker 的 tini 當 PID 1 收殭屍），`pids_limit` 留作保險 | PID 1 是 weed 不收殭屍 | 2026-11-03 | | 補定 | — | **內部測試包略過 SBOM 與弱點掃描**：主系統綁 `--skip-prod-key-check`、Agent 用 `--internal-test`；正式包不帶就一定會掃，沒有單獨關掉掃描的旗標 | 測試包每次多等約 9 分鐘 | 2026-11-03 | | 補定 | — | 主系統發動更新時，開著的 Agent 主控台**最慢 30 秒**才鎖（主控台平常 30 秒問一次狀態）；在主控台自己按的當下就鎖 | 要即時就得做 Agent 主動推給瀏覽器的通道，划不來 | 2026-11-03「先這樣」 | v1.0 其餘決策（D1～D8、D10～D12、Agent 不連外網、不做舊客戶過渡）**一條都沒有推翻**。 --- ## 3. 拆卡異動 {#cards nav="拆卡異動"} v1.0 的 19 張卡（CM-3402～3420）全部完成。修正另開獨立母卡 **CM-3469（FR-172.1）**，不掛在 CM-3401 底下（工作坊只派「母卡欄為空」的卡）： | 批 | 卡 | Repo | 做什麼 | |---|---|---|---| | 1 | F-1 CM-3470 | Agent | SeaweedFS `init: true` | | 1 | F-2 CM-3471 | BE | 一步更新（沒包先下載再推）、下載進度、整批成功清包、主系統升級成功只留清單 | | 1 | F-3 CM-3472 | FE | 更新中心文案、全頁遮罩、升級完返回不白畫面、更新紀錄可下載升級 log | | 1 | F-4 CM-3473 | Agent | 升級中停收工作、session 落地免重登、立即檢查請主系統查站 | | 2 | F-5 CM-3474 | FE | Agent 區一開始可勾、一步更新、下載進度與取消、按鈕排版同主系統 | | 2 | F-6 CM-3475 | FE | Agent 主控台更新頁改版、全視窗鎖定、斷線只給離線上傳 | | 2 | F-7 CM-3476 | BE | Agent 升級中標記、主控台立即檢查端點（節流）、每台步驟、主系統升級成功可下載 log | | 3 | T-1 CM-3477 | BE | 同版重套（主系統端）＋主機升級單讀開關 | | 3 | T-2 CM-3478 | Agent | 同版重套（Agent 端）＋主機升級單讀開關＋compose 轉傳開關 | | 3 | T-3 CM-3479 | FE | 三處「重新套用」按鈕 | 190 實測又抓到的三件（主系統留舊包推不出去、主控台同根因、8444 握手卡住導致強制重新整理沒 CSS）併在 F-2、F-6、F-4 的範圍內修，沒有另開卡。 --- ## 4. 版號 {#versions-shipped nav="版號"} | | 主系統 | Agent | |---|---|---| | v1.0 預定 | 1.28.0 | 1.5.0 | | 實際出到 | 1.28.3 | 1.5.5 | | 中間版用途 | 1.28.1 只換版號測升級；1.28.2 FR-172.1 批 1～2；1.28.3 批 3＋190 實測修正 | 1.5.1、1.5.2 只換版號測升級；1.5.3 批 1～2；1.5.4 批 3；1.5.5 主機升級單同版放行 | 全部是內部測試包、測試章簽。**正式章／Vault 簽的第一版留給 FR-173（1.29）**。 --- ## 5. 影響後續案 {#impact nav="影響"} - **FR-173 出版管線**：Agent CI（C-2）要沿用 `--internal-test`，不要另開同義旗標；主系統封包已改多核壓縮、釘版第三方 image 匯出檔以 image ID 快取，CI runner 要把 `.build/image-cache/` 放在持久目錄才有效。 - **189 POC**：仍是 1.27.x，升 1.28.x 時 Agent 要手動升一次（1.4.x 沒有 `/update` 端點）。