---
title: 網址型檢測 Profile 存成檔案並同步給 Agent — 需求紀錄 (FR-174)
status: draft
date: 2026-11-01
source: FR-172 CM-3410（H-5）實作時發現範圍超出，決策者裁暫緩、另開本案
---

# 網址型檢測 Profile 存成檔案並同步給 Agent：需求紀錄

> 這份只記需求、現況、已查證的阻擋點與決策者已定的方向。方案細節與拆卡留給討論稿與 design。

## 決策者需求

- Agent 主控台跑 CINC Auditor 時，Profile 下拉要看得到 CINC 的 Profile（目前是空的，只能手打路徑）。189 Demo 時發現。
- 2026-11-01 決策者裁：CM-3410 暫緩、**另開 FR 做**，方向採 **A 案**（見下）。

## 為什麼下拉是空的（已查證）

- 189 登記的 CINC 兩支 dev-sec Profile 是**網址型**（GitHub）。主系統只把**檔案型** Profile 同步給 Agent；網址型沒有檔，不會同步。
- 主系統登記網址型時其實**有下載過**（解析出控制項 Linux 59／Windows 431，`extraction_status=succeeded`），但解析完不留檔（`file_id` 空）。
- Agent 主控台這欄從 FR-166 P2-3 起就是文字框，下拉只在主系統檢測頁有，不是被弄壞的。
- 應急：121 Agent 的 `/data/content/cache/manual/{linux,windows}-baseline` 有首腦手放的 dev-sec 兩支，主控台貼路徑可跑，不進下拉。本案做完可刪。

## 三處阻擋（CM-3410 小弟查出、工作坊首腦開檔核對屬實）

網址型 Profile 的匯入與解析在 **jedi-detection 套件**，不在 BE（BE 用 Nexus 版 `jedi-detection==1.7.2`）。

1. `jedi_detection/app/service/detection_profile_extraction_service.py` 第 39–53 行的設計不變式：「下載內容不落儲存——不寫 `upload_files`、`source_type` 維持 `url`、`file_id` 維持 `NULL`。存成 file 型快照會破壞雙軌語意，掃描（agent 拉 URL）與抽取（平台存快照）可能對不上。」
2. 資料庫約束 `chk_dpv_source_exclusive`（套件 `migrations/001-detection-tables.sql:204`）：url 型必須 `file_id IS NULL`。
3. 同步條件 `list_current_files_visible_to`（repo_impl:117–124）只撈 `file_id IS NOT NULL`；`agent_profile_sync_service.current_profiles_for_heartbeat` 文件寫明「只含 file 型」。

## 決策者已定方向：A 案

匯入網址型時，把下載內容存成 `upload_files`，**該版改記成檔案型**（`source_type=file`、`file_id` 有值），原網址另存成「來源網址」欄位；新鮮度檢查（ETag）改看該欄。

- 資料庫約束、Agent 同步條件都**不用放寬**；平台解析的與 Agent 掃的是同一份檔，反而解掉不變式擔心的「兩邊對不上」。
- 符合 FR-172「Agent 不連外網」：網址型交給 Agent 自己拉，在客戶內網本來就拉不到。
- 被排除的 B 案：保留 url 型、放寬約束允許同時帶 `file_id`。改動小，但同一版有「網址」與「快照」兩個來源，Agent 該用哪個要另訂規則，日後容易兩個真相。

## 預估範圍（給討論稿參考，未拆卡）

約三張卡：①環境卡：BE 開發期改走 jedi-detection 本機路徑；②套件卡（Repo 選 jedi-packages）：匯入與抽取改法＋「來源網址」欄 migration＋ETag 改看該欄；③BE 卡：接線、DEV 重新匯入 dev-sec 兩支、本機 Agent 拉設定看到 CINC 兩筆、主控台下拉有東西。

**要先確認的**：
- 既有已登記的網址型 Profile（DEV、189）要不要回填成檔案型；出貨前無客戶，可能直接重匯即可。
- 與 FR-171 B 主題（設定通道，Profile 清單從心跳搬到 `GET /agents/config`）的接點：本案的同步走哪條通道，看 FR-171 做到哪。
- 套件不變式是 jedi-detection 設計決策，推翻要在套件 design 文件同步改寫。

## 相關

- FR-172 CM-3410 卡片（小弟回寫與首腦紀錄全文）
- FR-167 待辦 61（FR-167 handoff STATE）
- 套件：`~/Projects/Jedicogy/module/jedi-python-package/jedi-detection/`