---
title: "Agent 本機設定主控台 — 需求討論稿 (FR-157)"
brand: "Guidant AI · **FR-157** Agent 本機設定主控台"
eyebrow: "FR-157 · 需求討論稿 v1 · 2026-10-22（D1～D11 全數裁定；定案與拆卡見 design.md）"
h1: "工具帳密留在客戶機房，存了什麼檔自己看得到"
subtitle: "Agent 機上開一頁設定主控台：從主系統一鍵跳過去，填檢測工具的連線帳密、瀏覽這台 Agent 存了哪些證據檔"
lede: "現在客戶的 OpenVAS 密碼、SonarQube token、掃主機用的 SSH 私鑰，全部**加密存在我們主系統**，派工時再送去 Agent。PM 判定這些是客戶機敏資料，**不該放主系統**。本案在裝 Agent 的那台機器開一頁設定主控台，管理員從主系統的 Agent 管理頁按一下就跳過去（不用再登一次），帳密填在 Agent、加密存 Agent、主系統從此不碰。同一頁再加一個**檔案瀏覽**：客戶部署時多半把 Agent 當儲存設備，證據檔實際落在 Agent 機的 SeaweedFS，他要看得到「這台到底存了哪些檔」、能查、能下載。"
chips: [
  {text: "D1～D11 全數裁定（2026-10-22）", kind: ok},
  {text: "D10 改判：Agent 設定／Agent 檔案兩個能力點", kind: accent},
  {text: "推翻 FR-056 D9 雲端保管帳密", kind: accent},
  {text: "跨 4 repo：BE／FE／jedi-python-package／evidence-agent", kind: accent},
  {text: "陷阱：既有客戶的帳密要搬家，不能升級就壞", kind: crit},
  {text: "陷阱：只能在客戶內網操作、自簽憑證會跳警告", kind: crit}
]
footer: "FR-157 · 需求討論稿 · 2026-10-22 · 姊妹案：[FR-156](../FR-156-2610-agent-side-sbom-scan-and-vulndb-sync/) 掃描搬 Agent（入場券與 8444 門的先例） · 前作：[FR-056](../FR-056-2607-detection-tool-integration/) 檢測工具（D9 被本案推翻）、[FR-039](../FR-039-2606-distributed-file-agent/) Agent 儲存 · 雛形：[prototype/index.html](prototype/index.html)"
---

> 狀態：**討論完畢，D1～D11 全數裁定（D10 不採本稿建議，改為兩個能力點）**｜日期：2026-10-22｜定案與拆卡：[design.md](design.md)｜依賴 FR-156 E1（入場券＋8444 門，已 Done）
> 雛形：[`prototype/index.html`](./prototype/index.html)（六幕：主系統 Agent 清單、主控台總覽、工具連線設定、檔案瀏覽、主系統工具設定頁改版後、直接打網址被擋）

---

## 1. 需求背景 {#background nav="背景"}

### 1.1 PM 與決策者說了什麼

| 日期 | 誰 | 說什麼 | 白話翻譯 | 本稿對應 |
|---|---|---|---|---|
| 2026-10-21 | PM | 掃描工具的設定都在主系統，想改成在 Agent 那台開 Web UI 讓 user 設置、用主系統帳號登入、設定存 Agent 端，因為都是客戶機敏資料 | 客戶的密碼與私鑰不該離開客戶自己的機器 | §4 工具帳密搬 Agent |
| 2026-10-21 | 決策者 | 通常一個網段只放一台 Agent，或資料台與掃描台分開，各台都設定也正常 | 多台各設一次可接受，不做跨台同步 | D9（已裁） |
| 2026-10-22 | 決策者 | Agent 也有儲存設備的功能，未來部署客戶一定會指定 Agent 當儲存設備，要開一個介面讓他瀏覽跟查詢存在 SeaweedFS 內的檔案 | 客戶要看得到自己那台存了什麼 | §5 檔案瀏覽 |
| 2026-10-22 | 決策者 | 登入照原本的方式（從主系統跳轉，不另開登入表單） | 使用者不用記 Agent 網址、不用多登一次 | D1（已裁） |

### 1.2 現況哪裡痛

**帳密這條**：FR-056 D9 當時定的是「憑證加密存雲端，派工時經 mTLS 下發，Agent 用完即丟」。實查現況：

- 主系統 `config.tenant_detection_tool_configs` 一張表，每個租戶每支工具一列，`credentials_encrypted` 存 Fernet 密文、`field_values` 存非機敏欄位（網址、帳號、埠）。
- 派工時 `detection_orchestration_service._resolve_credentials()` 解密、塞進派工單的 `_credentials`，Agent 的 connector 收到明文 dict 用完即丟。
- 八支工具有機敏欄位：OpenVAS 密碼、SonarQube token、OpenSCAP 密碼／SSH 私鑰、ZAP api key、CINC Auditor 與 GCB 的 SSH 私鑰／密碼／WinRM 密碼、Nmap SSH 私鑰／密碼。第三方元件掃描沒有。

這套設計在「我們是 SaaS、客戶信任我們保管」的前提下合理；落地版客戶的立場是「這些密碼能打進我的內網主機，為什麼在你們的資料庫裡」。PM 的判定與 FR-039 的原始不變式一致：**客戶機敏的東西留在客戶機房**。

**檔案這條**：Agent 從 FR-039 起就是儲存設備（`storage_type=remote_agent`，主系統只存參照列、檔案本體在 Agent 機的 SeaweedFS 或本機磁碟）。DEV 實查主系統有 186 列參照指向 Agent。但 Agent 那邊**沒有任何畫面**：Agent 自己的 SQLite 索引（`upload_files`：檔名、大小、上傳時間、上傳者、SHA-256）只有程式在讀，客戶想知道「這台存了什麼、佔多少」只能問我們。

### 1.3 已有的零件（本案不用重做）

| 零件 | 在哪 | 本案怎麼用 |
|---|---|---|
| 入場券簽發 | jedi-remote-agent `agent_ticket_service.py`，用途已預留 `console_login` | 主系統 Agent 管理頁按「開啟設定頁」就簽這張票 |
| Agent 8444 瀏覽器門 | evidence-agent `core/browser_plane_server.py`（單向 TLS、驗票、目前只掛 `PUT /scan-input`） | 同一道門再掛主控台的靜態頁與 API |
| Agent 驗票 | 用註冊時拿到的雲端公鑰，離線可驗 | 直接沿用，A 台的票拿去 B 台無效 |
| Agent 檔案索引 | Agent SQLite `upload_files`（uid／檔名／大小／mimetype／上傳時間／上傳者／SHA-256／儲存後端） | 檔案瀏覽直接讀它，不用新索引 |
| Agent 心跳 | 每 N 秒 `POST /agents/heartbeat`，已帶版本、能力、弱點資料日期 | 加兩組欄位：已設定工具、儲存用量 |
| 工具目錄 | 主系統 `config.detection_tools.config_field_schema`（每支工具哪些欄位、哪些是機敏） | 主控台的表單長相從這裡來（D3） |
| 主系統工具設定頁 | FE `ToolPluginManage.vue`（958 行） | 機敏欄位拿掉、改顯示每台 Agent 的設定狀態 |

### 1.4 不做什麼（對話中已裁）

| 不做 | 原因 |
|---|---|
| Agent 之間同步設定 | 會經過雲端，與動機矛盾；決策者裁多台各設一次可接受 |
| Agent 自己管使用者帳號、開登入表單 | 主系統才是身分來源；決策者 2026-10-22 裁照跳轉方式 |
| 檔案瀏覽顯示業務脈絡（這檔屬於哪個專案哪項證據） | 第一版只列檔案本身，脈絡要經雲端要對照表，列第二期 |
| 瀏覽源碼掃描暫存檔、弱點資料包明細 | 只顯示佔用容量，不列細項 |

---

## 2. 分工概述（30 秒版） {#overview nav="概述"}

整案一句話：**管理員在主系統的 Agent 清單按「開啟設定頁」，新分頁直接進到 Agent 機上的主控台（免再登入），在那裡填檢測工具的帳密、看這台存了哪些檔；主系統從此不存帳密，派工時 Agent 用自己機上的那份。**

| 子需求 | 做什麼 | 產出 | 完成怎麼判定（決策者檢查法） |
|---|---|---|---|
| **A 跳轉與主控台殼** | 主系統 Agent 清單加按鈕簽票；Agent 8444 門掛主控台頁，驗票換 session | 新分頁開出 Agent 主控台，顯示這台是誰、儲存後端、容量 | 按一下「開啟設定頁」新分頁出現主控台不用輸帳密；直接打 `https://<agent>:8444/console` 看到「請從主系統開啟」說明頁；三十分鐘不動再點任何功能回到說明頁 |
| **B 檔案瀏覽** | 主控台列 Agent 索引裡的證據檔，可依檔名／日期／上傳者查、可下載 | 主控台「檔案」頁 | 在主系統上傳一份證據到某專案，到該台主控台的檔案頁搜檔名找得到、大小與 SHA-256 一致、按下載拿到同一份；源碼暫存與弱點資料只顯示 GB 數 |
| **C 工具帳密搬 Agent** | 主控台「檢測工具」頁照工具目錄長表單，機敏欄位加密存 Agent；測試連線在 Agent 本機跑 | 主控台「檢測工具」頁＋Agent 加密儲存 | 填 OpenVAS 帳密按「測試連線」綠勾；主系統 DB `credentials_encrypted` 該租戶該工具為空；在主系統派一支 OpenVAS 檢測正常跑完 |
| **D 主系統端配合** | 派工不再下發帳密；工具設定頁拿掉機敏欄位、改顯示每台 Agent 的設定狀態；Agent 清單加「已設定工具」「檔案數／容量」欄；升級時既有帳密搬家 | 主系統三頁改版＋搬家機制 | 升級舊客戶 DB 後，原本能跑的 OpenVAS 檢測升級後不重填也能跑；Agent 清單看得到每台設了哪些工具；派到沒設帳密的 Agent 立即失敗且訊息寫「Agent X 尚未設定 OpenVAS 連線」 |
| **E 文件與出貨** | SPEC、手冊、安裝文件、出貨基線 | 文件改成現況 | 手冊「檢測工具設定」一節的截圖是 Agent 主控台；安裝需求寫 8444 埠與憑證警告處理 |

依賴：FR-156 E1 的入場券與 8444 門已 Done，本案直接接上。**決策者功課**：無。

---

## 3. 登入與主控台殼 {#console nav="主控台"}

### 3.1 端到端（D1 已裁：從主系統跳轉）

```{.mermaid cap="圖 1 — 從主系統一鍵進到 Agent 主控台"}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
sequenceDiagram
    participant U as 管理員瀏覽器
    participant M as 主系統
    participant AG as Agent 8444（瀏覽器門）
    U->>M: Agent 管理頁按「開啟設定頁」
    M->>M: 查他有沒有 Agent 管理權限
    M-->>U: 五分鐘入場券（誰、哪個租戶、哪台 Agent、角色）
    U->>AG: 新分頁開 https://agent:8444/console#票
    AG->>AG: 用雲端公鑰驗票：這台嗎、過期嗎、用過嗎
    AG-->>U: 發 30 分鐘 session cookie，顯示主控台
    U->>AG: 填工具帳密／看檔案／下載
    AG->>AG: 帳密加密存本機；操作寫本機稽核
    AG->>M: 心跳：已設定哪些工具、儲存用量、稽核事件
```

四個設計點：

- **票放網址的 `#` 後面**，不放 `?`。瀏覽器不會把 `#` 後的內容送給伺服器、不進存取日誌；主控台頁載入後用 JS 讀出來，`POST /console/session` 換 cookie，然後把網址上的票抹掉。
- **票只能用一次**（`jti` 記在 Agent 記憶體，五分鐘後自然淘汰），轉貼網址給別人沒用。
- **session 是 Agent 自己發的**：HttpOnly、Secure、SameSite=Strict，三十分鐘沒操作過期。Agent 不存帳密、不連主系統資料庫、驗票不回頭問主系統。
- **誰能開**：主系統簽票那一刻看這個人有哪些 Agent 能力點（D10 裁：「Agent 設定」「Agent 檔案」兩個），把範圍寫進票。Agent 照票決定顯示哪些分頁、放行哪些 API，不自己理解主系統的角色表。

### 3.2 直接打網址會看到什麼

`https://<agent>:8444/console` 沒帶有效票或 session 時，顯示一頁靜態說明：「此頁面請從 Guidant AI 主系統的 Agent 管理頁開啟」，附主系統網址（Agent 註冊時就知道雲端網址）。不開登入表單、不顯示任何這台的資訊。

### 3.3 主控台長什麼樣

三個分頁：**總覽**（這台是誰、哪個租戶、儲存後端是 SeaweedFS 還是本機磁碟、磁碟用量、弱點資料日期、各工具設定狀態一覽）、**檢測工具**（§4）、**檔案**（§5）。右上角顯示「以 王小明（主系統）登入 · 29 分鐘後過期」與登出。

### 3.4 前端怎麼做（D5）

主控台是一小套純前端頁，跑在 Agent 機、打同一台 8444 的 JSON API，沒有跨網域問題。兩條路：

| 選項 | 做法 | 優 | 劣 |
|---|---|---|---|
| **a. FE repo 獨立 Vite 入口（建議）** | `compliance-manager-fe` 加第二個 build 入口 `console/`，共用設計系統 token、PrimeVue 元件、i18n 字典；build 產物（幾支靜態檔）複製進 Agent 安裝包 | 長相與主系統一致、i18n 不用再養一套、FE 開發者熟 | Agent 出包多一步「先 build FE console」；評估 PrimeVue 整包體積（可只引用用到的元件） |
| b. evidence-agent 內手寫靜態 HTML＋JS | 不依賴 FE repo | 出包單純 | 設計系統要手抄、i18n 要另養、三頁表單手寫 JS 維護成本高 |

::: {.callout .pending}
**D5 主控台前端放哪**

[**建議**：a。設計系統與 i18n 已經在 FE repo，手抄一份就是第二套真相。build 鏈多一步用腳本固定下來（`scripts/build/` 加一行），不是人工步驟。]{.rec}
:::

---

## 4. 工具帳密搬 Agent {#credentials nav="工具帳密"}

### 4.1 搬完之後

```{.mermaid cap="圖 2 — 帳密的存放與使用：之前 vs 之後"}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
flowchart LR
  subgraph before[之前：FR-056 D9]
    B1[主系統工具設定頁<br/>填帳密] --> B2[(主系統 DB<br/>Fernet 密文)]
    B2 -->|派工時解密下發| B3[Agent connector<br/>用完即丟]
  end
  subgraph after[之後：FR-157]
    A1[Agent 主控台<br/>填帳密] --> A2[(Agent 本機<br/>加密檔)]
    A3[主系統派工單<br/>不帶帳密] --> A4[Agent connector<br/>讀本機那份]
    A2 --> A4
    A2 -.心跳只報「已設定」不報內容.-> A5[主系統<br/>工具設定狀態]
  end
```

派工單從此沒有 `_credentials`。Agent 收到單子依工具代號讀本機加密檔；沒設定就立即回報失敗，主系統顯示「Agent 鼎泰機房-01 尚未設定 OpenVAS 連線，請至該台設定頁填寫」。

### 4.2 搬多少：整組連線設定，還是只搬機敏欄位（D2）

每支工具的設定分兩類：機敏（密碼、token、私鑰）與非機敏（網址、帳號、埠、用不用 sudo）。

| 選項 | 做法 | 優 | 劣 |
|---|---|---|---|
| **a. 整組連線設定搬 Agent（建議）** | 網址、帳號、埠、密碼全部在主控台填；主系統只留「這支工具要不要啟用」開關與每台 Agent 的設定狀態 | 使用者只有一個地方填；主系統連「客戶 OpenVAS 在哪個 IP」都不知道，PM 的「機敏」範圍寬一點也涵蓋 | 主系統工具設定頁大改；同租戶多台 Agent 各填一次整組（決策者已裁可接受） |
| b. 只搬機敏欄位 | 網址帳號留主系統，密碼在 Agent | 主系統頁改動小 | 一支工具在兩個地方各填一半，使用者會搞混；派工單還是得帶網址帳號 |

::: {.callout .pending}
**D2 連線設定搬多少**

[**建議**：a 整組。填一半在 A、一半在 B 是最差的使用體驗，而且 PM 說的「連線設定」本來就是整組。]{.rec}
:::

### 4.3 表單長相從哪來（D3）

主控台要知道「OpenVAS 要填網址、帳號、埠、密碼；OpenSCAP 要填帳號、認證方式、埠、私鑰或密碼」。這份定義現在在主系統的工具目錄（`config.detection_tools.config_field_schema`，含 CINC／GCB 的 SSH／WinRM 兩組憑證結構）。

| 選項 | 做法 | 優 | 劣 |
|---|---|---|---|
| **a. 主系統經控制面下發、Agent 快取（建議）** | 心跳回應多帶一份「工具表單定義」（或 Agent 啟動時 `GET /agents/tool-schemas` 拉一次，版本號變才重拉） | 工具目錄仍是唯一真相；新增工具或改欄位不用改 Agent 程式 | 第一次心跳前主控台看不到表單（實務上 Agent 註冊後幾秒就有） |
| b. Agent 自帶 | 每個 connector 自己宣告需要哪些欄位 | 離線也有 | 與主系統目錄兩份定義，改一邊漏一邊；i18n 標籤要另養 |

::: {.callout .pending}
**D3 表單定義從哪來**

[**建議**：a。目錄已經在主系統而且有 i18n，Agent 只是把它畫出來。]{.rec}
:::

### 4.4 Agent 怎麼存（D11）

- 存成一個加密檔（每支工具一個 JSON 區塊，Fernet），放 Agent 資料目錄（與 `agent.db`、mTLS 憑證同層，升級不動的那層）。
- 金鑰怎麼來：

| 選項 | 做法 | 優 | 劣 |
|---|---|---|---|
| **a. 獨立金鑰檔（建議）** | 第一次存帳密時產生 `secrets.key`，權限 0600、只有 Agent 服務帳號讀得到 | 單純；換 mTLS 憑證（重新註冊）不影響帳密 | 機器擁有者拿得到金鑰也拿得到密文（與 FR-064 D6 的邊界一致：不宣稱擋機器擁有者） |
| b. 用 Agent 的 mTLS 私鑰派生 | 不多一個檔 | 少一個檔 | 重新註冊換私鑰，帳密全部讀不回來；派生邏輯不直觀 |

::: {.callout .pending}
**D11 Agent 端加密金鑰放哪**

[**建議**：a。「重新註冊 Agent 就要重填所有工具帳密」會是客服電話的來源。]{.rec}
:::

- **測試連線在 Agent 本機跑**：主控台按「測試連線」，Agent 直接用剛存的帳密打目標工具，結果顯示在主控台並記到本機（最後測試時間與結果）。主系統工具設定頁的「測試」按鈕改成派一張探測工作給指定 Agent，Agent 用本機帳密跑，結果回主系統，兩邊都能測。
- **顯示規則同現況**：機敏欄位存過後不回顯內容，只顯示「已設定 · 2026-10-22 14:03」，留空送出代表不改。

### 4.5 既有客戶的帳密怎麼搬家（D4）

STG／POC 與已出貨客戶的主系統 DB 都有 `credentials_encrypted`。本案要守「每版可直接升級不壞舊資料」。

| 選項 | 做法 | 優 | 劣 |
|---|---|---|---|
| **a. 升級後自動交接一次、Agent 回執後主系統清除（建議）** | 升級後 Agent 第一次心跳回報「我是新版、支援本機帳密」，主系統把該租戶的帳密密文解開、經**既有的 mTLS 派工通道**送給該租戶每台 Agent（與現在每次派工送的是同一條路、同一份東西），Agent 存進本機加密檔並回執；全部 Agent 回執後主系統把密文清空、記一筆稽核 | 客戶升級後什麼都不用做，原本能跑的檢測繼續能跑 | 多一段一次性邏輯；租戶有 Agent 還沒升級時主系統要等（期間舊 Agent 照舊收派工單帶帳密） |
| b. 升級後請客戶重填 | 主系統清空密文，工具設定頁顯示「請至各台 Agent 設定頁重新填寫」 | 零搬家邏輯 | 升級當天所有檢測都跑不動，客戶要重填八支工具的帳密 |

::: {.callout .pending}
**D4 既有帳密怎麼搬**

[**建議**：a。這條通道本來就天天在送帳密，多送最後一次然後關掉，比讓客戶重填安全又省事。搬完才清，中途斷線重跑不會丟。]{.rec}
:::

### 4.6 主系統工具設定頁改成什麼樣

`ToolPluginManage.vue` 每支工具的對話框：

- 拿掉所有連線欄位（D2 a）。留：啟用開關、工具說明、「各 Agent 設定狀態」表（每台一列：Agent 名、已設定／未設定、最後測試時間與結果、「前往設定」按鈕＝簽票跳轉）。
- 「測試連線」改為選一台 Agent 後派探測工作。
- 工具目錄 `requires_credentials` 語意不變，改成「派工前檢查目標 Agent 心跳回報的已設定清單」。

---

## 5. 檔案瀏覽 {#files nav="檔案瀏覽"}

### 5.1 列什麼、從哪來

Agent 自己的 SQLite `upload_files` 就是「這台實際存了什麼」的真相。主控台「檔案」頁直接讀它：

| 欄 | 來源 | 備註 |
|---|---|---|
| 檔名 | `file_name` | 可搜尋（包含比對） |
| 大小 | `size` | 可排序 |
| 上傳時間 | `created_at` | 可依日期區間篩 |
| 上傳者 | `created_user` | 主系統 login name；可篩 |
| 儲存後端 | `storage_type` | `seaweedfs`／`local`／`minio`，一台通常只有一種 |
| SHA-256 | `sha256` | 可複製，對帳用 |
| 動作 | 下載 | 經主控台 session 下載，Agent 讀後端串流回瀏覽器 |

頁首四個數字：檔案總數、佔用容量、儲存後端與其健康（SeaweedFS 連得到／連不到）、磁碟剩餘。另兩列「源碼掃描暫存 X GB」「弱點資料 Y GB」只給數字不列細項（已裁）。

### 5.2 範圍與動作（D6）

| 選項 | 做法 | 優 | 劣 |
|---|---|---|---|
| **a. 只列證據檔、可查可下載、不可刪（建議）** | 刪除仍只能從主系統（刪證據→主系統經 Agent 刪本體） | 不會從 Agent 端刪出主系統找不到本體的孤兒參照 | 客戶想清空間只能回主系統 |
| b. 可刪 | 主控台加刪除 | 客戶自己管空間 | 主系統參照列變孤兒，下載時 404；要再做反向通知 |

::: {.callout .pending}
**D6 檔案瀏覽的動作範圍**

[**建議**：a。「存了什麼」是本案的需求，「刪什麼」是主系統證據生命週期的事。第二期若要做「清理主系統已刪但 Agent 還在的殘檔」，再開。]{.rec}
:::

### 5.3 業務脈絡（D7 已裁：第一版不做）

檔案屬於哪個專案、哪項證據，只有主系統知道。第一版不顯示；第二期可讓主系統經控制面給 Agent 一份「uid → 專案／證據名稱」對照快取。

---

## 6. 主系統端配合 {#mainsys nav="主系統端"}

### 6.1 Agent 清單頁（`RemoteAgentManage.vue`）

| 新增 | 內容 | 來源 |
|---|---|---|
| 「已設定工具」欄 | 小標籤列出已設定的工具代號；未設定的工具灰色；滑過看最後測試結果 | 心跳 `configured_tools` |
| 「儲存」欄 | 「1,284 檔 · 36.2 GB · SeaweedFS」 | 心跳 `storage` |
| 「開啟設定頁」按鈕 | 簽 `console_login` 票，新分頁開 `https://<host>:<browser_port>/console#<票>` | 入場券服務（已有）、`remote_agents.browser_port`（已有） |

### 6.2 心跳新欄位

```
configured_tools: {openvas: {configured_at, last_test_at, last_test_result}, sonarqube: {...}}
storage: {backend: "seaweedfs", file_count: 1284, bytes_used: 38876543210, disk_free_bytes: ..., backend_healthy: true}
console_events: [{at, actor, action: "credential_set|credential_cleared|file_downloaded|login", tool|file_uid}]
```

`console_events` 是 Agent 本機稽核的回傳（D8）。

### 6.3 Agent 上的操作要不要進主系統稽核（D8）

主系統有統一稽核（誰在什麼時候做了什麼）。管理員在 Agent 主控台改帳密、下載檔案，這些動作發生在客戶機上。

| 選項 | 做法 | 優 | 劣 |
|---|---|---|---|
| **a. 回傳主系統稽核（建議）** | Agent 本機先記，心跳帶回，主系統寫進既有稽核事件（`AgentEventCode` 加三個） | 稽核報表一處看完；客戶問「誰下載過這份證據」答得出 | 心跳 payload 多一段 |
| b. 只留 Agent 本機 | Agent 寫 log | 零改動 | 主系統稽核缺一塊，等於這些操作「不存在」 |

::: {.callout .pending}
**D8 主控台操作回傳稽核**

[**建議**：a。事件只有「誰、何時、做了什麼」沒有帳密內容，回傳不違反動機。]{.rec}
:::

### 6.4 誰能開主控台（D10）

檔案頁的對象不只 IT 管理員：稽核人員、顧問、專案成員都可能要對帳「這台到底存了什麼」。若主控台整個綁在「Agent 管理」權限上，這些人會被鎖在外面。

| 選項 | 做法 | 問題 |
|---|---|---|
| a. 與主系統「Agent 管理」頁相同的權限 | 能管理 Agent 的人才能開主控台；主控台內不分讀寫 | 沒有 Agent 管理權限就看不到檔案頁，而檔案頁的對象比 Agent 管理寬 |
| **b. 兩個能力點、一張票帶範圍（決策者裁）** | 「Agent 設定」（填工具帳密、清除）與「Agent 檔案」（瀏覽、下載）各自授權；簽票時把這個人有的範圍寫進票；主控台照票顯示分頁 | 多兩個能力點要種；走 FR-155 做好的角色管理，不另發明守門 |

::: {.callout .decided}
**D10 裁定：兩個能力點、一張票帶範圍**

- 能力點拆兩個：「Agent 設定」與「Agent 檔案」。角色管理裡各自勾，IT 管理員兩個都有，稽核人員只勾檔案。
- 票內帶範圍。只有檔案權限的人進主控台只看到「總覽」與「檔案」，沒有「檢測工具」分頁；Agent 的 API 同樣照範圍放行，不是只藏分頁。
- 入口不變，都是主系統 Agent 管理頁。只有檔案權限的人看到的是唯讀清單（名稱、狀態、存了多少），按鈕文字是「瀏覽檔案」；有設定權限的才看得到「開啟設定頁」與啟停、撤銷這類管理動作。
- **限制要講明**：第一版檔案頁的權限是租戶層，有檔案權限就看得到這台 Agent 的全部檔案，做不到「只看自己專案的證據」——Agent 不知道檔案屬於哪個專案，那是 D7 第二期的事。
:::

---

## 7. 決策彙整 {#decisions nav="決策"}

全部十一項已裁，定案理由與被排除方案見 [design.md §3](design.md)。

| 編號 | 問題 | 裁定 | 日期 |
|---|---|---|---|
| **D1** | 登入方式 | 從主系統跳轉、票換 session，Agent 不開登入表單 | 2026-10-22 |
| **D2** | 連線設定搬多少 | 整組搬 | 2026-10-22 |
| **D3** | 表單定義從哪來 | 主系統目錄經控制面下發、Agent 快取 | 2026-10-22 |
| **D4** | 既有帳密怎麼搬家 | 升級後經既有通道自動交接一次、回執後清除 | 2026-10-22 |
| **D5** | 主控台前端放哪 | FE repo 獨立 Vite 入口、產物進 Agent 包 | 2026-10-22 |
| **D6** | 檔案瀏覽動作範圍 | 只查只下載，不刪 | 2026-10-22 |
| **D7** | 檔案瀏覽顯示業務脈絡 | 第一版不做 | 2026-10-22 |
| **D8** | 主控台操作回傳稽核 | 要，走心跳 | 2026-10-22 |
| **D9** | 多台 Agent 設定同步 | 不做，各設一次 | 2026-10-21 |
| **D10** | 主控台權限 | **不採本稿建議**：「Agent 設定」「Agent 檔案」兩個能力點，票帶範圍（§6.4） | 2026-10-22 |
| **D11** | Agent 端加密金鑰 | 獨立金鑰檔 0600 | 2026-10-22 |

---

## 8. 拆棒草案 {#breakdown nav="拆棒"}

本節是討論時的草案；**定案的拆卡（10 張、5 批）以 [design.md §6](design.md) 為準**。排序以「決策者何時看得到畫面」為準：先讓主控台開得出來、檔案頁有真資料（Agent 索引本來就有東西），再做帳密。

| 批 | 卡 | 白話 | 改哪裡 | 看得到什麼 |
|---|---|---|---|---|
| 1 | **A1** 跳轉＋主控台殼 | 主系統按鈕簽票；Agent 8444 掛主控台頁與 session | BE jedi-remote-agent 端點、FE `RemoteAgentManage.vue` 按鈕、evidence-agent `browser_plane_server.py` 加 `/console` 路由與 session | 新分頁開出主控台總覽（這台是誰、儲存後端、容量） |
| 1 | **A2** 主控台前端骨架 | FE repo 獨立 Vite 入口，三個分頁的殼與設計系統 | FE `console/` 入口、build 腳本複製進 Agent 包 | 主控台三個分頁可切換 |
| 2 | **B1** 檔案瀏覽 | Agent 讀 SQLite 索引出清單；搜尋、篩選、下載；用量統計 | evidence-agent 檔案 API、FE console 檔案頁 | 檔案頁列出真實檔案，搜得到、下載得到 |
| 2 | **C1** 工具帳密表單與加密存 | 表單定義經心跳下發；主控台填寫；Agent 加密存本機；本機測試連線 | BE 心跳回應帶表單定義、evidence-agent 加密存與測試、FE console 工具頁 | 填 OpenVAS 帳密、測試連線綠勾 |
| 3 | **C2** 派工改讀本機、心跳回報設定狀態 | 派工單不帶帳密；connector 讀本機；沒設定立即失敗；心跳帶 `configured_tools` | jedi-detection 派工、evidence-agent connectors、心跳 | 主系統派檢測跑完；派到沒設定的 Agent 立即失敗訊息清楚 |
| 3 | **D1** 主系統三頁改版 | 工具設定頁拿掉連線欄位改各 Agent 狀態表；Agent 清單加兩欄 | FE `ToolPluginManage.vue`、`RemoteAgentManage.vue`、BE 清單 API | 主系統看得到每台設了哪些工具、存了多少檔 |
| 4 | **D2** 既有帳密搬家 | 升級後一次性交接、回執後清除 | BE jedi-detection／jedi-remote-agent、evidence-agent 回執、migration 標記 | 升級舊 DB 後原本的檢測不重填能跑；主系統密文欄清空 |
| 4 | **D3** 稽核回傳 | 主控台操作經心跳進主系統稽核 | evidence-agent 本機稽核、BE 事件碼 | 稽核報表看得到「誰在 Agent 改了帳密、下載了檔」 |
| 5 | **E1** SPEC、手冊、安裝文件、出貨基線 | 文件改現況 | BE `docs/spec-site/current/`、`docs/user-manual/`、installer docs、`scripts/init/` | 手冊截圖是主控台；安裝需求寫 8444 |

---

## 9. 風險與陷阱 {#risks nav="風險"}

| 風險 | 怎麼處理 |
|---|---|
| 瀏覽器連不到 Agent（管理員在外網） | 設計上的必然（帳密不離開客戶機房）。主系統按鈕旁提示「需在可連到 Agent 的網路」；開不出來時說明頁寫原因 |
| 自簽憑證警告 | 同 FR-156 D9：手冊寫匯入 CA；第二期選配客戶自備憑證 |
| 票被攔截重放 | 五分鐘、一次性、綁 Agent、放 `#` 不進日誌 |
| 搬家中途有 Agent 沒升級 | 主系統等所有 Agent 回執才清密文；期間舊 Agent 照舊收帶帳密的派工單；Agent 清單顯示「帳密搬家中：2/3 台」 |
| 同租戶多台 Agent 只設了一台 | Agent 清單「已設定工具」欄一眼看到；派工前檢查，派錯台立即失敗訊息指名哪台沒設 |
| 主控台 session 與 8444 上傳票共用一道門 | 路由分開（`/scan-input` 驗票、`/console/*` 驗 session），互不認對方的憑據 |
| Agent 機器擁有者讀得到金鑰與密文 | 與 FR-064 D6 邊界一致：不宣稱擋機器擁有者；文件寫明 |
| FE console 體積進 Agent 包 | 只引用用到的 PrimeVue 元件；量過再定，上限訂 2 MB |

---

## 10. 這份文件的定位 {#positioning nav="定位"}

| 你想知道 | 看這份 |
|---|---|
| 畫面長什麼樣 | [雛形](prototype/index.html) |
| 為什麼推翻 FR-056 D9 | 本稿 §1.2 |
| 入場券與 8444 門怎麼做的 | [FR-156 design](../FR-156-2610-agent-side-sbom-scan-and-vulndb-sync/design.md) E1 |
| Agent 儲存怎麼運作 | [FR-039](../FR-039-2606-distributed-file-agent/)、[FR-066.6 T-6.2](../FR-066-2608-agent-native-installer/) |
| 定案後每張卡怎麼做 | [design.md](design.md) |