FR-171 交接現況(STATE)

這份是 living 檔:每棒就地 Edit,只描述「此刻」。歷史脈絡看同資料夾的 FR-171-LOG.md。

項目 值
最後更新 2026-11-01(第 1 棒,首腦,討論稿 v1 交出、等決策者裁 D1~D12)
branch BE feature/FR-139;Agent/jedi 主線(本棒未動)
母案卡 未開(討論階段不開卡)
本棒角色 首腦(分析決策人員),走 big-feature-workflow,不開 subagent
階段 Step 2 討論稿已交,未拍板;design.md 未寫、Notion 未開卡
接手前必讀 §0 讀序

🧭 原始需求 / WHY

這節寫一次,之後各棒不動。

決策者原話(2026-10-31):

之前都是只能等心跳由 agent 發訊息給本體,後來才有了臨時 token 的模式讓本體可以主動跟 agent 溝通,所以現在應該算是可以雙向溝通?我想要把等待心跳的功能都改掉,除了原本的心跳功能,因為我覺得這太偷懶了而且越塞越多,不可能都只依靠心跳來處理事情。

討論中追加的三個要求(2026-10-31):

  1. 「反正都要重構了,我希望是好的設計,而不是像之前一樣都沒想過硬塞。」
  2. 「mTLS 10 年過了要怎麼更新?客戶是沒有 IT 的一般人,叫他打指令是要他的命;原廠出差到冰島、俄羅斯怎麼處理。」→ 換證要全自動。
  3. 「很多機制沒錯,但都做一半或是沒有統一。要嘛就是機制統一幾個,不然兩個月後沒人記得,除錯要花兩三天。」→ 不只做指令直推,連守門、client、簽章規則一起收斂。
  4. 「要真的分析過,不合理要反駁我,我會自己判斷。」→ 首腦據此撤回兩項自己先前的說法(見 §2)。

2026-11-01 另一 session 的決策者裁示(memory feedback_no_heartbeat_piggyback_messaging):「之後不要再用心跳帶訊息了,這機制真的雷到一個不行。」心跳只表存活;Agent→主系統的結果/進度走專用端點當下送、送不到進 outbox;主系統→Agent 走資料面。這條比討論稿 v1 更激進(v1 的主題 B 仍讓心跳帶設定同步,只是加版本號),接手首腦要把這條併進去重審主題 B,見 §3。

目標長什麼樣:一條指令通道(主系統→Agent 8443,派工/重啟/升級/換證/取消,打不通退回主系統 DB 的單子由心跳或下次直推補);心跳只表存活(設定同步改專用端點或帶版本號,依 11-01 裁示重審);兩個方向同一套「60 秒、綁方法路徑、綁 jti、自己私鑰簽」的簽章規則;憑證一年自動換、CA 與簽章公鑰走信任錨清單可輪換;主系統四份 client 收一份、Agent 守門一條規則。

本棒在大圖的位置:第 1 棒,探脈+討論稿 v1。前作 FR-170 第 4 棒「P4 分析」是起點,FR-170 P0~P3 已於 10-31 合回主線。

§0 接手讀序

0.1 🔒 先懂需求 gate

  1. 本檔 🧭 WHY 節
  2. docs/features/FR-171-2610-agent-command-channel/discussion.md 全讀(或開 discussion.html)——§2 現況地圖、§4 九個洞、§5 六主題、§7 D1~D12
  3. memory feedback_no_heartbeat_piggyback_messaging(docs/claude/memory/)——11-01 裁示,討論稿 v1 寫在它之前

0.2 現況與待辦

  1. 本檔 §2 已定裁示、§3 下一步
  2. FR-171-LOG.md 第 1 棒 block

0.3 需要細節才開

  • FR-170 LOG 第 4 棒「P4 分析」段、FR-170 design §3.x
  • Agent:guidant_agent/sync/api/data_plane_auth.py、sync/app/enroll.py、sync/adapters/cert_files.py(prior_key_proof)、sync/domain/agent_auth.py
  • jedi-remote-agent(.venv/lib/python3.11/site-packages/jedi_remote_agent/):common/agent_auth/jwt_util.py、possession.py、app/service/agent_enrollment_service.py、agent_enroll_token_service.py
  • 主系統:infra/remote_agent/agent_credential_client.py、agent_update_notify_client.py、core/plugins/remote_agent.py(build_adapters)

0.4 ✅ 冷接自檢

  1. 現在主系統與 Agent 有哪四條路?每條怎麼證明身分?(答不出來回去讀 discussion §2)
  2. 九個洞哪一個是「真正的洞」、哪些只是縱深不足?(§4)
  3. 為什麼心跳改持有證明選 DPoP 式而不是 mTLS?(§5.6)
  4. 為什麼撤回「CA 縮到 3 年」?(§7 D5)
  5. 11-01 的「心跳不帶訊息」裁示跟討論稿主題 B 哪裡衝突?

§1 當前狀態

項目 狀態
登記 docs/features/README.md FR-171 列已加(commit 03feb84ae)
討論稿 discussion.md v1,6 張 mermaid、D1~D12;已 build 站;未經決策者拍板
design.md 未寫
Notion 未開母卡與子卡
雛形 未畫(D11 建議不畫整頁,管理頁多一欄即可)
程式 本棒零改動
Agent 主線 3ab1253(FR-170 合回);1.4.8 已於 11-01 推 189(另一 session)

§2 已定裁示(不要重新討論)

裁示 何時 誰
WebSocket/長連線不做;SaaS 不開 8443 時才再議 2026-10-29 FR-170 §3.x;10-31 本案前置重申 決策者
心跳不再帶訊息(指令、結果、進度、清單);心跳只表存活;事件走專用端點 2026-11-01 決策者(另一 session)
換證必須全自動,客戶與原廠零人工 2026-10-31 決策者
機制要統一,不接受做一半 2026-10-31 決策者
「三種票共用一把私鑰是洞」撤回:RFC 8725 現況合規,分鑰是縱深(D10 仍建議順手做) 2026-10-31 首腦自撤
「CA 縮到 3 年定期換」撤回:NIST 要求能換不是排程換 2026-10-31 首腦自撤
私鑰永遠在 Agent 產生、不經網路;主系統「發動換證」只能是叫 Agent 自己換 2026-10-31 首腦提、決策者未反對

§3 下一步

🔴 下一個動作:接手首腦等決策者裁 D1~D12。裁之前先做一件事:把 11-01「心跳不帶訊息」裁示對照討論稿主題 B 重審。v1 主題 B 是「心跳帶 config_versions、主系統只回有變的」,仍是心跳帶設定;11-01 裁示下應改成「主系統設定有變→直推 POST /config 通知(或走指令通道);Agent 啟動與重連時主動 GET /agents/config?versions=… 拉」。改完出 v2 再請決策者裁。

決策者 10-31 討論中提出、v1 尚未落地的修正(接手要併進 v2):

  • D9 要擴大:註冊 token 改成「多把並存、每把有標籤/到期日/可用次數(預設 1)、撤銷針對單把」(Kubernetes bootstrap token 做法)。決策者的疑問「重新產生跟撤銷差在哪」查證結果:現況 token 一租戶一組永久有效、產生=換掉舊的、撤銷=關掉註冊不產新的,兩者對舊 token 動作相同;名字騙人。約兩張卡(表加三欄、兩支 API、FE token 頁)。
  • 已註冊的 Agent 不受 token 產生/撤銷影響(已向決策者確認);要讓一台斷線是在 Agent 管理頁撤銷那一台。

之後順序:拍板 → design.md(含 handoff/cards.py 驗批)→ Notion 母卡+子卡(四欄齊全)→ 停,工作坊派。釘版套件(jedi-agent-protocol、jedi-remote-agent)有改動,批 1 前要開環境卡。

⚠️ 這節是建議清單,不是執行授權。接手方讀完盤點完即停,等決策者發令。

§4 待辦與風險

  • 推測,待 verify:主系統四份 client 簽 JWT 前都沒查 remote_agents.status。grep 過 cancel client 與 credential client 確實沒看到;remote_agent_adapter.py 與 probe client 沒細讀。verify:grep -n "status\|enabled\|assert_agent_can_call" infra/upload_file/remote_agent_adapter.py .venv/lib/python3.11/site-packages/jedi_detection/infra/detection_tools/connector/agent_probe_client.py。
  • 已查證:proves_prior_key 不看舊證到期日(只驗 CA 簽發、CN、簽章),所以過期後仍可換證,寬限在程式層已成立。
  • 已查證:取消掃描已經是直推(agent_cancel_client 打 /detection/cancel),不在心跳。
  • mermaid 六張圖只靜態檢查(首行 init、語法形狀),未開瀏覽器看渲染(規範不開瀏覽器)。決策者若回報某張糊掉,看 discussion.md 對應 sequenceDiagram 的 Note 內有無特殊字元。
  • CA 憑證本身效期:installer openssl -days 3650,已確認 10 年。

§5 Pre-flight(唯讀)

cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
git status --short | grep -v "^??" ; git log --oneline -3
ls docs/features/FR-171-2610-agent-command-channel/
grep -n "FR-171" docs/features/README.md | cut -c1-60
cat docs/claude/memory/feedback_no_heartbeat_piggyback_messaging.md | head -5
git -C ~/Projects/Billows/Audit-Manager/evidence-agent log --oneline -1

§6 環境座標

  • 本機 Agent:~/guidant-agent-local/start-agent.sh(venv evidence-agent-knWYPLiu-py3.13)連 DEV BE 8000。
  • 不碰 STG/POC。189 POC 的 Agent 11-01 由另一 session 推 1.4.8,本案與它無關。
  • 已裝套件版本:jedi-remote-agent 1.11.0、jedi-agent-protocol 0.1.0(主系統 .venv/lib/python3.11/site-packages/)。

§7 行為規範提醒

  • 首腦不開 subagent(決策者 10-16 改判);探脈自己 grep。
  • 討論稿拍板前不寫 design、不開卡;開卡照 notion-card-templates,一張卡一個 repo,登記型檔不同批。
  • 回報一律白話、繁中;問裁決用「問題→建議→理由」。
  • 決策者要求「不合理要反駁」——提方案要附規範依據(RFC/NIST/業界實作),不順著他講。