FR-066 檢測 Agent 安裝包 — 全案收口 SUMMARY（2026-08-23）

由 FR-066-LOG.md 八棒 block 濃縮產生，不憑記憶重建。歷史細節看 LOG，終態看 STATE，決策全文看 design.md §3。

為何立案：檢測 Agent（evidence-agent）的本職是量測宿主機——機器指紋（product_uuid / machine-id / MAC）在 docker 容器內讀不到或會漂移（已發生過 machine-id 空檔退回隨機 MAC 的指紋漂移事故），現行靠 collect-host-id.sh workaround 硬撐；而業界同類（Nessus / Qualys / Wazuh / Datadog）全部原生套件＋systemd 交付。所以立案目標是：Nuitka 編譯＋外部工具全包一顆 tarball，一鍵裝成 Linux systemd 原生服務。

主軸翻轉——立案要做原生版，收口出貨的是 compose 版。來龍去脈：.1~.3 把原生版整條做完（SQLite 化、自起 mTLS、tarball、install.sh、188 build 通關、123 真機驗收），但 .5（Rocky/RHEL）開卡時 PM 揭示 agent 的本源需求其實是跨網段證據存放（FR-039 儲存鏈）——客戶要的是「有 docker 的機器快速起一個帶內建儲存的 agent」，不是封閉網路裸機。於是 .6 立案：compose 形態＋SeaweedFS 內建儲存＋指紋二源化（拿掉容器內量不到的 MAC，改掛載可得的兩源）。.6 全系收完後決策者裁 D16：原生 tarball 暫不出貨、現階段一律 compose 版——原生開發成果保留不廢（封閉網路／無 docker 客戶出現時解凍），且原生期的產物（Nuitka 編譯、簽章、install.sh 積木）全部是 compose 版的地基，沒有白做。

最終出貨形態：guidant-agent-compose 一顆包通吃（install/upgrade 不分包，差 82MB seaweedfs image 不值得維護兩條路）——Nuitka 編譯產物＋SeaweedFS＋互動安裝程式＋configure-storage＋恢復出廠。Windows 三路線一日生死劇後全線凍結（D19），評估與實測資產留檔待客戶訊號。

程式面（evidence-agent feature/FR-066，0.2.27→0.2.28）：

• SQLite 化（T-1.1）：agent-db postgres 容器退役；擋點在 jedi-common session_scope() 無條件 SET LOCAL，走 B 案修套件（0.0.31 已發 Nexus，依 dialect 判斷、PG 路徑行為恆等）；storage_scope 欄位自癒改清單驅動
• 指紋二源化（T-6.1，D11 全域）：sha256(product_uuid|machine-id)，MAC 退場；撞號防護搬 BE enroll 端（豁免條件必須「憑 uid 認出」，不是「resolve 到同一列」）
• 自起 mTLS（T-3.1，D4）：nginx sidecar 退役，gunicorn/ssl 自起 8443；enrollment 全自動、TOFU 信任雲端自簽（T-3.5）
• Nuitka build 管線＋簽章（T-1.3/T-2.2/T-2.3）：188 編譯 6m29s、smoke 五項量尺；雙層 manifest（agent 層啟動 gate／bundle 層交付完整性）＋啟動驗章
• compose 互動安裝程式（T-6.6，D15）：照 FR-065 主產品模式問答引導，客戶不碰 docker 指令；八支維運子命令
• configure-storage 三型＋恢復出廠（T-6.5/T-6.7，D14）：內建 SeaweedFS／自有 S3／本地目錄，出廠快照 factory-defaults.env 一鍵恢復
• 升級一條指令：install.sh --upgrade（原生＝切 symlink；compose＝新包 upgrade，資料與憑證不動）

BE/FE 面（皆 feature/FR-066）：CM-937 心跳自報 capabilities（enroll 從不寫的申報鏈缺口）；CM-1322 基線補漏（stage_objects＋Profile 進基線＋哨兵斷言）；CM-1331 系統設定四頁守門分流；CM-1333 儲存設定「恢復系統內建儲存」端點＋FE 按鈕；CM-1317 時區分流（心跳統一 UTC／公告日期營運時區）。

文件面：design.md D1~D19 完整決策鏈；兩本安裝手冊（CM-1347 onprem 對齊 55 commit 落差＋CM-1299 agent 手冊 11 章：憑證三世界全景／資料保護責任／時鐘同步排錯；CM-1348 全 21 章白話化）；Windows 三報告（T-4.3 評估 windows-feasibility.md＋T-7.1 Docker Desktop 實測＋T-7.4 WSL 生死驗證）；T-6.2 防篡改宣稱邊界查證。

里程碑級 commits（全列見 LOG 各棒）：evidence-agent e6aff6a（SQLite 化）→265f5f8（.1 build 就緒）→0fc80c8（.1 收口）→fc9cd23 系（install.sh）→1132150（指紋二源）→dd62b00 系（互動安裝）→a89a701（交付包收斂一顆）；jedi-common ec3d4ee（0.0.31）；BE 7c037530（時區）／ffca7c41（恢復）；FE 1143e37（恢復按鈕）。

D1~D19 一行版（全文見 design.md §3）：

三次大翻轉：

1. .5 暫緩→.6 立案（第 6-7 棒）：Rocky/RHEL 開卡即被 PM 暫緩，同時揭示本源需求＝跨網段證據存放——整案重心從「封閉網路裸機」轉到「compose＋內建儲存」。
2. D16 原生凍結（第 8 棒）：原生做完但暫不出貨——這個方向性裁示前幾棒只有口頭、未落文件，第八棒靠決策者本人提醒才補立 D16。
3. D17→D18→D19 Windows 三日生死劇（第 8 棒續）：D17 Docker Desktop 先行→決策者實際使用發現登出全滅（engine 綁登入 session，無人值守出貨不可）→D18 原生服務版唯一路線→PM 轉向 B 案（WSL+engine 常駐）→T-7.4 生死驗證判死（WSL VM 閒置 60 秒凍結 userspace、四種挽救全滅）→PM 最終拍板 D19 全凍。現行解答：掃 Windows＝Linux agent CINC WinRM 遠端掃（既有功能）。

• 188（build 機）：.1 完整 build 通關＋smoke 五項量尺（量尺自身連抓三個假綠後才可信）；決策者親跑 smoke 撞出第 4 項假紅（CM-1309）。
• 123（真機，第 5 棒）：決策者親手走「compile→打包→搬機→裝→上線」全鏈，撞出三個只有真實部署才現形的缺口（自簽憑證 TOFU／installer PKI／時區判離線），當日全數立卡、兩張當日修復。OpenSCAP 首單（123 掃 151）再撞出 capability 申報鏈缺口＋基線補漏全案（第 6 棒當日全收，OpenSCAP/CINC/GCB 三工具首單全通）。
• 190（agent 驗收機）：compose 兩形態安裝／升級／恢復循環實測；onepack 首裝全鏈重驗列殘項（1335 未驗假設）。
• 191（落地版 PRD 驗收機）：1.15.0 升級六容器 healthy；四頁守門＋恢復循環決策者手測通過；break-glass 收回 DB 實查確認。
• Windows 真機兩份實測結論：T-7.1（161→160）＝Docker Desktop 全鏈可通但登出全滅（P0，僅可 demo）；T-7.4＝WSL 常駐路線判死（觀察者效應：wsl.exe 探測會喚醒 distro、把死的看成活的——排除此干擾後確認凍結）。

1. runner 查證推翻首腦開卡假設（CM-1317）：「8 小時差」是首腦 psql 查證方法錯誤，真 bug 方向相反（TZ=UTC 假活）。開卡的「實測證據」也可能是查證方法的假象；被打臉後的下一個裁示要加倍謹慎（backfill 裁示同樣被修正）。「查證後再修」派工模式全勝。
2. 驗收環境打折會掩蓋真缺口（T-6.6）：「乾淨機」在有既存 stack 的 188 模擬，機上恰有 seaweedfs image→「第三方 image 沒進包、封閉網路裝不起」被掩蓋，決策者提問才暴露。已固化 CLAUDE.md「打折要當場講明」。
3. 批次驗證 vs 逐項（T-6.6 八支子命令七輪）：逐項驗一輪只暴露一個問題，其中五個在同一輪就能全部看到。已固化 CLAUDE.md「先整批跑完收集所有失敗，再一次修完再驗一輪」。
4. 探路卡的錢極值（T-7.1/T-7.4）：兩張各一天的小卡擋下 10~30 人日級的錯誤投資。T-7.4 的觀察者效應發現是本 arc 品質最高的實測之一。
5. 決策者的實際使用是最強測試：登出全滅是決策者日常操作撞出來的——評估文件與探路清單都沒排進這一項；123 真機三缺口、smoke 假紅同理。arc 尾聲必排真機真環境親測，越早越好。
6. 雙實作漂移（D11 註）：同一套邏輯存在兩份實作（Python↔︎shell 複刻 ctl、演算法↔︎守門豁免），改一邊必須指名另一邊，且對真端點／真機各跑一次——單元 fixture 會繞過真實解析路徑。
7. 口頭裁示不落文件會斷鏈：「原生暫不出貨」這種案級方向性翻盤，前幾棒未收進 LOG/design，第八棒靠決策者提醒才補 D16。方向性裁示當場落 LOG 應成慣例。
8. 手冊受眾校準要先給白話範本：CM-1348 決策者初審「看不懂」整本打回，21 章返工一輪——派工 prompt 首版就該附文風範本（每章導言＋術語括號註解＋指令前後白話句）。
9. 文件站產物要實點連結（CM-1349）：HTML 內 .md 互連未改寫致連結全壞——build 完要實際點過才算驗，且修法是修渲染層不是修文件。
10. 「沒看到壞消息 ≠ 好消息」（第 3 棒三連發＋第 6 棒三連發）：驗證器掃 0 個檔仍印通過、檔案移走仍 PASS、storage-seed 非空靜默跳過——任何驗證器不做突變測試等於沒驗；靜默失敗的共同解法＝把斷言埋進建庫與打包，缺料當場中止。
11. 需求的分岔要早問：「要掃 Windows」vs「agent 要裝在 Windows」是兩個需求，前者既有功能已解——早問可能省掉整條 .7/.8。同型：D13（首腦誤判新功能）、D15（誤判受眾），「給誰用」比「做什麼」更容易想當然。
12. 交接與收尾紀律：第 3 棒沒補 STATE/LOG 就收工，第 4 棒花一整段反推補帳；runner 收尾漏是系統性的（連兩棒 code 全好但回寫全漏）→ skill 補「開工標 In progress」＋「收工硬檢查四項」。

殘項（各自掛置，不擋收口——照母卡 CM-1284 收口段）：

• 暫緩：CM-1298（T-4.1 原生乾淨機＋斷網驗證——D3 立案根基至今無人跑過，決策者裁先不管，解凍或封閉網路客戶出現時再議）／.5 EL 四卡（1318~1321，PM 最後做）／.7+.8 Windows 全卡樹（1336~1345，D19 凍結、資產保留，解凍首步＝Windows build 機佈建）
• 等 PM：CM-1329（web 下發儲存設定——資安題：客戶儲存憑證進不進雲端 DB）
• 移轉他線：PROD 簽章鑰四步組＋窄驗證（現有包皆 --skip-prod-key-check 內部測試包，正式交付前必辦；移入 189 遷移線）；agent 自更新 follow-up（觸發＝單客戶十台級）
• 環境收尾：190/191 臨時免密 sudo 收回待裁；DEV 測試資料清理；demo 用 160 需有人登入帶 Docker Desktop

下一戰線（決策者 2026-08-23 拍板順序）：①決策者未揭露之「發版前要先處理的需求」（下一棒開工先問）→ ②merge feature/FR-066→main＋v1.16.0 進版（version-bump skill 全套；收斂 191 的 1.15.0 內容超前不一致）→ ③PROD 簽章鑰 → ④189 遷 bundle 形態（pg_dump→裝 bundle→灌回→upgrade；POC 異動等當次明示；兼 FR-065 T-4.2 補驗②）→ ⑤FR-065 母卡 CM-1189 收口。

母卡 CM-1284：Done（2026-08-23 收口，卡上有完整交付清單＋殘項）。全案累計 65 張卡（1284~1349 連號段＋復活舊卡 CM-937）：

註：張數以卡號段推算；逐卡權威狀態以 Notion 為準（python3 scripts/notion_case.py get CM-<n>）。

檔案座標：STATE FR-066-STATE.md（終態）／LOG FR-066-LOG.md（八棒全軌跡）／design ../design.md（D1~D19）／Windows 三報告 ../windows-feasibility.md＋T-7.1/T-7.4 報告／手冊 docs/user-manual/onprem/＋agent/。