OutSkill-Hackathon-Team-11/CrewOps-React

# CrewOps — 多智能体 DevOps 事件分析套件 ## 🎯 问题陈述 现代生产系统每分钟会产生数千条日志。值班工程师面临着以下挑战： - 无差别告警噪音导致的告警疲劳 - 在仪表盘、运维手册和 JIRA 之间频繁切换上下文 - 在压力下进行缓慢的手动根因分析 **CrewOps** 能将原始日志流转化为果断的行动——分类、分流、根因分析、修复建议、运维手册生成、工单创建和通知——全过程不到 60 秒。 ## 🏗️ 系统架构 ### 智能体流水线概述 ``` Raw Logs (text or file) │ ▼ ┌───────────────────────────────────────────────────────────────────┐ │ LangGraph StateGraph │ │ │ │ START ──► [Classifier] ──► [Severity Assessor] │ │ │ │ │ ┌─────────────┴──────────────┐ │ │ P1/P2 (full_pipeline) P3/P4 (summary) │ │ ▼ ▼ │ │ [Root Cause Analyst] [Cookbook Agent] │ │ (RAG-grounded, gpt-4o) │ │ │ │ [Notification] │ │ [Remediation Planner] │ │ │ (gpt-4o) │ END │ │ ▼ │ │ [Cookbook Synthesizer] │ │ (gpt-4o-mini) │ │ │ │ │ ┌─────────┴─────────┐ ← parallel fan-out │ │ ▼ ▼ │ │ [JIRA Agent] [Notification Agent] │ │ │ │ │ │ END END │ └───────────────────────────────────────────────────────────────────┘ │ │ │ ▼ ▼ ▼ LangSmith Traces JIRA Ticket Slack / n8n Alert ``` ### Mermaid 工作流图 ``` flowchart TD A([Raw Logs]) --> B[Classifier\ngpt-4o-mini] B --> C[Severity Assessor\ngpt-4o-mini] C --> D{Severity Router} D -- "P1 / P2\nfull_pipeline" --> E[Root Cause Analyst\ngpt-4o + RAG] E --> F[Remediation Planner\ngpt-4o] F --> G[Cookbook Synthesizer\ngpt-4o-mini] D -- "P3 / P4\nsummary_only" --> G G --> H[JIRA Agent\nADF ticket] G --> I[Notification Agent\nn8n → Slack] H --> Z([END]) I --> Z subgraph RAG [RAG Layer] KB[(LanceDB\nVector Index)] HF[HuggingFace\nBAAI/bge-small-en-v1.5] end E -. retrieves context .-> KB KB -. indexed by .-> HF subgraph Observability LS[LangSmith\nTrace Dashboard] end B & C & E & F & G -. traced .-> LS ``` ### 条件路由逻辑 | 严重程度 | 分支 | 调用的智能体 | |----------|--------|----------------| | **P1 / P2** | `full_pipeline` | Classifier → Severity → Root Cause → Remediation → Cookbook → **JIRA + Notification** | | **P3 / P4** | `summary_only` | Classifier → Severity → Cookbook → **仅通知** | ## 🤖 智能体名册 | # | 智能体 | 节点名称 | 模型 | 职责 | |---|-------|-----------|-------|------| | 1 | **Classifier** (分类器) | `classifier` | `gpt-4o-mini` (快速) | 对日志类型进行分类；生成结构化的事件摘要 | | 2 | **Severity Assessor** (严重程度评估器) | `severity` | `gpt-4o-mini` (快速) | 分配 P1–P4 优先级；提取关键问题；设置 `approval_required` | | 3 | **Root Cause Analyst** (根因分析师) | `root_cause` | `gpt-4o` (推理) | 基于 RAG 从 LanceDB 知识库进行深度 RCA | | 4 | **Remediation Planner** (修复规划器) | `remediation` | `gpt-4o` (推理) | 基于 RCA 输出制定逐步的修复计划 | | 5 | **Cookbook Synthesizer** (运维手册生成器) | `cookbook` | `gpt-4o-mini` (生成) | 根据完整事件上下文生成运维手册 / SOP | | 6 | **JIRA Agent** (JIRA 代理) | `jira` | — | 创建 ADF 格式的 JIRA 工单（模拟或实时） | | 7 | **Notification Agent** (通知代理) | `notification` | — | 通过 n8n Incoming Webhook 发布 Slack Block Kit 告警 | ## 🎨 用户界面与操作控制台 CrewOps 具有高保真度、未来感十足的基于 React 的仪表盘，专为高风险的 DevOps 环境设计。如需完整的视觉分解，请参阅 [官方技术报告](./CrewOps_Official_Report.html)。 ### 1. 主仪表盘 (`/dashboard`) *事件接入的指挥中心* - **多格式接入：** 支持原始文本、文件上传（log、txt、json）以及实时流模拟。 - **智能体实时进度流：** 7 个智能体流水线的实时可视化。观看 **Classifier** 识别故障，**Severity Assessor** 对风险进行分流，以及 **Analyst** 检索 RAG 上下文。 - **结构化情报卡：** 结果以适合管理层的格式呈现，详细说明事件摘要、根因分析和逐步的修复计划。 ### 2. 分析中心 (`/dashboard/analytics`) *面向 SRE 经理的数据驱动洞察* - **性能基准测试：** 实时 MTTR（平均解决时间）图表，将 CrewOps 的自主响应时间与行业标准的手动基准进行比较。 - **运维健康状况：** 直观跟踪智能体准确率、单次事件成本（token 使用量）以及基础设施中的严重程度分布。 - **趋势分析：** 识别 k8s 或 cloudwatch 日志中反复出现的故障模式和热点。 ### 3. RAG 调优工作室 (`/dashboard/rag`) *开发者的控制平面* - **向量索引管理：** 直接查看 **LanceDB** 向量存储。管理知识块、更新文档并实时重新索引知识库。 - **嵌入沙盒：** 通过使用自然语言查询向量索引来测试检索基础。验证 **Analyst** 是否能访问正确的故障排查手册。 - **模型编排：** 为流水线中的各个智能体配置温度设置和模型选择（例如 gpt-4o 与 Claude）。 ## 📄 官方文档 如需全面的技术白皮书、系统架构图和管理层概述，请查看： **[CrewOps 官方技术报告](./CrewOps_Official_Report.html)** ## 🗂️ 状态模式 (`CrewOpsState`) 所有 7 个节点共享一个单一的 `TypedDict` 状态。累加字段使用 `operator.add` reducer，从而实现安全的并行扇出。 ``` CrewOpsState ├── Input │ ├── raw_logs: str # Original log text │ └── metadata: dict # Filename, timestamp, user │ ├── Classification │ ├── log_summary: str # Structured classifier report │ └── log_type: str # k8s | nginx | cloudwatch | application | mixed │ ├── Severity │ ├── severity: str # P1 | P2 | P3 | P4 │ ├── severity_rationale: str │ └── critical_issues: list[str] ← add() # Accumulates across parallel branches │ ├── Root Cause (P1/P2 only) │ ├── rag_context: list[str] ← add() # Retrieved KB chunks │ └── root_cause_analysis: str │ ├── Remediation (P1/P2 only) │ └── remediation_plan: str │ ├── Cookbook │ └── cookbook: str # Runbook / SOP │ ├── Human Approval │ ├── approval_required: bool # True for P1/P2 │ └── approval_status: str # pending | approved | auto_approved │ ├── JIRA │ └── jira_tickets: list[dict] ← add() │ ├── Notifications │ └── notifications_sent: list ← add() │ └── Pipeline Metadata ├── pipeline_status: dict ← merge() # Per-agent timing + status └── errors: list ← add() # Non-fatal error accumulator ``` ## 🚀 快速开始 ### 前置条件 - Python 3.11+ - OpenRouter API key（用于访问 LLM） - JIRA API token *（可选 — 默认为模拟模式）* - Slack Incoming Webhook URL *（可选 — 默认为模拟模式）* - 带有 `slack-alert` webhook 的 n8n 实例 *（可选）* ### 🚀 启动指挥中心 #### 1. 后端 (FastAPI) ``` cd backend python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt pip install -e . # 从 /backend 运行 FastAPI server uvicorn api.main:app --reload --port 8000 # Swagger UI: http://localhost:8000/docs ``` #### 2. 前端 (React + Vite) ``` # 在一个新终端中（根目录） npm install npm run dev # Vite app: http://localhost:5173 ``` ### 配置环境 ``` cp .env.example .env ``` 编辑 `.env`： ``` # 必需 OPENROUTER_API_KEY=sk-or-... LANGCHAIN_API_KEY=ls__... LANGCHAIN_TRACING_V2=true LANGCHAIN_PROJECT=CrewOps-Hackathon # JIRA (设置 JIRA_MOCK_MODE=false 以启用 live tickets) JIRA_MOCK_MODE=true JIRA_SERVER=https://your-org.atlassian.net JIRA_EMAIL=you@example.com JIRA_API_TOKEN=... JIRA_PROJECT_KEY=OPS # Notifications (设置 NOTIFICATION_MOCK_MODE=false 以启用 live alerts) NOTIFICATION_MOCK_MODE=true N8N_WEBHOOK_URL=https://your-n8n/webhook/slack-alert SLACK_WEBHOOK_URL=https://hooks.slack.com/services/... ``` ### 3. 运行选项 **Streamlit 仪表盘（推荐）** ``` streamlit run app.py # → http://localhost:8501 ``` **CLI / 无头模式** ``` python run.py ``` **交互式 Notebook** ``` jupyter notebook Devops_Logs_Agent_Analyser.ipynb # 自上而下运行所有 cell (本地开发 — 无需 Colab) ``` ## 🛠️ 技术栈 | 层级 | 技术 | 备注 | |-------|-----------|-------| | 智能体编排 | LangGraph ≥0.3.0 | 带有 TypedDict + reducer 的 `StateGraph` | | LLM 提供商 | OpenRouter | `gpt-4o-mini` (快速/生成)，`gpt-4o` (推理) | | 可观测性 | LangSmith | 自动追踪所有 7 个节点 | | 向量存储 | LanceDB ≥0.8 | 本地磁盘 `lancedb/` 目录 | | 嵌入 | `BAAI/bge-small-en-v1.5` | 本地 HuggingFace — **RAG 无需 OpenAI key** | | RAG 框架 | LlamaIndex ≥0.11 | 索引 `data/knowledge_base/` 中的 Markdown 文档 | | JIRA 集成 | `jira` ≥3.8 | ADF 格式的工单描述 | | 通知 | n8n Incoming Webhook → Slack | Block Kit 富文本消息 | | 仪表盘 UI | Streamlit ≥1.45 | 通过 `st.navigation()` 实现多页面 | | 测试 | pytest ≥8.0 | 跨 6 个测试文件的 166 个测试，零 LLM 调用 | ## 项目结构 ``` CrewOps-React/ |-- package.json # React/Vite scripts and frontend dependencies |-- vite.config.js # Vite configuration |-- index.html # React app entry HTML |-- README.md | |-- src/ # React frontend at repo root | |-- main.jsx # React bootstrap | |-- App.jsx # App shell and routing | |-- index.css # Global styles | |-- store.js # Zustand app state and API streaming logic | | | |-- config/ | | `-- api.js # Default API and websocket URLs | | | |-- pages/ | | |-- LandingPage.jsx # Public landing page | | |-- Home.jsx # Dashboard, log input, live stream, results | | |-- Analytics.jsx # Incident and pipeline analytics | | |-- RagTuning.jsx # RAG/LLM tuning studio | | `-- Docs.jsx # Product/API documentation page | | | |-- components/ | | |-- Sidebar.jsx | | |-- PipelineProgress.jsx | | |-- AgentCard.jsx | | |-- KpiCard.jsx | | |-- IssuesTable.jsx | | `-- CustomSelect.jsx | | | |-- data/ | | |-- mockData.js | | `-- tuningConfig.js | | | `-- services/ | `-- openrouter.js | `-- backend/ # Python backend and original backend app files |-- requirements.txt # Backend dependency list |-- pyproject.toml # Backend package metadata |-- pytest.ini # Backend test config |-- run.py # CLI/headless pipeline runner |-- stream_logs.py # Live log stream helper |-- app.py # Streamlit entrypoint, if used |-- slack-template-n8n.json # Importable n8n workflow template |-- Devops_Logs_Agent_Analyser.ipynb # Interactive notebook | |-- api/ # FastAPI application | |-- __init__.py | |-- main.py # FastAPI app, /analyze, /health, websocket, webhook routes | `-- tuning.py # /tuning models, presets, validation, pipeline run APIs | |-- pages/ # Legacy Streamlit pages | |-- home.py | |-- 1_Analytics.py | `-- 2_RAG_Tuning.py | |-- src/crewops/ # Core CrewOps agent package | |-- state.py # CrewOpsState TypedDict + reducers | |-- agents.py # 7 node functions | |-- graph.py # LangGraph build_graph() + severity router | |-- prompts.py # Prompt templates | |-- parsers.py # Severity, ADF, Slack block parsers | `-- rag.py # LanceDB + LlamaIndex + HuggingFace embeddings | |-- data/ | |-- knowledge_base/ # RAG source Markdown docs | `-- sample_logs/ # Demo log scenarios | `-- tests/ # Backend unit/integration tests |-- test_state.py |-- test_parsers.py |-- test_agents.py |-- test_graph.py |-- test_rag.py `-- test_integrations.py ``` ## 🔧 关键设计决策 ### TypedDict 状态（而非 Pydantic BaseModel） LangGraph 的 `Annotated[list, operator.add]` reducer 需要 `TypedDict`。使用 `Pydantic BaseModel` 会破坏并行扇出——这是在开发过程中发现的一个关键 bug。 ### 3 层 LLM 工厂 | 层级 | 模型 | 温度 | 使用者 | |------|-------|-------------|---------| | `llm_fast` | `gpt-4o-mini` | 0.1 | Classifier，Severity | | `llm_reasoning` | `gpt-4o` | 0.2 | Root Cause，Remediation | | `llm_generation` | `gpt-4o-mini` | 0.3 | Cookbook | ### 依赖注入节点 `build_graph()` 接受可选的 `*_fn` 参数。在生产环境中，JIRA 和 Notification 节点通过 `functools.partial` 预绑定了 `.env` 中的值。在测试中，确定性的 fake 函数替换了所有 7 个节点——**测试套件中零 LLM 调用**。 ### 默认模拟模式 默认情况下 `JIRA_MOCK_MODE=true` 且 `NOTIFICATION_MOCK_MODE=true`——流水线无需凭证即可完全运行。在 `.env` 中将两者均设置为 `false` 以启用实时集成。 ### 本地嵌入（RAG 无需 OpenAI Key） RAG 通过 `llama-index-embeddings-huggingface` 使用 `BAAI/bge-small-en-v1.5`。首次索引构建（约 40 秒）会下载模型；后续运行使用本地 `lancedb/` 缓存。 ### 通过 Incoming Webhook 的 n8n 通知 Slack 集成使用通过 n8n 的 HTTP Request 节点发布的 **Incoming Webhook** URL——避免了 Slack OAuth bot token 工作流中常见的 `not_allowed_token_type` 错误。 ## 📊 演示场景 | 场景 | 文件 | 日志类型 | 预期严重程度 | 关键输出 | |----------|------|-----------|-------------------|-------------| | **支付级联故障** | `mixed_incident.log` | application + redis + k8s | **P1 CRITICAL** | 完整的 RCA，JIRA P1 工单，Slack 告警，修复计划 | | **K8s CrashLoop OOMKilled** | `k8s_crashloop.log` | kubernetes | **P2 HIGH** | 内存分析，资源限制运维手册，JIRA P2 工单 | ## 🧪 测试套件 ``` # 运行所有 166 个 tests pytest # 运行特定 module pytest tests/test_graph.py -v # 附带 coverage 运行 pytest --cov=src/crewops --cov-report=term-missing ``` | 测试文件 | 覆盖范围 | 关键测试项 | |-----------|--------------|-----------| | `test_state.py` | 状态模式，reducer | TypedDict 字段，`operator.add` 扇出安全性 | | `test_parsers.py` | 输出解析器 | 严重程度解析，ADF 构建器，Slack block 构建器 | | `test_agents.py` | 智能体节点 | 带有模拟 LLM 的全部 7 个节点 | | `test_graph.py` | 图拓扑与路由 | 注册的 7 个节点，条件路由器，端到端 P1/P4 测试 | | `test_rag.py` | RAG 流水线 | 索引构建，关键词回退，搜索结果 | | `test_integrations.py` | JIRA + 通知 | 模拟模式，实时模式，错误处理 | ## 🔌 n8n Slack 集成设置 将 `slack-template-n8n.json` 导入到您的 n8n 实例中： 1. **创建 Slack Incoming Webhook**：[api.slack.com/apps](https://api.slack.com/apps) → 您的应用 → Incoming Webhooks → Add to workspace → 复制 URL 2. **在 `.env` 中设置**：`SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T.../B.../...` 3. **设置 n8n webhook**：`N8N_WEBHOOK_URL=https://your-n8n/webhook/slack-alert` 4. **导入工作流**：n8n → Workflows → Import → 选择 `slack-template-n8n.json` 5. **激活**该工作流 该模板使用 HTTP Request 节点直接 POST 到 Slack Incoming Webhook——无需 OAuth 凭证。 ## 🔮 未来增强计划 - [ ] 用于自动修复执行的人机交互 (Human-in-the-loop) 审批节点 - [ ] 用于外部日志接入的 FastAPI REST 封装器 - [ ] 多集群 Kubernetes operator 集成 - [ ] PagerDuty + OpsGenie 通知渠道 - [ ] 通过时间序列嵌入进行历史事件关联 - [ ] 为基础设施配置修复自动生成 PR - [ ] 流式 UI — 通过 `graph.stream()` 实时展示智能体进度 ## 📜 许可证 ## 团队 ❤️ 团队成员：Sannith Kumar，Rakshit Rangarajan，Monalisa Das，Shaik Himan Johny，Charchit Bansal，Prakash Patil，Purushotham Boddu，Prathiba Katakol，Avinash Shyam。
*Built for the AI Post-Training Hackathon | CrewOps Team*

标签：AI, AIOps, Black Hat, DLL 劫持, GPT-4o, Incident Response, IT运维, JIRA集成, Kubernetes, LangGraph, LLM, Multi-Agent, n8n自动化, OpenAI, PyRIT, RAG, RCA, Slack通知, Socks5代理, SRE, StateGraph, Unmanaged PE, 严重性评估, 人工智能, 偏差过滤, 内存规避, 告警分类, 告警分诊, 告警疲劳, 多智能体系统, 大语言模型, 工作流自动化, 故障修复, 智能运维, 根因分析, 生产环境监控, 用户模式Hook绕过, 自动化代码审查, 自动化运维, 逆向工具