Texelbit/agentx-hackaton
GitHub: Texelbit/agentx-hackaton
这是一个基于多智能体架构的SRE事件响应系统，利用AI与RAG技术实现事件自动分诊、Jira工单创建及GitOps全生命周期管理。
Stars: 0 | Forks: 0
# 🤖 SRE 事件响应 Agent
## 解决方案简介
SRE Incident Response Agent 是一个自主多智能体系统，旨在消除事件分诊（triage）的手工负担。非技术用户通过对话式聊天界面用自然语言描述问题，并可选择粘贴截图。系统的 IntakeAgent 收集上下文，自动结束对话，并触发一个管道：通过基于 RAG 的 AI 进行分诊，创建包含证据附件的结构化 Jira 工单，打开 GitHub 分支，并通过电子邮件和 Slack 通知值班团队 —— 所有这些都在 30 秒内完成。
该解决方案的与众不同之处在于其端到端的生命周期自动化。一个可配置的 GitOps 状态机跨环境分支（dev → qa → main）跟踪 GitHub 事件（push、PR、merge），并自动将内部事件和 Jira 工单转换到各自的工作流中。当修复部署到生产环境时，EmailComposerAgent 会向原始报告人发送个性化的解决通知。整个管道通过结构化审计日志进行观察，涵盖从接收到解决的每个阶段。
该系统专为可配置性而构建：LLM 提供商可以在管理仪表板中运行时切换，GitOps 规则支持拖放重排，Jira 集成与语言无关（适用于任何语言环境）。基于 NestJS、React、Prisma、pgvector、Google Gemini 2.5 Pro 和 Google Cloud Storage 构建。
[](https://nestjs.com)
[](https://react.dev)
[](https://prisma.io)
[](https://github.com/pgvector/pgvector)
[](#-ai-agents)
## 📚 文档导航
| 文档 | 内容 |
|---|---|
| **[QUICKGUIDE.md](QUICKGUIDE.md)** | 单命令设置、`.env` 详解、验证、预构建测试场景 |
| **[AGENTS_USE.md](AGENTS_USE.md)** | 深入探讨每个智能体、编排、上下文工程、安全性、可观测性 |
| **[SCALING.md](SCALING.md)** | 系统如何扩展、假设、瓶颈、水平扩展计划 |
| **[HANDOFF.md](HANDOFF.md)** | 完整的技术交接 —— 模块图、IoC 桥接、设计模式、集成设置 |
| **🎥 [Demo video](https://www.youtube.com/watch?v=YOUR_VIDEO_ID)** | 3 分钟完整端到端流程演示 |
## 🎯 功能演示
非技术用户（例如参考电商平台 **Reaction Commerce** 的支持人员）打开一个极简的聊天 UI，用自然语言描述问题，并可选择附上截图。在几秒钟内，系统会：
1. **聊天**：通过 `IntakeAgent` 与报告人对话，直到收集到足够的上下文（从不询问标题、优先级或技术元数据）。
2. **自动结束**对话，将其向量化，并运行 **pgvector 相似性搜索** 以查找相关的过往事件。
3. **分诊**：使用 `TriageAgent`（Gemini 2.5 Pro）对事件进行分诊 —— 基于上下文生成标题、描述、优先级、服务和摘要。
4. **创建 Jira 工单**：在配置的项目中创建（语言无关 —— 支持英语、西班牙语或任何语言）。
5. **创建 GitHub 分支**：从 `main` 创建分支，以便工程师可以立即开始工作。
6. **通知团队**：通过电子邮件（Gmail SMTP）和 Slack 发送内容丰富且带有品牌标识的信息进行通知。
7. **响应 GitHub 事件**（push、PR opened、PR merged...）：通过签名的 webhook 触发，并根据可配置的 **GitOps 状态机** 推进内部事件和 Jira 工单。
8. 当状态为 `DONE` 时，`EmailComposerAgent` 起草并向原始报告人发送个性化的解决通知。
## ✅ 黑客马拉松交付物清单
| 需求 | 状态 | 证据 |
|---|---|---|
| 事件提交 UI | ✅ | [`apps/report-web/src/pages/ChatPage.tsx`](apps/report-web/src/pages/ChatPage.tsx) |
| LLM 驱动的分诊 | ✅ | [`apps/backend/src/incidents/agents/sre.agent.ts`](apps/backend/src/incidents/agents/sre.agent.ts) |
| 自动创建工单 (Jira) | ✅ | [`apps/backend/src/integrations/jira/jira.service.ts`](apps/backend/src/integrations/jira/jira.service.ts) |
| 团队通知 (Email + Slack) | ✅ | [`apps/backend/src/notifications/observers/`](apps/backend/src/notifications/observers/) |
| 解决通知 | ✅ | [`email.observer.ts`](apps/backend/src/notifications/observers/email.observer.ts) |
| `README.md` | ✅ | 本文件 |
| `QUICKGUIDE.md` | ✅ | [QUICKGUIDE.md](QUICKGUIDE.md) |
| `AGENTS_USE.md` | ✅ | [AGENTS_USE.md](AGENTS_USE.md) |
| 根目录 `docker-compose.yml` | ✅ | [docker-compose.yml](docker-compose.yml) |
| 根目录 `.env.example` | ✅ | [.env.example](.env.example) |
| 演示视频 (≤10 min) | ⏳ | _待补充_ |
## 🧠 AI 智能体
| 智能体 | 类型 | 当前配置模型 | 职责 | 源码 |
|---|---|---|---|---|
| **IntakeAgent** | 推理 (可配置) | **Gemini 2.5 Pro** | 与报告人进行自然对话，上下文充足时自动结束 | [`intake.agent.ts`](apps/backend/src/chat/agents/intake.agent.ts) |
| **TriageAgent (SREAgent)** | 推理 (可配置) | **Gemini 2.5 Pro** | 基于 RAG 的分诊 → 结构化事件 DTO | [`sre.agent.ts`](apps/backend/src/incidents/agents/sre.agent.ts) |
| **EmailComposerAgent** | 推理 (可配置) | **Gemini 2.5 Pro** | 撰写给报告人的解决邮件 | [`email.observer.ts`](apps/backend/src/notifications/observers/email.observer.ts) |
| **Embeddings** | 向量化 (固定) | **OpenAI `text-embedding-3-small`** (1536 维) | 将事件和仓库文件向量化，用于 pgvector 相似性搜索 | [`rag.service.ts`](apps/backend/src/rag/rag.service.ts) |
要将任何推理智能体切换到不同的提供商/模型，无需更改代码：打开 **Admin → LLM**，编辑该智能体角色的分配行，下一次调用将使用新模型。配置表：`llm_providers`、`llm_models`、`llm_configs`（参见 [Prisma schema](apps/backend/prisma/schema.prisma))。
## 🏗️ 架构
```
flowchart LR
U[👤 Reporter
report-web] -->|SSE chat| BE[NestJS backend] A[🛠️ Admin
dashboard-web] -->|REST + WS| BE BE --> IA(IntakeAgent) IA -->|auto-finalize| TA(TriageAgent) TA -.RAG.-> PG[(Postgres
+ pgvector)] TA --> JIRA[Jira Cloud] TA --> GH[GitHub API] TA --> NOTI[Notifications] NOTI --> MAIL[Gmail SMTP] NOTI --> SLACK[Slack webhook] GH -->|webhook HMAC| BE BE -->|state machine| JIRA ``` **核心模块**（均位于 [`apps/backend/src/`](apps/backend/src/))： - [`auth/`](apps/backend/src/auth/) — JWT RS256 + refresh 轮换 + RBAC 守卫 - [`chat/`](apps/backend/src/chat/) — SSE 流式传输 + IntakeAgent + 自动结束管道 - [`incidents/`](apps/backend/src/incidents/) — 完整的分诊管道 + 相似性检测 - [`rag/`](apps/backend/src/rag/) — pgvector 相似性 + 仓库索引器 - [`integrations/jira/`](apps/backend/src/integrations/jira/) — 与语言无关的 Jira 客户端（通过 `statusCategory.key` 匹配） - [`integrations/github/`](apps/backend/src/integrations/github/) — 分支创建 + 幂等 webhook 安装 - [`branch-rules/`](apps/backend/src/branch-rules/) — GitOps 状态机（支持拖放排序的规则） - [`webhooks/`](apps/backend/src/webhooks/) — HMAC 验证的 GitHub webhook 处理程序 - [`notifications/`](apps/backend/src/notifications/) — 观察者模式通知器（Email, Slack） - [`llm/`](apps/backend/src/llm/) — 运行时 LLM 提供商/模型/分配 CRUD ## 🧱 技术栈 **后端** — NestJS 10 · Prisma 5 · PostgreSQL (Supabase) · pgvector · Socket.io · nodemailer · JWT RS256 **前端** — React 18 · Vite 6 · TypeScript · TailwindCSS · framer-motion · @tanstack/react-query · zustand · @dnd-kit · socket.io-client **AI** — Gemini 2.5 Pro (当前) · OpenAI `text-embedding-3-small` (embeddings) · 运行时可切换至 OpenAI / Anthropic Claude **集成** — Jira Cloud REST v3 · GitHub REST v3 + Webhooks · Gmail SMTP · Slack incoming webhook **DevOps** — Docker Compose · VS Code Dev Tunnels · `npm run init` 一键引导 ## 🚀 快速开始 ``` git clone && cd agentx-hackaton
cp .env.example .env # fill in keys — see QUICKGUIDE.md
npm run init # installs, migrates, seeds Jira + GitHub, indexes repo
npm run dev:backend # :3000
npm run dev:dashboard # :5173
npm run dev:report # :5174
```
➡️ 完整设置 + 测试场景：**[QUICKGUIDE.md](QUICKGUIDE.md)**
## 🔐 安全亮点
- **HMAC 验证的 webhooks** — [`webhook-hmac.guard.ts`](apps/backend/src/webhooks/guards/webhook-hmac.guard.ts) 拒绝未签名的 GitHub 事件
- **具有细粒度权限的 RBAC** — [`auth/decorators/`](apps/backend/src/auth/decorators/)
- **受保护的超管** — 数据库强制执行的 `isProtected` 标志
- **登录后的 Swagger UI** — [`swagger-auth.middleware.ts`](apps/backend/src/swagger/swagger-auth.middleware.ts)
- **全局输入验证** — `ValidationPipe({ whitelist: true, forbidNonWhitelisted: true })`
- **提示注入防御** — 不受信任的用户文本包裹在 `<<>>` 分隔符中，系统提示明确指示模型将该块视为数据，仅 JSON 响应配合严格的模式验证，枚举绑定的优先级字段
- **速率限制** — 全局 `ThrottlerGuard`（60 次/分/IP）接入 [`app.module.ts`](apps/backend/src/app.module.ts)
- **凭证卫生** — `.env` 被 git 忽略，JWT RS256 密钥对由 `npm run init` 生成
- **GCP 凭证** — 包含一个仅用于测试的服务帐户（Storage Object Creator/Viewer），供黑客athon评委使用，位于 `apps/backend/.keys/gcp-credentials.json`。该凭证将在活动结束后**撤销**。评委可以通过更新环境变量使用自己的 GCP 帐户（参见 [`.env.example`](.env.example))
## 👤 作者
**Manuel Garcia** — AgentX Hackathon 2026
## 📄 许可证
[MIT](LICENSE)
report-web] -->|SSE chat| BE[NestJS backend] A[🛠️ Admin
dashboard-web] -->|REST + WS| BE BE --> IA(IntakeAgent) IA -->|auto-finalize| TA(TriageAgent) TA -.RAG.-> PG[(Postgres
+ pgvector)] TA --> JIRA[Jira Cloud] TA --> GH[GitHub API] TA --> NOTI[Notifications] NOTI --> MAIL[Gmail SMTP] NOTI --> SLACK[Slack webhook] GH -->|webhook HMAC| BE BE -->|state machine| JIRA ``` **核心模块**（均位于 [`apps/backend/src/`](apps/backend/src/))： - [`auth/`](apps/backend/src/auth/) — JWT RS256 + refresh 轮换 + RBAC 守卫 - [`chat/`](apps/backend/src/chat/) — SSE 流式传输 + IntakeAgent + 自动结束管道 - [`incidents/`](apps/backend/src/incidents/) — 完整的分诊管道 + 相似性检测 - [`rag/`](apps/backend/src/rag/) — pgvector 相似性 + 仓库索引器 - [`integrations/jira/`](apps/backend/src/integrations/jira/) — 与语言无关的 Jira 客户端（通过 `statusCategory.key` 匹配） - [`integrations/github/`](apps/backend/src/integrations/github/) — 分支创建 + 幂等 webhook 安装 - [`branch-rules/`](apps/backend/src/branch-rules/) — GitOps 状态机（支持拖放排序的规则） - [`webhooks/`](apps/backend/src/webhooks/) — HMAC 验证的 GitHub webhook 处理程序 - [`notifications/`](apps/backend/src/notifications/) — 观察者模式通知器（Email, Slack） - [`llm/`](apps/backend/src/llm/) — 运行时 LLM 提供商/模型/分配 CRUD ## 🧱 技术栈 **后端** — NestJS 10 · Prisma 5 · PostgreSQL (Supabase) · pgvector · Socket.io · nodemailer · JWT RS256 **前端** — React 18 · Vite 6 · TypeScript · TailwindCSS · framer-motion · @tanstack/react-query · zustand · @dnd-kit · socket.io-client **AI** — Gemini 2.5 Pro (当前) · OpenAI `text-embedding-3-small` (embeddings) · 运行时可切换至 OpenAI / Anthropic Claude **集成** — Jira Cloud REST v3 · GitHub REST v3 + Webhooks · Gmail SMTP · Slack incoming webhook **DevOps** — Docker Compose · VS Code Dev Tunnels · `npm run init` 一键引导 ## 🚀 快速开始 ``` git clone
标签：AgentX, API集成, Claude AI, DLL 劫持, GitOps, Google Cloud Storage, Hackathon 2026, Jira 集成, LLM, NestJS, OpenAI, pgvector, PostgreSQL, Prisma, RAG, React, Slack 集成, SRE, Syscalls, Unmanaged PE, Vite, 事件管理, 偏差过滤, 全栈应用, 内存规避, 可观测性, 后端开发, 向量数据库, 多智能体, 大语言模型, 审计日志, 工作流自动化, 故障响应, 智能运维, 检索增强生成, 测试用例, 生命周期管理, 自动化分诊, 角色权限, 请求拦截, 通知系统, 邮件通知