FR-056 檢測工具整合平台 — 主導 session 中繼交接(orchestrator handoff)

要解決什麼:客戶目前「用檢測工具掃描 → 匯出報告 → 手動上傳當任務證據 → 手動完成任務」全程手工。FR-056 要把這條線自動化:

1. 租戶自助設定檢測工具(首接 OpenVAS,之後 Nessus/SonarQube)——工具目錄 DB 驅動(取代 FE 寫死的 prototype 頁 plugin/tool-plugin-manage),租戶填連線資訊+憑證(Fernet 加密落庫)
2. 任務可設為「檢測工具執行」類型+掃描參數(BPMN userTask 同步)
3. 按「開始執行」→ 客戶端 Agent 觸發掃描——複用 FR-039 evidence-agent(mTLS+JWT 認證鏈已完備),派工走「心跳夾帶待辦」模式
4. 報告自動回收成任務證據(source=DETECTION_TOOL,沿用 DRIVE_SYNC handler 模板)→ 發信通知 → 依 completion_mode flag 決定自動完成或留給人工

完成模式(易誤解,必懂):completion_mode 只是「掃完要不要自動按完成鍵」的 flag,不是新狀態。auto=系統自動呼叫既有 complete_job;manual=系統不做事,任務留 PROCESSING,人工判斷證據後手動完成。零新增 JobStatus、不動 jedi_flow_engine(原「待覆核新狀態」方案已作廢,文件裡看到「待覆核」字樣的都是歷史注記)。

關鍵決策 D1–D11 全在 design.md §3。最常用到的:D9 憑證下發=雲端解密隨派工下發(mTLS,Agent 用完即丟不落地)/ D10 OpenVAS 走 API(python-gvm)非 CLI / D11 證據用既有 FILE 型別非新 REPORT 型別。

開發模式(本 FR 的實驗重點):主導 session 出計畫 → user 開 runner session(Sonnet 5)照 implementation-plan 實作 → 主導 session 派獨立 subagent 驗收(不信 runner 自報)→ Notion 三層全程留痕。user 正在觀察這套模式的效率,執行時間紀錄(見下)就是為此收集的數據。

🔒 先懂需求 gate(讀完才准動作):

1. 本文件 🧭 節(上方)全讀
2. docs/features/FR-056-2607-detection-tool-integration/design.md — §3 決策表 D1–D11 全讀 + §5 資料模型掃過
3. memory project_fr056_detection_tool_integration.md(session 啟動時已載入索引,開檔全讀)

然後: 4. Notion 母案 CM-907(page_id 3a9346da-4cd0-81a5-be6f-f0ddd6d770c6)——含「工作慣例補充」(執行時間回報格式) 5. 各 implementation-plan 按需讀(驗收哪個 phase 才讀哪份,別全讀,很大):implementation-plan.md(.1)/ -phase2.md / -phase3.md / -phase4.md

冷接自檢 4 問(答不出回去讀,別動工):

• FR-056 最終要讓使用者少做哪些手工?
• completion_mode=manual 時,任務狀態是什麼?系統做什麼?
• 你這一棒的角色是什麼?(提示:不是寫 code)
• 56.2 和 56.3 為什麼可以平行?它們共同依賴誰?

1.1 Notion 三層狀態

子需求卡 page_id:.1=3a9346da-4cd0-810c-9544-c237066d39d4 / .2=3a9346da-4cd0-8182-8451-f473f1bde2d5 / .3=3a9346da-4cd0-811d-8d54-cbf81686b661 / .4=3a9346da-4cd0-81c2-aae3-d8d6af1f8689。任務清單 data source:collection://23c346da-4cd0-8041-955e-000bb6976dd2。

1.2 56.1 驗收結論(已完成,勿重跑)

獨立 Sonnet subagent 對照專案鐵則 17 項檢查:16 ✅ + 1 N/A,零缺失放行。涵蓋 migration 鐵則(含 DEV DB 活庫實查:三表存在、openvas seed 有進、schema_migrations 有登記)、DDD/session、幽靈 WHERE/覆寫、憑證安全(response 只回 has_credentials,金鑰只在 env)、error code、pytest 11/11 實跑通過。全文回寫在 CM-908 卡內。

runner 加分:T-1.4 自行發現 test_connection 沒把 field_values(base_url)合併餵給 probe 的 bug,獨立 commit b26f83f1 修正+補測。

1.3 執行中的 runner(user 另開的 session,非本 session 的 subagent)

• 56.2 runner(Sonnet 5):T-2.1 GrcJobType+BPMN 同步 / T-2.2 綁定表+參數+completion_mode / T-2.3 FE 任務設置頁。
• 56.3 runner(Sonnet 5):T-3.1 agent_tasks 表 / T-3.2 心跳夾帶+ack+結果回收 / T-3.3 executor 骨架(evidence-agent repo)/ T-3.4 OpenVAS connector(python-gvm,無實體 OpenVAS 可 mock 驗收但須註明)。
• 兩者 prompt 已內建:Notion 回填鐵則(每張 case 開工 In progress / 完成「修正待驗證」+ 內文回寫做了什麼/偏差/驗收結果 + 執行紀錄段(開始/結束/耗時/卡點))、測試策略(範本手測、陷阱 pytest、phase 收尾整合驗)、git 紀律(顯式 add 逐檔、共用檔防撞:動 config/app_modules.py、common enums 前先 git status 查對方未 commit 變更,有就停下回報)、嚴禁 push/切 branch。

1. 驗收 subagent 會 context 自爆:第一次派驗收員沒限制讀量,它去整讀 plan/HTML 爆掉被終止。重派時必帶讀檔紀律:嚴禁讀 .html/.md 文件/mermaid.min.js,git show 只 --stat,grep 定位再小段 Read(≤120 行),Bash 輸出 head/tail 截斷。
2. 計畫會有遺漏,runner 發現是預期行為:56.1 期間 runner 發現缺「GET /detection-tools/configs 清單 endpoint」,停下回報 → 主導 session 決策(選補 endpoint)→ 回寫 plan/design/Notion → runner 續作。這個 loop 是健康的,遇到同類回報照此處理:決策給 user 選或自己判,四處回寫,再放行。
3. user 語言要求:繁體中文,絕不可出現簡體字。
4. 執行類工作發 subagent(Sonnet),不留主 session 做——省 Fable 額度,主 session 只派工+輕量抽查。

3a. runner 卡點支援(隨時)

user 貼 runner 的卡點訊息過來 → 判斷:plan 遺漏/矛盾 → 決策 + 回寫四處(plan md / plan-N.html 重轉 / design.md 若涉決策 / Notion 對應卡)→ 給 user 回覆 runner 的指示。plan→HTML 轉換腳本:scratchpad 的 render_plans.py(若 scratchpad 已清,重寫一個或直接只改 md、HTML 待收尾統一重轉)。

3b. 56.2 或 56.3 完成回報 → 驗收(主要工作)

照 56.1 驗收模式,派 Sonnet subagent(帶讀檔紀律) 獨立查證。56.1 的驗收 prompt 骨架可複用,按 phase 特性調整重點:

• 56.2 重點:GrcJobType 枚舉加值後全 call site 掃過(memory: 改 signature 後 grep 全 call site)/ BPMN userTask 同步線(_sync_task_to_template_xml(),actionType/actionInfo/camunda:property)/ 綁定表 migration 鐵則 / completion_mode 只是欄位不是狀態(確認沒人動 JobStatus/jedi_flow_engine)/ FE 任務設置頁 error-code i18n 同步
• 56.3 重點:agent_tasks 狀態機轉移邏輯 pytest / agent 路由走 mTLS 不掛 @jwt_required(這是設計,別當缺失)/ D9 憑證解密只在派工下發瞬間、不落地不進 log / evidence-agent repo 的 commit 分開驗 / T-3.4 若 mock 驗收,確認卡內文有註明「未對真實 OpenVAS 驗證」
• 驗收過 → 子需求卡標「修正待驗證」+ 回寫驗收報告(照 CM-908 格式);驗收出問題 → 返工清單給 user 轉 runner

3c. 56.2+56.3 都放行後 → 派 56.4

56.4 依賴 .2+.3 的產出。給 user 一份 56.4 runner prompt(Sonnet 5),骨架照 56.2/56.3 版(先讀清單 / case 清單:T-4.1 CM-924 3a9346da-4cd0-815c-b282-c50d5b9d9c3d、T-4.2 CM-925 3a9346da-4cd0-815c-be82-eb593a766505、T-4.3 CM-926 3a9346da-4cd0-8195-b39c-e58639d5a383 / Notion 回填鐵則含執行紀錄 / 測試策略 / git 紀律,此時無平行防撞需求)。plan 是 implementation-plan-phase4.md。56.4 重點提醒:D11 證據用 FILE 型別、completion_mode 分岔(auto→complete_job / manual→不動)、通知沿用既有信件機制。

3d. 全部放行後 → 總收尾(等 user 下令)

收尾動作(spec / SUMMARY / 母案收口 / memory / 執行時間彙整分析)一律等 user 明確下令。屆時可做:各 case 執行紀錄彙整成本分析(user 想看的數據)、writing-feature-specs 更新頁面 spec、母案 CM-907 收口。

cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
git branch --show-current   # 應為 feature/scan-plugin-integration;不對就停下問 user
git log --oneline -12       # 對照 §11;之後會多出 runner 的 fr056 phase2/3 commits(正常)
git status --short          # untracked docs/交付文件等雜項是既有狀態,非本 arc 產物
cd ~/Projects/Billows/Audit-Manager/compliance-manager-fe && git log --oneline -5

Notion 現況:用任務清單 data source SQL 查 需求編號 LIKE 'FR-056%' 看全部 case 最新狀態(runner 可能已推進)。

• 不切 branch / 不 push(等 user 明示)/ 收尾等 user 下令
• 派 subagent 一律 Sonnet(或 Haiku),不留 Fable 執行;驗收 subagent 必帶讀檔紀律(§2-1)
• 繁體中文
• Notion 先搜尋再開卡,別開重複;Claude 做的作業人員填「小弟」
• runner 回報的「plan 遺漏」是預期 loop,照 §2-2 處理
• BE 改 service 要重啟才生效(runner 自己會做,但驗收若要手測記得確認 listener)

• Nessus / SonarQube connector(只做 OpenVAS)
• 證據型別 REPORT(D11 已排除,用 FILE)
• jedi_flow_engine / JobStatus 任何改動
• FE prototype 頁面以外的 FE 重構
• 執行時間彙整分析(等全部完成、user 下令收尾才做)

BE(feature/scan-plugin-integration,部分已 push、後段未 push,以 origin 對照為準):

b26f83f1 fix(fr056): test_connection must merge field_values with decrypted credentials (T-1.4)
9a22142f feat(fr056): add missing GET list tenant configs endpoint (T-1.3 follow-up)
e49c0eb0 docs(FR-056): 補 GET /detection-tools/configs 清單 endpoint(計畫遺漏)
07d21822 docs(FR-056): 討論稿同步最新決策——完成模式改 manual/auto flag + 補 D9–D11
2258e143 feat(fr056): connection test + referencing-task count stub (T-1.4)
447c5720 docs(FR-056): 討論稿內嵌 mermaid.js 供本地離線渲染流程圖
a57af11b feat(fr056): tenant detection tool config CRUD + credential encryption (T-1.3)
097e0160 feat(fr056): detection_tools catalog read-only API (T-1.2)
77f6d4e4 feat(fr056): add config schema + detection tool tables (T-1.1)
88e79baf docs(FR-056): D9–D11 決策定案(憑證下發/OpenVAS API/證據型別)
661fb0e2 docs(FR-056): 檢測工具整合平台設計 + 四階段實作計畫

FE:

06c1fb5 fix(fr056): sync DetectionToolsErrorCode to FE zh-tw/en error-code.json
0d18938 feat(fr056): rebuild detection tool management page with real API (T-1.5)

請讀 docs/features/FR-056-2607-detection-tool-integration/handoff/2026-07-26-orchestrator-mid-arc-handoff.md 接手 FR-056 主導 session。
先過「🧭 原始需求」+ 冷接自檢 4 問,再跑 §6 pre-flight。
你的角色是派工+驗收,不自己實作。56.2/56.3 runner 正在跑,等我回報後照 §3b 驗收。