feat(packages): Phase 6.4a-c leWOOOgo modular architecture

New packages:
- packages/lewooogo-brain: AI reasoning & decision engine
  - IProposalEngine interface (ABC)
  - IIncidentProcessor interface (ABC)
  - Pydantic models: Proposal, Guardrails, Incident, Signal

- packages/lewooogo-data: Memory provider abstraction
  - IMemoryProvider interface (ABC)
  - IDualMemoryProvider for Working + Episodic memory
  - Generic type support for flexible data models

Documentation:
- ADR-008: Python modular packages architecture decision
- ARCHITECTURE_MEMORY.md: Module map index for AI developers
- LOGBOOK.md: Updated milestones and Phase 6.4 status

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
OG T
2026-03-23 09:32:07 +08:00
parent d050dd1ecc
commit 80d0ef4a8f
17 changed files with 1007 additions and 7 deletions

View File

@@ -0,0 +1,146 @@
# ADR-008: Python 模組化獨立積木架構
**狀態**: 已批准
**日期**: 2026-03-23
**決策者**: CEO (統帥) + C-Suite
**執行者**: CTO + Claude Code
## 背景
AWOOOI 2.0 的後端 Python 代碼 (`apps/api/src/services/`) 出現以下問題:
1. **模組化原則淡化**: 所有邏輯直接寫在 `services/` 目錄,未建立獨立積木
2. **跨模組非法引用**: `proposal_service.py` 直接 import `redis_client`, `db.base`
3. **前後端積木不對稱**: 前端有 `packages/lewooogo-core` (TS),後端無對應 Python 積木
4. **Skill Registry 缺失**: 6 個 Skill MD 檔案無動態載入機制
## 決策
**採用統帥方案 (方案 A): 在 `packages/` 下建立獨立 Python 積木**
### 放棄的方案
- **方案 B (漸進式)**: 在 `apps/api/src/` 內建立 `brain/``memory/` 模組
- **理由**: 無法達成真正的物理隔離,違反 leWOOOgo 積木化原則
### 採用的技術
```toml
# apps/api/pyproject.toml
dependencies = [
"lewooogo-brain @ file:../../packages/lewooogo-brain",
"lewooogo-data @ file:../../packages/lewooogo-data",
]
```
使用 `pip install -e .` (Editable Install) 達成本地聯動開發。
## 積木職責定義
### lewooogo-brain (AI 邏輯積木)
| 模組 | 職責 |
|------|------|
| `interfaces/` | ABC 定義 (IProposalEngine, IIncidentProcessor) |
| `engines/` | 推論引擎 (IncidentEngine, ProposalEngine) |
| `skills/` | Skill 動態載入器 |
### lewooogo-data (資料抽象積木)
| 模組 | 職責 |
|------|------|
| `interfaces/` | ABC 定義 (IMemoryProvider) |
| `providers/` | 具體實作 (RedisMemory, PgMemory) |
## 目錄結構
```
packages/
├── lewooogo-core/ # TS 前端積木 (已有)
├── lewooogo-brain/ # Python AI 積木 (新建)
│ ├── pyproject.toml
│ └── src/lewooogo_brain/
│ ├── __init__.py
│ ├── interfaces/
│ │ ├── __init__.py
│ │ ├── proposal_engine.py
│ │ └── incident_processor.py
│ ├── engines/
│ │ ├── __init__.py
│ │ ├── incident_engine.py
│ │ └── proposal_engine.py
│ └── skills/
│ ├── __init__.py
│ └── loader.py
└── lewooogo-data/ # Python 資料積木 (新建)
├── pyproject.toml
└── src/lewooogo_data/
├── __init__.py
├── interfaces/
│ ├── __init__.py
│ └── memory_provider.py
└── providers/
├── __init__.py
├── redis_memory.py
└── pg_memory.py
```
## 引用方式
```python
# apps/api/src/api/v1/incidents.py
from lewooogo_brain.engines import ProposalEngine
from lewooogo_data.providers import RedisMemory
engine = ProposalEngine(memory=RedisMemory())
proposal = await engine.generate(incident_id)
```
## 依賴配置
### lewooogo-brain
```toml
dependencies = [
"pydantic>=2.5.0",
"structlog>=24.1.0",
"opentelemetry-api>=1.20.0",
"lewooogo-data", # 依賴資料積木
]
```
### lewooogo-data
```toml
dependencies = [
"pydantic>=2.5.0",
"redis>=5.0.0",
"sqlalchemy[asyncio]>=2.0.0",
"structlog>=24.1.0",
]
```
## 後果
### 優點
1. **完全物理隔離**: Brain 和 Data 積木可獨立測試、獨立部署
2. **可複用性**: 其他專案可直接引用這些積木
3. **符合 leWOOOgo 原則**: 高內聚、低耦合
4. **介面先行**: 強制定義 ABC再實作具體類別
### 缺點
1. **初期工時增加**: 約 3-4 天建立積木骨架
2. **依賴管理複雜度**: 需維護多個 pyproject.toml
3. **學習曲線**: 團隊需適應新的引用方式
## 相關決策
- ADR-003: leWOOOgo 模組架構 (前端 TS 版)
- ADR-005: BFF 閘道架構
## 參考資料
- [Python Packaging User Guide](https://packaging.python.org/)
- [PEP 621 Storing project metadata in pyproject.toml](https://peps.python.org/pep-0621/)