179 lines
5.9 KiB
Markdown
179 lines
5.9 KiB
Markdown
# 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)
|