asorari09/Incident-Rootcause-Copilot

# IR-Copilot **以数据统计进行检测。以 AI agents 进行诊断。由人类进行干预与修复。** IR-Copilot 是一个人机协同（human-in-the-loop）的事件响应（incident-response）copilot。一个确定性的检测器会决定合成的指标异常是否真实；随后，一个固定且有预算上限的 LangGraph workflow 会检索 runbook 上下文，生成结构化假设，并为人工审查起草 GitHub issue 或本地试运行（dry-run）产出物。 它有意避免成为一个自动修复工具、Datadog 的替代品，或是一个自由格式的 multi-agent 演示。 ## 为什么开发它 在服务中断期间，工程师必须在时间压力下将各项指标、近期变更、已知 runbook 以及事件沟通记录关联起来。IR-Copilot 展示了一种更安全的职责划分：由统计学决定某些东西是否异常，而模型则帮助解释基于工具的事实证据（tool-grounded evidence），同时不执行任何基础设施变更。 ## 架构 ``` React/Vite dashboard → FastAPI → detector gate → fixed LangGraph ├→ local MiniLM + Chroma runbooks └→ draft-only GitHub client / local outbox ``` 完整的图表和时序图请参见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 ## 快速开始 环境要求：Python 3.12+，[uv](https://docs.astral.sh/uv/) 以及 Node/npm。 ``` make install make test make run-api ``` 在第二个终端中： ``` make run-web ``` 打开 `http://127.0.0.1:5173`，选择 `sc_db_pool`，点击 **Inject**，然后点击 **Run incident**。本地开发会使用离线的 Fake LLM 路径，Vite 会将 API 调用代理到 `http://127.0.0.1:8000`。API 的 OpenAPI UI 位于 `http://127.0.0.1:8000/docs`。 使用本地 MiniLM 模型索引 runbook（当已缓存或可用时）： ``` make index-runbooks ``` ## 演示场景 | 场景 | 预期结果 | |---|---| | `sc_db_pool` | `db_connection_pool_exhaustion` | | `sc_memory_leak` | `memory_leak_after_deploy` | | `sc_bad_deploy` | `regressive_deploy` | | `sc_dependency_outage` | `upstream_dependency_outage` | | `sc_noise_false_alarm` | 跳过；无根本原因 | ## 评估与可观测性 ``` make eval ``` 最新测得的离线结果： ``` evals PASS: 5/5 exact, noise_skip=True, mean_cost=$0.0000 ``` 此结果使用了 `FakeLLM`，因此零成本仅为离线测试结果，并不代表实际产生的 OpenAI 账单。实时运行被限制为仅使用 `gpt-4o-mini`、temperature 为 0 且 LLM 尝试次数不超过三次；标准的实时预算为 `$0.03/run`。本地 MiniLM embeddings 不产生任何 API embedding 成本。 Langfuse 是可选的。在未提交的 `.env` 中设置 `LANGFUSE_ENABLED=true`、`LANGFUSE_PUBLIC_KEY`、`LANGFUSE_SECRET_KEY`，以及可选的 `LANGFUSE_HOST`，即可发送配置好的 traces。若未提供密钥，相关的回调将变为空操作（no-op）。 ## 防护栏 - 异常拦截机制可以直接跳过图结构；噪声场景下会进行零次 LLM 调用。 - 工作流图是固定的，没有 supervisor 或自主的 agent 循环。 - Prompts 基于紧凑的检测器/RAG/GitHub 事实证据，并使用 Pydantic 进行结构化。 - 仅允许使用 `gpt-4o-mini`；严格执行 `MAX_LLM_CALLS_PER_RUN <= 3`。 - GitHub 的写入仅限草稿模式。不存在 auto-merge、部署、删除、kubectl 或云端环境变更工具。 - `GITHUB_DRY_RUN=true` 默认会将 Markdown 产出物写入 `data/outbox/`。 ## 实时演示 / 部署 (Render 免费版) 托管演示使用 **一个** Render 免费 Web Service (Docker)。该服务在空闲约 15 分钟后会休眠，唤醒可能需要约 1 分钟。请保持 `ALLOW_FAKE_LLM=true` 和 `ENABLE_RUNBOOK_INDEX=false`，这样演示就不需要付费的 API 密钥，并且能维持在 免费层的内存限制内。 **实时演示：** [https://ir-copilot.onrender.com](https://ir-copilot.onrender.com) 在空闲停机后的第一次请求可能需要大约一分钟，等待 Render 唤醒该免费实例。一旦唤醒，控制面板将提供与本地演示相同的无密钥 FakeLLM + GitHub 试运行（dry-run）流程。 分步指南：[docs/DEPLOY.md](docs/DEPLOY.md)。部署蓝图：[`render.yaml`](render.yaml)。 本地单服务对等配置： ``` cp .env.example .env docker compose up --build ``` 然后打开 `http://127.0.0.1:8000/` 访问内置控制面板，并访问 `http://127.0.0.1:8000/health` 查看健康检查。 ## 可用于简历的要点 - 构建了一个混合式事件响应 copilot，将确定性异常检测与 LLM 诊断分离开来，以降低产生幻觉的风险。 - 实现了一个固定的 LangGraph 工作流，包含本地 runbook 检索、Pydantic 结构化输出、严格的单次运行调用上限，以及仅限草稿模式的 GitHub 修复策略。 - 添加了五个标准测试场景和一个离线评估测试套件，测得 5/5 精确匹配，且针对误报路径实现了零次 LLM 调用。 - 实现了 FastAPI、React/Vite、SQLite 持久化、可选的 Langfuse 回调，并提供了支持缩容的免费 Render Docker 托管环境以进行无密钥演示。 ## 延伸阅读 - [部署 (Render 免费版)](docs/DEPLOY.md) - [架构](docs/ARCHITECTURE.md) - [决策记录](docs/DECISIONS.md) - [演示脚本](docs/DEMO_SCRIPT.md) - [面试指南](docs/INTERVIEW_GUIDE.md) - [构建回顾](docs/RETROSPECTIVE.md) - [权威实施计划](END_TO_END_PLAN.md)

标签：AI助手, LangGraph, RAG, 库, 应急响应, 异常检测, 请求拦截, 运维监控, 逆向工具