FR-170 Agent 架構重整

狀態：P0～P3 完成，已合回三 repo feature/FR-139（Agent 3ab1253、jedi fc67330e、主系統 18642c6cf）｜日期：2026-10-29～10-31｜母卡 P0 CM-3232（17 張）、P1～P3 CM-3324（16 張）｜取捨全文 docs/analysis/2026-10-29-agent-architecture-direction.md｜架構圖 architecture.html 開發 branch：Agent 與 jedi-python-package 2026-10-29 皆在 feature/FR-139；runner 開工 git branch --show-current 再確認，不對就停下問，不切。

Agent 要有自己的架構與守衛：模組在外、層在內，五個業務模組彼此只走 port，共用的只有不碰 DB 的 kernel 庫與通訊契約。

guidant_agent/
  platform/    宿主殼：啟動、DI 根、SQLite、migration 串接、背景元件 start/stop、完整性閘、錯誤回報
  identity/    本機帳號、離線操作者、LDAP、主控台 session
  sync/        註冊、心跳、outbox、profile、漏洞庫同步
  scan/        任務執行、connectors、工具帳密
  netdiag/     網路診斷
  files/       證據檔：blob API、儲存設定、完整性、瀏覽器直傳
  console/     主控台 API 聚合層，不碰 DB
  shared/      事件碼、錯誤碼、時間、路徑、archive_safety（零相依）

  每個業務模組內部：domain/ app/ ports/ adapters/ api/ migrations.py

依賴方向：console → 業務模組 → platform → shared，箭頭只能往右。五個業務模組彼此不直接 import，要跨模組走 platform 註冊的 port。模組內 domain 零 import SQLAlchemy／Flask／requests；SQL 字串只准在 adapters/；模組層級不准有可變全域。

3.x 溝通模式：先維持心跳輪詢，第二期改 WebSocket 出站推送（決策者 2026-10-29）

主系統與 Agent 之間有兩條路：Agent 出站的心跳（每 60 秒，拉派工單與各種同步狀態），以及主系統連進 Agent 資料面 8443 的直推（mTLS＋綁定 agent 身分的短效 JWT，測試連線、取證據檔、設定／清除工具帳密都走它，當場回結果）。落地版主系統與 Agent 同在客戶內網，直推一定通；SaaS 版主系統在雲端，要客戶開放 8443 進來才通，這是直推的唯一前提。心跳仍把狀態全量重送（實測 123 一跳：請求 5 KB，其中 profiles 3.3 KB、configured_tools 1 KB，沒變也送；回應 3 KB）。決策者方向：狀態類改帶版本號有變才送；SaaS 不想要求客戶開 8443 時，才需要 Agent 出站建 WebSocket 常駐連線讓主系統往下推。本案 P0 不含；開卡時沿用 BE 既有 SocketIO 8002。

批＝可同時派的一組；一批一到兩張是刻意的，同批的卡不能改同一個檔。登記型檔只讓一張卡碰：Agent pyproject.toml（1-3、3-2 不同批）、core/local_db/migrations.py（1-2）、jedi-common pyproject.toml（1-1、3-1 不同批）、jedi-iam pyproject.toml（1-4、3-1 不同批）。guidant_agent/platform/bootstrap.py 由 2-2 建、2-3 與 2-4 各改一次，故三張各自一批。

前置已成立：FR-166.1（CM-3199）、FR-169（CM-3223）2026-10-29 皆 Done。本案期間 Agent repo 不開功能卡；FR-167 的 Agent 側兩張（P4-5、P4-3）會改 core/enroll.py，不與本案批 5 同時派。主系統改釘 jedi-common 1.3.7／jedi-iam 1.11.0 不在本案，P0 驗收後另開主 repo 卡。

無人值守原則：單卡不得停下等人——不 sudo、不拔網路、不開瀏覽器、不等人確認發版；遇到要人決定的事（版號撞號、前置產物不在、測試紅找不到原因）commit 已完成部分、回寫問題→建議→理由、狀態留 In progress。真機情境（拔網路、真 188 Agent 升級）留測試期由首腦操作。

5.1 P1（搬 identity、sync）——五張卡四批，批 12 起，建卡不放行（決策者 2026-10-30）

P1 母卡 CM-3324（獨立於 P0 母卡 CM-3232：P0 工作坊結案要求子卡全 Done，P1 掛同一張會擋結案）。要跑 P1 時新開工作坊選 CM-3324。

前提：發版與線上更新用 P0 版；P0 若要修先合主線再放行批 12。搬前先剪三條線：audit() 與 LOCAL_ADMIN_SUB 搬 shared（1-1）；對主系統的 HTTP 通道從 task_executor 抽成 sync 的 adapter、心跳 observer 改走 registry 掛點（1-3，P1 最危險的一張）。identity 這次順便改接 jedi-password，舊雜湊必須仍可登入、驗過即 rehash。identity↔︎sync 四條互依邊在 1-4 用 port 與 platform/health.py 解。殼只在 1-5 刪零命中的，其餘 P2。

拆卡底表 handoff/cards_p1.py；三條線的分析依據（AST 掃出的跨模組邊、各邊實際用到的符號）在 handoff/FR-170-LOG.md 第 4 棒。

5.2 P2（搬 scan、netdiag、files；console 退聚合；刪舊 core/）——批 16～19（含首腦加開的 P2-6 CM-3345）

AST 掃出的事實：scan → sync 13 條邊全是 allowed_targets／tool_schemas／outbox／heartbeat_status 四個 → 抽 TargetAuthorizer／ToolSchemaCatalog／ResultOutbox 三個 port 由 sync 註冊（P2-1）；scan → console 7 條全是重啟旗標（歸 platform）與表單驗證（歸 scan）；console 的 84 條出邊是退聚合不是剪線（只准 import 對方 app/ 與 ports/）。agent.db 建表步驟從 legacy 一張清單拆回各模組 migrations.py 申報，版本號不變、攤平順序用測試鎖死。Fernet 加密保管下沉 platform/secret_store.py（D4 落實）。sonarqube.py、inspec.py 超標只搬不拆。無人值守：真機出包與主系統派工留測試期首腦做。

5.3 P3（抽 jedi-agent-protocol）——批 20～22；收口清理 P3-5 CM-3357 批 23

三邊鏡像現況：主系統 common/enum/event_code.py 52 個 AGENT_*、jedi-remote-agent/common/code.py 44 個、Agent event_codes.py 40 個；心跳請求 7 鍵、回應 24 鍵散在各 observer 的 data.get。P3 收成零相依 kernel 套件（事件碼、錯誤碼元組、HeartbeatRequest／HeartbeatResponse TypedDict、派工單鍵），三邊 import；數值與鍵名一字不變，三邊既有不一致只列不修。套件卡只發 beta，結案卡轉正式；主系統改釘與 event_code.py 改 import 是 P3 後另開的主 repo 卡。

拆卡底表 handoff/cards_p2.py、handoff/cards_p3.py。三期母卡各自獨立（CM-3324 → CM-3325 → CM-3331）：工作坊結案要求子卡全 Done，掛同一張會擋前一期結案。

1. Agent venv pip show jedi-common 為 1.3.7（3-2 後不帶 b），pip show psycopg 不存在（Agent 不裝 Postgres 驅動）；Nexus 上三支正式版存在。
2. 188 那台 Agent 的 agent.db 複本（WAL 模式，用 .backup 抓），跑 local_db.upgrade 到 v7 後 upload_files 每列 tenant_id 非 NULL；請求內與背景執行緒內上傳各一檔成功。
3. pytest test/ 全綠含六支守衛；故意在 guidant_agent/identity/domain/ 加一行 import sqlalchemy 守衛紅。
4. python main_app.py 起得來，log 第一行顯示「Guidant AI Agent app ready」；改 product.display_name 後重啟字串跟著變。
5. core/app_factory.py 行數 ≤ 30；guidant_agent/platform/ 存在且 di_containers/containers.py 內容搬入根容器。
6. 心跳、outbox、profile_sync、vulndb_sync 四支在 platform 的元件清單裡，stop() 後 thread 數歸零；SIGTERM 子行程 5 秒內結束（測試斷言）。測試期首腦在 DEV Agent 真機拔網路一次。

• tenant_id 回填：v7 對既有列給常數預設，已部署機的 agent.db 都要走一次；排練用 188 真實複本，不用空庫。
• 系統身分只設一次是假的：ContextVar 每請求每執行緒各一份；python -c 單執行緒測會過、真 app 上傳照樣撞 NOT NULL。1-2 驗收要求請求內與新 thread 內都斷言。
• beta 版號：PEP 440 1.3.7b1 排在 1.3.7 之前，pin 要寫完整版號不用範圍；jedi-iam 相依 jedi-password 的下限要含 b1 才解得到。
• psycopg 選配動到主系統同一支套件：主系統自己列了 psycopg 兩行，純版對它零影響；套件清單在結案批由決策者按下即確認。
• 背景元件改協定會動到心跳迴圈：2-3 是本案最容易弄壞線上行為的一張，驗收要拔網路、斷主系統、重啟三種情境各跑一次。
• jedi-common 1.3.x 若有未包在 dialect 判斷的 Postgres 寫法：探路 1,655 測試全綠已排除大部分；1-3 若撞到，回寫卡在哪、不自己繞。

本文件描述 P0～P3 的定案與拆法，四期已全部完成。終局結構以 Agent repo docs/ARCHITECTURE.md 為準（守衛測試即憲章的機器可讀版）；取捨理由、被排除的方向、反悔條件在 docs/analysis/2026-10-29-agent-architecture-direction.md，無人值守派工與合回主線的教訓在 docs/analysis/2026-10-31-fr170-unattended-workshop-and-merge-lessons.md。下一期 P4（心跳瘦身、指令類改直推 8443）決策者裁暫緩，分析在 handoff/FR-170-LOG.md 第 4 棒。