sumituppal03/pager
GitHub: sumituppal03/pager
基于 Spring Boot 和 LangChain4j 构建的生产级 AI 事件响应 Agent，采用多专家协同架构对接 PagerDuty 告警，通过人工审批机制实现安全的运维诊断与建议。
Stars: 0 | Forks: 0
# Pager
**一个 AI 事件响应 Agent —— 生产级的多 Agent 架构，端到端构建。**
这个仓库同时包含两样东西：
1. **一份从第一性原理出发的架构研究** ([阅读详情 →](./docs/architecture.html))
约一万字，从第一性原理推导设计：资深 SRE 在凌晨 3 点实际上是如何进行诊断的，为什么一个 Postgres 胜过三个数据库，为什么只读操作可以自主发布而写操作绝不可以，以及将设计转化为生产代码的 20 阶段构建生命周期。
2. **一个可运行的 Java + Spring Boot 参考实现**
使用大多数企业级生产系统实际采用的精确技术栈构建 —— Java 21、Spring Boot 3、LangChain4j、PostgreSQL + pgvector、Redis、Docker。通过 GitHub Actions 进行部署。
由位于班加罗尔的 [Sumit Uppal](https://github.com/sumituppal) 构建。
## 为什么使用 Java + LangChain4j，而不是 Python
95% 的 AI Agent 教程都是基于 Python 的。但是：
- 一半的财富 500 强企业在生产环境中运行 Java
- 印度每一家严谨的金融科技、保险和企业 SaaS 都运行在 JVM 上
- LangChain4j 已经存在，可用于生产环境，并且在第一性原理的深度解析文章中几乎无人涉及
Pager 旨在成为标准参考。如果您在生产环境中运行 Java，并且希望在不采用 Python 技术栈的情况下引入 Agentic AI 系统，这就是它的形态。
## 用一段话概述设计
PagerDuty 的 webhook 会触发一个 Spring Boot 入口处理器，该处理器会验证 HMAC，根据 `incident_id + payload_hash` 进行去重，并将分类任务排入 Redis。一个 worker 会对该任务进行出队操作，并通过 LangChain4j 将其并行分发给四个专家 Agent：`symptoms`（什么出现了故障）、`change`（最近部署/更改了什么）、`metrics`（各项数据指标说明了什么），以及 `comms`（要告知用户和团队什么内容）。每个专家都基于对过往的复盘报告和操作手册的检索（通过 pgvector 进行语义加全文搜索，并由倒数排名融合机制进行合并），以及对实时可观测性系统的**只读**工具调用作为支撑。一个聚合器会合并各项发现，对各个专家的去重结果进行交叉验证（并在他们意见一致时提升置信度），然后通过双层的 HITL 闸门来路由处理结果：当整体置信度 ≥ 0.75 时，只读分析会自动发布；建议的写操作（回滚、重启、扩容）会呈现出来，但**绝不**会在没有人工批准的情况下执行。整个过程中的每一个操作都会被写入同一个 Postgres 的 `agent_events` 表中，该表为追踪查看器、审计跟踪和成本台账提供数据支持。
## 架构一览
```
PagerDuty ──► Spring @RestController ──► Redis queue ──► Worker
│
▼
┌────────────────────────────────┐
│ Triage Graph (LangChain4j) │
│ │
│ symptoms change │
│ │ │ │
│ metrics comms │
│ │ │ │
│ └───┬───┘ │
│ ▼ │
│ aggregator │
│ │ │
│ ▼ │
│ HITL gate │
└───────────┬─────────────────────┘
│
read-only ────────┼──────── write action
│ │
▼ ▼
Slack approval queue
│
▼
human approves
│
▼
execute + audit
─────────────── beneath all of it ───────────────
Postgres + pgvector
· knowledge_chunks (memory / RAG)
· triage_runs (truth)
· findings (truth)
· hitl_approvals (truth)
· agent_events (time / append-only spine)
──────────────────────────────────────────────────
```
有关为什么采用这种架构形态而非其他的第一性原理完整推导，请[阅读该研究](./docs/architecture.html)。
## 技术栈
| 层级 | 选择 | 原因 |
|---|---|---|
| 语言 | Java 21 (LTS) | 现代 JVM：records、模式匹配、虚拟线程 |
| 框架 | Spring Boot 3.4 | 生产标准，无可匹敌的生态系统 |
| AI 编排 | LangChain4j 0.36 | 原生 JVM，结构化输出，工具调用，供应商无关 |
| LLM 供应商 | OpenAI + Anthropic | 为每个专家进行供应商路由 |
| 数据库 | PostgreSQL 16 + pgvector | 真相、记忆与时间统一于一个存储中 —— 见研究的第二部分 |
| ORM | Spring Data JPA + Hibernate | 类型安全；由 Flyway 管理 schema |
| 队列 | Redis (Spring Data Redis) | 异步 worker、重试、死信队列 |
| 弹性 | Resilience4j | 重试、熔断器、超时 |
| 前端 | Next.js 15 + TypeScript | 仪表盘 + 追踪查看器 (PR #13) |
| 容器 | Docker + Docker Compose | 从开发到生产使用相同的镜像 |
| CI/CD | GitHub Actions | 对每个 PR 进行类型检查、测试、构建 |
## 快速开始（本地开发）
您需要：Docker Desktop，JDK 21，Maven（或使用 `./mvnw`）。
```
# 1. Clone
git clone https://github.com/sumituppal/pager.git
cd pager
# 2. 启动 Postgres + Redis
docker compose up -d
# 3. 复制 env 模板（默认配置适用于本地开发）
cp .env.example .env.local
# 4. 运行测试（验证连接）
cd pager-api && ./mvnw test
# 5. 运行应用
./mvnw spring-boot:run
# 6. 对 health 端点进行 Sanity check
curl http://localhost:8080/actuator/health
# → {"status":"UP"}
```
## 状态
当前提交版本是可运行的基础基线：Spring Boot 启动，健康检查端点
正常响应，Docker Compose 成功拉起 Postgres（包含 pgvector）+ Redis。在此之后的
所有内容都将以 issue → PR 的形式发布，遵循
[`CONTRIBUTING.md`](./CONTRIBUTING.md) 中的规范。
在[议题页面](https://github.com/sumituppal/pager/issues)和[项目看板](https://github.com/sumituppal/pager/projects)上跟踪进度。
## 仓库结构
```
pager-api/ # Spring Boot backend (this PR)
├── src/main/java/dev/sumituppal/pager/
│ ├── PagerApplication.java
│ ├── domain/ # PR #02: entities, repositories
│ ├── ingress/ # PR #03: webhook, HMAC, idempotency
│ ├── queue/ # PR #03: Redis-backed job queue
│ ├── worker/ # PR #04: consumer, orchestrator
│ ├── specialists/ # PR #07-09: symptoms, change, metrics, comms
│ ├── aggregator/ # PR #09
│ ├── hitl/ # PR #10
│ ├── memory/ # PR #11: pgvector RAG + hybrid retrieval
│ ├── tools/ # PR #12: read-only tool registry
│ ├── observability/ # PR #05: EventEmitter, tracing
│ └── llm/ # PR #06: LangChain4j wiring
└── src/main/resources/
├── application.yml
└── db/migration/ # Flyway SQL migrations
pager-web/ # Next.js + TypeScript frontend (PR #13)
docs/
├── architecture.html # The first-principles study
└── decisions/ # ADRs added as we build
docker-compose.yml # Postgres (pgvector) + Redis for local dev
```
## 贡献 / 反馈
这是一件作品集性质的项目 —— 但我非常希望收到架构层面的反馈。欢迎提交 issue。
如果您是一家 AI 原生或重度依赖 Java 的初创公司的创始人或工程负责人，并且这种思维模式正是您期望在创始/资深工程师身上看到的，我的收件箱随时向您敞开。
## 许可证
MIT.
标签：AI智能体, LangChain4j, RAG, Spring Boot, 域名枚举, 搜索引擎查询, 请求拦截, 运维自动化