NANDAGOPALNG/sentinal-opscenter-v2

# Sentinal OpsCenter V2 **面向站点可靠性工程的自主多智能体事件响应平台** Sentinal OpsCenter V2 是一个智能 SRE 工作流引擎，它接收生产事件，通过结构化的响应流水线编排协调一致的 AI 智能体团队，并将从分诊到修复的完整审计跟踪记录持久化在可查询的 API 中。 ## 概述 现代工程团队在检测事件到执行协调响应之间的空档期浪费了关键时间。Sentinal OpsCenter V2 通过在事件到达时立即部署专业化 AI 智能体流水线来消除这一差距。每个智能体拥有明确的职责：规划、研究、修复建议、验证和通知。这些智能体通过有状态的 LangGraph 工作流进行协作，并且每个决策都会持久化到 SQLite 中，以便进行完整的事件事后审查。 ## 架构 ``` Incoming Event (webhook / manual) | v Event Normalizer ───────────────────────────────────────────────────────────────────── | | v Idempotency LangGraph Workflow Guard | +──> Planner Agent Creates a structured incident response plan (Groq LLM) | +──> Researcher Agent Gathers context: GitHub repo summary, file snippets, | live web search via Tavily (when configured) | +──> Fixer Agent Drafts a safe, actionable remediation proposal (Groq LLM) | +──> Validator Agent Verifies the proposal includes investigation steps, | | validation criteria, and rollback/safety language | | | +── PASS ──> Finish Node | | | +── FAIL ──> Retry Node ──> Planner (up to max_retries) | | | +── MAX RETRIES ──> Fail Node | +──> Notifier Agent Records lifecycle notifications; optionally posts to Discord | v SQLite Persistence Full workflow state: plan, findings, GitHub context, file snippets, fix proposal, validation report, notifications, trace ID, dedupe key ``` ## 智能体职责 | 智能体 | 角色 | 支撑 | |---|---|---| | 规划器 (Planner) | 解析事件并生成逐步响应计划 | Groq LLM (llama-3.3-70b-versatile) | | 研究员 (Researcher) | 获取仓库上下文、文件片段和实时网络搜索结果 | GitHub API (只读) + Tavily | | 修复者 (Fixer) | 在研究上下文的基础上起草修复建议 | Groq LLM | | 验证器 (Validator) | 检查建议的完整性、可操作性和回滚覆盖范围 | 本地基于规则 | | 通知器 (Notifier) | 记录生命周期事件并在配置后发布到 Discord | Discord webhook | ## 核心功能 **工作流引擎** - 具有条件重试路由的异步 LangGraph 状态机 - 带反馈的自动重试：失败的提案会连同明确指出缺失内容的指导意见一起重新进入规划器 - 可配置的最大重试上限，防止无限循环 **事件接入** - 通过 `/webhook` 接受任意 JSON 负载 - GitHub 事件规范化——原始的 push、pull request 和 issue 事件被映射为统一的事件模式 - 设置 `GITHUB_WEBHOOK_SECRET` 后，通过 `X-Hub-Signature-256` 验证 Webhook 签名 - 通过 `X-GitHub-Delivery` 头或显式的 `idempotency_key` 字段实现幂等性——重复提交会被检测并拒绝，不会重新执行工作流 **GitHub 集成（只读）** - 仓库摘要：待解决的 issue、近期的 pull request、贡献者活动 - 安全的文件检查：在工作流执行期间从仓库获取特定的文件路径 - 路径遍历保护和可配置的文件限制 **持久化** - 通过异步 SQLAlchemy 将完整的工作流状态写入 SQLite - 可通过工作流 ID 查询；所有智能体输出存储为结构化的 JSON 字段 - Trace ID 和去重键与结果一起存储，用于调试和审计 **可观测性** - `/health` 端点用于存活探针 - `/github/status` 用于查看认证和 webhook 安全配置状态 - `/webhook/preview` 用于空运行规范化而不触发工作流 - Streamlit 仪表板，用于浏览工作流历史记录 ## 项目结构 ``` sentinal-opscenter-v2/ ├── agents/ │ ├── fixer/ Groq-backed remediation proposal agent │ ├── notifier/ Lifecycle notification agent (log + Discord) │ ├── planner/ Groq-backed incident response planner │ ├── researcher/ GitHub context + Tavily web search agent │ └── validator/ Local proposal validator ├── apps/ │ ├── api/ │ │ ├── db/ Async SQLAlchemy setup, CRUD operations │ │ ├── services/ Workflow executor │ │ └── main.py FastAPI application, all route definitions │ └── dashboard/ Streamlit workflow browser ├── shared/ │ ├── config/ Pydantic settings, environment variable binding │ ├── models/ SQLAlchemy ORM models │ ├── schemas/ Pydantic workflow state schema │ └── utils/ Event normalizer, idempotency, webhook security ├── tools/ │ ├── github/ Read-only GitHub API client │ └── search/ Tavily web search client ├── workflows/ │ └── incident_graph.py LangGraph workflow definition and node wiring ├── scripts/ │ └── smoke-test.ps1 End-to-end test script ├── Dockerfile ├── docker-compose.yml └── pyproject.toml ``` ## 技术栈 | 层级 | 技术 | |---|---| | API 框架 | FastAPI + Uvicorn | | 工作流引擎 | LangGraph | | LLM | Groq (llama-3.3-70b-versatile) | | 数据库 | SQLite + async SQLAlchemy + aiosqlite | | GitHub 集成 | PyGitHub | | 网络搜索 | Tavily | | 仪表板 | Streamlit | | 运行时 | Python 3.12+ | | 包管理器 | uv | | 容器化 | Docker + docker-compose | ## 设置 ### 1. 克隆并配置环境 ``` cp .env.example .env ``` 打开 `.env` 并设置你的密钥： ``` # 必需 GROQ_API_KEY=your_groq_api_key_here # 推荐 — 启用 GitHub context enrichment GITHUB_TOKEN=your_github_token_here GITHUB_REPOSITORY=owner/repository-name # 可选 — 启用 Researcher agent 中的实时网络搜索 TAVILY_API_KEY=your_tavily_api_key_here # 可选 — 启用 webhook signature verification GITHUB_WEBHOOK_SECRET=your_webhook_secret_here # 可选 — 启用 Discord lifecycle notifications DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/... ``` 只有 `GROQ_API_KEY` 是必填项。所有其他集成在未配置时会优雅降级。 ### 2. 使用 Docker 启动 ``` docker-compose up --build ``` API 可通过 `http://localhost:8001` 访问。 ### 3. 运行 Streamlit 仪表板（可选） ``` uv run streamlit run apps/dashboard/streamlit_app.py ``` 仪表板可通过 `http://localhost:8501` 访问。 ## API 参考 ### 健康检查 ``` GET /health ``` 返回服务存活状态和版本。 ### GitHub 状态 ``` GET /github/status ``` 报告 GitHub 认证状态和 webhook 安全配置。 ### Webhook 预览 ``` POST /webhook/preview ``` 在不执行工作流的情况下空运行 GitHub 事件规范化。适用于验证负载结构。 ### 提交事件 ``` POST /webhook ``` 规范化传入事件，检查幂等性，并异步运行完整的多智能体工作流。 **示例负载：** ``` { "event_type": "latency_spike", "service": "api", "severity": "warning", "message": "P99 latency exceeded threshold on /checkout", "repository": "owner/repo-name", "files": ["apps/api/main.py", "workflows/incident_graph.py"] } ``` ### 列出工作流 ``` GET /workflows ``` 返回按创建时间排序的所有已持久化的工作流运行记录。 ### 检查工作流 ``` GET /workflows/{id} ``` 返回完整的工作流记录，包括计划、研究发现、GitHub 上下文、文件片段、修复建议、验证报告、通知、Trace ID 和去重键。 ## 运行冒烟测试 ``` .\scripts\smoke-test.ps1 ``` 如果 `GITHUB_WEBHOOK_SECRET` 仅存在于 `.env` 中而未导出到 shell： ``` .\scripts\smoke-test.ps1 -WebhookSecret "your_secret_here" ``` 冒烟测试会提交一个合成事件，轮询直至完成，并打印所有持久化的智能体输出。 ## 幂等性 Sentinal 在执行工作流之前对传入事件进行去重。如果存在 `X-GitHub-Delivery` 头，它将被用作去重键。否则，将使用请求体中显式的 `idempotency_key` 字段。 两次提交相同的事件会产生： ``` first request → { "status": "accepted" } second request → { "status": "duplicate" } ``` 对于每个唯一事件，工作流只会精确运行一次。 ## 范围和设计决策 **设计上采用只读的 GitHub 集成。** 系统检查仓库状态以为修复建议提供信息，但不会创建分支、提交或 pull request。可写操作保留在验证和安全框架得到进一步强化之后的未来阶段进行。 **本地验证器。** 验证器智能体使用确定性的基于规则的检查，而不是额外的 LLM 调用。这使得验证步骤快速、可预测，并消除了对于回滚覆盖等安全关键检查的幻觉风险。 **选择 SQLite 以保证可移植性。** 选择 SQLite 是为了实现零基础设施的本地和演示部署。异步 SQLAlchemy 设置与 PostgreSQL 兼容，只需更改连接字符串即可进行切换。 **带有结构化反馈的重试。** 当验证器拒绝修复建议时，工作流不会简单地盲目重试。重试节点将描述缺失内容的明确指导注入到工作流状态中，并在重新进入时将此指导传递给规划器，以便下一次提案包含有关上次失败的上下文。 ## 路线图 - 可写的 GitHub 操作：分支创建、提交、pull request - 研究员智能体中的实时 Tavily 网络搜索（集成已完成；需要密钥） - 通过 Alembic 进行生产数据库迁移 - 具有实时工作流状态的增强版 Streamlit 仪表板 ## 许可证 MIT

标签：AIOps, AI智能体, API集成, CISA项目, DLL 劫持, IP 地址批量处理, IT运维, Kubernetes, LangGraph, LLMOps, Socks5代理, SQLite, SRE, Webhook, 代码修复建议, 偏差过滤, 力导向图, 可观测性, 多智能体, 大语言模型, 工作流引擎, 故障自愈, 生产故障处理, 自动化运维, 请求拦截, 运维自动化, 逆向工具