Guidant AI v1.16.0 Release Note¶
| 項目 | 內容 |
|---|---|
| 版本 | 1.16.0（功能版號；主軸＝檢測能力往「多網段、多工作」擴張——檢測 Agent 出貨形態落地＋一次執行派多台 agent） |
| 發布日期 | 2026-08-26 |
| 上一版本 | 1.15.0（2026-08-19） |
| 涵蓋區間 | 2026-08-19 ~ 2026-08-26（c8498d50..feature/FR-067 HEAD） |
| 涵蓋需求 | FR-066 檢測 Agent 安裝包（Nuitka 編譯 agent／compose 一顆包通吃／互動安裝程式／儲存三型＋恢復出廠／兩本客戶手冊；Windows 評估與凍結）＋ FR-067 檢測多 Agent 分派（一次執行派多台 agent、每列自足的工作設定、群組化彙總與收口、per-assignment 排程、單組重跑／取消）＋ 期間驗收修正 |
| 規模 | BE 88 commits（feat 18／fix 13／docs 57）；FE 24 commits（feat 14／fix 10）；evidence-agent 0.2.27 → 0.2.30；DB migration 7 支 |
| 適用部署 | dev（已驗）＋ 188 落地版 stack（安裝包形態，已跑最新 code）；STG 未上版；POC 為全新安裝走安裝包（見 §5） |
| 部署性質 | 含 7 支 DB migration（安裝包形態的 stack 已全套、老 25432 DEV 庫已套；POC 全新安裝由安裝包依 manifest 套用，不需手動補）。檢測 Agent 出貨形態改為 compose 一顆包（原生 tarball 開發完成但暫不出貨）。Windows agent 全線凍結。 |
0. 發版前回歸 gate¶
本版未執行 site-regression 自動 Core gate（決策者明示豁免）。放行依據為 188 落地版驗收 stack 的多輪端到端實測——FR-067 於 2026-08-24 完成雙 agent 雙網段端到端驗收第一輪（六張回饋卡全清），其後續輪修正與 FR-067.8 每列自足模型皆在同一 stack 上重布複驗（CM-1384／CM-1394 兩次重布）；FR-066 則在 188（build）／123（真機）／190（agent 驗收）／191（落地版 PRD 驗收）四台上分階段實測。自動化 gate 待落地版 E2E 套件補齊後於後續版本恢復。
1. 概述¶
v1.15.0 解決的是「產品怎麼交到客戶手上」；v1.16.0 解決的是「客戶裝好之後，檢測能力怎麼覆蓋整個環境」。
兩個需求構成一條線：
- FR-066：檢測 Agent 自己也變成一顆客戶裝得起來的包——編譯出貨、一鍵安裝、內建儲存、可恢復出廠。每個網段擺一台 agent 這件事，從此不需要原廠工程師到場。
- FR-067：平台端能一次把工作派給多台 agent——一個檢測任務裡設好「哪台掃哪些目標、用什麼參數、幾點開跑」，按一次執行同時派出，全部回報完才算完成，失敗的那台可單獨重跑。多網段隔離環境（辦公網／機房網／DMZ）從此一個任務就掃得完。
在此之前，一次執行只派一台、而且是系統隨手挑的（不看在線狀態，挑到離線機就永遠掛在待領取）；要掃三個網段只能開三個任務人工湊。
2. 重點新功能¶
2.1 FR-067 檢測多 Agent 分派（本版主軸）¶
每列自足的工作設定。任務設置的檢測工具區改成一份「Agent 工作指派」清單，每列＝一台 agent ＋ 該工具的完整參數表單（掃描目標／Profile／連線方式／認證資訊等）。任務層只保留「完成模式」。這個形狀取代了原本「任務層共用參數＋分派列逐鍵覆寫」的模型——覆寫模型每開一個欄位就多一條「留空沿用什麼」的說明，使用者看一列要心算兩層合併；而且 SonarQube 的多模式（pull／scan／upload）在單一任務層 scan_mode 之下根本表達不了「一列 pull、一列 upload」。業界主流（Nessus／Qualys／AWX／防火牆規則表）的形狀正是「每條工作規格自足、重用靠引用庫」，我們的 Profile 庫（FR-059）就是那個可重用參數包。
配套：每列「複製此列」鈕、新增列預設帶第一列的值（密碼類欄位刻意不抄，避免誤顯示「已設定」而存進空密碼）；密碼類參數跟著列走（DB 密文、API 剝除、畫面顯示「已設定」）。
掃描目標支援 CIDR 與範圍寫法。10.1.0.0/24、10.1.0.5-20 這類寫法會依工具分流展開——逐台登入型工具（OpenSCAP／CINC）展開成逐台，原生支援網段的工具（Nmap／OpenVAS）原樣傳下去。畫面同時顯示台數與原始寫法，讓使用者知道「這一列實際會掃幾台、真正被掃的是什麼」。
執行群組（group）與彙總收口。按一次「開始執行」展開成 N 筆執行紀錄（維持既有「一筆執行＝一張工單」1:1 不變），外面包一層群組做彙總：
- 群組內全部回報完才算這次執行完成——自動完成任務、通知信、彙總狀態三件事都上移到收口時做。
- 彙總語意：全成功→成功；有失敗但無執行中→部分失敗（沿用既有黃色語彙，一眼看出「有掃到但不完整」）；全失敗→失敗；取消比照失敗。
- 自動完成只認全部成功——部分網段沒掃到，任務不該自動關。
- 順帶修掉現況「多筆各自觸發完成撞任務狀態 409、agent 收 5xx」的地雷（收口改列鎖）。
執行前逐台驗證。派工前逐列檢查 agent 存在／啟用／未撤銷／有掃描能力／在線，任一不過整次擋下並一次列出所有不合格機與原因（甲機(offline); 乙機(no_capability)）。理由是部分派出＝部分網段被跳過、結果殘缺卻顯示「完成」，比不派更糟。
單組重跑與取消。失敗那一組可單獨重跑（同群組追加一筆、彙總以每組最新一筆計算），不必整組重掃。重跑前置在本版收窄到該組自己的最新一筆是失敗／已取消即可——原本要求整個群組都不在執行中，會讓 30 秒就失敗的組乾等一小時的慢組。另有單組取消與整組取消（整組取消為 best-effort，打不到的 agent 不會讓整次操作報錯）。
per-assignment 排程執行。每組可設「幾點才開跑」（不同網段常有不同維護窗，半夜才能掃機房網）。實作形狀是「群組照常立即建，延後的是 agent 領得到單的時間」——心跳領單查詢加時間條件，沒到時間的單 agent 看不到；不需背景排程器。排程中的組可「立即開始」催跑，也可直接取消（單還沒被領走，不打 agent）。⚠️ 前端送值須帶時區位移（2026-08-25T02:00:00+08:00），不帶會被當 UTC。
執行紀錄與通知的呈現。執行紀錄改群組卡片：彙總徽章 ＋ 每台一列（agent 名稱／掃描目標／狀態／報告），重跑歷史收合；舊資料單筆自成一組，形狀一致不需分叉。通知改成收口發一封彙總，內含每台一列（agent／目標／狀態／發現數／時間），取代原本 N 台 N 封的轟炸。
連帶地基修補：Agent 清單 API 補上能力與在線狀態並可依能力過濾（下拉才列得出「能掃描的」）；自動挑機改為只挑在線的；「測試連線」可指定 agent，確保測通的那台就是實際執行的那台。
2.2 FR-066 檢測 Agent 安裝包¶
出貨形態＝compose 一顆包通吃。Agent 改 Nuitka 編譯（原始碼不可見），外部檢測工具全部包進同一顆 tarball 離線自足，配互動安裝程式（照主產品模式問答引導，客戶不需自己下 docker 指令）。原生 systemd 版本已完整開發並在真機驗過，但決策裁定現階段一律出 compose 版，原生成果保留待封閉網路／無 docker 客戶出現時解凍。
三容器縮成單一服務：agent-db（postgres）退役換 SQLite；nginx mTLS sidecar 退役，agent 自行以 gunicorn/ssl 起 8443 雙向認證。註冊流程全自動、首次連線信任雲端自簽憑證。
機器指紋二源化：改為 sha256(product_uuid|machine-id)，MAC 退場（容器內讀不到或會漂移）；撞號防護搬到平台註冊端。
內建儲存與恢復出廠：安裝包內含 SeaweedFS，可切換為自有 S3 或本地目錄；出廠設定快照可一鍵恢復。升級一條指令（install.sh --upgrade），資料與憑證不動。
兩本客戶手冊：落地版安裝手冊（docs/user-manual/onprem/，11 章）與檢測 Agent 安裝手冊（docs/user-manual/agent/，11 章），全書白話化改寫，隨包出貨。
Windows 支援凍結：三條路線（Docker Desktop／原生服務版／WSL 常駐）經真機實測後全線凍結——Docker Desktop 的 engine 綁登入 session，使用者登出就全滅，無人值守出貨不可行；WSL 路線的虛擬機閒置 60 秒即凍結使用者空間。評估與實測資產留檔待客戶訊號。現行掃 Windows 的解答是：Linux agent 透過 WinRM 遠端掃（既有功能）。
2.3 主產品側的連帶修補（FR-065／FR-066 期間）¶
- 系統設定四頁守門：非超級管理員一律 403，route 守門改按分頁式能力點分流。
- 儲存設定「恢復系統內建儲存」：安裝器出廠快照 ＋ 後端一鍵恢復端點 ＋ 前端按鈕。
- 心跳自報能力：agent 心跳帶回自己的能力清單（原本只在註冊時寫一次，手動開通的能力會永久消失）。
- DB 初始化基線補漏：
stage_objects全缺、水位哨兵、時區釘死；檢測 Profile 庫改「裝好就有」。
3. 重要修補¶
- 執行紀錄整批從畫面消失：舊資料筆的卡片分組鍵與「最新一筆」判定鍵不同步，導致同一任務下所有舊筆被視為同一條分組線、只有最新那筆被標為當前；每張卡又各自成卡，於是除最新那張外每張卡都是「零當前列＋一列歷史」，前端預設收合歷史之下整包稽核紀錄從畫面消失（實測 10 筆只顯示得出 1 筆）。修法為抽出共用的卡片鍵函式，並補回歸測試鎖住「每張卡至少一列當前」的不變量。
- 時區基準分流：agent 心跳統一寫 UTC、公告日期用營運時區；既有
last_seen_at以 migration 換算（原本存的是容器本地牆鐘，修正後會被判成「未來時戳」而誤判離線）。 - 落地版 Office 檔 PDF 預覽 500：唯讀 rootfs 撞上相對路徑的 static folder。
- 指紋撞號守門對複製機失效：豁免條件改看「是否憑 uid 認出」而非「是否 resolve 到同一列」。
- 文件站死連結歸零：站內
.md互連在渲染層改寫為.html；使用手冊分組補兩頁。 - 前端零星修補：重跑歷史收不起來（
v-show被 PrimeFlex 的!important壓過）、排程小日曆時間調不上去、Agent 分派空列改為儲存擋下＋必填紅框（原本靜默丟棄）、單一目標型工具不再顯示多餘的掃描目標欄。
4. Breaking Changes¶
- 檢測工具任務設置的參數形狀改變（FR-067.8）：任務層共用掃描參數區收掉，參數改落在每個分派列上。存量綁定的讀取端會合成一列顯示（把原本隱含的單組 fallback 顯性化），使用者第一次存檔時真正落庫；不做資料庫層 backfill。前端讀任務層參數的四處（上傳模式判定、檢測設定顯示、執行主機與掃描目標清單）已改讀各分派列。
- 執行 API 回傳形狀改變：
POST /detection-tools/jobs/{job_uid}/execute回{group_uid, status, total_count, executions:[...]}，不再是單筆的{agent_task_uid, execution_uid}。 - 執行紀錄 API 改兩層形狀：
GET /detection-tools/jobs/{job_uid}/executions的data為群組陣列（群組 → 各台執行紀錄）；舊資料以is_legacy: true單筆自成一組，形狀一致。 - 同一綁定下不再限制一台 agent 只能出現一列（拿掉唯一約束，重複判準改為後端驗證層看「agent＋掃描目標」整組）。
- 檢測 Agent 出貨形態變更：新客戶一律 compose 版安裝包；原生 systemd 形態暫不出貨。既有部署不受影響。
5. DB Migration（7 支）¶
| 檔名 | 內容 |
|---|---|
2026-08-18-cm1283-smtp-ldap-capability-delegation.sql |
SMTP／LDAP 能力點下放給業務租戶（is_platform 翻轉） |
2026-08-20-cm1317-remote-agents-last-seen-at-utc-backfill.sql |
remote_agents.last_seen_at 既有值由容器本地牆鐘換算成 UTC（冪等） |
2026-08-23-fr067-2-detection-multi-agent-tables.sql |
檢測多 Agent 分派資料層：assignment 子表＋執行群組表＋執行紀錄擴欄補索引 |
2026-08-24-fr067-7-per-assignment-scheduling.sql |
per-assignment 排程：子表與工單加 scheduled_at、執行紀錄新增 scheduled 語意、領單部分索引 |
2026-08-24-fr067-5-profile-field-select-only.sql |
openscap／inspec／gcb 的 Profile 欄位由可手填改為純下拉 |
2026-08-24-fr067-5-drop-jedta-agent-unique.sql |
拿掉「同綁定同 agent 只能一列」的唯一約束 |
2026-08-25-fr067-5-scan-target-syntax-hint.sql |
掃描目標欄補 CIDR／範圍寫法說明（依工具展開方式分流措辭） |
前兩支（
cm1283／cm1317）產生於 v1.15.0 之後、本版之前，實際已套用但先前漏登記於scripts/sql/manifest.tsv，本版補登。安裝包依 manifest 套增量，漏登會讓全新安裝默默少套。
套用狀態：188 落地版 stack（安裝包形態）已全套；老 25432 DEV 庫已全套。STG 未上版。POC 為全新安裝——走安裝包由 manifest 依序套用，不需手動補。
6. 相依套件版本¶
| 套件 | 版本 | 變更 |
|---|---|---|
| evidence-agent | 0.2.30 | 重新註冊（re-enroll）支援＋錯誤輸出改走 stderr；累計自 0.2.27（SQLite 化／自起 mTLS／指紋二源／compose 一顆包） |
| jedi-common | 0.0.31 | session_scope() 依方言判斷 SET LOCAL（SQLite 化前置；PostgreSQL 路徑行為恆等） |
| jedi-file-upload | 0.0.22 | 未變 |
| jedi-project | 0.0.8 | 未變 |
| jedi-oscal-v2 | 2.2.3 | 未變 |
| jedi-auth | 0.1.34 | 未變 |
主專案
pyproject.toml未變更 jedi-* pin（jedi-common0.0.31 供 evidence-agent 使用）。
7. 部署順序（既有環境）¶
- 套用 §5 migration（安裝包形態由
install.sh --upgrade依 manifest 自動套；手動環境依sql-migrationskill 流程） - 部署 BE
- 部署 FE（版號同步 1.16.0）
- 檢測 Agent 升級至 0.2.30（
install.sh --upgrade，資料與憑證不動） - 驗證：任務設置的 Agent 工作指派清單、執行紀錄群組卡片、Agent 清單的在線狀態
8. 已知 follow-up¶
| 項目 | 卡號 | 說明 |
|---|---|---|
| FR-067 收尾棒（.6） | CM-1356 系 | e2e 測試（test repo）＋ SPEC 三頁 html build 與查漏 |
| Windows 無域環境掃描憑證 | 待開卡 | 無網域（workgroup）機器的同名本機帳號需逐台建、且有 UAC token filter 限制；現行憑證為租戶層單組，多網段無域場景不成立。方向：手冊寫明前置 ＋ 憑證組別擴成可多組並支援 per-列指定 |
| OpenSCAP content 平台派發 | 待開卡 | content 檔目前逐台手放，50 台客戶無法維運；方向為沿 FR-059 的 file 型 profile 派發機制擴到 openscap |
| 註冊 token 端點路徑重複 | 待開卡 | 回傳值已含 /api/1.0，agent 端再自補一次導致 404 |
| 掃描設定下放指派人員 | 等 PM | 治理面（工具／基準／完成模式）由 PM 設定，操作面（目標機器／憑證）由指派人員在任務頁補 |
| Windows agent 全線 | CM-1336~1345（暫緩） | D19 凍結，資產保留待客戶訊號 |
| PROD 簽章鑰 | — | 現有安裝包皆為內部測試包（--skip-prod-key-check），正式交付前必辦 |
| 儲存後端遷移工具 | CM-1279 | 切換 storage 時搬移既有檔案（沿自 v1.15.0） |
9. 相關文件索引¶
- FR-066：
docs/features/FR-066-2608-agent-native-installer/（design.md D1~D19 決策鏈；handoff/ STATE＋LOG＋全案 SUMMARY；Windows 三份實測報告） - FR-067：
docs/features/FR-067-2608-detection-multi-agent-dispatch/（design.md §3 決策定案 D1~D10、§5.10 每列自足模型、§6 拆分；handoff/ STATE＋LOG） - 客戶安裝手冊：
docs/user-manual/onprem/（落地版主產品）／docs/user-manual/agent/（檢測 Agent） - 檢測工具使用指南：
docs/user-manual/detection-tools-guide.md - 頁面 SPEC：
docs/specs/v1.16.0/（本版凍結快照）／docs/specs/current/（持續更新）