Agent 只出站，客戶一個埠都不用開

整案一句話：主系統不再連 Agent；Agent 開一條長輪詢去主系統問「有事嗎」，有事主系統立刻回、Agent 做完把結果送回來；原本八種「主系統連 Agent」的用途全部改走這條；直推與 Agent 8443 的指令端點退役。

依賴一句：P1 是全部的前提；P2 與 P3 可平行；P4 等 P2、P3 全部驗完才做。決策者功課：D1～D8。

1.1 時間軸：三個月內換了方向，前提卻是錯的

結論：FR-171 把一個本來在單向網路能跑的機制，換成了不能跑的。而且 FR-039 以來的檔案與同步問答路徑，從來沒在單向網路跑過。

1.2 現在單向網路下壞掉的八種功能

主系統主動連 Agent 8443 的用途，開檔逐支盤出來共八種：

1～6 改成「Agent 定時來拉」就通；7、8 要「主系統當下拿到回答」，固定間隔的輪詢不夠——這就是為什麼本稿提長輪詢而不是定時輪詢（§3）。

1.3 心跳補推為什麼救不了

FR-171 D3 設計「直推打不通就等心跳回來補推」，很多人以為這代表單向網路可以用。實查 AgentCommandService.redispatch_pending()：補推走的是同一支 AgentDataPlaneClient.command()，同樣連 Agent 8443。單向網路下每一跳的補推都失敗，單永遠 pending，管理頁「連線」欄永遠顯示「僅單向」。設計當時給的解法是 hover 提示「請確認 Agent 主機的 8443 埠對主系統開放」——也就是把問題交給客戶開埠，而客戶不會開。

業界對照：Datadog、CrowdStrike、Tailscale 的 agent 全部只出站；GitHub Actions self-hosted runner 就是長輪詢（runner 打 GitHub 問「有 job 嗎」，吊 50 秒）；Chef／Puppet 定時 pull。長輪詢是「客戶不開埠」這個前提下最少元件的正規做法。

3.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（長輪詢元件）
  participant M as 主系統 API
  participant Q as 指令佇列（DB 正本＋Redis 喚醒）
  participant U as 管理員瀏覽器
  A->>M: GET /agents/commands?wait=30（通行證＋DPoP）
  M->>Q: 查這台有沒有待辦
  Note over M: 沒有 → 訂閱 Redis 頻道 agent:<uid>，吊著
  U->>M: 按「派工」（或重啟／升級／取消／換證／改設定）
  M->>Q: 寫 DB 正本（工單 pending／restart_requested／…）＋ publish agent:<uid>
  Q-->>M: 喚醒
  M-->>A: 200 {commands:[{kind:"task", task_uid, payload}, …]}
  Note over A: 逐條交給既有 handler（cmd_tasks／cmd_restart／…的 app 層函式）
  A->>M: POST /agents/tasks/<uid>/ack（既有）
  M->>Q: status=dispatched
  A->>M: GET /agents/commands?wait=30（立刻再掛一條）
  Note over M,A: 30 秒沒事 → 204，Agent 立刻再掛

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

三道防撞沿用 FR-171：task uid 冪等、ack 即 dispatched、Agent 本機單執行緒佇列。長輪詢只有一個觸發點（不像直推＋補推兩個），反而更簡單。

3.2 端到端：同步問答怎麼走（7、8）

%%{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 主系統 API（worker X）
  participant R as Redis
  participant M2 as 主系統 API（worker Y）
  participant A as Agent
  U->>M: POST 測試連線 {agent_uid, target}
  M->>M: 寫 agent_requests（kind=probe, status=waiting, request_id）
  M->>R: publish agent:<uid>；subscribe reply:<request_id>
  Note over M: 吊著等，最多 30 秒
  A->>M2: GET /agents/commands（剛好掛在 worker Y）
  M2-->>A: {commands:[{kind:"probe", request_id, target}]}
  A->>A: 跑 probe
  A->>M2: POST /agents/replies/<request_id> {result}
  M2->>M2: agent_requests status=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 喚不醒對方。專案已有 Redis（core/extensions.py redis_client），用它的 pub/sub 跨進程喚醒。結果本身落 DB（agent_requests.result），Redis 只傳「好了」——Redis 掉訊息最壞 30 秒逾時時再查一次 DB。

逾時：瀏覽器那條吊 30 秒沒等到就回 504「Agent 無回應」，agent_requests 留 waiting，Agent 晚到的回覆照樣落 DB（可查，不浪費）。

證據檔（8a）的特例：bytes 不能走 JSON 回覆。

暫存落主系統磁碟是 FR-039「binary 不落雲端」的例外——那是 SaaS 的要求，落地版主系統本來就在客戶內網（D4 待裁）。

3.3 八種用途的歸宿

主系統側的正本：1～4 用既有表；5、6 沒有正本，併進新表 agent_requests（kind、agent_id、payload、status waiting／taken／done／expired、result、request_id、建立時間）——7、8 也用這張表。也就是說只新增一張表，五種「沒正本的指令」與「要回答的請求」共用；1～4 不搬進去（它們的狀態機各自更複雜，硬併等於重寫）。

3.4 長輪詢回應的形狀（契約草案）

GET /api/1.0/agents/commands?wait=30
→ 200 {
  "commands": [
    {"kind": "task", "task_uid": "…", "payload": {…}},
    {"kind": "probe", "request_id": "…", "payload": {"target": "…"}},
    {"kind": "config_changed"}
  ],
  "server_time_utc": "…"
}
→ 204 （30 秒沒事）

• 一次最多回 20 條（沿用 REDISPATCH_LIMIT），剩下的 Agent 下一條請求再拿。
• task 的 payload 可能帶明文工具帳密（現況直推 body 就是），長輪詢回應走的是同一條 TLS＋通行證＋DPoP 的 Agent 出站連線，守門強度不低於直推（直推是 mTLS＋JWT；出站是主系統 HTTPS 憑證指紋釘死＋通行證＋DPoP，FR-171 D 已定）。
• Agent 拿到 probe／credentials_set／query_logs 等要回答的，先回 taken 再做（POST /agents/replies/<request_id> 帶 status: taken），主系統據此分辨「Agent 沒拿到」與「Agent 拿到了在做」。

3.5 主系統側的「等回答插槽」是共用元件

app/remote_agent/service/agent_request_service.py（新）：

• ask(agent, kind, payload, timeout=30) -> result：寫 agent_requests、publish 喚醒 Agent 的長輪詢、subscribe 回覆頻道、吊著等、回結果或 raise 逾時。
• fire(agent, kind, payload)：寫表＋喚醒，不等。
• reply(request_id, status, result)：Agent 回覆端點呼叫，落 DB＋publish。

7a、7b、8a、8b 都只呼叫 ask，不各寫一套等待邏輯。jedi-detection 的 agent_probe_client／agent_credential_client／agent_cancel_client 三支 client 改成呼叫主系統注入的 ask／fire（套件不認識 Redis，透過 port 注入）。

3.6 Agent 側的長輪詢元件

guidant_agent/sync/app/command_pull.py（新，照 config_pull.py 的 WorkerComponent 形狀）：

• 註冊成功後起一條背景執行緒，無限迴圈 GET /agents/commands?wait=30；逾時 204 立刻再掛；連線錯誤退避（5 秒起、最多 60 秒）後再掛。
• 拿到 commands 逐條分派到 §3.3 的既有函式；分派表是模組內一張 dict，不是 if 鏈。
• 要回答的：先 taken，做完 done；做失敗回 failed 帶原因（主系統照樣喚醒瀏覽器回錯誤，不讓它等到逾時）。
• 升級中、重啟已排定：拿到 task 回 failed reason=upgrading（現況直推回 409 的語意搬過來），主系統單留 pending。
• 🔴 長輪詢與心跳是兩條獨立的出站連線：心跳照舊每 300 秒一跳只表存活；長輪詢掛著不算心跳。Agent 離線判定仍看心跳 last_seen（不動 offline_threshold_sec）。

3.7 退役清單

批＝可同時跑的一組；登記型共用檔（契約 commands.py、routing.py、Agent registry.py、事件碼表）由批 1 一張卡當 owner 一次掛齊。

批 1 三張互不依賴可同跑（契約是登記型檔，F-2、F-3 開工時契約還沒發版，各自先用本機 path 指 F-1 工作區——這正是環境卡 E-1 要在批 2 收的）。design.md 會用 handoff/cards.py 驗批。

• WebSocket／gRPC 長連線：長輪詢做到八成功能、零新元件；真有上百台 Agent 再評估（反悔條件：單一主系統 Agent 數 > 100 或 gthread 執行緒常態吃滿）。
• 心跳改變：心跳維持 11-01 裁示只表存活，長輪詢是獨立連線；離線判定不動。
• SaaS 版「binary 不落雲端磁碟」：D4 接受暫存；SaaS 到時另案。
• Agent 主控台（8444）：不動。
• FR-171 的身分、換證、金鑰登記簿、設定通道、事件通道、DPoP：全部保留，本案只換「指令怎麼到 Agent」與「同步問答怎麼走」。
• gunicorn 不驗直接上：批 0（P-0）先驗 sync 卡死與 gthread＋配額，結論決定 D2。
• 舊版 Agent 升級：決策者 11-07 裁「舊的先不管，全部重新安裝」——已裝的 Agent（123、POC）本案出貨後重裝，不走「主系統先收長輪詢再刪直推」的兩段升級，不留相容路徑。