From c66b4dfb22720aee57ef048bca5005033d172bb6 Mon Sep 17 00:00:00 2001 From: OG T Date: Mon, 23 Mar 2026 00:20:51 +0800 Subject: [PATCH] feat(agents): implement 6 core Claude skills for auto-pilot validation Skills created: - 01-awoooi-frontend-aesthetics.md: Nothing.tech visual standards + i18n - 02-lewooogo-backend-core.md: FastAPI four iron laws + OTEL - 03-openclaw-cognitive-expert.md: Incident Engine + Multi-Sig + Redis - 04-awoooi-devops-commander.md: K3s + Docker + Tier 1-3 authorization - 05-awoooi-sre-qa.md: Playwright + automated QA (no human testing) - 06-awoooi-monorepo-master.md: Git + dependencies + LOGBOOK updates Added skill routing to .awoooi-agent-rules.md Session startup flow. Co-Authored-By: Claude Opus 4.5 --- .../skills/01-awoooi-frontend-aesthetics.md | 89 ++ .agents/skills/02-lewooogo-backend-core.md | 135 +++ .../skills/03-openclaw-cognitive-expert.md | 136 +++ .agents/skills/04-awoooi-devops-commander.md | 142 ++++ .agents/skills/05-awoooi-sre-qa.md | 180 ++++ .agents/skills/06-awoooi-monorepo-master.md | 182 ++++ .awoooi-agent-rules.md | 774 +++++++++++++++++- 7 files changed, 1623 insertions(+), 15 deletions(-) create mode 100644 .agents/skills/01-awoooi-frontend-aesthetics.md create mode 100644 .agents/skills/02-lewooogo-backend-core.md create mode 100644 .agents/skills/03-openclaw-cognitive-expert.md create mode 100644 .agents/skills/04-awoooi-devops-commander.md create mode 100644 .agents/skills/05-awoooi-sre-qa.md create mode 100644 .agents/skills/06-awoooi-monorepo-master.md diff --git a/.agents/skills/01-awoooi-frontend-aesthetics.md b/.agents/skills/01-awoooi-frontend-aesthetics.md new file mode 100644 index 00000000..f2d82505 --- /dev/null +++ b/.agents/skills/01-awoooi-frontend-aesthetics.md @@ -0,0 +1,89 @@ +# Skill 01: AWOOOI Frontend Aesthetics +# 前端視覺主權守護者 + +> **管轄範圍**: `apps/web/` (Next.js, Zustand, Tailwind) +> **觸發條件**: 任何 `.tsx`, `.ts`, `.css` 檔案修改 + +--- + +## 核心約束 (Iron Laws) + +### 1. Nothing.tech 純白工業風 (絕對標準) + +| 元素 | 規範 | 違規處置 | +|------|------|----------| +| 背景 | `bg-white/70 backdrop-blur-[20px]` | 立即修正 | +| 字體 | `VT323` 點陣風格 | 禁止其他字體 | +| 發光色 | `#4A90D9` (Glacier Blue) | 唯一許可強調色 | +| 陰影 | `shadow-lg/20` 白玻璃效果 | 禁止深色陰影 | + +### 2. i18n 零容忍硬編碼 + +```typescript +// ❌ 絕對禁止 +確認執行 + +// ✅ 唯一許可 +{t('actions.confirm')} +``` + +- 所有 UI 文字必須透過 `next-intl` 的 `useTranslations()` +- 字典檔案位置: `apps/web/messages/{locale}.json` + +### 3. Zustand SSE 狀態管理 + +```typescript +// ✅ 正確模式 +const buffer = useSSEStore((s) => s.buffer); +const appendChunk = useSSEStore((s) => s.appendChunk); + +// ❌ 禁止模式 +useState() // 管理 SSE 串流狀態 +``` + +### 4. 禁止 Mock Data 掩蓋錯誤 + +- 所有 API 調用必須處理真實回應 +- 無數據時顯示 `"--"` 或空狀態組件 +- 禁止使用假數據填充 UI + +--- + +## 強制驗收程序 (Mandatory Validation) + +### 修改任何 `.tsx` 後必須執行: + +```bash +# Step 1: TypeScript 靜態檢查 +cd apps/web && pnpm exec tsc --noEmit + +# Step 2: 生產建置測試 +pnpm run build + +# Step 3: Hydration 錯誤檢測 (如有疑慮) +pnpm run dev & sleep 5 && curl -s http://localhost:3000 | grep -i "hydration" +``` + +### 驗收標準 + +| 檢查項目 | 通過條件 | +|----------|----------| +| tsc --noEmit | Exit code 0, 無錯誤 | +| pnpm build | 成功完成, 無警告 | +| Hydration | 無 "Hydration mismatch" 錯誤 | + +--- + +## 常見陷阱 (Known Pitfalls) + +1. **SSR vs Client State**: 使用 `useEffect` 包裝瀏覽器專屬 API +2. **apiBaseUrl 空值**: 確保 `NEXT_PUBLIC_API_URL` 在 build-time 注入 +3. **Tailwind Purge**: 動態類名需完整拼寫，禁止字串拼接 + +--- + +## 參考文檔 + +- ADR-002: Nothing.tech 設計系統 +- `apps/web/tailwind.config.ts`: 顏色定義 +- `apps/web/src/components/ui/`: 原子組件庫 diff --git a/.agents/skills/02-lewooogo-backend-core.md b/.agents/skills/02-lewooogo-backend-core.md new file mode 100644 index 00000000..fd15f476 --- /dev/null +++ b/.agents/skills/02-lewooogo-backend-core.md @@ -0,0 +1,135 @@ +# Skill 02: leWOOOgo Backend Core +# 後端核心引擎守護者 + +> **管轄範圍**: `apps/api/` (FastAPI, Python) +> **觸發條件**: 任何 `.py` 檔案修改 + +--- + +## 核心約束 (Four Iron Laws) + +### 1. Async-First (非同步優先) + +```python +# ✅ 正確 +async def get_health() -> HealthResponse: + result = await check_services() + return result + +# ❌ 禁止 +def get_health() -> HealthResponse: # 同步函數 + result = check_services() + return result +``` + +### 2. CORS 白名單鎖定 (無 Wildcard) + +```python +# ✅ 正確 (config.py) +CORS_ORIGINS: list[str] = [ + "https://awoooi.wooo.work", + "http://localhost:3000", +] + +# ❌ 絕對禁止 +CORS_ORIGINS = ["*"] +``` + +### 3. Pydantic 強型別驗證 + +```python +# ✅ 正確 +class SignalPayload(BaseModel): + source: str + severity: Literal["P0", "P1", "P2", "P3"] + message: str + +# ❌ 禁止 +def process_signal(data: dict): # 無型別驗證 + pass +``` + +### 4. structlog 結構化日誌 + +```python +# ✅ 正確 +import structlog +logger = structlog.get_logger() +logger.info("signal_processed", signal_id=signal.id, severity=signal.severity) + +# ❌ 禁止 +print(f"Signal {signal.id} processed") +import logging # 原生 logging +``` + +--- + +## OTEL 可觀測性 (P0 核心) + +### 強制注入追蹤 + +```python +# 所有 API 請求必須自動產生 traces +# 目標端點: http://192.168.0.188:24317 (SigNoz OTEL Collector) + +# 環境變數 (必須設定) +OTEL_ENABLED=true +OTEL_EXPORTER_OTLP_ENDPOINT=http://192.168.0.188:24317 +OTEL_SERVICE_NAME=awoooi-api +``` + +--- + +## 機密管理 (嚴禁硬編碼) + +```python +# ✅ 正確 (從環境變數讀取) +settings.GEMINI_API_KEY +settings.CLAUDE_API_KEY +settings.WEBHOOK_HMAC_SECRET + +# ❌ 絕對禁止 +API_KEY = "sk-xxx..." # 硬編碼機密 +``` + +--- + +## 強制驗收程序 (Mandatory Validation) + +### 修改任何 `.py` 後必須執行: + +```bash +# Step 1: 語法檢查 +cd apps/api && python -m py_compile src/core/config.py + +# Step 2: 本地啟動測試 (MOCK_MODE) +docker run --rm -e MOCK_MODE=true -p 8888:8000 awoooi-api-test + +# Step 3: Health Check +curl -sf http://localhost:8888/api/v1/health +``` + +### 驗收標準 + +| 檢查項目 | 通過條件 | +|----------|----------| +| py_compile | 無 SyntaxError | +| Docker Run | Application startup complete | +| Health API | HTTP 200, status: healthy/degraded | + +--- + +## 常見陷阱 (Known Pitfalls) + +1. **Pydantic v2 Field 命名**: 禁止底線開頭 (`_field_name`) +2. **JSON Array 環境變數**: ConfigMap 中使用 `'["a","b"]'` 格式 +3. **httpx 超時**: 預設 90 秒，長時間 AI 調用需調整 + +--- + +## 參考文檔 + +- `apps/api/src/core/config.py`: 設定中心 +- `apps/api/src/main.py`: FastAPI 應用入口 +- ADR-005: BFF 閘道架構 +- ADR-006: AI 備援策略 diff --git a/.agents/skills/03-openclaw-cognitive-expert.md b/.agents/skills/03-openclaw-cognitive-expert.md new file mode 100644 index 00000000..53ff9fb6 --- /dev/null +++ b/.agents/skills/03-openclaw-cognitive-expert.md @@ -0,0 +1,136 @@ +# Skill 03: OpenClaw Cognitive Expert +# AI 認知引擎專家 + +> **管轄範圍**: Incident Engine, GraphRAG, Multi-Sig, Event Bus +> **觸發條件**: 修改 `services/incident_*.py`, `services/multi_sig*.py`, `services/graph*.py` + +--- + +## 核心架構 (三層記憶系統) + +### 1. Working Memory (Redis Hash) +``` +位置: 192.168.0.188:6380/10 +用途: 活動中 Incident 狀態 (TTL 7天) +Key: incident:{incident_id} +``` + +### 2. Episodic Memory (PostgreSQL/SQLite) +``` +位置: 192.168.0.188:5432 (Prod) / awoooi.db (Dev) +用途: 長期歷史記錄 +Table: incident_records +``` + +### 3. Event Bus (Redis Streams) +``` +Stream: stream:awoooi_signals +Group: awoooi_workers +用途: 告警信號傳遞 +``` + +--- + +## 核心約束 (Cognitive Iron Laws) + +### 1. 雙層記憶同步 + +```python +# ✅ 正確 (必須同時寫入) +async def create_incident(incident: Incident): + # 1. Working Memory (即時狀態) + await redis_client.hset(f"incident:{incident.id}", mapping=incident.to_redis()) + + # 2. Episodic Memory (持久化) + await db.execute(insert(IncidentRecord).values(**incident.to_db())) + +# ❌ 禁止 (單層寫入) +await redis_client.hset(...) # 只寫 Redis，遺漏 DB +``` + +### 2. LLM 調用必須走快取 + +```python +# ✅ 正確 +async def analyze_with_ai(context: str) -> str: + cache_key = f"ai_response:{hash(context)}" + cached = await redis_client.get(cache_key) + if cached: + return cached + + response = await _call_ollama(context) + await redis_client.setex(cache_key, 3600, response) + return response + +# ❌ 禁止 (無快取直接調用) +response = await _call_ollama(context) +``` + +### 3. Multi-Sig 動作必須 Dry-Run + +```python +# ✅ 正確 (先模擬，後執行) +async def execute_k8s_action(action: K8sAction) -> ExecutionResult: + # Step 1: Dry-Run 驗證 + dry_result = await k8s_executor.execute(action, dry_run=True) + if not dry_result.success: + raise ValidationError(dry_result.error) + + # Step 2: 等待 Multi-Sig 簽核 + approval = await wait_for_approval(action.approval_id) + + # Step 3: 真實執行 + return await k8s_executor.execute(action, dry_run=False) + +# ❌ 禁止 (跳過 dry_run) +return await k8s_executor.execute(action, dry_run=False) +``` + +--- + +## Event Bus 規範 + +### Signal Producer (告警輸入) + +```python +# Webhook 接收告警 → XADD 至 Stream +await redis_client.xadd( + "stream:awoooi_signals", + {"payload": json.dumps(signal.model_dump())}, + maxlen=10000, # 告警風暴防護 +) +``` + +### Signal Consumer (Worker) + +```python +# XREADGROUP 消費 → ACK 確認 +messages = await redis_client.xreadgroup( + groupname="awoooi_workers", + consumername=consumer_id, + streams={"stream:awoooi_signals": ">"}, + count=10, + block=5000, +) +# 處理後必須 ACK +await redis_client.xack("stream:awoooi_signals", "awoooi_workers", message_id) +``` + +--- + +## Incident Engine 聚合規則 + +| 參數 | 值 | 說明 | +|------|-----|------| +| 時間窗口 | 30 分鐘 | 相近告警聚合 | +| 相似度閾值 | 0.7 | 文字相似度門檻 | +| 升級規則 | 3 筆 P2 → P0 | 自動提升 Severity | + +--- + +## 參考文檔 + +- `apps/api/src/services/incident_engine.py`: 聚合引擎 +- `apps/api/src/services/multi_sig_redis.py`: 分散式狀態 +- `apps/api/src/workers/signal_worker.py`: Event Bus 消費者 +- Phase 6.0-6.3: 認知覺醒計畫 diff --git a/.agents/skills/04-awoooi-devops-commander.md b/.agents/skills/04-awoooi-devops-commander.md new file mode 100644 index 00000000..e18f39f9 --- /dev/null +++ b/.agents/skills/04-awoooi-devops-commander.md @@ -0,0 +1,142 @@ +# Skill 04: AWOOOI DevOps Commander +# 基礎設施指揮官 + +> **管轄範圍**: Docker, K3s, Nginx, NetworkPolicy, CI/CD +> **觸發條件**: 修改 `k8s/`, `Dockerfile`, `.github/workflows/`, `nginx` + +--- + +## 四主機架構 (絕對邊界) + +| 主機 | IP | 角色 | 部署內容 | +|------|-----|------|----------| +| DevOps | 192.168.0.110 | 金庫 | Harbor Registry, GitHub Runner | +| Security | 192.168.0.112 | 安全 | Kali Scanner | +| K3s Master | 192.168.0.120 | 叢集 | K3s Control Plane | +| K3s Worker | 192.168.0.121 | 叢集 | K3s Worker Node | +| AI/Web | 192.168.0.188 | 大腦 | Nginx, PostgreSQL, Redis, Ollama, SigNoz | + +### 絕對禁令 + +``` +❌ 禁止在 .188 以外部署決策 AI (OpenClaw, Ollama) +❌ 禁止 K3s 直接訪問公網 (必須透過 .188 Nginx) +❌ 禁止繞過 NetworkPolicy 直連 Pod +``` + +--- + +## 授權分級機制 (Tier 1~3) + +### Tier 1: 自主執行 (無需詢問) + +| 動作 | 範例 | +|------|------| +| 查看日誌 | `kubectl logs deployment/...` | +| 檢查狀態 | `kubectl get pods`, `docker ps` | +| 語法檢查 | `tsc --noEmit`, `python -m py_compile` | +| 本地建置 | `docker build`, `pnpm build` | + +### Tier 2: 提案確認 (Y/n 詢問) + +| 動作 | 範例 | +|------|------| +| 重啟服務 | `kubectl rollout restart` | +| 套用配置 | `kubectl apply -f` | +| Git Push | `git push origin main` | +| Nginx Reload | `nginx -s reload` | + +### Tier 3: 統帥親核 (必須等待明確授權) + +| 動作 | 範例 | +|------|------| +| 刪除資源 | `kubectl delete`, `docker rm -f` | +| 機密操作 | 修改 K8s Secrets, .env 檔案 | +| 生產資料庫 | DROP TABLE, TRUNCATE | +| 強制推送 | `git push --force` | + +--- + +## K3s 部署規範 + +### Image Tag 規則 + +```yaml +# ✅ 正確 (精確版本) +image: 192.168.0.110:5000/library/api:a2f7d12-23406265221 + +# ❌ 絕對禁止 +image: 192.168.0.110:5000/library/api:latest +``` + +### NodePort 分配 + +| 服務 | NodePort | 說明 | +|------|----------|------| +| awoooi-api | 32334 | FastAPI Backend | +| awoooi-web | 32335 | Next.js Frontend | + +### NetworkPolicy 核心原則 + +```yaml +# Default Deny All (零信任) +spec: + podSelector: {} + policyTypes: + - Ingress + - Egress + +# 白名單許可 +# - 192.168.0.188/32 (Nginx Gateway) +# - 192.168.0.120/32, 192.168.0.121/32 (K3s Nodes, for NodePort SNAT) +# - 10.42.0.0/16 (K3s Pod CIDR) +``` + +--- + +## CI/CD 規範 + +### GitHub Actions 鐵律 + +```yaml +# 必須使用 self-hosted runner +runs-on: [self-hosted, harbor, k8s] + +# 禁止跳過 hooks +# ❌ --no-verify +# ❌ --no-gpg-sign +``` + +### Telegram 通報 (閉環) + +```bash +# 部署完成必須通報 +curl -s -X POST "https://api.telegram.org/bot${TOKEN}/sendMessage" \ + -d chat_id="${CHAT_ID}" \ + -d text="${EMOJI} AWOOOI ${STATUS}" +``` + +--- + +## 強制驗收程序 + +### 修改 K8s YAML 後: + +```bash +# Step 1: 語法驗證 +kubectl apply -f k8s/awoooi-prod/*.yaml --dry-run=client + +# Step 2: 套用配置 +kubectl apply -f k8s/awoooi-prod/*.yaml + +# Step 3: 驗證 Rollout +kubectl rollout status deployment/awoooi-api -n awoooi-prod +``` + +--- + +## 參考文檔 + +- `k8s/awoooi-prod/`: K8s Manifests +- `.github/workflows/deploy-prod.yml`: CI/CD Pipeline +- `reference_four_hosts.md`: 主機架構參考 diff --git a/.agents/skills/05-awoooi-sre-qa.md b/.agents/skills/05-awoooi-sre-qa.md new file mode 100644 index 00000000..6681fc4f --- /dev/null +++ b/.agents/skills/05-awoooi-sre-qa.md @@ -0,0 +1,180 @@ +# Skill 05: AWOOOI SRE & QA +# 可靠性工程與品質守護者 + +> **管轄範圍**: Playwright, API Testing, Health Monitoring +> **觸發條件**: 懷疑 UI 異常、API 錯誤、部署驗證 + +--- + +## 核心約束 (絕對禁止人工 QA) + +### 絕對禁止指令 + +``` +❌ "請統帥開啟瀏覽器檢查..." +❌ "請按 F12 查看 Console..." +❌ "請截圖回報錯誤..." +❌ "請手動測試以下步驟..." +``` + +### 正確做法 + +``` +✅ 自主撰寫 Playwright 腳本驗證 +✅ 自主執行 curl/httpx 測試 API +✅ 自主擷取 kubectl logs 分析錯誤 +✅ 自主產出驗證報告表格 +``` + +--- + +## Playwright 自動化規範 + +### 測試腳本結構 + +```typescript +// apps/web/tests/e2e/health-check.spec.ts +import { test, expect } from '@playwright/test'; + +test('健康檢查頁面無 Console Error', async ({ page }) => { + const errors: string[] = []; + + page.on('console', (msg) => { + if (msg.type() === 'error') { + errors.push(msg.text()); + } + }); + + await page.goto('/zh-TW'); + await page.waitForLoadState('networkidle'); + + expect(errors).toHaveLength(0); +}); +``` + +### 強制設定 (playwright.config.ts) + +```typescript +export default defineConfig({ + use: { + // ✅ 必須啟用截圖錄影 + screenshot: 'only-on-failure', + video: 'retain-on-failure', + trace: 'retain-on-failure', + }, + reporter: [ + ['html', { outputFolder: 'test-results/html' }], + ['json', { outputFile: 'test-results/results.json' }], + ], +}); +``` + +--- + +## API 測試規範 + +### Health Check 驗證腳本 + +```bash +#!/bin/bash +# scripts/verify-health.sh + +echo "=== AWOOOI 全鏈路健康檢查 ===" + +# API Health +API_STATUS=$(curl -skf https://awoooi.wooo.work/api/v1/health | jq -r '.status') +echo "API: $API_STATUS" + +# Web Frontend +WEB_STATUS=$(curl -skI https://awoooi.wooo.work/ | grep -c "HTTP/2 307") +echo "Web: $([ $WEB_STATUS -gt 0 ] && echo 'OK' || echo 'FAIL')" + +# CORS Header +CORS=$(curl -skI -H "Origin: https://awoooi.wooo.work" https://awoooi.wooo.work/api/v1/health | grep -i "access-control-allow-origin") +echo "CORS: $CORS" +``` + +### SSE 串流驗證 + +```javascript +// scripts/verify-sse.js +const EventSource = require('eventsource'); + +const es = new EventSource('https://awoooi.wooo.work/api/v1/dashboard/stream'); + +es.onmessage = (event) => { + console.log('✅ SSE Message:', JSON.parse(event.data)); + es.close(); + process.exit(0); +}; + +es.onerror = (err) => { + console.error('❌ SSE Error:', err); + process.exit(1); +}; + +setTimeout(() => { + console.error('❌ SSE Timeout'); + process.exit(1); +}, 10000); +``` + +--- + +## 雙端驗證報告格式 (強制) + +### 回報統帥時必須附帶此表格: + +```markdown +## 雙端驗證報告 + +| 項目 | 前端 | 後端 | 結果 | +|------|------|------|------| +| HTTP Status | 200 | 200 | ✅ | +| CORS Header | ✅ | ✅ | ✅ | +| Console Error | 0 | N/A | ✅ | +| Response Time | 120ms | 65ms | ✅ | +| SSL Certificate | Valid | N/A | ✅ | +``` + +--- + +## 常見診斷流程 + +### 1. UI 渲染異常 + +```bash +# Step 1: Headless 截圖 +cd apps/web && pnpm exec playwright screenshot https://awoooi.wooo.work /tmp/screenshot.png + +# Step 2: Console Error 擷取 +pnpm exec playwright test tests/e2e/console-check.spec.ts +``` + +### 2. API 502/503 錯誤 + +```bash +# Step 1: 檢查 Pod 狀態 +kubectl get pods -n awoooi-prod -o wide + +# Step 2: 擷取 Pod 日誌 +kubectl logs deployment/awoooi-api -n awoooi-prod --tail 50 + +# Step 3: 檢查 NodePort 連線 +curl -v http://192.168.0.120:32334/api/v1/health +``` + +### 3. CORS 錯誤 + +```bash +# 驗證 CORS Header +curl -vI -H "Origin: https://awoooi.wooo.work" https://awoooi.wooo.work/api/v1/health 2>&1 | grep -i "access-control" +``` + +--- + +## 參考文檔 + +- `apps/web/playwright.config.ts`: Playwright 設定 +- `apps/web/tests/`: E2E 測試腳本 +- `scripts/`: 自動化驗證腳本 diff --git a/.agents/skills/06-awoooi-monorepo-master.md b/.agents/skills/06-awoooi-monorepo-master.md new file mode 100644 index 00000000..41dce24a --- /dev/null +++ b/.agents/skills/06-awoooi-monorepo-master.md @@ -0,0 +1,182 @@ +# Skill 06: AWOOOI Monorepo Master +# 專案架構與版本守護者 + +> **管轄範圍**: `packages/*`, Git, Workspace, Dependencies +> **觸發條件**: 修改共用套件、Git 操作、依賴更新 + +--- + +## Monorepo 結構 + +``` +awoooi/ +├── apps/ +│ ├── api/ # FastAPI 後端 +│ └── web/ # Next.js 前端 +├── packages/ +│ ├── lewooogo-core/ # 核心共用邏輯 +│ ├── eslint-config/ # ESLint 共用配置 +│ └── tsconfig/ # TypeScript 共用配置 +├── k8s/ +│ └── awoooi-prod/ # K8s Manifests +├── .agents/ +│ └── skills/ # Claude Skills +└── docs/ # 文檔系統 +``` + +--- + +## 核心約束 (Monorepo Iron Laws) + +### 1. 絕對禁止 Import 舊專案 + +```typescript +// ❌ 絕對禁止 +import { something } from '../../../wooo-aiops/...' +import { legacy } from '@wooo-aiops/...' + +// ✅ 正確 (僅限 AWOOOI 內部) +import { something } from '@awoooi/lewooogo-core' +import { config } from '../core/config' +``` + +### 2. K8s Image Tag 禁止 latest + +```yaml +# ❌ 絕對禁止 +image: 192.168.0.110:5000/library/api:latest + +# ✅ 正確 (精確版本) +image: 192.168.0.110:5000/library/api:a2f7d12-23406265221 +# 格式: {git-sha}-{run-id} +``` + +### 3. 依賴版本鎖定 + +```json +// package.json - 禁止寬鬆版本 +{ + "dependencies": { + // ❌ 禁止 + "next": "^14.0.0", + "react": "*", + + // ✅ 正確 (精確版本) + "next": "14.2.29", + "react": "18.3.1" + } +} +``` + +--- + +## Git Commit 規範 + +### Commit Message 格式 + +``` +(): + +[optional body] + +Co-Authored-By: Claude Opus 4.5 +``` + +### Type 列表 + +| Type | 說明 | 範例 | +|------|------|------| +| feat | 新功能 | `feat(api): add incident aggregation` | +| fix | 修復 | `fix(web): resolve hydration mismatch` | +| refactor | 重構 | `refactor(core): extract redis client` | +| docs | 文檔 | `docs: update LOGBOOK.md` | +| chore | 雜項 | `chore: update dependencies` | +| test | 測試 | `test(api): add health endpoint tests` | + +### Scope 列表 + +| Scope | 對應目錄 | +|-------|----------| +| api | apps/api | +| web | apps/web | +| core | packages/lewooogo-core | +| k8s | k8s/ | +| ci | .github/workflows | +| agents | .agents/ | + +--- + +## LOGBOOK 更新規範 + +### 強制更新時機 + +| 事件 | 必須更新 | +|------|----------| +| Phase 完成 | ✅ | +| 重大修復 | ✅ | +| 架構變更 | ✅ | +| 部署成功 | ✅ | + +### 格式範例 + +```markdown +| 2026-03-23 00:30 | **🔧 Phase 8 NodePort 修復**: NetworkPolicy 新增 K3s Node IP 白名單，OTEL 端口修正 4317→24317 | CTO + Claude Code | +``` + +--- + +## 依賴管理 + +### pnpm Workspace 規範 + +```yaml +# pnpm-workspace.yaml +packages: + - 'apps/*' + - 'packages/*' +``` + +### 安裝依賴 + +```bash +# 根目錄安裝 (開發依賴) +pnpm add -D -w + +# 特定 app 安裝 +pnpm add --filter @awoooi/web + +# 共用套件安裝 +pnpm add --filter @awoooi/lewooogo-core +``` + +--- + +## 分支策略 + +| 分支 | 用途 | 保護 | +|------|------|------| +| main | 生產分支 | ✅ 禁止 force push | +| feature/* | 功能開發 | - | +| fix/* | 修復分支 | - | + +### PR 規範 + +```markdown +## Summary +- 簡述變更內容 + +## Test plan +- [ ] 本地測試通過 +- [ ] CI/CD 綠燈 + +🤖 Generated with Claude Code +``` + +--- + +## 參考文檔 + +- `turbo.json`: Turborepo 配置 +- `pnpm-workspace.yaml`: Workspace 定義 +- `DEPENDENCIES.md`: 依賴清單 +- `docs/LOGBOOK.md`: 進度追蹤 diff --git a/.awoooi-agent-rules.md b/.awoooi-agent-rules.md index f7fe1da1..9bd4dcd4 100644 --- a/.awoooi-agent-rules.md +++ b/.awoooi-agent-rules.md @@ -1,23 +1,48 @@ # AWOOOI - AI Agent 開發契約 (L1 System Prompt) -> **版本**: v1.0 -> **生效日期**: 2026-03-19 +> **版本**: 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) 是岑洋國際行銷有限公司的下一代智能運維平台。 +**AWOOOI** (AI + WOOO) 是岑洋國際行銷有限公司的**全新獨立 SaaS 智能運維平台**。 | 項目 | 說明 | |------|------| | **母品牌** | AWOOOI | | **技術引擎** | leWOOOgo Engine (樂高模組化) | | **視覺符號** | Data Pincer (數據鉗) | -| **設計風格** | Nothing.tech (點陣字體 + 毛玻璃 + 極簡) | -| **核心理念** | Agent-Centric (AI 主動發現 → 分析 → 建議 → 人類批准) | +| **設計風格** | Nothing.tech **純白工業風** (點陣紋理 + 白玻璃 + 高對比) | +| **核心理念** | AI-Infused (全站 AI Copilot，無所不在) | +| **語言支援** | 繁體中文 (zh-TW) + English (en) | --- @@ -61,6 +86,44 @@ 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 處理 | + --- ## ✅ 開發準則 @@ -90,25 +153,267 @@ const API_KEY = process.env.API_KEY | **Container** | Harbor Registry (192.168.0.110:5000) | | **Orchestration** | K3s (192.168.0.120/121) | -### Nothing.tech 設計規範 +### Nothing.tech 設計規範 (純白工業風 v2.0) + +> ⚠️ **2026-03-20 重大變更**: 從深色駭客風轉為純白工業風 ```css -/* 色彩 */ ---nothing-black: #000000; +/* 色彩系統 - 純白基底 */ --nothing-white: #FFFFFF; ---nothing-red: #D71921; /* 告警/錯誤 */ ---nothing-gray-100: #F5F5F5; ---nothing-gray-800: #1A1A1A; +--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-display: "NDot", monospace; /* AI 介面 (點陣風) */ --font-body: "Inter", system-ui; /* 一般文字 */ -/* 效果 */ +/* 效果 - 白玻璃 (非深色毛玻璃) */ --glass-blur: blur(20px); ---glass-bg: rgba(255, 255, 255, 0.05); +--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 思考狀態專用 | + +#### ClawBot 視覺規範 + +```tsx +// 機械爪面板 - 3D 骨架風格 +
+ {/* 核心 LED - 藍色脈衝 */} +
+ + {/* 點陣狀態文字 */} + + [AGENT] patrolling... + +
+``` + +#### 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' +
+ +
+ +// ❌ 禁止 - 依賴實體圖片 +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, **ClawBot: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 | ClawBot | 狀態 | +|------|----------|-----|---------|------| +| **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) + --- ## 📚 知識參考來源 @@ -125,6 +430,362 @@ AI 可跨資料夾讀取以下舊專案文檔 (唯讀)： --- +## 👁️ 首席架構師防禦性審查 (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 發送模擬告警 +- 觸發 ClawBot 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 驗證 + +--- + ## 🏗️ 專案結構 ``` @@ -186,6 +847,16 @@ AI 在每次新對話開始時，必須： 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` | 專案架構 | --- @@ -199,4 +870,77 @@ AI 在每次新對話開始時，必須： --- -*最後更新: 2026-03-19 (Phase 0 Day 1)* +## 🌐 國際化 (i18n) 鐵律 + +> **2026-03-21 戰略對齊**: 全站雙語為 P0 基礎設施，違反視為阻擋性缺陷 + +### 🚨 絕對禁止 (Zero Tolerance) + +```typescript +// ❌ 禁止寫死任何文字 (違反 = PR 拒絕) + +

發生錯誤

+載入中... +

戰情室

+ +// ✅ 正確：100% 透過 next-intl 字典檔 + +

{t('errors.generic')}

+{t('common.loading')} +

{t('dashboard.title')}

+``` + +### 字典檔結構 + +``` +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 + 純白視覺絕對標準)*