tianhg468/AI-Incident-Response-Engineer-

# AI 事件响应工程师 一个自主 Agent，负责为基于 Kubernetes 的服务进行生产事件的分析、诊断和修复。 ## 概述 本项目实现了一个 AI 驱动的事件响应系统，具备以下功能： - 通过 webhook 或 CLI 接收告警 - 通过 MCP 从可观测性和基础设施工具收集证据 - 通过回溯机制形成并验证关于根因的假设 - 在人工介入审批的前提下提出修复建议 - 执行已批准的修复操作 - 生成详尽的复盘报告 ## 核心特性 1. 带有回溯机制的**假设-验证循环**（而非线性流水线） 2. 在任何写操作前设置严格的**人工介入关卡** 3. 通过 LangGraph 检查点实现的**持久化状态**（调查过程可从重启中恢复） 4. 用于 runbook 关联和部署分析的**自定义 MCP 服务器** 5. 带有预设事件场景的**真实评估测试工具** ## 架构 ``` graph TD A[Intake] --> B[Evidence Gathering] B --> C[Diagnosis] C --> D[Verification] D -->|Refuted| C D -->|Confirmed| E[Recovery Proposal] D -->|Inconclusive| F[Escalate] E -->|Approved| G[Execution] E -->|Rejected| H[Post-Mortem] G --> H F --> H ``` ## 项目结构 ``` . ├── agent/ │ ├── graph.py # LangGraph wiring │ ├── state.py # State types │ ├── nodes/ # One file per node │ └── prompts/ # Versioned prompt templates ├── mcp_servers/ │ ├── mock/ # Fixture-based mock MCP servers │ │ ├── kubernetes.py │ │ ├── github.py │ │ ├── slack.py │ │ ├── observability.py │ │ └── README.md │ ├── registry.py # Mode-switching registry (eval/live) │ └── runbook_correlator/ # Custom MCP server + README ├── fixtures/ │ ├── scenarios/ # Per-scenario fixture data │ │ └── oom_after_deploy/ │ └── shared/ # Shared fixtures ├── webhook/ # FastAPI app ├── dashboard/ # Streamlit UI ├── evals/ │ ├── scenarios/ # Eval scenario definitions │ ├── runner.py │ └── rubric.py ├── docker-compose.yml ├── pyproject.toml └── README.md ``` ## 模拟 MCP 服务器 一个关键的架构决策：**Agent 并不关心它所交互的是真实的还是模拟的 MCP 服务器。** ``` # Agent 代码在两种模式下均可工作 from mcp_servers.registry import get_mcp_server registry = get_mcp_server() # MODE env var controls real vs mock result = registry.call_tool("kubernetes", "k8s_get_pod_status", {...}) ``` **在评估模式下**（`MODE=eval`）： - 模拟服务器从 `fixtures/scenarios/{scenario}/` 目录提供固定数据 - 提供确定、可复现的评估结果 - 无需外部依赖（Kubernetes、GitHub 等） - 在 CI/CD 中执行速度快 **在实时模式下**（`MODE=live`）： - 通过 stdio 或 HTTP 连接真实的 MCP 服务器 - 连接到真实的 Kubernetes 集群、GitHub API 等 - 用于生产环境的事件响应 这种双模式架构支持： - 无需真实基础设施即可进行开发和测试 - 具有已知真实基准的可复现评估场景 - 从评估环境平滑过渡到生产使用 详情请参见 [`mcp_servers/mock/README.md`](mcp_servers/mock/README.md)。 ## 使用真实 MCP 服务器的实时模式 **当设置 `MODE=live` 时，Agent 可以连接到真实的基础设施。** 这使得使用真实的 Kubernetes 集群、GitHub 仓库、Slack 工作区和可观测性平台进行生产事件响应成为可能。 ### 快速开始 ``` # 1. 将 MODE 设置为 live export MODE=live # 2. 配置 MCP server 路径 export MCP_K8S_SERVER=/path/to/kubernetes-mcp-server export MCP_GITHUB_SERVER=/path/to/github-mcp-server export MCP_SLACK_SERVER=/path/to/slack-mcp-server export MCP_OBSERVABILITY_SERVER=/path/to/observability-mcp-server # 3. 配置 credentials export GITHUB_TOKEN=ghp_your_token export SLACK_BOT_TOKEN=xoxb_your_token export KUBECONFIG=~/.kube/config export GRAFANA_API_KEY=your_key # 4. 运行调查 python -m agent.graph ``` ### 支持的 MCP 服务器 - **Kubernetes**：Pod 状态、日志、事件、Deployments - **GitHub**：Commits、PRs、diffs、文件内容 - **Slack**：消息、审批、通知 - **Observability**：指标、告警、服务健康状态 (Grafana/Datadog/Prometheus) - **Runbook Correlator**：自定义服务器（已内置） ### 工作原理 `MCPServerRegistry` 会根据 MODE 自动路由工具调用： ``` # Agent 代码完全无关特定实现 from mcp_servers.registry import get_mcp_server registry = get_mcp_server() # Reads MODE env var result = registry.call_tool("kubernetes", "k8s_get_pod_status", {...}) # MODE=eval → 使用基于 fixture 的 mocks # MODE=live → 连接到真实的 Kubernetes API ``` ### 安装指南 参见 [`mcp_servers/real/README.md`](mcp_servers/real/README.md) 了解以下内容： - 安装/构建 MCP 服务器 - 各服务的配置示例 - 身份验证设置 - 故障排除指南 - 安全注意事项 ## 检查点与可恢复性 **调查过程可以挺过进程重启。** LangGraph 的检查点机制会将完整的 Agent 状态持久化到数据库中，从而支持： - 在重启之间暂停和恢复调查 - 查看带有完整记录的历史调查 - 调试并重放特定的调查步骤 - 跟踪多个并发调查 ### 工作原理 ``` from agent.graph import create_incident_response_graph from agent.utils.checkpointing import get_checkpointer, get_thread_id # 创建 checkpointer (默认为 SQLite) checkpointer = get_checkpointer() # 创建启用 checkpointing 的 graph graph = create_incident_response_graph(checkpointer=checkpointer) # 使用唯一的 thread_id 开始调查 thread_id = get_thread_id("alert_12345") config = {"configurable": {"thread_id": thread_id}} # 运行调查 result = graph.invoke(initial_state, config=config) # === 在进程重启之后 === # 创建新的 graph 和 checkpointer 实例 checkpointer = get_checkpointer() graph = create_incident_response_graph(checkpointer=checkpointer) # 使用相同的 thread_id 从 checkpoint 恢复 state = graph.get_state(config) # 从上次中断的地方继续调查 ``` ### 配置 通过环境变量设置检查点模式： ``` # SQLite (开发和测试的默认选项) CHECKPOINT_MODE=sqlite CHECKPOINT_DB_PATH=./data/checkpoints.db # Postgres (用于生产环境) CHECKPOINT_MODE=postgres DATABASE_URL=postgresql://user:password@localhost:5432/incident_response # In-memory (无持久化) CHECKPOINT_MODE=memory ``` ### 测试可恢复性 ``` python tests/test_checkpointing.py ``` 这演示了： 1. 在启用检查点的情况下启动调查 2. 模拟进程重启 3. 从准确的检查点恢复 4. 验证状态的连续性 ## Dashboard（仪表盘） **使用 Streamlit 仪表盘实时监控调查过程。** 查看活动和历史调查、跟踪指标并分析 Agent 性能。 ### 快速开始 ``` # 首先运行一些调查 export MODE=eval SCENARIO=oom_after_deploy python -m agent.graph # 启动 dashboard streamlit run dashboard/app.py # 在浏览器中打开 http://localhost:8501 ``` ### 功能特性 **概览页面：** - 汇总指标（总数、已完成、已升级、平均轮次） - 分布图（按严重程度、按服务） - 可选的实时自动刷新 **调查列表：** - 按状态、严重程度、服务进行筛选 - 关键指标快速查看 - 一键访问详情 **调查详情：** - 完整的事件信息 - 包含验证状态的所有假设 - 恢复建议和审批信息 - 完整的调查时间线 ### Dashboard 视图示例 **跟踪的指标：** - 总调查数：15 - 完成率：80% - 升级率：20% - 平均验证轮次：1.8 **过滤器：** - 状态：completed, escalated, in_progress - 严重程度：critical, high, medium, low - 服务：payment-service, user-service 等 详细文档请参见 [`dashboard/README.md`](dashboard/README.md)。 ## 设置 ### 前置条件 - Python 3.11+ - Docker 和 Docker Compose - pip 或 uv ### 安装 ``` # 克隆 repository git clone cd ai-incident-response # 安装依赖 pip install -e ".[dev]" # 设置环境变量 cp .env.example .env # 使用你的 API keys 编辑 .env ``` ### 本地运行 ``` # 1. 设置环境变量 export MODE=eval export SCENARIO=oom_after_deploy export CHECKPOINT_MODE=sqlite # 2. 运行调查 python -m agent.graph # 3. 启动 dashboard streamlit run dashboard/app.py # 4. (可选) 启动用于生产环境的基础设施 docker-compose up -d # 5. (未来) 运行 webhook server # uvicorn webhook.main:app --reload ``` ## 开发状态 **当前阶段：** 第 10 步 - Dashboard ✅ - [x] 定义状态类型 - [x] 包含空操作节点的骨架图 - [x] 创建节点占位符 - [x] 初始化 Prompt 模板 - [x] 模拟 MCP 服务器 (Kubernetes, GitHub, Slack, Observability) - [x] 支持模式切换的 MCP 服务器注册表 - [x] 带有固定数据的示例场景 (oom_after_deploy) - [x] 自定义 Runbook Correlator MCP 服务器 - [x] find_runbook 工具 (带有 YAML frontmatter 的 markdown 语料库) - [x] correlate_deploys 工具 (多因素嫌疑评分) - [x] similar_past_incidents 工具 (使用 sentence-transformers + FAISS 进行向量搜索) - [x] 全面的协议级文档 - [x] 端到端正常路径 - [x] Intake 节点从场景加载事件 - [x] Evidence 收集调用模拟 MCP 服务器 - [x] Diagnosis 使用 LLM 生成假设 - [x] Verification 确认第一个假设 - [x] Recovery 建议在评估模式下自动批准 - [x] Execution 和 post-mortem 完成工作流 - [x] 完整的测试场景运行器 - [x] **带回溯的验证循环** ⭐ 关键差异化优势 - [x] 使用 LLM 和针对性检查进行真实验证 - [x] 严格应用证伪标准 - [x] 被反驳的假设触发回溯到诊断阶段 - [x] 被确认的假设进入恢复阶段 - [x] 达到最大轮次后升级 (共 5 次，3 次无定论) - [x] 展示了非线性图执行 - [x] 验证回溯行为的测试套件 - [x] **人工介入审批流程** 🔒 安全关卡 - [x] 带有风险级别的操作类型白名单 - [x] 支持 Slack/CLI 回退的 ApprovalHandler - [x] 评估模式下自动审批以便测试 - [x] 完整的审计跟踪 (status, reasoning, decided_by, method) - [x] 与 recovery_proposal 节点集成 - [x] 全面的测试覆盖 - [x] **检查点与可恢复性** 💾 持久性 - [x] 使用 SQLite/Postgres 的 LangGraph 检查点 - [x] 基于线程的调查跟踪 - [x] 跨进程重启的状态持久化 - [x] 演示暂停/恢复的可恢复性测试 - [x] 支持多个并发调查 - [x] 所有调查的完整审计跟踪 - [x] **带评分的评估工具** 📊 指标 - [x] 使用脚本化场景的自动化评估 - [x] 真实的根因标签 - [x] 评分标准 (root cause, remediation, efficiency, cost) - [x] 5 个不同难度的完整场景 - [x] Markdown 报告生成 - [x] 用于 CI/CD 集成的命令行运行器 - [x] **真实 MCP 服务器集成** 🔌 实时模式 - [x] 用于真实 MCP 服务器的 Stdio 传输 - [x] 适用于所有服务器类型的配置系统 - [x] 支持 Kubernetes, GitHub, Slack, Observability - [x] 基于环境的配置 - [x] 透明的模式切换 - [x] 全面的集成文档 - [x] **Streamlit 仪表盘** 📊 可观测性 - [x] 带有汇总指标的概览页面 - [x] 带有过滤功能的调查列表 - [x] 包含完整记录的详细调查视图 - [x] 假设与验证跟踪 - [x] 恢复建议和审批状态 - [x] 实时读取检查点数据库 ## 当前评估得分 **评估工具现已构建完成并可供运行！** 执行命令： ``` python -m evals.runner ``` **目标指标（目标）：** | 指标 | 目标得分 | |--------|--------------| | 根因准确率 (Exact) | ≥ 60% | | 根因准确率 (Partial+) | ≥ 80% | | 修复方案可接受度 | ≥ 75% | | 平均验证轮次 | ≤ 2.5 | | 每次事件平均成本 | ≤ $0.015 | | 升级率 | ≤ 25% | **当前场景：** - oom_after_deploy (简单) - 5xx_spike_feature_flag (中等) - dns_resolution_failure (困难) - slow_query_missing_index (中等) - cascading_failure_timeout (困难) 有关评估工具的详情，请参见 [`evals/README.md`](evals/README.md)。 ## 架构 参见 [`ARCHITECTURE.md`](ARCHITECTURE.md) 获取全面的架构文档，包括： - 系统概览图 - 数据流序列 - 组件架构 - 关键设计决策与权衡 - 可扩展性考量 - 安全模型 ## 实战案例 参见 [`EXAMPLE.md`](EXAMPLE.md) 获取 OOM 事件调查的完整演示： - 从告警到解决的逐步记录 - 证据收集与假设生成 - 验证过程和 LLM 评估 - 审批流程与修复执行 - 复盘报告生成 - 性能指标与人类 SRE 的对比 ## 限制 参见 [`LIMITATIONS.md`](LIMITATIONS.md) 了解对当前限制的客观评估： **当前限制**： - 假设生成质量依赖于证据 - 验证检查解释使用简单的关键词匹配 - 仅限于 5 种操作类型 - 调查之间缺乏学习机制 - 侧重于单一服务（在处理级联故障时较为吃力） - 评估范围仅限于 5 个场景 **观察到的故障模式**： - 因误导性证据导致的错误确认（在评估中约占 5%） - 无限验证循环（已通过最大轮次限制缓解） - 证据收集超时（尚未实现超时处理） **对生产环境的建议**： - 将评估场景扩展到 15-25 个 - 为所有 MCP 调用添加超时处理 - 在日志中实现密钥脱敏 - 为高升级率添加告警 - 对审批流程进行安全审查 **渐进式推广策略**： 1. 影子模式（仅观察） 2. 提出修复建议（需人工批准） 3. 自动执行低风险操作 4. 对已知模式实现完全自主 ## 项目统计 | 指标 | 值 | |--------|-------| | **总代码行数** | ~11,100 | | **Agent 节点** | 7 | | **MCP 工具 (模拟)** | 22 | | **MCP 服务器 (真实)** | 5 | | **评估场景** | 5 | | **测试文件** | 6 | | **文档页数** | 7 | ## 许可证 MIT

标签：AIOps, AI智能体, API集成, CLI, DLL 劫持, Human-in-the-loop, Incident Response, Kubernetes, LangGraph, MCP, Model Context Protocol, Post-Mortem, Python, RCA, Slack, SRE, Webhook, WiFi技术, 人工智能, 人机协同, 假设验证, 偏差过滤, 力导向图, 可观测性, 告警分诊, 回溯算法, 复盘报告, 大语言模型, 子域名突变, 故障排查, 故障诊断, 无后门, 根因分析, 模块化设计, 测试用例, 状态管理, 生产环境, 用户模式Hook绕过, 站点可靠性工程, 系统恢复, 自主代理, 自动化修复, 自动化运维, 请求拦截, 运维自动化, 逆向工具