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

技術棧

層級	技術選型	版本要求	用途
AI 決策	Python + Google ADK	Python 3.11+	智能代理與決策制定
執行引擎	Go	Go 1.24+	高性能工具執行與橋接
通訊協議	gRPC + Protocol Buffers	-	跨語言服務通訊
可觀察性	Prometheus + Grafana + Alloy	-	統一監控與告警
容器化	Docker + Docker Compose	-	開發與部署環境

系統需求

開發環境

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

生產環境

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

📚 文檔導航

核心文檔體系

文檔	描述	適合讀者	AI 使用場景	更新頻率
AI協作指南	AI代理操作規範與協作流程	AI工程師、協作開發者	🤖 AI 必讀 - 協作規範與工作流程	每月
系統架構	系統架構與決策框架	架構師、技術負責人	🏗️ 理解系統設計 - 架構決策與職責劃分	每季
技術規格	詳細技術實作規範	開發者、實作者	⚙️ 實作參考依據 - API規格與配置	每週
開發任務	當前開發進度與任務	開發團隊、專案管理	📋 執行具體任務 - 任務清單與進度	每日

角色導向閱讀路徑

🆕 新使用者入門路徑

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/            # 🔧 自動化腳本

開發工作流程

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

🤝 社群與貢獻

貢獻指南

程式碼貢獻：請參考 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 檔案

Name		Name	Last commit message	Last commit date
Latest commit History 68 Commits
assets		assets
contracts		contracts
deploy		deploy
docs		docs
go-platform		go-platform
python-adk-runtime		python-adk-runtime
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
AGENT.md		AGENT.md
ARCHITECTURE.md		ARCHITECTURE.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
ROADMAP.md		ROADMAP.md
SPEC.md		SPEC.md
TASKS.md		TASKS.md
config.yaml.example		config.yaml.example
go.mod		go.mod
go.sum		go.sum

License

detectviz/detectviz-platform

Folders and files

Latest commit

History

Repository files navigation