# AWOOOI 架構指引

> 架構相關的核心原則與規範

---

## 文件資訊

| 欄位 | 值 |
|------|-----|
| **版本** | v1.2 |
| **建立日期** | 2026-03-22 (台北) |
| **建立者** | Claude Code |
| **最後修改** | 2026-06-01 00:00 (台北) |
| **修改者** | Codex |

### 變更紀錄

| 版本 | 日期 | 執行者 | 變更內容 |
|------|------|--------|----------|
| v1.0 | 2026-03-22 | Claude Code | 初始建立 |
| v1.1 | 2026-03-25 | Claude Code | 加入文件資訊區塊 |
| v1.2 | 2026-06-01 | Codex | OpenClaw 定位改為市場主流評估與實測數據決策 |

---

## 快速索引

| 主題 | 核心原則 | 詳細章節 |
|------|---------|---------|
| OpenClaw | 當前生產核心；去留由市場主流與實測數據決策 | [→ OpenClaw](#openclaw-核心架構) |
| 模組化 | Interface → Memory → Brain → Skill | [→ leWOOOgo](#lewooogo-模組化) |
| API 整合 | Props Mapping 五步驟檢查 | [→ API](#api-整合) |
| 防禦性 | 先質疑後實作 | [→ 防禦性工程](#防禦性工程) |

---

## OpenClaw 核心架構

**Memory 來源:** `feedback_architecture_openclaw_core.md`

### 原則

```
✅ OpenClaw 是目前 AWOOOI 生產決策核心
✅ 是否保留、拆分、替換，必須由市場主流 Agent 評估與 AWOOOI 實測數據決定
✅ 禁止用歷史定位、個人偏好或單次 demo 取代專業評估
✅ 決策鏈必須可視化 (ThinkingTerminal)
✅ 雙軌決策: LLM + Expert System Fallback
```

### 市場評估鐵律

OpenClaw 不是永久不可挑戰的固定答案。產品核心是「AI 自主維運能力」，若市場主流 Agent 在 AWOOOI 的真實 incident replay、shadow、canary 中證明更強，就應提出 ADR 調整架構。

評估必須覆蓋 OpenAI Agents SDK、Claude Agent SDK、LangGraph、Google ADK、Microsoft Agent Framework、NVIDIA NeMo Agent Toolkit / Nemotron、CrewAI 等當期主流候選，並比較：

- 多 Agent orchestration / handoff / workflow / state / resume
- tool calling、dry-run、rollback、HITL、危險動作攔截
- trace、audit、token/cost、prompt/tool/result 可觀測性
- memory、learning、offline replay、evaluation
- sandbox、secret isolation、privacy/local deploy
- p95/p99 latency、fallback、crash recovery、月成本與 infra 需求
- 與 AwoooP、Telegram、Incident、KM/Playbook、MCP、Prometheus/SignOz/K8s 的整合成本

沒有上述數據，不得宣稱「OpenClaw 必須保留」或「OpenClaw 必須被取代」。

NeMo/Nemotron 類外部 runner 另需通過 preflight、sanitize/regenerate、readiness 三段本地 gate；`ready_for_approval` 只代表可提交統帥批准，不代表可直接呼叫外部 NIM/API/LLM。

### 決策流程

```
Signal → IncidentEngine → DecisionManager → Telegram/UI
                              ↓
                    LLM 提案 + Expert System 備援
```

### 命名規範

- ✅ 正確: OpenClaw, openclaw
- ❌ 禁止: OpenClaw, clawbot (舊稱)

---

## leWOOOgo 模組化

**Memory 來源:** `feedback_modular_architecture.md`, `feedback_modular_core_spirit.md`

### 四層架構

```
┌─────────────────────────────────────────┐
│  Skill Layer (技能層)                   │
│  - 特定領域知識                          │
│  - 可組合、可替換                        │
├─────────────────────────────────────────┤
│  Brain Layer (決策層)                   │
│  - LLM + Expert System                  │
│  - 決策邏輯                              │
├─────────────────────────────────────────┤
│  Memory Layer (記憶層)                  │
│  - Working: Redis (短期)                │
│  - Episodic: PostgreSQL (長期)          │
├─────────────────────────────────────────┤
│  Interface Layer (介面層)               │
│  - Telegram Gateway                     │
│  - REST API                             │
└─────────────────────────────────────────┘
```

### 核心精神

1. **Interface 先行** - 先定義清晰的介面契約
2. **Memory 分離** - Working Memory ≠ Episodic Memory
3. **Brain 獨立** - 決策邏輯不綁定特定 LLM
4. **Skill 可組合** - 技能可插拔、可替換

---

## API 整合

**Memory 來源:** `feedback_api_response_verification.md`

### Props Mapping 五步驟檢查

新增 API 欄位時，必須確認完整鏈路：

```
1. API Response 有該欄位 ✓
2. Mapper 函數有轉換該欄位 ✓  ← 最常遺漏！
3. TypeScript 型別有定義該欄位 ✓
4. 組件 Props 有接收該欄位 ✓
5. 組件有使用該欄位 ✓
```

### 快速診斷

```bash
# 確認 API 有回傳
curl -s API_URL | jq '.[0].decision'

# 確認 Mapper 有轉換
grep -n "decision" apps/web/src/app/*/page.tsx
```

### 2026-03-23 教訓

Y/n 按鈕灰色無法點擊，因為 `mapToDualState()` 遺漏傳遞 `decision` 欄位。

---

## 防禦性工程

**Memory 來源:** `feedback_defensive_engineering.md`

### 原則

```
1. 先質疑，後實作
2. 看到可疑代碼，先問為什麼存在
3. 不確定的變更，先問統帥
4. 任何刪除操作，三思後行
```

### 常見陷阱

- 「這段代碼看起來沒用」→ 先 grep 確認沒人用
- 「這個 TODO 很久了」→ 先確認是否已完成
- 「這個邏輯很奇怪」→ 可能是特殊 case 處理

---

## 相關 ADR

- [ADR-003: leWOOOgo 模組架構](adr/ADR-003-lewooogo-module-architecture.md)
- [ADR-006: AI Fallback 策略](adr/ADR-006-ai-fallback-strategy.md)
- [ADR-008: Python 模組化](adr/ADR-008-python-modular-packages.md)
- [ADR-009: OpenClaw Agent Teams](adr/ADR-009-openclaw-agent-teams.md)