Pagalavan17/Incident-Detection-Agent

# 🚨 事件响应与事后总结 Agent ## 🎯 项目概述 **事件响应与事后总结 Agent** 是一个由 AI 驱动的工程级 Copilot，它改变了工程团队检测、响应生产事件并从中学习的方式。 该系统不再依赖人工筛选和团队内部的隐性知识，而是： - **摄取**来自多个基础设施源的结构化和非结构化日志 - **检测**使用 AI 驱动的模式识别来发现异常 - **检索**从持久化的向量记忆 中检索相似的历史事件 - **分析**使用大型语言模型 分析根本原因 - **建议**提供经过 Enkrypt AI Guardrails 安全验证的修复措施 - **生成**自动生成结构化的事后总结报告 - **学习**持续学习——每一个已解决的事件都会丰富机构记忆 ## 🏛️ 架构概览 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Incident Response Agent │ │ │ │ ┌──────────┐ ┌──────────┐ ┌───────────────┐ ┌───────────┐ │ │ │ Log │──▶│ Anomaly │──▶│ RCA Engine │──▶│ Remediation│ │ │ │ Ingestion│ │Detection │ │ (Claude 3.5) │ │ (Enkrypt) │ │ │ └──────────┘ └──────────┘ └───────────────┘ └───────────┘ │ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ │ │ ┌────────────────────────────────────────────────────────────────┐ │ │ │ Mastra Orchestration Layer │ │ │ │ (Agents · Tools · Workflows · Memory) │ │ │ └────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────────────┐ │ │ │ Qdrant DB │ │ Post-Mortem │ │ OpenTelemetry │ │ │ │ (Vector Mem.) │ │ Generator │ │ (Tracing) │ │ │ └───────────────┘ └───────────────┘ └───────────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ ``` ### 核心设计原则 | 原则 | 应用 | |-----------|-------------| | **整洁架构** | 领域逻辑与基础设施隔离 | | **SOLID** | 每个服务都有单一、明确定义的职责 | | **类型安全** | 严格使用 TypeScript 并在各处使用 Zod 进行运行时验证 | | **可观测性** | 通过 OpenTelemetry 对所有 Agent 操作进行追踪 | | **安全第一** | Enkrypt AI 验证每一个由 LLM 生成的修复操作 | | **机构记忆** | Qdrant 将每个事件存储为可搜索的向量 | ## 🛠️ 技术栈 | 层级 | 技术 | 用途 | |-------|-----------|---------| | **运行时** | Node.js 20+ | 原生 ESM，现代 JS 运行时 | | **语言** | TypeScript 5.7 | 严格的类型安全 | | **Web 框架** | Express 4 | 轻量级 HTTP API | | **AI 编排** | Mastra 0.10 | Agent 工作流、工具、记忆 | | **主要 LLM** | Anthropic Claude 3.5 | 根因分析 (RCA) 与事后总结生成 | | **Embeddings** | OpenAI text-embedding-3-small | 语义相似度搜索 | | **向量数据库** | Qdrant 1.13 | 持久化机构记忆 | | **安全性** | Enkrypt AI Guardrails | LLM 输出验证 | | **验证** | Zod 3 | 运行时 schema 强制执行 | | **可观测性** | OpenTelemetry | 分布式追踪 | | **日志器** | Pino | JSON 结构化日志 | | **容器** | Docker + Compose | Qdrant 本地开发环境 | ## 📁 文件夹结构 ``` incident-response-agent/ │ ├── src/ # All application source code │ ├── index.ts # Application entry point │ │ │ ├── config/ # Environment & app configuration │ ├── core/ # Domain models, interfaces, base classes │ ├── events/ # Event emitters & internal event bus │ ├── models/ # Data transfer objects & domain entities │ ├── types/ # Shared TypeScript type definitions │ ├── utils/ # Pure utility functions │ │ │ ├── services/ # Business logic services │ │ ├── logs/ # Log ingestion & normalisation │ │ ├── anomaly/ # Anomaly detection engine │ │ ├── qdrant/ # Qdrant client & collection management │ │ ├── retrieval/ # Semantic similarity search │ │ ├── embeddings/ # Embedding generation (OpenAI) │ │ ├── llm/ # LLM orchestration (Claude, OpenAI) │ │ └── enkrypt/ # Enkrypt AI guardrails integration │ │ │ ├── mastra/ # Mastra AI framework layer │ │ ├── agents/ # Mastra agent definitions │ │ ├── tools/ # Mastra tool definitions │ │ └── workflows/ # Mastra workflow definitions │ │ │ ├── api/ # Express HTTP API layer │ │ ├── controllers/ # Request handlers │ │ ├── routes/ # Route definitions │ │ └── middleware/ # Auth, validation, error handling │ │ │ └── scripts/ # One-off operational scripts │ ├── generateLogs.ts # Synthetic log data generator │ ├── setupQdrant.ts # Qdrant collection bootstrapper │ └── seedQdrant.ts # Historical incident seeder │ ├── docs/ # Architecture docs, ADRs, diagrams ├── data/ # Raw & processed log data (gitignored) ├── reports/ # Generated post-mortem reports (gitignored) ├── tests/ # Unit and integration tests ├── docker/ # Dockerfile & container configs (future) │ ├── package.json # Dependencies & npm scripts ├── tsconfig.json # TypeScript (type-check only) ├── tsconfig.build.json # TypeScript (production emit) ├── docker-compose.yml # Qdrant local infrastructure ├── .env.example # Environment variable template └── .gitignore # Git exclusion rules ``` ## ⚙️ 安装说明 ### 前置条件 | 工具 | 版本 | 安装 | |------|---------|---------| | Node.js | ≥ 20.0.0 | [nodejs.org](https://nodejs.org) | | npm | ≥ 10.0.0 | 随 Node.js 附带 | | Docker | ≥ 24.0 | [docker.com](https://docs.docker.com/get-docker/) | | Docker Compose | ≥ 2.20 | 随 Docker Desktop 附带 | ### 设置步骤 ``` # 1. Clone 仓库 git clone https://github.com/your-org/incident-response-agent.git cd incident-response-agent # 2. 安装依赖 npm install # 3. 创建本地环境文件 cp .env.example .env # → 打开 .env 并填写您的 API keys # 4. 启动 Qdrant 向量数据库 docker compose up -d # 5. 验证 Qdrant 是否健康 curl http://localhost:6333/healthz # → 预期结果：OK # 6. 运行 type-checker 以验证项目设置 npm run typecheck ``` ## 🚀 本地运行 ``` # 启动开发服务器（通过 tsx watch 进行 hot-reload） npm run dev # 在不启动服务器的情况下进行类型检查 npm run typecheck # Lint 源代码 npm run lint # 为生产环境构建 npm run build # 启动生产构建 npm start ``` ## 🐳 Docker 设置 `docker-compose.yml` **仅运行 Qdrant** —— 应用程序通过 npm 脚本原生运行，以提供最佳的开发体验（快速的热重载、原生调试器、无需重新构建镜像）。 ``` # 在后台启动 Qdrant docker compose up -d # 检查容器状态和健康状态 docker compose ps # 查看 Qdrant 日志 docker compose logs -f qdrant # 停止容器（数据保留在命名卷中） docker compose down # 停止容器并销毁所有向量数据（请谨慎使用！） docker compose down -v ``` ### Qdrant Web UI 启动后，可以通过以下地址访问内置的 Qdrant 仪表板： → **http://localhost:6333/dashboard** ### 端口参考 | 端口 | 协议 | 服务 | |------|----------|---------| | `6333` | HTTP REST | Qdrant REST API 和仪表板 | | `6334` | gRPC | Qdrant gRPC API | | `3000` | HTTP | 事件 Agent Express API | ## 🛡️ 环境变量 | 变量 | 必需 | 描述 | |----------|----------|-------------| | `NODE_ENV` | ✅ | 运行环境 (`development` \| `production`) | | `PORT` | ✅ | Express 服务器端口 (默认: `3000`) | | `ANTHROPIC_API_KEY` | ✅ | 用于 RCA 和报告生成的 Claude API 密钥 | | `OPENAI_API_KEY` | ✅ | 用于生成 embedding 的 OpenAI 密钥 | | `ENKRYPTAI_GUARDRAILS_API_KEY` | ✅ | 用于安全验证的 Enkrypt AI 密钥 | | `QDRANT_URL` | ✅ | Qdrant REST URL (默认: `http://localhost:6333`) | | `QDRANT_API_KEY` | ⬜ | 仅 Qdrant Cloud 部署需要 | | `OTEL_EXPORTER_OTLP_ENDPOINT` | ⬜ | 追踪收集器 endpoint | ## 🗺️ 开发路线图 ### ✅ 模块 1 — 项目初始化 (第 1 天) ← *您当前的位置* - [x] 仓库结构与文件夹脚手架 - [x] 包含所有生产环境依赖的 `package.json` - [x] 严格的 TypeScript 配置 - [x] 用于 Qdrant 的 Docker Compose - [x] 环境变量模板 - [x] README 与项目文档 ### 🔲 模块 2 — 配置与类型系统 - [ ] 使用 Zod 验证的环境加载器 (`src/config/env.ts`) - [ ] 用于事件、日志、embedding 的共享 TypeScript 类型 - [ ] 在开发环境下带有美化打印的 Pino 日志记录器初始化 - [ ] OpenTelemetry 追踪器引导程序 ### 🔲 模块 3 — 日志摄取服务 - [ ] 日志规范化 pipeline - [ ] 多源日志适配器 (CloudWatch, Datadog, 原始 JSON) - [ ] 合成日志生成脚本 ### 🔲 模块 4 — 向量记忆 - [ ] Qdrant collection 设置脚本 - [ ] 使用 OpenAI 的 embedding 服务 - [ ] 历史事件种子数据填充 ### 🔲 模块 5 — Mastra Agent 核心 - [ ] 事件响应 Agent 定义 - [ ] RCA 工具、检索工具、异常工具 - [ ] Mastra 工作流编排 ### 🔲 模块 6 — 安全与验证 - [ ] Enkrypt AI guardrails 集成 - [ ] 修复操作验证器 ### 🔲 模块 7 — 事后总结生成器 - [ ] 结构化报告模板 - [ ] 由 Claude 驱动的生成 - [ ] Markdown 与 PDF 导出 ### 🔲 模块 8 — REST API - [ ] 用于事件提交的 Express 路由 - [ ] 用于实时 Agent 更新的 WebSocket - [ ] 认证 middleware ### 🔲 模块 9 — 前端 - [ ] Next.js 仪表板 - [ ] 实时事件时间线 - [ ] 事后总结查看器 ## 📄 许可证 MIT © HiDevs 团队 — HiDevs × Mastra 黑客松 2024

标签：AI智能体, LLMOps, MITM代理, SOC控制台, 根因分析, 用户代理, 自动化应急响应, 自动化攻击, 请求拦截, 运维自动化