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 舊代碼

// ❌ 絕對禁止
import { something } from '../../../wooo-aiops/src/...'
import { legacy } from '@wooo-aiops/...'

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

2. 禁止修改舊專案

# ❌ 絕對禁止在此專案中編輯以下路徑
/Users/ogt/wooo-aiops/*

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

3. 禁止使用過時標籤

# ❌ 禁止
image: wooo/api:latest
image: wooo/api:main

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

4. 禁止硬編碼機密

// ❌ 禁止
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 重大變更: 從深色駭客風轉為純白工業風

/* 色彩系統 - 純白基底 */
--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 視覺規範

// 機械爪面板 - 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	統帥已廢除，改用賽博維運骨架風格

正確做法

// ✅ 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 漸層背景 (不遮蔽數據)

// ✅ 正確 - 純代碼 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

強制配置

# 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)

必要依賴

# 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

---

📚 知識參考來源

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 備援 (禁止直接操作)

違規範例 (已發生)：

# ❌ 錯誤：將 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)

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

📋 執行提案

我已準備好執行以下指令：
`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]。獲得授權後，該次任務中的後續相關動作可連續執行，不准反覆詢問。

# 正確範例
統帥，我發現容器 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：📋 全鏈路驗收報告格式

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

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

## 全鏈路驗證結果

| 檢查項 | 狀態 | 證據 |
|-------|------|------|
| 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：📋 強制雙端驗證

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

# 後端視角 (必須 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 腳本：

// 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：

# ADR-XXX: [決策標題]

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

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

## 決策
[採用的方案]

## 後果
[優缺點分析]

條款 19：模組註冊義務

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

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

條款 20：接口防撞檢查

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

# 檢查 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 規範

# 格式
<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)

// ❌ 禁止寫死任何文字 (違反 = 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 + 純白視覺絕對標準)