↑ 需求首頁 ⌂ 需求中心

FR-172 交接現況（STATE）

這份是 living 檔：每棒就地 Edit，只描述「此刻」。歷史脈絡看同資料夾的 FR-172-LOG.md。

項目 值
最後更新 2026-11-03 17:1x（FR-172 結案：190 實測通過，決策者裁 172 系列卡全收 Done，下一步走 FR-173）
branch 五個 repo 皆 feature/FR-172（工作坊分支已全部合回）；FR-173 也在這支（決策者裁）
母案卡 CM-3401 Done（含 S-4 CM-3420）；修正母卡 CM-3469 Done（FR-172.1，CM-3470～3479 全 Done）
本棒角色 發版首腦（S-4 由首腦接手，不再派回工作坊）
階段 171、172、172.1、174 結案；173 已開卡未派（CM-3462），決策者裁直接往 173 走
接手前必讀 §0

🧭 原始需求 / WHY

這節寫一次，之後各棒不動。

決策者原話（2026-11-01，189 推 Agent 1.4.8 時）：主系統跟 Agent 要分開來，不要像現在都包在同一包；要可以各別分開更新；Agent 那邊也要有更新中心，可以離線更新或跟主系統發動更新需求；R2 上面的安裝包要分開來；不要再用心跳帶資料。

本 session 開場追加（2026-11-01）：①出版分開，CI、R2 路徑與檔名分開；②Agent 獨立更新、Agent UI 有更新功能、可離線更新；③更新中心 Agent 區的狀態與進度要跟主系統一樣看得到下載、各站點進度、成敗；④不要再用心跳送指令；⑤與 FR-171 一起分析分工。

已裁四件：Agent 不直接連更新站；主控台發動更新＝主系統幫這一台更新；171 與 172 一起看一起拍板；172 要附雛形。

目標長什麼樣：見 discussion.md §3。

本棒在大圖的位置：第 1 棒，接 FR-167 收口後留的需求草稿（已搬進本資料夾 requirement-notes.md）與 FR-171 第 1 棒的討論稿 v1。

§0 接手讀序

  1. 本檔 🧭 WHY 節
  2. discussion.md 全讀（§0 概述、§3 目標設計、§4 與 171 分工、§5 D1～D12）
  3. prototype/index.html 點過十頁
  4. FR-171 discussion.md v2（§5.3 主題 B 改法、§7.5 與 172 分工、D13）
  5. 本檔 §2 已定裁示、§3 下一步
  6. 細節才開：requirement-notes.md（心跳夾帶八種盤點）、FR-167 agent-rollout-spec.md、update-site-schema-spec.md、release-signing-spec.md

冷接自檢：①Agent 包現在怎麼走到客戶 Agent 主機（五段，哪一段掛在主系統）？②172 直接用 171 的哪三樣？③為什麼 Agent 的章要另一個 payload_type？④P3／P4 為什麼要等 171 批 2？

§1 當前狀態（2026-11-03 17:1x）

三案

案 狀態
FR-171 通訊重整 ✅ 結案（工作坊 31、34 closed），已在 feature/FR-172
FR-174 網址型 Profile 存檔 ✅ 結案（工作坊 33 closed）；出貨基線已含 dev-sec 兩列系統檔
FR-172 Agent 獨立更新 ✅ 結案（CM-3401、修正案 CM-3469 皆 Done）；190 實測通過
FR-173 出版管線 開卡未派：母卡 CM-3462、子卡 CM-3463～3468；見 FR-173 STATE

合回與推送

repo feature/FR-172 HEAD 遠端
BE 9c1539491（1.28.3） 已推
FE b4463557（1.28.3） 已推
Agent 9296bd2／cd3a1f9（1.5.5） 已推
jedi 套件 bc38f89a 已推
update-center e5d63dc 沒有遠端，只合

出包（188，皆 --skip-prod-key-check 內部測試包）

版本 路徑 sha256 備註
主系統 1.28.0 /opt/guidant-ai-be/.build/bundle/guidant-ai-1.28.0.tar.gz 252e52d4…f92c 開包驗過：無 agent/、release-keys 三把正式章、無測試章
主系統 1.28.1 同目錄 guidant-ai-1.28.1.tar.gz 250e9212…c64c 沿用 1.28.0 映像只換版號（runbook 2.5），測升級用
Agent 1.5.0 /opt/guidant-ai-agent/.build/compose/guidant-agent-compose-1.5.0.tar.gz ded181ed…4972 版本說明 5 條（映像內 manifest 也是 5 條）；映像 release-keys 與 BE 一致。第一顆壞包（說明 0 條）改名 .BAD-notes0 保留
Agent 1.5.1 同目錄 …-1.5.1.tar.gz efede01c…6175 只換版號
Agent 1.5.2 同目錄 …-1.5.2.tar.gz 683bda8d…39ef 只換版號；離線上傳檔在 Mac ~/Projects/Billows/Audit-Manager/.fr167-dev/offline/agent-1.5.2/guidant-agent-1.5.2.offline.tar.gz
主系統 1.28.2 /opt/guidant-ai-be/.build/bundle/guidant-ai-1.28.2.tar.gz 8e365e7f…68eda FR-172.1 七張合回後完整 build
Agent 1.5.3 /opt/guidant-ai-agent/.build/compose/guidant-agent-compose-1.5.3.tar.gz e85b86d9…166a FR-172.1；版本說明 4 條；SeaweedFS init: true
主系統 1.28.3 /opt/guidant-ai-be/.build/bundle/guidant-ai-1.28.3.tar.gz 96c9da16…20bd 同版重套＋Agent 區舊包先下載；無 agent/、三把正式章
Agent 1.5.4 /opt/guidant-ai-agent/.build/compose/guidant-agent-compose-1.5.4.tar.gz 7209f72f…2aac 同版開關轉進容器、8444 握手修正、主控台重新套用
Agent 1.5.5 同目錄 …-1.5.5.tar.gz 55ff08d3…6704a 主機升級單同版放行；--internal-test 首包（15 分 52 秒）

出包途中修的三件（都已推）：Agent RELEASE_NOTES.md 標題被吃掉致說明 0 條（6760914）；開機補登金鑰登記簿沒有 app context、新裝第一次開機留 Traceback（088ca2b75）；出包幽靈選單比對表補 agent-keys（96d4e23e7）。

更新站（update-center，正式 guidantai-update.jedicotech.com）

  • 已部署新版（兩條版本線，product 必填）；D1 套了 0005，套前備份 ~/backup/update-center-d1-20261102_2253-before-0005.sql。
  • 🔴 188 STG、189 POC 是 1.27.x，不帶 product，更新中心「檢查新版」會失敗，直到升上 1.28.0（決策者 2026-11-02 裁照設計部署）。
  • D1 現況：主系統 1.28.1、1.28.2、1.28.3 published；Agent 1.5.1～1.5.5 published。全部用測試章 b91819f86eb4b4f8 簽。1.28.0 與 Agent 1.5.0 沒上站（190 離線升）。正式章／Vault 簽的第一版留給 FR-173（1.29）。
  • 測試期發布腳本：Mac ~/Projects/Billows/Audit-Manager/.fr167-dev/publish/publish2.sh host|agent <版>（STATUS=draft 只登記），簽章 sign/sign-release2.ts，Agent 離線檔 sign/make-agent-offline.ts（不入版控）。

190 測試機

項 狀態
主系統 1.28.3（11-03 15:48 指令升級，八步皆 0）；/etc/guidant/release-keys/ 四把：測試章＋三把正式章
Agent 1.5.5（1.5.4→1.5.5 由更新中心不預先下載直接推、自動下載成功；同版重套 1.5.5 成功）；SeaweedFS init: true 後無殭屍
同版重套開關（只在 190） /srv/guidant-ai/guidant.env PRODUCT_UPDATE_ALLOW_SAME_VERSION=1、/srv/guidant-ai-agent/.env AGENT_UPDATE_ALLOW_SAME_VERSION=1；改前備份 .bak-20261103-160922。要關就刪這兩行，主系統 sudo guidantai start、Agent sudo guidant-agent-compose start

為什麼 Agent 要手動升一次：1.28.0 只用 FR-171 的 POST /update 直推升級、心跳不再帶升級指令；1.4.x 沒有這支端點，主系統推不動。1.4.7 對 1.28.0 心跳 401→重註冊循環，是預期的。189 的 Agent（1.4.7／1.4.8）上 1.28.0 時也要手動升一次。

驗章規則（查證過）

主系統驗主系統包與 Agent 包、主機升級腳本、Agent 主控台離線上傳，全部只認本機已裝的公鑰，不拿包內公鑰驗自己。所以 188／189／190 要先裝上 1.28.0 才認得正式章與 Vault 章（1.29 用 Vault 簽時不能跳過 1.28.0）；用 1.28.0 全新安裝的機器不認測試章，但新裝不經線上驗章，下一次線上升級是 1.29（正式章／Vault）。Agent 收主系統推送只核大小與 sha256（數字來自主系統驗過的清單），主機端另用舊版 Agent 驗新版程式樹的完整性章（另一套，與發布章無關）。

§2 已定裁示（不要重新討論）

裁示 何時 誰
Agent 不直接連更新站；包只從主系統拿、離線靠主控台上傳 2026-11-01 決策者
Agent 主控台「發動更新」＝主系統建單幫這一台下載並推，不是跳轉 2026-11-01 決策者
171 與 172 同週期一起拍板；兩個 FR、兩棵卡樹 2026-11-01 決策者
討論稿附可點雛形 2026-11-01 決策者
心跳不再帶任何訊息，只表存活 2026-11-01 決策者（FR-167 session）
FR-167 待辦 62（compose 標籤）不併本案 2026-11-01 決策者
CM-3410 H-5（待辦 61，CINC 網址型 Profile）暫緩、移出 FR-172，另開 FR-174（docs/features/FR-174-2611-url-profile-snapshot-sync/，已登記、需求紀錄已寫、未討論未開卡）；方向採 A 案：網址型匯入時下載內容存成 upload_files、該版改記檔案型、原網址存成「來源網址」欄。要改 jedi-detection 套件（推翻「網址型不落儲存」不變式）＋migration＋環境卡，約三張卡。代價：189 Demo 的 CINC 下拉在新案前仍空 2026-11-01 決策者（工作坊首腦回報後）
出貨前無客戶：所有舊版相容、備援期、過渡搬包全拿掉 2026-11-01 決策者
雛形定稿：Agent 主控台文案「開始更新／有新版本」；Agent 進度與主系統更新中同一套 .steplist 直式清單（E-5、G-3 卡已 append） 2026-11-01 決策者
1.28.0 先出（Mac 手簽），FR-173 跟 1.29；S-4 把 Vault 公鑰 05086455d42ca0d6.pub 放進 scripts/installer/release-keys/ 並列入 PROD_KIDS，1.29 才能換 Vault 簽（裁示已 append 到 CM-3420） 2026-11-02 決策者
1.28.0 用測試章簽、包內只帶三把正式章；測試章公鑰移出 release-keys/；出貨基線由首腦重產 2026-11-02 決策者
173 與 172 共用 feature/FR-172；173 開卡不派 2026-11-02 決策者
S-4 由首腦接手到底、不派回工作坊；放行部署更新站（接受 188／189 升 1.28.0 前檢查新版失敗）、190 升 1.28.0＋手動升 Agent、出 1.28.1／Agent 1.5.1／1.5.2 測升級（1.5.2 先草稿，主系統端測完再發） 2026-11-02 決策者

§3 下一步

FR-172 已結案，下一步走 FR-173 出版管線（docs/features/FR-173-2611-release-pipeline/handoff/FR-173-STATE.md）。

留給後續的事（未開卡）

  • 189 POC 升級時機、release note 1.27.x～1.28.x 補寫：待裁。
  • 守衛測試 8 條紅（乾淨 HEAD 一樣紅，非本案造成）：test_route_guard_inventory 的 detection.remote-agent.upgrade 沒有守門端點登記（P-5 遺留）、test_agent_console_allow_cidr 缺 app context、兩條測試順序相依。
  • Agent 主控台由主系統發動更新時最慢 30 秒才鎖畫面（平常輪詢間隔）：決策者裁先這樣。
  • Agent 主控台背景輪詢 /update/status 會寫「看過更新頁」稽核（CM-3469 F-6 驗收時記，未修）。
  • 測試機只改主機腳本的修正無法只換 .sh：主機每次從現行 Agent 映像讀 install-lib/upgrade_order.sh，要驗就得出版；要不要做測試機本機覆寫，另議。

⚠️ 這節是建議清單，不是執行授權。

§4 待辦與風險

  • S-4 範圍（已做完）：主系統發布清單 release_json.sh 補 "product": "host"（否則 register-draft 400）；出貨基線重產（見 §3 第 4 條）；手冊三句（前門 CSP Agent 位址最多 5 分鐘生效、換鑰期間只發 Agent 不算新章生效、runbook 2.2 等 Agent 出包段搬走）；H-4 沒實點的「有新版本／已下載」兩態在 1.28.0 上補點。
  • 事件碼：主線 6249／6250 已被 FR-171 用掉，AGENT_BUNDLE_DOWNLOAD 改 6251（367c0bde7）。DEV system_logs 若有 H-2 實測留下的 6249 一筆，開發期資料不回填。
  • 離線上傳來源值：FE（H-4）約定 Agent 主控台離線上傳的 rollout source 用 offline；G-1／G-2 要用同一個字。
  • 套件鏡像測試：jedi-agent-protocol test_mirror::test_agent_sends_only_contract_keys 紅（找 Agent 舊心跳函式 _heartbeat_once，FR-170 搬家後沒跟上），P-1 前就紅、不屬 172 範圍。
  • 雛形十頁未開瀏覽器看（規範不開瀏覽器）；grep border-left 為 0。決策者若看到版面壞掉，先看 proto.css 是否與 FR-167 那份同步。
  • mermaid 兩張圖只靜態檢查首行 init。
  • requirement-notes.md 是從 docs/draft_requirement_spec/ git mv 過來的，內文仍是需求紀錄體（含「目前的做法」段），不是說明文件，拍板後不改寫。
  • FR-167 CM-3378 結案出包（1.27.11）裁等本案與 171 一起出。
  • 🔴 共用 .venv 會被卡改掉：卡工作區的 .venv 連到主資料夾那份，任何一張卡 poetry update 都會改到 8000 的環境（今天 171 E-0b、174 Z-1 各踩一次）。172 剩下的卡若要改套件版本，先要求小弟回報不要直接 update。已寫進 closing-and-handoff skill「runner 環境紀律」②；根治要改 agent-workshop（每個工作坊一份 venv），未提案。
  • 🔴 跨工作坊合回不自動：工作坊只把卡合回自己的 ws-<母卡>；要讓別的工作坊看到，要按該工作坊「合回」（要全部子卡 Done）。主 FR＋副 FR 的提議（主 FR 排先後、放行）決策者表示方向可以，未落地成規範。
  • jedi 套件 Z-6 改了程式碼但沒發版：protocol 0.2.0／remote-agent 1.12.1 在 Nexus 上仍帶 console_events 兩個沒人用的鍵，不影響執行，留給下次發版。
  • 指令端點錯誤格式不一致：/tasks、/restart、/update body 驗證錯回 {error}，其他端點回 {error_code, msg}；記在 FR-171 agent-api-spec.md。

§5 Pre-flight（唯讀）

cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
git status --short | grep -v "^??"; git log --oneline -3
ls docs/features/FR-172-2611-agent-independent-update/ docs/features/FR-172-2611-agent-independent-update/prototype/
grep -n "FR-172" docs/features/README.md | cut -c1-60
grep -n "需求討論稿 v2" docs/features/FR-171-2610-agent-command-channel/discussion.md | head -1

§6 環境座標

  • 本機 Agent：~/guidant-agent-local/start-agent.sh 連 DEV BE 8000。
  • 不碰 STG／POC。189 POC 的 Agent 是 1.4.8（121）／1.4.7（60.167，磁碟已清待重推）。
  • update-center repo：~/Projects/Billows/Audit-Manager/update-center/（TypeScript Worker，src/releases.ts 的 r2Key() 是 R2 路徑唯一拼法）。
  • Agent build 機 188 /opt/guidant-ai-agent，沒有 node；Agent repo 目前沒有 CI。

§7 行為規範提醒（輔助首腦）

直接拍板的：卡片範圍怎麼解讀、design 沒寫到但在已裁方向內的技術選擇、小弟回報「前置沒做」或撞檔時退回／改卡／調批、暫緩或放回卡片、補開漏掉的小卡、往卡上補說明、驗收爭議。 要停下問決策者的：推翻已裁決定（三案 design §1、本檔 §2）、超出 FR-171／172／173 範圍的需求、使用者看得到且雛形沒畫的畫面或文案、碰 STG／POC、推 main、卡片改 Done。 每個決定寫回對應卡片（append「輔助首腦裁示」段）與 STATE，工作坊首腦下一棒才讀得到。

  • 不開 subagent（決策者沒明說就不開）；探脈自己 grep。
  • 改卡內文先改 handoff/cards.py／gen_notion_cards.py，再 append 到 Notion，不手改。
  • 心跳不帶訊息、不做舊版相容是三案鐵律，小弟 diff 往心跳加欄位或留 deprecated 分支就是阻斷級。
  • 雛形與 FE 禁 border-left 粗邊框；資料區塊上下疊。
  • 回報白話、繁中；輸出裡有 token、Unseal Key 的行一律不貼、不寫進文件。
  • 決策者說「先不要急著寫文件」時就不寫，等令。