5.9 KiB
5.9 KiB
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 |
| 模組化 | Interface → Memory → Brain → Skill | → leWOOOgo |
| API 整合 | Props Mapping 五步驟檢查 | → 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 │
└─────────────────────────────────────────┘
核心精神
- Interface 先行 - 先定義清晰的介面契約
- Memory 分離 - Working Memory ≠ Episodic Memory
- Brain 獨立 - 決策邏輯不綁定特定 LLM
- Skill 可組合 - 技能可插拔、可替換
API 整合
Memory 來源: feedback_api_response_verification.md
Props Mapping 五步驟檢查
新增 API 欄位時，必須確認完整鏈路：
1. API Response 有該欄位 ✓
2. Mapper 函數有轉換該欄位 ✓ ← 最常遺漏！
3. TypeScript 型別有定義該欄位 ✓
4. 組件 Props 有接收該欄位 ✓
5. 組件有使用該欄位 ✓
快速診斷
# 確認 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 處理