下載收進權限點、剩餘天數看得到、profile 自動到位、主系統設定 Agent 掃描工具、稽核走 logging 管線、登入後能切語言

狀態：v2 定案、實作完成待收尾｜日期：2026-10-29｜母卡 CM-3199、子卡 CM-3200～CM-3222、CM-3282～CM-3285｜前作 FR-166（主控台、D23 離線權限同主系統、HTML 預覽）、FR-156（弱點資料心跳同步）、FR-157（工具帳密搬進 Agent）、FR-033（主系統稽核事件管線）｜並行 FR-169（下載檔加密） 開發 branch：五個 repo 皆在 feature/FR-139；runner 開工 git branch --show-current 再確認，不對就停下問，不切

🔴 這份是設計決策，不是現況。 上線後的畫面與 API 現況看 SPEC 頁。

PM 2026-10-28 看完 FR-166 手測版後的六條原話與決策者補充：

做完之後

• 沒有「下載證據」權限的人，主站十個地方的下載鈕都不見、Agent 主控台只剩預覽、主系統「Agent 掃描執行紀錄」頁報告也只剩預覽。出貨預設沒有任何角色有這顆，管理員要給才有。SVG 這類 Agent 不 inline 的格式就看不到。
• 主控台總覽多一張卡「離線登入還能用 N 天」，到 0 變紅並說明只剩本機管理員能登；離線密碼與 AD 一起鎖，連回主系統才能再用。
• 主控台總覽多一張卡「檢測基準」：幾支、多久前更新、幾支失敗，可按「立即檢查更新」，健康區多一盞燈。
• 主系統上傳新版 profile 後，每台 Agent 下次心跳自己比對、背景拉、回報；profile 頁每個版本展開看得到每台 Agent「已取得／待更新／失敗／離線」，有「補更新」鈕。主控台也有「立即檢查」。
• 主系統「檢測工具」頁翻回來改名「Agent 掃描工具設定」：左邊選一台 Agent，右邊是那台每支工具一張卡（已設定／未設定、設定時間、設定方式、最近測試）；每張卡一顆功能選單：設定、測試連線、清除，都開彈窗、當場生效。帳密只過一手、主系統不落地；Agent 離線整頁鎖並說明。
• Agent 稽核改寫進本機 SQLite 的 system_logs 表，欄位與主系統同一份；主控台多「日誌」分頁可依人、事件、日期篩，可匯出 CSV。預覽、進頁、開工具表單、開執行紀錄詳情也記；升級時舊版 jsonl 稽核一次搬進表。回傳主系統的機制不變，游標改自增 id。
• 所有下載（主控台檔案、報告、日誌匯出、診斷包，主系統 Agent 執行紀錄報告）都照 FR-169 加密：下載前顯示一次性密碼。
• 主控台登入後右上角可切中英。

flowchart LR
  subgraph 主系統
    FU[jedi-file-upload 簽票<br/>action=preview/download]
    CAP[(各模組 download 能力點<br/>認領者自己查)]
    HB[心跳回應<br/>profiles 清單＋補更新旗標]
    DP[資料面直推 8443<br/>PUT／DELETE /detection/credentials]
    SL[(system_logs)]
  end
  subgraph Agent
    PC[profile_cache 既有取檔]
    PS[profile_sync 照 vulndb_sync]
    CS[credential_store]
    AP[audit() → Filter → Queue → DBLogHandler 子類]
    SQ[(SQLite system_logs)]
    UI[主控台：預覽／剩餘天數／日誌／語言]
  end
  CAP --> FU
  HB --> PS --> PC
  DP --> CS
  AP --> SQ --> |心跳 console_events| SL

主系統與 Agent 之間有兩條路：Agent 出站的心跳（每 60 秒拉一次，profile 清單、補更新旗標夾在回應裡），以及主系統連進 Agent 資料面 8443 的直推（mTLS＋綁定 agent 身分的短效 JWT，回應比對 Agent 指紋）。要當場知道結果的動作（測試連線、取證據檔、設定與清除工具帳密）走直推；狀態同步走心跳。直推的前提是主系統連得到 Agent 的 8443：落地版同在客戶內網一定通，SaaS 版要客戶開放。

全部開卡前實查（2026-10-29）。

5.1 下載權限點（T1：A1、A1b、A2、A2b、B1、B4、B5、A5、F2、F6）

票分用途。 GET /file/access-token/<uid>?action=preview|download，省略＝preview（舊前端不壞）。票的 scope 字串在既有 file_access_scope 後接 :download，下載端點 file_access_guard 只收帶 :download 的票，pdf-preview 端點兩種都收。簽 download 票前先跑 adapters.download_guard（宿主注入，None 時不擋）。

認領者各看自己那顆。 登記表 FILE_ACTION_DOWNLOAD；主系統 core/plugins/_file_ownership.py::assert_download_capability 一支共用：上傳者本人直接放行，否則查該模組的 download 能力點；9 類認領者各自呼叫它。能力點 migration 照 FR-166 形狀但第三段「預設角色授權」整段不寫。匯出端點照既有 @require_capability("<模組>.export") 形狀補 2 顆。

Agent 端：票範圍 download-files；files_download、netdiag 報告、runs 報告三條下載都改這個範圍；新增 GET /console/files/<uid>/preview 走 inline_policy。主系統「Agent 掃描執行紀錄」報告下載端點 _ADMIN_CAPABILITIES 改 detection.remote-agent.download-files。

前端：signedDownloadUtil.fileDownloadUrl 帶 action=download；下載鈕顯示條件＝「持該模組 download 能力點，或是自己上傳的」，各頁帶各自那顆；共用預覽框由呼叫端給能力點；匯出鈕看各自 export 顆；主控台檔案頁改「預覽」為主、下載鈕看 me.scope 含 download-files。

陷阱：Agent 驗票見到不認得的範圍整張拒收，所以 Agent（A2 套件＋A5）要先認得 download-files，主系統才可以簽；升級順序 Agent 先。

5.2 離線剩餘天數（T2：F1）

總覽卡：剩餘 = offline_login_days − offline_days，只在 net === OFFLINE 顯示；≤0 紅字＋「只剩本機管理員可登入」。資料心跳已下發、Agent /console/state 已回，純畫面。到期後離線密碼與 AD 一起鎖（D9）：Agent operator_session_valid 不分登入方式都看 offline_login_disabled()，登入當下與每個請求重驗走同一支；登入頁兩個分頁一起灰。

5.3 profile 同步（T3：A4、A7、B2、F4）

照 vulndb_sync.py 逐段對應：

失敗冷卻同 vulndb，避免每次心跳重拉。

主控台總覽「檢測基準」卡：Agent profile_sync.summary() 回 {total, ok, error, last_synced_at, listed}，取得時間用快取完成標記檔的 mtime（重啟不丟）；卡片顯示「N 天前更新／M 支基準 K 支失敗」，主系統沒下發清單時顯示「主系統未提供」；「立即檢查更新」與弱點資料卡共用 useSyncCheck；健康區 profiles 燈超過 7 天或有失敗轉黃。

5.4 Agent 掃描工具設定（T4：A9、B3、F5、F8，直連改寫）

頁面：主系統「合規與稽核 → Agent 掃描工具設定」（route agent-tool-credentials，門檻 detection.remote-agent.configure）。左欄選 Agent（連線中／離線、已設定 n／N 支、最近心跳）；右欄是那台每支工具一張卡：已設定／未設定、設定時間、設定方式（由主系統設定／Agent 主控台）、最近測試結果。只列租戶啟用、要帳密的工具。卡片標題列一顆「⋮」功能選單：

頁頂「管理啟用的工具」對話框是租戶層開關：關掉的工具整個停用，這頁不列、任務設定也選不到。

直推流程：

1. is_online false → 409 FILE_AGENT_409003，不打 Agent。工具目錄不認得 → 404。
2. infra/remote_agent/agent_credential_client.py 以 mTLS＋短效 JWT 打 Agent；帶帳密的 PUT 在非 full 模式直接拒（不走裸 http）；回應比對 X-Agent-Fingerprint，不符拒用並稽核 6081。
3. Agent 端 /detection/credentials 走 credential_handover.store（照工具目錄 schema 用 secret_form.validate 驗、寫 credential_store、稽核 6086／6087 method=handover）；欄位不合回 400，訊息只有欄名。
4. 主系統把回來的 status 寫回 remote_agents.configured_tools（assign_fields），畫面當場翻面；下一次心跳照常以 Agent 自報值覆蓋。
5. 主系統稽核 AGENT_CREDENTIAL_SET／AGENT_CREDENTIAL_CLEARED method=remote，只帶工具代號。

離線與舊版 Agent：右欄整頁鎖（離線說明連不上、舊版說明請先升級），每 30 秒重抓 Agent，連回自動解鎖；填到一半斷線會關彈窗。

5.5 Agent 稽核管線（T5：A3、A6、F3）

業務碼 ──audit(logger,"AGENT_X",AgentEventCode.AGENT_X,**fields)──▶ logger "agent"
                                                                     │
                                       ConsoleActorFilter（補 user_uid/user_nickname/login_method/source_ip；無 request→system）
                                       SecretMaskingFilter（jedi-common）
                                                                     │
                                                              QueueHandler（請求不等 DB）
                                                                     │  專屬執行緒
                                                              QueueListener ──▶ AgentDBLogHandler(DBLogHandler)
                                                                                  只放行 event_code≠None/''/'-'；缺欄補 None
                                                                                  system_log_service.add_system_log（@transaction 自開 scope）
                                                                                       │
                                                                                 SQLite system_logs
                                                                                       │
                                                        心跳 console_events：select id>cursor and event_code in REPORTED
                                                        ack → cursor=max(id)（自增 id，重啟不重送）

• 呼叫點：41 處從 audit("credential_set", g.console_session.sub, tool=code) 改成 audit(logger, "AGENT_CREDENTIAL_SET", AgentEventCode.AGENT_CREDENTIAL_SET, tool=code)。actor 參數消失。
• 哪些回傳主系統：事件碼表的屬性（套件 AgentEventCode 旁一個 REPORTED 集合），不再是 audit.py 另一個集合。
• 新事件碼（A2 在套件加、B1 鏡像）：AGENT_LOGOUT、AGENT_CREDENTIAL_TESTED、AGENT_PASSWORD_CHANGED、AGENT_HEARTBEAT_LOST、AGENT_HEARTBEAT_RESTORED、AGENT_VULNDB_UPDATED、AGENT_PROFILE_UPDATED、AGENT_LOCAL_SCAN_REFUSED、AGENT_LDAP_CHANGED、AGENT_STORAGE_CHANGED、AGENT_SUPPORT_BUNDLE_DOWNLOADED，從 6207 起。
• 保留期 180 天，心跳每日一次 delete where act_time < now-180d。
• 覆蓋率（D10）：core/console/audit_import.py 啟動時把舊 console-audit.jsonl（含 .1）照時間排序一次寫進表，35 個舊動作名對到事件碼、對不到的記 6235；同一交易寫一列 6234 當冪等標記，寫完才把檔改名 .imported；act_time 原樣保留到微秒，主系統以 at 去重不會重複。audit_once 同一 session 同一對象在窗內只記第一筆（只在真的記了才更新時刻）。
• 匯出（D10）：GET /console/api/logs/export 同一組篩選、不分頁、上限 50,000 列，CSV 帶 BOM、以 = + - @ 開頭的儲存格加單引號；守「看日誌」範圍＋download-files 兩層；走 file_protect.send_protected（FR-169）。
• 過渡層：AgentDBLogHandler 只存在因為 0.0.31 的 emit 不過濾且直讀 record.user_uid；檔頭註解只寫這一句與「升 jedi-common ≥1.3.6 即刪」。
• A3 開工第一件事：實測 QueueListener 執行緒上呼叫 add_system_log，@transaction 能自開 session_scope（session_context 是 ContextVar，新執行緒為空，應可）；不行就在 handler 內顯式 with session_scope()。

5.6 語言切換（T6：F1）

Login.vue 的 toggleLocale 抽成 useLocale.js（localStorage 記住，照 theme.js 形狀），殼頂欄與登入頁共用。

5.7 安全規則對照

• 下載票分用途後，preview 票打 download 端點必 403（A1 突變測試）。
• 7＋2 顆能力點出貨零角色；gen_permission_matrix.py 重產矩陣讓 FE 角色矩陣多一欄「下載／匯出」。
• 設定帳密：fields 只在這次直推的 request body 過手；主系統 log、稽核 message、回應 body 都不得帶值；帶帳密只走 mTLS 通道；回應比對 Agent 指紋。
• 所有下載出口走 FR-169 send_protected：主控台檔案、網路除錯報告、診斷包、日誌匯出，主系統 Agent 執行紀錄報告；預覽不加密。
• 入場券帶 Agent 不認得的範圍時回 AGENT_CONSOLE_TICKET_SCOPE_UNKNOWN（請升級 Agent），不混進「無效或過期」。
• 稽核 message 經 SecretMaskingFilter；A3 突變：把 filter 拿掉，含 password= 的測試要紅。
• 日誌端點唯讀、四種範圍任一可看；不回 path／line_no 這種程式座標給使用者。

批（Stage）＝工作坊同時開幾個小弟一起跑的那一組：同一批不改同一個既有檔、不依賴對方產出。底表在 handoff/cards.py，兩個斷言已過。

登記型檔只讓一張卡碰：manifest.tsv／event_code.py／remote_agent.py adapters（B1、B2、B3 各在不同批）；console/routes.py（A6）；enroll.py（A7）；Shell.vue 與 i18n key（F1 先登記「日誌」項，F3 只新開 view）；capabilities.js 由 B1 重產、F2 commit。

套件異動：jedi-file-upload 1.4.0、jedi-remote-agent 1.9.0、jedi-detection 1.7.0、jedi-issue 1.4.0（意見回饋附件認領者），皆已發版、BE 已釘。批 10 與手測直修只動 Agent、BE、FE，沒有新套件版本。

表中 B3／F5 兩列寫的是開卡範圍（派工單＋等心跳）；行為以 D5 直連為準，見 §5.4。

• 升級順序 Agent 先：主系統簽的票帶 download-files，舊 Agent 整張拒收，持有者登不進主控台。與 FR-166 P3-0b 同一個坑。
• 票改用途會不會壞第三方呼叫：action 預設 preview，只有 FE 的 fileDownloadUrl 一處改帶 download；其他簽票呼叫者行為不變。
• profile 的 cache 路徑是凍結契約 /data/content/cache/：正式版靜 compose 掛可寫 volume；用源碼直接跑的開發機要自己把這個目錄給 Agent 帳號寫入權，否則每支 profile 回報 PermissionError。
• QueueListener 執行緒上的 session scope：A3 第一件事實測；不行就 handler 內顯式開 scope。
• SQLite 寫表失敗不得讓請求失敗：DBLogHandler.emit 整支 try/except 走 handleError，1.3.6 有、0.0.31 沒有，子類要補。
• 設定帳密走直推：主系統要連得到 Agent 的 8443。落地版同內網沒問題；SaaS 版要客戶開放 8443 進來，否則設定、測試連線、取證據檔一起不能用（同一個前提）。
• 主系統送來的欄位一定照工具 schema 驗：曾有人直打 API 存進錯的欄位名，卡片顯示已設定、掃描時才報缺少憑證。
• profile 冷卻：拉失敗每次心跳重拉會把頻寬吃光（vulndb 已踩過），冷卻照抄。
• JobExecutionDrawer.vue 3179 行：F2 只改一行加 v-can，不碰其他。

設計決策與拆卡；開工後現況看 SPEC 與手冊；每棒做了什麼看 handoff/FR-166.1-LOG.md。