Cairn

一个智能体式事件分析副驾。用自然语言问"为什么凌晨 3 点结账延迟飙升？"；Cairn 会查询可观测性技术栈，与部署时间线进行关联分析，检索相关运行手册，并提出带有证据的根因——还可以在人工审批门禁之后执行修复操作。

本仓库实现了 docs/architecture.md。

仪表盘

配套的 npm 包（npx @nouman-amjad/cairn dashboard）可为任何项目提供实时本地仪表盘——无需构建步骤，无依赖，无需网络。

Related MCP server: semley

四项承诺及其在代码中的位置

目录结构

packages/
  cairn-core/          domain model, config, auth, DB, sensitivity, artifacts
  cairn-mcp-kit/       MCP scaffolding: identity, OPA guard, result capping, versioning
services/
  cairn-gateway/       OIDC, rate limits, cost budgets, circuit breaker, SSE fan-out
  cairn-orchestrator/  the agent loop as a state machine persisted to Postgres
  cairn-router/        model routing, cost accounting, vLLM + Anthropic clients
  cairn-approval/      approval state machine and the Slack gate
  cairn-mcp-observability/  metrics, logs, traces, deploys, artifacts
  cairn-mcp-runbooks/       hybrid search, ingest, past-incident recall
  cairn-mcp-actions/        approval-gated write tools
  cairn-eval/          30 scenarios, 7 metrics, the CI gate, a seeded stack
  cairn-cli/           `cairn ask "why did checkout spike?"`
ui/                    Next.js: chat, trajectory viewer, approvals
cairn-deploy/          Helm chart, ArgoCD app-of-apps, OPA bundle, prompts
cairn-infra/           Terraform: VPC, EKS, RDS, Karpenter, IRSA, S3
docker/                one Dockerfile for all Python services, plus vLLM
docs/adr/              14 architecture decision records

cairn-deploy 和 cairn-infra 在此处随附以供审查。在生产环境中，它们是具有独立生命周期的独立仓库——参见 ADR-013。

快速开始

make install     # uv sync + npm ci
make up          # Postgres (pgvector), Redis, MinIO, OPA
make migrate
make test        # 246 tests
make selfcheck   # 21 module self-checks
make eval        # 30 scenarios through the real agent loop

上述所有操作都不需要 GPU 和 API 密钥。make eval 以启发式模式运行，该模式使用脚本化的替身而非模型来演练整个流水线——循环、工具上限、持久化、七项指标、门禁。参见注意事项。

要针对真实模型运行，请设置 CAIRN_ROUTER_ANTHROPIC_API_KEY 并将 CAIRN_ROUTER_VLLM_URL 指向 vLLM 服务器。

使用 MCP 客户端进行调试

每个 MCP 服务器都支持 stdio 和 Streamable HTTP：

make mcp-stdio
# or, the way an outside user would:
uvx cairn-mcp-observability --stdio

将 Cursor、Zed 或任何其他 MCP 客户端指向它，你就能看到智能体所看到的完全一致的内容。这大约只需二十行代码（ADR-002），而且当工具结果第一次与你的预期完全不符时，它就值回票价了。

已验证与未验证的内容

说得具体一点，因为"它能工作"不是一个值得含糊其辞的说法。

在此处实际运行验证过的内容：

• 246 个测试在真实的 PostgreSQL 16 + pgvector 上通过，包括审批门禁安全属性（无自我审批、无双重执行、未经审批不执行、由数据库触发器强制执行的仅追加审计日志）以及路由器属性——受限数据永远不会到达云端模型——已对所有任务类别和层级状态进行了穷举检查。

• 21 个模块自检通过。

• Alembic 迁移可干净地应用于真实数据库。

• 12/12 个 OPA 策略测试通过。

• 30 个场景的评估通过真实智能体循环端到端运行；所有七项指标均高于目标，门禁正确阻止了模拟回归和低于目标的运行。

• UI 通过类型检查并成功构建。CLI 的五个命令均可解析。

此处未验证的内容及其原因：

• 评估准确率数据。 提交的基线是启发式模式，它评估的是测试框架本身而非智能体。真实数据需要针对实时路由器运行 make eval-record。LLM 原因评判器已构建但未经校准——没有人标注过 100 次运行，因此 κ 未知。

• Terraform。 此环境中没有 terraform 二进制文件；fmt、validate 和 tflint 在 CI 中运行。尚未对任何 AWS 账户执行过应用操作。

• Helm 渲染。 helm lint、template 和 kubeconform 在 CI 中针对所有三个环境运行。未在本地运行。

• docs/cost.md 中的每一项成本数据。 用于衡量这些数据的核算系统已构建并测试；但用于填充数据的流量尚不存在。

• vLLM 性能表。 基于内存带宽的算术推算，而非实测。docs/inference.md 提供了基准测试命令和证伪阈值。

• 混沌测试。 路线图的第 7 阶段尚未运行。

docs/roadmap.md 逐阶段跟踪此进度。

文档

• docs/architecture.md — 本实现所依据的设计

• docs/adr/ — 14 条决策记录，每条都附有后果

• docs/security.md — 威胁模型及每项控制措施的位置

• docs/inference.md — GPU 规格、KV 缓存算术、vLLM 标志

• docs/cost.md — 成本模型，包括 GPU 是否能收回成本

• docs/operations.md — 运行手册：什么情况会触发告警、该怎么做

• docs/roadmap.md — 阶段、风险以及实际完成的内容

• services/cairn-eval/README.md — 如何解读门禁失败