5d76ac1145
Some checks failed
Code Review / ai-code-review (push) Successful in 13s
CD Pipeline / tests (push) Successful in 1m48s
Ansible / Reboot Recovery Contract / validate (push) Has been cancelled
CD Pipeline / post-deploy-checks (push) Has been cancelled
CD Pipeline / build-and-deploy (push) Has been cancelled
210 lines
9.5 KiB
Markdown
210 lines
9.5 KiB
Markdown
# 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)
|
||
|
||
```bash
|
||
# 必須從 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，必須透過介面抽象
|