Allen-Saji/deja

# Deja [](https://github.com/Allen-Saji/deja/actions/workflows/ci.yml) [](LICENSE) Deja 是一个持久的 incident response agent。它会诊断 alert，引用相关的 precedent，记录发生的事件，并根据 operator 的处理结果改进其下一次响应。 为 CockroachDB x AWS Hackathon 而构建。 [打开实时 dashboard](https://deja-khaki.vercel.app) ## 为什么选择 Deja 大多数 incident agent 每次处理 alert 都是以零知识储备开始。当 worker 超时时，它们的推理过程就会丢失，之前的 postmortem 与当前的 incident 依然脱节，并且重复的 alert 噪音不断传达给 operator。 Deja 将记忆视为执行模型的一部分： - Working memory 会在每个 graph node 进行 checkpoint，以便中断的运行可以恢复。 - Episodic memory 通过 CockroachDB C-SPANN 检索类似的已完成 incident。 - Procedural memory 学习需要抑制哪些重复的通知，以及哪些 runbook 有效。 最终的结果是，这样一个 agent：它的诊断可以追溯到存储的 evidence，并且随着 incident 的累积，其行为会变得更加有用。 ## 架构  一个 IAM 签名的 alert 到达 AWS Lambda 上的 FastAPI 服务。API 会预留一个持久运行，将异步自调用排入队列，并返回 HTTP 202。Worker 获取数据库 lease，加载最新的 LangGraph checkpoint，并仅执行未完成的 graph node： 1. `ingest` 持久化 alert。 2. `recall` 使用 VoyageAI 对 incident 进行 embedding，并使用 C-SPANN 检索相关的 precedent。 3. `triage` 向 Groq 请求结构化诊断，并验证每个引用的 incident ID。 4. `act` 推荐 runbook 或仅抑制已学习到的重复通知。 5. `writeback` 完成 postmortem 并为未来的运行记录 evidence。 CockroachDB Cloud 是用于 incident、运行、postmortem、checkpoint、vector、噪音账本和 runbook 结果的记录系统。独立的 Next.js dashboard 和 CockroachDB Managed MCP 连接使用专门的只读访问权限。 `act` node 仅供参考。Deja 绝不会更改基础设施，也绝不会跳过 incident 处理。 ## 持久记忆 ### Working memory `CockroachDBSaver` 在稳定的 `run_id` 下，在每个 graph node 之后写入 checkpoint。Lambda 重试会获取相同的执行 lease，并从保存的 checkpoint 继续，而不是重新开始处理另一个 incident。 ### Episodic memory VoyageAI 生成 1,024 维的 postmortem embedding。CockroachDB C-SPANN 在相同的服务和 alert 类型中搜索已完成的 incident。Triage 只能引用由该搜索返回的 ID。 ### Procedural memory 噪音账本只有在匹配到三次非关键、非升级的观察结果后，才会学习到一个稳定的重复项。Runbook 使用根据记录的 operator 成功和失败结果计算出的、经过 Laplace 平滑的有效性得分。 ## 生产环境证据 已部署的系统已通过其真实的受 IAM 保护的 Lambda Function URL 和 CockroachDB Cloud 数据库进行了测试验证。 | 能力 | 已验证证据 | | --- | --- | | 正常 alert 流程 | `RUN-E1D6DD5025E8` 排队并完成了所有五个 graph node | | 超时恢复 | `RUN-591F981A5EDB` 在 triage 之前超时；重试在 triage 时恢复并在 2.966 秒内完成 | | 数据库节点丢失 | 本地的三节点 CockroachDB 验收测试在 triage 之前杀死了一个节点，并通过剩余的 quorum 完成 | | 生产可观测性 | `RUN-3E482889BBA4` 在 4.334 秒内完成，并带有从验收测试到完成的结构化 CloudWatch 事件 | | 只读检查 | Managed MCP 通过限定了只读权限的 principal 查询了实时集群 | | 公共运维视图 | Vercel dashboard 提供了一个经过脱敏处理、自动刷新的快照，不包含任何数据库或提供商凭证 | 详细的只读控制和验证查询位于 [`docs/observability/read-only-access.md`](docs/observability/read-only-access.md)。 ## 仪表板 生产环境：[deja-khaki.vercel.app](https://deja-khaki.vercel.app) Dashboard 展示了 incident 动态、graph node 和尝试追踪、延迟、记忆提升、学习到的噪音模式以及 runbook 有效性。它仅从 Next.js 服务边界查询 CockroachDB，并且不暴露任何 mutation endpoint。 ``` cd dashboard cp .env.example .env.local # 将 DEJA_DATABASE_URL 设置为只读的 CockroachDB 连接。 npm ci npm run check npm run dev ``` Vercel functions 运行在 `bom1`，与孟买的 CockroachDB 集群处于同一位置。 ## API - `GET /health`：进程健康状态，无需外部调用 - `GET /ready`：CockroachDB 连通性 - `POST /alerts`：预留运行，将执行排入队列，返回 HTTP 202 - `GET /runs/{run_id}`：持久化的运行和 postmortem - `GET /runs/{run_id}/attempts`：执行尝试和 checkpoint 恢复位置 - `POST /runbooks`：创建一个启用的 runbook，并带有中性的有效性得分 - `POST /runs/{run_id}/runbook-outcome`：记录所选 runbook 的成功或失败 Alert 示例： ``` { "service": "payments-api", "alert_type": "http-500-spike", "severity": "critical", "message": "HTTP 500 rate exceeded 18 percent after deploy", "labels": { "environment": "production", "region": "ap-south-1" } } ``` ## 本地开发 要求： - Python 3.12 - `uv` - 用于 dashboard 的 Node.js 22 - 用于三节点数据库验收测试的 Docker ``` uv sync --frozen --extra dev --python 3.12 cp .env.example .env ``` 在 `.env` 中设置 `DATABASE_URL`、`GROQ_API_KEY` 和 `VOYAGE_API_KEY`，然后在不打印其值的情况下加载它们： ``` set -a . ./.env set +a .venv/bin/ruff check . .venv/bin/pytest -q .venv/bin/python scripts/live_smoke.py .venv/bin/python scripts/memory_state_acceptance.py make crdb-node-failure-acceptance ``` 探索性的 checkpoint 和 vector 实验仍保留在 `spikes/` 下： ``` .venv/bin/python spikes/s3_checkpoint_resume.py crash .venv/bin/python spikes/s3_checkpoint_resume.py resume .venv/bin/python spikes/s3_vectorstore.py ``` ## 实时验收 使用签名请求调用受 IAM 保护的 Function URL： ``` .venv/bin/deja-simulate https://FUNCTION_ID.lambda-url.ap-south-1.on.aws \ --aws-profile deja \ --aws-region ap-south-1 .venv/bin/python scripts/memory_replay_acceptance.py \ https://FUNCTION_ID.lambda-url.ap-south-1.on.aws \ --aws-profile deja \ --aws-region ap-south-1 # 仅在受控的超时接受窗口内启用 DEJA_CHAOS_ENABLED。 make lambda-timeout-acceptance ``` ## 部署 部署脚本会创建或更新 ECR 存储库、Lambda 执行角色、容器 function、异步重试配置以及受 IAM 保护的 Function URL。 ``` set -a . ./.env set +a AWS_PROFILE=deja AWS_REGION=ap-south-1 ./scripts/deploy.sh ``` ## 项目布局 ``` src/deja/ FastAPI service, LangGraph workflow, memory, and persistence dashboard/ Read-only Next.js operations dashboard scripts/ Deployment, smoke, replay, timeout, and node-loss acceptance deploy/ Isolated three-node CockroachDB test environment docs/ Architecture, observability, and submission material tests/ Backend unit and contract tests spikes/ Early checkpoint and vector-search experiments ``` ## 安全模型 - Lambda Function URL 需要 AWS IAM 身份验证。 - CockroachDB 连接使用 TLS `verify-full`，并在镜像中包含云根证书。 - 执行 lease 可防止并发的重复交付，并会安全过期以便重试。 - Node 效果基于运行 ID 和 node 名称实行先写者优先策略。 - Groq 输出在到达工作流之前会经过 schema 验证。 - Dashboard 和 Managed MCP 使用一个被限制为仅能对九张特定表执行 `SELECT` 操作的 principal。 - 浏览器响应中不包含数据库 URL、AWS 凭证或任何提供商密钥。 ## 当前局限性 - Deja 推荐操作，但不执行基础设施更改。 - 相似性检索有意受到服务和 alert 类型的限制。 - 噪音抑制需要稳定的重复观察，并且绝不会抑制关键 alert。 - Operator 结果捕获通过 API 暴露；不包含专用的反馈 UI。 ## License [MIT](LICENSE)

标签：CockroachDB, LangGraph, Serverless, 事故响应, 告警自动化, 请求拦截, 逆向工具