FR-181 Agent 只出站通道 — 設計定版 v1.0

🔴 本版已凍結。現行版本是 design-v1.1.md（無人值守調整：批次 7→6、P-0 判據寫死、驗收改本機模擬）。

客戶網路確定不讓主系統連進 Agent 主機。現況八種「主系統主動連 Agent 8443」的功能在這種客戶一個都送不到：派工、重啟、升級、設定變更通知、立即換證、取消檢測（六種指令）；測試連線與工具帳密、證據檔四操作與遠端查日誌（同步問答）。心跳補推也是連 8443，救不了。

做完後的狀態：

整案一句話：Agent 永遠是發起方；主系統有事就讓掛著的那條請求立刻回去。

依賴：批 1 的結論決定 E-1 翻不翻 gunicorn 預設；批 2 三張互不依賴；批 5 三張分屬三個 repo。決策者功課：批 1 驗完看一眼數字拍板 D2；批 5 驗收前把 123 Agent 主機 8443 入站擋掉（或告訴首腦擋）。

4.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
  autonumber
  participant A as Agent command_pull
  participant M as 主系統 /agents/commands
  participant DB as DB 正本
  participant R as Redis
  participant U as 管理員
  A->>M: GET /agents/commands?wait=30（通行證＋DPoP）
  M->>DB: 查這台待辦（pending 單／restart／update／agent_requests waiting）
  Note over M: 沒有 → waiter.wait(uid, 30) 訂閱 agent:<uid>
  U->>M: 按「派工」
  M->>DB: 寫正本（after_commit）
  M->>R: publish agent:<uid>
  R-->>M: 喚醒
  M->>DB: 再查一次
  M-->>A: 200 {commands:[{kind:"task", task_uid, payload}]}
  A->>A: 分派表 → task_intake → task_queue.submit
  A->>M: POST /agents/tasks/<uid>/ack（既有）
  M->>DB: status=dispatched
  A->>M: GET /agents/commands?wait=30（立刻再掛）
  Note over M,A: 30 秒沒事 → 204 → Agent 立刻再掛

正本仍在 DB：工單表、restart_requested、rollout 表、agent_requests。Redis 只是「醒來查表」的鈴；鈴沒響最壞 30 秒逾時後 Agent 再掛一條時查表也會查到。沒有第二個佇列（FR-171 D3 原則不變）。

防撞：task uid 冪等、ack 即 dispatched、Agent 本機單執行緒佇列（沿用 FR-171 三道）；restart 被 Agent 取走時主系統立刻清 restart_requested（不然每條長輪詢都回 restart）。

4.2 同步問答怎麼走

%%{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
  autonumber
  participant U as 瀏覽器
  participant M as 主系統 worker X
  participant R as Redis
  participant M2 as 主系統 worker Y
  participant A as Agent
  U->>M: POST 測試連線 {agent_uid, target}
  M->>M: ask()：agent_requests(kind=probe, waiting, expires=+5m)
  M->>R: publish agent:<uid>；subscribe reply:<request_id>
  Note over M: 吊著等，最多 30 秒（配額 ≤ 8 條，滿了 503）
  A->>M2: GET /agents/commands（掛在 worker Y）
  M2-->>A: {commands:[{kind:"probe", request_id, payload}]}
  A->>M2: POST /agents/replies/<id> {status:"taken"}
  A->>A: 跑 probe
  A->>M2: POST /agents/replies/<id> {status:"done", result}
  M2->>M2: agent_requests done、result 落 DB
  M2->>R: publish reply:<request_id>
  R-->>M: 喚醒
  M->>M: 讀 agent_requests.result
  M-->>U: 200 {reachable: true}

Redis 是為了跨 gunicorn worker：瀏覽器吊在 worker X、Agent 回覆打到 worker Y，進程內 Event 喚不醒對方。結果本身落 DB，Redis 只傳「好了」。

逾時：30 秒沒等到回 504 GRC_504_AGENT_NO_REPLY，agent_requests 留 waiting，Agent 晚到的回覆照樣落 DB。taken 與 failed：Agent 拿到要回答的先回 taken（主系統據此分辨「沒拿到」與「在做」）；做失敗回 failed reason=，主系統立刻喚醒瀏覽器回錯誤，不讓它等到逾時。

4.3 證據檔四操作（D4 A 案）

錯誤碼不變：504→FILE_AGENT_UNREACHABLE、Agent failed→FILE_AGENT_BAD_RESPONSE（FE 依碼顯示）。

5.1 契約（jedi-agent-protocol 0.3.0，F-1）

GET  /api/1.0/agents/commands?wait=30        → 200 CommandsResponse | 204
POST /api/1.0/agents/replies/<request_id>    body Reply（JSON）或 multipart（file + Reply 欄位）
GET  /api/1.0/agents/files/<request_id>      → bytes（Agent 來拿主系統暫存的檔）

Command        {kind, request_id?, task_uid?, payload, expires_at?}
CommandsResponse {commands: [Command], server_time_utc}
Reply          {status: taken|done|failed, result?, reason?}

十三個 kind：

既有直推路徑常數與 body dataclass 不刪（D6），檔頭註解改「直推預設關，長輪詢是主路徑」。

5.2 主系統長輪詢端點（jedi-remote-agent 1.13.0，F-3）

套件只做端點與組裝，不認識 Redis、不建表，四個 port 由宿主注入（app/ports/command_channel.py）：

端點組裝順序：pending 且 _due 的工單（搬 redispatch_pending 的查單邏輯）→ restart → update → agent_requests；一次最多 20 條；有東西立刻回，沒有 waiter.wait 後再查一次；同台第二條進來 preempt 讓第一條回 204。

5.3 等回答插槽（A-1）

app/remote_agent/service/agent_request_service.py 三個方法，7a、7b、8a、8b 都只呼叫這三個，不各寫等待邏輯：

• ask(agent, kind, payload, timeout=30)：寫表（expires_at＝+5 分）→ notify → subscribe reply:<id> 吊著 → 喚醒讀 DB result → 回；配額滿 503 GRC_503_AGENT_BUSY；逾時 504 GRC_504_AGENT_NO_REPLY。
• fire(agent, kind, payload)：寫表＋notify，不等。
• reply(request_id, status, result)：落 DB＋publish reply:<id>；taken 只改狀態不喚醒。

背景排程（core/scheduler_agent.py）：expire_requests 每分鐘、reap_orphans 每小時。

5.4 agent_requests 表（E-1）

compliance.agent_requests：id／uid／agent_id FK／tenant_id／kind／payload jsonb／status waiting|taken|done|failed|expired／result jsonb／reason／expires_at／taken_at／done_at／created 系列。索引 (agent_id, status, expires_at)。GRANT cm_app、RLS 照 agent_tasks。主線 phase=active → 出貨基線待重產。

為什麼只加一張表：取消、換證（沒正本）與測試連線、帳密、證據檔、查日誌（要回答）性質相同——「一次性、短命、要麼做完要麼過期」；工單／重啟／升級各有自己更複雜的狀態機，硬併等於重寫。

5.5 Agent 長輪詢元件（F-2、A-3）

guidant_agent/sync/app/command_pull.py，照 config_pull.py 的 WorkerComponent 骨架：

• 註冊成功後起背景執行緒無限迴圈；204 立刻再掛；2xx 逐條分派；連線錯退避 5→10→20→40→60 秒。
• 分派表 dict[kind -> handler]，不是 if 鏈；F-2 接四個（task／restart／update／config_changed）、其餘留 no-op 給 A-3 填。
• 要回答的先 taken 再做，做完 done，失敗 failed reason=。
• 升級中／重啟已排定拿到 task → 不進佇列、reply failed reason=upgrading（現況直推 409 語意）。
• 回覆走 reply_sender.py，送不到進 event_sender 同一條 outbox（新 kind reply）。
• 🔴 長輪詢與心跳是兩條獨立出站連線；離線判定仍看心跳 last_seen。

抽 app 層：cmd_tasks._parse → task_intake.py；detection_route 的 cancel／probe → scan/app/cancel.py／probe.py；blob_route 四操作 → files/app/blob_ops.py。route 殼改薄、開關開時仍呼叫同一支，不複製。

5.6 gunicorn（P-0、E-1）

main.py gunicorn options 加 worker_class（env GUNICORN_WORKER_CLASS）、threads（GUNICORN_THREADS）；P-0 只加入口不翻預設，E-1 依 P-0 結論翻成 gthread／16。install.sh 寫 .env 補這兩個變數。

5.7 開關（D6、D7）

守衛（C-1）：預設皆 False；主系統開關 False 時 patch AgentDataPlaneClient.command 成 raise，跑派工／重啟／升級／換證／設定變更五條全綠。

批＝可同時跑的一組；登記型檔各只讓一張卡碰（契約 F-1、routing.py F-3、Agent registry.py／data_plane_server.py F-2、remote_agent.py plugin 掛點 A-1、main.py／migration E-1、jedi-detection 三 client A-4）。底表 handoff/cards.py，python cards.py 斷言：依賴在更早的批、同批同 repo 不改同一檔。

各卡的改哪些檔、新開哪些檔、驗收條件以 cards.py 為準（Notion 卡從它產）。

全部在 123 Agent 主機 iptables 擋 8443 入站（iptables -I INPUT -p tcp --dport 8443 ! -s 127.0.0.1 -j DROP）的狀態下做：

• WebSocket／gRPC 長連線（反悔條件：單一主系統 Agent 數 > 100 或 gthread 執行緒常態吃滿）。
• 心跳改變、離線判定改變。
• SaaS 版「binary 不落雲端磁碟」（D4 暫存加密另開卡）。
• 源碼包瀏覽器直傳 8444（D5 擱置）。
• 舊 Agent 兩段升級（全部重裝）。
• FR-171 身分、換證、金鑰登記簿、設定通道、事件通道、DPoP 全部不動。