awoooi/docs/awooop/AWOOOI-AWOOOP-AI-AUTONOMOUS-FLYWHEEL-INTEGRATION-PLAN.md

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. 共同目標迴路

目標閉環如下：

監控 / 告警
  -> 事件分類
  -> 規則匹配或規則建立
  -> 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 依賴

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 群組。