diff --git a/.agents/skills/02-lewooogo-backend-core.md b/.agents/skills/02-lewooogo-backend-core.md index e75b71719..797998642 100644 --- a/.agents/skills/02-lewooogo-backend-core.md +++ b/.agents/skills/02-lewooogo-backend-core.md @@ -10,11 +10,11 @@ | 欄位 | 值 | |------|-----| -| **版本** | v2.0 | +| **版本** | v2.1 | | **建立日期** | 2026-03-20 (台北) | | **建立者** | Claude Code | -| **最後修改** | 2026-03-29 19:00 (台北) | -| **修改者** | Claude Code (首席架構師) | +| **最後修改** | 2026-03-29 20:10 (台北) | +| **修改者** | Claude Code | ### 變更紀錄 @@ -31,6 +31,7 @@ | v1.8 | 2026-03-28 | Claude Code | ✅ Phase 16 首席架構師驗收 50/50 OUTSTANDING | | v1.9 | 2026-03-28 | Claude Code | 🦞 新增 Phase 19 Terminal SSE 後端整合章節 | | v2.0 | 2026-03-29 | Claude Code | 🔴 Phase D-G P0 修正: 新增 LearningRepository (積木化合規) | +| v2.1 | 2026-03-29 | Claude Code | 🛡️ 新增 ADR-038/039 OpenClaw 安全網章節 (Wave 1 部署) | --- @@ -639,6 +640,85 @@ Incident → Expert 分類 → 診斷收集 → RAG 匹配 --- +## 🛡️ ADR-038/039 OpenClaw 安全網 (2026-03-29) + +> **架構審查**: Wave 1 194/200 (97%) OUTSTANDING +> **Memory**: `project_current_status.md` +> **ADR**: ADR-038 (推理併發治理) + ADR-039 (全域修復熔斷) + +### 鐵律:所有 OpenClaw 呼叫必須雙層保護 + +```python +from src.core.circuit_breaker import get_openclaw_guard + +async def call_openclaw_analyzer(error_context: dict) -> ErrorAnalysisResult | None: + guard = get_openclaw_guard() + + # Layer 1: Circuit Breaker 快速失敗 + if guard.is_circuit_open(): + logger.warning("openclaw_circuit_open", metrics=guard.get_metrics()) + return None + + # Layer 2: Concurrency Semaphore 限流 (最多 3 並發) + async with guard.semaphore: + try: + async with httpx.AsyncClient() as client: + response = await client.post(...) + guard.record_success() + return result + except Exception: + guard.record_failure() # 連續 5 次失敗 → 斷路 60s + return None +``` + +### 🔴 全域修復冷卻 (ADR-039) + +**鐵律**: 任何自動修復前必須呼叫 `check_global_repair_cooldown()` + +```python +from src.services.global_repair_cooldown import ( + check_global_repair_cooldown, + record_global_repair_action, +) + +# ✅ 正確 +async def execute_auto_repair(action: str, target: str): + if not await check_global_repair_cooldown(): + logger.warning("global_repair_cooldown_active") + return None + + result = await _do_repair(action, target) + await record_global_repair_action(action, target) + return result +``` + +### StatefulSet 黑名單 + +| 服務 | 說明 | 狀態 | +|------|------|------| +| `postgres` | 資料庫 | 🔴 永遠禁止自動修復 | +| `redis` | 快取/訊息 | 🔴 永遠禁止自動修復 | +| `clickhouse` | 分析資料庫 | 🔴 永遠禁止自動修復 | +| `minio` | 物件儲存 | 🔴 永遠禁止自動修復 | +| `etcd` | 叢集狀態 | 🔴 永遠禁止自動修復 | + +**允許修復**: `awoooi-api`, `awoooi-web`, `awoooi-worker` (無狀態服務) + +### Worker XCLAIM 機制 + +```python +# Signal Worker 必須實作孤兒訊息回收 +# 閒置超過 60s 的訊息會被 XCLAIM 回收 + +# 相關配置: +XCLAIM_IDLE_THRESHOLD_MS = 60_000 # 60 秒 +XCLAIM_BATCH_SIZE = 10 # 每批最多 10 條 +terminationGracePeriodSeconds: 90 # K8s 優雅關機 +Python stop() timeout: 75 # 比 K8s 少 15s 緩衝 +``` + +--- + ## 🦞 Phase 19 Terminal SSE 後端整合 (2026-03-28) > **審查結果**: 首席架構師審查 47/50 (P0-P2 全部修復)