---
title: "FR-066 檢測 Agent 安裝包 — 全案收口 SUMMARY"
brand: "Guidant AI · **FR-066** 檢測 Agent 安裝包"
eyebrow: "FR-066 · 全案收口 SUMMARY · 2026-08-23"
h1: "FR-066 全案收口 SUMMARY"
lede: "八棒（2026-08-18~23）走完立案到收口：由 LOG 逐 block 濃縮——一句話與成果、交付清單、D1~D19 決策軌跡與三次大翻轉、驗收紀錄、教訓彙整、殘項與下一戰線、Notion 卡總帳。"
chips: [
  {text: "母卡 CM-1284 Done（2026-08-23）", kind: ok},
  {text: "出貨形態：compose 一顆包通吃（D16）", kind: accent},
  {text: "Windows 全線凍結（D19）", kind: warn},
  {text: "來源：FR-066-LOG.md 八棒 block", kind: plain}
]
footer: "FR-066 · 全案收口 SUMMARY · 2026-08-23 · 由 FR-066-LOG.md 濃縮產生"
---

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

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

## 1. 一句話與成果

**為何立案**：檢測 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）**，評估與實測資產留檔待客戶訊號。

## 2. 交付清單

**程式面（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`（恢復按鈕）。

## 3. 決策軌跡摘要

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

| # | 一行 |
|---|------|
| D1 | Nuitka standalone → tarball → systemd（不用 onefile：啟動慢＋逐檔驗章難做） |
| D2 | agent-db postgres 退役換 SQLite（只服務一張表；Q2 方言掃描前置守門） |
| D3 | 外部工具全包一顆 tarball、離線自足，~1GB+ 接受（封閉網路漏帶＝現場死局） |
| D4 | nginx sidecar 退役，agent gunicorn/ssl 自起 8443 mTLS |
| D5 | 設定＝agent.env（systemd EnvironmentFile），install.sh 問答三題生成 |
| D6 | 簽章瘦身版：build 期 manifest 簽章＋啟動驗章，不做 runtime 全家桶 |
| D7 | 升級＝versions/ ＋ current symlink；資料不隨版本走、無備份模型 |
| D8 | Windows 只出評估文件不實作（附錄初判非定案） |
| D9 | 指紋只做 Linux 直讀，不預抽 OS 抽象層；collect-host-id.sh 廢除 |
| D10 | EL（Rocky/RHEL）＝低 glibc 容器編譯（隨 .5 暫緩） |
| D11 | 指紋二源化全域（MAC 退場）；撞號防護＝BE enroll 端守門 |
| D12 | 雙形態單產線：同一顆 Nuitka 產物同一套簽章，build_all 兩出口 |
| D13 | 「使用 Agent 服務」＝FR-039 既有功能，BE/FE 零新功能 |
| D14 | 儲存設定 CLI 先做；web 下發開評估卡等 PM（資安題：憑證進不進雲端） |
| D15 | compose 版配互動安裝程式——受眾一線工程師，不假設會 docker |
| D16 | 出貨收斂：原生暫不出貨、一律 compose 版；交付包一顆通吃 |
| D17 | Windows Docker Desktop 路線先行（當日即被 T-7.1 推翻） |
| D18 | 原生 Windows 服務版為唯一出貨路線；code signing 階段策略（客戶在望買 OV） |
| D19 | Windows 全線凍結（PM）：Linux 為主，客戶真有需求再開卡 |

**三次大翻轉**：
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 遠端掃（既有功能）。

## 4. 驗收紀錄

- **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、把死的看成活的——排除此干擾後確認凍結）。

## 5. 教訓彙整（長期價值最高的一節）

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」＋「收工硬檢查四項」。

## 6. 殘項與下一戰線

**殘項**（各自掛置，不擋收口——照母卡 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 收口。

## 7. Notion 卡總帳

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

| 狀態 | 張數 | 明細 |
|------|------|------|
| Done | 43 | 母卡 1284；子需求 1285（.1）/1323（.6）；.1 系 1289~1291＋追加 1303~1309；.2/.3 系 1292~1297＋追加 1310~1315；真機缺口 1316/1317；.6 系 1324~1328/1330~1335；基線 937/1322；Windows 探路 1337/1346；手冊四卡 1347/1299/1348/1349；FR-066.4 收斂項 1300（Windows 評估） |
| 暫緩 | 15 | 1298（T-4.1 隨 D16）；1318~1321（.5 EL）；1336/1338/1339（.7）；1340~1345（.8）＋FR-065 側 1265（由本案三份文件取代） |
| 等 PM | 1 | 1329（web 下發儲存設定） |
| 收斂註記 | — | 1286/1287/1288（子需求 .2/.3/.4）隨母卡收口一併收束；1299 曾暫緩後復活（Linux only 範圍）收 Done |

> 註：張數以卡號段推算；逐卡權威狀態以 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/`。