主系統不在，Agent 也要能自己站著

狀態：v5｜日期：2026-10-26｜已裁：D1～D23（D20～D22 是決策者看過十二幕雛形後補裁；D23 是手測時改裁）｜LDAP 三選一納入、憑證改首次信任釘住（推翻 CM-2239）｜§13 全案重新檢視｜§14 全量工作清單給 PM（§9 彙整）｜定案後落 design.md 再開卡 雛形：prototype/index.html（六幕：直接打網址的登入頁、總覽（含離線橫幅）、獨立掃描、網路除錯、執行紀錄與待回傳、主系統端的離線操作者授權與自主執行紀錄；右上可切「在線／離線／未同步」看三種狀態的差別）

1.1 老闆與決策者說了什麼

1.2 現況哪裡痛

實查 evidence-agent（主控台 FR-157 已上到 F2）與 jedi-remote-agent 後，五件事各自的現況：

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

1.4 不做什麼（本稿先劃線，決策者可改）

整案：Agent 主控台多三個分頁（掃描工具、網路除錯、執行紀錄）與一頁登入，主系統連得上時照舊跳轉進去，連不上時用主系統事先授權的本機帳號登入；掃描與除錯直接在 Agent 上按、結果先存 Agent，連回主系統後自動補傳到「Agent 自主執行紀錄」。

資安守門（§6）不是獨立一棒，是 A～E 每棒的驗收條件；收口時 ddd-compliance-reviewer 與資安規則檔一起掃。依賴：FR-157 主控台殼（已上到 F2）、FR-156 E1（已 Done）。決策者功課：D1 登入模式、D5 除錯工具清單要拍板。

3.1 現況的門怎麼開、哪裡斷

FR-157 D1 裁「Agent 不開登入表單」，前提是主系統一定連得到。本案的前提剛好相反：主系統連不到是常態之一。FR-157 的三條路在離線時：

所以「離線登入」要新開一條路，而這條路的核心問題不是表單怎麼畫，是 Agent 離線時憑什麼認得你。

3.2 業界常見的五種模式（D1）

還有兩個常被問到的，本稿先排除：硬體金鑰／客戶端憑證（瀏覽器匯入憑證才能進——落地版客戶會抱怨麻煩，且撤銷要管 CRL）、Agent 自己接 OIDC 到雲端 IdP（離線時一樣斷，等於 A）。

多因子（TOTP 驗證碼 App）：B／C／D 都能疊。業界獨立管理台（Nessus、pfSense）多半有，但要客戶每個人裝驗證器 App。本稿建議列第二期選配，不綁第一版。

3.3 定案：三層身分（D1 已裁）

決策者點出的關鍵：「主系統沒先給、根本沒設過」100% 會發生。這種情境下 Agent 只有兩種選擇——只認安裝時設的那組密碼，或自己放寬讓任何主系統帳號試（離線時驗不了主系統密碼，等於讓人猜，就是跳板的開端）。沒有第三條路；業界所有有管理頁的設備（Nessus scanner、FortiGate、UniFi）都走第一種。所以登入分三層，從「最後保障」到「日常」：

救援：機上 sudo guidant-agent-ctl console-login 一次性網址（現況已有），給「本機管理員密碼也忘了」的情況。忘密碼的恢復路徑是「有機器 sudo 權限的人」，與所有設備忘密碼要接 console 口同理。

%%{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 I as 安裝者
    participant U as 使用者瀏覽器
    participant M as 主系統
    participant AG as Agent 8444
    Note over I,AG: 安裝時
    I->>AG: install.sh 強制設 local-admin 密碼（只存雜湊）
    Note over M,AG: 在線時（平常）
    M->>AG: 心跳回應帶「離線操作者名單」：誰、範圍、到期日（沒有主系統密碼）
    U->>M: Agent 管理頁按「開啟主控台」
    M-->>U: 五分鐘入場券
    U->>AG: 帶票進門
    AG-->>U: 發 session；在名單且未設離線密碼 → 提示設定
    U->>AG: 設離線密碼（只存雜湊）
    Note over U,AG: 離線時
    U->>AG: 直接打 https://agent:8444/console
    AG-->>U: 登入頁（橫幅：主系統連線中斷）
    U->>AG: 主系統帳號＋離線密碼，或 local-admin＋管理員密碼
    AG->>AG: 名單內？未到期？密碼對？沒被鎖？（local-admin 只驗後兩項）
    AG-->>U: 發 session；掃描範圍仍照清冊，未同步只准診斷
    Note over U,AG: 什麼都不行時
    U->>AG: 機上 sudo console-login 印一次性網址

設計點：

• 名單由主系統下發，Agent 只做快取，名單只有帳號、顯示名、範圍、到期日，沒有主系統密碼雜湊。Agent 端沒有任何「新增使用者」功能，①只有一個固定帳號——Agent 永遠不會長出主系統看不見的身分。
• 離線密碼是另一組：主系統密碼雜湊不該離開主系統（FR-157 的動機）；一人授權多台各設一組可接受（與 FR-157 D9 同理）；在線跳轉進任一台都能重設該台密碼。
• 登入頁版面照主系統 Login.vue（左 44% 表單、右品牌面板、底線式分頁），改 Agent 模式：分頁依連線狀態變——在線＝主系統登入（首選，跳回主系統驗證）／AD／離線密碼；離線＝AD／離線密碼／本機管理員；未同步＝只有本機管理員可按。右面板主角是「這台 Agent 卡」（名稱、IP、版本、角色、連線狀態）加一句狀態提示，不放 hero 標語；拿掉記住我、忘記密碼、captcha。FE console 的 Login.vue 直接從主站複製版面與樣式再刪分流邏輯。
• 主控台殼改左側邊選單，結構照主系統、身分靠四個訊號分（決策者 2026-10-26 裁：「結構一樣、身分明顯不一樣」）。FR-157 的頂部 TabView 在三頁時合理，七頁不夠放。側欄 14rem、頂欄 4rem、麵包屑、側欄底部使用者區，照主站 AppSidebar／AppTopbar 複製版面（console 不載 router 與 Pinia，選單項寫死在 console 自己的清單）。分組：總覽／作業（掃描工具、網路除錯、執行紀錄）／設定（檢測工具、身分來源、檔案）／維運（服務與重啟）；未同步時作業與設定項反灰。四個環境訊號：①側欄用主站現成的 teal 主題色（--menu-bg: #00695C），主站側欄跟亮暗走、Agent 固定 teal；②側欄頂「AGENT」字樣＋這台的名稱與狀態點（主站同位置是租戶／專案）；③內容區頂部常駐狀態列「AGENT · 高雄機房 Agent-01 · 主系統連線正常／中斷／未同步」，不是只有異常才出現；④瀏覽器分頁標題「Guidant AI Agent · 高雄機房 Agent-01」加 favicon 角標。同一套產品的 prod／staging 就是這樣分，不靠版面不同辨識。
• 總覽＝dashboard，不另開 Dashboard 頁：要處理的事放最上面（主系統連線、待回傳積壓、磁碟低於門檻、清冊過舊、帳密儲存損壞、有掃描被拒絕），其他正常收成一行；網路一行四個點（網卡、閘道、DNS、主系統）；正在執行；最近五筆；這台的靜態資訊放最下。主系統端 Agent 清單本身就是跨台 dashboard，不另做「Agent 總覽儀表板」；跨據點統計圖列第二期報表。
• 「沒設過」不能是靜默狀態：主系統 Agent 清單對「離線操作者 0 位」顯示紅字警示；安裝完成畫面與手冊要求把 local-admin 密碼交給現場負責人保管。
• local-admin 不是萬能帳號：它只過門 1；門 2（清冊）與門 3（工具清單）不看身分（§6.1）。攻擊者拿到 local-admin 能做的是對清冊內已授權設備跑既有工具，不能掃任意 IP、不能下指令；未同步過的 Agent 連掃描都跑不了。

3.4 登入後能做什麼：在線、離線、未同步三種狀態

「未同步」＝這台 Agent 從未收過授權清冊或離線操作者名單（剛裝好還沒註冊、或註冊後第一次心跳還沒成功）。決策者裁：未同步就預設沒完成設定，拒絕用工具，只准 local-admin 登進來查連線（D12）。

3.5 第四層：接客戶 AD／LDAP（D17、D18、D19 已裁）

決策者判斷老闆會要。實查現況與缺漏在 §13.8；這裡講設計。

三選一（各區可能不同 AD——總部一個網域、新加坡子公司自己的、日本點用 Google Workspace 沒有 AD）。主控台「檢測工具」旁同形狀多一張「身分來源」卡：

守住的點：LDAP 只取代「密碼怎麼驗」那一步，不決定「誰能登」——名單仍是主系統下發的離線操作者；名單內的人可選用 AD 密碼登 Agent、不必另設離線密碼；名單不在、AD 密碼對也不給進。AD 也連不到時退回離線密碼或 local-admin，登入頁一個帳號欄，Agent 自己判斷。

憑證（D18）：客戶多半沒有 CA 憑證可貼，「驗證憑證」勾選框是工程師思維。改成 首次信任、之後釘住（SSH known_hosts 模式，專案 SSH 連線已是 RejectPolicy＋known_hosts）：第一次連自動記下伺服器憑證指紋、畫面顯示「已信任 xxx 的憑證（到期 2027-03）」；之後指紋變了就擋並紅字「伺服器憑證變了，若非你們更換憑證請聯絡網管」，管理員按「重新信任」才放行。拿掉勾選框，只留「貼上 CA」當進階選項。加密方式預設 STARTTLS，連不上自動退 389 並黃字「目前是明文連線」。使用者零操作、零憑證知識，中間人攻擊擋得住。此條推翻 CM-2239（當時裁預設不勾的理由正是「客戶沒憑證」，釘住模式同時滿足兩邊）。主系統 LDAP 設定頁與 Agent 端都改。

抽套件（D19）：ldap_adapter.py 兩百多行混了兩種東西——目錄連線（約 180 行，只靠 ldap3）與主系統帳號對應（約 30 行，查 user_auth_providers／users 表，繼承 BaseRepository）。Agent 沒那兩張表，裝整支 jedi-iam 要拖 Flask-RESTful 全套且 jedi-common 版本線衝突（Agent 釘 0.0.31、jedi-iam 要 ≥1.3.4——jedi-masking 抽成零相依套件的理由相同）。

jedi-ldap（新，零相依只靠 ldap3）
  LdapDirectory(config).verify_user(username, pw) → DirectoryUser(uid, name, email, groups)
  LdapDirectory(config).test_connect() → 結構化結果（連不到／憑證變了／帳號格式／密碼錯）
  LdapConfig dataclass；首次信任釘住（指紋算與比對；存哪由呼叫端給 store）
  加密預設 STARTTLS；不丟 Flask 例外
jedi-iam.LdapAdapter  → 瘦成 30 行：呼叫 jedi-ldap 拿 DirectoryUser，再查綁定表；失敗計數補 LDAP 路徑
evidence-agent        → 裝 jedi-ldap，不裝 jedi-iam

復用性（決策者：「要可以復用抽出來才有意義」）：判準是不綁任何一張表、不綁 Flask、只靠 ldap3。現在就有三個使用者——主系統登入（jedi-iam 瘦身後）、Agent 離線登入（本案）、未來任何「用客戶 AD 驗身分」的地方（FR-132 存取管理若做 AD 群組對應角色、License Center 若接客戶目錄）。C11 標的「跳脫寫在兩處」「鎖定不計入」「加密預設無」三個洞抽出來後只修一處。

4.1 老闆說的「像第三方元件掃描的模式」是什麼

FR-134／156 的第三方元件掃描是主系統側選單一個獨立模組：使用者挑 Agent、上傳源碼或 SBOM、按掃描，不必先有稽核任務，結果自己一張表（compliance.source_scans）、有自己的報表頁，之後要當證據再掛到任務。本案要把這種「工具自己能按」的形狀搬到 Agent 上，而且對八支工具通用。

4.2 畫面長什麼樣（雛形幕 3）

主控台「掃描工具」分頁：

1. 工具卡：八支工具一人一卡，顯示「已設定帳密／未設定」「這台能跑」（capabilities）；未設定的卡按下去先導去帳密分頁。
2. 目標：從授權清冊挑（設備名＋IP，清冊版本與更新時間標在旁邊）；允許手打 IP 或網段，但必須落在授權網段內，否則當場擋（D3）。
3. 參數：照工具目錄的 param_schema 長表單（與主系統派工表單同一份定義，心跳下發、Agent 快取——FR-157 D3 同一機制）。
4. 執行：按下去進本機執行紀錄，進度與取消比照派工（同一支 connector、同一個 cancel_event）。
5. 完成：摘要（發現幾項）、報告下載、「回傳主系統」狀態三種：已回傳（附時間）／待回傳／回傳失敗（附原因，例如主系統回 413）。在線時可按「立即重試」不等下一次心跳；離線時按鈕反灰、連回後自動補傳，急著要報告用「匯出 PDF」帶走。主系統端「手動匯入 Agent 報告」列第二期。畫面上來源一律寫「Agent 手動」（不寫「本機」，使用者分不出什麼本機）。

4.3 Agent 內部怎麼跑

不另寫執行路徑：手動執行＝自己造一張「本機任務」，走 task_executor._run_one 同一條（ack 與 result 的「雲端」改成本機紀錄表）。差異只有三處：任務來源標 local、沒有 job_execution_uid、結果回報對象是本機紀錄＋待傳佇列。

兩支工具的範圍（§13.1 實查）：Nmap 的執行主機走 params.hosts，_run_one 呼叫 connector 前對 params 整包 allowed_targets.check()，執行主機本來就過清冊，手動模式沿用同一條不必另做。ZAP 的網址是 FR-129 刻意留的缺口（allowed_targets.py 檔頭明寫網址不在授權範圍）；手動模式若照現況開 ZAP 等於開一條對任意網址發掃描的路。決策者裁「所有掃描工具都要能在 Agent 獨立執行」，所以不是拔掉 ZAP，是把網址型目標納進清冊規則：Agent 端 allowed_targets.py（203 行）把 ZAP 的網址欄位加進比對欄位，urlsplit 取 hostname → getaddrinfo 解成 IP → 過同一張清冊；解不到或不在網段內就拒。主系統清冊不用改（網址最後仍落到 IP）。主系統派工的 ZAP 也一併受這條管（現況不過清冊）。並發上限：同一台 Agent 同時最多 2 個掃描、1 個診斷，超過排隊；執行不綁 session，session 過期掃描繼續。

本機紀錄表（Agent SQLite 新增 local_runs）：uid、kind（scan／diag）、tool、targets、params（不含帳密）、started_by（本機操作者帳號）、status、summary、report_file_uid（走既有 upload_files）、created_at、finished_at、synced_at、cloud_uid。

4.3b 八支工具都在 Agent 執行，差別只在入口與結果落點

決策者點出：第三方元件掃描「也是 call Agent 執行，應該整個在 Agent 上執行，只是看使用者要用哪一台」。實查現況確實如此——FR-156 之後它的執行就全在 Agent（主系統只剩開單、簽直傳票、收結果出報表），不存在「移過來」的問題；本案要補的是Agent 自己的入口。這與其他七支工具是同一個形狀：

給 runner：八支都在 Agent 執行、都有兩個入口；差別只在結果回傳落哪張表。第三方元件掃描手動模式不是第二套，是在 source_scans 多一個「來源＝Agent 手動」的值。

4.4 結果回主系統要落在哪（D4）

「掛成證據」：有了 a 之後，第二期在任務抽屜加「從 Agent 自主執行紀錄挑一份當證據」，複製參照即可。第一版不做。

5.1 要回答的問題

「Agent 跟某幾台設備連不到，原因是什麼？」拆開來是四個層次：這台 Agent 自己的網路正不正常（介面、閘道、DNS）→ 到目標的路通不通（ping、traceroute）→ 目標的服務開不開（連接埠、TLS、HTTP）→ 跟主系統之間通不通（心跳端點、憑證、時鐘）。工具就照這四層挑。

5.2 兩區：這台 Agent 的網路（儀表板）＋對目標做診斷（勾選）

決策者裁：「看自己這台」做成 UI，不是勾選項。網路除錯分頁分上下兩區。

上半區「這台 Agent 的網路」：進頁自動載入、不用按、不對外送任何封包、無噪音。右上「重新整理」「複製成文字」（貼給網管）。

下半區「對目標做診斷」：選目標 → 勾項目 → 執行。每項標噪音等級（安靜＝正常應用程式天天在做；中＝某些 IDS 規則會記；高＝多數監控當掃描告警）。

規則：一次只查一台、不並發；同一目標每分鐘最多 3 輪、每 session 最多 20 個目標；上次勾的組合記本機。

噪音以總量計，不只看單項（D20）：決策者問「全勾不就一堆，不算攻擊嗎」。答：單項各只做一次正常連線，但八項全勾對同一台二十秒內二十幾次連線，敏感的 IDS 可能記為探測。所以按「開始診斷」前先算這次總共幾次連線（勾幾項加總：ping 4、DNS 1、埠 N、TLS 1、HTTP 1、SSH 1、MTU 1、主系統序列 5、traceroute 30、持續監測 60）與約幾秒，顯示噪音條；總連線數超過 10、或含中高項目，執行前跳確認框列出每個原因。連線之間固定隔 1 秒、不連發。不採「只能勾一項」——判讀卡要多項結果合起來才講得出「斷在第幾跳」。門檻、每項噪音等級、埠上限、間隔都寫死在程式，不能被參數改。

5.3 結果怎麼呈現：結論在上、證據在下（雛形幕 4）

決策者問「會知道斷在哪嗎」。結果區三層：

第一層：路徑圖。每一跳一個節點、綠勾紅叉，紅叉那跳就是斷點；只跑 ping 沒跑 traceroute 時兩端之間標「未探測（勾 traceroute 可看每一跳）」。

第二層：判讀卡，固定三句——結論／依據／建議動作。判讀規則是確定性的，不做 AI 推測：

第三層：原始輸出，摺疊，等寬字，給網管複製。

每次執行產一份診斷報告：可匯出文字／PDF（html.escape 走既有 WeasyPrint 路徑）、可「回傳主系統」（走 outbox，落自主執行紀錄 kind=diag）。報告含內網拓撲，下載過 session scope；回傳主系統後下載過能力點。

5.4 安裝後連不上主系統（雛形幕 7）

決策者問「一開始安裝就連不通，怎麼知道本體在哪」。未同步狀態下 local-admin 登入 → 總覽紅橫幅「尚未同步」→ 按「診斷主系統連線」→ 跑 §5.2 的固定序列 → 路徑圖＋判讀。這條序列同時是手冊「安裝後連不上」一節的排查順序，UI 與手冊同一份邏輯。

6.1 三道門：「誰能登入」與「能掃誰」是兩件事

決策者擔心的是「有登入口＝有跳板」。答案是掃描範圍由主系統決定、與登入身分無關，三道門各管各的：

%%{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'}}}%%
flowchart LR
  A[任何人] --> G1
  subgraph G1[門 1 · 誰能登入]
    direction TB
    L1[local-admin 安裝時設]
    L2[離線操作者 主系統下發名單]
    L3[入場券 主系統簽]
  end
  G1 --> G2
  subgraph G2[門 2 · 能對誰動手]
    direction TB
    C1[授權目標清冊 主系統下發 Agent 只快取]
    C2[從未收到清冊 = 一律拒]
    C3[Nmap 執行主機 ZAP 網址解析 IP 也過]
  end
  G2 --> G3
  subgraph G3[門 3 · 能用什麼]
    direction TB
    T1[八支工具 只接表單定義參數]
    T2[除錯清單 不包埠範圍 nmap 封包擷取]
    T3[沒有命令列 subprocess 傳陣列不經 shell]
  end
  G3 --> R[對清冊內設備跑既有工具 僅此而已]

推論：攻擊者拿到 local-admin 密碼，能做的是對清冊內那幾十台已授權設備跑 OpenSCAP；不能掃 192.168.77.5、不能掃任意網段、不能下指令。未同步過的 Agent（D12）連門 2 都過不了，什麼都掃不了。守衛測試固定一條：用 local-admin session 打清冊外目標必須 403。

6.2 逐威脅配鎖

本案把 Agent 從「只聽主系統」變成「現場也能操作」，攻擊面變大是事實；下面是每一道新門配的鎖。這些是 A～E 每棒的驗收條件，不是另一棒。

守衛測試（runner 每卡 commit 前跑）：① 除錯與獨立掃描的所有入口都呼叫 allowed_targets.check()（grep 斷言）；② 沒有任何 shell=True；③ 工具清單裡沒有 nmap／tcpdump／iperf 字樣；④ 回報端點對重複 uid 回 200；⑤ local-admin session 打清冊外目標 403；⑥ 未同步狀態下所有掃描與除錯入口（主系統連線診斷除外）403；⑦ Agent 端 grep 不到任何「新增使用者」路由。

7.1 現況哪裡會掉

%%{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 M as 主系統
    participant AG as Agent
    participant Q as Agent 待傳佇列（SQLite）
    M->>AG: 心跳回應帶 pending_tasks
    AG->>M: ack（pending→dispatched）
    Note over M,AG: 此時斷線
    AG->>AG: 掃描照跑（執行緒不受影響）
    AG->>AG: 報告存本機 upload_files（本來就在這台）
    AG--xM: POST result 失敗
    AG->>Q: 入列：task_result{uid, status, summary, result_ref}
    AG->>Q: 入列：稽核事件、local_runs 摘要
    Note over M,AG: 主系統畫面：「Agent 離線中，掃描結果等待回傳」
    Note over M,AG: 復線
    AG->>M: 心跳成功
    AG->>Q: 依序取出
    AG->>M: POST result（冪等：已是終態回 200）
    AG->>M: POST local-runs（批次 50 筆）
    AG->>Q: 成功才刪；失敗留著下次再送
    M->>M: 任務→succeeded、證據照既有流程產生

實查結果：

• 執行不會停：dispatch_tasks 每筆開 daemon thread，與心跳無關；報告 _upload_report 存 Agent 自己的儲存，不經主系統。這兩段已經是對的。
• 會掉的只有兩處：① _result() 的 POST 失敗只記 log（註解「留待 FR-056.4 觀察」）；② 主控台稽核事件走心跳游標，離線期間累積在本機但沒有上限控管。
• 主系統端：任務停在 dispatched，Agent 在線判定＝心跳間隔×3 沒心跳就算離線（is_online）。畫面目前只會看到「執行中」轉圈。

7.2 做法（D7）

• Agent 待傳佇列：SQLite 新表 outbox（id、kind：task_result／local_run／audit、payload、idempotency_key、attempts、next_retry_at、created_at）。_result() 失敗即入列；心跳成功後 drain() 依 created_at 序送，每次心跳最多 50 筆，失敗退避（1、2、4、8 分鐘，上限 1 小時）；送成功才刪，重啟中途可能重送，靠主系統終態冪等吸收。上限 10,000 筆，丟棄順序：先稽核事件、再 local_runs 摘要、任務結果永不丟（一台一天不會超過幾十筆）。
• 主系統端冪等：實查 agent_task_service.receive_result 只對 cancelled 短路，succeeded 再收一次會再跑 write_success 與 listener（證據再產一次）。改成「任何終態（succeeded／failed／cancelled）＝回 200 記 log 不重做」；新端點 POST /agents/local-runs（批次 50 筆）以 (agent_id, local_uid) 去重，agent_id 從通行證取、body 帶的無效。
• 主系統端顯示：任務卡片與檢測執行頁，當 agent_tasks.status in (dispatched, running) 且該 Agent is_online=false → 顯示「Agent 離線中，結果等待回傳（最後心跳 10/24 14:31）」，不計入失敗、不觸發逾時失敗；Agent 清單加「待傳 N 筆」欄（心跳帶 outbox_size）。
• 逾時與收尾（D15）：實查主系統沒有任何派工逾時機制（dispatched_at 只是記錄欄位，jedi-remote-agent 與 jedi-detection 都沒拿它判過期）。所以離線不會被誤判失敗，但永久離線（機器報廢）的任務會永遠「執行中」無人收尾。補：主系統既有背景排程加一條「dispatched／running 且該 Agent 離線超過 7 天 → failed，原因 agent_unreachable」，system_context("agent_task_offline_reaper") 具名、看到 0 筆不動；Agent 復線後回傳已 failed 的單走終態冪等（記錄不重做）。
• 離線判定加遲滯（斷斷續續的線路）：Agent 端連續 3 次心跳失敗才切「離線」、連續 2 次成功才切「在線」，避免畫面跳動與佇列反覆送一半；佇列每筆獨立冪等，送一半重來不重複。
• 「連得到但被拒」與「連不到」分開：主系統整台重裝、憑證對不上時心跳是 401／403 不是逾時；總覽與診斷頁顯示「連得到主系統但身分被拒（憑證或註冊問題）」，與「連不到」是兩種狀態、兩種處置。
• 離線期間任務被主系統取消：Agent 不知道、跑完回傳；主系統收到已取消任務的結果記錄但不產證據、不炸。
• Agent 重開機（斷電）：記憶體 session 全失效、正在跑的掃描中斷——執行紀錄標「中斷」；待傳佇列在 SQLite 不丟；開機後自動重連補傳。
• 磁碟空間：低於門檻（既有 disk_space.py）拒絕新掃描、總覽紅字；佇列本體只存指標與摘要。

7.3 本機狀態放哪（D11 已裁：同一個 SQLite，不起 Postgres）

實查 Agent 本機現在存的東西：檔案索引 upload_files（SQLite 單檔，FR-066 D2 從 Postgres 換來）、工具帳密（Fernet 加密檔）、清冊與工具表單定義（JSON 檔）、主控台稽核（JSONL＋游標）、救援碼（一碼一檔）。本案要加：離線操作者名單、local-admin 與離線密碼雜湊、本機執行紀錄 local_runs、待傳佇列 outbox。全部是單機、單進程、幾千筆以內、無並發寫入的資料。

業界邊緣節點（Nessus scanner、Wazuh agent、FortiGate）都用嵌入式 DB，沒有一家為本機帳號起 Postgres。做法：四張新表進既有的 SQLite 檔；清冊與工具定義的 JSON 順手收進去；稽核 JSONL 與帳密加密檔維持（帳密有獨立金鑰檔的理由，FR-157 D11）。反悔條件：Agent 要跑多 worker 同時寫、或本機資料要給第三方報表工具直接查。

8.1 多據點怎麼表達（D8 已裁：用 Agent 名稱，不加據點欄）

老闆的情境是「台北主系統，高雄、台南、日本、新加坡各一台」。決策者裁：Agent 名稱本來就是管理員取的，「高雄機房 Agent-01」一看就知道在哪，一台 Agent 通常就是一個點，不另加「據點」欄位。自主執行紀錄與 Agent 清單照 Agent 名稱篩；手冊寫命名建議「地點＋用途＋編號」。

8.2 離線操作者授權頁（雛形幕 6）

Agent 管理頁每台 Agent 多一個「離線操作者」設定：勾人（租戶內使用者）、每人選範圍（Agent 設定／Agent 檔案／獨立掃描／網路除錯四個能力點的子集，不能超過這個人在主系統本來就有的能力點）、授權到期日（預設 90 天）。存 remote_agent_offline_operators（agent_id、user_id、scope、expires_at、local_password_set_at、revoked_at）。心跳回應帶給 Agent；撤銷即從名單拿掉，Agent 下次心跳刪快取。

新增兩個能力點：detection.remote-agent.run-local-scan（獨立掃描）、detection.remote-agent.net-diag（網路除錯），照 FR-157 D10 形狀；入場券的 scope 也帶這兩個。

Agent 清單對「離線操作者 0 位」顯示紅字警示（提醒要嘛勾人、要嘛確認現場有 local-admin 密碼）；名單內的人若還沒設離線密碼，授權頁標「離線密碼：未設定」；有撤銷但該台離線還沒同步到的，標「有待同步的撤銷」。離職流程手冊寫明：把人從離線操作者移除，離線中的那台等它上線才生效。

8.5 重啟 Agent（D14）

兩種部署形態都有外部拉起機制（systemd Restart=on-failure、compose restart: unless-stopped），主控台重啟＝Agent 自己優雅結束（取消執行緒、關 DB、exit 0）由外部重拉，不是 Agent 去呼叫 systemctl 或 docker API（要特權、又多一條能被濫用的路）。

流程：確認框列出「正在跑的掃描 N 個會中斷並標 cancelled；待回傳佇列不受影響；約 10 秒後恢復」→ 寫本機稽核、進 outbox → 回「已送出」→ 前端倒數 15 秒打 /api/me（401）→ 顯示「Agent 已重啟，請重新登入」。旗標分兩種（§13.2 #8）：restart_when_idle（預設，等沒任務）、restart_now；主系統按鈕預設前者、勾「立即」才後者。總覽加 uptime_sec 與上次重啟原因（手動／崩潰重拉／主系統要求）。

同區塊：服務狀態（uptime）、下載支援診斷包（Agent 側新做，不是 FR-071 的主系統包：log 尾段、去敏設定、本機儀表板快照、最近診斷結果）。權限：local-admin 與 configure scope。

8.3 自主執行紀錄分頁

Agent 管理頁「自主執行紀錄」：一列一次執行——Agent、種類（掃描／除錯）、工具、目標、執行者、時間、狀態、報告下載（經 Agent 資料面取檔，Agent 離線時標「報告在離線的 Agent 上」）。篩 Agent／工具／人／日期。

8.4 心跳新欄位

Agent → 主系統：outbox_size、local_login_enabled（離線超過 30 天停用時回 false）、local_admin_set、console_allow_cidr_installed（安裝時設的，供主系統驗交集）、uptime_sec、last_restart_reason。主系統 → Agent：offline_operators[]（含撤銷→Agent 踢 session）、console_allow_cidr（只能收緊）、restart（when_idle／now／空）。全部照既有 observer 形狀掛進 _heartbeat_loop。

排序以「決策者何時看得到畫面」為準：先讓登入頁與離線橫幅出現，再長功能。同一批彼此不改同一檔；登記型共用檔（能力點 migration、ROUTE_TABLE、心跳 payload 組裝、FE console/ 路由）分批。

批 0 兩張是地基（套件與 DB 機制），批 1 起才能並行；批 1 內 A1／B1／C1 改不同檔；批 2 的 A2 與 D1 都動 enroll.py 的 observer 掛點（登記型）→ A2 先、D1 排批 2 尾或改批 3，開卡時定。

跨 repo 的棒（A1、D2、E1）各拆成「BE＋套件」與「FE 主站」兩張卡，一卡一 repo。

決策者要求在定案前把整案重走一遍：會不會有死結、有沒有情境沒想到、有沒有既有機制沒注意到、有沒有違反開發與資安規範。本節是逐項實查（開檔看程式、不憑印象）後的結果，實查推翻本稿前面說法的地方標 🔁，前面各節已同步改正。

13.1 既有機制盤點：哪些本來就有、本案直接接上

這張表的目的是「不重複造輪子」。每一列都是開檔確認過的。

13.2 死結推演

逐條想「這個情境會不會卡住、誰來解」。

13.3 前面沒想到的情境（本輪新增）

13.4 Agent 本機 DB 的版本機制（新 D16）

現況 app_factory.py 只對 upload_files 一張表 create(checkfirst=True)，再加 _heal_upload_files_columns 補欄位——這是「沒有 migration 的 migration」。本案四張新表若也照這個做法，每張表各寫一支 heal，下一個 FR 再加就第三套。

13.5 開發規範對照

13.6 資安規範對照（.claude/rules/security/ 八支逐條）

兩條例外登記（SR-08.2 逐項回結果、SR-04.9 內網直連）是本案資安面最需要決策者知道的：規則寫給「主系統代人連任意目標」的情境，本案「Agent 對清冊內目標做診斷」是功能本體。例外不是繞過，是把「目標受限」這個前提寫清楚讓規則成立。

決策者問「變例外會不會造成漏洞」——不會，前提是三個條件都守住（已裁照此登記）：①目標只能是清冊內設備＋主系統＋閘道＋DNS（探得到的範圍＝主系統本來就授權 Agent 掃的範圍，沒有新增可達性）；②單目標序列、每分鐘 3 輪（掃 42 台要 14 分鐘以上，不是掃描器的形狀）；③結果寫稽核含完整目標。對比：主系統派 Nmap 回來的報告本來就逐台列埠與服務，比除錯頁詳細得多，而那是正常功能，因為目標過清冊；除錯頁的風險上限不會超過它。唯一新增的是三個固定例外，而那是 Agent 本來天天在連的對象。守衛測試「local-admin 打清冊外目標必須 403」就是確保前提永遠成立，它被改掉例外就失效，寫進登記。

13.8 既有 LDAP 功能的缺漏（決策者要求順便檢查）

登入本體做對三件事（資安連線分析 C11 已驗）：OpenLDAP 兩段式 bind（先用服務帳號查 DN，再拿 DN＋使用者密碼真的登一次目錄；AD 走 NTLM 一步到位）；帳號欄特殊字元跳脫；加密連線可驗憑證可貼 CA。重要設計特性：LDAP 使用者不自動建帳號，要先有本地帳號再由管理員綁定（LOGIN_LDAP_ACCOUNT_NOT_BIND）——對 Agent 是好消息，「誰能用 LDAP 登」仍是主系統的使用者表。

13.7 本輪修正彙整（對前面各節的影響）

決策者要求：「先用最嚴謹的設計模式跟能力來看有多少工要做，再來跟 PM 討論有哪些可以分階段或剔除。切階段、切內容要分清楚，不能因為戰線太長造成東西沒辦法銜接。」本節是這張底表。每一工項都寫到「砍掉會斷什麼」，PM 砍的時候知道後果。

14.1 四個原則（切階段的判準）

1. 每個階段結束都是可出貨狀態：階段 N 做完，客戶升級不會壞、沒做的功能只是「看不到」，不是「按了壞掉」。這是戰線拉長也不會斷的保證。
2. 地基先、畫面後，但地基只做該階段畫面需要的部分：不為第三階段的畫面先鋪第一階段的表。
3. 登記型共用檔分批（能力點 contract、事件碼、心跳 payload 組裝、FE 路由、Agent observer 掛點、SQLite 版本清單），同批兩張卡動同一個登記檔必衝突。
4. 套件先於宿主，宿主先於畫面：jedi-* 改了要發版（或 dev 走 path dependency）宿主才接得上；宿主端點好了 FE 才有東西打。

14.2 五個階段

哪些能砍：P0 不能砍，砍了後面每張卡都要往已經太大的檔案裡硬塞。P1 是老闆要的最低限度。P2 的掃描、除錯、重啟三塊可以各砍各的。P3 可以整段延後，但「離線 7 天自動收掉任務」建議留，它修的是現在就有的問題。P4 的 AD 可以延後，文件不能砍。

14.3 全量工項表

欄位：ID（階段-序號）／做什麼／repo／改哪些既有檔（行數＝現況，超過 800 標 🔴）／新開哪些檔／依賴／可砍？砍了斷什麼。

P0 地基（7 項）

P1 進得去（8 項）

P2 能做事（9 項）

P3 接回主系統（7 項）

P4 LDAP 與收尾（6 項）

14.4 數量總覽

最小可出貨組合（PM 砍到底的下限）：P0 全部（9 卡）＋P1 不可砍 6 項＋P2-1／P2-2／P2-3（手動掃描）＋P3-1／P3-2／P3-5＋P4-4／P4-5。約 28 卡。砍掉的是：CIDR、網路除錯整塊、維運與重啟、自主執行紀錄頁、離線顯示、LDAP、e2e。

老闆原始五點對應：① 直接登入＝P1；② 離線身分＝P0-1～3＋P1；③ 獨立掃描＝P2-1～3；④ 網路除錯＝P2-4～6；⑤ 續傳＝P3-1～2；資安＝P3-7＋P4-5 例外登記。P4 LDAP 是決策者追加（老闆可能會要）。

14.5 銜接保證：每階段結束的狀態

每階段都是「加法」：沒有任何一階段會把前一階段做的東西改形狀。這是戰線拉長也不斷的根據。