detectviz-platform

Detectviz Platform

文檔職責：作為專案入口與導航中心，提供專案概覽、快速開始指南和文檔導航地圖

文檔定位

• 目標受眾：新使用者、評估者、貢獻者、所有專案參與者
• 更新頻率：每個版本更新
• 版本：1.0.0
• 最後更新：2025-08-17

文檔關係

[README.md] (專案入口) → AGENT.md (AI協作規範) → ARCHITECTURE.md (系統架構) → SPEC.md (技術規格) → TASKS.md (開發任務)

閱讀路徑：

• 後續閱讀：AGENT.md - AI協作指南 - 了解AI協作規範
• 深入了解：ARCHITECTURE.md - 系統架構 - 理解系統設計
• 技術實作：技術實作 - 獲取實作細節

智能化 SRE 平台：基於 AI Agent 的全生命週期 SRE 解決方案

🚀 快速開始 (Quick Start)

本指南提供兩種快速入門路徑，請根據您的需求選擇：

• 路徑 A：體驗完整平台 (Docker) - 適合希望運行完整 SRE 監控堆疊並與平台互動的使用者。
• 路徑 B：設定開發環境 (本地) - 適合希望貢獻程式碼的開發者。

路徑 A：體驗完整平台 (Docker)

此方法將使用 Docker Compose 啟動所有後端服務（Grafana、Prometheus 等），並在本機運行 Detectviz 主程式。

步驟 1：啟動後端監控服務

# 1. 進入部署目錄
cd deploy

# 2. 複製環境變數檔案 (此為關鍵步驟)
# 注意：是將根目錄的 .env.example 複製到 deploy 目錄下
cp ../.env.example .env

# 3. 啟動所有服務 (此過程可能需要幾分鐘)
make start

# 4. 檢查服務狀態，確保所有服務 (Services) 的狀態為 "Up" 或 "healthy"
make status

提示：初次啟動，您無需修改 .env 檔案。服務啟動後，可訪問 Grafana 儀表板 (帳號: admin, 密碼: admin123)。

步驟 2：啟動 Detectviz 主程式

在另一個終端機視窗中，從專案根目錄執行以下指令：

# 5. 啟動 Detectviz 主程式 (包含 HTTP Demo)
# 此指令會讀取先前建立的 .env 檔案
source deploy/.env && \
    DETECTVIZ_HTTP_DEMO=1 \
    ./detectviz plugin serve --config config.yaml

步驟 3：驗證平台

# 6. 對 Detectviz 主程式發送測試請求
curl http://localhost:7777/business

# 7. 查詢 Tempo API，確認是否收到 trace 數據
# 預期應返回包含 traceID 的 JSON 數據
curl "http://localhost:3200/api/search"

✅ 設定完成！ 您現在擁有一個完整的本地監控與應用環境。

路徑 B：設定開發環境 (本地)

此方法將設定您的本機環境，以便直接修改和測試 Go/Python 原始碼，此路徑不會啟動後端監控服務。

步驟 1：安裝開發工具與依賴

# 1. 執行開發環境安裝腳本
# 此命令會安裝 protoc, buf, Go/Python 相關工具
make setup-development

步驟 2：驗證與生成程式碼

# 2. 執行契約健康檢查，確保 proto 檔案正確
make health-check-proto

# 3. 生成所有基於 proto 的 Go 和 Python 程式碼
make gen

步驟 3：驗證與生成程式碼

# 4. 執行契約健康檢查與程式碼生成
make health-check-proto && make gen

✅ 設定完成！ 成功執行後，您即可開始修改 go-platform 或 python-adk-runtime 的程式碼。若遇到問題，可嘗試執行 make fix-common-issues。

📋 專案概覽

核心價值

• 🧠 智能決策：AI Agent 自動分析系統狀態並制定 SRE 策略
• 🔄 全生命週期：事前預防 → 事中響應 → 事後複盤的完整 SRE 流程
• ⚡ 混合架構：Go 高性能執行引擎 + Python 智能決策大腦
• 🔍 統一可觀察性：整合 Logs、Metrics、Traces、Profiles 的全方位監控

系統架構概覽

graph TB
    subgraph "AI 決策層"
        A[Python ADK Runtime]
        B[多 Agent 協作]
        C[智能決策引擎]
    end
    
    subgraph "執行層"
        D[Go Platform Core]
        E[Tool Bridge]
        F[Plugin Host]
    end
    
    subgraph "數據層"
        G[Contracts SSOT]
        H[Metrics Provider]
        I[Grafana Alloy]
    end
    
    A --> D
    B --> E
    C --> F
    D --> G
    E --> H
    F --> I
    
    style A fill:#e1f5fe
    style D fill:#e8f5e8
    style G fill:#fff3e0

技術棧

系統需求

開發環境

• 作業系統：Linux/macOS/Windows (WSL2)
• 記憶體：最少 8GB，建議 16GB+
• 儲存空間：最少 10GB 可用空間
• 網路：需要網際網路連線以下載依賴

生產環境

• CPU：4 核心以上
• 記憶體：16GB 以上
• 儲存：SSD，50GB+ 可用空間
• 網路：穩定的內網連線

📚 文檔導航

核心文檔體系

角色導向閱讀路徑

🆕 新使用者入門路徑

README.md → 快速開始 → AGENT.md → ARCHITECTURE.md

目標：10分鐘內理解專案價值並完成基本設置

👨‍💻 開發者工作路徑

README.md → SPEC.md → TASKS.md → AGENT.md

目標：快速找到技術細節並開始開發工作

🏗️ 架構師評估路徑

README.md → ARCHITECTURE.md → SPEC.md → docs/architecture/

目標：全面理解系統設計與技術選型

🤖 AI 代理協作路徑

AGENT.md → ARCHITECTURE.md → SPEC.md → TASKS.md

目標：理解協作規範並執行開發任務

快速查找索引

🔍 按主題查找

• 架構設計：ARCHITECTURE.md → 系統架構設計
• API 規格：SPEC.md → API 規格與介面定義
• 開發環境：docs/guides/DEVELOPMENT_SETUP.md
• 部署指南：SPEC.md → 配置管理與模組規範
• 故障排除：SPEC.md → 故障排除與除錯指南

🎯 按任務類型查找

• 新功能開發：TASKS.md → 實作任務清單
• Bug 修復：TASKS.md → 問題追蹤與風險管理
• 性能優化：SPEC.md → 實作最佳實踐
• 測試驗證：docs/development/TESTING_GUIDELINES.md

• Go Platform：go-platform/README.md
• Python ADK Runtime：python-adk-runtime/README.md
• Contracts SSOT：contracts/README.md
• 依賴服務總覽：deploy/

📖 術語索引

• 完整術語對照表：詳見各文檔中的術語定義
• AI協作術語：參見 AGENT.md 中的術語定義
• 系統架構術語：參見 ARCHITECTURE.md 中的術語定義
• 技術實作術語：參見 SPEC.md 中的術語定義

🛠️ 開發指南

專案結構

detectviz-platform/
├── contracts/           # 📋 SSOT - 跨語言契約定義
│   ├── proto/          # Protocol Buffers 定義
│   ├── schemas/        # JSON Schema 規範
│   └── gen/            # 生成的程式碼
├── go-platform/        # ⚡ Go 平台核心
│   ├── cmd/            # 主程式入口
│   ├── internal/       # 內部套件
│   └── tools/          # 開發工具
├── python-adk-runtime/ # 🧠 Python ADK Runtime
│   ├── src/            # 核心程式碼
│   ├── agents/         # AI 代理實作
│   └── tools/          # 工具集合
├── deploy/             # 依賴服務總覽
├── docs/               # 📚 文檔體系
└── scripts/            # 🔧 自動化腳本

開發工作流程

1. 閱讀協作規範：AGENT.md - 理解 AI 協作模式
2. 理解系統架構：ARCHITECTURE.md - 掌握設計決策
3. 查看技術規格：SPEC.md - 獲取實作細節
4. 檢查開發任務：TASKS.md - 選擇工作項目
5. 執行開發工作：遵循 開發指導原則

🤝 社群與貢獻

貢獻指南

• 程式碼貢獻：請參考 GitHub Issues 和 GitHub Discussions
• 文檔改進：參見 docs/development/DOCUMENTATION_AUTOMATION.md
• 問題回報：使用 GitHub Issues
• 功能建議：使用 GitHub Discussions

社群資源

• 技術討論：GitHub Discussions
• 開發文檔：docs/ 目錄
• API 文檔：contracts/ 目錄
• 範例程式碼：各組件的 examples/ 目錄

📈 專案狀態

• 當前版本：v0.1.0-MVP
• 開發階段：Phase 3 - 事後複盤系統
• 完成進度：參見 TASKS.md
• 下一里程碑：完整 SRE 生命週期整合

🎯 核心設計原則

• 🔗 SSOT 契約優先：所有跨語言介面變更必須先更新 contracts/
• ⚖️ 職責分離：Agent 負責智能決策，Tool 負責具體執行
• 👁️ 可觀察性優先：統一收集 Logs/Traces/Metrics/Profiles
• 🧩 模組化設計：以模組卡規範管理組件分類與依賴關係
• 🤖 AI 友善：文檔結構化，支援 AI 代理自動化協作

📄 授權條款

MIT License - 詳見 LICENSE 檔案