mohammed-taha-el-ahmar/incidentcouncil

# IncidentCouncil 一个用于数据平台事件响应的分层多智能体系统。 值班工程师通过提交一个表格、一个现象和一个时间戳来开启一个事件；Incident Commander 会并行将任务委派给四个专家智能体，接收它们的调查结果，并返回一份结构化的简报——包含假设、严重程度、爆炸半径、补救措施，以及是否已准备好回滚候选方案——只需几秒钟即可完成，而无需像往常那样在数仓、血缘图谱、部署流和运维手册库之间来回切换。 ## 该项目解决的问题 一个典型的数据平台事件通常始于某个下游事实表的监控器报警。值班工程师需要在四个地方来回切换以弄清状况： | 问题 | 查看位置 | 此处负责人 | | --- | --- | --- | | 异常在统计上是真实的吗？ | Warehouse / SQL | Metrics Forensics | | 哪个上游出现了故障？ | 血缘图谱，dbt / Airflow | Lineage Detective | | 在事件窗口附近发生了什么变更？ | GitOps，部署流，IAM 审计 | Change Correlator | | 上次我们是如何修复这个问题的？ | 运维手册库，既往复盘报告 | Runbook Historian | 推理过程本质上是并行的——这四个问题在很大程度上是独立的——但单个人类只能串行地回答它们。这就是本项目填补的空白。 ## 架构 ``` incident alert │ ▼ ┌────────────────────┐ │ Incident Commander │ ← supervisor LLM └────────────────────┘ │ ┌─────────┬──────────┼──────────┬──────────┐ ▼ ▼ ▼ ▼ ▼ Metrics Lineage Changes Runbooks (specialists, Forensics Detective Correlator Historian each with its │ │ │ │ own tool set) ▼ ▼ ▼ ▼ DuckDB JSON JSON TF-IDF warehouse lineage deploys runbook + IAM corpus │ ▼ ┌────────────────────┐ │ Incident brief + │ │ attempt trail │ └────────────────────┘ ``` supervisor 暴露了四个工具——`invoke_metrics`、`invoke_lineage`、`invoke_changes`、`invoke_runbooks`——并且没有其他工具。它无法自行查询 DuckDB、读取血缘清单或搜索运维手册；它只能进行委派。 每个专家智能体都会针对真实的工具集运行其自身有界的工具调用循环。Metrics 拥有三个 DuckDB 查询；Lineage 拥有三个 JSON 清单查询；Changes 拥有三个流查询；Runbooks 拥有基于本地 TF-IDF 索引的 `search_runbooks`。每次工具调用都会记录在专家的 `SpecialistFinding` 中，以便 supervisor 和 UI 能够进行端到端的审计推理。 智能体之间的每条消息都是一个 Pydantic 模型，因此工具 schema、FastAPI 响应和 UI 全都读取同一个唯一事实来源。 ## 阶段划分 本仓库分两个阶段交付，因此每一轮都会以一个通过测试的、自包含的绿色切片结束。 **阶段 1（本仓库，已完成）：** 本地 Groq 路径完全可用。`LocalCouncil` orchestrator、四个专家智能体、真实的 DuckDB + JSON + 本地运维手册索引、FastAPI + 尝试轨迹 UI、带有 `ScriptedFakeLLM` 的 pytest 测试套件，ruff 检查通过。 **阶段 2（下一步）：** 通过 Terraform 配置的 AWS Bedrock Agents（Claude 3.5 Sonnet supervisor，Amazon Nova Lite 专家智能体）、每个专家对应的 Lambda action groups、基于 OpenSearch Serverless 的 Bedrock Knowledge Base（用于运维手册语料库）、用于会话和简报历史的 DynamoDB，外加一个镜像 `LocalCouncil` 接口的 `BedrockCouncil` 类，从而保持 FastAPI 接口保持不变。 ## 快速开始 ``` make install # uv sync --extra dev make test # 30 tests, zero cloud credentials make lint # ruff check make demo # runs the sample incident with a scripted fake LLM (no network) make serve # boots the FastAPI dispatch console on :8000 ``` 要调用真实的 LLM 而不是脚本模拟的虚假 LLM： ``` cp .env.example .env # 编辑 .env：设置 INCIDENTCOUNCIL_LLM_BACKEND=groq 和 GROQ_API_KEY=... make serve ``` ## 仓库结构 ``` src/incidentcouncil/ schemas.py Pydantic contracts between all agents & the UI settings.py pydantic-settings env config local_council.py Supervisor orchestrator + delegation loop factory.py Wires LLM + tools + specialists cli.py `python -m incidentcouncil.cli demo` llm/ base.py LLMClient protocol, message/tool-call dataclasses groq_client.py Live Groq HTTP client fake_llm.py ScriptedFakeLLM for deterministic tests specialists/ base.py Bounded tool-calling loop + finding parser metrics.py Metrics Forensics lineage.py Lineage Detective changes.py Change Correlator runbooks.py Runbook Historian tools/ warehouse.py DuckDB queries (row_count history, baseline, freshness) lineage_graph.py JSON lineage + job runs + schema diffs changes.py Deploys / config / IAM feeds vector_search.py Deterministic TF-IDF over the runbook corpus api/ app.py FastAPI: /api/incidents, /api/incidents/sample, / frontend/ Vanilla-JS attempt-trail UI (no build step) fixtures/ DuckDB seed, JSON fixtures, runbook markdown tests/ 30 tests, all offline, all deterministic docs/DEMO.md Honest coverage matrix ``` ## 值得在面试中讨论的亮点 - **分层委派，而不是单个智能体配备更多工具。** supervisor 看不到任何数仓或血缘工具——它只能调用专家。每个专家都拥有自己有界的工具循环。正是这种分离，使其成为一个名副其实的*council*（委员会），而不是一个带有更长 prompt 的根因调查器。 - **每个专家都各司其职。** Metrics 决定*该异常是否真实*，而不是*是什么导致了它*。Lineage 决定*哪个上游出现了故障*，而不是*该异常是否显著*。supervisor 是唯一将它们结合成假设的智能体。这就是多智能体协同。 - **每一个发现都达到了审计级。** 发现包含了生成这些发现的完整工具调用记录。UI 会渲染出该轨迹；测试会对其进行断言。这就是一个仅用于演示的多智能体系统与一个能在面试审查下站得住脚的系统之间的区别。 - **确定性测试，真实固件。** LLM 是脚本化的，但工具运行在真实的 DuckDB 数仓和真实的 TF-IDF 索引上。测试套件还兼具针对 supervisor 和专家 prompt 的回归防护作用（脚本化的模拟器拒绝过度运行）。 - **通过契约实现本地 ↔ 云端对等。** `LocalCouncil` 和阶段 2 的 `BedrockCouncil` 将实现相同的 `handle(alert) -> CouncilResponse` 契约。FastAPI 接口、UI、固件和测试永远不需要知道背后运行的是哪一个。

标签：PyRIT, 人工智能, 多智能体系统, 安全规则引擎, 数据平台, 用户模式Hook绕过, 自动化运维, 逆向工具