iakshayrathee/meridian
GitHub: iakshayrathee/meridian
Meridian 是一个基于 LangGraph 多智能体编排的 AI 事件响应平台演示项目，旨在通过自动化根因分析和恢复编排来缩短站点可靠性工程中的平均解决时间。
Stars: 0 | Forks: 0
# Meridian
### 基于 AI 的事件响应编排平台
**Meridian** 是一个面向产品级、面向投资组合规模的事件响应平台，展示了如何通过多智能体 AI 编排来缩短平均解决时间 (MTTR)。它基于 LangGraph 构建，能够从监控系统接入实时告警，执行智能根因分析，在安全门控下执行恢复运行手册，并生成详尽的事后总结——所有这些都具备完整的可观测性和 human-in-the-loop（人工介入）控制。
## 概述
Meridian 使用多智能体架构自动化了完整的事件生命周期——从告警检测到事后总结生成。它围绕站点可靠性工程 (SRE) 工作流设计，将大语言模型的推理能力与基于模式的安全控制以及 human-in-the-loop 门控相结合，实现了端到端的面向产品的架构模式。
## 已知限制
这是一个演示项目。它展示了面向产品的架构，但
**并未**针对真实部署进行安全强化。当前存在的不足：
- **身份验证使用单一共享 API 密钥。** 当设置了 `API_KEY` 时，状态变更端点（webhook、审批、事件修改）需要 `X-API-Key` 请求头；如果未设置，它们将开放访问（开发模式）。这仅属于演示级别——真实使用场景需要基于用户的身份验证 (JWT/OIDC)，而不是单一的共享密钥。
- **命令“安全性”采用的是白名单 + 模式黑名单，而非沙箱。** 它通过子字符串/模式匹配并拦截 shell 元字符（因此 `curl x | bash` 无法自动运行），但依然可以通过刻意的混淆来绕过。真正的隔离需要 container/seccomp 执行环境。
- **默认的 checkpointer 是基于内存的。** 除非安装并配置了 `langgraph-checkpoint-redis`，否则重启后处于暂停状态的审批将会丢失。
- **Runbook 检索具备服务感知能力，但并不完美。** 它现在会对候选结果进行重新排序，优先选择精确的服务匹配；但最终选择仍取决于该服务在知识库中存在哪些运行手册。
- **性能指标数字是预期目标，而非实测结果。** `backend/loadtest/` 中提供了一个 Locust 测试工具——运行它以获取真实的测试数据。
- **Grafana 指标是模拟数据。** 指标工具返回的是合成数据；对接真实的 Grafana/Prometheus 数据源超出了演示的范围。
### 核心功能
**智能告警处理**
- 亚秒级 webhook 接入，通过 Redis 锁 + 告警指纹实现尽力而为的去重
- 具备结构化输出验证的 AI 驱动分类（P1-P4 严重程度）
- 基于规则的备用分类器确保在 OpenAI 服务中断期间 pipeline 仍能运行
**自主根因分析**
- 结合工具增强的多步推理（Grafana 指标、历史事件、运行手册）
- 两种可选拓扑：快速的线性 pipeline，或包含专家子智能体、合成器和自我审查循环的多智能体 supervisor 模式
- 置信度评分，具备可配置的阈值用于升级门控
- 从历史事件中进行语义记忆检索（Qdrant 向量搜索），支持可选的查询扩展 + 倒数秩融合
**安全的 Runbook 执行**
- 三级安全验证：硬拦截 → 审批门控 → 白名单
- 用于 human-in-the-loop 审批的 LangGraph 中断/恢复机制
- 具备破坏性模式黑名单和执行超时的命令白名单（基于模式匹配，并非真正的沙箱）
**企业级可观测性**
- LangSmith 自动追踪，零埋点开销
- 基于 Redis pub/sub 和重放缓冲区的实时 SSE 流式传输
- 针对每个事件的 token 使用量跟踪和成本归因
- 针对高吞吐场景的批量数据库写入
**质量保证**
- 结合 LLM-as-judge 评分（4个维度）的评估工具
- 用于 prompt 工程的 A/B 测试框架
- RAG 检索质量指标（Precision@3，相关性评分）
## 架构
### 系统概览
```
┌─────────────┐
│ Grafana │ Alert Webhook
│ Prometheus │────────────┐
└─────────────┘ │
▼
┌──────────────┐
│ FastAPI │
│ Webhook │──── Background Task
└──────┬───────┘
│
Redis Lock + Dedup
│
▼
┌────────────────────┐
│ LangGraph Compiled │
│ Graph (AGENT_MODE) │
└─────────┬──────────┘
▼
┌────────────┐
│ Alert │
│ Classifier │ (fallback → rule-based)
└─────┬──────┘
┌────────────-┴─────────────┐
AGENT_MODE│=pipeline AGENT_MODE│=supervised
▼ ▼
┌────────────┐ ┌───────────────────┐
│ Root Cause │ │ Supervisor │◀────────┐
│ Analyzer │ │ (dispatch loop) │ │
└─────┬──────┘ └─────────┬─────────┘ │
│ ▼ │ findings
│ ┌──────────────────────────────┐ │ (blackboard)
│ │ Specialists (ReAct) │ │
│ │ metrics · logs · deps · hist │─────┘
│ └──────────────┬───────────────┘
│ ▼
│ ┌──────────────┐
│ │ Synthesizer │
│ └──────┬───────┘
│ ▼
│ ┌──────────────┐ revise
│ │ Critic │───────┐
│ └──────┬───────┘ │(≤ MAX_REVISIONS)
│ approve▼ └─▶ back to Supervisor
│ ┌──────────────┐
│ │ Remediation │
│ │ Planner │
│ └──────┬───────┘
└───────────────┬───────────┘
▼ (shared downstream)
┌────────────┐ safety-gated
│ Runbook │ interrupt/resume
│ Executor │◀── human approval
└─────┬──────┘
┌─────────┴─────────┐
▼ ▼
┌────────────┐ ┌────────────┐
│ Escalation │────▶│ Postmortem │
│ Manager │ │ Drafter │
└────────────┘ └─────┬──────┘
│
Redis Pub/Sub
│
▼
┌──────────────────┐
│ Next.js SSE │
│ Dashboard │
└──────────────────┘
```
### 两种 Agent 拓扑
Meridian 提供了两种可选择的 agent 工作流，通过 `AGENT_MODE` 环境变量进行配置：
- **`supervised`**（默认）—— 多智能体 supervisor 模式。supervisor 动态调度专家子智能体，这些子智能体在一个共享的调查结果“黑板”上进行协作，随后在执行恢复之前经过合成器合成，并进行一次自我审查（反思）循环。在模糊事件上的处理质量更高，但代价是会产生更多的 LLM 调用。
- **`pipeline`** —— 由五个节点组成的确定性线性 pipeline。速度快、成本低且易于推理。保留它是为了作为评估基线以进行 A/B 对比。
两种拓扑共享相同的入口节点（告警分类器）和相同的下游尾部（Runbook 执行器、升级管理器、事后总结起草器），共享相同的 checkpointer 以及相同的安全门控。它们唯一的区别在于中间的诊断阶段：pipeline 运行单一根因分析器；而 supervised 模式将其替换为 supervisor + 专家智能体 + 合成器 + 审查者 + 恢复计划器。
### 按事件选择模式
拓扑结构是**按事件**选择的，而不仅仅是全局配置，因此 pipeline 和 supervised 模式可以并排进行比较：
- 仪表板的 **Alert Simulator** 具有模式切换开关（保存在 `localStorage` 中），用于设置下一个触发事件的拓扑。
- 所选模式将作为 webhook 负载中的 `agent_mode` 发送，经过验证后，**持久化保存在事件记录中**（`incidents.agent_mode`）。因此，human-in-the-loop 审批恢复时始终会重新进入事件开始时使用的*同一个* graph。
- 对于未明确指定模式而创建的事件（例如真实的 Grafana webhook），`AGENT_MODE` 依然是后备默认值。
- 该切换开关仅影响**新**事件；现有事件保留其运行时的模式，并在事件详情页头部显示为徽章。
```
# 显式触发受监管事件
curl -X POST http://localhost:8000/webhook/grafana \
-H "Content-Type: application/json" \
-d '{"agent_mode": "supervised", "alerts": [ ... ]}'
```
### 实时拓扑端点（防漂移 graph）
前端的 agent-graph 视图由后端端点驱动，而不是硬编码的节点映射，因此渲染的拓扑始终与编译后的 graph 保持一致：
```
GET /agents/topology?mode=supervised
→ { "mode", "nodes": [{id,label,role,entry}], "edges": [{source,target,type,conditional}] }
```
节点 `role`（分类器、编排器、专家、合成器、审查者、计划器、执行器、升级、事后总结）和边 `type`（主要、条件、循环、升级）驱动布局、节点样式和图例。事件详情页会获取该事件存储模式对应的拓扑，并叠加来自 SSE 追踪的真实遍历状态。
### 两种模式的 A/B 对比
评估工具可以强制指定模式，以对比质量/MTTR：
```
# Baseline (pipeline) 与 multi-agent (supervised) 对比
docker compose exec backend python -m app.evals.runner pipeline_report.json pipeline
docker compose exec backend python -m app.evals.runner supervised_report.json supervised
# 比较摘要
jq '.summary' pipeline_report.json supervised_report.json
```
### Pipeline 模式节点 (`AGENT_MODE=pipeline`)
| 节点 | 用途 | LLM | 工具 | 安全性 |
|------|---------|-----|-------|--------|
| **Alert Classifier** | 严重程度检测 (P1-P4) | GPT-4o | 无 | 规则降级回退；可选的自洽性投票 |
| **Root Cause Analyzer** | 多步诊断 | GPT-4o | Grafana, Qdrant (情景 + 语义) | 置信度门控 |
| **Runbook Executor** | 恢复步骤 | GPT-4o | Shell, Slack | 3 级验证 + 中断/恢复 |
| **Escalation Manager** | 路由和通知 | 模板 | Slack | 置信度阈值 |
| **Postmortem Drafter** | 文档记录 | GPT-4o | 无 | N/A |
### Supervised 模式节点 (`AGENT_MODE=supervised`)
在告警分类器之后运行，取代单一的根因分析器：
| 节点 | 用途 | LLM | 工具 |
|------|---------|-----|-------|
| **Supervisor** | 动态调度专家智能体直到确信 | GPT-4o | 无 |
| **Metrics Analyst** | 调查 Grafana/Prometheus 指标 | GPT-4o (ReAct) | Grafana, Prometheus 范围查询 |
| **Log Analyst** | 搜索并关联日志 | GPT-4o (ReAct) | 日志搜索 |
| **Dependency Mapper** | 映射上游/下游服务影响 | GPT-4o (ReAct) | 服务依赖关系图 |
| **Historical Analyst** | 查找相似的历史事件 | GPT-4o (ReAct) | 情景记忆搜索 |
| **Synthesizer** | 将专家的发现合并为一个根因 | GPT-4o | 无 |
| **Critic** | 反思循环 —— 批准或要求修订 | GPT-4o | 无 |
| **Remediation Planner** | 根据检索到的运行手册构建有序计划 | GPT-4o | 语义记忆 |
调查深度受 `MAX_AGENT_STEPS` 限制，审查者的修订循环受 `MAX_REVISIONS` 限制，以此来控制成本并保证必定终止。
## 技术栈
### 后端
- **Python 3.11+** — Async/await runtime
- **FastAPI 0.115** — 高性能异步 REST API
- **LangGraph 0.2+ / LangChain 0.3+** — 具备状态检查点机制的多智能体工作流
- **OpenAI GPT-4o** — 结构化输出推理
- **PostgreSQL 16** — 关系型持久化 (SQLAlchemy 2.0 async + asyncpg)
- **Redis Stack 7+** — 分布式锁，pub/sub，检查点机制
- **Qdrant 1.11+** — 用于语义/情景记忆的向量搜索
- **LangSmith** — 自动化 agent 追踪与评估
- **prometheus-fastapi-instrumentator** — 可选的 `/metrics` 导出
### 前端
- **Next.js 14** — React App Router
- **TypeScript 5** — 类型安全
- **Tailwind CSS 3** — 实用优先的样式
- **Radix UI + lucide-react** — 无障碍基础组件和图标
- **TanStack Query + Zustand** — 服务端/客户端状态管理
- **Recharts** — 分析图表
- **SVG + framer-motion** — 拓扑驱动的 agent-graph 可视化（从 `GET /agents/topology` 渲染，因此始终与编译后的后端 graph 匹配）
- **EventSource (SSE)** — 实时更新
### 基础设施
- **Docker Compose** — 多容器编排
- **Alembic** — 数据库迁移
- **pytest** — 测试框架
## 快速开始
### 前置条件
```
# 必填
- Docker & Docker Compose
- OpenAI API key
# 可选
- LangSmith API key (for observability)
- Slack bot token (for notifications)
```
### 安装
```
# 1. 克隆仓库
git clone https://github.com/iakshayrathee/meridian.git
cd meridian
# 2. 配置环境
cp .env.example .env
# 编辑 .env 并添加你的 OPENAI_API_KEY
# 3. 启动服务
docker compose up -d
# 4. 等待健康检查
docker compose ps # All services should show "healthy"
# 5. 应用数据库迁移
docker compose exec backend alembic upgrade head
# 6. 填充 runbooks 和历史事件
docker compose exec backend python -m app.seed
# 7. 打开 dashboard
open http://localhost:3000
```
### 验证安装
```
# 检查后端健康状态
curl http://localhost:8000/health
# 查看 API 文档
open http://localhost:8000/docs
# 监控日志
docker compose logs -f backend
```
## 用法
### 触发测试告警
**选项 1：Alert Simulator（仪表板）**
1. 导航至 http://localhost:3000
2. 点击 "Alert Simulator" 面板
3. 选择告警类型（CPU 飙升、内存泄漏等）
4. 点击 "Fire Alert"
5. 实时观察事件出现
**选项 2：Grafana Webhook（编程方式）**
```
curl -X POST http://localhost:8000/webhook/grafana \
-H "Content-Type: application/json" \
-d '{
"alerts": [{
"status": "firing",
"labels": {
"alertname": "HighCPUUsage",
"service": "api-server",
"severity": "critical"
},
"annotations": {
"summary": "CPU usage above 90%",
"description": "API server CPU at 95% for 5 minutes"
}
}],
"commonLabels": {
"alertname": "HighCPUUsage",
"service": "api-server",
"severity": "critical"
}
}'
```
### 预期执行流程
```
[0s] Alert received → Webhook processing
[1s] Alert classified → P2 severity assigned
[3s] Root cause analysis → Grafana metrics queried
[8s] Runbook retrieved → Semantic search
[10s] ⏸️ PAUSED → Human approval gate
[User approves/rejects in dashboard]
[11s] Runbook execution → Steps executed
[15s] Escalation check → Slack notification sent
[18s] Postmortem drafted → Documentation generated
[20s] ✅ Incident resolved
```
### 人工审批门控
当 runbook 执行器暂停时：
1. **仪表板显示审批 UI**，包含：
- 步骤描述和待执行命令
- 安全性评估
- 批准 ✅ / 拒绝 ❌ 按钮
2. **批准** → graph 从检查点恢复执行
3. **拒绝** → 升级给人工处理，跳过自动化
## API 参考
### 核心端点
```
GET /health Health check
POST /webhook/grafana Grafana alert ingestion (auth)
GET /incidents List incidents
GET /incidents/{id} Get incident details
PATCH /incidents/{id} Update incident fields (auth)
POST /incidents/{id}/resolve Manually resolve an incident (auth)
DELETE /incidents/{id} Delete an incident (auth)
POST /incidents/{id}/approve Approve/reject a runbook step (auth, resumes graph)
GET /stream/{incident_id} SSE event stream
GET /runbooks List runbooks
GET /runbooks/{id} Get a single runbook
POST /runbooks Create a runbook (indexed for search) (auth)
GET /analytics/overview Aggregate KPIs (?days=)
GET /analytics/mttr-trends MTTR over time (?days=)
GET /analytics/severity-distribution Severity breakdown over time (?days=)
GET /agents/topology Compiled graph nodes + edges (?mode=)
GET /metrics Prometheus metrics (only when METRICS_ENABLED)
```
标有 **(auth)** 的端点在设置了 `API_KEY` 时需要提供 `X-API-Key` 请求头
（参见 [已知限制](#known-limitations)）。
访问 http://localhost:8000/docs 获取交互式 API 文档。
## 安全与防护
### 三级验证
以下数值反映了实际的代码（`app/utils/safety_validator.py` 和
`app/config.py`）。匹配方式基于子字符串/模式——参见
[已知限制](#known-limitations)。
**第 1 级：硬拦截** —— 破坏性模式，立即拒绝 (`safety_validator.DESTRUCTIVE_PATTERNS`)
```
DESTRUCTIVE_PATTERNS = [
"rm -rf", "DROP TABLE", "TRUNCATE", "DELETE FROM",
"kill -9", "shutdown", "reboot", "format", "mkfs",
"> /dev/", "dd if=", ":(){:|:&};:",
]
```
**第 2 级：审批门控** —— 需要人工审批 (`config.REQUIRE_APPROVAL_FOR`)
```
REQUIRE_APPROVAL_FOR = [
"restart", "kill", "delete", "drop", "truncate", "rm",
]
```
**第 3 级：白名单** —— 自动执行；其他任何操作默认需要审批 (`config.ALLOWED_SHELL_COMMANDS`)
```
ALLOWED_SHELL_COMMANDS = [
"curl", "ping", "nslookup", "dig",
"df", "free", "top", "ps",
]
```
### 额外保护措施
- **命令沙箱化** —— 30 秒超时，无 shell 扩展
- **速率限制** —— 每个客户端 120 次请求/分钟（可配置）
- **输入验证 —— 所有端点均使用 Pydantic schema
- **审计追踪** —— 对所有 LLM 决策进行完整的 LangSmith 追踪
## 可观测性
### LangSmith 集成
无需手动埋点的自动追踪：
```
# 配置 (在 .env 中)
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=lsv2_...
LANGCHAIN_PROJECT=meridian
```
**追踪视图** 展示：
- 所有 LLM 调用（prompt、响应、token、延迟）
- 工具调用（Grafana、runbook 搜索、shell）
- 状态转换（节点到节点的流转）
- 针对每个事件的成本归因
### 实时流传输
**Server-Sent Events (SSE)** 提供实时更新：
- Agent 节点状态转换（running → completed → failed）
- Runbook 步骤执行日志
- 审批门控状态
- 错误消息
**可靠性特性**：
- 基于 Redis pub/sub 的重放缓冲区（不会错过事件）
- 心跳保活（防止代理超时）
- 断开连接时自动重连
### 成本跟踪
Token 使用量和成本通过 `app/services/cost_tracking.py`
借助 LangChain token 计数回调 (`app/utils/token_callback.py`) 针对每个事件进行归因，并
聚合到 Redis 中。完整的逐次调用明细（prompt、响应、token、
延迟）也可以在启用追踪时的 LangSmith 中查看。目前还没有
专门的成本 REST 端点；可以在 `GET /analytics/overview` 获取聚合的事件 KPI。
## 评估与测试
### LLM-as-Judge 评估
运行自动化质量评估：
```
docker compose exec backend python -m app.evals.runner eval_report.json
# 查看结果
cat eval_report.json | jq '.summary'
```
**评分维度**：
1. **严重程度准确性** — 正确的 P1-P4 分类（二元判定）
2. **根因质量** — 具体程度、证据支撑、可操作性 (0-1)
3. **Runbook 相关性** — 匹配告警类型和服务 (0-1)
4. **事后总结完整性** — 结构、深度、客观无责备 (0-1)
**当前分数**（最新一次运行，13 个测试用例 — `backend/eval_report.json`）：
```
{
"total_fixtures": 13,
"severity_accuracy": 0.77,
"avg_root_cause_quality": 0.79,
"avg_runbook_relevance": 0.53,
"avg_postmortem_completeness": 0.95,
"overall_pipeline_score": 0.76
}
```
### Prompt A/B 测试
对比 prompt 变体：
```
docker compose exec backend python
# 在 Python shell 中
from app.prompts.ab_tester import run_ab_test
import asyncio
test_input = {"alert_type": "cpu_spike", "service": "api-server"}
result = asyncio.run(run_ab_test("root_cause", "1.0", "2.0", test_input))
print(f"Winner: {result['winner']}")
print(f"Improvement: {result['improvement']:.1%}")
```
### 测试套件
```
# 运行所有测试
docker compose exec backend pytest tests/ -v
# 运行覆盖率测试
docker compose exec backend pytest tests/ --cov=app
# 运行特定测试类别
docker compose exec backend pytest tests/test_agents/ -v
```
## 性能目标
| 指标 | 目标 |
|--------|--------|
| 告警处理 (webhook → 202) | <1s |
| 分类时间 | <5s |
| 根因分析 | <15s |
| 完整 pipeline（不含审批） | <60s |
| 单个事件成本 | <$0.10 |
**可扩展性（理想目标——尚未经过负载测试）：**
- 并发的告警接入、活跃的 SSE 连接和 P95 查询延迟
是我们的设计目标，有待通过负载测试工具进行验证。
## 项目结构
```
meridian/
├── backend/
│ ├── app/
│ │ ├── agents/ # LangGraph orchestration
│ │ │ ├── state.py # Shared IncidentState schema (+ blackboard findings)
│ │ │ ├── graph.py # Pipeline + supervised graph builders
│ │ │ ├── nodes/ # Agent nodes (classifier, root cause,
│ │ │ │ │ # supervisor, synthesizer, critic,
│ │ │ │ │ # remediation planner, executor, etc.)
│ │ │ │ └── specialists/ # ReAct sub-agents (metrics, logs, deps, history)
│ │ │ └── edges/ # Conditional routing (pipeline + supervised)
│ │ ├── api/ # FastAPI endpoints
│ │ ├── models/ # SQLAlchemy ORM
│ │ ├── schemas/ # Pydantic schemas
│ │ ├── services/ # Business logic
│ │ ├── tools/ # LangChain tools
│ │ ├── memory/ # 3-tier memory system
│ │ ├── prompts/ # Versioned YAML prompts
│ │ ├── evals/ # Evaluation harness (13 fixtures, scorer)
│ │ ├── utils/ # Safety validator, dedup, token callback
│ │ └── middleware/ # Rate limiter
│ ├── alembic/ # Database migrations
│ ├── scripts/ # Debug/backfill/KB-coverage utilities
│ ├── seed/ # Seed runbooks + past incidents (JSON)
│ ├── loadtest/ # Locust load-test harness
│ ├── tests/ # Test suite
│ └── requirements.txt
├── frontend/
│ ├── src/
│ │ ├── app/ # Next.js App Router pages
│ │ ├── components/ # React components (dashboard, incident, ui)
│ │ ├── hooks/ # useSSE, useIncident, useAgentTrace
│ │ ├── contexts/ # Global incident state
│ │ ├── lib/ # API client + utils
│ │ └── types/ # TypeScript types
│ └── package.json
├── docker-compose.yml
├── .env.example
├── README.md
├── TECHNICAL_DESIGN.md # Full per-file structure + architecture
├── DEPLOYMENT.md
├── IMPLEMENTATION_PLAN.md
└── TASKS.md
```
## 配置
### 环境变量
在项目根目录创建 `.env` 文件：
```
# OpenAI (必填)
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
# API 认证 (在开发环境中可选，在任何实际部署中必填)
# 设置后，更改状态的端点需要以下请求头：X-API-Key: <此值>
API_KEY=
# Agent workflow
AGENT_MODE=supervised # default topology: "supervised" or "pipeline"
# (overridable per incident via the UI toggle / agent_mode payload)
MAX_AGENT_STEPS=6 # Supervisor investigation budget
MAX_REVISIONS=2 # Critic reflection-loop cap
ESCALATION_CONFIDENCE_THRESHOLD=0.6
# 可选的准确性/检索功能 (默认关闭)
SELF_CONSISTENCY_ENABLED=false # Majority-vote severity classification
SELF_CONSISTENCY_SAMPLES=3
SELF_CONSISTENCY_TEMPERATURE=0.5
QUERY_EXPANSION_ENABLED=false # LLM query variants + RRF for runbook search
QUERY_EXPANSION_VARIANTS=3
RRF_K=60
# LangSmith (可选，用于可观测性)
LANGCHAIN_API_KEY=lsv2_...
LANGCHAIN_TRACING_V2=true
LANGCHAIN_PROJECT=meridian
# Prometheus 指标导出 (可选)
METRICS_ENABLED=false # Exposes GET /metrics when true
# 数据库
DATABASE_URL=postgresql+asyncpg://user:password@postgres:5432/meridian
# Redis
REDIS_URL=redis://redis:6379
# Qdrant
QDRANT_URL=http://qdrant:6333
# Grafana (可选，用于 metrics 工具 — 当前为模拟)
GRAFANA_URL=
GRAFANA_API_KEY=
# Slack (可选，用于升级通知 — incoming webhook)
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
# 前端源 (CORS)
FRONTEND_URL=http://localhost:3000
```
## 开发
### 本地开发
```
# 进入 backend 容器
docker compose exec backend bash
# 使用 app context 运行 Python shell
docker compose exec backend python
# 查看带有时间戳的日志
docker compose logs -f --timestamps backend
# 重启单个服务
docker compose restart backend
# 代码更改后重新构建
docker compose up -d --build backend
```
### 数据库管理
```
# 连接到 PostgreSQL
docker compose exec postgres psql -U user -d meridian
# 创建新迁移
docker compose exec backend alembic revision --autogenerate -m "description"
# 应用迁移
docker compose exec backend alembic upgrade head
# 回滚一次迁移
docker compose exec backend alembic downgrade -1
```
### Redis 检查
```
# 连接到 Redis CLI
docker compose exec redis redis-cli
# 查看 keys
KEYS *
# 查看 incident events (replay buffer)
LRANGE incident_replay:incident-id 0 -1
# 查看分布式锁
KEYS alert_lock:*
```
## 高级功能
### 版本化 Prompt
Prompt 以 YAML 文件形式存储，并附带元数据：
```
# app/prompts/root_cause_v2.yaml
version: "2.0"
author: "sre-team"
created_at: "2024-01-15"
last_eval_score: 0.87
changelog: |
- Added Bayesian reasoning structure
- Improved evidence weighting
system: |
You are an expert SRE performing root cause analysis.
Use Bayesian reasoning...
user_template: |
Alert: {alert_description}
Metrics: {grafana_data}
...
```
以编程方式加载 prompt：
```
from app.prompts.loader import load_prompt
# 加载最新版本
prompt = load_prompt("root_cause")
# 加载特定版本
prompt = load_prompt("root_cause", version="1.0")
```
### 置信度门控升级
低置信度的诊断会自动升级：
```
def route_after_root_cause(state):
confidence = state.get("confidence_score", 0.0)
if confidence < 0.6:
state["escalation_reason"] = (
f"Low confidence ({confidence:.0%}) in root cause. "
"Human review required."
)
return "escalation_manager"
return "runbook_executor"
```
### 优雅降级
在 OpenAI API 发生故障时激活备用分类器：
```
# 在 alert_classifier.py 中
try:
result = await llm_chain.ainvoke(alert)
result["classifier_mode"] = "llm"
except Exception:
logger.warning("LLM classification failed, using fallback")
result = await fallback_classifier_node(state)
result["classifier_mode"] = "fallback"
```
## 故障排除
### 常见问题
**问题：前端显示 "Connection failed"**
```
# 检查后端健康状态
curl http://localhost:8000/health
# 在 app/main.py 中检查 CORS 配置
# 确保前端 URL 在 allow_origins 中
```
**问题：创建了重复的事件**
```
# 检查 Redis 连接
docker compose exec redis redis-cli PING
# 验证分布式锁是否正常工作
docker compose exec redis redis-cli KEYS alert_lock:*
```
**问题：SSE 连接断开**
```
# 检查 Redis pub/sub
docker compose exec redis redis-cli
> PUBSUB CHANNELS incident_stream:*
# 验证日志中的 heartbeat
docker compose logs -f backend | grep heartbeat
```
**问题：OpenAI API 错误**
```
# 测试 API key
docker compose exec backend python -c "
from openai import OpenAI
client = OpenAI()
print(client.models.list())
"
# 检查 fallback classifier 激活状态
docker compose logs backend | grep "fallback"
```
### 添加新的 Agent 节点
1. 在 `app/schemas/` 中定义输入/输出 schema
2. 在 `app/agents/nodes/` 中实现节点逻辑
3. 在 `app/agents/graph.py` 中注册
4. 在 `app/agents/edges/routing.py` 中添加路由逻辑
5. 在 `tests/test_agents/` 中编写测试
6. 更新文档
### 添加新工具
1. 在 `app/tools/` 中实现工具
2. 从 `app/tools/__init__.py` 导出
3. 在 agent 节点的 `tools` 参数中注册
4. 记录预期的输入/输出
5. 添加集成测试
### 代码规范
- **类型提示** — 所有函数必须有类型注解
- **文档字符串** — 使用 Google 风格的文档字符串
- **Async/await** — I/O 操作使用异步模式
- **错误处理** — 优雅降级，不吞掉错误
- **日志记录** — 使用结构化日志记录（JSON 格式）
- **测试** — 至少 80% 的代码覆盖率
## 许可证
MIT 许可证 - 详情请参阅 [LICENSE](LICENSE) 文件。
## 致谢
本项目基于以下优秀的开源作品构建：
- [LangChain](https://github.com/langchain-ai/langchain) & [LangGraph](https://github.com/langchain-ai/langgraph) — 多智能体编排
- [FastAPI](https://github.com/tiangolo/fastapi) — 现代异步 Web 框架
- [Qdrant](https://github.com/qdrant/qdrant) — 向量搜索引擎
- [Next.js](https://github.com/vercel/next.js) — React 框架
- [Radix UI](https://www.radix-ui.com/) — 无障碍基础组件
标签：AI智能体, DLL 劫持, LangGraph, 大语言模型, 搜索引擎查询, 故障分析, 自动化运维, 请求拦截, 运维与可靠性, 逆向工具