awoooi/docs/adr/ADR-003-lewooogo-module-architecture.md

ADR-003: leWOOOgo 模組化架構

狀態: Accepted 日期: 2026-03-19 決策者: CTO + CEO

背景

AWOOOI 需要高度模組化的架構，讓開發者能像組樂高一樣快速組合功能。CEO 命名此引擎為 leWOOOgo (樂高 + WOOO)。

傳統 monolithic 架構難以擴展，plugin 架構則能支援生態系統發展。

決策

採用六大積木類別的 Plugin 架構

┌─────────────────────────────────────────────────────────────────┐
│                      leWOOOgo Engine                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   🧱 INPUT ──────→ 🧠 BRAIN ──────→ 📢 OUTPUT                  │
│   (觸發器)          (AI 處理)         (通知)                     │
│       │                │                 │                       │
│       │                ↓                 │                       │
│       │          🔧 ACTION              │                       │
│       │          (執行器)                │                       │
│       │                │                 │                       │
│       └───────→ 📊 DATA ←───────────────┘                       │
│                 (儲存)                                           │
│                                                                 │
│                    🎨 UI                                         │
│                 (介面元件)                                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

六大積木類別

類別	介面	用途	範例
INPUT	TriggerPlugin	觸發工作流	Webhook, Cron, Alert, Email
BRAIN	AgentProvider	AI 處理決策	LLM Router, RAG, Triage, MCP
OUTPUT	NotificationChannel	發送通知	Telegram, Slack, LINE, Email
ACTION	ActionExecutor	執行操作	K8s, SSH, Docker, API Call
DATA	DataAdapter	資料存取	PostgreSQL, Redis, S3, Vector
UI	WidgetComponent	介面元件	Card, Chart, Timeline, Status

核心介面定義

// packages/lewooogo-core/src/interfaces/plugin.ts

/** 所有 Plugin 的基礎介面 */
interface LeWOOOgoPlugin {
  readonly id: string
  readonly name: string
  readonly version: string
  readonly category: 'INPUT' | 'BRAIN' | 'OUTPUT' | 'ACTION' | 'DATA' | 'UI'

  initialize(): Promise<void>
  healthCheck(): Promise<HealthStatus>
  shutdown(): Promise<void>
}

/** INPUT 觸發器 */
interface TriggerPlugin extends LeWOOOgoPlugin {
  category: 'INPUT'
  subscribe(handler: TriggerHandler): Unsubscribe
  getSchema(): TriggerSchema
}

/** BRAIN AI 處理器 */
interface AgentProvider extends LeWOOOgoPlugin {
  category: 'BRAIN'
  process(input: AgentInput): Promise<AgentOutput>
  getCapabilities(): AgentCapability[]
}

/** OUTPUT 通知頻道 */
interface NotificationChannel extends LeWOOOgoPlugin {
  category: 'OUTPUT'
  send(message: NotificationMessage): Promise<SendResult>
  getTemplates(): NotificationTemplate[]
}

/** ACTION 執行器 */
interface ActionExecutor extends LeWOOOgoPlugin {
  category: 'ACTION'
  execute(action: ActionRequest): Promise<ActionResult>
  dryRun(action: ActionRequest): Promise<DryRunResult>
  rollback(executionId: string): Promise<RollbackResult>
}

/** DATA 資料適配器 */
interface DataAdapter extends LeWOOOgoPlugin {
  category: 'DATA'
  connect(): Promise<void>
  query<T>(request: QueryRequest): Promise<T>
  disconnect(): Promise<void>
}

/** UI 介面元件 */
interface WidgetComponent extends LeWOOOgoPlugin {
  category: 'UI'
  render(props: WidgetProps): ReactNode
  getConfigSchema(): JSONSchema
}

資料夾結構

packages/
├── lewooogo-core/           # 核心引擎
│   ├── src/
│   │   ├── interfaces/      # 六大介面定義
│   │   ├── registry/        # Plugin 註冊中心
│   │   ├── pipeline/        # 工作流引擎
│   │   └── utils/           # 共用工具
│   └── package.json
│
├── lewooogo-input/          # INPUT 積木
│   ├── src/
│   │   ├── webhook/
│   │   ├── cron/
│   │   ├── prometheus-alert/
│   │   └── email-trigger/
│   └── package.json
│
├── lewooogo-brain/          # BRAIN 積木
│   ├── src/
│   │   ├── llm-router/      # LLM 路由器
│   │   ├── mcp-bridge/      # MCP 整合 (ADR-001)
│   │   ├── triage-engine/   # 告警分級
│   │   └── rag-provider/    # RAG 檢索
│   └── package.json
│
├── lewooogo-output/         # OUTPUT 積木
│   ├── src/
│   │   ├── telegram/
│   │   ├── slack/
│   │   ├── line/
│   │   └── email/
│   └── package.json
│
├── lewooogo-action/         # ACTION 積木
│   ├── src/
│   │   ├── kubernetes/
│   │   ├── ssh/
│   │   ├── docker/
│   │   └── http-api/
│   └── package.json
│
├── lewooogo-data/           # DATA 積木
│   ├── src/
│   │   ├── postgres/
│   │   ├── redis/
│   │   ├── s3/
│   │   └── vector-db/
│   └── package.json
│
└── lewooogo-ui/             # UI 積木
    ├── src/
    │   ├── cards/
    │   ├── charts/
    │   ├── timeline/
    │   └── status-indicators/
    └── package.json

理由

1. 開發者體驗 (DX)

傳統方式	leWOOOgo 方式
修改核心程式碼	npm install + 註冊
重新部署整體	熱插拔 Plugin
閱讀大量文檔	統一介面 + TypeScript

2. 生態系統潛力

標準介面允許第三方開發 Plugin，形成市場。

3. 測試隔離

每個 Plugin 獨立測試，不影響核心引擎。

後果

優點

• 模組化 功能獨立開發部署
• 可擴展 第三方生態系統
• 可測試 單元測試隔離
• 可維護 責任分離清晰

缺點

• 初期成本 需建立完整介面規範
• 效能開銷 Plugin 動態載入有成本
• 版本管理 多 package 需 monorepo 工具

風險

風險	緩解措施
介面設計錯誤	Phase 0 充分討論 + 早期 POC 驗證
Plugin 衝突	Plugin Registry 管理 + 命名空間隔離
效能問題	關鍵路徑避免過度抽象，效能測試

Monorepo 工具

採用 pnpm workspace + Turborepo：

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

// turbo.json
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    },
    "test": {
      "dependsOn": ["build"]
    }
  }
}

參考

• Turborepo
• pnpm Workspaces
• ADR-001: MCP Protocol 採用
• 會議記錄: docs/meetings/2026-03-19_FRONTEND_RESTRUCTURE_STRATEGY.md