IT 运维告警分诊与处置建议多智能体平台。
目标岗位能力对标：Agent 编排（LangGraph）/ RAG / 评测 / 可观测 / 生产化落地。 本仓库按里程碑演进，M1-M4 全部交付。PM 文档见 docs/（PRD / 风险登记册 / 迭代复盘）。
| 指标 | mock（离线回归） | 真实模型（校准前） | 真实模型（校准后） |
|---|---|---|---|
| 分类准确率 | 100% | 90% | 90% |
| 定级准确率 | 100% | 70% | 80% |
| 链路完成率 | 100% | 100% | 100% |
| 平均 token/条 | 1521 | 2824 | 3490 |
迭代改进实录：首轮真实模型评测发现定级系统性偏高（P3 判为 P2）， 通过在分诊 prompt 中引入四级判定标准与"宁低勿高"校准原则， 定级准确率提升 10 个百分点（报告对比见
reports/）。 评测报告由python scripts/run_eval.py [--real]自动生成；CI 每次 push 自动跑 mock 基线。
告警接入 → [分诊 Agent] → [RAG 检索 Runbook] → [诊断 Agent] → [规划 Agent] → 【审批门 HITL】→ [执行器] → [复盘 Agent]
分类/定级/去重 BM25 检索 根因假设+证据 工具调用计划 写操作需人工批准 副作用分级执行 报告+记忆沉淀
-
告警接入：
POST /alerts（原生 JSON）或POST /webhook/alertmanager（Prometheus Alertmanager webhook 推送，severity 自动映射 P1-P4，resolved 告警自动跳过） -
分诊 Agent：分类（compute/storage/database/network/application）、定级（P1-P4）、去重键、摘要
-
RAG：Runbook 按章节切块，RRF 混合检索（BM25 关键词 + Qdrant/FastEmbed bge-small-zh 稠密向量，
ALERTPILOT_RETRIEVER_BACKEND可切换 bm25/dense/hybrid，向量依赖缺失自动降级 BM25） -
诊断 Agent：基于告警 + 检索证据输出根因假设与处置建议（含输出契约归一化，容忍 LLM 返回格式漂移）
-
规划 Agent：诊断建议 → 结构化工具调用计划，规则引擎做副作用分级（LLM 只提建议，规则定边界）
-
HITL 审批门：写操作（清理/重启/扩容）通过 LangGraph
interrupt()暂停图，人工批准后Command(resume=...)从断点恢复 -
执行器：只读工具自动执行；写工具仅在批准后执行，拒绝则跳过并留痕；支持 local（进程内）/ mcp（跨进程 MCP 协议，
ALERTPILOT_TOOL_BACKEND=mcp）双通道 -
MCP 工具服务：
python -m alertpilot.tools.mcp_server以 stdio 暴露运维工具，与 Agent 运行时解耦，可独立接入任意 MCP 客户端 -
持久化：SQLite 记录全量告警、计划、执行结果与审批人；LangGraph checkpoint 支持断点恢复
-
用量计量：每次运行统计 LLM 调用数、token 消耗与延迟，写入记录并聚合到
/metrics -
看板：
GET /提供指标概览、分类分布、待审队列与告警列表（纯静态无依赖） -
评测：黄金集 20 条 +
scripts/run_eval.py生成 Markdown 评测报告（mock/真实模型双模式） -
复盘闭环 + 记忆治理：执行后自动生成事故报告（
data/incidents/），经验以[pending]写入data/runbooks/incident-memory.md，经POST /memory/review人工审核后才进入检索语料——未经审核的经验不会污染诊断证据链 -
故障注入：LLM 损坏输出 / 契约漂移 / 工具失败均有测试覆盖的恢复路径
# 1. 安装（开发模式 + 测试依赖）
pip install -e ".[dev]"
# 2. 配置（可选：不配置默认使用 mock LLM 也能跑测试）
cp .env.example .env # 填入真实 LLM API Key 后改 ALERTPILOT_LLM_PROVIDER=openai-compatible
# 2.5（可选）启用混合检索（默认已启用，缺依赖时自动降级 BM25）
pip install -e ".[vector]" # Qdrant + FastEmbed 本地嵌入模型
# 3. 运行测试（离线、确定性、无需联网）
pytest -s
# 4. 启动 API（默认 mock LLM；配置 .env 后走真实模型）
uvicorn alertpilot.api:app --reload
# 5. 提交一条告警（若诊断含写操作，将返回 awaiting_approval 并停在审批门）
curl -X POST http://127.0.0.1:8000/alerts -H "Content-Type: application/json" -d "{\"service\": \"order-service\", \"title\": \"磁盘使用率超过 92%\", \"description\": \"日志堆积\"}"
# 6. 查看待审列表 / 人工批准
curl http://127.0.0.1:8000/approvals
curl -X POST http://127.0.0.1:8000/approvals/<alert_id> -H "Content-Type: application/json" -d "{\"decision\": true, \"approver\": \"reviewer-zhang\"}"alertpilot/
├── src/alertpilot/
│ ├── config.py # 环境变量配置
│ ├── schemas.py # 核心数据模型
│ ├── llm.py # LLM 客户端（openai-compatible / mock）
│ ├── graph.py # LangGraph 流水线编排 + checkpoint
│ ├── db.py # SQLite 持久化
│ ├── api.py # FastAPI 服务
│ ├── mock_source.py # mock 告警源
│ ├── agents/ # 分诊 / 诊断 / 规划智能体
│ ├── tools/ # mock 运维工具 + 副作用分级执行器
│ └── rag/ # Runbook 检索
├── data/runbooks/ # 运维处置手册（RAG 语料）
└── tests/ # 单测 + 黄金数据集评测
| 里程碑 | 内容 | 状态 |
|---|---|---|
| M1 | 只读分诊链路：分类 → RAG → 诊断建议 | ✅ |
| M2 | HITL 审批门 + 副作用分级执行 + 断点恢复 | ✅ |
| M3 | 评测体系 + 用量/延迟指标 + 看板 + Docker 部署 | ✅ |
| M4 | 故障注入演练 + 复盘记忆闭环 + PRD/风险册/复盘文档 | ✅ |
| M5 | Qdrant/FastEmbed 稠密向量 + RRF 混合检索（三路对比评测 100% 命中） | ✅ |
| M6 | MCP 工具服务器（stdio）+ 双通道执行器 + 记忆审核治理 | ✅ |
| M7 | Alertmanager webhook 接入 + 看板记忆审核 UI | ✅ |