HadiaIshtiaqq/Maestro

# Maestro — 企业级重大事件响应与协调平台 **Band of Agents 黑客松 (lablab.ai) · 赛道 3 — 受监管与高风险工作流** Maestro 是一个多 agent 平台，可将海量原始运维和安全信号转化为单一、受控且完全可追溯的事件响应流程 —— 由 11 个专业化 agent 和一名人类指挥官在一个共享的 **Band room** 内进行实时协调。 ## 为什么选择 Maestro (赛道 3) | 要求 | Maestro 的实现方式 | |---|---| | 通过 Band 运行 ≥3 个 agent | 在每个事件专属的 Band room 中部署 11 个 agent + 人类指挥官 | | 受监管 / 高风险 | 企业级：安全漏洞、系统宕机、数据完整性 —— 支持 DORA/SOC2/HIPAA 风格的工作流 | | 人类在环 | 人类指挥官的批准对于 SEV-1/SEV-2 **由策略强制执行** (对于较低严重级别，LLM 可以请求通过该关卡，但无法选择退出)；在 5 分钟超时或服务器重启时自动否决 | | 审计追踪 | 每条 Band 消息在投递完成前都会同步到 MongoDB；可通过 `/api/band/audit-trail/:id` 导出合规报告；房间会在重启时从 MongoDB 恢复数据 | | 跨框架 | 当设置了 `ANTHROPIC_API_KEY` 时，验证 agent 运行 **Claude (Anthropic)** (否则回退至 Gemini —— 追踪记录会记录实际运行的引擎)；其他所有 agent 均使用 Gemini 2.0 Flash | | 动态招募 | 指挥官在确认严重程度后会招募第二阶段的团队 (基于严重程度的策略：SEV-1–3 为完整团队，SEV-4/5 为精简团队) | ## 架构 ``` Signal Sources ──POST /api/ingest-signal──▶ Intake Agent │ opens Band room │ ┌──────────────── BAND ROOM ─────────────────┐ │ Correlation ─▶ Validation(Claude) ─▶ Classification ─▶ Severity │ Commander recruits: │ Allocation · DepSim · Mitigation · Runbook · Comms │ │ │ approval_request (requires_human_approval) │ ▼ │ Human Commander: approve / veto │ (msg_type authority rules enforced in the adapter) └─────────────────────────────────────────────┘ │ │ MongoDB (audit) Operator Web View ``` ## 快速开始 ``` npm install cp .env.example .env # add GEMINI_API_KEY + MONGODB_URI (+ ANTHROPIC_API_KEY for the Claude agent) npm run dev # starts server + Vite on http://localhost:3000 npx tsx scenarios/demo_runner.ts all # fires 3 demo scenarios ``` **操作员视图:** http://localhost:3000 — 选择一个事件 → 进入 **Band Room** 标签页查看实时协调信息和批准关卡。 ### 环境变量 | 变量 | 用途 | |---|---| | `GEMINI_API_KEY` | Worker agent (Gemini 2.0 Flash) | | `ANTHROPIC_API_KEY` | 验证 agent (Claude)。未设置 → 回退至 Gemini，并记录在追踪日志中 | | `MONGODB_URI` | 事件及审计数据持久化 | | `JWT_SECRET` | 移动端用户认证。**在生产环境中必填** (若未设置，服务器将拒绝启动)；开发环境使用每次启动时生成的随机密钥 | | `OPERATOR_API_KEY` | 保护批准/否决操作及操作员路由 (`x-operator-key` 请求头)。未设置 → 开放访问，并在启动时发出警告 — 在公开部署前请务必设置。演示级别的共享密钥 (Web UI 会在客户端暴露它)；生产环境应使用基于用户的独立认证 | | `VITE_OPERATOR_KEY` | 相同的值，暴露给操作员 Web UI | | `VITE_GOOGLE_MAPS_API_KEY` | 仪表盘地图 (通过 HTTP referrer 进行访问限制) | | `BAND_USE_SDK`, `BAND_API_URL`, `BAND_API_KEY` | 从模拟的 Band adapter 切换到真实的 Band 平台 (使用启动时提供的凭据) | | `AIML_API_KEY`, `FEATHERLESS_API_KEY` | 跨框架合作服务商 (未设置时 agent 回退至 Gemini) | | `CORS_ORIGIN` | 逗号分隔的 CORS 白名单 (未设置 = 开放访问；公开部署时请务必设置) | | `LIVE_DATA_POLLING` | 设为 `true` 可启用真实的 GDACS/USGS/Open-Meteo 数据接入 (默认关闭 — 触发后的每个事件都会运行完整 pipeline) | ## 核心 API 端点 ``` POST /api/ingest-signal Signal intake (zod-validated, rate-limited; body {"async": true} → 202 + background pipeline; same-type signals within 15 min attach to the existing incident instead of opening a new room) GET /api/band/rooms/by-incident/:id Band room + message trail GET /api/band/audit-trail/:incidentId Compliance export GET /api/band/approvals/pending Actions awaiting approval POST /api/band/approve { proposalMsgId } Human Commander approval (operator key required) POST /api/band/veto { proposalMsgId } Human Commander veto (operator key required) ``` ## 演示场景 ``` npx tsx scenarios/demo_runner.ts single # credential-stuffing, SEV-2, human approval npx tsx scenarios/demo_runner.ts false-positive # conflicting signals → retraction npx tsx scenarios/demo_runner.ts concurrent # two incidents, shared SRE pool ``` ## Band 集成 Band 集成被封装在 [src/band/adapter.ts](src/band/adapter.ts) 的 `IBandAdapter` 接口背后： - **`MockBandAdapter`** (默认) — 进程内房间 + 权限强制执行 + MongoDB 镜像。允许在平台凭据下发前运行完整的工作流。 - **`BandSdkAdapter`** (`BAND_USE_SDK=true`) — 将消息发送到**真实的 Band Agent API** (`https://app.band.ai/api/v1/agent`，使用 `X-API-Key` 认证)：`POST /chats` 为每个事件开启一个聊天会话，`POST /chats/{id}/messages` 发布每条发现 (将结构化的 Maestro 信封转换为 Band 的文本+@提及消息模型)，`GET /chats/{id}/messages` 读取追踪记录。本地的 Mock 存储依然是权限执行和审计镜像的真相来源；Band 则是构建于其上的实时 agent 间协调骨干网络。需要通过 Band 的 Human API 注册一个 agent `X-API-Key`。 Agent 逻辑、治理规则和 UI 仅依赖于 `IBandAdapter`，因此替换操作完全被限制在这一个文件中。 ### 权限规则 (职责分离) | msg_type | 允许的发送者 | |---|---| | `finding`, `status` | 任何 agent | | `proposal`, `approval_request` | 仅限 `incident-commander` | | `approval` | 仅限 `human-commander` | | `retraction` | `incident-commander`, `human-commander` | 在 `post()` 中强制执行；`approve`/`veto` HTTP 路由还需要提供操作员密钥。 ## Agent 名单 | Agent | 模型 | msg_type | |---|---|---| | 接入与标准化 | Gemini 2.0 Flash | `status` | | 关联与去重 | Gemini 2.0 Flash | `finding` | | **验证与可信度** | **Claude Sonnet (Anthropic)** — 无密钥时回退至 Gemini | `finding` | | 分类 | Gemini 2.0 Flash | `finding` | | 严重程度与爆炸半径 | Gemini 2.0 Flash | `finding` | | 响应人员分配 | Gemini 2.0 Flash | `finding` | | 依赖影响模拟 | Gemini 2.0 Flash | `finding` | | 缓解方案预测 | Gemini 2.0 Flash | `finding` | | 操作手册顾问 | Gemini 2.0 Flash | `finding` | | 利益相关者沟通 | Gemini 2.0 Flash | `finding` | | **事件指挥官** | Gemini 2.0 Flash | `proposal`, `approval_request` | | **人类指挥官** | — | `approval`, `retraction` | ## 资源池 共享的待命人员总数，在并发事件间进行分配 ([src/services/resourceManager.ts](src/services/resourceManager.ts))：12 名 SRE、6 名安全工程师、4 名数据工程师、3 名事件指挥官、2 名合规专员。高优先级事件可以从低优先级事件中回收资源；每一次重新分配都会被记录在追踪日志中。该资源池存在于内存中 (重启时会重置) — 生产环境应将其持久化到 Redis/MongoDB。 ## 故障行为 (诚实模式) - 如果 LLM 在重试后仍无法访问，agent 将返回**带有清晰标记的降级输出** (`degraded: true`，置信度 0.2，“未执行分析”)，而不是捏造分析结果；并且在降级模式下，任何传达给指挥官的内容都会**强制要求人类批准**。 - 如果在 5 分钟内未给予人类批准，该操作将被**自动否决**，同时事件将被撤回。 - Band 房间和消息日志会在启动时从 MongoDB 恢复数据，因此操作员视图和审计导出功能可以在重启后保留。处于等待状态的批准关卡**无法**在重启后保留 (根据设计，它们会超时并变为否决状态)。 ## 已知限制 - 在接入 Band 平台凭据之前 (`BAND_USE_SDK=true`)，默认使用 `MockBandAdapter`。 - 审计追踪是持久化的 (在认为消息发送完成之前，会等待镜像写入完成)，但并非加密不可变 —— 没有哈希链。 - 信号输入 UI 中的“社交/交通动态流”面板是 **AI 生成的模拟内容**，在响应中已对此作了明确标注。 - 自主行动的副作用 (PagerDuty 呼叫、Slack 作战室、SMS 撤回通知) 均为**模拟实现** (每条记录上都带有 `simulated: true`) —— 决策逻辑是真实的，但集成部分仅为演示用的替代品。 - 跨信号去重的依据是 15 分钟窗口内的信号 `type` —— 在该窗口内发生的两个*独立*但同类型的事件会被合并。生产环境应基于 type + 受影响的服务进行去重。 - 资源池和批准关卡存在于内存中；仅支持单节点。 - Expo 移动应用 (`mobile/`) 是一个配套的市民上报客户端，不属于赛道 3 的提交范围。请设置 `EXPO_PUBLIC_API_URL` 以进行局域网开发。 ## 成本与延迟 | 组件 | 单次事件成本 | 延迟 | |---|---|---| | Gemini 2.0 Flash × ~11 次调用 | ~$0.001 (提供免费额度) | 8–15秒 端到端 (串行) | | Claude Sonnet (验证) | ~$0.01 | 1–3秒 | | MongoDB Atlas (M0) | $0 | <50毫秒 | 针对不同事件的 pipeline 可并发运行 (`ConcurrentOrchestrator`)；但在单个 pipeline *内部*的步骤是串行的，因为每个 agent 都需要消耗前一个 agent 的上下文。 ## 项目结构 ``` Maestro/ ├── src/ │ ├── band/ │ │ ├── adapter.ts # MockBandAdapter + BandSdkAdapter + singleton selection │ │ └── types.ts # BandMessage, BandRoom, AUTHORITY_RULES, IBandAdapter │ ├── agents/ │ │ ├── AntigravityCore.ts # Orchestrators, GeminiAgent, ClaudeAgent │ │ └── ciroAgents.ts # 11 registered agents with prompts + JSON schemas │ ├── services/ │ │ ├── incidentService.ts # Band-coordinated pipeline + approval gate flow │ │ ├── approvalService.ts # Human approval gates (promise-based, 5-min auto-veto) │ │ ├── resourceManager.ts # Priority-based shared responder pool │ │ └── geminiService.ts # Gemini wrapper: retries, cache, degraded fallbacks │ ├── components/ # Operator web UI (BandRoomTimeline = approval gate UI) │ └── routes/index.ts # API routes (operator routes behind OPERATOR_API_KEY) ├── scenarios/demo_runner.ts # 3 hackathon demo scenarios ├── mobile/ # Expo companion app (out of submission scope) └── server.ts # Express + Socket.IO + Band room rehydration ``` ## 许可证 MIT — 见 [LICENSE](./LICENSE)

标签：AI工作流, 人机协同, 多智能体, 自动化攻击, 跨大模型框架, 运维自动化