# 事件调查员
一个开源的、**供应商中立的故障调查引擎**，作为一个
[MCP](https://modelcontextprotocol.io) 服务器暴露。
Incident Investigator **不会**连接到 Kubernetes、AWS、GitHub、Slack、
Datadog、Prometheus 或任何其他系统。它没有连接器，也没有供应商
SDK。相反，它是一个**有状态调查运行时**，引导 AI agent
进行调查：它请求所需的证据，对
agent 提交的证据进行推理，构建证据图，生成竞争
假设，并生成最终调查报告。
它适用于任何支持 MCP 的助手 —— Claude Code、Codex、Cursor、Goose、
OpenHands 等。
## 核心理念
| AI 助手负责 | 引擎负责 |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| 决定调用哪些外部工具 | 维护调查状态 |
| 收集日志、指标、告警、部署、trace 等。 | 请求额外证据（动态规划器） |
| 了解 CloudWatch / Datadog / Kubernetes 是什么 | 构建和关联证据图 |
| | 生成竞争假设 + 置信度评分 |
| | 矛盾检测、缺失证据检测、影响范围估算 |
| | 时间线生成以及复盘 / 报告生成 |
引擎只理解**证据类别**。它从不依赖供应商
schema。
## 架构
```
MCP Server (cmd/incident-investigator)
│
Investigation Runtime (internal/runtime)
│
┌─────────────────┼──────────────────────────────┐
Session Planner Engines (internal/engine)
(model) (what to collect next) ├─ Reasoner / Signals
│ │ ├─ Hypothesis Engine
Evidence Store Evidence Graph Timeline ├─ Confidence Engine
(in-memory) │ ├─ Contradiction Engine
│ Hypotheses + Confidence ├─ Missing-Evidence Engine
History Report Generator ├─ Blast-Radius Estimator
└─ Timeline / Graph builders
```
**没有**连接器。没有 AWS SDK，没有 Kubernetes SDK，没有 GitHub SDK，没有
Slack SDK，没有 Prometheus SDK，没有 Datadog SDK。什么都没有。
每个引擎都定义在 Go interface 之后（参见 `internal/runtime` 的
`Engines` struct），因此内置的启发式实现可以替换为
替代方案（例如由 LLM 支持），而无需触及运行时或 MCP 层。
## 证据类别
引擎仅识别以下供应商中立的类别：
`application_logs`、`infrastructure_events`、`deployment_events`、`alert_events`、
`metrics`、`trace_events`、`configuration_changes`、`network_events`、
`database_events`、`security_events`、`human_context`、`custom`。
## 证据模型
助手提交的每个对象都会被标准化为：
```
{
"id": "uuid",
"timestamp": "2026-06-27T09:01:00Z",
"category": "application_logs",
"source": "provided_by_client",
"entity": "checkout-api",
"summary": "Database connection timeout",
"payload": {}
}
```
`payload` 是不透明的 —— 可以放入任何内容。引擎从不解析供应商格式；
它对 `category`、`timestamp`、`entity` 和 `summary` 进行推理，并提取
`payload` 的 key（如 `region`、`customer` 和 `api`/`endpoint`）用于影响范围
估算。
## MCP 工具
| 工具 | 目的 |
| -------------------------- | ------------------------------------------------------------------------------------------------ |
| `start_investigation` | 开始会话。返回 `session_id`、`status` 以及首先需要收集的 `required_evidence`。 |
| `submit_evidence` | 添加证据。返回更新后的 `progress`、`confidence`、`missing_evidence`、`next_required_evidence`、`updated_hypotheses`、`contradictions`。 |
| `get_investigation_status` | 当前的假设、置信度、图、时间线、缺失证据、影响范围、进度。 |
| `finish_investigation` | 最终报告：执行摘要、时间线、证据、假设、根因候选、图、影响范围、矛盾、缺失证据、建议、置信度以及 Markdown 格式的复盘。 |
### 示例：`start_investigation`
请求：
```
{
"question": "Why did checkout fail yesterday?",
"service": "checkout-api",
"time_window": { "start": "2026-06-27T09:00:00Z", "end": "2026-06-27T09:30:00Z" }
}
```
响应（已节选）：
```
{
"session_id": "inv-…",
"status": "collecting_evidence",
"required_evidence": [
{ "category": "deployment_events", "priority": "high", "reason": "Need to determine whether a deployment preceded the incident." },
{ "category": "application_logs", "priority": "high", "reason": "Need application logs to characterize the failure mode." },
{ "category": "metrics", "priority": "medium" }
]
}
```
## 调查生命周期
```
start_investigation
└─> planner determines required evidence
└─> submit_evidence (repeat)
└─> planner re-evaluates, hypotheses & confidence update
└─> confidence sufficient? ── no ──> keep collecting
└─ yes ─> finish_investigation
```
一切都是**增量式**的，并在一次调查期间保存在**内存**中 ——
无需从数据库重新计算任何内容，并且（目前）没有持久化层。
## 安装
预构建的二进制文件发布在 [GitHub Releases](https://github.com/stackrail-io/Incident-Investigator/releases)。
推送 `v*` 标签（例如 `v0.1.0`）以触发发布工作流并发布安装程序。
### macOS / Linux
```
curl -fsSL https://raw.githubusercontent.com/stackrail-io/Incident-Investigator/main/scripts/install.sh | bash
```
安装到自定义目录：
```
INSTALL_DIR="$HOME/.local/bin" curl -fsSL .../install.sh | bash
```
安装特定版本：
```
INCIDENT_INVESTIGATOR_VERSION=0.1.0 curl -fsSL .../install.sh | bash
```
验证：
```
incident-investigator version
```
### Windows
```
irm https://raw.githubusercontent.com/stackrail-io/Incident-Investigator/main/scripts/install.ps1 | iex
```
特定版本：
```
$env:INCIDENT_INVESTIGATOR_VERSION = "0.1.0"
irm https://raw.githubusercontent.com/stackrail-io/Incident-Investigator/main/scripts/install.ps1 | iex
```
### Docker
拉取并运行（stdio MCP 服务器）：
```
docker pull ghcr.io/stackrail-io/incident-investigator:0.1.0
docker run -i --rm ghcr.io/stackrail-io/incident-investigator:0.1.0
```
或使用安装助手（拉取镜像并打印 MCP 配置）：
```
curl -fsSL https://raw.githubusercontent.com/stackrail-io/Incident-Investigator/main/scripts/install-docker.sh | bash
```
本地构建：
```
docker build -t stackrail/incident-investigator:0.1.0 .
docker run -i --rm stackrail/incident-investigator:0.1.0
# 或者使用 compose
docker compose up --build
```
### Claude Code 插件
从此仓库的插件市场安装（包含 MCP 服务器 + 调查技能）：
```
/plugin marketplace add stackrail-io/Incident-Investigator
/plugin install incident-investigator@incident-investigator
/reload-plugins
```
使用捆绑的技能：
```
/incident-investigator:incident-investigation
```
在提交到 [Claude 社区市场](https://platform.claude.com/plugins/submit) 之前进行本地验证：
```
claude plugin validate plugins/incident-investigator
```
详情请参阅 [plugins/incident-investigator/README.md](plugins/incident-investigator/README.md)。
### Codex 插件
```
codex plugin marketplace add stackrail-io/Incident-Investigator
codex plugin install incident-investigator --source incident-investigator
```
在 Codex TUI 中使用 `/plugins` 浏览已安装的插件。
官方 Codex 插件目录目前尚不接受第三方提交；这个基于 Git 的市场现在可用。请参阅 [OpenAI 的插件构建指南](https://developers.openai.com/codex/plugins/build)。
### MCP 客户端配置
安装后，将你的 MCP 客户端指向二进制文件或容器：
**原生 (macOS / Linux)**
```
{
"mcpServers": {
"incident-investigator": {
"command": "incident-investigator"
}
}
}
```
**Windows**
```
{
"mcpServers": {
"incident-investigator": {
"command": "C:/Users/you/AppData/Local/Programs/incident-investigator/incident-investigator.exe"
}
}
}
```
**Docker**
```
{
"mcpServers": {
"incident-investigator": {
"command": "docker",
"args": ["run", "-i", "--rm", "ghcr.io/stackrail-io/incident-investigator:0.1.0"]
}
}
}
```
### 手动安装
从 [Releases](https://github.com/stackrail-io/Incident-Investigator/releases) 下载适用于你平台的压缩包，解压 `incident-investigator`（或 `incident-investigator.exe`），并将其放在你的 `PATH` 中。
### 从源码构建
需要 Go 1.25+。
```
git clone https://github.com/stackrail-io/Incident-Investigator.git
cd Incident-Investigator
go build -o bin/incident-investigator ./cmd/incident-investigator
./bin/incident-investigator
```
或者使用 `go run`（无需安装）：
```
{
"mcpServers": {
"incident-investigator": {
"command": "go",
"args": ["run", "github.com/stackrail/incident-investigator/cmd/incident-investigator"]
}
}
}
```
有关开发环境设置，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)；有关报告漏洞，请参阅 [SECURITY.md](SECURITY.md)。
## 构建与运行（开发者）
```
go test ./...
go build -o bin/incident-investigator ./cmd/incident-investigator
./bin/incident-investigator version
./bin/incident-investigator
```
当推送 `v*` 标签时会使用 [GoReleaser](https://goreleaser.com/) 进行构建（参见 `.github/workflows/release.yml`）。
## 推理的工作原理
内置引擎是确定性的、基于规则的启发式算法，纯粹
对从证据中提取的抽象信号进行操作（`internal/engine/signals.go`）：
- **Planner** —— 从基准（部署、日志、告警、指标）开始，并
随着证据的到来*动态*扩展请求集（例如，一旦
出现部署，它就会请求配置变更和 trace）。
- **假设引擎** —— 总是产生*竞争*假设
（部署引起、与部署无关、数据库饱和、配置
变更、网络/DNS、证书过期、资源耗尽、重试风暴、
未知），进行评分并标准化为概率场。
- **置信度引擎** —— 随着独立一致性、多类别
佐证和清晰的时间顺序而上升；随着矛盾和
缺失关键证据而下降。
- **矛盾引擎** —— 标记不可能/不一致的序列，例如
在事件开始*之后*带有时间戳的部署、在发生之前恢复，以及
重复的证据。
- **影响范围估算器** —— 从实体和众所周知的 payload key 推导出受影响的服务/区域/客户/API。
## 项目布局
```
cmd/incident-investigator/ MCP server entrypoint (stdio)
plugins/incident-investigator/ Claude Code + Codex plugin bundle
.claude-plugin/marketplace.json Claude marketplace catalog
.agents/plugins/marketplace.json Codex marketplace catalog
internal/model/ Vendor-neutral domain types (evidence, graph, …)
internal/engine/ Planner, hypotheses, confidence, contradictions, …
internal/runtime/ Stateful runtime + in-memory store
internal/mcpserver/ MCP tool definitions and DTOs
internal/fixtures/ Realistic incident scenarios used by tests
```
## 测试
真实的事件 fixture（`internal/fixtures`）端到端验证 planner、证据
图、时间线、假设和置信度：
- 错误的部署
- 数据库中断
- 证书过期
- DNS 中断
- Kubernetes 重启循环
- 内存泄漏
- 重试风暴
```
go test ./...
```
还有一个端到端的 MCP 测试，它通过
内存传输驱动实际协议（`internal/mcpserver/server_test.go`）。
## 不在范围内（故意未实现）
连接器、身份验证、RBAC、UI 和流式遥测明确
**不在范围内**。引擎的唯一工作是对证据进行推理。
## 社区
| 资源 | 链接 |
| -------- | ---- |
| 插件包 | [plugins/incident-investigator/README.md](plugins/incident-investigator/README.md) |
| Claude 市场提交 | [platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit) |
| 更新日志 | [CHANGELOG.md](CHANGELOG.md) |
| 贡献 | [CONTRIBUTING.md](CONTRIBUTING.md) |
| 行为准则 | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) |
| Bug 报告 | [提交 Bug 报告](https://github.com/stackrail-io/Incident-Investigator/issues/new?template=bug_report.yml) |
| 安全 | [SECURITY.md](SECURITY.md) |
## License
MIT（参见 `LICENSE`）。