awoooi/.awoooi-agent-rules.md

# AWOOOI - AI Agent 開發契約 (L1 System Prompt)

> **版本**: v2.2 (Operation Phoenix Rising - 戰略對齊)
> **生效日期**: 2026-03-21
> **適用對象**: Claude Code / Cursor / GitHub Copilot
> **強制等級**: 絕對遵守 (違反等同事故)

---

## 🎯 品牌 Slogan (最高定讞)

> **"AI Sees. AI Acts. You Approve."**

此 Slogan 為統帥親自核定，不可更改。代表 AWOOOI 的三大核心價值：
1. **AI Sees** - AI 全方位監控與感知
2. **AI Acts** - AI 自主執行運維動作
3. **You Approve** - 人類保有最終決策權 (HITL Multi-Sig)

---

## 🔴 重大戰略變更 (2026-03-20)

**AWOOOI 定位從「Agent 指揮艙」升級為「100% 獨立重構的 SaaS 平台」**

| 項目 | 原計畫 | 新計畫 |
|------|--------|--------|
| 產品定位 | 舊系統附屬品 | **完全取代舊版 (63+ 頁面重構)** |
| 視覺風格 | 深色駭客風 | **Nothing.tech 純白工業風** |
| AI 整合 | 部分頁面 | **全站 AI Copilot (Ubiquitous AI)** |
| 語言 | 單語 | **雙語 (zh-TW + en)** |

---

## 🎯 專案定位

**AWOOOI** (AI + WOOO) 是岑洋國際行銷有限公司的**全新獨立 SaaS 智能運維平台**。

| 項目 | 說明 |
|------|------|
| **母品牌** | AWOOOI |
| **技術引擎** | leWOOOgo Engine (樂高模組化) |
| **視覺符號** | Data Pincer (數據鉗) |
| **設計風格** | Nothing.tech **純白工業風** (點陣紋理 + 白玻璃 + 高對比) |
| **核心理念** | AI-Infused (全站 AI Copilot，無所不在) |
| **語言支援** | 繁體中文 (zh-TW) + English (en) |

---

## 🚫 絕對禁止事項 (紅線)

### 1. 禁止 Import 舊代碼
```typescript
// ❌ 絕對禁止
import { something } from '../../../wooo-aiops/src/...'
import { legacy } from '@wooo-aiops/...'

// ✅ 正確做法：透過 HTTP API 呼叫
const response = await fetch('https://api.aiops.wooo.work/v1/...')
```

### 2. 禁止修改舊專案
```bash
# ❌ 絕對禁止在此專案中編輯以下路徑
/Users/ogt/wooo-aiops/*

# ✅ 舊專案僅供「唯讀參考」
# 如需修改舊專案，請切換到舊專案的工作區
```

### 3. 禁止使用過時標籤
```yaml
# ❌ 禁止
image: wooo/api:latest
image: wooo/api:main

# ✅ 正確：唯一不可變標籤
image: 192.168.0.110:5000/library/awoooi-api:{sha}-{run_id}
```

### 4. 禁止硬編碼機密
```typescript
// ❌ 禁止
const API_KEY = "sk-xxx..."

// ✅ 正確：環境變數
const API_KEY = process.env.API_KEY
```

### 5. 物理部署鐵律：禁止腦分裂 (Split Brain Prevention)

> **2026-03-22 C-Suite 戰略會議決議**

```
┌─────────────────────────────────────────────────────────────────┐
│  AWOOOI 物理架構：單一大腦 + 分散感測器                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   .188 AI 中心 (唯一大腦)                                       │
│   ┌─────────────────────────────────────────────────────────┐  │
│   │  OpenClaw + Redis + PostgreSQL + Ollama                 │  │
│   │  (決策層 + 記憶層 + 認知層)                              │  │
│   └─────────────────────────────────────────────────────────┘  │
│                              ↑                                  │
│              Event Bus (Redis Streams) 統一匯流                 │
│                              ↑                                  │
│   ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐          │
│   │  .110   │  │  .112   │  │  .120   │  │  .121   │          │
│   │ Sensor  │  │ Sensor  │  │ Sensor  │  │ Sensor  │          │
│   └─────────┘  └─────────┘  └─────────┘  └─────────┘          │
│   (感測器只採集，不決策)                                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

| 禁止行為 | 原因 |
|----------|------|
| **多主機部署多個 OpenClaw** | 🔴 腦分裂：記憶不同步、決策衝突 |
| **各主機獨立 Redis** | 🔴 狀態不一致：簽核可能被重複處理 |
| **Sensor 自行決策** | 🔴 越權：感測器只能採集，不能行動 |

| 正確做法 | 說明 |
|----------|------|
| **.188 為唯一大腦中心** | 所有 AI 推論、記憶存取、決策產生都在 .188 |
| **其他主機只部署 Sensor** | .110/.112/.120/.121 只負責採集並送回 Event Bus |
| **統一 Event Bus** | 所有告警透過 Redis Streams 匯流至 .188 處理 |

---

## ✅ 開發準則

### leWOOOgo 六大積木類別

| 類別 | 用途 | 範例 |
|------|------|------|
| **INPUT** | 觸發器 | Webhook, Cron, Alert |
| **BRAIN** | AI 處理 | LLM Router, RAG, Triage |
| **OUTPUT** | 通知 | Telegram, Slack, Email |
| **ACTION** | 執行器 | K8s, SSH, API Call |
| **DATA** | 儲存 | Redis, PostgreSQL, S3 |
| **UI** | 介面元件 | Widget, Card, Chart |

### 技術棧

| 層級 | 技術選擇 |
|------|----------|
| **Frontend** | Next.js 14+ / React 18+ / TypeScript |
| **Styling** | Tailwind CSS (Nothing.tech 配置) |
| **State** | Zustand + React Query |
| **Backend** | FastAPI (Python 3.11+) |
| **Database** | PostgreSQL + Redis Stack |
| **AI** | MCP Protocol + LLM Router |
| **Observability** | SigNoz (OTEL) + Prometheus |
| **Container** | Harbor Registry (192.168.0.110:5000) |
| **Orchestration** | K3s (192.168.0.120/121) |

### Nothing.tech 設計規範 (純白工業風 v2.0)

> ⚠️ **2026-03-20 重大變更**: 從深色駭客風轉為純白工業風

```css
/* 色彩系統 - 純白基底 */
--nothing-white: #FFFFFF;
--nothing-snow: #FAFAFA;      /* 主背景 */
--nothing-cloud: #F5F5F5;     /* 次背景 */
--nothing-mist: #E5E5E5;      /* 邊框 */
--nothing-ink: #0A0A0A;       /* 主文字 (高對比) */
--nothing-gray: #6B7280;      /* 次文字 */
--nothing-red: #D71921;       /* Nothing 品牌紅 */

/* 功能色 */
--status-success: #10B981;    /* 綠 */
--status-warning: #F59E0B;    /* 黃 */
--status-error: #EF4444;      /* 紅 */
--status-info: #3B82F6;       /* 藍 */
--status-thinking: #8B5CF6;   /* AI 思考紫 */

/* 品牌色 */
--brand-primary: #FF6B35;     /* AWOOOI 橘 */

/* 字體 */
--font-display: "NDot", monospace;  /* AI 介面 (點陣風) */
--font-body: "Inter", system-ui;     /* 一般文字 */

/* 效果 - 白玻璃 (非深色毛玻璃) */
--glass-blur: blur(20px);
--glass-bg: rgba(255, 255, 255, 0.7);  /* 白玻璃 */
--glass-border: rgba(0, 0, 0, 0.05);

/* 點陣紋理 */
--dot-matrix: radial-gradient(circle, rgba(0, 0, 0, 0.03) 1px, transparent 1px);
--dot-size: 16px 16px;
```

### 視覺風格參考

| 參考 | 特徵 | 應用 |
|------|------|------|
| Nothing Phone | 點陣燈、透明背板 | 點陣紋理、透光感 |
| Apple Health | 乾淨白底、高對比 | 數據呈現 |
| Linear | 極簡、功能優先 | 介面佈局 |
| 醫療監控儀 | 精密、冷靜、專業 | 整體氛圍 |

### 🧬 視覺 DNA 憲法 (Nothing.tech Pure White Identity)

> **⚠️ 2026-03-21 戰略對齊**: **Cyber Palette (深空灰/螢光綠) 已作廢**
> **絕對強制**: Nothing.tech 純白工業風，禁止任何深色系/駭客風/螢光色
>
> **AWOOOI 視覺 DNA：白玻璃 + 骨架細框 + 點陣 Typography + 機械爪藍**
> **最高指令：扁平化 shadcn/ui 與深色駭客風全部作廢，採用純白工業賽博風格。**

#### 核心視覺元素

| 元素 | 規範 | 說明 |
|------|------|------|
| **awoooi-glass** | `bg-white/70 backdrop-blur-[20px]` | 高通透度毛玻璃，禁止不透明 |
| **骨架細框線** | `border border-nothing-gray-200/50` | Skeletal Style 精密線條 |
| **點陣字體** | `VT323`, `font-mono` | 所有狀態文字必須點陣風格 |
| **機械爪藍** | `#4A90D9` (claw-blue) | AI 核心 LED 發光色 |
| **思維紫** | `#8B5CF6` (status-thinking) | AI 思考狀態專用 |

#### OpenClaw 視覺規範

```tsx
// 機械爪面板 - 3D 骨架風格
<div className={cn(
  'relative overflow-hidden rounded-xl',
  'bg-white/70 backdrop-blur-[20px]',     // awoooi-glass
  'border border-nothing-gray-200/50',     // 骨架細框線
  'shadow-[0_4px_24px_rgba(0,0,0,0.06)]'  // 輕柔陰影
)}>
  {/* 核心 LED - 藍色脈衝 */}
  <div className="w-4 h-4 rounded-full bg-claw-blue animate-pulse shadow-glow-blue" />

  {/* 點陣狀態文字 */}
  <span className="font-mono text-xs tracking-widest text-nothing-gray-600">
    [AGENT] patrolling...
  </span>
</div>
```

#### AI 思考流動畫 (WOW Factor)

當收到告警時的視覺流程：
1. **攔截階段**: 機械爪核心藍燈快速脈衝 (`animate-ping`)
2. **分析階段**: 點陣字體打字機效果 `[SYS] Analyzing blast radius...`
3. **生成階段**: `[SYS] Generating proposed action...`
4. **完成階段**: 卡片 Slide Up 動畫進入 (`animate-slide-in-up`)

### 🔴 視覺鐵律 (Phase 0 紀律 - 2026-03-20)

> **絕對遵守 Nothing.tech 的透明、硬核、極簡風格。禁止任何遮蔽數據的大面積不透明漸層色塊。**

#### 絕對禁止

| 禁止項目 | 說明 |
|----------|------|
| **不透明漸層色塊** | 任何 gradient 色塊若遮蔽底層數據，視為 UX 災難 |
| **過度光暈效果** | 禁止 `shadow-glow`, `ring-4` 等大面積發光效果 |
| **Border Beam 濫用** | 流光邊框禁止使用於資料卡片，會遮蔽右側內容 |
| **深色半透明遮罩** | 禁止 `bg-black/50` 等降低可讀性的遮罩 |
| **扁平化 shadcn/ui** | 統帥已廢除，改用賽博維運骨架風格 |

#### 正確做法

```tsx
// ✅ CRITICAL 狀態：僅使用左側 4px 邊框
className="border-l-4 border-l-status-critical"

// ✅ MEDIUM 狀態：左側黃色邊框
className="border-l-4 border-l-status-warning"

// ✅ LOW 狀態：左側綠色邊框
className="border-l-4 border-l-status-healthy"

// ✅ awoooi-glass 毛玻璃效果 (白玻璃)
className="bg-white/70 backdrop-blur-[20px] border border-black/[0.06]"

// ❌ 禁止：遮蔽數據的漸層
className="bg-gradient-to-r from-red-500/50 to-transparent"

// ❌ 禁止：過度光暈
className="shadow-[0_0_30px_rgba(239,68,68,0.5)]"
```

#### 視覺資產規範 (第七章)

- **禁止**要求使用者下載/搬運實體圖檔 (PNG/JPG/SVG)
- **強制**使用 lucide-react 圖示 + CSS Typography
- **Logo**: 使用 lucide-react `Eye`/`Bot`/`Brain` + 呼吸燈動畫
- **狀態指示**: 純 CSS `animate-ping`, `animate-pulse`
- **品牌色塊**: Tailwind 漸層背景 (不遮蔽數據)

```tsx
// ✅ 正確 - 純代碼 Logo
import { Eye, Sparkles } from 'lucide-react'
<div className="w-10 h-10 rounded-xl bg-claw-blue/10 flex items-center justify-center">
  <Eye className="w-6 h-6 text-claw-blue" />
</div>

// ❌ 禁止 - 依賴實體圖片
<img src="/logo-claw.png" alt="Logo" />
```

---

## 🖥️ 四主機架構 (基礎設施常量)

> 萃取自舊專案 CLAUDE.md，這些 IP 與伺服器配置適用於所有 WOOO 專案
> ⚠️ **2026-03-21 戰略對齊**: **跳過 UAT 環境，直接以 Production Ready 標準建置**

| IP | 名稱 | 職責 |
|-----|------|------|
| **192.168.0.110** | DevOps 金庫 | Harbor:5000 (`awoooi/` Project), GH Runner (`awoooi-runner`) |
| **192.168.0.112** | Kali Security | Scanner API:8080 (Header 區分: `X-Source: awoooi`) |
| **192.168.0.188** | AI+Web 中心 | Nginx SSL, Ollama:11434, **OpenClaw:8089**, **SigNoz:3301 (OTEL 收集器)** |
| **192.168.0.120** | K3s Master | **awoooi-prod (API:32334, Frontend:32335)** ⚠️ 唯一部署目標 |
| **192.168.0.121** | K3s Worker | HA 備援 |

### AWOOOI 專用 Port 分配

> ⚠️ **絕對禁令**: 禁止部署 UAT 環境，僅使用 Prod (32334/32335)

| 環境 | Frontend | API | OpenClaw | 狀態 |
|------|----------|-----|---------|------|
| **AWOOOI Prod** | **32335** | **32334** | 8089 | ✅ 唯一部署目標 |
| ~~AWOOOI UAT~~ | ~~32235~~ | ~~32234~~ | - | ❌ **已廢除** |
| Legacy (凍結) | 31235 | 31234 | 8088 | 🔒 禁止觸碰 |

### 網路隔離原則

- **Nginx 路由**: `awoooi.wooo.work` 獨立於 `aiops.wooo.work`
- **K8s Namespace**: `awoooi-prod` 為唯一部署目標 (禁止 UAT)
- **NetworkPolicy**: 禁止 AWOOOI 連接 Legacy Namespace (`wooo-aiops`)
- **Port 鐵律**: 僅使用 32334/32335，禁止觸碰 31234/31235/32234/32235

---

## 🚨 六大鐵律 (違反等同事故)

> 萃取自舊專案 CLAUDE.md，這些規則是公司級基礎設施鐵律

| # | 鐵律 | 說明 |
|---|------|------|
| 1 | **kustomization 禁寫 newTag** | 導致 Ghost Rollback，Tag 由 CI 動態注入 |
| 2 | **CI/CD 禁止 git push 回 main** | GitOps Lite 已永久停用 |
| 3 | **映像標籤必須唯一不可變** | 格式: `{sha}-{run_id}`，禁用 latest/main/dev |
| 4 | **禁止 Gitea ↔ GitHub 雙向同步** | 唯一來源: GitHub |
| 5 | **LLM 調用必須走快取** | 使用 `_call_with_cache`，禁止直接調用 |
| 6 | **Markdown 產出必須遵守格式** | 頭部元數據 + 更新 LOGBOOK |
| 7 | **可觀測性必須打向 SigNoz** | OTEL Traces/Logs → 192.168.0.188:3301 |
| 8 | **UI 文字禁止硬編碼** | 100% next-intl 字典檔 (zh-TW/en) |

---

## 🔭 可觀測性鐵律 (Observability Iron Law)

> **2026-03-21 新增**: 所有後端服務必須整合 OpenTelemetry

### 強制配置

```python
# apps/api/src/core/telemetry.py
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor

# SigNoz 端點 (絕對禁止寫死其他地址)
SIGNOZ_ENDPOINT = "http://192.168.0.188:4317"

def setup_telemetry(app):
    provider = TracerProvider()
    processor = BatchSpanProcessor(OTLPSpanExporter(endpoint=SIGNOZ_ENDPOINT))
    provider.add_span_processor(processor)
    trace.set_tracer_provider(provider)
    FastAPIInstrumentor.instrument_app(app)
```

### 必要依賴

```txt
# apps/api/requirements.txt
opentelemetry-api>=1.20.0
opentelemetry-sdk>=1.20.0
opentelemetry-exporter-otlp>=1.20.0
opentelemetry-instrumentation-fastapi>=0.41b0
opentelemetry-instrumentation-httpx>=0.41b0
opentelemetry-instrumentation-sqlalchemy>=0.41b0
```

### 驗收標準

| 項目 | 要求 |
|------|------|
| **Traces** | 所有 API 請求可在 SigNoz 追蹤 |
| **Logs** | 結構化日誌含 trace_id 關聯 |
| **Metrics** | Prometheus 格式 /metrics 端點 |
| **Dashboards** | SigNoz 預建 AWOOOI 儀表板 |

---

## 🔐 機密查詢指南

> **2026-03-20 新增**: 解決「重複詢問帳密」痛點

**AI 不需要重複詢問帳號密碼，請查閱：**

| 環境 | 位置 |
|------|------|
| 開發環境 | `.env.local` (本機) |
| 服務端點 | `docs/security/SECRETS_REFERENCE.md` |
| 生產環境 | `kubectl get secret -n awoooi-prod` |

詳見: [SECRETS_REFERENCE.md](docs/security/SECRETS_REFERENCE.md)

---

## 📚 知識參考來源

AI 可跨資料夾讀取以下舊專案文檔 (唯讀)：

| 文檔 | 路徑 | 用途 |
|------|------|------|
| **架構規範** | `/Users/ogt/wooo-aiops/CLAUDE.md` | 開發規則參考 |
| **API 規格** | `/Users/ogt/wooo-aiops/docs/` | 舊 API 格式 |
| **會議記錄** | `/Users/ogt/wooo-aiops/docs/meetings/` | 決策歷史 |
| **運維日誌** | `/Users/ogt/wooo-aiops/LOGBOOK.md` | 進度追蹤 |
| **鐵律記憶** | `/Users/ogt/wooo-aiops/.claude/projects/-Users-ogt-wooo-aiops/memory/` | 重要規則 |

---

## 👁️ 首席架構師防禦性審查 (Mandatory Review)

> **2026-03-21 新增**: 防止基礎設施配置錯誤的永久記憶

### 條款 1：四主機架構強制交叉比對

**任何涉及 IP、Port、主機名稱的改動，必須與以下常量嚴格比對：**

| IP | 職責 | 允許操作 |
|-----|------|----------|
| **192.168.0.110** | DevOps 金庫 (Harbor) | Docker Registry 操作 |
| **192.168.0.112** | Kali Security | 安全掃描 API 呼叫 |
| **192.168.0.188** | AI+Web 中心 | **Nginx 部署**、Ollama、SigNoz |
| **192.168.0.120** | K3s Master | kubectl 操作、NodePort 存取 |
| **192.168.0.121** | K3s Worker | HA 備援 (禁止直接操作) |

**違規範例 (已發生)：**
```bash
# ❌ 錯誤：將 Nginx 設定部署到 DevOps 金庫
scp awoooi.wooo.work.conf root@192.168.0.110:/etc/nginx/

# ✅ 正確：部署到 AI+Web 中心
scp awoooi.wooo.work.conf root@192.168.0.188:/etc/nginx/
```

### 條款 2：交付前自主 Code Review 清單

**每次交付工作前，Claude Code 必須自主執行以下檢查：**

| 檢查項目 | 驗證方法 |
|---------|---------|
| **無主執行緒阻塞** | 確認 async/await、BackgroundTasks 正確使用 |
| **無記憶體溢出風險** | Array 有 slice() 限制、無無限累積 |
| **無硬編碼機密** | grep 搜尋 `sk-`, `password=`, `token=` |
| **IP/Port 交叉比對** | 與四主機架構表格核對 |
| **OTEL 追蹤整合** | 新端點有 span 包裹 |
| **i18n 完整性** | 無硬編碼中英文字串 |

### 條款 3：🛑 交付前強制驗證 (Pre-Commit Verification)

> **2026-03-21 新增**: 解決「AI 修改前端後無視畫面崩潰」問題

**只要修改了前端檔案，回報前必須自主執行以下驗證：**

| 驗證類型 | 命令 | 觸發條件 |
|---------|------|---------|
| **靜態檢查** | `cd apps/web && pnpm exec tsc --noEmit` | 任何 .tsx/.ts 修改 |
| **編譯檢查** | `cd apps/web && pnpm run build` | 重大 UI 變更 |
| **終端機監聽** | 讀取 dev server 最後 20 行日誌 | npm run dev 運行中 |

**必須攔截的 Runtime 錯誤：**

```
❌ ReferenceError: xxx is not defined
❌ Hydration failed because the initial UI does not match
❌ Cannot read properties of undefined
❌ Module not found: Can't resolve
❌ Type error: xxx
```

**驗證流程（強制）：**

1. 修改前端檔案後
2. 執行 `pnpm exec tsc --noEmit` 或 `pnpm run build`
3. 確認無錯誤後才可回報「已完成」
4. 若有錯誤，必須先修復再回報

**違規處置：**

- 回報「完成」但前端崩潰 → 視為嚴重事故
- 必須在下次回覆中展示驗證終端機輸出

### 條款 4：🛑 禁止任務轉嫁 (No Task Delegation to Human)

> **2026-03-21 新增**: 解決「AI 把指令丟給統帥自己執行」的反模式

**核心原則：Claude Code 是執行者，不是秘書。**

#### 主動執行原則

```
❌ 禁止：「請統帥執行 pnpm dev」
❌ 禁止：「請在終端機輸入 python scripts/xxx.py」
❌ 禁止：「請手動建立 .env.local 檔案」

✅ 正確：直接執行指令並回報結果
✅ 正確：使用 Bash 工具自動化所有操作
```

#### 授權模式原則 (The Approval Pattern)

若指令涉及**破壞性操作**或**外部系統連線**，必須先提案：

```markdown
📋 執行提案

我已準備好執行以下指令：
`python -m scripts.fire_test_alert --type db_connection_timeout`

此操作將：
- 向 Webhook API 發送模擬告警
- 觸發 OpenClaw AI 分析
- 建立一筆待簽核卡片

統帥，是否授權執行？ [Y/n]
```

#### 自動化優先

| 情境 | 正確做法 |
|------|---------|
| 需要啟動服務 | 直接執行 `pnpm dev` 或 `uvicorn` |
| 需要測試腳本 | 直接執行並回報輸出 |
| 需要建立檔案 | 使用 Write 工具直接建立 |
| 需要查看日誌 | 使用 Bash 讀取並摘要回報 |

**違規處置：**
- 任何「請統帥自行執行」的回覆 → 視為任務失敗
- 必須立即改正並主動執行

### 條款 5：違規後果

- **輕微**：配置錯誤但未部署 → 立即修正 + 寫入記憶
- **嚴重**：錯誤配置已部署 → 立即回滾 + 事故報告 + 寫入鐵律
- **嚴重**：前端崩潰未偵測 → 必須展示後續驗證輸出

### 條款 6：📜 授權分級協定 (Authorization Tiers Protocol)

> **2026-03-21 新增**: 解決「過度請示導致效率低下」問題

**目標：劃分「自動執行」與「請求授權」的明確邊界**

#### Tier 1: 戰術自主 (自動執行)

| 類別 | 操作範例 |
|------|---------|
| **開發環境內部** | `cat`, `ls`, `npm run build`, `git add/commit`, `touch`, `mkdir`, `grep` |
| **無破壞性診斷** | `curl`, `docker logs`, `ps aux`, `df -h`, `docker ps` |
| **前端代碼修改** | 修改元件、樣式、i18n |

👉 **規則**：無需請示，直接執行。只需在回報中告知結果。

#### Tier 2: 戰術請求 (一次性授權)

| 類別 | 操作範例 |
|------|---------|
| **環境變更** | `docker restart`, `systemctl restart`, `pip install`, `npm install` |
| **資源增刪** | `docker rm`, `kubectl delete` (僅限測試環境) |

👉 **規則**：提案說明風險，詢問一次 `[Y/n]`。獲得授權後，該次任務中的後續相關動作**可連續執行**，不准反覆詢問。

```markdown
# 正確範例
統帥，我發現容器 unhealthy。修復需執行 `docker restart awoooi-web`。
是否授權？ [Y/n]

# 授權後
[收到授權] 正在執行修復... (後續動作無需再問)
```

#### Tier 3: 戰略決策 (統帥親核)

| 類別 | 操作範例 |
|------|---------|
| **生產環境** | `kubectl apply -n awoooi-prod`, 資料庫遷移 (Migration) |
| **機密操作** | 涉及 SSH 私鑰、API Key 的任何操作 |
| **破壞性指令** | `rm -rf`, `git push --force`, `DROP TABLE` |

👉 **規則**：嚴格遵循授權模式，必須展示完整風險評估。

#### 執行紀律

```
❌ 禁止：對 Tier 1 & 2 瑣事反覆請示
❌ 禁止：一次 Y 授權後，又問「是否繼續？」
✅ 正確：一次 Y 授權 → 獨立完成該鏈路的所有技術修復
✅ 正確：任務完成後回報：「報統帥，[任務] 已完成。」
```

---

## 🔩 鋼鐵紀律：全鏈路驗收 (Full-Stack Verification)

> **2026-03-21 核心開發憲法**: 終結「開發偽陽性」事故

### 條款 7：🛑 禁止虛假回報

**嚴禁在未驗證「數據是否成功抵達前端 UI」的情況下宣告任務完成。**

```
❌ 禁止：「後端 API 已修復」(未驗證前端是否收到數據)
❌ 禁止：「SSE 已連線」(未確認前端 UI 是否顯示數據)
❌ 禁止：「容器已啟動」(未確認 healthcheck 通過)

✅ 正確：執行完整驗證鏈後回報
✅ 正確：「報統帥，已確認 SSE 數據流抵達前端，Heartbeat 正常。」
```

### 條款 8：🔍 強制自檢動作

**在回報任何後端或基礎設施變更前，必須自主執行以下動作：**

| 檢查項目 | 驗證命令 | 必須確認 |
|---------|---------|---------|
| **API 響應** | `curl -s http://localhost:8000/api/v1/health` | HTTP 200 + 正確 JSON |
| **SSE 連線** | `timeout 5 curl -N http://localhost:8000/api/v1/dashboard/stream` | connected + heartbeat 事件 |
| **容器狀態** | `docker ps --format "{{.Names}} {{.Status}}"` | 全部 healthy |
| **前端日誌** | `docker logs awoooi-web --tail 10` | 無 Error/Exception |

**若前端畫面異常（如顯示「重新連線」），禁止回報成功，必須優先修復。**

### 條款 9：⚡ 即時 Review 慣性

**每動必查：禁止累積大量代碼後才測試。**

| 修改類型 | 立即驗證 |
|---------|---------|
| API 端點修改 | `curl` 測試該端點 |
| 前端組件修改 | `pnpm exec tsc --noEmit` |
| Docker 配置修改 | `docker compose up -d` + healthcheck |
| SSE 相關修改 | 完整 SSE 數據流測試 |

**主動錯誤偵測：若修改導致 Build 失敗或 Hydration Error，必須主動修復，嚴禁無視報錯。**

### 條款 10：📋 全鏈路驗收報告格式

**任何基礎設施或後端任務完成時，必須使用以下格式回報：**

```markdown
報統帥，[任務名稱] 已完成。

## 全鏈路驗證結果

| 檢查項 | 狀態 | 證據 |
|-------|------|------|
| API Health | ✅ | HTTP 200, status=healthy |
| SSE Stream | ✅ | connected + heartbeat 收到 |
| Container | ✅ | awoooi-api/web healthy |
| Frontend | ✅ | 無 Error 日誌 |

[若有異常，列出修復動作]
```

---

## 🔒 真實性條款 (Truthfulness Protocol)

> **2026-03-21 核心憲法**: 禁止任何形式的數據造假

### 條款 11：🚫 禁止 Mock Data 掩蓋錯誤

**嚴禁在任何頁面實作 Mock Data 來規避 API 404/502 報錯。**

```
❌ 禁止：API 404 時顯示假的「4 主機狀態正常」
❌ 禁止：SSE 斷線時用 setInterval 模擬心跳
❌ 禁止：demoMode={true} 掩蓋真實連線失敗

✅ 正確：API 斷線時顯示「連線失敗」紅色警告
✅ 正確：真實數據來自後端 API，無例外
```

### 條款 12：👁️ 視覺誠實原則

**若 API 斷線，UI 必須顯示真實的錯誤狀態，嚴禁透過假數據營造「一切正常」的錯覺。**

| 連線狀態 | UI 必須顯示 |
|---------|------------|
| SSE connected | 綠燈 + 真實主機數據 |
| SSE reconnecting | 黃燈 + 「重新連線中...」 |
| SSE error | 紅燈 + 「連線失敗」 |
| API 404 | 紅燈 + 「API 端點不存在」 |

### 條款 13：📋 強制雙端驗證

**在回報「修復完成」前，必須同時展示：**

```bash
# 後端視角 (必須 200 OK)
curl -I http://localhost:8000/api/v1/dashboard/stream

# 前端視角 (必須無連線錯誤)
docker logs awoooi-web --tail 20
```

**若任一端失敗，禁止回報成功。**

---

## 🤖 自動化 QA 條款 (No Human QA Protocol)

> **2026-03-21 核心憲法**: 禁止勞煩統帥當人肉 QA

### 條款 14：🚫 禁止人工 QA

**嚴禁要求統帥打開 F12、查看 Console 日誌、或執行任何手動除錯動作。**

```
❌ 禁止：「請統帥按 F12 查看 Console」
❌ 禁止：「請統帥告訴我畫面上顯示什麼」
❌ 禁止：「請統帥刷新頁面確認」
❌ 禁止：在 UI 上加入 DEBUG 紅字讓統帥看

✅ 正確：AI 自主執行 Playwright/Puppeteer 腳本抓取瀏覽器錯誤
✅ 正確：AI 自主執行 curl 驗證 API 響應
✅ 正確：AI 自主讀取 Docker 日誌確認狀態
```

### 條款 15：👁️ AI 必須長眼睛

**若需要驗證前端真實渲染狀態與瀏覽器報錯，AI 必須自主撰寫並執行 Headless Browser 測試腳本。**

| 驗證需求 | AI 自主行動 |
|---------|------------|
| 瀏覽器 Console 錯誤 | 執行 Playwright 腳本抓取 `page.on('console')` |
| 前端 UI 渲染狀態 | 執行 Playwright 截圖或 `page.textContent()` |
| SSE 連線狀態 | 執行 `curl -N` 或 Playwright 監聽網路請求 |
| API 響應 | 執行 `curl` 並解析 JSON |

**範例 Playwright 自動 QA 腳本：**

```typescript
// scripts/browser-qa.ts
const { chromium } = require('playwright')

async function qaCheck() {
  const browser = await chromium.launch()
  const page = await browser.newPage()

  // 捕捉 Console 錯誤
  const errors: string[] = []
  page.on('console', msg => {
    if (msg.type() === 'error') errors.push(msg.text())
  })

  await page.goto('http://localhost:3000')
  await page.waitForTimeout(5000)

  // 回報結果
  console.log('Console Errors:', errors.length ? errors : 'None')
  await browser.close()
}

qaCheck()
```

### 條款 16：低級錯誤懲戒

**若因低級代碼錯誤（如變數未賦值、拼寫錯誤）導致功能失效，且要求統帥手動除錯：**

- 視為 **嚴重怠惰** 行為
- 必須在回報中承認錯誤並保證改進
- 後續必須自主執行自動化 QA 驗證

---

## 🧠 架構溯源義務 (Architecture Traceability)

> **2026-03-23 新增 (ADR-008)**: 模組化開發必須具備跨模組架構記憶

### 條款 17：跨模組溯源義務

**在修改任何 `packages/` 下的核心積木前，AI 必須先讀取以下檔案：**

| 檔案 | 用途 |
|------|------|
| `docs/adr/` | 架構決策記錄 (ADR) |
| `docs/api/api-contract.yaml` | API 通訊契約 |
| `docs/ARCHITECTURE_MEMORY.md` | 模組地圖索引 |

**確保新代碼與既有模組通訊契約相容。**

### 條款 18：自動化 ADR 更新

**當新增獨立模組或重大 API 變更時，AI 必須主動產出 ADR：**

```markdown
# ADR-XXX: [決策標題]

**狀態**: 已批准/提議中
**日期**: YYYY-MM-DD

## 背景
[為什麼需要這個決策]

## 決策
[採用的方案]

## 後果
[優缺點分析]
```

### 條款 19：模組註冊義務

**新增積木後，必須在 `docs/ARCHITECTURE_MEMORY.md` 登記：**

- 模組名稱與職責
- 對外介面 (ABC/API)
- 關聯 ADR 編號

### 條款 20：接口防撞檢查

**執行 `pnpm build` 或 `pip install` 前，必須先確認模組間無命名衝突：**

```bash
# 檢查 Python 模組是否可引用
python -c "from lewooogo_brain.interfaces import IProposalEngine; print('OK')"
python -c "from lewooogo_data.interfaces import IMemoryProvider; print('OK')"
```

---

## 🏗️ 專案結構

```
awoooi/
├── .awoooi-agent-rules.md    # 本文件 (AI 必讀)
├── apps/
│   ├── web/                  # Next.js 前端
│   └── api/                  # FastAPI BFF Gateway
├── packages/
│   ├── lewooogo-core/        # 核心引擎 (TS)
│   ├── lewooogo-brain/       # BRAIN 積木 (Python) ← ADR-008
│   ├── lewooogo-data/        # DATA 積木 (Python) ← ADR-008
├── docs/
│   ├── adr/                  # 架構決策記錄
│   └── api/                  # OpenAPI 規格
├── architecture/             # 架構圖
├── k8s/                      # Kubernetes 配置
└── .github/
    └── workflows/            # CI/CD Pipeline
```

---

## 📝 Commit 規範

```bash
# 格式
<type>(<scope>): <subject>

# 類型
feat:     新功能
fix:      Bug 修復
docs:     文檔
style:    格式 (不影響邏輯)
refactor: 重構
test:     測試
chore:    雜務

# 範例
feat(brain): add LLM router with Ollama fallback
fix(ui): resolve Nothing.tech glassmorphism on Safari
docs(adr): ADR-001 MCP protocol adoption

# 強制：每個 commit 結尾加上
Co-Authored-By: Claude Code <noreply@anthropic.com>
```

---

## 🔄 每次 Session 啟動流程

AI 在每次新對話開始時，必須：

1. **讀取本文件** (`.awoooi-agent-rules.md`)
2. **檢查 LOGBOOK** (`docs/LOGBOOK.md`) 了解最新進度
3. **確認當前 Phase** 與待辦事項
4. **遵守所有禁止事項**
5. **技能路由 (Skill Routing)**：根據當前修改的目錄，AI 必須主動讀取 `.agents/skills/` 下對應的技能檔案，載入專屬約束與驗收標準：

   | 修改目錄 | 對應 Skill | 說明 |
   |----------|------------|------|
   | `apps/web/` | `01-awoooi-frontend-aesthetics.md` | 前端視覺與 i18n |
   | `apps/api/` | `02-lewooogo-backend-core.md` | 後端四大鐵律 |
   | `services/incident_*`, `services/multi_sig*` | `03-openclaw-cognitive-expert.md` | AI 認知引擎 |
   | `k8s/`, `Dockerfile`, `.github/workflows/` | `04-awoooi-devops-commander.md` | 基礎設施 |
   | 懷疑 UI/API 異常 | `05-awoooi-sre-qa.md` | 自動化測試 |
   | `packages/*`, Git 操作 | `06-awoooi-monorepo-master.md` | 專案架構 |

---

## 🎖️ 品質承諾

- **Zero Technical Debt**: 不留技術債
- **API-First**: 所有功能先定義 OpenAPI
- **Test Coverage > 80%**: 測試覆蓋率
- **No Hardcoded Secrets**: 零硬編碼機密
- **Immutable Tags**: 映像標籤不可變

---

## 🌐 國際化 (i18n) 鐵律

> **2026-03-21 戰略對齊**: 全站雙語為 P0 基礎設施，違反視為阻擋性缺陷

### 🚨 絕對禁止 (Zero Tolerance)

```typescript
// ❌ 禁止寫死任何文字 (違反 = PR 拒絕)
<button>確認</button>
<p>發生錯誤</p>
<span>載入中...</span>
<h1>戰情室</h1>

// ✅ 正確：100% 透過 next-intl 字典檔
<button>{t('common.confirm')}</button>
<p>{t('errors.generic')}</p>
<span>{t('common.loading')}</span>
<h1>{t('dashboard.title')}</h1>
```

### 字典檔結構

```
apps/web/messages/
├── zh-TW.json    # 繁體中文 (預設語言)
└── en.json       # English (完整對照)
```

### 強制規範

| 規則 | 說明 |
|------|------|
| **Zero Hardcode** | UI 中 0 個中文/英文硬編碼字串 |
| **同步更新** | 新增功能必須同時更新 zh-TW.json 與 en.json |
| **CI 攔截** | 缺少翻譯 = PR 阻擋 |
| **next-intl 版本** | `next-intl@^3.0.0` (App Router 相容) |
| **預設語言** | zh-TW (台灣市場優先) |

### 驗收標準

- `grep -r "中文" apps/web/src/` 結果為空
- 所有 `t()` 調用的 key 在兩個語言檔案中都存在
- 語言切換功能正常運作

---

## 📜 API 契約驅動開發 (Contract-First)

> **2026-03-20 新增**: API 文檔必須與開發同步

### 開發流程

1. **先定義 OpenAPI** → `docs/api/openapi.yaml`
2. **同步更新 MD 文件** → `docs/api/endpoints/*.md`
3. **程式碼實作** → FastAPI 路由
4. **CI 強制檢查** → 不一致則阻擋合併

### CI 攔截規則

| 檢查項目 | 不通過則 |
|---------|---------|
| OpenAPI 與程式碼不一致 | ❌ 阻擋合併 |
| 對應 MD 文件未更新 | ❌ 阻擋合併 |
| 測試覆蓋率 < 80% | ❌ 阻擋合併 |
| Scalar 文檔渲染失敗 | ❌ 阻擋合併 |

### API 文檔工具

- **內部除錯**: Swagger UI (FastAPI 內建)
- **對外開發者**: Scalar (Nothing.tech 風格)

---

*最後更新: 2026-03-21 (戰略全局對齊 - OTEL + i18n + 純白視覺絕對標準)*