496c569d51
- RED_ZONES.md: Tier 3/2 紅區清單 - setup-hooks.sh: Git Hook 安裝腳本 - infrastructure docs: 部署拓撲更新 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
159 lines
4.5 KiB
Markdown
159 lines
4.5 KiB
Markdown
# AWOOOI 架構指引
|
|
|
|
> 架構相關的核心原則與規範
|
|
|
|
---
|
|
|
|
## 文件資訊
|
|
|
|
| 欄位 | 值 |
|
|
|------|-----|
|
|
| **版本** | v1.1 |
|
|
| **建立日期** | 2026-03-22 (台北) |
|
|
| **建立者** | Claude Code |
|
|
| **最後修改** | 2026-03-25 23:59 (台北) |
|
|
| **修改者** | Claude Code |
|
|
|
|
### 變更紀錄
|
|
|
|
| 版本 | 日期 | 執行者 | 變更內容 |
|
|
|------|------|--------|----------|
|
|
| v1.0 | 2026-03-22 | Claude Code | 初始建立 |
|
|
| v1.1 | 2026-03-25 | Claude Code | 加入文件資訊區塊 |
|
|
|
|
---
|
|
|
|
## 快速索引
|
|
|
|
| 主題 | 核心原則 | 詳細章節 |
|
|
|------|---------|---------|
|
|
| OpenClaw | 產品核心，只能增強不能移除 | [→ OpenClaw](#openclaw-核心架構) |
|
|
| 模組化 | Interface → Memory → Brain → Skill | [→ leWOOOgo](#lewooogo-模組化) |
|
|
| API 整合 | Props Mapping 五步驟檢查 | [→ API](#api-整合) |
|
|
| 防禦性 | 先質疑後實作 | [→ 防禦性工程](#防禦性工程) |
|
|
|
|
---
|
|
|
|
## OpenClaw 核心架構
|
|
|
|
**Memory 來源:** `feedback_architecture_openclaw_core.md`
|
|
|
|
### 原則
|
|
|
|
```
|
|
✅ OpenClaw 是 AWOOOI 產品核心
|
|
✅ 只能增強，不能移除
|
|
✅ 決策鏈必須可視化 (ThinkingTerminal)
|
|
✅ 雙軌決策: LLM + Expert System Fallback
|
|
```
|
|
|
|
### 決策流程
|
|
|
|
```
|
|
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)
|