lyudmylan/ai-incident-investigator

# AI 事件调查员 一个面向未来 AI SRE agent 的、可解释的、人类在环的调查层。给它一个离线事件包（告警、指标、日志、追踪、部署、拓扑、操作手册）；它会关联证据，使用可审计的置信度准则对假设进行排序，并生成安全的后续步骤、缓解选项（始终需要人类批准）、内部更新草稿以及复盘草稿——以稳定的 JSON 或人类可读的 Markdown 格式输出。 它负责调查和建议。它唯一能执行的操作是 v5 试点版本中的单个特性开关切换——受限于生产环境的双人批准法定人数、严格的允许列表以及完整的审计跟踪；除此之外，它永远只负责起草。 ## 快速开始 需要 [uv](https://docs.astral.sh/uv/) 和 Python 3.12+。 ``` uv sync --dev # 仅确定性事实（无 LLM）：事件窗口、合并时间线、间隙 uv run python -m ai_incident_investigator \ --incident examples/incidents/latency_spike # 基于已提交 fixtures 的完整调查报告 - 无需 API key uv run python -m ai_incident_investigator \ --incident examples/incidents/latency_spike --llm replay --format markdown # 针对 Claude API 的实时调查 ANTHROPIC_API_KEY=... uv run python -m ai_incident_investigator \ --incident examples/incidents/latency_spike --llm live --output report.json ``` 以上所有操作都在已提交的固定数据上运行——测试、CI 和演示在设计上消耗 **零 LLM token**。`docs/demo_tour.md` 是对整个界面（调查、发布、批准、比较）的五步引导式演练，所有内容均可零成本重放。`docs/testing_and_demo.md` 是决策指南：说明哪种模式消耗多少（实测：一次完整的实时调查需要 10 次调用 / ~77k 输入 + ~34k 输出 token——在 Haiku 4.5 上约 $0.25，而在 Opus 定价下约 $4-5），此外还提供了免费演示的标准配方以及唯一值得付费录制的演示。 固定数据中包含十个示例事件，因此重放演示开箱即用。其中四个原始事件：`latency_spike`（部署驱动的重试放大）、`error_rate_spike`（特性开关破坏了模板渲染；在时间窗口内恢复）、`dependency_timeout`（第三方 API 降级，无内部变更），以及 `collected_demo`（与下文 `collect` 命令收集到的相同的预订场景——从已提交的 HTTP 固定数据中逐字节复现）。此外还有一个包含六个场景的**对抗性语料库**，专门构建用于误导——红鲱鱼（干扰性）部署、相互矛盾的指标、对于任何合理假设而言都过于单薄的证据——每一个都根据一套“正确调查必须和绝不能声称什么”的准则进行评分（`scripts/eval_corpus.py`；评分表已提交至 `docs/eval_scorecard.md`）。 ## 引导式修复 (v3) 除了诊断之外，报告还包含引导式的、**严格仅限草稿**的产物——该工具永远不会在任何地方发布、创建或执行任何内容： - **修复计划**：经过审查的缓解选项被组织为分步计划，并且在存在与部署相关的假设时附带回滚检查清单。安全性深植于 schema 中：如果没有 `requires_human_approval: true` 和验证步骤，就无法存在改变状态的步骤；中止条件是强制性的；悬空引用会被 linter 拦截。 - **恢复验证计划**：根据偏移序列和记录在案的恢复规则确定性地（无需 LLM）推导出来——监控什么、监控多久、哪些错误模式应该停止、何时重新告警。 - **外部草稿**，供人类复制：一个 Jira 工单（优先级在代码中由严重程度映射得出），一个 Slack 更新（必须声明未执行任何操作），以及一个受符合 lint 规范且对客户安全的规则约束的状态页面更新（内部服务名称会被机械性地拦截）。 渲染后的计划如下所示（来自 latency_spike 重放）： ``` ### booking-service 发布 2026.06.01-1420 的回滚清单（rollback） > **Human approval required before any step of this plan is acted on.** - addresses hypothesis: `hypothesis_314fcf61a4` - suggested owner: on-call engineer - preconditions: previous release 2026.05.28 artifacts still deployable 1. [read-only] check whether release 2026.06.01-1420 shipped data migrations - verify: release notes and migration directory reviewed 2. **[STATE-CHANGING - approval required]** roll booking-service back to the previous release - verify: deployed version reports the previous release and appointments-db CPU falls below 60% **Abort if:** rollback pods crash-loop or error rate exceeds 10% ``` ## 引导式操作 (v4) v4 在构建闭环之前先赢得了信任——以下所有内容都是确定性的、零 token 的，且不对任何事物采取行动： - **对抗性评估语料库**：六个旨在进行误导的场景设计（参见上方的示例列表），在每次测试运行时进行评分；已提交的评分表是 CI 回归门禁。 - **`publish`**：该工具唯一的写入路径——将其自身的报告作为 GitHub issue 发布。客户端类型只能表达确切的一个路由和动词；其凭证与所有收集配置隔离（在结构上隔离，且双向均有测试）。使用 `--dry-run` 进行预览；一个 stub fixture 用于离线演示。 - **`approve`**：人类的批准与确切报告文件的 sha256 绑定——重新生成报告，其上的所有批准即告失效。`is_actionable` 门禁是未来的执行器必须查阅的内容；目前它只负责解答。批准永远不等于执行。 - **`compare`**：使用结束事件时间窗口的相同规则，根据原始事件的恢复计划来评估后续快照。策略上保持悲观：缺失的信号是无法验证的，绝不假设已恢复。 ## 闭环协助（v5 试点） 执行功能现已存在——确切地说是仅限一个操作，原封不动地使用 v4 的批准记录： - **`execute`**：切换一个允许列表中的 feature flag，支持 dry-run 或 live。进入操作的唯一入口是 `is_actionable` 法定人数门禁：环境的层级决定了需要多少个不同的批准者（生产环境底线：2 人——任何单个人都无法为关键变更放行；强调对等多数，而非层级）。在试点期间，实时切换只能到达 sandbox/staging 层级；即便满足法定人数，生产环境也会被拒绝。每一个决策——包括拒绝——都会在报告之前落入一个只追加的 executions sidecar 中。无密钥演示：针对已提交的 stub fixture 使用 `--live --http replay`。 - **`compare --verify-execution`**：使用相同的确定性规则，根据后续快照验证已执行切换的结果——`verified`（已验证）、`unverifiable`（缺失信号绝不假定为良好）或 `aborted`（已满足重新告警条件或无恢复）。验证结果会追加；执行记录绝不篡改。 - **执行器拒绝矩阵**是信任账本的一部分：十一个确定性场景（篡改报告、过期批准、法定人数操纵、未列出的 flag、生产环境实时尝试）在每次测试运行时都会在 `docs/eval_scorecard.md` 中进行评分。 ## 从实时来源收集包 (v2) 与其手工编写包，不如使用 `collect` 从只读来源收集一个包——类似于 Sentry 的 issue（锚点）、类似于 Prometheus 的指标、类似于 Loki 的日志、GitHub 发布/部署以及已配置的操作手册——并写入一个普通的包目录（该快照同时作为保存的事件证据）。在 `sources.toml` 中配置 endpoint（`examples/collect/sources.toml` 是一个模板）；凭证是由环境变量名引用的只读 token，绝不在配置中写入具体值。 连接真实的架构栈是一个渐进的过程，而非一堵不可逾越的墙：告警锚点是唯一必需的来源，其他所有来源都是增量添加的，其缺失会被作为报告中的缺口。**`docs/adoption.md`** 逐步引导您完成此操作，从两行配置（`examples/collect/sources.minimal.toml`）开始。 ``` # 基于已提交 HTTP fixtures 的离线演示 - 无需凭据： uv run python -m ai_incident_investigator collect \ --sources examples/collect/sources.toml --issue 9101 \ --output /tmp/collected-incident \ --http replay --http-fixtures-dir tests/fixtures/http/demo_collect \ --then-investigate --format markdown # 实际使用：将 sources.toml 指向您的服务，并将 tokens 放入 # gitignored .env（参见 docs/testing_and_demo.md），然后使用相同的命令 # 加上 `uv run --env-file .env` + --http live（报告则加上 --llm live）。 ``` 收集过程会针对每个来源进行降级处理（宕机的来源会成为调查报告中指出的缺口），只有在告警锚点不可用时才会彻底失败。适配器只能执行 GET 请求——写入在结构上是不可能的（见 `docs/architecture.md`，收集层；映射关系见 `docs/collection_sources.md`）。 ## 工作原理 ``` incident package -> deterministic core -> agent graph -> report (files) loader, validation, 6 investigators (parallel) incident window, -> hypothesis ranker merged timeline -> safety critic -> recommendation builder -> reporter (drafts) -> deterministic safety linter ``` - **确定性的事实，智能体式的推理。** 解析、验证、事件窗口和时间线都是普通代码；LLM agent 永远只能看到经过预先验证的、有类型约束的事实（见 `docs/architecture.md`）。 - **构造上即支持证据支撑。** Agent 通过 id 引用证据；引用无法验证的假设会被剔除。置信度标签是由文档记录的准则（`docs/assumptions.md`）在代码中推导出来的——模型无法过度断言。 - **优雅降级，绝不崩溃。** 缺失的文件、格式错误的数据和失败的 agent 会转化为 `missing_data` 条目；报告总能输出，并带有明确的“不可用”后备方案。 - **安全性深植于 schema。** 每个缓解选项都带有由类型系统强制执行的 `requires_human_approval: true`，并且确定性的 linter 会检查最终报告，即使所有的 LLM 调用都失败了。 契约：`docs/incident_package_contract.md`（输入）和 `docs/output_contract.md`（输出），两者均由代码生成。 ## 开发 ``` uv run ruff format . && uv run ruff check . # format + lint uv run mypy # strict type check uv run pytest # tests (offline, no API key) uv run python -m ai_incident_investigator.contracts # regen contract docs uv run --no-sync python scripts/bootstrap_fixtures.py # regen fixtures + goldens ``` CI 在没有任何 API key 的情况下运行上述所有操作：测试会重放已记录的 LLM 固定数据。有关完整的工作流程和规则，请参阅 `AGENTS.md`；有关产品规格和路线图，请参阅 `docs/product.md`。

标签：Claude API, SRE, 事故分析, 人工智能运维, 人机协同, 偏差过滤, 可解释AI, 安全规则引擎, 逆向工具