# AWOOOI / AwoooP / AI 自主化飛輪整合計畫

**日期**：2026-05-06
**狀態**：已接受，作為 AwoooP 後續執行的整合基準
**範圍**：AWOOOI 告警、AI 決策、簽核、MCP 執行、KM/RAG/PlayBook 學習、AwoooP Operator Console、稽核、治理與平台可靠性
**相關文件**：
- `docs/superpowers/specs/2026-04-15-MASTER-ai-autonomous-flywheel-v2.md`
- `docs/awooop/MASTER-WORKPLAN.md`
- `docs/awooop/DETAILED-IMPLEMENTATION-PLAN.md`
- `docs/awooop/AWOOOP-MONITORING-ALERTING-CONVERGENCE.md`
- `docs/adr/ADR-106-agent-platform-architecture.md`

## 1. 架構決策

目前盤點出的問題不是一批孤立 bug，而是 AI 自主化飛輪尚未端到端閉環的證據。

AwoooP 不得在 AWOOOI 自動化之外另長成一條產品線。AwoooP 是同一條飛輪的人機協作與治理平面：

- **AI Flywheel**：引擎、認知、執行與學習迴路。
- **AwoooP**：操作員控制台、治理平面、稽核平面與人工簽核平面。
- **MCP Gateway**：工具呼叫的唯一執行閘門。
- **Approval / Trust**：唯一授權狀態機。
- **KM / RAG / PlayBook**：唯一知識底座。
- **Channel Event / Audit**：唯一觀測、稽核與追蹤流。

如果 AI 自動化與 AwoooP 分成兩條軌道推進，系統會漂移出兩套簽核狀態機、兩套稽核流、兩套路由閘門、兩套 MCP 與 Channel 決策，最後前端看到的狀態會與後端真實執行狀態不一致。

## 2. 共同目標迴路

目標閉環如下：

```text
監控 / 告警
  -> 事件分類
  -> 規則匹配或規則建立
  -> PlayBook / KM / RAG 檢索
  -> AI 決策
  -> Approval / Trust Gate
  -> MCP Gateway 執行
  -> 稽核與追蹤
  -> 執行驗證
  -> KM / Rule / PlayBook 回饋
```

AwoooP 負責呈現與治理這條迴路，不建立獨立的執行 lane。

## 3. 架構不變式

1. **唯一執行閘門**：production MCP 呼叫必須通過 MCP Gateway。直接呼叫 provider 是相容性技術債，必須逐步標記為 `forbid-new`。
2. **唯一簽核狀態機**：AwoooP approvals、AWOOOI approval records、TrustEngine 與 Telegram 簽核按鈕必須收斂成一條可簽章、可稽核的流程。
3. **唯一稽核流**：Channel events、runtime state、MCP audit、model routing 與 approval decisions 必須能以 `project_id`、`run_id`、`trace_id` 串接查詢。
4. **唯一知識底座**：KM、RAG、PlayBook embeddings 必須使用一致的維度與模型命名。測試 fixtures 必須與 production schema 一致。
5. **唯一模型路由控制面**：provider/model fallback 必須透過 EffectivePolicy，或在絞殺榕遷移期間使用受包裝的 legacy 等價層解析。
6. **租戶邊界禁止 fail-open**：缺少 `project_id` 時不得擴大資料可見範圍。Bootstrap 例外必須明確且可稽核。
7. **禁止 client-only 身份**：frontend body 提供的 operator identity 只能當顯示 metadata；授權身份必須來自已認證 principal。
8. **Channel adapter 不做政策決策**：Telegram、LINE、Slack、Email adapter 只負責收送與追蹤訊息，不決定模型、工具、簽核或事件策略。
9. **文件一律繁體中文**：Markdown 文件、ADR、LOGBOOK、Runbook、交接文件與計畫文件必須使用繁體中文；技術識別碼、API path、程式符號、錯誤碼、指令、服務名稱與原始 log 可保留英文。

## 4. 整合分層

### 4.1 AI 飛輪核心層

負責監控、告警入口、事件分類、規則匹配、規則生成、PlayBook、KM/RAG、AI 決策、安全修復、驗證與學習回饋。

既有關鍵介面：

- `apps/api/src/api/v1/webhooks.py`
- `apps/api/src/services/decision_manager.py`
- `apps/api/src/services/alert_rule_engine.py`
- `apps/api/src/services/learning_service.py`
- `apps/api/src/services/auto_repair_service.py`
- `apps/api/src/services/knowledge_rag_service.py`
- `apps/api/src/services/playbook_rag.py`

### 4.2 AwoooP 治理 / 操作層

負責 operator runs、approvals、audit、channel events、MCP Gateway 可視化、frontend 操作面、i18n 與已認證 operator identity。

既有關鍵介面：

- `apps/api/src/api/v1/platform/*`
- `apps/api/src/services/platform_*`
- `apps/api/src/plugins/mcp/gateway.py`
- `apps/api/src/plugins/mcp/registry.py`
- `apps/web/src/app/[locale]/awooop/*`
- `docs/awooop/*`

### 4.3 基礎設施 / 可靠性層

負責 DB schema 與 RLS、Redis namespace migration、K8s manifests、NetworkPolicy、Ollama failover、Gitea CD、migration discipline 與 release gates。

既有關鍵介面：

- `apps/api/migrations/*`
- `apps/api/src/db/*`
- `k8s/awoooi-prod/*`
- `.gitea/workflows/*`
- `docs/runbooks/*`
- `docs/awooop/inventory/*`

## 5. 整合風險登錄表

### 5.1 P0：production 會壞或安全關鍵

| ID | 風險 | 影響 | 必要方向 |
| --- | --- | --- | --- |
| P0-A | MCP Gateway 尚未成為 production choke point；caller 仍可直接碰 `provider.execute()`。 | Gateway gate、redaction、audit 可能被繞過。 | 包裝所有 production MCP call sites，然後將 direct provider access 標記為 `forbid-new`。 |
| P0-B | MCP blocked-call audit 在 `tool_row` 缺失或 Gate 1/2 提早拒絕時有缺口。 | 被拒絕或可疑的呼叫可能從稽核中消失。 | 在 gate 評估前後都寫入 audit attempt，並套安全 redaction。 |
| P0-C | Legacy K8s tool execution 仍有 command/shell injection 風險。 | 破壞性指令路徑可能被 LLM 或使用者輸入污染。 | 解析指令結構、避免 shell、強制 operation schema 與 allowlist。 |
| P0-D | 部分成功路徑用 `MCPToolResult(data=...)`，與 dataclass 欄位不一致。 | Sentry / ArgoCD 等 provider 可能在有效結果上 crash。 | 正規化 result schema，並為所有 MCP providers 補 regression tests。 |
| P0-E | RAG/KM/PlayBook embedding 維度仍分裂為 768 與 1024。 | 搜尋或 backfill 可能靜默失敗，或掩蓋 production drift。 | 統一為 `bge-m3` 1024 維，移除 stale fixtures。 |
| P0-F | KM backfill reconciler 缺少必要 async import 或 runtime dependency。 | 原本應修復 embeddings 的補救路徑可能 crash。 | 對 reconciler path 做 compile 與 integration test。 |
| P0-G | Ollama routing 仍有 direct `OLLAMA_URL` consumers。 | GCP-A/GCP-B/111 順序與 Gemini fallback policy 可能被繞過。 | 盤點、包裝並遷移 call sites 到 resolver / EffectivePolicy。 |
| P0-H | `project_id` 為 null 時 RLS fail-open。 | 有跨租戶資料暴露風險。 | RLS 強制 fail-closed，並建立明確 platform bootstrap identity。 |
| P0-I | Approval APIs 信任 frontend/body identity，例如 `approver_id: "operator"`。 | 稽核身份無法作為法務或維運依據。 | Decide endpoint 必須從 auth/session/token 推導 principal，不信任 body。 |
| P0-J | 部分 API control plane 缺少真正 authorization；CSRF 不是 authorization。 | Operator APIs 可能在沒有真實角色邊界下被呼叫。 | 為 AwoooP APIs 加入 authenticated principal 與 role checks。 |
| P0-K | Alertmanager internal bypass 搭配 `X-Forwarded-For` 與過寬 trusted hosts，可能讓來源身份被 spoof。 | 偽造告警入口可能建立 incidents 或 approvals。 | 要求 signed webhook，或嚴格限制 trusted proxy chain。 |
| P0-L | AwoooP approval token service 也依賴 `aioredis`。 | Python/runtime 相容性問題可能打壞 approvals。 | 遷移 Redis client path，或包裝成已維護的 async Redis interface。 |

### 5.2 P1：治理一致性與可靠性

| ID | 風險 | 影響 | 必要方向 |
| --- | --- | --- | --- |
| P1-A | Approval repository / TrustEngine 有 race condition。 | 可能出現重複決策、stale decision 或 missed approval。 | 加入 row locks、idempotency keys 與 single source of truth。 |
| P1-B | TrustEngine 使用 process memory dict。 | pending approvals 會因 pod restart 或多副本拆裂而消失或分裂。 | 權威狀態移到 PostgreSQL；Redis 僅作 cache/notification。 |
| P1-C | NetworkPolicy 名稱像 deny，但語義上允許過寬流量。 | 造成隔離已完成的錯覺。 | 對齊名稱、政策與 live cluster 行為。 |
| P1-D | Kustomize 可能漏納 service registry、HPA、VPA、backup cron 或相關資源。 | GitOps drift 與 partial deploy。 | 盤點 generated/live manifests，補齊缺失資源。 |
| P1-E | alert rules 中仍殘留 hardcoded restart/SSH actions。 | 與 AI 自動化、rule/PlayBook evidence loop 衝突。 | 轉換為 PlayBook proposals，並走 trust gates。 |
| P1-F | startup schema mutation 與散落 SQL migrations 仍存在。 | Runtime ALTER 可能讓 dev/prod schema 漂移。 | 收斂到紀律化 migration path，移除 runtime mutation。 |
| P1-G | Tests 仍使用 stale 768 維 vectors。 | Dev tests 可能通過，但 production RAG 失效。 | Test fixtures 必須映射 production vector dimensions。 |
| P1-H | GCP-B 可能只停留在被動 fallback。 | Active-active 設計無法落地。 | 透過 policy 讓 GCP-B 承擔 batch、embedding、shadow、canary lanes。 |

### 5.3 P2：產品化與長期可維護性

| ID | 風險 | 影響 | 必要方向 |
| --- | --- | --- | --- |
| P2-A | AwoooP frontend i18n 不完整，IA 不一致。 | Operator experience 不專業且脆弱。 | 對齊 UI 文字、sidebar、routes 與 workflow labels。 |
| P2-B | Operator Console 缺少深度 trace/journal views。 | Operators 無法解釋 AI 為什麼做出某個決策。 | 加入 run step journal、trace spans、model/tool/cost panes。 |
| P2-C | Error code taxonomy 不完整。 | Frontend 與 channels 無法呈現可行動狀態。 | 定義 auth、schema、budget、MCP、routing、approval、RAG 的 platform error codes。 |
| P2-D | Docs 與 runtime 可能漂移。 | 未來 sessions 會重複同樣盤點。 | ADR、LOGBOOK、inventory 與 release checklists 必須連到 commits。 |

## 6. 對先前盤點的修正

消化早期 12-agent inventories 時，必須套用以下修正：

1. C21/C22 CronJob service account 與 image 問題在 worktree 中看起來已部分修正，但結案前必須對 live cluster state 驗證。
2. C1 `aioredis` 不一定在所有受影響路徑都是 top-level import；至少 Gate 5 runtime import 仍讓風險成立。
3. C2 的精準說法是：`tool_row is None` 時 blocked calls 可能跳過 audit，不只是資料庫 `NOT NULL` failure。
4. C12 對主要 embedding service 的描述部分過期，但 `knowledge_rag_service.py` 與 `playbook_rag.py` 仍需要驗證 1024 維一致性。

## 7. 12-agent 權責矩陣

| Owner | 範圍 | 第一個驗證點 |
| --- | --- | --- |
| Chief Architect | 總藍圖、依賴順序、紅區治理 | 本整合計畫已從 AwoooP master workplan 與 LOGBOOK 串接。 |
| Security | Auth、webhook spoofing、RLS、MCP security、token signing | Approval decision 不能被 body-only identity 偽造。 |
| MCP Gateway | Gateway chokepoint、audit、provider bypass、result schema | Direct provider call inventory 達到零個未追蹤 `forbid-new` 例外。 |
| K8s / SRE | CronJob、Kustomize、NetworkPolicy、RBAC、deployment verification | `kubectl diff` 與 live resource inventory 符合 GitOps 預期集合。 |
| DB / Migration | Alembic、RLS、JSONB、FK、approval race | RLS fail-closed tests 與 migration up/down 通過。 |
| RAG / KM | `bge-m3` 1024 維、backfill、PlayBook embedding | Production vector dimension 與 test fixtures 一致。 |
| AI Router / Ollama | Resolver、failover、direct URL cleanup、GCP-A/B/111 lanes | 新 alert route logs 證明 `GCP-A -> GCP-B -> 111 -> Gemini` 順序。 |
| Core / Trust | TrustEngine、RedisLock、UnitOfWork、feature flags | Pending approval 可存活於 pod restart 與 HPA multi-pod 執行。 |
| API Layer | Platform endpoints auth、CSRF、tenant boundaries | Platform APIs 會拒絕 unauthenticated 與 cross-project requests。 |
| Frontend / AwoooP | i18n、sidebar、approver identity、internal IP ban | `/zh-TW/awooop` 可正常 render，且 browser bundle 無 private `NEXT_PUBLIC_*` 外洩。 |
| QA / Test | 整合測試、no-mock 掃描、回歸矩陣 | 高風險路徑有 production-like integration tests，不只靠 mocks。 |
| Docs / Release | ADR、LOGBOOK、Memory handoff、runbooks、release checklist | 每個 wave 都有 release note、rollback path 與 live verification evidence。 |

## 8. 執行 waves

### Wave 0：正式收斂基準

目標：把跨 session 結論轉成單一營運真相來源。

工作：

- 新增本整合計畫。
- 從 `MASTER-WORKPLAN.md` 與 `AWOOOP-MONITORING-ALERTING-CONVERGENCE.md` 串接本文件。
- 除已授權的緊急修復外，不碰 runtime。
- 為每個高風險項目定義 owner 與 wave。

退出條件：

- 計畫已 commit。
- LOGBOOK 記錄整合基準。
- 下一個 implementation session 可直接從本文件開工，不必重推架構。

### Wave 1：P0 production-broken / security-critical

目標：防止自動化飛輪繞過治理。

進度：

- 2026-05-06：P0-L 第一段 enforcement patch 已落地。AwoooP approval token storage 與 MCP Gateway Gate 5 已改用 shared Redis pool，不再建立 runtime `aioredis.from_url()` client。
- 2026-05-06：P0-I 第一段 enforcement patch 已落地。AwoooP approval decide endpoint 已從 trusted operator headers 推導 `approver_id`，不再信任 frontend body；production 缺 `AWOOOP_OPERATOR_API_KEY` 時 fail closed。

工作：

- MCP Gateway bypass 與 audit gaps。
- Approval/MCP 路徑中的 `aioredis` runtime 相容性。
- `MCPToolResult` schema normalization。
- K8s command injection hardening。
- Webhook spoofing 與 platform API approval auth。
- RAG/KM/PlayBook 1024 維一致性。
- Production alert paths 的 Ollama direct `OLLAMA_URL` cleanup。

退出條件：

- 沒有 production MCP caller 可在未追蹤 `forbid-new` 例外下繞過 Gateway。
- Approval decide endpoint 使用 authenticated principal。
- Embedding dimensions 與 production 一致。
- Alert route logs 證明 Gemini 只在 GCP-A、GCP-B、111 全部失敗後才作為 fallback。

### Wave 2：P1 治理一致性

目標：讓 platform state 持久且 tenant-safe。

工作：

- RLS fail-closed 與 project context injection。
- Approval / Trust race fixes。
- TrustEngine state 從 process memory 移到 PostgreSQL。
- NetworkPolicy semantic cleanup。
- Kustomize resource coverage。
- Ollama failover centralization 與 GCP-B active-active usage。

退出條件：

- Cross-project read tests fail closed。
- Pending approval 可存活於 pod restart。
- Live cluster resources 符合 Git-managed resources。

### Wave 3：P2 產品化

目標：讓 AwoooP 成為專業可用的 operator console，而不是旁支 dashboard。

工作：

- AwoooP i18n 與 sidebar IA。
- Run step journal 與 trace view。
- Platform error code taxonomy。
- Alembic 與 migration discipline。
- Internal IP bundle checks。
- Regression matrix 與 release checklists。

退出條件：

- Operator 能從 alert 到 MCP execution 到 KM feedback 解釋一次 run。
- Frontend user-facing strings 全部收斂到 i18n，不在元件內硬編碼。
- Release checklist 串起 commit、image、route health 與 live URL verification。

## 9. Wave 依賴

```text
Wave 0
  -> Wave 1 MCP/Auth/RAG/Ollama safety
      -> Wave 2 RLS/Trust/K8s state convergence
          -> Wave 3 Operator Console productization
```

Wave 1 綠燈且 Wave 2 tenant state fail-closed 前，不得把破壞性或自動修復路徑推進到 AwoooP enforcement。

## 10. Release 與驗證紀律

每個 wave 必須發布：

- 變更面
- runtime behavior 是否改變
- contract family
- migration posture：keep、mirror、wrap、replace、forbid-new
- rollback 或 disable flag
- 受影響 event types
- 風險等級
- live verification command 或 URL
- LOGBOOK entry

Frontend release 也必須驗證：

- `pnpm --filter @awoooi/web typecheck`
- `NEXT_PUBLIC_API_URL=https://awoooi.wooo.work pnpm --filter @awoooi/web build`
- 產出的 browser bundle 不得包含 private `NEXT_PUBLIC_*` internal IPs
- CD rollout 後檢查 live route status 與內容

AI routing release 也必須驗證：

- active pod environment
- provider route logs
- cost-bearing provider fallback order
- 只有在所有 configured Ollama lanes 都失敗，或 policy 明確允許 cloud fallback 時，`Gemini` 才能出現

## 11. 立即下一步

1. 將 `scripts/ops/deploy-alertmanager-config.sh` 納入 reboot/release checklist，並評估 `ops/alertmanager/**` 變更是否應由 CD 自動執行。
2. 持續推進 Wave 1 的 MCP Gateway bypass 與 MCP audit completeness，因為 production callers 仍可能繞過 gateway。
3. 每次 alert-path release 都必須驗證 GCP-A/GCP-B/111 Ollama routing，直到 EffectivePolicy 成為權威來源。
4. 新增 Sentry/Snuba post-reboot health gate：ClickHouse table existence、Snuba migration status、Kafka consumer offsets 必須納入 cold-start validation。
5. 新增 Alertmanager post-deploy live check：`amtool check-config`、container status、config-file mode；direct Telegram 必須維持 emergency-only，且目標只能是 SRE 群組。
