$mq9.AI.* 协议设计文档
概述
$mq9.AI.* 是 mq9 为 Agent 异步通信设计的协议。核心解决的问题：Agent 之间的异步通信，发件方和收件方不需要同时在线。
mq9 只解决通信问题——消息怎么可靠送达。至于消息里装什么、怎么用、业务语义是什么，mq9 不管。消息内容是 byte 数组，不解析、不校验、不限制。
基础概念
mail_id：通过 MAILBOX.CREATE 创建邮箱时返回的通信地址。不绑定 Agent 身份，一个 Agent 可以为不同任务申请不同的 mail_id。用完不管，TTL 自动清理。
私有邮箱的 mail_id 由系统生成，不可猜测。公开邮箱的 mail_id 由用户自定义，有意义的名字——task.queue、analytics.result。
mail_id 不可猜测即安全边界。 知道 mail_id 就能发消息、能订阅。不知道 mail_id 就无从操作。没有 token，没有 ACL。
TTL：邮箱创建时声明，到期自动销毁，消息随之清理。CREATE 幂等，重复创建同一邮箱不报错，TTL 以第一次创建为准。
priority：可选。不指定为 normal 默认优先级，指定 urgent 或 critical 可提升处理顺序。同优先级 FIFO，跨优先级高优先处理。存储层保证顺序，消费方无需自行排序。
msg_id：每条消息的唯一标识，客户端用于去重。
订阅语义：每次订阅全量推送所有未过期消息，后续新消息实时推送。不区分已读/未读，不追踪消费位点。服务端零消费状态。
消息流程：消息到达 → 写存储 → 在线则实时推送，不在线则等待 → 订阅者上线时全量推送所有未过期消息。
协议总览
| Subject | 方向 | 持久化 | 说明 |
|---|---|---|---|
$mq9.AI.MAILBOX.CREATE | PUB | — | 创建邮箱 |
$mq9.AI.MAILBOX.MSG.{mail_id} | PUB/SUB | 是 | 发消息/接收消息，normal 优先级 |
$mq9.AI.MAILBOX.MSG.{mail_id}.urgent | PUB/SUB | 是 | 紧急消息 |
$mq9.AI.MAILBOX.MSG.{mail_id}.critical | PUB/SUB | 是 | 最高优先级消息 |
$mq9.AI.MAILBOX.LIST.{mail_id} | PUB | — | 查看邮箱当前内容 |
$mq9.AI.MAILBOX.DELETE.{mail_id}.{msg_id} | PUB | — | 删除指定消息 |
$mq9.AI.MAILBOX.CREATE
创建邮箱。私有邮箱 mail_id 系统生成，公开邮箱 mail_id 用户自定义。
创建私有邮箱
nats pub '$mq9.AI.MAILBOX.CREATE' '{"ttl": 3600}'
# 响应
{"mail_id": "m-uuid-001"}创建公开邮箱
nats pub '$mq9.AI.MAILBOX.CREATE' '{
"ttl": 3600,
"public": true,
"name": "task.queue",
"desc": "任务队列"
}'
# 响应
{"mail_id": "task.queue"}public: true 的邮箱创建后 mail_id 对外可见，TTL 到期自动移除。
CREATE 是幂等的。邮箱已存在则静默返回成功，TTL 以第一次创建为准。
$mq9.AI.MAILBOX.MSG.
消息通道。同一个 subject，PUB 发消息，SUB 接收消息。
发消息
知道 mail_id 即可发送，无需任何授权。
# normal 优先级，大多数场景直接用这个
nats pub '$mq9.AI.MAILBOX.MSG.{mail_id}' 'payload'
# 需要优先处理时，显式指定
nats pub '$mq9.AI.MAILBOX.MSG.{mail_id}.urgent' 'payload'
nats pub '$mq9.AI.MAILBOX.MSG.{mail_id}.critical' 'payload'priority
| 值 | 语义 | 典型场景 |
|---|---|---|
| 不指定（normal） | 默认，大多数消息 | 任务分发、结果返回、状态上报 |
| urgent | 紧急，优先处理 | 审批请求、重要通知 |
| critical | 最高优先级 | 任务中断、紧急指令 |
消息内容是 byte 数组，mq9 不解析、不校验、不限制格式。用户传什么，mq9 原样存储和投递。
接收消息
# 订阅所有消息（normal + urgent + critical）
nats sub '$mq9.AI.MAILBOX.MSG.{mail_id}'
nats sub '$mq9.AI.MAILBOX.MSG.{mail_id}.>'
# 仅订阅最高优先级
nats sub '$mq9.AI.MAILBOX.MSG.{mail_id}.critical'
# 竞争消费
nats sub '$mq9.AI.MAILBOX.MSG.{mail_id}.>' --queue workers订阅即全量推送——所有未过期消息立即推送，后续新消息实时推送。
竞争消费——多个订阅者可以用 queue group 竞争消费，每条消息只被一个订阅者处理：
nats sub '$mq9.AI.MAILBOX.MSG.{mail_id}.>' --queue workers禁止的操作：
nats sub '$mq9.AI.MAILBOX.MSG.*' # 禁止，broker 拒绝
nats sub '$mq9.AI.MAILBOX.MSG.#' # 禁止，broker 拒绝订阅必须精确到 mail_id，不允许通配符订阅所有邮箱。
$mq9.AI.MAILBOX.LIST.
查看邮箱当前存储的所有消息，不影响订阅推送。request/reply 模式，PUB 请求，server 返回快照。
nats request '$mq9.AI.MAILBOX.LIST.{mail_id}' ''
# 响应
{
"mail_id": "m-uuid-001",
"messages": [
{"msg_id": "msg-001", "priority": "critical", "ts": 1234567890},
{"msg_id": "msg-002", "priority": "urgent", "ts": 1234567891},
{"msg_id": "msg-003", "priority": "normal", "ts": 1234567892}
]
}$mq9.AI.MAILBOX.DELETE.{mail_id}.
删除邮箱中的指定消息。已处理的消息可以显式清理，保持邮箱干净。
nats pub '$mq9.AI.MAILBOX.DELETE.{mail_id}.{msg_id}' ''
# 响应
{"deleted": true}公开邮箱
公开邮箱没有独立的发现机制。mail_id 由用户自定义为有意义的名字——task.queue、analytics.result——知道名字直接订阅即可：
nats sub '$mq9.AI.MAILBOX.MSG.task.queue.>'创建时指定 public: true 和自定义名字：
nats pub '$mq9.AI.MAILBOX.CREATE' '{
"ttl": 3600,
"public": true,
"name": "task.queue",
"desc": "任务队列"
}'
# 响应
{"mail_id": "task.queue"}公开邮箱和私有邮箱的区别只在于 mail_id 是否可预测，通信机制完全一致。