nutcas3/runbook-agent
GitHub: nutcas3/runbook-agent
AI 驱动的事件响应 agent，将运维 runbook 转为可执行安全状态机，通过 Gemini 诊断事件并在人工批准后执行恢复操作。
Stars: 0 | Forks: 0
# runbook-agent
一个由 AI 驱动的事件响应 agent，它能将 runbook 转换为可执行且安全的状态机。你无需在凌晨两点从 Markdown 文件中复制粘贴命令，该 agent 会使用 Gemini 诊断事件，提出恢复操作建议，并在获得人工批准后执行它。
## 功能介绍
1. 通过 webhook 接收警报 (`POST /api/alerts`)
2. 从 YAML 加载结构化的 runbook（诊断步骤 + 恢复操作）
3. 使用 Gemini 结合只读工具（`kubectl`、`curl`、`redis-cli`、Prometheus）**诊断事件**
4. **形成结构化假设**（根本原因、置信度、风险等级）
5. **检查安全关卡** —— 拒绝禁止的操作；高风险操作将暂停等待人工批准
6. **执行恢复** —— 仅在工程师通过 dashboard 批准后执行
7. **记录所有内容** —— 记录到审计跟踪中（默认使用 SQLite）
## 架构
```
cmd/server HTTP server (alerts, approvals, audit)
internal/agent Gemini agent with read-only diagnostic tools
internal/runbook YAML parser, executor, and Agent interface
internal/model Shared types (Hypothesis) — cycle-free
internal/approval Human-in-the-loop gate
internal/audit SQLite audit store
internal/safe Safety enforcer (read-only + approval lists)
```
## 安全模型
该 agent 在诊断期间**仅进行读取**。它不能：
- 执行非白名单命令
- 未经明确批准修改状态
- 绕过安全执行器
恢复操作会与 runbook 的 `safe_state` 进行核对：
```
safe_state:
read_only:
- delete_database
requires_approval:
- restart_service
```
## 快速开始
### 前置条件
- Go 1.26+
- `GOOGLE_API_KEY` 环境变量（用于 Gemini）
- 已配置的 `kubectl`（可选，用于 K8s 诊断）
### 运行
```
go run ./cmd/server
```
服务器监听 `:8080`。
### 触发 runbook
```
curl -X POST http://localhost:8080/api/alerts \
-H "Content-Type: application/json" \
-d '{
"alert": "PaymentGatewayErrorRate",
"severity": "critical",
"runbook": "payment-gateway-failure",
"telemetry": "error_rate: 45%, p99_latency: 2.3s"
}'
```
### 端点
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `POST` | `/api/alerts` | 接收警报 webhook |
| `GET` | `/api/approvals` | 列出待处理的批准 |
| `POST` | `/api/approvals/:id/approve` | 批准操作 |
| `POST` | `/api/approvals/:id/reject` | 拒绝操作 |
| `GET` | `/api/incidents/:id/history` | 审计跟踪 |
| `GET` | `/health` | 存活探针 |
## Runbook 格式
```
name: payment-gateway-failure
version: "1.0"
severity: critical
mttr_target: 5m
triggers:
- alert: PaymentGatewayErrorRate
threshold: "> 10%"
duration: 2m
safe_state:
read_only:
- delete_database
requires_approval:
- restart_service
diagnostic_steps:
- step: 1
name: Check pod status
command: kubectl get pods -n payments
ai_interpret: Look for CrashLoopBackOff or high restart counts
recovery_actions:
- condition: stripe_down
action: restart_service
requires_approval: true
command: kubectl rollout restart deployment/payment-gateway -n payments
rollback_command: kubectl rollout undo deployment/payment-gateway -n payments
```
## 项目结构
| 包 | 职责 |
|---------|---------------|
| `internal/agent` | Gemini agent、诊断工具、假设生成 |
| `internal/runbook` | YAML 解析、runbook 执行引擎、`Agent` 接口 |
| `internal/model` | 共享数据类型（避免循环导入） |
| `internal/approval` | 人工批准队列和阻塞请求 |
| `internal/audit` | 基于 SQLite 的事件日志 |
| `internal/safe` | 安全策略执行 |
## 设计决策
- **Agent 仅进行读取** —— 所有写操作均在安全检查后于执行器中进行
- **接口驱动** —— `runbook.Agent` 将执行器与具体的 Gemini agent 解耦
- **Model 包** —— `internal/model` 打破了 `agent ↔ runbook` 的循环导入
- **Genkit v1.10** —— 使用 `ai.ToolContext`、`ai.WithConfig` 和 `genkit.GenerateData` API
标签：AI智能体, EVTX分析, Go, Pandas, Ruby工具, 搜索引擎查询, 故障响应, 日志审计, 状态机, 自定义请求头, 运维自动化