# FR-066 檢測 Agent 原生安裝包 — STATE（living，只描述此刻）

> **這份是 living 檔**：每棒就地 Edit，只描述「此刻」。歷史脈絡與決策軌跡見同資料夾 `FR-066-LOG.md`。

| 項目 | 值 |
|------|-----|
| 最後更新 | 2026-08-23（**全案收口**：母卡 CM-1284 收 Done；FR-065 側 1246/1264/1275 同日收。本檔轉歷史紀錄，下一戰線=v1.16.0→PROD 鑰→189 遷移，接手讀 §3） |
| branch | evidence-agent `feature/FR-066`（主要 code 標的）／BE＋FE `feature/FR-066`（文件＋.6 起含主產品修正：1331 守門/1333 恢復預設） |
| 母案卡 | CM-1284（**Done，2026-08-23 收口**） |
| 子需求卡 | 1285（.1，Done）／1286（.2，修正待驗證）／1287（.3，修正待驗證）／1288（.4，In progress）／1318（.5，**暫緩**）／1323（.6，**Done**） |
| .6 系卡 | 1324~1328/1330~1335 **全 Done**（決策者 2026-08-22 裁示 .6 通過）；1329（web 下發，等 PM，Not started） |
| 早期追加卡 | 1303/1304（第二棒）；1305~1309（第三棒，皆完成）；1316/1317（真機三缺口，修正待驗證） |
| .4 系卡 | 1298（T-4.1，**暫緩**——隨 D16 原生凍結）／1299（T-4.2 手冊，範圍改 compose 為主）／1300（T-4.3 Windows 評估，修正待驗證，首腦已親驗合格） |
| Notion CLI | `python3 scripts/notion_case.py get/status/append/query`（在 BE repo 跑；見 memory reference_notion_case_cli） |
| 接手前必讀 | §0 讀序 |

## 🧭 原始需求 / WHY

> 這節寫一次，之後各棒不動（需求改案要在 LOG 記一筆）。

- **要解決什麼**：檢測 Agent（evidence-agent repo，v0.2.27）目前以 docker 三容器（agent＋agent-db postgres＋nginx mTLS sidecar）出貨，但 **agent 的本職是量測宿主機**——機器指紋（`/sys/class/dmi/id/product_uuid`、`/etc/machine-id`、主網卡 MAC）在容器內**讀不到或會漂移**（已發生 Debian base image machine-id 空檔退回隨機 MAC 的指紋漂移事故），現行靠 `deploy/collect-host-id.sh` workaround 硬撐。業界同類（Nessus / Qualys / Wazuh / Datadog Agent）**全部原生套件＋systemd 交付**——貼宿主量測的產品，原生安裝就是行規。
- **目標模型**：agent 改 **Nuitka standalone 編譯**（原始碼不可見）＋外部檢測工具（CINC / sonar-scanner / LibreOffice＋中文字型…）**全包一顆 tarball**（~1GB+，已接受），`install.sh` 一鍵裝成 **Linux systemd 服務**；封閉網路（既定支援情境）離線完全自足。SQLite 取代 agent-db、agent 自起 TLS 取代 nginx sidecar、build 期 manifest 簽章＋啟動驗章（FR-064 泛用層瘦身複用）。
- **Windows 不實作**，只出評估文件與前提清單（D8；附錄有 2026-08-18 口頭初判，**非定案**）。
- **戰線位置**：落地版交付三部曲（FR-063 編譯／FR-064 防竄改／FR-065 installer，皆已收）之後的**獨立新戰線**——FR-065 期間決策者裁定「agent 安裝包另起新 FR、非 docker」，即本案。與 FR-065 殘項（PROD 鑰／T-4.2／收尾）**無依賴**，可平行。

## 角色定位

本 arc 首腦 session＝**分析決策／協調**：需求釐清、拍板、拆卡、派工單、親驗抽查（不信 runner 自報）。**實作全走 runner session**——派工只給卡號＋一句話，內容都在卡裡。**push 永遠 user 本人做**。

## §0 接手讀序

### 0.1 🔒 先懂需求 gate（全讀，讀完才能碰任何東西）
1. 本檔 🧭 WHY 節＋ §2 已定裁示
2. `docs/features/FR-066-2608-agent-native-installer/design.md` §2（分工概述）＋§3（D1–D9 決策表）＋§6（拆分表與 Q1–Q4 歸屬）全讀；要細節再開 §4/§5
3. `notion-fetch CM-1284`＋要派的對應子卡

### 0.2 現況與待辦
4. 本檔 §1 當前狀態、§3 下一步
5. `FR-066-LOG.md` 最後 2 個 block

### 0.3 ✅ 冷接自檢（答不出來回 0.1，不要碰任何東西）
1. 為什麼 agent 不能繼續用 docker 交付？（指紋量測在容器內讀不到／漂移＋業界行規）
2. D3 為什麼外部工具全包一顆 tarball、不做分層附加包？（封閉網路漏帶無法補救）
3. SQLite 檔為什麼落資料目錄、不能放版本目錄？（D7 升級＝切 symlink，資料要跨版本存活）
4. 本案改 code 的 repo 是哪個？（evidence-agent，不是 BE——BE 只放文件）

## §1 當前狀態（2026-08-22 晚，第八棒）

**D16 拍板：原生 tarball 暫不出貨、出貨一律 compose 版。.6 全系（1323~1328/1330~1335）收 Done；T-4.3 Windows 評估完成（1300 修正待驗證，首腦已親驗）；T-4.1 隨 D16 暫緩。**

| 面向 | 實況 |
|---|---|
| BE repo | HEAD `4d172cae`（CM-1300 Windows 評估文件），branch `feature/FR-066`；**領先 origin（4d172cae＋design/STATE/LOG 更新待 commit/push）** |
| FE repo | HEAD `1143e37`（CM-1333 恢復按鈕），`feature/FR-066` 與 origin 同步；工作樹乾淨 |
| evidence-agent | HEAD `a89a701`（CM-1335 交付包收斂一顆，已 push），`feature/FR-066` 與 origin 同步 |
| Notion 卡狀態 | **In progress**：CM-1284（母）、1288（.4）／**修正待驗證**：1286、1287（子需求，等總複測）、1293~1297（.2/.3 實作）、1316、1317、1300／**Done**：1285、1289~1292、1303~1309、**1323~1328、1330~1335（.6 全系）**／**Not started**：1299、1329／**暫緩**：1318~1321（.5）、**1298（T-4.1，隨 D16）** |
| 188 build 區 | HEAD `a89a701`；主產品包 `guidant-ai-1.15.0.tar.gz`（933MB，烙印 `429a4c21`）；agent onepack `guidant-agent-compose-0.2.28`（1375MB，sha256 `0b5d47f0…`，烙印 `6f86303`＋打包腳本 `a89a701`） |
| 190（agent 驗收機） | 0.2.28 舊制包跑動中；**待砍掉重裝**（用 onepack 包，驗首裝全鏈＋恢復循環＋upgrade 路徑）；onepack 已放 `~/guidant-agent-compose-0.2.28-onepack.tar.gz`；臨時免密 sudo 仍在（重裝後收） |
| 191（落地版 PRD 驗收機） | 1.15.0 已升級（commit `429a4c21`）、六容器 healthy；**blsadmin break-glass 已收回**（`is_super_admin=f`，第八棒 DB 實查）；四頁守門＋恢復循環決策者手測通過；臨時免密 sudo 是否收回待裁示 |
| PROD 簽章鑰 | 仍未生成——191 的包以 `--skip-prod-key-check` 產出，屬內部測試包不可交付客戶（FR-065 既有殘項） |


## §2 已定裁示（不要重新討論；完整理由與被排除方案見 design.md §3）

- **D1** Nuitka standalone（非 onefile）→ tarball → systemd（2026-08-18）
- **D2** agent-db（postgres:16）退役換 **SQLite**——現況只服務 jedi-file-upload `upload_files` 一張表；**Q2 PG 方言掃描是 T-1.1 前置守門**（2026-08-18）
- **D3** 外部工具**全包一顆 tarball**、離線自足，體積 ~1GB+ 已明示接受（2026-08-18）
- **D4** nginx sidecar 退役，agent 以 gunicorn/ssl 自起 8443 mTLS（2026-08-18）
- **D5** 設定＝`/etc/guidant-agent/agent.env`（systemd EnvironmentFile），install.sh 互動三題生成；enrollment 既有流程零改（2026-08-18）
- **D6** 簽章防竄改**瘦身版**：build 期 manifest 簽章＋啟動驗章（FR-064 泛用層加 `agent_manifest` type），不做 runtime 抽查／lockdown（2026-08-18）
- **D7** 升級＝`versions/<ver>/`＋`current` symlink 切換；SQLite／憑證在資料目錄不隨版本走；無備份模型（agent 無 migration）（2026-08-18）
- **D8** Windows **只出評估文件不實作**；design.md D8 附錄有口頭可行性**初判（非定案）**，是 T-4.3 起點素材（2026-08-18）
- **D9** 指紋只做 Linux 原生直讀，不預抽 OS 抽象層；`collect-host-id.sh` 廢除（2026-08-18）——⚠️ D11 起指紋改二源，本條的「三源直讀」已被 D11 部分取代
- **Q1–Q4** 是對應卡的**前置查證項**（Q1 LibreOffice 離線形式→T-2.1／Q2 PG 方言→T-1.1／Q3 EXCLUDE 名單→T-1.3／Q4 openscap-utils・sshpass 殘留→T-2.1），不阻擋開工但 Q2 先行
- **D10** EL（Rocky/RHEL）＝方案 A 低 glibc 容器編譯（2026-08-20 定，**隨 .5 暫緩**）
- **D11** 指紋二源化全域：`sha256(product_uuid|machine-id)`，MAC 退場；撞號防護＝BE enroll 端偵測（2026-08-21）
- **D12** 雙形態單產線：compose=有 docker 首選／原生=封閉網路；同一顆產物同一套簽章；升級包不帶 seaweedfs image、形態宣告寫 manifest 檔頭（2026-08-21）
- **D13** 「使用 Agent 服務」＝FR-039 既有功能，BE/FE 零新功能，只做 agent 端（2026-08-21）
- **D14** 儲存後端設定＝CLI（configure-storage）先做；web 下發開 CM-1329 評估卡等 PM（2026-08-21）
- **D15** compose 版配互動安裝程式（照 FR-065 主產品模式），受眾一線工程師不假設會 docker（2026-08-22）
- **恢復預設方案**（2026-08-22）：出廠快照＋一鍵恢復（主產品 FACTORY_DEFAULT 隱藏列／agent factory-defaults.env）；排除動態讀現值、教 user 翻 credentials、恢復重生帳密
- **D16 出貨形態收斂**（2026-08-22）：原生 tarball **暫不出貨**、現階段一律 compose 版（開發成果保留，解凍等商務需求）；T-4.1 暫緩、T-4.2 改 compose 為主。同日裁示：compose 交付包廢除 install/upgrade 兩包制、**收斂一顆通吃**（CM-1335，evidence-agent `a89a701`）。⚠️ 斷網封閉網路驗證（D3 根基）至今無人跑過，不隨原生凍結——歸屬待裁示
- **WSL/docker 過渡風險接受度**（2026-08-22 決策者口頭）：Windows docker 過渡的指紋不穩問題，「只要有 log 記錄發生什麼事、或可重新註冊 agent 就沒問題」——重置後重綁定屬可接受維運事件，非否決點（T-4.3 文件的「不建議當正式方案」讀成「不當長期形態」即可）
- **防篡改宣稱邊界**（T-6.2 查證，2026-08-21）：只可講「改動必被偵測」（雲端 sha256 錨點），不可講 WORM／不可刪除——SeaweedFS 3.99 Object Lock 有效但整桶刪擋不住、且我們未啟用

## §3 下一步（2026-08-23 第八棒續版 v2——189 路線已定案）

**主線（決策者 2026-08-23 拍板）：手冊收完 → v1.16.0 進版 → 189 遷移 bundle 形態。之後全環境統一「拿新 bundle 跑 install.sh --upgrade」升級模式。**

1. ✅ **手冊全收（2026-08-23）**：CM-1347（主產品對齊 1.15.0）＋CM-1299（agent 手冊十一章）＋CM-1348（21 章全面白話化，決策者初審打回後改寫、終審過）＋CM-1349（build 工具修 .md→.html 連結改寫＋SPEC 站白名單補兩頁）四卡 Done。手冊落點：`docs/user-manual/onprem/`＋`agent/`（md）與 `onprem-html/`＋`agent-html/`（網頁版，入口在 FR-065/066 文件站）。⚠️ 決策者提過「有個需求要先處理再發版」——**內容未揭露，下一棒先問**。
2. **可與手冊平行的前置**：①PROD 簽章鑰四步組（LC repo 生鑰→BE PUBLIC_KEYS commit→出貨簽章切 PROD→驗證；正式 bundle 硬門檻）②189 探路盤點（唯讀）：舊 DB schema 落差（`guidant_ai_poc` 在機上 postgres 容器 port 25432、`main` HEAD `8c82e8e6` 約 1.13 era、跑已退役 `main_app.py`）、.env 全量抄錄、camunda/pgadmin 誰在用、停機窗口問決策者。
3. **按序執行**：merge feature/FR-066→main（BE+FE，決策者親手或明示）→ version-bump v1.16.0（skill 全套：release note/pyproject/FE 對齊/specs 凍結快照；⚠️ 191 現跑的 1.15.0 bundle 內容超前 main 的 1.15.0——進版時收掉此不一致）→ build_all 出正式 bundle（PROD 鑰簽）→ 189 遷移（pg_dump 舊庫→裝 bundle→灌回→upgrade 自動補 migration→驗收；**POC 異動，執行當天等決策者當次明示**）。
4. **連帶待拍**：STG（188 裸跑）要不要同批遷 bundle；190/191 免密 sudo 收回。
5. **母卡 CM-1284 收口條件**：雙手冊收完＋user 過目（Windows 已由 D19 移出範圍；斷網維持「先不管」）。
6. design.md D6 註記仍欠；其餘掛置：1298/.5 四卡/1329 暫緩；agent 自更新 follow-up；DEV 測試資料收尾清；demo 用 160 要有人登入帶 Docker Desktop（runbook 素材在 t71 報告）。

> ⚠️ 本節是**建議清單，不是執行授權**。接手方讀完盤點完即停，等 user 發令。


## §4 Pre-flight（必跑）

```bash
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
git status -sb          # 應在 feature/FR-066
python3 scripts/notion_case.py get CM-1284   # 母案 In progress
python3 scripts/notion_case.py get CM-1292   # .2 進行中的卡，看 runner 有無回寫

cd ~/Projects/Billows/Audit-Manager/evidence-agent
git status -sb          # feature/FR-066、與 origin 同步（CM-1292 runner 可能有新 commit）
git log --oneline -3    # 基準 0fc80c8（.1 收口點），其後為 .2 的 commits

ssh jedi@192.168.50.188 'cd /opt/guidant-ai-agent && git log --oneline -1 && ls .build/dist/'
# 基準：HEAD 0fc80c8、dist 有 evidence-agent-0.2.27（.1 驗收級產物，🔴 不可覆蓋/刪除）
```

## §5 環境座標

| 素材 | 路徑 |
|---|---|
| **標的 repo（改 code 的地方）** | `~/Projects/Billows/Audit-Manager/evidence-agent`（branch `feature/FR-066`） |
| BE repo（只放文件＋Notion CLI） | `~/Projects/Billows/Audit-Manager/compliance-manager-be`（branch `feature/FR-066`） |
| design（§3 決策表／§5 詳設／§6 拆分） | `docs/features/FR-066-2608-agent-native-installer/design.md` |
| 討論稿（D 項拍板全文） | 同資料夾 `discussion.md` |
| FR-063 複用（build 管線／私房 wheel／resource_path） | `scripts/build/build_release.sh`、`rebuild_wheels.sh`、FR-063 design |
| FR-064 複用（簽章泛用層） | `gen_integrity_manifest.py`／`sign_manifest.sh`／License Center 簽發 |
| FR-065 複用（install.sh 七步／維運子命令體例） | FR-065 design＋`scripts/install/` 系 |
| Notion CLI | BE repo `scripts/notion_case.py` |

## §6 行為規範提醒（與本 arc 相關）

- 不切 branch、**push 永遠 user 本人做**、顯式 `git add <檔名>` 禁 `-am`；BE 與 evidence-agent **分開 commit**。
- runner 收工回寫子卡「**修正待驗證**」＋白話已完成修正段＋commit hash；**母卡／子需求卡收尾等令**（首腦驗收後收）。
- 碎片卡預設**不寫新 unit test**（CLAUDE.md 測試政策）；驗證＝手測步驟＋既有測試不弄壞。
- 🔴 環境鐵律：開發只動本機／DEV；STG/POC/基線庫不碰。
- 派工＝先有 Notion 卡（本案 17 卡已建齊，派工 prompt 帶實際卡號＋URL）。

## §7 不在本期 scope

- Windows 實作（只出 T-4.3 評估文件）；OS 指紋抽象層（D9 明示延後）。
- ZAP / OpenVAS / OpenSCAP / Nmap 引擎不進 bundle（客戶自備或裝在受測機）。
- FR-064 runtime 全家桶（抽查／lockdown／unlock）不做（D6 瘦身版）。
- FR-065 殘項（PROD 鑰／T-4.2／全案收尾）屬另一條戰線，不在本 arc 順手做。

## §8 給 fresh session 的短 prompt

```
接手 FR-066 檢測 Agent 原生安裝包（母案 CM-1284）。先讀
docs/features/FR-066-2608-agent-native-installer/handoff/FR-066-STATE.md（§0 讀序全走：
WHY＋design.md §2/§3/§6＋Notion 母卡）＋ FR-066-LOG.md 最後 2 block，
答完自檢 4 問、跑完 §4 pre-flight 後回報現況。
讀取與盤點完成後不做任何事——不派工、不跑測試、不改檔，等我下指令才開始作業。
```