awoooi/docs/ARCHITECTURE_MEMORY.md

AWOOOI 架構記憶地圖 (Architecture Memory)

AI 模組地圖索引 - 每次新增積木後必須登記

最後更新: 2026-06-18 (IwoooS AI 自動化產品契約) 維護者: AWOOOI 工程團隊

---

產品定位記憶 (2026-06-18)

AWOOOI / AwoooP / IwoooS 是 AI 自動化產品，不是單純的監控頁、告警轉發器、資安清冊或文件集合。任何告警、資安事件、主機訊號、CI/CD 訊號、Wazuh / Kali / SOC 證據、Nginx / gateway / runtime config drift、code review 候選與人工批准，都必須回到可驗證的 AI 自動化閉環。

合格閉環必須能回答：

1. Sensor / Evidence：訊號來源與只讀證據在哪裡。
2. Normalizer：原始訊號如何被轉成可判讀事件包。
3. AI 分流：由哪個 AI lane / 規則 / agent 判讀。
4. 候選：產生哪些修復、隔離、回復、文件或人工送審候選。
5. 閘門：需要哪些 owner / reviewer / maintenance window / rollback / secret boundary。
6. 執行邊界：哪些行為仍是 0 / false，不得被 UI 可見或 CD 成功誤判成授權。
7. 驗證器：完成後用什麼 readback、smoke、metric、receipt 或 timeline 驗證。
8. 學習回寫：如何回寫 KM、PlayBook、LOGBOOK、候選規則與前台狀態。

若一個工作項目無法回答 AI 判讀到哪、候選是什麼、閘門是否滿足、驗證器是否完成、學習是否回寫，就不得宣稱 AI 自動化完成，也不得上修 IwoooS headline 完成度。前台只能呈現脫敏後的產品資訊與證據摘要，不得顯示工作視窗對話、內部協作內容、個人 namespace、內網位址、secret 片段或 raw process dump。

---

📦 Python 積木 (packages/)

積木名稱	職責	對外介面	狀態	ADR
lewooogo-brain	Brain 積木 - AI 決策與提案引擎	IProposalEngine, IIncidentProcessor, Guardrails	✅ 已完成	ADR-008
lewooogo-data	Data 積木 - 雙層記憶體 (Working + Episodic)	IMemoryProvider, IDualMemoryProvider	✅ 已完成	ADR-008

lewooogo-brain 模組結構

packages/lewooogo-brain/
├── src/lewooogo_brain/
│   ├── interfaces/           # ABC 定義
│   │   ├── proposal_engine.py    → IProposalEngine
│   │   └── incident_processor.py → IIncidentProcessor
│   ├── engines/              # 推論引擎實作
│   │   ├── proposal_engine.py    # ✅ ProposalEngine 已完成
│   │   └── incident_engine.py    # ✅ IncidentEngine 已完成
│   ├── guardrails/           # 安全護欄
│   │   └── guardrails.py         # ✅ Guardrails 已完成
│   └── skills/               # Skill 動態載入
│       └── loader.py             # ✅ SkillLoader 已完成

lewooogo-data 模組結構

packages/lewooogo-data/
├── src/lewooogo_data/
│   ├── interfaces/           # ABC 定義
│   │   └── memory_provider.py    → IMemoryProvider, IDualMemoryProvider
│   └── providers/            # 具體實作
│       ├── redis_memory.py       # ✅ RedisMemoryProvider 已完成
│       ├── pg_memory.py          # ✅ PgMemoryProvider 已完成
│       └── dual_memory.py        # ✅ DualMemoryProvider 已完成

---

📦 TypeScript 積木 (packages/)

積木名稱	職責	對外介面	ADR
lewooogo-core	前端 Plugin 系統	LeWOOOgoPlugin, AgentProvider, DataAdapter	ADR-003

---

🛡️ OpenClaw 架構治理 (AI Fallback & Rule Engine)

2026-03-31 首席架構師審查與定調

1. 高可用性 AI Fallback 路由

• 定義位置: K8s ConfigMap (awoooi-config) 的 AI_FALLBACK_ORDER
• 啟動條件: 當高優先級 Provider (如 NVIDIA) 因為 400 Bad Request, API Rate Limit 或是 Timeout 陣亡時。
• 預設排序: ["nvidia", "gemini", "ollama", "claude"]
• 目的: 確保告警裁決流程絕不中斷。出現 [LLM_GEMINI] 並非設定跑版，而是容錯轉移 (Failover) 完美運作的展現。

2. Mock LLM 與 規則匹配 (Rule-Match) 引擎

• 定義位置: decision_manager.py 與 openclaw.py 雙軌引擎
• 啟動條件: 系統偵測到特定靜態特徵 (如 CD_E2E_Test 系列)，判定為「無需耗費 AI Token 即有標準作業程序」。
• 特徵表現: 輸出 [規則匹配] 且強制定調 confidence = 0.0。這代表了 0% 的隨機猜測率，即 100% 的鐵律遵從，避免真正的假數據與浪費。

---

🤖 Agent Teams (apps/api/src/agents/)

Phase 9 新增 - 專家 Agent 群組

Agent 名稱	職責	狀態	ADR
SecurityAgent	資安風險評估與威脅分析	✅ 已完成	ADR-009
BlastRadiusAgent	爆炸半徑影響範圍分析	✅ 已完成	ADR-009
ActionPlannerAgent	行動計畫制定與步驟規劃	✅ 已完成	ADR-009
ConsensusEngine	多 Agent 共識引擎	✅ 已完成	ADR-009

Agent Teams 模組結構

apps/api/src/agents/
├── __init__.py
├── base_agent.py             # Agent 基底類別
├── security_agent.py         # ✅ SecurityAgent 資安專家
├── blast_radius_agent.py     # ✅ BlastRadiusAgent 影響分析
├── action_planner_agent.py   # ✅ ActionPlannerAgent 行動規劃
└── consensus_engine.py       # ✅ ConsensusEngine 共識引擎

---

🔗 模組依賴關係

apps/api (FastAPI BFF)
    ├── agents/ (Agent Teams) ✅ Phase 9 專家群組
    │   └── lewooogo-brain (AI 積木)
    ├── lewooogo-brain (AI 積木) ✅ Phase 6.4 已完成
    │   └── lewooogo-data (資料積木)
    └── lewooogo-data (直接引用) ✅ Phase 6.4 已完成

apps/web (Next.js)
    └── lewooogo-core (TS 積木)

Docker Build 指令 (Phase 6.4i)

# 必須從 monorepo 根目錄執行
cd /path/to/awoooi
docker build -f apps/api/Dockerfile -t awoooi-api:latest .

---

📋 介面契約索引

Python 介面

介面	位置	職責
IProposalEngine	lewooogo_brain.interfaces	決策提案生成
IIncidentProcessor	lewooogo_brain.interfaces	事件聚合處理
Guardrails	lewooogo_brain.guardrails	安全護欄與風險檢查
IMemoryProvider	lewooogo_data.interfaces	單層記憶體存取
IDualMemoryProvider	lewooogo_data.interfaces	雙層記憶體 (Working + Episodic)
BaseAgent	apps.api.src.agents	Agent 基底類別
ConsensusEngine	apps.api.src.agents	多 Agent 共識協調

HTTP API 契約

端點	位置	職責
POST /api/v1/incidents/{id}/propose	apps/api/src/api/v1/incidents.py	生成決策提案
GET /api/v1/incidents/{id}	apps/api/src/api/v1/incidents.py	取得事件詳情

---

🛡️ Wave 1 安全網 (Safety Net)

Phase 22 新增 - 系統底層防禦機制

元件名稱	職責	對外介面	狀態	ADR
CircuitBreaker	斷路器 - 防止推理引擎雪崩	is_circuit_open(), record_failure()	✅ 已完成	ADR-038
GlobalRepairCooldown	全域修復冷卻 - 防止修復迴圈	check_global_repair_cooldown()	✅ 已完成	ADR-039
OpenClawGuard	併發守衛 - Semaphore 限流	async with guard.semaphore	✅ 已完成	ADR-038
XCLAIM Sweeper	孤兒訊息回收器 - 防止訊息遺失	流式背景掃描 (_reclaim_loop)	✅ 已完成	ADR-037
IncidentDebounce	告警去抖動 - 防止告警風暴	_check_global_incident_storm()	✅ 已完成	ADR-037

安全網橫切關注點 (Cross-cutting)

• Graceful Degradation: AnomalyCounter 在 Redis 故障時自動降級為 In-memory count 或預設值。
• StatefulSet Blacklist: 禁止對 postgres, redis, clickhouse 等有狀態服務進行自動重啟。
• Termination Buffer: Worker 節點具備 90sec terminationGracePeriod 與 preStop: sleep 5 保險。

---

🛰️ Telegram 雙向對話 (Interactive Chat)

Phase 21.5 新增 - 統帥與 AI 的直連鏈路

元件名稱	職責	對外介面	狀態
ChatManager	對話大腦 - 整合 K3s 狀態與 LLM	generate_response()	✅ 已完成
TelegramGateway	訊息閘道 - 支援 Long Polling 雙向通訊	_handle_chat_message(), send_notification()	✅ 已完成

關鍵機制: 會話主權競爭 (Split-Brain Mitigation)

• 侵略性 Polling: 當遭遇 409 Conflict 時，重試延遲縮短至 2s (vfix14 導入)，確保 K3s Pod 優先奪回主權。
• Webhook Kicker: 透過暫時性 Webhook 設定 (set/delete) 強制中斷所有 Long Polling 會話，清空殘留衝突。

---

🔬 OpenClaw 魯棒分析引擎 (Resilient Parsing)

vfix16 導入 - 針對 Nemo-4B 進行模型適配

• NEMOTRON_SYSTEM_PROMPT: 專為 4K Context 設計的超精簡指令集，降低 LLM 輸出斷片的風險。
• 防崩潰填充 (Fail-safe Filling): 在 Pydantic 驗證前，若 JSON 缺失非核心欄位 (如 risk_level, confidence)，系統自動按上下文規律補全，防止 AI 仲裁退化為規則匹配。

---

1. 新增積木前: 先讀取此檔案確認命名不衝突
2. 新增積木後: 必須在此檔案登記職責與對外介面
3. 修改介面前: 先讀取 docs/adr/ 確認架構決策
4. 跨模組引用: 禁止直接 import，必須透過介面抽象