From bb7441ec8a347b8f1fa548114e10d0840291544c Mon Sep 17 00:00:00 2001 From: OG T Date: Thu, 16 Apr 2026 01:09:26 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20CLAUDE.md=20+=20HA?= =?UTF-8?q?RD=5FRULES.md=20v2.0=20+=20LOGBOOK=20(2026-04-16)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - HARD_RULES.md v2.0: 新增 Self-Loop Workflow、Circuit Breaker Exception、State & Flow Validation - CLAUDE.md: 補充 §4 必讀Memory 表格 - LOGBOOK: 記錄 AIOps E2E 修復進度 2026-04-16 Claude Sonnet 4.6 Asia/Taipei Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 5 +- docs/HARD_RULES.md | 141 ++++++++++++++++++++++++++++++++++++++++++++- docs/LOGBOOK.md | 59 +++++++++++++++++++ 3 files changed, 201 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3ab5c8ef..3eadaf87 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -73,7 +73,10 @@ Tier 3 核心檔案 (decision_manager, trust_engine, config 等) 修改需首席 | OpenClaw | `feedback_architecture_openclaw_core.md` | | 命名規範 | `feedback_openclaw_naming.md` | | i18n | `feedback_i18n_zero_hardcode.md` | -| 防禦性工程 | `feedback_defensive_engineering.md` | +| 防禦性工程/狀態機驗證 | `feedback_defensive_engineering.md` | +| 禁止孤島開發 🔴🔴 | `HARD_RULES.md` → No Island Coding | +| 主動執行與熔斷 🔴🔴 | `feedback_proactive_execution.md` + `HARD_RULES.md` → Circuit Breaker | +| 自循環工作流 🔴🔴 | `HARD_RULES.md` → Self-Loop Workflow | | 積木化強制 🔴🔴 | `feedback_lewooogo_modular_enforcement.md` | | API 整合 | `feedback_api_response_verification.md` | | 構建部署 | `feedback_build_from_git_only.md` | diff --git a/docs/HARD_RULES.md b/docs/HARD_RULES.md index 4c0a4de3..8d9b251e 100644 --- a/docs/HARD_RULES.md +++ b/docs/HARD_RULES.md @@ -8,11 +8,11 @@ | 欄位 | 值 | |------|-----| -| **版本** | v1.9 | +| **版本** | v2.0 | | **建立日期** | 2026-03-20 (台北) | | **建立者** | Claude Code | -| **最後修改** | 2026-04-15 (台北) | -| **修改者** | Claude Code + ogt (ADR-080 AI 自主化飛輪 Phase 退出條件鐵律) | +| **最後修改** | 2026-04-16 (台北) | +| **修改者** | Claude Code + ogt (新增孤島開發/主動執行熔斷/自循環工作流/狀態機驗證鐵律) | ### 變更紀錄 @@ -28,6 +28,7 @@ | v1.7 | 2026-04-02 | Claude Code | Phase 24 AI Router 重構規範 (DI/隱私/絞殺者) | | v1.8 | 2026-04-03 | Claude Code | 🔴🔴🔴 費用變更強制審批 (統帥指示) | | v1.9 | 2026-04-15 | Claude Code + ogt | 🔴🔴🔴 AI 自主化飛輪 Phase 退出條件鐵律 (ADR-080) | +| v2.0 | 2026-04-16 | Claude Code + ogt | 新增 No Island Coding / 主動執行熔斷機制 / 自循環工作流 / 狀態機驗證鐵律 | --- @@ -54,6 +55,10 @@ | **AI Router** | **Router import 具體 Provider** | **只依賴 Protocol** | [→ OpenClaw](#openclaw) | | **🔴🔴🔴 費用變更** | **擅自切換/新增付費 AI Provider** | **先讀憲法第五章，再請統帥批准** | [→ Cost Change Approval](#cost-change-approval) | | **🔴🔴🔴 AI 飛輪 Phase** | **未過退出條件就宣告完成** | **必須逐條驗收 exit conditions** | [→ AI Phase Exit Conditions](#ai-phase-exit-conditions) | +| **🔴🔴 孤島開發** | **局部最佳化不查 Callers** | **grep 全域掃描後才動手** | [→ No Island Coding](#no-island-coding) | +| **🔴🔴 熔斷機制** | **不確定就停下來問** | **主動做完，爆炸半徑 >3 模組才熔斷** | [→ 主動執行與熔斷](#proactive-execution--circuit-breaker) | +| **🔴🔴 工作流節奏** | **每步都來回報** | **內部自循環，全局單次回報** | [→ 自循環工作流](#self-loop-workflow) | +| **🟡 狀態機驗證** | **不查中間狀態卡死** | **必驗 TTL + Cleanup + Fallback** | [→ State & Flow Validation](#state--flow-validation) | --- @@ -491,6 +496,136 @@ def new_function(): --- +--- + +## 🔴🔴 No Island Coding — 禁止孤島開發 + +> 任何程式碼修改，必定影響上下游。未經全域檢視的局部最佳化，視為嚴重失職。 + +### 三條鐵律 + +| 情境 | 必做動作 | +|------|---------| +| **變更函數簽名** | `grep -rn "函數名" apps/ packages/` 找出所有 Callers，一併更新 | +| **變更資料模型 (DB/Pydantic)** | 同步確認 Write 層、Read 層、Redis Cache 序列化/反序列化邏輯一致 | +| **任何局部修改** | 禁止「假設它會動」，必須全域掃描才能動手 | + +```bash +# 修改函數前的強制指令 +grep -rn "target_function_name" apps/ packages/ --include="*.py" +# 列出所有 Caller，逐一確認影響範圍 +``` + +**與積木化的關係：** No Island Coding 是「橫向」掃描（找所有呼叫者），leWOOOgo 積木化是「縱向」邊界（Router 不能越界）。兩者並行，缺一不可。 + +--- + +## 🔴🔴 Proactive Execution & Circuit Breaker — 主動執行與熔斷機制 + +> 整合 `feedback_proactive_execution.md`（主動執行，2026-04-05）與孤島開發停問規則。 +> **主動執行為絕對預設，停下問是唯一例外。** + +### 預設：主動狂奔 + +看到任務與規格後，**一口氣實作到底**： + +``` +✅ 自己寫 Code +✅ 自己跑測試 +✅ 自己修 Error +✅ 全部跑通後才回報 +``` + +``` +❌ 禁止：列出步驟然後問「統帥可不可以開始」 +❌ 禁止：把「不確定」當作不寫 Code 的藉口 +❌ 禁止：拿中間的 Error 來打斷統帥 +``` + +### 唯一熔斷條件（Circuit Breaker） + +**必須同時滿足以下兩個條件**，才可暫停並請求裁示： + +1. 修改的檔案是 **Tier 3 核心紅區**（如 `decision_manager.py`、`db/base.py`） +2. 透過 `grep` 發現這個修改會直接導致 **超過 3 個以上未關聯模組**發生不可預期的 Crash + +熔斷時的回報格式： +``` +發現連鎖爆炸半徑，涉及 [A, B, C]，請求裁示 +``` + +**其餘所有情況，全部自己解決。** + +--- + +## 🔴🔴 Self-Loop Workflow — 自循環工作流與全局回報 + +> 四步工作流是 AI 的**內部背景作業**，不是與統帥的來回節奏。 + +### 內部自循環（不對外打斷） + +``` +[1. 影響評估] → [2. 實作] → [3. 串接驗證] + ↓ Error + [4. 自動修復] → 回到 [3. 串接驗證] +``` + +遇到驗證腳本報錯，**必須自動遞迴修復，不得中斷統帥。** + +### 全局單次回報（唯一一次） + +當整個任務 100% 通過時，進行唯一一次成果彙報，必須包含： + +``` +1. 修改了哪些檔案（逐一列出） +2. 最終成功的終端機輸出（Console Output） +3. 是否有潛在副作用 +``` + +等待統帥批准後，才能執行 `git commit` 與 `push`。 + +### 驗證腳本規範 — Live-Fire Only（實彈演習） + +根據 [No Mock Testing](#no-mock-testing) 鐵律，`verify_script.py` **絕對禁止使用任何 Mock 套件**： + +```python +# ❌ 禁止 — 自己 mock 自己測，驗證毫無意義 +from unittest.mock import MagicMock +db = MagicMock() + +# ✅ 正確 — 打真實 PostgreSQL / Redis / HTTP +async with get_session() as session: + result = await session.execute(select(MyModel).where(...)) + +# 驗證完畢後必須 Teardown，清理測試資料 +await session.execute(delete(MyModel).where(MyModel.id == test_id)) +``` + +--- + +## 🟡 State & Flow Validation — 狀態機與流程驗證 + +修改涉及 **async、background jobs、DB 狀態轉換** 的邏輯時，必須驗證以下清單。 + +### 必查斷點 + +| 風險類型 | 必查項目 | +|---------|---------| +| **中間狀態卡死** | `PENDING` 是否有機制轉為 `EXPIRED`？`PROCESSING` 超時後誰負責撿起？ | +| **Fire-and-forget 無聲失敗** | 異步任務失敗時，Exception 是否被吞掉？有無 dead letter / retry？ | +| **新增資料實體** | TTL 多長？Cleanup Job 是什麼？錯誤降級策略（Fallback）定義了嗎？ | +| **生命週期完整性** | 建立 → 處理 → 結案 → 清理，四個階段必須全部有對應的程式碼 | + +```python +# 新增資料實體的最低要求 +class MyEntity(Base): + expires_at: datetime # TTL 必填 + # 對應 Cleanup Job: scheduler/cleanup_expired_entities.py + # 降級策略: 超時 → status = EXPIRED → Telegram 告警 +``` + +--- + ## 如何新增規則 1. 在此文件新增章節 diff --git a/docs/LOGBOOK.md b/docs/LOGBOOK.md index faf7e4ac..17d5d71f 100644 --- a/docs/LOGBOOK.md +++ b/docs/LOGBOOK.md @@ -6,6 +6,65 @@ --- +## 📍 2026-04-15 深夜 — AI 自主化飛輪 Phase 4-6 全完成 + 生產全開 🎉 + +### Phase 4 異常偵測升級（commit 14a0226，ADR-084） + +| 成品 | 路徑 | +|------|------| +| TrendPredictor | `services/trend_predictor.py` — statsmodels ARIMA 趨勢預測 | +| ProactiveInspector | `services/proactive_inspector.py` — 主動巡檢（L1-L4 四層） | +| 8D 感官升級 | `services/pre_decision_investigator.py` — anomaly_context 增強 | + +### Phase 5 修復抽象化（commit 655d1a5，ADR-086） + +| 成品 | 路徑 | +|------|------| +| BlastRadiusCalculator | `services/blast_radius_calculator.py` — CRITICAL/HIGH/MEDIUM/LOW 分控 | +| DeclarativeRemediation | `services/declarative_remediation.py` — dry-run → apply 分階段 rollout | +| GitOpsPRService | `services/gitops_pr_service.py` — 自動 PR 生成 IaC 修復 | +| RollbackManager | `services/rollback_manager.py` — 自動回滾策略 | +| DecisionManager 接線 | `AIOPS_P5_BLAST_RADIUS_CHECK` gate 守衛 | + +### Phase 6 自我治理閉環（commit 05b7743 + 77a92eb） + +| 成品 | 路徑 | +|------|------| +| AiSloCalculator | `services/ai_slo_calculator.py` — SLO 計算器 | +| TrustDriftDetector | `services/trust_drift_detector.py` — 信任度漂移偵測 | +| KbRotCleaner | `jobs/kb_rot_cleaner.py` — 知識庫腐爛清理 Job | +| 自我降級引擎 | `services/decision_manager.py` 接線 | +| SLO REST API | `api/v1/ai_slo.py` — GET /api/v1/ai/slo | +| OfflineReplayService | `services/offline_replay_service.py` — 離線回放驗證 | +| ModelRollbackService | `services/model_rollback_service.py` — 模型回滾機制 | +| DB 表 | `db/models.py` AiGovernanceEvent + 3 index | + +### P1-P6 全開（commit 76558a3） + +``` +AIOPS_P1_ENABLED=True ... AIOPS_P6_ENABLED=True（全部） +Nemotron 接線 + offline replay loop 啟動 +``` + +### 生產修補（全開後，2026-04-15 深夜） + +| Commit | 修復內容 | +|--------|---------| +| `85c4e3b` | KM 寫入全為 unknown 根因（alertname/affected_services/category 三節點） | +| `ecfb714` | YAML 規則引擎與自動執行路徑核心斷點接通 | +| `3696fb5` | host_resource 誤發 K8s kubectl + 自動執行重複風暴 | +| `67f4370` | 四個生產致命 bug（outcome 寫入/OpenClaw/Telegram/LLM 規則顯示） | +| `256a24e` | drain3/statsmodels 依賴補入 + warmup skip 舊資料 | +| `c05bac6` | Playbook seed tuple unpack + text[]→jsonb migration | +| `da871fc` | AIOps P1/P2/P6 migration SQL 補齊（已 prod 套用） | + +### 技術債（下次 Sprint） + +- `send_notification()` 未私有化（raw text bypass 可能） +- `approval_repository.py:find_by_fingerprint()` 無 TTL + +--- + ## 📍 2026-04-15 — AI 自主化飛輪 Phase 0 防護欄建立 ### 完成項目