deghosal-2026/ai-incident-commander

# ai-incident-commander [](https://github.com/deghosal-2026/ai-incident-commander/actions/workflows/ci.yml) [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://pypi.org/project/ai-incident-commander/) ## 快速开始 ``` pip install ai-incident-commander # 运行 SEV1 payment-service 故障 — 零配置 incident-commander simulate --service payment-service --severity SEV1 --auto-approve # 输出将写入 ./output/ ``` 就这样。无需 API keys，无需云账户，无需 Docker。该工具默认使用本地 LLM（Ollama/MLX）。 ## 功能说明 | 步骤 | 发生的操作 | |------|-------------| | **摄取** | 从 CLI flags、输入目录或 Python API 加载事件数据 | | **构建时间线** | 将告警、日志、聊天信息和 GitHub PR 合并为按时间顺序排列且带有信任层级的时间线 | | **关联部署** | 将告警前 30 分钟内合并的 GitHub PR 标记为部署关联 | | **检索 runbook** | 通过 RAG（内存或 Qdrant）搜索 runbook 和历史事件 | | **起草更新** | 生成以结果为导向的利益相关者更新，并根据严重程度设定更新频率（SEV1=5分钟，SEV2=15分钟，SEV3=30分钟） | | **建议修复** | 对历史事件进行模式匹配，建议带有引用和置信度分数的操作 | | **试运行模拟** | LLM 预测每个建议修复措施的预期结果 | | **生成事后总结** | 采用 COE 格式且带有 AI 标记部分的事后总结，根据严重程度生成（SEV1=8个部分，SEV2=6个，SEV3=5个） | | **追踪成本** | 通过 JSONL 可观测性日志进行基于节点的 LLM 成本追踪 | | **导出** | 10 个输出文件：摘要、时间线、更新、通信模块、修复、事后总结、成本报告、LLM 调用、会话、元数据 | ## CLI 命令 ``` # 模拟故障（无需输入数据） incident-commander simulate --service payment-service --severity SEV1 --output-dir ./output/ incident-commander simulate --scenario db-connection-pool --output-dir ./output/ # 从真实数据运行 incident-commander run --alert alert.json --logs ./logs/ --output-dir ./output/ incident-commander run --input-dir ./incident-data/ --output-dir ./output/ # 查看已保存的会话 incident-commander timeline --thread incident-commander postmortem --thread # 导出 JSON Schemas incident-commander export-schemas --output-dir ./schemas/ # 验证输入 incident-commander validate --alert alert.json # 自动批准所有中断（用于 CI/pipelines） incident-commander simulate --auto-approve ``` ## Python API ``` from incident_commander import run_simulation, run_incident # 模拟故障 result = run_simulation( service="payment-service", severity="SEV1", auto_approve=True, ) # 从真实数据运行 result = run_incident( alert={"severity": "SEV1", "service": "api-gateway", ...}, logs=[{"timestamp": "...", "level": "ERROR", "message": "..."}], messages=[{"timestamp": "...", "author": "alice", "text": "..."}], auto_approve=True, ) print(result.postmortem.root_cause_analysis.content) print(f"Cost: ${result.cost_report.total_estimated_cost_usd:.4f}") ``` ## 输入目录 用于批处理的结构化目录： ``` incident-data/ ├── meta.json # incident_id, service, severity, start_time ├── alert.json # Required: severity, service, summary, source, timestamp ├── logs/ # Optional: .log, .json, or .md files │ ├── 01-app.log │ └── 02-database.json ├── messages.json # Optional: chat messages ├── github.json # Optional: GitHub PRs ├── runbooks/ # Optional: runbook JSON files └── notes.md # Optional: manual event notes (## headings → timeline) ``` ## 输出目录 每次运行生成 10 个文件： ``` output/ ├── incident-summary.md # ID, service, severity, MTTR, cost ├── timeline.md # Chronological event table with trust levels ├── stakeholder-updates.md # Consequence-first update drafts ├── comms-blocks.md # Pasteable Slack/email blocks ├── remediation.md # Suggested actions with citations ├── postmortem.md # COE-format postmortem with AI labels ├── cost-report.md # Per-node LLM cost breakdown ├── llm-calls.jsonl # Raw LLM call log (response text) ├── session.json # Full session state └── meta.json # Session metadata ``` ## 配置 该工具使用环境变量进行 LLM 配置： ``` # 默认：Ollama local export LLM_MODEL=ollama/qwen2.5-coder:7b export LLM_BASE_URL=http://localhost:11434/v1 # 或：OpenCode Zen (cloud, cheap) export LLM_MODEL=deepseek-v4-flash export LLM_BASE_URL=https://opencode.ai/zen/v1 export LLM_API_KEY= # 或：OpenAI export LLM_MODEL=gpt-4o-mini export LLM_BASE_URL=https://api.openai.com/v1 export LLM_API_KEY= ``` 完整配置选项（通过 Python API 设置）： | 选项 | 默认值 | 描述 | |--------|---------|-------------| | `mode` | `"simulate"` | `"simulate"` 自动批准中断；`"run"` 需要人工批准 | | `analysis_model` | `"ollama/qwen2.5-coder:7b"` | 用于根因分析的主要 LLM | | `comms_model` | `None` | 用于利益相关者更新的 LLM（回退至 analysis_model） | | `postmortem_model` | `None` | 用于生成事后总结的 LLM（回退至 analysis_model） | | `confidence_threshold` | `0.7` | 修复建议的最低置信度 | | `deploy_correlation_window` | `30` | 检查部署关联的告警前分钟数 | | `cadence` | `{"SEV1": 5, "SEV2": 15, "SEV3": 30}` | 按严重程度划分的利益相关者更新间隔 | | `qdrant_url` | `None` | Qdrant 向量数据库 URL（None = 内存检索器） | | `session_dir` | `~/.incident-commander/sessions` | 会话持久化目录 | | `output_format` | `"markdown"` | 输出格式（`"markdown"` 或 `"json"`） | ## 模拟场景 | 场景 | 服务 | 严重程度 | 部署关联 | |----------|---------|----------|-------------------| | `db-connection-pool` | payment-service | SEV1 | ✅ | | `bad-deploy` | api-gateway | SEV2 | ✅ | | `memory-leak` | auth-service | SEV2 | ❌ | | `cert-expiry` | api-gateway | SEV1 | ❌ | | `dependency-outage` | payment-service | SEV1 | ❌ | | `config-drift` | web-frontend | SEV3 | ✅ | | `cache-invalidation` | product-catalog | SEV2 | ❌ | | `rate-limit-hit` | search-service | SEV3 | ❌ | ## 安全护栏 | 护栏 | 功能说明 | |-----------|-------------| | **中断点** | 3 个人机交互关卡：利益相关者更新、修复审查、事后总结审查。在 CI 环境中使用 `--auto-approve` 自动批准 | | **置信度阈值** | 抑制置信度低于 0.7 的修复建议（可配置） | | **来源引用** | 每项修复措施都必须引用 runbook 或历史事件。无引用的建议将被拒绝 | | **仅试运行** | LLM 将修复结果以文本形式模拟——绝不执行生产环境的变更 | | **免责定调** | 事后总结提示词强制使用无指责性语言（COE 格式） | | **AI 部分标签** | 所有 AI 生成的内容都会标记为 `[AI-GENERATED — review carefully]` | | **优雅降级** | LLM 故障会产生“数据不足”的兜底内容——绝不让图崩溃 | ## 架构 ``` ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Input Dir │ │ CLI Flags │ │ Python API │ │ (files) │ │ (args) │ │ (program) │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ └────────────────────┼────────────────────┘ │ ┌───────▼────────┐ │ Normalizer │ │ (obj/dict/path│ │ → Pydantic) │ └───────┬────────┘ │ ┌───────▼─────────────────────┐ │ LangGraph StateGraph │ │ │ │ receive_alert → build_ │ │ timeline → correlate_ │ │ deploys → retrieve_runbooks │ │ → rerank → cadence_timer → │ │ draft_update → [APPROVE] → │ │ produce_output → ... → │ │ resolve → suggest_ │ │ remediation → dry_run → │ │ [APPROVE] → generate_ │ │ postmortem → [APPROVE] → │ │ cost_report → END │ └───────┬──────────────────────┘ │ ┌───────▼────────┐ │ 10 output │ │ markdown files│ └────────────────┘ ``` ## 文档 - [产品需求](docs/PRD.md) - [技术规范](docs/SPEC.md) - [工作分解结构](docs/wbs.md) - [API 参考](docs/api-reference.md) *(即将推出)* - [安全护栏](docs/safety-guardrails.md) *(即将推出)* - [模拟指南](docs/simulation-guide.md) *(即将推出)* - [输入格式](docs/input-format.md) *(即将推出)* - [输出格式](docs/output-format.md) *(即将推出)* ## 开发 ``` pip install -e ".[dev]" pytest ruff check mypy --strict src/ ``` ## 许可证 MIT

标签：AI风险缓解, LLM, Python, RAG, Unmanaged PE, 人工智能, 库, 应急响应, 无后门, 用户模式Hook绕过, 运维工具, 逆向工具