内容
# 布洛克
**一款MCP服务器，估算系统的实际容量并找出其瓶颈，基于引用的数字而非LLM的猜测。**
你指向一个架构（一个`docker-compose.yml`文件或一个组件列表），并告诉它你期望的规模。它告诉你哪个组件首先会崩溃，大致支持多少用户，以及原因。推理是确定性的。核心中没有运行模型，因此它是免费的，并且每次都给出相同的答案。
以布洛克命名，布洛克是北欧神话中的一个矮壮的矮人铁匠（也是《战神》中辛德里的性格粗鲁、更有趣的兄弟）：他尊重有价值的工作，对懒惰的工作没有耐心。匹配的冷面声音正在开发中；今天的判决是简单明了的。
---
## 问题
大多数人，甚至越来越多的AI编码助手，在设计系统时不知道他们所设计系统的限制。一个Postgres数据库用于所有事情。一个CDN在写入前面。六个顺序跨区域调用。没有人发现设计在12,000用户时就会崩溃，直到它实际崩溃为止。
明显的人工智能方法，“询问模型我的架构是否良好”，会产生自信的、通用的、没有根据的建议。前沿模型在系统设计方面一般般，本地小模型更差。因此，幼稚的设计是一个返回听起来合理的废话的包装器。
布洛克采取相反的方法：**模型从不推理系统。确定性代码使用真实的、引用的数字进行推理。**
---
## 它今天的作用
给定一个架构和一个预期的规模，布洛克返回：
- **瓶颈** 组件（第一个饱和的组件），
- 设计支持的最大**用户容量**，
- **每个组件的利用率** （负载与其引用的上限），
- 它对您未提供的任何输入所做的**假设**，明确说明。
示例（`api` + Postgres + Redis，支持200万日活跃用户）：
```
瓶颈：api
它大约超过其安全上限1.7倍。
设计的最大容量：~1,152,000日活跃用户。
置信度：低。
```
注意它所捕获的内容：墙是单个**应用层**，而不是大家担心的数据库。缓存吸收了读取操作，因此Postgres没问题，单个应用实例首先饱和。这就是确定性引擎产生的那种非显而易见的、具体的成果。
---
## 背后的数据
布洛克不会捏造数字。每个容量判决都追溯到一个精选的、引用的能力表（每个范围的保守低端用于判决）：
| 组件 | 吞吐量（单个实例） | 来源 |
|-----------|------------------------------|--------|
| 关系型数据库（Postgres） | ~1,000至1,875次写入/秒，计划在500+时更改 | [PostgreSQL写入基准测试](https://dev.to/haikasatryan/postgresql-write-performance-what-the-benchmarks-wont-tell-you-mm7) |
| 缓存（Redis） | ~100,000次操作/秒，1,000,000+管道化 | [Redis基准测试](https://redis.io/docs/latest/operate/oss_and_stack/management/optimization/benchmarks/) |
| 队列（Kafka） | ~每集群数百万条消息/秒 | [Confluent：Kafka性能](https://developer.confluent.io/learn/kafka-performance/) |
| 应用服务器 | ~2,000至8,000次请求/秒 | 数量级 |
| CDN | 大量读取分发，写入无帮助 | CDN是读取缓存 |
容量通过标准的[信封背面估算](https://bytebytego.com/courses/system-design-interview/back-of-the-envelope-estimation)和[小法则](https://en.wikipedia.org/wiki/Little's_law)计算。目标是正确的数量级：2倍以内即可，偏差100倍意味着设计的系统是错误的。
---
## 它经过基准测试，基准测试是诚实的
自己运行：
```bash
python scripts/bench.py
```
```
布洛克基准测试成绩单
瓶颈准确率：100%
容量在2倍以内：100%
偏差100倍：0
可引用的准确率：100%
过载准确率：100%
```
这意味着什么，不意味着什么，所以这里有诚实的框架。基准测试验证了三个方面：
1. **一致性。** 在受控设计中，引擎是否能重现其自身的引用上限？（预期容量由人工从发布的上限导出，而不是从引擎读取，因此不是循环的。）
2. **行为。** 它是否对未知组件保持沉默，并且不对小型业余应用发出狼来了的警报？
3. **诚实。** 像Instagram（按数据量分片，而不是吞吐量）和Discord（读取热点分区）这样的真实系统被包含在内，作为文档化的模型例外。它们运行，它们在记分卡中可见，并且由于它们超出了单个实例吞吐量模型可以判断的范围，因此不参与准确性评分。
因此，声明是精确的：**布洛克与其引用的数字一致，行为正确，并且对其无法看到的内容诚实。** 这不是一个预测每个现实世界缩放墙的声明。
---
## 它是如何工作的
```
Claude Code（或任何MCP客户端）
|
v
布洛克MCP
|
解析为设计图 <- 调用者执行任何英文解析；
| 布洛克只消耗结构化输入
v
确定性容量镜头 <- 引用上限 + 信封背面数学
|
v
判决：瓶颈 + 最大用户 + 每个组件的利用率
```
分离是关键。调用助手（已经是一个LLM）将您的文本或代码转换为结构化图。布洛克的引擎不包含任何模型，也不进行网络调用，对引用数字进行实际推理。这就是为什么它是免费的、确定性的，而不是一个包装器。
---
## 限制（在信任判决之前请阅读此内容）
布洛克故意对其边界保持诚实：
- **目前仅限容量。** 它尚未建模延迟、成本或设计反模式。这些都在下面的路线图中。
- **仅限吞吐量。** 它推理请求吞吐量，不考虑数据量、连接限制、热点分区或锁竞争，这是许多实际数据库真正死亡的地方。
- **单个实例。** 它不建模副本或分片。它告诉您当组件的单个实例成为墙时，这正是预缩放设计所需的建议。
- **数量级。** 组件吞吐量因硬件和配置而异，范围从10倍到100倍，因此请将数字视为“正确范围”，而不是精确的。
- **它放弃。** 如果它没有引用数字的组件，它会说明，而不是猜测。
---
## 安装
```bash
git clone https://github.com/RudraDudhat2509/brok
cd brok
pip install -e ".[dev]"
```
将其添加到MCP客户端（例如Claude Desktop），在`mcpServers`块中：
```json
{
"mcpServers": {
"brok": { "command": "python", "args": ["-m", "brok.server"] }
}
}
```
---
## 用法
布洛克公开了两个工具。调用助手选择正确的工具，重要的是，应该传递预期的规模（`expected_dau`）；如果没有它，结果会退回到假设的默认值，并报告为低置信度。
**`review_architecture(compose_yaml, expected_dau=..., read_write_ratio=..., ...)`**
当项目有`docker-compose.yml`时，助手读取它并传递内容和预期规模。
**`review_components(components, expected_dau=..., ...)`**
当没有compose文件时，助手从代码或用户的描述中推断出组件，并将它们作为`{"name", "type"}`字典列表传递。有效类型：`relational_db`, `cache`, `queue`, `cdn`, `app_server`, `object_store`, `load_balancer`。其他类型被报告为未估计。
两者返回一个结构化结果，助手可以显示和推理：
```python
import brok.server as s
result = s.review_architecture(
"""
services:
api: { build: . }
db: { image: postgres:16 }
cache: { image: redis:7 }
""",
expected_dau=2_000_000,
)
print(result["bottleneck"]) # "api"
print(result["max_dau"]) # 1152000
print(result["report_text"]) # 人类可读的判决
```
返回字段：`bottleneck`, `max_dau`, `confidence`, `assumptions`, `utilizations`, `notes`, `report_text`.
---
## 路线图
今天已构建和基准测试：容量引擎和黄金集基准测试，以及一个可用的MCP界面。
前方：
- **延迟和成本镜头。** 相同的引擎，带有延迟数字表和粗略的成本表，因此判决涵盖“是否快速”和“账单是多少”，而不只是“多少用户”。
- **反模式检查器。** 结构检查单点故障，双写入，写入CDN和热点分区（上面Discord案例的故障模式）。
- **布洛克之声。** 一个叙述层，用布洛克干燥，唐突的语气表述确定性发现（参见[docs/brok-voice.md](docs/brok-voice.md)），而数字仍由引擎计算，工具在不确定时仍放弃。
---
## 为什么要这样构建
布洛克故意与自信的猜测相反。智能存在于引用的数据和算术中，模型远离判断，工具在不知道时放弃。可以信任的容量估计比可能错误的吐司更有价值。
## 开发
```bash
pip install -e ".[dev]"
pytest -q # 完整的确定性测试套件
python scripts/bench.py # 容量基准测试成绩单
```
所有操作无需API密钥和网络即可运行。
