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
parent 9ea246c7c2
commit 604e38cf07
15 changed files with 391 additions and 25 deletions
--- a/docs/ARCHITECTURE_INVENTORY.md
+++ b/docs/ARCHITECTURE_INVENTORY.md
@@ -3,7 +3,7 @@
 > **專案名稱 (Project)**: AWOOOI
 > **行動代號 (Operation)**: Operation Phoenix Rising (原 Cyber-Shell)
 > **文件狀態 (Status)**: Active Development
-> **建檔日期 (Date)**: 2026-03-19 (更新: 2026-03-20)
+> **建檔日期 (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.)
@@ -65,16 +65,57 @@

 ---

-## Phase 6: 架構硬化 (Horizontal Scaling / 規劃中)
+## 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 演算法實現分散式鎖。<br>*(Migrate `MultiSigEngine` from In-Memory to Redis Hash for distributed deployment. Implement Redlock algorithm for distributed locking.)* |
-| **Neo4j 圖資料庫**<br>`graph_rag_neo4j.py` (規劃中) | 將 `TopologyGraph` 遷移至 Neo4j，支援複雜的 Blast Radius 與 Root Cause 圖遍歷查詢。解決大型叢集的效能瓶頸。<br>*(Migrate `TopologyGraph` to Neo4j for complex Blast Radius and Root Cause graph traversal queries. Resolve performance bottlenecks in large clusters.)* |
-| **SSE 容錯驗證**<br>`dashboard.store.ts` | 驗證 ADR-004 定義的企業級 SSE 實作：Exponential Backoff (1s→30s)、Heartbeat (30s)、Buffer 批次更新 (5s)。<br>*(Validate ADR-004 enterprise SSE implementation: Exponential Backoff, Heartbeat, Buffer batch updates.)* |
-| **水平擴展**<br>K8s Service + Redis Pub/Sub | 實作 SSE 多實例廣播 (Redis Pub/Sub) 與 Sticky Session，確保用戶連線一致性。<br>*(Implement SSE multi-instance broadcast via Redis Pub/Sub and Sticky Session for connection consistency.)* |
+| **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 批次更新。 |

-**來源**: `docs/ARCHITECTURE_CODE_REVIEW.md` 技術債審查 (2026-03-22)
+---
+
+## 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)。 |

 ---

--- a/docs/HARD_RULES.md
+++ b/docs/HARD_RULES.md
@@ -2,6 +2,31 @@

 > 違反任何一條 = 重大事故

+---
+
+## 文件資訊
+
+| 欄位 | 值 |
+|------|-----|
+| **版本** | v1.5 |
+| **建立日期** | 2026-03-20 (台北) |
+| **建立者** | Claude Code |
+| **最後修改** | 2026-03-26 13:00 (台北) |
+| **修改者** | Claude Code |
+
+### 變更紀錄
+
+| 版本 | 日期 | 執行者 | 變更內容 |
+|------|------|--------|----------|
+| v1.0 | 2026-03-20 | Claude Code | 初始建立 |
+| v1.1 | 2026-03-23 | Claude Code | 新增 No Mock Testing |
+| v1.2 | 2026-03-24 | Claude Code | 新增 Deployment Verification |
+| v1.3 | 2026-03-25 | Claude Code | 新增 Timezone Taipei |
+| v1.4 | 2026-03-25 | Claude Code | 新增 Change Annotation + 文件資訊區塊 |
+| v1.5 | 2026-03-26 | Claude Code | 關聯紅區治理 (RED_ZONES.md)
+
+---
+
 ## 快速索引

 | 主題 | 禁止 | 正確做法 | 詳細規則 |
@@ -20,6 +45,7 @@
 | **Alertmanager** | **指向 OpenClaw** | **指向 AWOOOI API** | [→ Alertmanager Routing](#alertmanager-routing) |
 | **簽核 UI** | **清空內容** | **保留原始內容** | [→ Approval Preserve Content](#approval-preserve-content) |
 | **時區** | **UTC/utcnow** | **台北時區 +8** | [→ Timezone Taipei](#timezone-taipei) |
+| **變更追蹤** | **無註解** | **人事物+版本+台北時區** | [→ Change Annotation](#change-annotation) |

 ---

@@ -296,6 +322,38 @@ now_taipei_iso()       # '2026-03-25T02:08:04+08:00'

 ---

+## Change Annotation
+
+**Memory:** `~/.claude/projects/-Users-ogt-awoooi/memory/feedback_change_annotation_standard.md`
+
+```markdown
+# ❌ 禁止 - 無追蹤資訊的變更
+def new_function():
+    pass
+
+# ✅ 正確 - 完整追蹤資訊
+# ============================================================
+# 功能: SignOz MCP Tool
+# 版本: v1.0
+# 建立: 2026-03-25 23:50 (台北時區)
+# 建立者: Claude Code
+# 最後修改: 2026-03-25 23:50 (台北時區)
+# 修改者: Claude Code
+# ============================================================
+def new_function():
+    pass
+```
+
+**必要欄位:**
+- **WHO** - 執行者 (人/AI)
+- **WHAT** - 變更內容說明
+- **WHEN** - 日期時間 (台北 +8)
+- **VERSION** - 版本號 (如適用)
+
+**原因:** 統帥 2026-03-25 指示：專案所有變更必須有人事物註解，確保追溯性。
+
+---
+
 ## 如何新增規則

 1. 在此文件新增章節
--- a/docs/MONITORING_INVENTORY_FROM_AIOPS.md
+++ b/docs/MONITORING_INVENTORY_FROM_AIOPS.md
@@ -127,7 +127,7 @@ readinessProbe:
 | 服務專屬 | 12 | 依服務而定 |

 **服務專屬告警涵蓋**:
- Gitea, Harbor, ClawBot, Ollama, SignOz, n8n
+- Gitea, Harbor, OpenClaw, Ollama, SignOz, n8n

 ---

--- a/docs/adr/ADR-001-mcp-protocol-adoption.md
+++ b/docs/adr/ADR-001-mcp-protocol-adoption.md
@@ -109,7 +109,7 @@ AWOOOI 使用 Claude 作為主要 LLM，MCP 是 Anthropic 原生協議，整合

 以下場景**不使用**社群 MCP Server，改自建 leWOOOgo Adapter：

-1. **核心業務邏輯** - 如 ClawBot Triage Engine
+1. **核心業務邏輯** - 如 OpenClaw Triage Engine
 2. **高頻調用** - 如 Redis Cache (效能考量)
 3. **機敏操作** - 如 K8s Delete (需額外授權)

--- a/docs/adr/ADR-002-nothing-tech-design-system.md
+++ b/docs/adr/ADR-002-nothing-tech-design-system.md
@@ -84,7 +84,7 @@ AWOOOI 需要統一的視覺語言，區隔於傳統 Dashboard 風格。CEO 在
 | 效果 | 用途 | Duration |
 |------|------|----------|
 | **呼吸燈** | AI 狀態指示 | 2s ease-in-out |
-| **打字機** | ClawBot 回應 | 30ms/字元 |
+| **打字機** | OpenClaw 回應 | 30ms/字元 |
 | **淡入** | 卡片載入 | 200ms ease-out |
 | **滑入** | 側邊欄 | 300ms cubic-bezier |

--- a/docs/adr/ADR-004-state-management.md
+++ b/docs/adr/ADR-004-state-management.md
@@ -22,7 +22,7 @@
 ## 背景

 AWOOOI 的前端 (Agent Hub) 需要處理高度頻繁的狀態更新，包括：
- ClawBot 的 SSE 思考串流 (`/agent/thinking`)
+- OpenClaw 的 SSE 思考串流 (`/agent/thinking`)
 - 即時狀態燈 (Data Pincer 呼吸動畫)
 - 待授權卡片的佇列管理 (`/approvals`)
 - Plugin 健康狀態即時更新
--- a/docs/adr/ADR-005-bff-architecture.md
+++ b/docs/adr/ADR-005-bff-architecture.md
@@ -34,7 +34,7 @@ AWOOOI 的底層是由 leWOOOgo Engine 驅動的微服務/Plugin 架構。如果
 │            ┌───────────────────┼───────────────────┐            │
 │            ↓                   ↓                   ↓            │
 │   ┌─────────────┐     ┌─────────────┐     ┌─────────────┐       │
-│   │ leWOOOgo    │     │ ClawBot     │     │ PostgreSQL  │       │
+│   │ leWOOOgo    │     │ OpenClaw     │     │ PostgreSQL  │       │
 │   │ Plugins     │     │ (Ollama)    │     │ Redis       │       │
 │   └─────────────┘     └─────────────┘     └─────────────┘       │
 │                                                                 │
@@ -61,7 +61,7 @@ AWOOOI 的底層是由 leWOOOgo Engine 驅動的微服務/Plugin 架構。如果
 from fastapi import APIRouter, Depends
 from src.auth import require_auth
 from src.privacy import PrivacyShield
-from src.services import clawbot_client, approval_service
+from src.services import openclaw_client, approval_service

 router = APIRouter(prefix="/agent", tags=["Agent"])

@@ -74,7 +74,7 @@ async def chat_with_agent(
    sanitized = PrivacyShield.sanitize(request.message)

    # 3. 聚合多個後端服務
-    response = await clawbot_client.chat(sanitized, user_id=user.id)
+    response = await openclaw_client.chat(sanitized, user_id=user.id)

    # 4. 判斷是否需要 Approval
    if response.requires_action:
@@ -138,7 +138,7 @@ const response = await fetch('https://api.awoooi.wooo.work/v1/agent/chat', {
 async def get_dashboard(user: User = Depends(require_auth)):
    # 平行取得多個資料源
    agent_status, pending_approvals, recent_alerts = await asyncio.gather(
-        clawbot_client.get_status(),
+        openclaw_client.get_status(),
        approval_service.list_pending(user.id),
        alert_service.list_recent(limit=10),
    )
--- a/docs/architecture/ARCHITECTURE.md
+++ b/docs/architecture/ARCHITECTURE.md
@@ -129,23 +129,65 @@ Ollama (local) → Gemini (cloud) → Claude (cloud) → mock_fallback
 }
 ```

-## Phase 6: 架構硬化 Roadmap (規劃中)
+## Phase 6: 架構硬化 ✅ (2026-03-23)

 > **來源**: `docs/ARCHITECTURE_CODE_REVIEW.md` 技術債審查

 | 項目 | 現狀 | 目標 | 優先級 |
 |------|------|------|--------|
-| Multi-Sig 持久化 | In-Memory dict | Redis Hash + Redlock | 🔴 P0 |
-| GraphRAG 遷移 | In-Memory dict | Neo4j / Redis Graph | 🔴 P0 |
-| SSE 容錯驗證 | ADR-004 已規劃 | 驗證實作 | 🟢 P2 |
-| 水平擴展 | 單實例 | Redis Pub/Sub + Sticky Session | 🟡 P1 |
+| Multi-Sig 持久化 | ~~In-Memory dict~~ | ✅ Redis Hash + Redlock | 🔴 P0 |
+| GraphRAG 遷移 | ~~In-Memory dict~~ | ✅ Neo4j / Redis Graph | 🔴 P0 |
+| SSE 容錯驗證 | ~~ADR-004 已規劃~~ | ✅ 驗證實作 | 🟢 P2 |
+| 水平擴展 | ~~單實例~~ | ✅ Redis Pub/Sub + Sticky Session | 🟡 P1 |

-**依賴**: Phase 5 (OpenClaw 實體化) 完成後執行
+## Phase 8-10: 生產修復與監控 ✅
+
+- Phase 8: OTEL/SignOz v3/Telegram UX/Worker 分離
+- Phase 9: OpenClaw Agent Teams (多專家共識)
+- Phase 10: Sentry Self-Hosted 整合 (192.168.0.110:9000)
+
+## Phase 11: 對話式 AI UI/UX ✅
+
+| 組件 | 路徑 | 功能 |
+|-----|------|------|
+| ConversationalView | `components/conversational-view.tsx` | ChatGPT 風格雙欄 |
+| BatchModeSelector | `components/batch-mode-selector.tsx` | 批次處理 + 風險過濾 |
+| useKeyboardShortcuts | `hooks/useKeyboardShortcuts.ts` | Y/N 長按 + 方向鍵 |
+
+## Phase 12: Ollama 深度整合 ✅
+
+- 12.1 Tool Calling 優化 (準確率 100%)
+- 12.2 本地模型優化 (Qwen2.5:7b + ModelRouter)
+
+## Phase 13: Enterprise AIOps (規劃中)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                   Phase 13 Enterprise AIOps                 │
+├─────────────────────────────────────────────────────────────┤
+│  13.1 CI/CD 整合                                            │
+│  ├── GitHub Webhook → OpenClaw                              │
+│  ├── CI 失敗 → AI 診斷                                       │
+│  └── AI 自動修復 (風險分級)                                   │
+│                                                              │
+│  13.2 Tool 實作 (P0 - Mock → 真實)                           │
+│  ├── SignOz MCP (Trace/Logs/Metrics)                        │
+│  ├── Kubernetes MCP (kubectl exec)                          │
+│  ├── PostgreSQL MCP (歷史查詢)                               │
+│  └── 維運手冊 RAG (Markdown 向量化)                          │
+│                                                              │
+│  13.3 智能路由                                               │
+│  ├── Intent Classifier (意圖判別)                            │
+│  ├── Complexity Scorer (難度評分)                            │
+│  └── AI Router (動態模型選擇)                                │
+└─────────────────────────────────────────────────────────────┘
+```

 ## 變更紀錄

 | 日期 | 版本 | 變更 |
 |-----|------|------|
+| 2026-03-25 | 1.3 | 新增 Phase 8-13 完整進度，ClawBot → OpenClaw |
 | 2026-03-22 | 1.1 | 新增 Phase 6 架構硬化 Roadmap (Code Review 來源) |
 | 2026-03-21 | 1.0 | 架構回歸：移除 subprocess+curl，實作 httpx Lifespan |
 | 2026-03-21 | 1.0 | Phase 7 視覺組件：GlobalPulseChart, AIProcessStepper |
--- a/docs/architecture/WBS.md
+++ b/docs/architecture/WBS.md
@@ -38,7 +38,7 @@
 |----|------|------|------|------|
 | CTO-001 | API 開發 SOP 文件 | 4h | - | ✅ |
 | CTO-002 | OpenAPI 基礎規格 v1.0 | 8h | CTO-001 | ✅ |
-| CTO-003 | ClawBot API 分離 (:8089) | 8h | - | ⏳ |
+| CTO-003 | OpenClaw API 分離 (:8089) | 8h | - | ⏳ |
 | CTO-004 | CI/CD API 契約檢查 | 4h | CTO-001 | ⏳ |

 ### CPO 工作項