fable-architecture

Fable 架构：微服务强制执行引擎

在项目启动时（第一步）评估项目规格，以确定规模、吞吐量、并发量、领域复杂度或工作负载异构性是否需要采用分布式微服务架构。触发条件满足时，严格限定所有主要编码 Agent 和下游子 Agent，使其只能在解耦的微服务驱动执行模式下工作；按核心能力分配精选的语言与框架组合，并强制执行标准的服务间通信协议。

---

使命

在任何目录搭建或实现开始之前拦截项目规格，确定规模与负载、领域解耦或资源强度是否需要采用分布式架构。达到阈值时，严格禁止 Agent 团队搭建单体架构（allowMonolith: false），强制采用解耦的微服务及精选的多语言技术栈，并要求使用双传输网络：南北向 REST HTTP/JSON（OpenAPI 3.1），以及东西向 gRPC（Protocol Buffers）或消息代理（RabbitMQ / Kafka）。

---

适用场景

• 项目规格描述了高并发（$\ge 5,000$ 个并发用户／连接，$>10,000$ RPS/TPS）。
• 规格定义了 $\ge 2$ 个解耦的业务领域（身份／认证、计费／Stripe、转码、AI 推理、分析、消息传递）。
• 工作负载同时包含受 CPU 限制的内核（复杂数学计算、转码、密码学）和受 I/O 限制的管道（API 网关、CRUD）。
• 用户明确要求评估微服务、设计分布式架构或分配多语言技术栈。
• 第一步提示词评估钩子检测到架构触发阈值。

---

不适用场景

• 项目是简单的命令行脚本、实用程序或单文件工具（fable-execute）。
• 项目是隔离的单领域 CRUD 原型或静态博客，规模仍处于单体架构的适用范围内。
• 任务仅涉及局部错误修复或单模块重构（fable-tdd 或 fable-simplify）。
• 大范围工作已完成拆分，只需按标准步骤进行规划（fable-plan）。

---

情况分类

类别	核心能力	语言	框架选项	主要工作负载	子 Agent 角色
A 类	高并发 API 与分布式网络	Go（Golang）	Fiber、Gin、Go-Kit	无状态路由、每秒数百万条消息、边缘代理	distributed-network-engineer
B 类	I/O 密集型、快速 API 网关与编排	TypeScript	NestJS、Fastify（Node.js）或 Elysia（Bun）	公共 API 网关、BFF、CRUD、快速业务逻辑	gateway-orchestrator / crud-engineer
C 类	高性能计算内核与系统	Rust	Axum、Actix-web	复杂数学计算、密码学、视频转码、原始二进制数据	systems-kernel-engineer
D 类	人工智能、数据工程与 ML	Python	FastAPI（搭配 PyTorch/TensorFlow）	LLM 路由、预测建模、嵌入、ML 管道	ai-inference-engineer
E 类	超高并发、容错实时系统	Elixir	Phoenix（搭配 LiveView）	数十万个持久 WebSocket、实时消息编排、零停机	realtime-systems-engineer

---

协议

阶段 1：初始三向评估

从以下 3 个独立维度评估传入的规格：

1. 维度 1：规模与负载（0–10 分）：检测高并发（$\ge 5k$）、吞吐量目标和延迟 SLA。
2. 维度 2：领域解耦（0–10 分）：检测运营领域边界（auth、billing、gateway、compute、ai、messaging、realtime）。
3. 维度 3：资源强度（0–10 分）：检测 CPU 密集型与 I/O 密集型瓶颈的混合情况。
4. 计算综合得分：$(0.35 \times \text{Scale}) + (0.40 \times \text{Domain}) + (0.25 \times \text{Resource})$。

阶段 2：判定与单体架构锁定

• 如果任一维度 $\ge 7.0$ 或综合得分 $\ge 6.0$：
  • 设置 verdict: 'microservices' 和 allowMonolith: false。
  • 严格禁止搭建单体应用。
• 否则：
  • 设置 verdict: 'monolith' 和 allowMonolith: true。

阶段 3：多语言技术栈分配与拆分

• 确保 API Gateway 使用类别 B（TypeScript/NestJS）作为服务 #1 实例化。
• 为每个已识别的运营领域分配类别 A–E 中专用的服务技术栈。
• 确保除 Gateway 外至少有 2 个不同的领域工作器服务。

阶段 4：通信标准协议

• 南北向：使用 REST HTTP/JSON、OpenAPI 3.1 架构和 TLS 1.3。
• 东西向：使用 gRPC 和 Protocol Buffers（proto/），或使用消息代理（Kafka/RabbitMQ）。禁止内部 HTTP/JSON。

阶段 5：输出架构清单

• 生成结构化 TOON 清单 microservices_manifest.toon 及配套的 docker-compose.yml。

---

决策规则

• 当 allowMonolith: false 时，任何生成单目录应用或共享数据库的尝试都将立即违反不变量。
• 每个内部东西向 RPC 服务接口都必须先通过严格的 .proto IDL 定义，然后才能实现客户端或服务端代码。
• 重度 CPU 计算绝不能在 Node.js 事件循环上运行；始终应路由到类别 C（Rust）或类别 D（Python）。
• 高吞吐量无状态消息流必须路由到类别 A（Go）分布式网络服务。
• 如果某个子服务需要管理数十万条持久 WebSocket 连接、实时消息编排或零停机容错，则自动选择类别 E：Elixir（Phoenix/LiveView）。
• 外部客户端绝不能直接调用内部东西向 gRPC 服务；所有客户端流量都必须经由 API Gateway。

---

不变量

• 任何维度 $\ge 7.0$ 或综合得分 $\ge 6.0$ 时，都禁止搭建单体架构。
• 强制采用微服务时，严格禁止服务间使用无类型的 HTTP/JSON 通信。
• 每个微服务都拥有自己的私有数据持久化层；禁止跨服务边界共享关系型数据表。
• 产品搭建开始前，必须先将架构清单序列化为有效的 TOON 格式。

---

故障分类

不当搭建单体架构

Agent 在规模或领域阈值已触发的情况下，仍尝试构建带有单体控制器的单一仓库。解决方案：硬拦截、拒绝目录结构，并触发 fable-architecture 重新拆分。

东西向传输降级

内部服务使用普通 HTTP/JSON REST 而非 gRPC 进行通信。解决方案：在 proto/ 中生成 .proto IDL 合约，并接入 gRPC 传输绑定。

CPU 导致事件循环饥饿

在 Node.js/TypeScript 中执行视频转码或重度加密运算。解决方案：将 CPU 密集型逻辑提取到专用的 Rust 类别 C 微服务中。

领域边界渗漏

多个业务领域直接访问同一数据库架构。解决方案：通过私有数据存储和 gRPC 接口强制实施服务边界。

---

反模式

• 当并发量 $\ge 50,000$ RPS 时，为了“保持简单”而生成单体。
• 所有服务共用一个 PostgreSQL 数据库，并使用跨域外键。
• 内部后端服务之间使用无类型的 HTTP/JSON 通信。
• 在 Go 或 TypeScript CRUD 服务中嵌入深度学习模型推理。
• 跳过 API 网关，直接向公共客户端暴露内部 gRPC 端口。

---

完成标准

• 已完成并记录 3-vector 评估，包含离散评分和综合评分。
• 已生成架构清单（microservices_manifest.toon），其中包含明确的服务表。
• 如果触发阈值，已建立单体锁定状态（allowMonolith: false）。
• 通信契约严格执行南北向 REST 与东西向 gRPC/代理的区分。
• 已为每个拆分出的服务分配专门的子 Agent 角色和多语言技术栈。

---

渐进式资源

• 向量评分指南：references/vector-scoring.md
• 技术栈矩阵：references/tech-stack-matrix.md
• 通信标准：references/communication-standards.md
• 子 Agent 角色分配：references/subagent-role-distribution.md
• 示例演练：examples/fintech-scale-walkthrough.md、examples/ai-media-pipeline-walkthrough.md
• 模板：templates/microservices-manifest.toon、templates/docker-compose.microservices.yml、templates/service-contract.proto
• 验证脚本：scripts/evaluate-architecture.py