tianhg468/AI-Incident-Response-Engineer

# AI 事故响应工程师 一个自主代理，用于对基于 Kubernetes 的服务进行事故分类、诊断和修复协助。 ## 概述 本项目实现了一个 AI 驱动的事故响应系统，具有以下功能： - 通过 webhook 或 CLI 接收告警 - 通过 MCP 从可观测性和基础设施工具收集证据 - 通过回溯形成并验证根本原因假设 - 提出修复方案并由人工审批 - 执行已批准的修复 - 生成全面的复盘报告 ## 核心特性 1. **假设-验证循环**，支持回溯（非线性管道） 2. **严格的人工介入关卡**，在任何写入操作前进行审批 3. **持久化状态**，通过 LangGraph 检查点保存（调查可在重启后继续） 4. **自定义 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 服务器 一个关键的架构决策：**代理 agnostic 于它是在与真实还是模拟 MCP 服务器通信。** ``` # Agent code works in both modes 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` 时，代理可以连接到真实基础设施。** 这使得可以使用实际的 Kubernetes 集群、GitHub 仓库、Slack 工作区和可观测性平台进行生产事故响应。 ### 快速开始 ``` # 1. Set MODE to live export MODE=live # 2. Configure MCP server paths 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. Configure 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. Run investigation python -m agent.graph ``` ### 支持的 MCP 服务器 - **Kubernetes**：Pod 状态、日志、事件、部署 - **GitHub**：提交、PR、差异、文件内容 - **Slack**：消息、审批、通知 - **可观测性**：指标、告警、服务健康状态（Grafana/Datadog/Prometheus） - **运行手册关联器**：自定义服务器（已包含） ### 工作原理 `MCPServerRegistry` 根据 MODE 自动路由工具调用： ``` # Agent code is completely agnostic 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 → Uses fixture-based mocks # MODE=live → Connects to real Kubernetes API ``` ### 设置指南 请参阅 [`mcp_servers/real/README.md`](mcp_servers/real/README.md) 了解： - 安装/构建 MCP 服务器 - 各服务的配置示例 - 身份验证设置 - 故障排除指南 - 安全注意事项 ## 检查点与可恢复性 **调查可在进程重启后继续。** LangGraph 的检查点将完整的代理状态持久化到数据库，支持： - 跨重启暂停和恢复调查 - 查看具有完整记录的历次调查 - 调试和重放特定调查步骤 - 跟踪多个并发调查 ### 工作原理 ``` from agent.graph import create_incident_response_graph from agent.utils.checkpointing import get_checkpointer, get_thread_id # Create a checkpointer (SQLite by default) checkpointer = get_checkpointer() # Create graph with checkpointing enabled graph = create_incident_response_graph(checkpointer=checkpointer) # Start an investigation with a unique thread_id thread_id = get_thread_id("alert_12345") config = {"configurable": {"thread_id": thread_id}} # Run the investigation result = graph.invoke(initial_state, config=config) # === AFTER PROCESS RESTART === # Create new graph and checkpointer instances checkpointer = get_checkpointer() graph = create_incident_response_graph(checkpointer=checkpointer) # Resume from checkpoint using the same thread_id state = graph.get_state(config) # Continue investigation from where it left off ``` ### 配置 通过环境变量设置检查点模式： ``` # SQLite (default for dev/testing) CHECKPOINT_MODE=sqlite CHECKPOINT_DB_PATH=./data/checkpoints.db # Postgres (for production) CHECKPOINT_MODE=postgres DATABASE_URL=postgresql://user:password@localhost:5432/incident_response # In-memory (no persistence) CHECKPOINT_MODE=memory ``` ### 测试可恢复性 ``` python tests/test_checkpointing.py ``` 这演示了： 1. 启用检查点启动调查 2. 模拟进程重启 3. 从精确检查点恢复 4. 验证状态连续性 ## 仪表板 **通过 Streamlit 仪表板实时监控调查。** 查看活跃和历史调查，跟踪指标，分析代理性能。 ### 快速开始 ``` # Run some investigations first export MODE=eval SCENARIO=oom_after_deploy python -m agent.graph # Launch dashboard streamlit run dashboard/app.py # Open browser at http://localhost:8501 ``` ### 功能 **概览页面：** - 汇总指标（总数、已解决、升级、平均轮次） - 分布图表（按严重程度、按服务） - 实时自动刷新选项 **调查列表：** - 按状态、严重程度、服务筛选 - 快速查看关键指标 - 一键访问详情 **调查详情：** - 完整事故信息 - 所有假设及验证状态 - 恢复方案和审批信息 - 完整调查时间线 ### 仪表板视图示例 **跟踪的指标：** - 总调查数：15 - 完成率：80% - 升级率：20% - 平均验证轮次：1.8 **筛选器：** - 状态：已完成、升级中、进行中 - 严重程度：严重、高、中、低 - 服务：payment-service、user-service 等 详细文档请参阅 [`dashboard/README.md`](dashboard/README.md)。 ## 设置 ### 前置条件 - Python 3.11+ - Docker 和 Docker Compose - pip 或 uv ### 安装 ``` # Clone the repository git clone cd ai-incident-response # Install dependencies pip install -e ".[dev]" # Set up environment variables cp .env.example .env # Edit .env with your API keys ``` ### 本地运行 ``` # 1. Set environment variables export MODE=eval export SCENARIO=oom_after_deploy export CHECKPOINT_MODE=sqlite # 2. Run an investigation python -m agent.graph # 3. Launch the dashboard streamlit run dashboard/app.py # 4. (Optional) Start infrastructure for production docker-compose up -d # 5. (Future) Run the webhook server # uvicorn webhook.main:app --reload ``` ## 开发状态 **当前阶段：** 步骤 10 - 仪表板 ✅ - [x] 定义状态类型 - [x] 带有空操作节点的骨架图 - [x] 创建节点占位符 - [x] 初始化提示模板 - [x] 模拟 MCP 服务器（Kubernetes、GitHub、Slack、可观测性） - [x] 带模式切换的 MCP 服务器注册表（eval/live） - [x] 带固定数据的示例场景（oom_after_deploy） - [x] 自定义运行手册关联器 MCP 服务器 - [x] find_runbook 工具（带 YAML frontmatter 的 markdown 语料库） - [x] correlate_deploys 工具（多因素可疑评分） - [x] similar_past_incidents 工具（使用 sentence-transformers + FAISS 的向量搜索） - [x] 全面的协议级文档 - [x] 端到端成功路径 - [x] Intake 节点从场景加载事故 - [x] 证据收集调用模拟 MCP 服务器 - [x] 诊断使用 LLM 生成假设 - [x] 验证确认第一个假设 - [x] 恢复方案在评估模式下自动审批 - [x] 执行和复盘完成工作流 - [x] 完整测试场景运行器 - [x] **带回溯的验证循环** ⭐ 关键差异化特性 - [x] 使用 LLM 和针对性检查的真实验证 - [x] 严格应用证伪标准 - [x] 被反驳的假设触发回溯到诊断 - [x] 被确认的假设继续到恢复 - [x] 达到最大轮次后升级（共 5 轮，3 轮无结论） - [x] 展示非线性图执行 - [x] 验证回溯行为的测试套件 - [x] **人工介入审批流程** 🔒 安全门 - [x] 带风险等级的操作类型白名单 - [x] 带 Slack/CLI 回退的 ApprovalHandler - [x] 评估模式下自动审批以支持测试 - [x] 完整审计跟踪（状态、推理、决定者、方法） - [x] 与 recovery_proposal 节点集成 - [x] 全面的测试覆盖 - [x] **检查点 + 可恢复性** 💾 持久性 - [x] 使用 SQLite/Postgres 的 LangGraph 检查点 - [x] 基于线程的调查跟踪 - [x] 跨进程重启的状态持久化 - [x] 展示暂停/恢复的可恢复性测试 - [x] 支持多个并发调查 - [x] 所有调查的完整审计跟踪 - [x] **带评分的评估框架** 📊 指标 - [x] 使用脚本化场景的自动化评估 - [x] 根本原因真实值标签 - [x] 评分标准（根本原因、修复、效率、成本） - [x] 5 个难度各异的完整场景 - [x] Markdown 报告生成 - [x] 用于 CI/CD 集成的命令行运行器 - [x] **真实 MCP 服务器集成** 🔌 生产模式 - [x] 真实 MCP 服务器的 stdio 传输 - [x] 所有服务器类型的配置系统 - [x] 支持 Kubernetes、GitHub、Slack、可观测性 - [x] 基于环境的配置 - [x] 透明模式切换（eval/live） - [x] 全面的集成文档 - [x] **Streamlit 仪表板** 📊 可观测性 - [x] 带汇总指标的概览页面 - [x] 带筛选的调查列表- [x] 带完整记录的详细调查视图 - [x] 假设和验证跟踪 - [x] 恢复方案和审批状态 - [x] 实时检查点数据库读取 ## 当前评估分数 **评估框架已构建完成，可以运行！** 执行命令： ``` python -m evals.runner ``` **目标指标（目标值）：** | 指标 | 目标分数 | | ------------------------------ | ------------ | | 根本原因准确率（精确） | ≥ 60% | | 根本原因准确率（部分+） | ≥ 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)，包括： - 系统概览图 - 数据流序列 - 组件架构 - 关键设计决策和权衡 - 可扩展性考虑 - 安全模型 ## 工作示例 OOM 事故调查的完整演练请参阅 [`EXAMPLE.md`](EXAMPLE.md)： - 从告警到解决的逐步记录 - 证据收集和假设生成 - 验证过程和 LLM 评估 - 审批流程和修复执行 - 复盘生成 - 性能指标及与人类 SRE 的比较 ## 局限性 当前局限性的诚实评估请参阅 [`LIMITATIONS.md`](LIMITATIONS.md)： **当前局限性：** - 假设生成质量依赖于证据 - 验证检查解释使用简单关键词匹配 - 仅限于 5 种操作类型（rollback、scale、restart、config_change、patch） - 调查之间无学习能力 - 单一服务关注（级联故障处理困难） - 评估覆盖仅 5 个场景 **观察到的失败模式：** - 由于误导性证据导致的错误确认（评估中约 5%） - 无限验证循环（通过最大轮次限制缓解） - 证据收集超时（尚无超时处理） **生产环境建议：** - 扩展评估场景到 15-25 个 - 为所有 MCP 调用添加超时处理 - 在日志中实施机密信息脱敏 - 添加高升级率告警 - 审批流程安全审查 **渐进式推出策略：** 1. 影子模式（仅观察） 2. 提出修复方案（需要审批） 3. 自动执行低风险操作 4. 对已知模式完全自主 ## 项目统计 | 指标 | 数值 | | ----------------------- | ------- | | **代码总行数** | ~11,100 | | **代理节点** | 7 | | **MCP 工具（模拟）** | 22 | | **MCP 服务器（生产）** | 5 | | **评估场景** | 5 | | **测试文件** | 6 | | **文档页面** | 7 | ## 许可证

标签：AIops, API集成, Kubernetes, LangGraph, MCP, Model Context Protocol, SRE, Webhook, 事后分析, 人工智能运维, 人机协作, 偏差过滤, 力导向图, 可观测性, 子域名突变, 安全运营, 容器编排, 开源框架, 扫描框架, 持续集成, 故障恢复, 根因分析, 检查点, 测试用例, 特征库, 状态管理, 生产环境监控, 站点可靠性工程, 自主代理, 自动化运维, 自定义请求头, 请求拦截, 逆向工具