wooo/awoooi
1
1
Fork 0
Code Issues 2 Pull Requests 1 Actions 6 Packages Projects Releases Wiki Activity
Files
dev
awoooi/docs/ARCHITECTURE_INVENTORY.md
OG T 604e38cf07 docs: Phase 14 紅區治理 + Skills 01/03 更新 
- CLAUDE.md: 紅區治理章節
- Skills 01/03: 版本更新
- ADR/Architecture: 標準化

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-03-26 09:55:47 +08:00

124 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# AWOOOI 核心架構與程式碼最終盤點清單 (Core Architecture & Codebase Inventory)
> **專案名稱 (Project)**: AWOOOI
> **行動代號 (Operation)**: Operation Phoenix Rising (原 Cyber-Shell)
> **文件狀態 (Status)**: Active Development
> **建檔日期 (Date)**: 2026-03-19 (更新: 2026-03-25)
本文件記錄了 AWOOOI 系統從零到一的關鍵架構決策與防禦性實作（防雷紀錄），作為未來技術團隊接手、擴展與稽核的最高指導原則。
(This document records the key architectural decisions and defensive implementations of the AWOOOI system from zero to one, serving as the supreme guiding principle for future technical teams' handover, scaling, and auditing.)
---
## Phase 0: Phoenix Rising (2026-03-20 戰略重構)
| 核心文檔與規範 (Core Documentation) | 首席架構師拍板的「關鍵決策與排雷紀錄」 (Architect's Key Decisions & Pitfall Avoidance) |
| :--- | :--- |
| **API 開發 SOP**<br>`docs/api/API_DEVELOPMENT_SOP.md` | 定義 Contract-First 開發流程，強制 OpenAPI + MD 同步更新，CI 阻擋不一致提交。快取 TTL 分層 (1h/5m/30s/0) 與日誌脫敏規範。<br>*(Defined Contract-First workflow, enforced OpenAPI + MD sync updates with CI blocking. Cache TTL tiering and log sanitization rules.)* |
| **原子組件庫規格**<br>`docs/design/COMPONENT_LIBRARY.md` | 完整定義 Nothing.tech 純白工業風 Design Tokens (色彩/間距/字體/效果)。涵蓋 12 個核心組件規格 (StatusOrb/GlassCard/HostCard/ApprovalCard/CommandPalette 等)。<br>*(Complete Nothing.tech pure white industrial Design Tokens. 12 core component specifications including StatusOrb, GlassCard, HostCard, ApprovalCard, CommandPalette.)* |
| **RBAC 權限架構**<br>`docs/security/RBAC_SCHEMA.md` | 簡化至 4 角色 (Owner/Admin/Member/Viewer) + 資源級權限。Multi-Sig 簽核機制與 Blast Radius 風險矩陣。完整資料庫 Schema 與遷移策略。<br>*(Simplified to 4 roles + resource-level permissions. Multi-Sig approval mechanism with Blast Radius risk matrix. Complete DB schema and migration strategy.)* |
| **機密參考指南**<br>`docs/security/SECRETS_REFERENCE.md` | 解決「重複詢問帳密」痛點，記錄「去哪裡找」而非實際值。涵蓋開發 (.env.local)、CI (GitHub Secrets)、Prod (K8s Secrets) 三環境。<br>*(Solved "repeated credential asking" pain point. Documents "where to find" not actual values. Covers dev, CI, and prod environments.)* |
---
## Phase 1: 視覺與大腦 (前端與核心連線 / Visuals & AI Brain)
| 核心模組與檔案 (Core Modules) | 首席架構師拍板的「關鍵決策與排雷紀錄」 (Architect's Key Decisions & Pitfall Avoidance) |
| :--- | :--- |
| **狀態管理 (State Management)**<br>`agent.store.ts` | 採用 Zustand 封裝 SSE 串流與 `AbortController`，將網路請求與畫面渲染徹底解耦。<br>*(Adopted Zustand to encapsulate SSE streaming and `AbortController`, completely decoupling network requests from UI rendering.)* |
| **數據鉗 UI (Data Pincer UI)**<br>`data-pincer.tsx` | 落實 Nothing.tech 風格，使用 `.glass-panel` 與 Tailwind 狀態色碼，利用 Selector 避免無意義的重複渲染。<br>*(Implemented Nothing.tech style using `.glass-panel` and Tailwind status colors, utilizing Selectors to prevent meaningless re-renders.)* |
| **大腦連線 (Brain Connection)**<br>`agent.py` | 串接本地 Ollama 模型，實作「Token 累積緩衝（每 10 字符發送）」，確保前端打字機效果如絲綢般滑順。<br>*(Integrated local Ollama models with "Token Accumulation Buffer", ensuring silky-smooth typewriter effects on the frontend.)* |
---
## Phase 2: 人機協作與企業合規 (HITL & Enterprise Compliance)
| 核心模組與檔案 (Core Modules) | 首席架構師拍板的「關鍵決策與排雷紀錄」 (Architect's Key Decisions & Pitfall Avoidance) |
| :--- | :--- |
| **授權卡片 (Approval Card)**<br>`ApprovalCard.tsx` | 實作 Blast Radius (爆炸半徑) 視覺化，並針對 `DESTRUCTIVE` (毀滅性操作) 強制加入二次解鎖防呆機制。<br>*(Visualized Blast Radius and enforced a secondary unlock mechanism for `DESTRUCTIVE` operations to prevent human error.)* |
| **預演引擎 (Dry-Run Engine)**<br>`dry_run.py` | 實作 K8s Mock 驗證契約，涵蓋 RBAC、語法與資源檢查，確保「沒過 Dry-Run 絕對不准按批准」。<br>*(Implemented K8s Mock validation contracts covering RBAC, syntax, and resource checks. Strict rule: No approval without passing Dry-Run.)* |
| **多重簽核 (Multi-Sig)**<br>`approval.py` | 實作風險矩陣。**阻斷 TOCTOU 漏洞**：批准前強制重跑 Dry-Run；若狀態改變，簽章標記為 `VOIDED` (作廢) 以保留稽核軌跡，嚴禁物理刪除。<br>*(Implemented Risk Matrix. **Blocked TOCTOU Vulnerability**: Forced Dry-Run re-evaluation before approval execution. Voided signatures on state changes to preserve audit trails; physical deletion is strictly prohibited.)* |
| **資料脫敏 (Privacy Shield)**<br>`privacy_shield.py` | 實作企業級 Regex 攔截。導入 **Consistent Hashing (一致性雜湊)**，確保跨日誌的同 IP 獲得相同標籤，完美保留 AI 判斷上下文的能力。<br>*(Enterprise-grade Regex interception. Introduced **Consistent Hashing** to ensure identical IPs across logs get the same label, preserving AI context reasoning.)* |
---
## Phase 3: 企業護城河 (AI 擴充功能 / Enterprise Moats)
| 核心模組與檔案 (Core Modules) | 首席架構師拍板的「關鍵決策與排雷紀錄」 (Architect's Key Decisions & Pitfall Avoidance) |
| :--- | :--- |
| **工具橋樑 (MCP Bridge)**<br>`mcp_bridge.py` | 串接 MCP 協議。實作 **Rehydration Engine (資安標籤還原器)**，並要求按標籤長度或邊界匹配替換，嚴禁將還原後的參數寫入標準日誌。<br>*(MCP Protocol integration. Implemented **Rehydration Engine** with strict boundary-matching replacement rules. Logging rehydrated parameters is strictly forbidden.)* |
| **信任引擎 (Trust Engine)**<br>`trust_engine.py` | 實作漸進自治。導入 `normalize_action_pattern` 忽略 K8s Hash 碼；設定 Reject 瞬間歸零，且 `CRITICAL` 級別永遠不准降級。<br>*(Progressive Autonomy. Introduced `normalize_action_pattern` to ignore K8s hash codes. Rejects instantly reset trust to zero, and `CRITICAL` levels can never be downgraded.)* |
| **成本優化 (FinOps Engine)**<br>`cost_analyzer.py` | 實作 CFO 印鈔機。嚴格區分 `Realizable` (真實省錢) 與 `Freed` (釋放空間)；導入 `SAFETY_BUFFER = 1.2`，嚴防極限縮容導致 OOM 系統崩潰。<br>*(The CFO Money Printer. Strictly distinguished `Realizable` vs `Freed` savings. Introduced `SAFETY_BUFFER = 1.2` to prevent OOM system crashes from extreme downscaling.)* |
| **知識圖譜 (GraphRAG)**<br>`graph_rag.py` | 實作 BFS 上下游追溯。加入 **`max_depth` (最大深度限制)** 防止爆炸半徑無限擴張；尋找 Root Cause 時優先收集所有異常的 DB/CACHE 節點。<br>*(BFS upstream/downstream tracing. Added **`max_depth` limit** to prevent infinite blast radius expansion. Prioritized collecting all abnormal DB/CACHE nodes when seeking Root Causes.)* |
---
## Phase 4: 最終門面 (展示與開源準備 / Final Polish & Open Source)
| 核心模組與檔案 (Core Modules) | 首席架構師拍板的「關鍵決策與排雷紀錄」 (Architect's Key Decisions & Pitfall Avoidance) |
| :--- | :--- |
| **思考流終端機 (Thinking Terminal)**<br>`ThinkingTerminal` | 導入 ASCII Art 動態渲染拓撲依賴圖與 FinOps 三欄式紅綠燈，極致提升硬核賽博龐克質感。<br>*(Introduced dynamic ASCII Art rendering for topology dependency graphs and a 3-column FinOps traffic light system, maximizing the hardcore cyberpunk aesthetic.)* |
| **多語系引擎 (i18n Engine)**<br>`next-intl` & `middleware.ts` | 導入 `next-intl` 實作動態語系路由，支援 `zh-TW` (預設) 與 `en`，完美對齊企業級 SaaS 國際化標準。<br>*(Implemented dynamic locale routing with `next-intl`, supporting `zh-TW` (default) and `en`, perfectly aligning with enterprise SaaS i18n standards.)* |
| **開源門面 (Open Source README)**<br>`README.md` | 定調 Slogan 與 Hero Section，完整包裝四大企業護城河，為 GitHub 開源與商業化做好全面準備。<br>*(Defined Slogan and Hero Section, fully packaging the four enterprise moats, preparing for GitHub open-sourcing and commercialization.)* |
---
---
## Phase 6: 架構硬化 ✅ (2026-03-23 完成)
| 核心模組與檔案 (Core Modules) | 首席架構師拍板的「關鍵決策與排雷紀錄」 (Architect's Key Decisions & Pitfall Avoidance) |
| :--- | :--- |
| **Redis 狀態持久化**<br>`multi_sig_redis.py` ✅ | 將 `MultiSigEngine` 從 In-Memory 遷移至 Redis Hash，支援分散式部署與 7 天 TTL 稽核保留。導入 Redlock 演算法實現分散式鎖。 |
| **Event Bus**<br>`redis_streams.py` ✅ | Redis Streams 事件匯流排，支援告警信號傳遞與 Consumer Group 消費。 |
| **雙層記憶系統**<br>`dual_memory.py` ✅ | Working Memory (Redis) + Episodic Memory (PostgreSQL) 雙層同步架構。 |
| **SSE 容錯驗證**<br>`useApprovalSSE.ts` ✅ | 驗證 ADR-004 企業級 SSE 實作：Exponential Backoff、Heartbeat、Buffer 批次更新。 |
---
## Phase 7-10: 視覺主權與生產強化 ✅ (2026-03-21 ~ 23)
| 核心模組與檔案 (Core Modules) | 首席架構師拍板的「關鍵決策與排雷紀錄」 (Architect's Key Decisions & Pitfall Avoidance) |
| :--- | :--- |
| **GlobalPulseChart**<br>`global-pulse-chart.tsx` | 4 指標卡片 + Sparkline，Nothing.tech 純白工業風，真實 API 數據整合。 |
| **AIProcessStepper**<br>`ai-process-stepper.tsx` | 5 步 AI 決策流程視覺化，支援即時狀態更新。 |
| **Sentry 整合**<br>`sentry.client.config.ts` | Self-Hosted 192.168.0.110:9000 + Tunnel 避免內網權限對話框。 |
| **OpenClaw Agent Teams**<br>`agent_teams.py` | 多專家共識決策 (Security/BlastRadius/ActionPlanner)，加權投票機制。 |
| **Worker 獨立部署**<br>`awoooi-worker` | API/Worker Pod 分離，避免 Event Bus 阻塞影響 API 響應。 |
---
## Phase 11: 對話式 AI UI/UX ✅ (2026-03-25)
| 核心模組與檔案 (Core Modules) | 首席架構師拍板的「關鍵決策與排雷紀錄」 (Architect's Key Decisions & Pitfall Avoidance) |
| :--- | :--- |
| **ConversationalView**<br>`conversational-view.tsx` | ChatGPT 風格雙欄佈局，左側列表 + 右側詳情，SSE 即時更新整合。 |
| **BatchModeSelector**<br>`batch-mode-selector.tsx` | 批次處理模式 (全部接受/逐一審核/CRITICAL Only)，CRITICAL/DESTRUCTIVE 安全過濾。 |
| **useKeyboardShortcuts**<br>`useKeyboardShortcuts.ts` | Y/N 長按 2 秒 + 頂部進度條，防止誤觸。方向鍵導航 + Esc 取消。 |
| **SSE 即時更新**<br>`useApprovalSSE.ts` | Polling → SSE 改造，減少伺服器壓力，即時推送 Approval 狀態變更。 |
---
## Phase 12: Ollama 深度整合 ✅ (2026-03-25)
| 核心模組與檔案 (Core Modules) | 首席架構師拍板的「關鍵決策與排雷紀錄」 (Architect's Key Decisions & Pitfall Avoidance) |
| :--- | :--- |
| **Tool Calling 優化**<br>`parse_operation_from_action()` | 24 測試案例 (英/中/混合)，準確率 80% → 100%，支援中文指令解析。 |
| **ModelRouter**<br>`model_router.py` | 動態模型選擇，依複雜度路由到不同模型 (llama3.2:3b / qwen2.5:7b / qwen2.5:14b)。 |
| **本地模型優化**<br>`qwen2.5:7b-instruct` | 192.168.0.188 (62GB RAM)，Benchmark: qwen2.5 29s vs llama3.2 69s。 |
---
## Phase 13: Enterprise AIOps 🟡 (2026-03-25 規劃)
| 核心模組與檔案 (Core Modules) | 首席架構師拍板的「關鍵決策與排雷紀錄」 (Architect's Key Decisions & Pitfall Avoidance) |
| :--- | :--- |
| **CI/CD 整合** (13.1)<br>`github_webhook_handler.py` | Git Push/CI 失敗 → AI 審查診斷。風險分級自動修復 (LOW/MEDIUM 可自動，HIGH/CRITICAL 人工)。 |
| **Tool 實作** (13.2)<br>`mcp_bridge.py` | **P0 最優先** - Mock → 真實連接 (SignOz/K8s/PostgreSQL/RAG)，打通 AI 與外部系統。 |
| **智能路由** (13.3)<br>`ai_router.py` | Intent Classifier + Complexity Scorer + 動態模型選擇，小模型判別意圖 (< 100ms)。 |
---
*Zero-Touch Ops. Human-Centric Decisions.*
*(零干預維運，以人為本的決策。)*
Reference in New Issue View Git Blame Copy Permalink