定版交付：Agent 主控台權限能力點化

Agent 主控台權限變成 26 顆主系統能力點 agent.<功能>.<動作>，角色頁逐顆給；簽票與離線名單照既有管道把持有的顆帶到 Agent；Agent 版本舊時丟掉不認得的顆、照常登入並提示；主系統派下來的掃描紀錄歸「掃描 · 檢視」。

本案動到四個程式 repo 與兩類文件，另外重產了出貨基線。契約（清單本身）在 jedi-agent-protocol；主系統這邊是資料遷移、端點守門與角色頁；Agent 這邊是驗票與路由守門；前端分主控台與主站兩塊。下表列每個 repo 交付了什麼、落在哪些檔。

能力點全名 agent.<功能>.<動作>；入場券與 Agent 守門用去掉 agent. 的 <功能>.<動作>。模組 agent 同時是角色樹第一層的分組名。清單的單一來源是 jedi_agent_protocol.console_scopes，三邊都從那裡讀，不各自硬寫。

共 26 顆；離線操作者可下放 24 顆，只有 update.read、update.execute 不下放（換版不可逆，斷線時不該有人換版；重啟可逆、斷線卡住要能現場重啟，所以下放）。

模組為什麼是 agent 而不是 detection：出貨 seed 的系統角色帶萬用字元 pattern——稽核主管 detection.*.*，稽核員、一般成員、唯讀 detection.*.read。能力點若放在 detection 底下，新裝客戶的稽核主管升級後自動持有全部 26 顆（含檔案下載、重啟、換版），唯讀角色自動持有 11 顆檢視。agent 是新模組，沒有任何既有 pattern 命中。DEV 的角色沒有這些 pattern，在 DEV 驗不出來，所以守衛測試掃 seed 檔本身。

權限從角色設定頁到 Agent 主控台走兩條路：使用者在線時點「進入主控台」拿入場券（即時路），斷線時用離線操作者名單登入（離線路）。兩條路都讀同一份角色持有，本案沒有新增任何同步機制，只把寫進票與名單的範圍從 7 個換成 26 個。下圖是完整順序。

%%{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','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','sequenceNumberColor':'#FFFFFF'}}}%%
sequenceDiagram
  autonumber
  actor M as 管理員
  participant H as 主系統 API
  actor U as 使用者（瀏覽器）
  participant A as Agent（:8444 主控台）
  M->>H: 角色頁「Agent 主控台」子頁勾顆，或按「比照主系統功能帶入」
  H->>H: GET /roles/{uid}/agent-console-mirror 依 MIRRORS 算出該加的顆（只算不寫）
  M->>H: 儲存角色
  U->>H: POST /remote-agents/{uid}/console-ticket
  H->>H: 逐顆查使用者持有的 26 顆，寫進票 scope；一顆都沒有回 403
  H-->>U: 五分鐘入場券（RS256，scope 原樣 26 個短名字串）
  U->>A: 帶票登入
  A->>A: 範圍過濾：認得的留下、不認得的丟掉並計數；全部不認得回 403 TICKET_SCOPE_EMPTY
  A-->>U: session；/api/me 回 scope 與 dropped_scopes，前端依 *.read 開分頁、依 update／execute／download 開按鈕
  A->>H: 心跳
  H->>H: 離線操作者名單：每人依當下持有的顆算可下放範圍（24 顆內）
  H-->>A: 整份名單；縮權的人踢掉已登入 session

第 5 步的「持有」由 jedi-iam 展開服務算，含萬用字元 pattern（*.*.* 的系統管理員自然持有 26 顆）。第 8 步丟掉不認得的範圍只會讓人少拿權限、不會多拿，所以主系統可以先升、Agent 慢慢跟；舊 Agent 收到新顆名會全部丟掉，等同登入失敗。反向不相容：新 Agent 不認舊的 7 個範圍名，舊主系統發的票在新 Agent 上全丟、回 403，升級順序必須主系統先。第 11 步的名單只決定「能不能離線登入這台」，範圔永遠跟著角色，主系統改角色下一次心跳就生效。

• 守門只收緊不放寬。每條 Agent 路由與主系統端點換顆後，新顆持有者集合是舊顆持有者集合的子集；主系統執行紀錄的三個下載端點守 scan.download／netdiag.download 任一，route 內再依紀錄種類細判一次。
• 主系統端點對應：進入主控台（簽票）與 Agent 清單可見→26 顆任一；重啟→ops.execute；換發憑證→keys.update；代設工具帳密→tools.update；補更新基準→ops.update。Agent 管理頁本身的新增、檢視、修改、刪除仍是 detection.remote-agent.* 四顆，不動。
• 執行紀錄不分來源。本機手動與主系統派工的掃描紀錄都歸 scan.read 看、scan.download 帶走；網路除錯紀錄歸 netdiag.*。
• 「比照主系統功能帶入」是一次性動作，不是連動。依 MIRRORS 15 條把對應顆勾起來，管理員可再取消，要按儲存才寫入。對照：檢測工具的檢視／修改→工具設定的檢視／設定；掃描設定檔檢視→掃描檢視、修改→掃描執行；LDAP 設定→LDAP；平台授權→授權；儲存設定→維運檢視／設定；產品更新→更新；Agent 管理的修改→金鑰設定＋維運執行；Agent 管理的新增→連線設定；主系統證據下載→檔案下載。日誌與網路除錯沒有對應的主系統功能，不會被帶入。
• 既有角色的升級。migration 把字面持有舊 7 顆的角色（含客戶自建）展開到新顆：configure→工具、LDAP、金鑰、授權、維運、連線六組的檢視＋設定共 14 顆再加掃描檢視；browse-files→檔案檢視、日誌檢視；run-local-scan→掃描檢視＋執行、日誌檢視；net-diag→除錯檢視＋執行、日誌檢視；download-files→檔案、掃描、除錯、日誌四顆下載，ops.download（診斷包）只給同時持 configure 者；restart→ops.execute；upgrade→更新兩顆。萬用字元持有者不展開。展開後刪舊 7 顆與 role_capabilities、route_capabilities、role_capability_patterns 的對應列。
• 出貨預帶：系統管理員靠 *.*.*；稽核員 agent.scan.read、agent.scan.download；檔案下載四顆與更新兩顆不預帶給任何非管理員角色。
• 票上寫法：scope 是 26 個短名的字串陣列，原樣寫，約 2.5 KB；Agent 登入入口 body 上限 8 KB。
• 錯誤碼：Agent 路由沒權限 403 AGENT_CONSOLE_SCOPE_DENIED；票上範圍全部不認得 403 TICKET_SCOPE_EMPTY；主系統一顆都沒有簽不到票 403 AGENT_CONSOLE_NO_SCOPE。
• 前端只決定看得到、點得進，真正的牆是 Agent 端 require_session(<短名>) 與主系統 _ADMIN_CAPABILITIES；直接打 API 一樣被擋。

自動測試（四 repo 工作區，合回前；protocol 鏡像測試在合回後對主線再跑一次）：

DEV 資料庫（migration 套用後）：capabilities 中 module='agent' 26 顆、舊 7 顆 0；ui_routes 有 remote-agent-console（tree_page、非選單）綁 26 顆；role_capabilities、route_capabilities 無孤兒；原持 configure 等舊顆的角色已展開（例如 IT 執行人員持 21 顆、系統管理員 26 顆）。

主系統端點實打（HEAD 起在 8123）：系統管理員簽票 200、票帶 26 個範圍；只持 agent.scan.download＋detection.remote-agent.read 的角色對掃描報告過守門、對除錯報告 403。

出貨基線：188 基線庫套本案 migration 後重產三份產物；本機乾淨 postgres:16 跑完整 init.sh（198 表、271 條 RLS policy、cm_app 缺權限 0），agent 顆 26、舊顆 0、子頁綁 26、基線 marker 在、稽核員預帶 2、非系統角色萬用字元命中 agent.* 為 0。

未實機驗證：Agent 的新票登入 200、舊票 403 是用 Flask 測試 client 打的，沒另起 Agent 程序；掃描報告下載沒拿到 200（DEV 的 Agent 離線，過守門後連不上）；角色頁子頁、帶入鈕、主控台側欄與橫幅沒有人在瀏覽器實機點過。

三件事還沒做，讀本頁時不要把它們當成已完成。

畫面手測。角色頁「Agent」組底下的子頁 26 顆與「比照主系統功能帶入」鈕、主控台側欄依權限顯示、舊版 Agent 的頂部橫幅，全部只有自動測試驗過，沒有人在瀏覽器實機點過。DEV 的 Agent 要重起到含本案的版本才看得到。由決策者接。

push 與上版。四個 repo 的 feature/FR-172 都有本案的 commit，尚未 push；STG 與 POC 都沒上。上版順序必須主系統先、Agent 後，因為新 Agent 不認舊的 7 個範圍名。由決策者接。

主線本來就失敗的一條守衛。test_fr132_capability_home_route 的 test_dev_every_capability_has_a_home 列出 13 顆 proj.* 專案角色能力點沒有 home_route，與本案無關，由 FR-194 處理。

本頁只寫交付了什麼與現在長什麼樣。為什麼這樣決定、過程中發生什麼、怎麼操作，分別在設計、歷史、手冊三類文件裡，照下表找。