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 <noreply@anthropic.com>
This commit is contained in:
OG T
89
.agents/skills/01-awoooi-frontend-aesthetics.md
Normal file
89
.agents/skills/01-awoooi-frontend-aesthetics.md
Normal file
@@ -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
|
||||
// ❌ 絕對禁止
|
||||
<span>確認執行</span>
|
||||
|
||||
// ✅ 唯一許可
|
||||
<span>{t('actions.confirm')}</span>
|
||||
```
|
||||
|
||||
- 所有 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/`: 原子組件庫
|
||||
135
.agents/skills/02-lewooogo-backend-core.md
Normal file
135
.agents/skills/02-lewooogo-backend-core.md
Normal file
@@ -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 備援策略
|
||||
136
.agents/skills/03-openclaw-cognitive-expert.md
Normal file
136
.agents/skills/03-openclaw-cognitive-expert.md
Normal file
@@ -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: 認知覺醒計畫
|
||||
142
.agents/skills/04-awoooi-devops-commander.md
Normal file
142
.agents/skills/04-awoooi-devops-commander.md
Normal file
@@ -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`: 主機架構參考
|
||||
180
.agents/skills/05-awoooi-sre-qa.md
Normal file
180
.agents/skills/05-awoooi-sre-qa.md
Normal file
@@ -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/`: 自動化驗證腳本
|
||||
182
.agents/skills/06-awoooi-monorepo-master.md
Normal file
182
.agents/skills/06-awoooi-monorepo-master.md
Normal file
@@ -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 格式
|
||||
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
[optional body]
|
||||
|
||||
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
||||
```
|
||||
|
||||
### 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 <package>
|
||||
|
||||
# 特定 app 安裝
|
||||
pnpm add <package> --filter @awoooi/web
|
||||
|
||||
# 共用套件安裝
|
||||
pnpm add <package> --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`: 進度追蹤
|
||||
@@ -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 骨架風格
|
||||
<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, **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 拒絕)
|
||||
<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 + 純白視覺絕對標準)*
|
||||
|
||||
Reference in New Issue
Block a user