@agentunion/fastaun-browser 0.5.4 → 0.5.8

package/_packed_docs/protocol/15-/347/246/273/347/272/277/346/216/250/351/200/201/351/200/232/347/237/245/345/215/217/350/256/256.md

@@ -1,421 +1,165 @@
-# 15 - 离线推送通知协议 (Push Notification)
-
-## 1. 概述
-
-当目标 AID 的所有设备均离线时，AUN Gateway 通过事件通知将推送摘要发送给 `push_notify_aid`（推送代理 AID），由其完成最终的平台推送（APNs / FCM / WebPush 等）。
-
-**设计原则：**
-
-- push_notify_aid 是普通客户端 AID，不是 AUN 内部服务
-- 通过事件通知（非 P2P 消息）下发推送摘要——轻量、实时、不持久化
-- push_token 对 Gateway 完全不透明（opaque），push_notify_aid 自签自验
-- 任意一台设备在线即不触发推送
-- 推送内容仅含元数据，不含消息正文（E2EE 安全保证）
-- 背压控制：串行确认，Gateway 等 push_notify_aid ack 后再发下一批
-- 跨域推送：推送由**目标 AID 所属域**的 Gateway 触发，发送方域不参与
-
----
-
-## 2. 架构
-
-```mermaid
-graph TB
-    Sender[发送方 AID] -->|message.send| GW[Gateway]
-    GW -->|目标全部离线| PA[PushAggregator]
-    PA -->|event/push.offline_message| GW
-    GW -->|事件通知| PNA[push_notify_aid<br/>推送代理客户端]
-    PNA -->|push.ack| GW
-    PNA -->|平台推送| PLATFORM[APNs / FCM / WebPush]
-    PLATFORM -->|通知| Target[目标终端]
-
-    PNA -.->|connect 到 Gateway 保持在线| GW
-```
-
-**关键约束：**
-
-- push_notify_aid 作为普通客户端 AID 连接到 Gateway，通过事件通知接收推送摘要
-- push_notify_aid 离线时事件丢弃——推送是 best-effort，消息可靠性由 message.pull 保证
-- 目标 AID 有任意一台设备在线时，不触发推送
-
----
-
-## 3. 推送注册流程
-
-### 3.1 应用层：客户端向推送代理注册
-
-```mermaid
-sequenceDiagram
-    participant App as 应用客户端
-    participant PNA as push_notify_aid
-
-    Note over App,PNA: 应用层行为，AUN 协议不规定细节
-    App->>PNA: 注册推送(aid, device_id, platform, device_token)
-    PNA->>PNA: 生成 push_token（格式自定）
-    PNA-->>App: push_token
-```
-
-push_token 的格式、签名算法、有效期完全由 push_notify_aid 自行决定。AUN 协议不做任何约束。
-
-### 3.2 协议层：connect 时携带推送配置
-
-```mermaid
-sequenceDiagram
-    participant C as Client
-    participant GW as Gateway
-
-    C->>GW: connect(aid, token, push_notify_aid, push_token)
-    GW->>GW: 认证 AID 身份 ✓
-    GW->>GW: 持久化 push_config
-    GW-->>C: connected
-```
-
----
-
-## 4. 离线推送时序
-
-```mermaid
-sequenceDiagram
-    participant A as Sender AID
-    participant GW as Gateway
-    participant PA as PushAggregator
-    participant PNA as push_notify_aid
-
-    A->>GW: message.send(to=B, payload=...)
-    GW->>GW: 持久化消息 + 查询 B 在线状态
-
-    alt B 有任意设备在线
-        GW->>GW: 投递到 B 的在线 session
-        Note over GW: 不触发推送
-    else B 全部设备离线
-        GW->>PA: enqueue(target=B, from=A, msg_id, ts)
-        PA->>PA: 聚合窗口 + 频控 + 背压检查
-
-        alt 触发推送 且 in_flight < max
-            PA->>GW: event/push.offline_message
-            GW->>PNA: 事件通知(batch_id, summary, push_token)
-            PA->>PA: in_flight++, 启动 ack_timeout
-            PNA->>PNA: 验证 push_token ✓ → 发送平台推送
-            PNA->>GW: push.ack(batch_id)
-            GW->>PA: release(batch_id)
-            PA->>PA: in_flight--
-        else in_flight = max（背压）
-            PA->>PA: 排队等待槽位释放
-        else 频控抑制
-            PA->>PA: 延迟到下一窗口
-        end
-    end
-
-    GW-->>A: ack(msg_id, seq)
-```
-
----
-
-## 5. 背压与 in-flight 控制
-
-```mermaid
-stateDiagram-v2
-    [*] --> Idle: 初始状态
-    Idle --> Sending: 有待推送 & in_flight < max
-    Sending --> WaitAck: 事件已发出, in_flight++
-    WaitAck --> Idle: 收到 push.ack, in_flight--
-    WaitAck --> Idle: ack_timeout 超时, in_flight--
-    WaitAck --> Queued: 新推送到达但 in_flight = max
-    Queued --> Sending: 槽位释放
-```
-
-### 参数
-
-| 参数 | 默认值 | 说明 |
-|------|--------|------|
-| max_in_flight | 1 | 同一 push_notify_aid 未确认批次上限（串行） |
-| ack_timeout | 30s | 超时未 ack 自动释放槽位 |
-| batch_size | 50 | 每批最多聚合多少个 target_aid 的通知 |
-
-### 行为规则
-
-- in_flight < max → 发送事件，in_flight++
-- in_flight = max → 排队等待
-- 收到 `push.ack(batch_id)` → in_flight--，触发队列中下一批
-- 超时 → in_flight--，**不重试**（推送是 best-effort，过时推送是噪音）
-- push_notify_aid 离线 → 事件丢弃，in_flight 不增加
-
----
-
-## 6. 在线判断规则
-
-```mermaid
-flowchart TD
-    A[消息到达，目标 AID = B] --> B{B 的在线设备数 > 0?}
-    B -->|≥ 1 台在线| C[投递到在线 session，不推送]
-    B -->|0 台在线| D{push_config 存在?}
-    D -->|是| F[进入 PushAggregator]
-    D -->|否| G[仅持久化，等对方上线 pull]
-    F --> H[聚合 + 频控 + 背压 → 推送]
-```
-
-**边界情况：**
-
-- 目标 AID 上线瞬间：清空该 AID 的聚合桶，取消待发推送
-- 最后一台设备断连：不立即触发推送，只有后续新消息到达时发现全离线才走推送路径
-
----
-
-## 7. 跨域推送
-
-**核心原则：推送由目标 AID 所属域的 Gateway 触发。**
-
-发送方域不感知目标域的 push_config 和白名单，也不需要任何跨域配置同步。
-
-```mermaid
-sequenceDiagram
-    participant A as alice.domain-a.com
-    participant GW_A as Gateway A
-    participant GW_B as Gateway B
-    participant PA_B as PushAggregator B
-    participant PNA as push.domain-b.com<br/>(连在 GW_B)
-
-    A->>GW_A: message.send(to=bob.domain-b.com)
-    GW_A->>GW_A: 持久化消息
-    GW_A->>GW_B: 跨域 relay 消息
-    GW_B->>GW_B: 查询 bob 本地在线状态
-
-    alt bob 在本域有设备在线
-        GW_B->>GW_B: 投递到 bob 的在线 session
-    else bob 本域全部离线
-        GW_B->>PA_B: enqueue(target=bob, from=alice.domain-a.com)
-        PA_B->>GW_B: event/push.offline_message
-        GW_B->>PNA: 事件通知
-        PNA->>GW_B: push.ack
-    end
-
-    GW_B-->>GW_A: relay ack
-    GW_A-->>A: ack
-```
-
-**规则：**
-
-| 关注点 | 行为 |
-|--------|------|
-| 推送配置存储 | 仅存于目标 AID 所属域，不跨域同步 |
-| 白名单管理 | 各域独立配置 `allowed_notify_aids`，互不影响 |
-| push_notify_aid 必须连接位置 | 目标 AID 所属域的 Gateway |
-| push_notify_aid 跨域时 | 不支持。push_notify_aid 必须与其服务的 AID 同域 |
-| summary.senders 中的跨域 AID | 保留完整 AID（含域名），如 `alice.domain-a.com` |
-
-**约束：** push_notify_aid 必须与其服务的目标 AID 处于同一域。如果应用希望在多个域提供推送服务，需要在每个域部署独立的 push_notify_aid 并分别加入白名单。
-
----
-
-## 8. 聚合与频控
-
-### 8.1 PushAggregator 数据结构
-
-每个离线目标 AID 一个聚合桶：
-
-```
-bucket[target_aid] = {
-    push_notify_aid: "push.myapp.com",
-    push_token: "eyJhb...",
-    pending: [{from, msg_id, ts}, ...],
-    first_enqueue_ts: timestamp,
-    last_push_ts: timestamp,
-}
-```
-
-### 8.2 去重规则
-
-同一 target_aid 在频控窗口内只产生一次推送通知。具体行为：
-
-- 首条消息触发推送后，该 target_aid 进入频控冷却期（默认 60s）
-- 冷却期内新消息只更新聚合桶的 summary（unread_count++、senders 去重追加），不产生新推送
-- 冷却期结束时，若桶内有新增未推送内容，合并为一条推送发出
-
-效果：无论短时间内收到多少条消息，target_aid 最多每 60s 收到一次推送通知，且 summary 是累积聚合的。
-
-### 8.3 触发规则
-
-| 规则 | 说明 | 默认值 |
-|------|------|--------|
-| 首条即推 | 桶为空且不在冷却期时，第一条消息立即触发 | 开启 |
-| 窗口聚合 | 首条之后的消息等待窗口合并 | 5 秒 |
-| 数量上限 | 桶内积累 N 条立即触发（不等窗口） | 20 条 |
-
-### 8.4 频控规则
-
-| 维度 | 限制 | 说明 |
-|------|------|------|
-| 同一 target_aid | 60 秒内最多 1 次推送 | 避免终端刷屏 |
-| 同一 push_notify_aid | 1000 次/分钟 | 保护推送代理服务 |
-| 全局 | 5000 次/分钟 | 系统保护 |
-
-频控被触发时消息不丢弃，等窗口过后下一次聚合时一并推送。
-
----
-
-## 9. 协议字段
-
-### 9.1 connect 扩展字段
-
-```json
-{
-  "method": "auth.login",
-  "params": {
-    "aid": "bob.example.com",
-    "challenge_response": "...",
-    "push_notify_aid": "push.myapp.com",
-    "push_token": "eyJhbGciOiJIUzI1NiJ9..."
-  }
-}
-```
-
-- `push_notify_aid` 和 `push_token` 均为可选字段
-- 两者必须同时提供或同时不提供
-- 不提供 = 不需要离线推送
-- 每次 connect 覆盖写（最新连接为准）
-
-### 9.2 事件通知格式
-
-Gateway 向 push_notify_aid 下发的事件通知：
-
-```json
-{
-  "method": "event/push.offline_message",
-  "params": {
-    "batch_id": "uuid-xxx",
-    "items": [
-      {
-        "target_aid": "bob.example.com",
-        "push_token": "eyJhbGciOiJIUzI1NiJ9...",
-        "summary": {
-          "unread_count": 3,
-          "senders": ["alice.example.com", "charlie.example.com"],
-          "latest_ts": 1716100005,
-          "group_ids": ["g-abc123.agentid.pub"]
-        }
-      }
-    ]
-  }
-}
-```
-
-**安全约束：** 不包含消息正文。E2EE 场景下 Gateway 无法解密，推送代理只需知道"有 N 条未读来自谁"即可构造推送文案。
-
-### 9.3 push.ack RPC
-
-push_notify_aid 处理完一批推送后回调确认：
-
-```json
-{
-  "method": "push.ack",
-  "params": {
-    "batch_id": "uuid-xxx"
-  }
-}
-```
-
-Gateway 收到后释放 in-flight 槽位，触发下一批。
-
-### 9.4 push.update_config RPC（可选）
-
-允许客户端在不重连的情况下更新推送配置：
-
-```json
-{
-  "method": "push.update_config",
-  "params": {
-    "push_notify_aid": "push.myapp.com",
-    "push_token": "new-token..."
-  }
-}
-```
-
----
-
-## 10. push_token 鉴权模型
-
-### 10.1 push_notify_aid 白名单
-
-Gateway 配置允许的 push_notify_aid 白名单，只有白名单内的 AID 才能被设置为推送代理：
-
-- 客户端 connect 时携带的 `push_notify_aid` 不在白名单内 → 忽略该字段，不报错，不存储
-- 白名单为空 → 禁用推送功能
-- 白名单配置在 Gateway 启动配置中，运行时不可动态修改
-
-```json
-{
-  "push": {
-    "allowed_notify_aids": [
-      "push.myapp.com",
-      "push.partner.com"
-    ]
-  }
-}
-```
-
-### 10.2 token 透传模型
-
-```mermaid
-sequenceDiagram
-    participant PNA as push_notify_aid
-    participant GW as Gateway
-
-    Note over PNA,GW: push_token 生命周期
-    PNA->>PNA: 签发 push_token（格式/算法自定）
-    Note over GW: Gateway 存储 push_token（opaque bytes）
-    Note over GW: 不验签、不解析、不判断过期
-    GW->>PNA: event/push.offline_message(..., push_token="xxx")
-    PNA->>PNA: 自己验签 push_token
-    alt token 有效
-        PNA->>PNA: 执行推送
-        PNA->>GW: push.ack(batch_id)
-    else token 无效/过期
-        PNA->>PNA: 丢弃
-        PNA->>GW: push.ack(batch_id)
-        Note over PNA: 客户端下次 connect 带新 token
-    end
-```
-
-**职责划分：**
-
-| 角色 | 职责 |
-|------|------|
-| push_notify_aid | 签发 token、验证 token、决定格式和有效期、处理后 ack |
-| Gateway | 存储 token、透传 token、不解析不验证、管理 in-flight |
-| Client | 向 push_notify_aid 申请 token、connect 时携带 |
-
----
-
-## 11. 持久化
-
-### push_config 表
-
-```sql
-CREATE TABLE push_config (
-    aid VARCHAR(255) PRIMARY KEY,
-    push_notify_aid VARCHAR(255) NOT NULL,
-    push_token TEXT NOT NULL,
-    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
-);
-```
-
-- 随 connect 写入/更新（UPSERT）
-- 可加内存缓存（TTL 5 分钟）
-
----
-
-## 12. 边界情况
-
-| 场景 | 处理 |
-|------|------|
-| push_notify_aid 离线 | 事件丢弃，不持久化。推送是 best-effort，消息可靠性由 pull 保证 |
-| 目标 AID 未配置推送 | 不推送，消息正常持久化等对方上线 pull |
-| 目标 AID 上线瞬间 | 清空聚合桶，取消待发推送 |
-| E2EE 消息 | 推送内容只含元数据（发送者、数量），不含密文 |
-| 群组消息 | 群内每个离线成员独立聚合，summary 含 group_ids |
-| push_token 过期 | push_notify_aid 丢弃但仍 ack，客户端下次 connect 刷新 token |
-| ack 超时 | 释放槽位，不重试。后续新消息触发新批次时会包含累积通知 |
-| 同一 AID 多设备不同推送配置 | 以最后一次 connect 为准（单条记录覆盖） |
-| 跨域消息推送 | 由目标 AID 所属域的 Gateway 触发，发送方域不参与 |
-| push_notify_aid 跨域 | 不支持，必须与目标 AID 同域 |
-
-
+# 15 - 离线推送通知协议（Push Notification）
+
+## 1. 目标与权威依据
+
+当可靠消息的目标安装没有 AUN 长连接时，Push Service 向该安装登记的 Push Server 发送不含消息正文的唤醒事件。终端收到外部平台通知后重新连接，并通过原有 `message.pull` / `group.pull` 获取真实消息。
+
+本章描述对外协议。冲突时按以下顺序解释：
+
+1. `docs/superpowers/契约冻结-v3-to-v4.md`
+2. `docs/superpowers/specs/2026-07-24-push-service-design-v3.md`
+3. 本文档
+
+V1 使用独立 Go Push Service、单可用 Gateway、单 Push Service 实例和批次级 ACK。`push.offline_message` 不经 federation 转发；明文 token 仅允许隔离 PoC。
+
+## 2. 术语与职责
+
+| 名称 | 含义 |
+| --- | --- |
+| `push_notify_aid` | 应用和 SDK 使用的推送代理 AID 名称 |
+| `push_server_aid` | `push.register` 线上 RPC 的冻结字段；与 `push_notify_aid` 指向同一角色 |
+| Push Server | 普通 AUN 客户端，验证 opaque token、调用 APNs/FCM/WebPush，并按 delivery 幂等处理 |
+| Push Service | 保存 registration、candidate、delivery、batch 和频控状态，负责调度、投递、ACK、重试与恢复 |
+| Gateway | 注入可信身份、路由 `push.*`、查询长连接 Session、定向投递事件；不保存 registration、不解析 token |
+
+Message/Group 只在消息形成可靠事实后异步提交候选。推送失败不得反向改变消息发送成功语义。
+
+## 3. 安装登记与注销
+
+### 3.1 Python SDK 推荐入口
+
+应用启动时在 `connect()` 中携带 `push_notify_aid` 和 `push_token`：
+
+```python
+await client.connect({
+    "push_notify_aid": "push.example.com",
+    "push_token": token,
+})
+```
+
+这是 SDK 便利语义，不是 `auth.connect` 协议扩展。Python SDK 先建立 AUN 会话，再把 `push_notify_aid` 映射为 `push_server_aid` 调用 `push.register`；字段不会进入认证握手，也不会保存在可公开读取的 session options 中。登记失败时本次 `connect()` 回滚并抛错。
+
+本轮只修改 Python SDK。Go、TypeScript、JavaScript 尚无专用 Push facade 或 connect 自动登记。
+
+### 3.2 运行期变更
+
+应用无需断开连接即可更新或注销当前安装：
+
+```python
+await client.push.register(push_notify_aid="push.example.com", push_token=new_token)
+await client.push.unregister()
+```
+
+`register()` 可附带 `provider`、`app_id` 诊断字段。`unregister()` 幂等禁用当前 `(aid, device_id, slot_id)`，不删除历史 delivery。
+
+### 3.3 `push.register`
+
+| 项目 | 契约 |
+| --- | --- |
+| 请求 | `push_server_aid`、`push_token`；可选 `provider`、`app_id` |
+| 可信安装 | 只取 Gateway 注入的 `_auth.aid/device_id/slot_id` |
+| 成功结果 | `registration_id`、`registration_version` |
+| 更新语义 | 同一安装 UPSERT，version 递增并重新启用 |
+| 校验 | Push Server 白名单、同域约束、字段类型和 token 长度 |
+
+请求体不得自报或覆盖 AID、device、slot、connection ID 等可信身份字段。
+
+### 3.4 `push.unregister`
+
+请求无业务参数。Push Service 根据 `_auth.aid/device_id/slot_id` 禁用当前安装；已禁用或不存在仍返回幂等成功 `status=disabled`。
+
+## 4. 主链路
+
+1. 终端登记当前安装的 Push Server 和 opaque token。
+2. Message/Group 在消息持久化成功后异步调用 `push.enqueue`。
+3. Push Service 等待离线宽限期，再调用 `gateway.query_sessions(long_only=true)` 复核目标 AID。
+4. 任一目标长连接在线时抑制候选；查询错误、超时或非法响应视为“未知”，不得推断离线。
+5. 确认离线后，Push Service 为每条有效 installation registration 生成稳定 delivery。
+6. Scheduler 按 Push Server、目标、公平性、频控、batch 数量和事件字节上限构建批次。
+7. Push Service 选择 Push Server 最早建立的确定长连接，定向投递 `push.offline_message`。
+8. Push Server 按 `delivery_id` 幂等执行平台推送，并用 `push.ack` 返回批次结果。
+
+短连接不抑制离线推送，也不能承载 `push.offline_message`。
+
+## 5. 候选与可靠性边界
+
+`push.enqueue` 仅允许 Gateway 注入 `_caller_id=message` 或 `group`。候选 ID 由版本、kind、消息标识、目标 AID 和可选 group ID 规范化后计算 SHA-256。
+
+- 数据库提交成功后才能返回 `accepted`。
+- 相同 candidate ID 和相同不可变内容返回 `duplicate`。
+- 相同 ID 但内容冲突必须返回冲突错误。
+- 生产者临时调用失败时保留同一队列项并退避，直到 accepted、duplicate 或 TTL 到期。
+- 队列满、进程在确认前崩溃或 TTL 到期允许丢失唤醒提示，但必须记录指标和诊断；真实消息仍可 pull。
+
+## 6. `push.offline_message`
+
+事件名为 `push.offline_message`，一个 batch 只属于一个 Push Server，并固定定向到一个长连接 `connection_id`。`federation_forward=false`。
+
+批次字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `protocol_version` | V1 固定为字符串 `1` |
+| `batch_id` | 64 位十六进制稳定标识 |
+| `expires_at_ms` | 批次最早过期时间 |
+| `items` | 1 到配置上限条 installation delivery |
+
+item 字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `delivery_id` | Push Server 幂等键；重试期间保持不变 |
+| `target_aid` | 需要唤醒的目标 AID |
+| `device_id` / `slot_id` | 目标安装身份 |
+| `push_token` | Push Server 自签自验的 opaque token |
+| `category` | 候选类型，如 `message` 或 `group` |
+| `new_count` | 本批新增提示计数 |
+| `latest_at_ms` | 最新候选发生时间 |
+
+事件不得包含消息正文、E2EE 密文、发送者隐私数据、证书私钥或其他身份材料。
+
+## 7. Push Server 处理规则
+
+- 必须先校验协议版本、batch 过期时间和 item 结构。
+- 必须验证自己的 opaque token；Gateway 和 Push Service 不解析 token 业务内容。
+- 必须按 `delivery_id` 幂等。重复事件不得重复产生不可逆平台副作用，但仍需重新 ACK。
+- 普通终端不订阅该事件；只有承担 Push Server 角色的客户端处理。
+
+Python Mock Push Server 使用修改后的 Python SDK 接收事件和调用 `client.push.ack()`，仅用于隔离测试，不代表生产 APNs/FCM 适配实现。
+
+## 8. `push.ack`
+
+请求字段为 `batch_id` 和批次级 `status`。V1 只允许：
+
+| status | 结果 |
+| --- | --- |
+| `accepted` | 批次内 delivery 进入 accepted |
+| `retryable_failure` | 未超重试上限的 delivery 回到 pending 并退避 |
+| `permanent_failure` | 批次内 delivery 进入 permanent_failed |
+
+成功响应的 `status` 为 `applied`、`duplicate` 或 `stale`。ACK 只信任 `_auth.aid`，必须与 batch owner 一致；它只能影响创建 batch 时冻结的 membership。
+
+ACK timeout、响应丢失、dispatch 结果未知和进程重启都由持久状态机恢复。V1 不提供逐 delivery ACK。
+
+## 9. 在线判断、聚合与容量
+
+- 在线复核只看 `long_only=true` 的 Session。
+- Push Server 多长连接时，按 `(created_at_ms ASC, connection_id ASC)` 选择第一个。
+- registration TTL、candidate TTL、离线宽限、聚合窗口、目标 cooldown、Push Server/全局频控、batch 数量、事件字节上限和每 Server 最大并行 batch 均是运行约束。
+- 数据库是恢复真源；内存只能缓存热状态，不能单独决定 timeout、重试或恢复。
+- 同一 Push Server 和不同 Push Server 之间都必须避免长期饥饿。
+
+## 10. 安全、域与发布边界
+
+- Push Server 必须在所属域的允许列表中，且与目标 registration 同域。
+- token 只允许记录不可逆短指纹，不得出现在日志、指标、错误或诊断响应中。
+- 生产环境必须使用可信 token 加密和密钥管理；当前明文模式只能用于隔离 PoC。
+- `push.offline_message` V1 不跨 federation；跨域 E2E 尚未作为完成项验收。
+- 测试不得创建、删除、清空或重建既有 AID 身份、数据库和固定 Push Server 材料。
+
+## 11. 实现状态
+
+- Push Service、Gateway 路由、Message/Group 候选链和 Python SDK/Mock Push Server 已按冻结契约实现。
+- Python SDK 提供 `connect()` 自动登记和 `client.push.register/unregister/ack`。
+- Go、TypeScript、JavaScript SDK 本轮未修改；文档不得宣称其已有专用 Push facade。
+- 生产发布仍受 token 加密硬门阻断；运行和回滚要求见 `docs/AUN离线推送服务运维与发布指南.md`。

package/_packed_docs/protocol/README.md

@@ -42,6 +42,7 @@ AUN 是 ACP 协议的 2.0 版本，采用 WebSocket + JSON-RPC 2.0 定义 Agent
 | [08-AUN-E2EE.md](08-AUN-E2EE.md) | Legacy P2P E2EE 信封说明；当前默认主路径见 SDK V2 多设备 wrap 文档 |
 | [08-AUN-E2EE-Group.md](08-AUN-E2EE-Group.md) | 群组 E2EE V2：消息级密钥、逐设备密钥包裹、成员状态签名验证 |
 | [10-Group-子协议.md](10-Group-子协议.md) | `group.*` 群组管理、群消息、`group.index` 签名索引、`_meta.group_indexes` 和 CAS 更新 |
+| [13-Agent行为规范.md](13-Agent行为规范.md) | Agent 自主模式、收发方响应义务、群 `mention_mode` 与 channel 过滤边界 |
 | [16-系统目录保护方案.md](16-系统目录保护方案.md) | `memberdata` 与 `group_data` 的系统目录保护、`group_data` 目录树隐藏与读下载/写保护边界、Group FS 授权路径和配额归属 |
 
 ### 附录

package/_packed_docs/protocol/aun-docs-guide.md

@@ -18,10 +18,12 @@ AUN 协议采用**主协议 + 子协议**架构：
 ├── 04-Peer-子协议.md          ← peer.* 对等认证
 └── 05-Relay-子协议.md         ← relay.* 中继传输
 
-业务层与公共基础
-├── 06-服务协议.md             ← message/meta/search/task + 跨域消息路由
-├── 07-错误码与状态机.md       ← 错误码汇总、状态机
-└── 08-AUN-E2EE.md               ← Legacy P2P E2EE 信封；当前主路径见 SDK E2EE V2 文档
+业务层与公共基础
+├── 06-服务协议.md             ← message/meta/search/task + 跨域消息路由
+├── 07-错误码与状态机.md       ← 错误码汇总、状态机
+├── 08-AUN-E2EE.md             ← Legacy P2P E2EE 信封；当前主路径见 SDK E2EE V2 文档
+├── 10-Group-子协议.md         ← 群组协议与 mention_mode
+└── 13-Agent行为规范.md        ← Agent 自主模式与 channel 过滤边界
 ```
 
 ## 渐进式查阅流程
@@ -43,6 +45,7 @@ AUN 协议采用**主协议 + 子协议**架构：
 | Relay 中继 | 05-Relay-子协议.md |
 | 消息收发、搜索、任务 | 06-服务协议.md |
 | 群组、group.index 签名索引和 CAS | 10-Group-子协议.md |
+| 群提及过滤 mention_mode、Agent 自主行为与响应义务 | 10-Group-子协议.md、13-Agent行为规范.md |
 | 错误码和状态机 | 07-错误码与状态机.md |
 | E2EE 加密 | ../sdk/E2EE_V2消息通信时序图.md / 08-AUN-E2EE-Group.md；旧信封查 08-AUN-E2EE.md |
 | 安全威胁和防护 | 09-安全考虑.md |