Agent 跟進

Agent 跟進的意思是：主系統升到某一版後，把那一版主系統包裡附的 Agent 安裝包推給各台 Agent。規則是先 1 台，成功再推其餘；任何一台失敗，還沒推的自動暫停。

Agent 不連外網、不連更新站，包只從主系統拿。主系統與 Agent 是兩條版號線（主系統 1.27.x、Agent 1.4.x），「Agent 不比主系統新」只靠一件事守：Agent 包只取 host_version 那一版主系統包附的那份，且 host_version 不得比主系統現行版新（agent_rollout_service.py:7-8、98-101）。

%%{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 S as 主系統每分鐘排程
    participant DB as agent_update_rollouts
    participant A as Agent 容器
    participant H as Agent 主機 systemd
    participant U as 原廠更新站
    S->>DB: 進度檔 succeeded 且 to=現行版 → 建列（第 1 批 1 台 dispatched、第 2 批 pending）
    S-->>A: 交易提交後背景 POST /update/notify（mTLS＋短效 JWT，5 秒）
    A->>S: 心跳 POST /agents/heartbeat
    S-->>A: 回應 data.update = {target_version, bundle_sha256, size}
    A->>S: GET /api/1.0/agents/update/bundle（Range 續傳）
    A->>A: 驗大小與 sha256 → 寫 agent-order/agent-upgrade-order.json
    H->>H: path 單元觸發 upgrade-host order：precheck → stage → 舊映像驗新映像 → runner
    H->>H: 寫 upgrade-progress.json（同 job_id）
    A->>S: 下一次心跳帶 upgrade_result {version, status, at, error}
    S->>DB: record_result → succeeded／failed
    S->>DB: 下一分鐘 _advance：前一批全成功→下一批 dispatched；有失敗→paused
    S->>U: 終態列 POST /v1/report（target=agent），送達才寫 reported_at

推進分三處（agent_rollout_service.py:12-15）：

一列＝一台 Agent 跟主系統某一版升級的進度。建表 scripts/sql/2026-10-30-fr167-agent-update-rollouts.sql，not_before 加在 2026-10-30-fr167-agent-follow-optional.sql，reported_at 加在 2026-11-01-fr167-agent-rollout-reported-at.sql。ORM infra/product_update/model/agent_update_rollout.py，entity 常數 domain/product_update/entity/agent_update_rollout_entity.py。

唯一鍵 (agent_id, host_version)。cm_app 只有 SELECT／INSERT／UPDATE。

「開著的列」＝pending／dispatched／paused（OPEN_STATUSES）。一台 Agent 同時只有一列開著：建新一版的列時，同一台還開著的舊版列改 paused、error="已改跟主系統 <版>"（agent_rollout_service.py:483-494）。

%%{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'}}}%%
stateDiagram-v2
    [*] --> dispatched: 第一批那 1 台（無排程）
    [*] --> pending: 其餘、或排程推送的第一台
    pending --> dispatched: 前一批全成功／排程時間到
    pending --> paused: 前一批有失敗（自動）／管理員暫停
    dispatched --> succeeded: 心跳回報 succeeded
    dispatched --> failed: 心跳回報 failed
    dispatched --> paused: 管理員暫停／同台改跟新版
    paused --> succeeded: 已下發過、結果照收；或繼續時已是目標版
    paused --> failed: 已下發過、結果照收
    paused --> dispatched: 繼續（重新先 1 台）
    paused --> pending: 繼續（其餘等第一台）

3.1 主系統升完自動建列（_start_following）

agent_rollout_service.py:461-481，每分鐘排程呼叫。全部成立才建：

1. 進度檔 status=succeeded、to＝主系統現行版、from 有值且不等於現行版（換接已完成）。
2. 這一版還沒建過任何列（list_by_host_version(current) 為空）。
3. 這次升級的更新單 with_agents 不是 false（follow_scope_from_job，:155-166）。找不到單（手動 CLI 升級、舊版主機）當作全部跟進。
4. 升級目錄裡找得到這一版的 Agent 包（§4.1）；找不到記 warning、不建列。

對象：status=active、enabled 不是 false、且比 Agent 包版號舊的 Agent；更新單有勾 agent_uids 就只取那幾台，勾了但已停用、已最新或不存在的略過並記一行 log（pick_chosen，:129-139）。

排法 plan_batches（:176-180）：依 last_seen_at 新到舊（同時間依 id），最近心跳最新的那台自成第 1 批 dispatched，其餘全部第 2 批 pending。

3.2 放下一批（_advance）

agent_rollout_service.py:496-516，只動現行版那一組，逐批看：

• 這一批 pending 且帶 not_before 的：時間到就轉 dispatched，不看前一批（前一批是別次推送的結果）。
• 其餘 pending：看前一批（next_batch_status，:104-111）——有任一台 failed → 全部轉 paused、error="前一批有 Agent 升級失敗，已自動暫停"；全部 succeeded → 全部轉 dispatched；還有沒結果的 → 先等。

3.3 重新排批（_rebatch）

agent_rollout_service.py:526-542，「繼續」與「推選定」共用。把要推的那幾台重新照「先 1 台再其餘」排在現行版最後一批之後（base = max(batch) + 1）：

• 第一台（第 base 批）：沒排程 → dispatched；有 not_before → pending 並帶 not_before。
• 其餘（第 base+1 批）：pending，等第一台的結果。
• 🔴 只有第一台帶 not_before，其餘的舊值要清掉（clear_not_before）：_advance 看到過期的 not_before 會不等前一批直接下發。
• 每台 requested_by＝操作者、error 清空。

3.4 下發時叫醒 Agent

任何一列從別的狀態轉成 dispatched（_set，:339-348；或 _create 直接建成 dispatched），agent_id 記進 _woken。交易提交後才逐台呼叫 notify_in_background（§6.1）——Agent 被叫醒馬上心跳，交易沒提交就讀不到下發列，等於白叫。叫不到只是退回等下一次心跳，不影響分批狀態。

主系統升級時管理員決定 Agent 要不要跟；不跟的之後在更新中心手動推。

4.1 Agent 包從哪來

find_agent_bundle（agent_rollout_service.py:205-232）：

• 位置：<GUIDANT_UPGRADE_DIR>/bundles/guidant-ai-<host_version>/agent/（主機升級時解開、容器唯讀掛載）。主機升級收尾 upgrade_cleanup.sh:86-97 只留本次那一包的 agent/，所以現行版的 Agent 包一定在——前提是用 guidantai upgrade 升的。
• 檔名 guidant-agent-compose-<版>.tar.gz，旁邊要有 .sha256（64 位小寫 hex）。
• 沒有、不只一份、.sha256 壞了都回 None（不派）。不在這裡重算整包雜湊：主系統包已驗過簽章與雜湊才解開，Agent 下載完會再對一次。
• 版本說明：同目錄 guidant-agent-compose-<版>.notes.json（{"version", "notes":[…]}，≤64KB、最多 20 條、每條 ≤500 字），版號對不上回空（:235-253）。
• 最低相容 Agent 版：讀 incoming/guidant-ai-<現行版>.release.json 驗過印章的 min_agent_version（:256-271）。

能力點與守門同 update-center-api-spec.md §2；寫入另在 app service 擋 SaaS 非平台管理員，並寫事件 AGENT_UPDATE_ROLLOUT_CHANGED（6238）。

5.1 GET agents（overview）

AgentRolloutService.overview()（agent_rollout_service.py:625-661）。先在交易內組資料，再到交易外拉下發中那幾台的進度（最多等 3 秒網路，不能佔著 DB 連線）。

5.2 每台 Agent（_agent_item，:722-733）

5.3 POST agents/pause、agents/resume

5.4 POST agents/push

5.5 POST agents/remind-later

寫 ROOT 租戶 system_configs PRODUCT_UPDATE/agent_remind＝{version: <Agent 包版號>, until: 現在+7 天}。回 {version, snoozed_until}。錯誤：412008、500 500001。記的是版號，換新版提醒就回來。

5.6 紀錄頁的 Agent 列

history()（:689-692）以登入者身分讀全部列，同一 host_version、同一 created_at（同一交易建的）彙整成一列，target=agent，帶 agent_total／agent_succeeded／agent_failed。總狀態：還有 pending／dispatched → running；有 paused → paused；有 failed → failed；全成功 → succeeded（:274-313）。

infra/remote_agent/agent_update_notify_client.py。認證通道與設定帳密同一道 agent_credential_client.send（infra/remote_agent/agent_credential_client.py:67-75）：

• AGENT_AUTH 啟用時：mTLS（主系統的雲端客戶端憑證）＋現簽的短效 JWT（AGENT_JWT_TTL_SEC，預設 60 秒），claims 綁 agent_uid、tenant_id、bound_fp（裝置指紋）與 op="<方法> <路徑>"。
• 回應要帶 X-Agent-Fingerprint 且等於該台登記的指紋，不符視為失敗。
• Agent 的 base_url 必須是 https://；未啟用時走裸 http。
• 兩支都不拋例外：連不到（離線、客戶沒開入站埠、Agent 正在重建容器）、回 4xx／5xx、指紋不符一律回 False／None，分批狀態不受影響。

Agent 端守門 guidant_agent/sync/api/data_plane_auth.py:29-31：/update 在 _PROTECTED_PREFIXES，且在 _OP_BOUND_PREFIXES——JWT 的 op 必須等於本次「方法 路徑」，別的用途的 token 不能拿來打這裡。

6.1 POST /update/notify

6.2 GET /update/progress

快取（agent_rollout_service.py:65-67、663-682）：模組層字典 _PROGRESS_CACHE = {agent_uid: (拉到的時間, progress)}。這次拉不到的沿用上次的值；不在下發中的台從快取清掉；心跳收到結果時也清該台（:410）。快取在每個 gunicorn worker 行程各一份，某次刷新落在別的行程只是少看到一次，下一刷就有。

接線 core/plugins/remote_agent.py:331-341：dispatch_gate、update_extra、heartbeat_payload_observers 三個 port 由 jedi-remote-agent 1.11.0（pyproject.toml:75）的 jedi_remote_agent/app/service/heartbeat_upgrade.py 搬運。

7.1 停派新任務（dispatch_gate）

dispatch_gate=lambda: not is_draining()。主機升級第 2 步放 upgrade/draining 旗標時，心跳不派新的檢測任務，待辦留在 pending，旗標拿掉後下一跳照常領。gate 本身出錯當成「不派」（heartbeat_upgrade.py:21-33）。

7.2 下發：回應 data.update

update_heartbeat_extra(agent) → AgentRolloutService.update_for_agent（agent_rollout_service.py:369-386）。

只有全部成立才回物件，否則 update: null（欄位一律帶，Agent 據 null 判「沒有要升」）：這台開著的列是 dispatched、Agent 仍比 target_version 舊、host_version 不比主系統現行版新、找得到包且版號等於 target_version。宿主出錯也回 null、心跳不失敗（heartbeat_upgrade.py:36-49）。

心跳回應沒有下載網址；Agent 固定打 GET /api/1.0/agents/update/bundle。

7.3 下載端點 GET /agents/update/bundle

api/remote_agent/routes/agent_update_bundle_route.py、core/plugins/_agent_update.py:80-121。

7.4 上報：payload upgrade_result

Agent 心跳 payload（guidant_agent/sync/app/enroll.py:193、update_sync.py:289-299）：

同一筆一直重送到有新結果為止。套件以 upgrade_values_from_payload（heartbeat_upgrade.py:52-74）判斷「是不是新的結果」並寫 remote_agents.last_upgrade_version／last_upgrade_status／last_upgrade_at（error 不入那張表）；主系統的 observer record_upgrade_result 用同一支判斷，兩邊判法一致。

🔴 依賴 observer 拿到的 agent 是本次心跳寫入前的值；套件若改成先回填再通知 observer，主系統會把每一筆新結果都當成重送（agent_rollout_service.py:183-199）。

record_result（:394-411）寫回規則：這台開著的列已下發過（dispatched_at 有值）且狀態是 dispatched 或 paused、回報的 version 等於列上的 target_version，才寫 succeeded／failed（failed 帶 error）。暫停中但已下發過的列也收——管理員按暫停時那台可能正在升。下一批的放行留給每分鐘排程。

evidence-agent/guidant_agent/sync/app/update_sync.py，UpdateSync 是一個背景 WorkerComponent，有自己的執行緒。

8.1 目錄（compose 掛載，deploy/docker-compose.yml:236-237）

AGENT_UPGRADE_DIR=/upgrade。主機目錄權限：agent-order/ 1000:1000 750、agent-staging/ 0:0 700（scripts/install/lib/upgrade_order.sh:83-85）。

8.2 心跳 observer（observe，update_sync.py:301-342）

心跳回應進來時只做比對與排工作，不在心跳迴圈裡下載，且不往外拋例外。依序：

1. 有升級單就先判結果；結果還沒隨心跳送出過，這輪不動（先讓主系統收到失敗，免得在空窗馬上重寫單）。成功的話清掉本地包。
2. data.update 不是物件 → 主系統沒要這台升（含 paused），什麼都不做。
3. target_version／bundle_sha256／size 格式不對、或 target_version 已等於自己版號 → 略過。
4. 同一目標、同一 sha 的單已寫好且還在等主機 → 等。
5. 不支援：不是容器（原生安裝）、或 agent-order/ 不存在或不可寫 → 記一筆本機失敗（下次心跳帶上 failed），不默默不理——不回報的話主系統那一批永遠停在下發中。
6. 有工作在執行 → 等它們做完再下載。
7. 同一包失敗後 30 分鐘內不重試（一包 1GB 以上，_RETRY_AFTER_SEC=1800）。
8. 排給自己的執行緒做 sync_once。

8.3 下載、驗、寫單（sync_once，:403-426）

1. 清掉舊單、舊主機結果、別版的包與半成品，只留這版的包與 .part。
2. 已有同大小同 sha 的包就不重下。
3. 磁碟：可用空間 < 剩餘大小＋1GB 就回報失敗（_check_disk）。
4. GET /api/1.0/agents/update/bundle 續傳到 .part；404 視為這台已不在下發批、等下一次心跳；斷線留著半成品下次續。
5. 大小與 sha256 都對才改名；不對刪檔回報「傳輸損毀或遭竄改」。
6. 寫升級單（暫存檔 → chmod 644 → os.replace 進監看的路徑）：

{"job_id": "agent-20261101-123045-a1b2c3", "target_version": "1.4.8",
 "bundle": "guidant-agent-compose-1.4.8.tar.gz", "bundle_sha256": "<64 hex>",
 "size": 1800000000, "from_version": "1.4.7", "created_at": "2026-11-01T04:30:45+00:00"}

8.4 結果判定（_order_outcome，:109-136）

只認 job_id：進度檔可能是別次（手動）升級寫的，版號相同也不能算這張單的結果。

evidence-agent/scripts/install/lib/upgrade_order.sh。單元 guidant-agent-upgrade-order.path（PathChanged=<升級目錄>/agent-order）觸發 guidant-agent-upgrade-order.service → <安裝程式副本> upgrade-host order（入口放在 /usr/local/lib/guidant-agent-upgrade/，不指維運指令——它要到升級第 6 步才換新）。另有 guidant-agent-upgrade-boot-check.service：開機時進度檔還是 running 就先退回（upr_recover）。

🔴 agent-order/ 是容器可寫的，裡面的單與包一律不可信；單上的 sha 也是容器寫的，sha 對了只代表下載沒壞。root 執行新版任何一行之前要先過下面的關（:11-17）。

%%{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'}}}%%
flowchart TD
    A["path 單元觸發"] --> B["複製單到 agent-staging/order.json<br/>≤64KB、不是連結、10 秒逾時"]
    B --> C{"job_id 合法？<br/>處理過？"}
    C -->|否／已處理| Z["結束"]
    C -->|是| D["precheck<br/>格式・版號遞增・升級鎖・執行中工作"]
    D -->|不過| R1["寫 agent-upgrade-host.json<br/>failed／skipped"]
    D -->|過| E["開進度檔、第 0 步 extract"]
    E --> F["stage：mv 包進 staging → 驗 sha<br/>→ 列清單 → 只解三個檔"]
    F --> G["load_and_verify：docker load<br/>→ 擋夾帶 tag → 用**現行**映像驗新映像<br/>→ 版號相符 → install.sh／compose 逐位元組相同"]
    F -->|不過| R2["進度檔 failed＋host 結果檔"]
    G -->|不過| R2
    G -->|過| H["第 0 步 ok → runner 第 1～6 步"]

9.1 precheck（_uo_precheck，:217-234）

不碰包就能判的；不過時印 <failed|skipped>:<說明>：

job_id 要符合 ^agent-[0-9]{8}-[0-9]{6}-[0-9a-f]{6}$；處理過的單（agent-staging/last-job 或進度檔 job_id 相同）不再跑——否則之後手動升級蓋掉進度檔時，舊單被碰一下就會把版本降回去。

9.2 stage（_uo_stage_bundle，:243-261）

1. mv 包進 agent-staging/bundle.tar.gz（換目錄項，不跟連結、不讀 FIFO），必須是一般檔。
2. sha256sum 等於單上的 sha。
3. 安全清單（_uo_safe_listing）：只收一般檔與目錄、全在 guidant-agent-compose-<版>/ 底下、沒有 ..、解開總量 ≤ 壓縮檔 3 倍＋1GB。
4. 只解三個檔：install.sh、docker-compose.yml、guidant-ai-agent-<版>.image.tar。
5. 出貨清單重寫成只有 agent 映像一行：SeaweedFS 不從自動升級載（不許蓋掉現行那顆）。

9.3 load_and_verify（_uo_load_and_verify，:296-319）

1. 記下現行 AGENT_IMAGE 的映像 ID（找不到就無法驗新版）。
2. docker load；載入後凡是「載入前就有、ID 卻變了」的 tag 一律指回載入前的 ID，多出來的刪掉，然後拒收——映像 tar 可以夾帶任意 tag，檢查時 tag 已經被蓋掉了，只看載入輸出不夠。
3. docker create --network none 新映像，把 /opt/guidant-agent/current/agent 程式樹複製出來。
4. 用現行（信任的）映像的執行檔跑 evidence-agent verify-tree 驗新樹的簽章與逐檔雜湊；新版的程式碼在這之前一行都沒執行。驗不過提示「現行版本若太舊不支援自動跟進，請手動升級一次」。
5. 簽章內版號＝單上版號。
6. 包內 install.sh、docker-compose.yml 與簽章樹內那份逐位元組相同。

9.4 交給 runner

UPG_JOB_ID=<單的 job_id> UPG_TRIGGER_KIND=order UPG_TRIGGER_USER=agent UPG_TRIGGER_MODE=now <維運指令> upgrade <staging>/pkg/guidant-agent-compose-<版>。runner 認得同 job_id 的進度檔是升級單開的，沿用第 0 步。

runner 開跑前就停下（只到第 0 步）由升級單補寫：退出碼是「這次不升」→ 進度檔與 host 結果檔寫 skipped；其他 → failed「升級沒有開始（退出碼 N），過程紀錄在 /var/log/guidant-ai-agent/」。

host 結果檔 agent-upgrade-host.json：{job_id, status: failed|skipped, at, error}，先寫在 staging 再 mv 過去。

report_agent_results（core/plugins/_agent_update.py:58-77）＋report_finished（agent_rollout_service.py:415-443），每分鐘排程在系統身分下跑。

src/views/product-update/AgentRolloutPanel.vue、agentRolloutState.js、src/composables/useAgentRollout.js。

每台展開 8 格（AGENT_STEPS，agentRolloutState.js:63-66）：

succeeded 八格全打勾；failed 時最後一個有狀態的格標失敗並帶 rollout.error（Agent 的 steps 沒有 detail，失敗原因只有心跳回報的那句）。結果一進來主系統就清掉進度快取，所以 failed 常常沒有 progress。

• 設計文件：定案與取捨（與本文件不一致時以程式碼與本文件為準）
• 更新中心 API 規格
• 主機升級指令規格
• 原廠更新站規格
• 發布與簽章規格
• 狀態機
• 時序圖