Uthmannabeel/blackbox

# 🛩️ BlackBox **记忆能在崩溃中幸存的 incident-response agent。** BlackBox 是一个 SRE copilot，用于对生产事件进行分诊、诊断和协助缓解。就像飞机的黑匣子一样，它的记忆专为抵御它正在帮你对抗的故障而构建：它在 CockroachDB 之上保持**全局可用、强一致性和区域固定** —— 因此，当整个云区域在事件处理中途宕机时，agent 依然能保持记忆和持续推理。 ## 为什么选择 CockroachDB（而不仅仅是 vector store） 大多数 agent memory 演示使用的数据库都可以被随意替换。BlackBox 的设计核心围绕着**只有 CockroachDB** 才能做好的事情： | 功能 | BlackBox 如何使用它 | 为什么重要 | |---|---|---| | **`REGIONAL BY ROW`** | 每条记忆（incident、runbook、thought）都通过 `crdb_region` 固定到其源区域。 | 低延迟的本地召回 + **按行控制数据驻留** —— EU 事件的记忆永远不会离开 EU。 | | **`SURVIVE REGION FAILURE`** | 记忆数据库可以容忍整个区域的丢失而不会丢失数据。 | agent 的记忆比它正在诊断的故障更持久。这是现场演示的最精彩之处。 | | **Distributed Vector Indexing (C-SPANN)** | 带有区域前缀 vector index 的 `VECTOR(1024)` 列，用于语义召回。 | 在数百万个 vector 中询问“我们以前见过类似的事件吗？”，并按区域协同定位。 | | **Strong consistency** | 实时的 `incident_state`（阶段、假设、操作）是事务性的。 | agent 在危机期间永远不会根据过期或脑裂状态采取行动。 | 一个系统既是**记录系统**又是**agent memory 层** —— 无需将 vector DB、状态存储和缓存拼接在一起。 **我们证明了这一点，而不是口头声称：** 本仓库提供了一个本地的 9 节点、3 区域混沌测试环境（[`infra/chaos/`](./infra/chaos/README.md)）。我们在加载了 10,000+ 条记忆的情况下，杀死了数据库主区域的所有节点 —— 召回依然在约 140ms 内响应（包括源区域已死亡的记忆），并且源区域已死亡的写入依然持续提交。 ## 超越召回：不断复利的记忆，以及能对自身大脑进行分诊的 agent - **Learning loop** —— 当 agent 解决了一个事件后，该解决方案会自动提炼为新的*学习到的 runbook*（程序性记忆）。下一个类似的事件会召回 agent 刚刚学到的修复方法。 - **Self-diagnosis** —— agent 的记忆*就是*一个 CockroachDB 集群，而它的 `diagnose_memory` 工具会观察各区域的节点存活情况和生存目标，因此在中途发生故障时，它可以解释：“一个区域宕机了；但我所有的记忆仍然可读并可写。” ## 所使用的必需工具 **CockroachDB（使用了 3 个必需工具；要求 ≥2 个）：** - ✅ **Distributed Vector Indexing** —— 针对 incident、runbook 和 agent thought 流的语义记忆（`db/schema.sql`）。 - ✅ **Cloud Managed MCP Server** —— agent 在推理过程中将其实时操作的集群（schema、健康状态、运行中的查询）作为一种工具进行内省。 - ✅ **`ccloud` CLI** —— 用于配置多区域集群并启用区域生存能力（`infra/`）。 **AWS（使用了 3 个；要求 ≥1 个）：** - ✅ **Amazon Bedrock** —— 使用 Claude 进行推理，并使用 Titan Text Embeddings v2 (1024-dim) 生成记忆 embedding。 - ✅ **AWS Lambda** —— 托管 agent 循环。 - ✅ **Amazon S3** —— 存储 incident 产出物和事后分析报告。 ## 记忆模型 BlackBox 实现了 agent 所需的三种经典记忆类型，每种都由一个 CockroachDB 表提供支持（参见 `db/schema.sql`）： - **Episodic** —— `incidents`：发生了什么、何时发生以及是如何解决的。 - **Semantic / procedural** —— `runbooks`：如何修复特定类别的问题。 - **Working + long-term stream** —— `agent_memory`： agent 的观察、操作和反思，并根据重要性进行权重分配以便召回。 - **Structured live state** —— `incident_state`：正在处理中的 incident 的事务性真实数据源。 每个表都是 `REGIONAL BY ROW` 并带有区域前缀的 vector index。 ## 架构 ``` ┌─────────────────────────────┐ Operator (browser) ── │ web/ Next.js dashboard │ │ chat · timeline · CHAOS btn │ └──────────────┬──────────────┘ │ ┌──────────────▼──────────────┐ │ packages/agent (AWS Lambda) │ │ reason ↔ recall ↔ act loop │ │ Bedrock: Claude + Titan │ └───────┬───────────────┬──────┘ memory tools │ │ introspection ┌───────▼──────┐ ┌─────▼─────────────┐ │ packages/ │ │ CockroachDB Cloud │ │ memory (pg) │──│ Managed MCP Server│ └───────┬──────┘ └───────────────────┘ │ ┌──────────────────▼───────────────────────┐ │ CockroachDB Cloud — multi-region │ │ us-east-1 · eu-west-1 · ap-south-1 │ │ REGIONAL BY ROW · SURVIVE REGION FAILURE │ │ distributed VECTOR indexes (C-SPANN) │ └───────────────────────────────────────────┘ ``` 详情请参阅 [`ARCHITECTURE.md`](./ARCHITECTURE.md)。 ## 仓库结构 ``` cockroach-ai/ ├── db/ CockroachDB schema + seed (the memory layer's heart) ├── packages/ │ ├── memory/ TypeScript memory service over pg + Bedrock embeddings │ └── agent/ Agentic reason/recall/act loop on Bedrock ├── web/ Next.js demo dashboard (incident chat + chaos button) └── infra/ ccloud + AWS provisioning ``` ## 快速开始 ### 30秒离线体验（无需云服务，无需密钥） ``` npm install npm run dev:mock # open http://localhost:3000 ``` Mock 模式会替换为确定性的 embedding、由样本 incident 种子化的内存存储，以及一个脚本化的 agent —— 因此整个 UI（召回、incident 时间线、混沌/生存能力面板）都可以在零凭证的情况下运行。非常适合作为初次体验和演示的备用方案。 ### 对接真实的 CockroachDB + AWS Bedrock 运行 ``` npm install cp .env.example .env # fill in CockroachDB + AWS credentials npm run db:schema # apply db/schema.sql to your cluster npm run db:seed # load sample fleet + historical incidents (embeds via Bedrock) npm run agent:dev # talk to the agent from the CLI npm run dev # or use the web dashboard at http://localhost:3000 ``` 有关配置多区域集群、启用 Managed MCP Server 以及申请 Bedrock 模型访问权限的信息，请参阅 [`infra/README.md`](./infra/README.md)。 ## 测试 ``` npm test # vitest — runs the full suite in offline mock mode ``` 涵盖了 embedding 的确定性和相似度排序、基于种子化记忆的语义召回、agent 的推理/召回/执行循环，以及 API 速率限制。 ## 生产环境加固 - 通过 MCP 进行只读、受语句保护的集群内省 - 全面使用参数化 SQL；通过 TLS `verify-full` 连接到集群 - 在 agent endpoint 上实施速率限制 + 输入验证 - 配置 CSP + `Strict-Transport-Security`/`X-Frame-Options`/`X-Content-Type-Options` 标头 - 错误仅在服务器端记录；永远不会泄露给客户端 ## 许可证 Apache-2.0 —— 参见 [`LICENSE`](./LICENSE)。

标签：AIOps, AWS Bedrock, CockroachDB, RAG, 自动化攻击, 运维