KIM3310/AegisOps

# AegisOps — 基于 GCP 的多模态 SEV1 事件 Copilot  在真实的 SEV1 事件中，难点很少在于缺失遥测数据。更困难的部分是将来自日志、截图和告警的零散证据转化为一份可供他人快速审查的报告。 **AegisOps** 将： `收集 → 推理 → 决策 → 沟通` 压缩为一份单一、可审查的事件报告。 ## 产品家族 AegisOps 是更广泛的 `Aegis` 事件分析产品家族中的多模态 copilot 界面。 配套仓库： - `Aegis-Air`：面向无法将遥测数据发送到公共 API 的团队的本地优先/物理隔离事件审查引擎 ## 演示 / 链接 - 演示视频：https://youtu.be/FOcjPcMheIg - Cloudflare Pages 演示：https://aegisops-ai-incident-doctor.pages.dev - Google AI Studio 演示：https://ai.studio/apps/drive/1nInCvCJjSXy0IQGiDeK9gbsjjhhPqtlg?fullscreenApplet=true ## 功能 - **输入：** 原始文本日志 + 监控截图 - **输出：** 结构化的 JSON 事件报告： - 严重级别、RCA（根因分析）假设、优先级操作、时间线、预防建议 - 简短的**推理轨迹**（观察 / 假设 / 决策路径） - **内置事件回放套件：** 基于量表的检查，涵盖严重性、标签、标题质量、可操作性、时间线覆盖范围、推理结构和置信区间 - 基于生成的报告上下文的**后续 Q&A** - **可选：** 值班音频简报（TTS，文本转语音） - **可选：** 将产物导出到 Google Workspace（Docs/Slides/Sheets/Calendar，以及 Chat webhook） ## 范围 - 构建端到端工作流：React/Vite UI + 本地 API 代理 (Express) + 报告 Schema + 后续 Q&A。 - 实现 JSON 提取/修复，即使在模型输出混乱时也能保持 UI 稳定。 - 在缺少 `GEMINI_API_KEY` 时添加了回退演示模式。 - 对多模态输入实施载荷保护（图像限制 + 部分失败容错）。 - 客户端不保存密钥（服务端密钥处理；无 Vite 环境变量注入）。 - 通过 `GET /api/evals/replays` 和 `npm run eval:replays` 暴露回放结果。 ## 事件回放评估 本仓库包含一个小型的事件分析质量回放工具： - 套件源码：`evals/incidentReplays.ts` - 评分逻辑：`server/lib/replayEvals.ts` - 审查脚本：`npm run eval:replays` - API 摘要：`GET /api/evals/replays` 当前套件涵盖 4 个场景 / 32 项量表检查。有关评分量表和案例设计，请参阅 `docs/INCIDENT_REPLAY_EVALS.md`。 ## 架构 关键设计目标是**密钥卫生**：Gemini API 密钥绝不能发送到浏览器。  ``` flowchart LR UI[React/Vite UI] -->|/api/*| API[Local API Proxy (Express)] API -->|Gemini| LLM[Gemini Models] UI -->|OAuth token| GWS[Google Workspace APIs] ``` - 前端调用本地 API（`/api/analyze`、`/api/followup`、`/api/tts`）。 - API 在服务端读取 `GEMINI_API_KEY` 并调用 Gemini。 - Grounding（`googleSearch` 工具）默认**关闭**，必须显式启用。 ## 示例输入 您可以将 `samples/` 中的示例输入拖放到 UI 中： - `samples/logs/*.txt` - `samples/screenshots/*.png` ## 本地运行（单条命令） ### 前置条件 - Node.js 18+ ### 快速开始 ``` npm install && npm run dev # 或：运行 make demo-local ``` - UI：`http://127.0.0.1:3000` - API：`http://127.0.0.1:8787` ### 环境变量 将 `.env.example` 复制到 `.env` 并根据需要填写。 ``` # 如果缺失，API 将以 demo 模式运行（无外部 LLM 调用）。 GEMINI_API_KEY= # LLM 提供商选择： # - auto : 当 key 存在时使用 Gemini，否则使用 demo 模式 # - demo : 始终使用 demo 模式 # - gemini : Gemini 模式（当 key 缺失时回退到 demo） # - ollama : 本地 Ollama 模式（离线） LLM_PROVIDER=auto # 可选：Ollama 本地端点 + 模型（当 LLM_PROVIDER=ollama 时使用） OLLAMA_BASE_URL=http://127.0.0.1:11434 OLLAMA_MODEL_ANALYZE=llama3.1:8b OLLAMA_MODEL_FOLLOWUP=llama3.1:8b # 可选：使用 admin token 保护 /api/settings/api-key。 # 通过 Authorization: Bearer 或 x-api-settings-token header 发送。 API_KEY_SETTINGS_TOKEN= # 可选：允许来自非 localhost 客户端的 /api/settings/api-key 访问。 # 默认为 false（仅限 localhost）。 ALLOW_REMOTE_API_KEY_SETTINGS=false # 可选：API 绑定主机（默认值：127.0.0.1）。 # 仅当您明确需要远程/LAN 访问时设置 HOST=0.0.0.0。 HOST=127.0.0.1 # 可选：信任反向代理 headers (X-Forwarded-For)。 TRUST_PROXY=false # 可选：Gemini 上游超时时间（毫秒）。 GEMINI_TIMEOUT_MS=45000 # 可选：Gemini 重试策略（针对瞬时 429/5xx/timeout 的指数退避）。 GEMINI_RETRY_MAX_ATTEMPTS=3 GEMINI_RETRY_BASE_DELAY_MS=400 # 可选：API 请求体和 payload 防护栏。 REQUEST_BODY_LIMIT_MB=25 MAX_IMAGE_BYTES=5000000 MAX_QUESTION_CHARS=4000 MAX_TTS_CHARS=5000 # 可选：用于重复 analyze 请求的内存缓存。 ANALYZE_CACHE_TTL_SEC=300 ANALYZE_CACHE_MAX_ENTRIES=200 # 可选：为 Workspace integration 启用真实的 Google OAuth（否则 UI 使用 demo auth）。 VITE_GOOGLE_CLIENT_ID= # 可选：社区集成 VITE_FORMSPREE_ENDPOINT= VITE_DISQUS_SHORTNAME= VITE_DISQUS_IDENTIFIER=aegisops-community VITE_GISCUS_REPO= VITE_GISCUS_REPO_ID= VITE_GISCUS_CATEGORY= VITE_GISCUS_CATEGORY_ID= # 可选：AdSense VITE_ADSENSE_CLIENT=ca-pub-xxxxxxxxxxxxxxxx VITE_ADSENSE_SLOT=1234567890 # 可选：Teachable Machine 图像分类器（客户端） # 使用基础文件夹 URL (.../model/) 或直接的 model.json URL。 VITE_TM_MODEL_URL= ``` 对于本地开发，Vite 默认绑定到 `127.0.0.1`。 如果需要 LAN/设备测试，请在 `npm run dev` 之前设置 `VITE_DEV_HOST=0.0.0.0`。 您也可以通过 UI（顶部栏的 `API Key` 按钮）提供 Gemini 密钥。 该运行时密钥仅保留在后端内存中，并在 API 服务器重启时重置。 Google OAuth 访问令牌现在仅在有效时从会话中恢复；过期令牌会自动清除。 `public/ads.txt`、`public/robots.txt`、`public/sitemap.xml`、`public/about.html`、`public/compliance.html` 和 `public/_headers` 中包含了 AdSense 审查辅助工具。 ### Teachable Machine（可选） 当设置了 `VITE_TM_MODEL_URL` 时，AegisOps 可以在 Gemini 分析之前运行**本地浏览器端图像分类**： - 上传的截图由您的 Teachable Machine 模型评分 - 高置信度标签以 `[TM] ...` 行的形式附加到日志上下文中 - 失败是非阻塞的（分析在没有 TM 信号的情况下继续进行） ## 演示模式（无需密钥） 如果未设置 `GEMINI_API_KEY`，API 将切换到**演示模式**： - 分析返回基于所提供日志的固定存根报告 - 后续 Q&A 返回固定的辅助响应 - TTS 被禁用 这使得项目在没有外部凭证的情况下也能运行。 回放套件也在演示模式下运行，因此可以在本地重现当前分数。 Cloudflare Pages 部署在没有后端的情况下也可用。如果 `/api/*` 不可用，前端将回退到： - 浏览器中的确定性本地事件分析 - 本地回放套件评分 - 演示后续回答和 Workspace 导出存根 ## Ollama 离线模式（无需云端 LLM） 当您想要离线本地推理时使用此模式。 1. 在本地安装并运行 Ollama。 2. 拉取模型： ``` ollama pull llama3.1:8b ``` 3. 设置 `.env`： ``` LLM_PROVIDER=ollama OLLAMA_BASE_URL=http://127.0.0.1:11434 OLLAMA_MODEL_ANALYZE=llama3.1:8b OLLAMA_MODEL_FOLLOWUP=llama3.1:8b ``` 4. 启动应用： ``` npm run dev ``` 注意事项： - 在 `ollama` 模式下，Gemini API 密钥运行时设置被禁用。 - TTS 端点被视为不可用（`audioBase64` 为空）。 - 如果 Ollama 未运行/不可达，analyze/follow-up 端点将返回 `502` 并附带连接提示。 ## 说明 / 限制 - Workspace 导出功能需要 OAuth scopes；在演示模式下不会执行这些调用。 - 本项目专注于可重复的本地审查、默认安全和运维 UX。 ## 术语表（初次阅读者） - SEV1：严重级别 1 事件（最高紧急程度） - RCA：根因分析 - TTS：文本转语音 - OAuth：开放授权（基于浏览器的同意流程） - LLM：大语言模型 ## 本地验证 ``` npm install npm run typecheck npm run test npm run eval:replays npm run build ``` ## 仓库规范 - 请勿将运行时产物提交到版本控制（`.codex_runs/`、缓存文件夹、临时 venvs）。 - 建议 在提交 PR 之前运行上述验证命令。 _最后更新：2026-03-04_

标签：AI风险缓解, GCP, Gemini Pro Vision, Google Workspace集成, MITM代理, multimodal, React, SEV1事故报告, SRE工具, Syscalls, Vite, 事故复盘, 多模态人工智能, 截图分析, 根因分析(RCA), 自动化报告, 自动化攻击, 运维助手