RabbitMQ 设计与使用助手
触发条件
当用户出现以下意图时激活本 Skill：
- 设计 RabbitMQ 交换机 / 队列 / 绑定
- 消息路由规则设计
- 死信队列 / 延迟队列方案
- 消息可靠性（持久化/ACK/Confirm）设计
- 高可用镜像队列 / 仲裁队列设计
- "如何设计 xxx 的消息模型"
设计流程（Agent 执行路径）
0. 版本检查 → 加载 references/version-major.md 对比用户版本，识别废弃项和重大变更。同时加载所有 version-X.Y.md（X.Y ≤ 用户目标版本），后续设计过程中 Agent 从已加载的上下文中自主匹配深度特性
1. 需求分析 → 理解消息流、可靠性等级、吞吐量、消费者模型
2. 交换机设计 → 类型选择（Direct/Topic/Fanout/Headers）、命名规范
3. 队列设计 → 队列类型（Classic/Quorum/Stream）、持久化、参数
4. 绑定设计 → Routing Key 规范、通配符策略
5. 消费设计 → ACK 策略、Prefetch、并发、死信处理
6. 使用指引 → 加载 references/usage-guide.md，给出场景化操作
7. 生产建议 → 加载 references/best-practices.md，给出集群/高可用/监控建议
8. 模板参考 → 加载 references/patterns.md，匹配业务消息拓扑模板
快速参考
交换机类型速查
| 类型 | 路由逻辑 | 适用场景 | 示例 |
|---|---|---|---|
| Direct | Routing Key 精确匹配 | 单播/定向投递 | order.created → order_queue |
| Topic | Routing Key 通配符匹配（* 单段 / # 多段） |
多条件路由/发布订阅 | order.*.success |
| Fanout | 忽略 Routing Key，广播到所有绑定队列 | 广播/扇出 | 配置刷新通知 |
| Headers | 按 Header 属性匹配（x-match: all/any） |
属性路由 | 日志级别路由 |
队列类型速查
| 类型 | 可靠性 | 性能 | 适用场景 | 最低版本 |
|---|---|---|---|---|
| Quorum Queue | 高（Raft 共识） | 中 | 订单/支付/金融 | 3.8+ |
| Classic Queue (CQv2) | 中（可配镜像） | 高 | 通用消息/临时队列；懒加载自动落盘（原 Lazy Queue 行为） | 3.12+ 推荐 |
| Stream | 高（持久化+重放） | 高吞吐 | 事件溯源/日志/大数据 | 3.9+ |
消息可靠性速查
| 级别 | Producer | Broker | Consumer | 丢失风险 |
|---|---|---|---|---|
| 最低 | 不 Confirm | 内存/不持久化 | Auto ACK | 高 |
| 标准 | Publisher Confirm | Durable 队列 + Persistent 消息 | Manual ACK | 极低 |
| 最高 | Publisher Confirm | Quorum 队列 | Manual ACK + 重试 | 几乎为零 |
死信设计核心参数
| 参数 | 说明 |
|---|---|
x-dead-letter-exchange |
死信转发的目标交换机 |
x-dead-letter-routing-key |
死信转发的 Routing Key |
x-message-ttl |
消息 TTL（毫秒），超时转死信 |
x-max-length / x-max-length-bytes |
队列长度/字节上限 |
x-delivery-limit |
重试次数上限（Quorum Queue） |
Prefetch 设计
| 场景 | prefetch_count |
说明 |
|---|---|---|
| 低延迟 / 消息小 | 50-100 |
并发高 |
| 高延迟 / 消息大 | 1-10 |
公平分发 |
| 顺序处理 | 1 |
严格有序 |
渐进式加载
详细内容按需加载 references/：
| 主题 | 文件 | 何时加载 |
|---|---|---|
| 交换机/队列/绑定/消息设计规范 | references/design-spec.md |
Step 2-4 拓扑设计 |
| 场景化操作（创建/生产/消费/管理/迁移） | references/usage-guide.md |
Step 6 使用指引 |
| 最佳实践（高可用/可靠性/集群/监控/运维） | references/best-practices.md |
Step 7 生产建议 |
| 业务消息拓扑模板（5类业务完整设计） | references/patterns.md |
Step 8 模板参考 |
| 重大版本特性（废弃/依赖变更/新模块） | references/version-major.md |
Step 0 版本检查（模块激活时即加载） |
| 深度版本特性 — 4.x（AMQP 1.0/Khepri/MQTT 5.0/Stream过滤/延迟重试） | references/version-4.0.md |
Step 0 版本检查时自动加载（版本 ≤ 用户目标版本时） |
| 深度版本特性 — 3.x（CQv2/原生MQTT/Quorum Queue/Stream/OAuth 2） | references/version-3.0.md |
Step 0 版本检查时自动加载（版本 ≤ 用户目标版本时） |
版本参考文档启用规则
- 模块激活时 — 始终加载
references/version-major.md，Agent 需主动对比用户使用的 RabbitMQ 版本，若存在废弃项或重大变更，立即提示用户 - 深度特性 Step 0 自动加载 — 版本检查时加载所有 version-X.Y.md（X.Y ≤ 用户目标版本）。设计过程中 Agent 从已加载的上下文中自主检索匹配相关特性，用户无需指定版本号
- 深度特性按大版本拆分，小版本持续追加 — 如
version-4.0.md包含该大版本下所有小版本的设计级特性。更新时在文件中新增## X.Y.Z版本节即可，不单开文件
硬规则
- 设计规范内容来自权威资料（RabbitMQ 官方文档/社区最佳实践），不编造
- 消息必须持久化（Durable 队列 + Persistent delivery_mode），除临时队列外
- 必须设计死信策略（DLX + DLQ），不可让无法处理的消息无限重试或静默丢弃
- 必须启用 Publisher Confirm，关键业务不可仅依赖 Fire-and-Forget
- Consumer 必须使用 Manual ACK（
auto_ack=false），在业务处理成功后确认 - 队列命名格式：
<业务域>.<队列用途>[.<子类型>]，如order.created.notification - 生产环境不得使用 Fanout + 大量绑定，用 Topic 交换机替代
