@agentunion/fastaun-browser 0.5.0 → 0.5.2

package/_packed_docs/cli/CLI/346/211/213/345/206/214.md

@@ -0,0 +1,331 @@
+# AUN CLI 手册
+
+## 位置与入口
+
+AUN CLI 是 Python SDK 的命令行工具，源码位于：
+
+```text
+D:\modelunion\kite\aun-sdk-core\python\src\aun_cli
+```
+
+仓库内相对路径为 `python/src/aun_cli`。安装入口在 `python/pyproject.toml`：
+
+```toml
+[project.scripts]
+aun = "aun_cli.main:app"
+```
+
+开发环境可直接运行：
+
+```powershell
+cd D:\modelunion\kite\aun-sdk-core\python
+pip install -e .
+aun --help
+```
+
+也可以不安装包，直接指定 `PYTHONPATH`：
+
+```powershell
+$env:PYTHONPATH="D:\modelunion\kite\aun-sdk-core\python\src"
+python -m aun_cli --help
+```
+
+## 全局用法
+
+```text
+aun [全局选项] <command> [参数]
+```
+
+全局选项：
+
+| 选项 | 说明 |
+|------|------|
+| `--profile, -p` | 仅本次命令使用指定 profile |
+| `--json` | 输出 JSON，适合脚本 |
+| `--debug` | 启用 debug 日志 |
+| `--no-color` | 禁用彩色输出 |
+| `--timeout, -t` | 操作超时秒数，默认 30 |
+| `--version, -V` | 显示版本 |
+| `--install-completion` | 安装当前 shell 的补全脚本，Typer 自动提供 |
+| `--show-completion` | 输出补全脚本，Typer 自动提供 |
+| `--help` | 显示帮助 |
+
+CLI 不提供 `--gateway` 选项；Gateway 发现由 SDK 处理。
+
+非 JSON 模式会先打印当前 `profile`、`aid`、`active_group` 和 `trace`，命令结束时可能输出 RPC summary。脚本里建议使用 `--json`。
+
+## 配置与 Profile
+
+默认配置文件为 `~/.aun/cli.toml`。常用命令：
+
+```powershell
+aun profile create dev --aid alice.agentid.pub
+aun profile switch dev
+aun profile current
+aun profile list
+
+aun config set timeout 60
+aun config get timeout
+aun config list
+```
+
+`profile` 也挂在 `config` 下，`aun config profile list/current/create/switch` 与根级 `aun profile ...` 使用同一套实现。
+
+当前 profile 的核心字段：
+
+| 字段 | 说明 |
+|------|------|
+| `aid` | 默认操作身份 |
+| `aun_path` | 本地身份、密钥、日志等数据目录 |
+| `active_group` | 默认群组；值使用目标态 `group_aid`，省略 `group_id` 兼容参数时使用 |
+| `debug` / `trace` / `timeout` | 调试、trace 和超时配置 |
+
+有效 profile 选择顺序：
+
+```text
+--profile > AUN_PROFILE > 当前终端标签页状态 > default.profile
+```
+
+## 身份命令
+
+| 命令 | 用法 |
+|------|------|
+| `aun register <aid>` | 注册新 AID，并写入当前 profile |
+| `aun login [aid]` | 加载本地身份、认证并连接一次 |
+| `aun whoami` | 查看当前 profile / AID / 数据目录 |
+| `aun identity list` | 列出本地身份 |
+| `aun identity check <aid>` | 检查本地身份材料和远端注册状态 |
+
+示例：
+
+```powershell
+aun register alice.agentid.pub
+aun login alice.agentid.pub
+aun whoami
+aun identity check alice.agentid.pub
+```
+
+## P2P 消息命令
+
+| 命令 | 用法 |
+|------|------|
+| `aun send <target-aid> <message>` | 发送 P2P 消息，默认加密 |
+| `aun send <target-aid> -` | 从 stdin 读取消息 |
+| `aun pull [--from aid] [--limit N] [--after-seq N]` | 拉取离线消息 |
+| `aun ack <sender-aid> --seq N` | 确认消息 seq |
+| `aun listen [--from aid] [--group group_id]` | 实时监听 P2P 和群消息；`group_id` 是兼容参数名，值使用 `group_aid` |
+
+示例：
+
+```powershell
+aun send bob.agentid.pub "hello"
+Get-Content .\msg.txt | aun send bob.agentid.pub -
+aun pull --limit 20
+aun listen --from bob.agentid.pub
+```
+
+## 群组命令
+
+| 命令 | 用法 |
+|------|------|
+| `aun group create <name> [--members a,b] [--group-name name]` | 创建群；成功后自动设为 active group |
+| `aun group use <group-id>` | 设置当前 active group |
+| `aun group current` | 查看当前 active group |
+| `aun group send [group-id] <message>` | 发送群消息；省略 group-id 时使用 active group |
+| `aun group list` | 列出已加入群 |
+| `aun group info [group-id]` | 查看群详情 |
+| `aun group members [group-id]` | 查看成员 |
+| `aun group invite [group-id] <aid...>` | 邀请成员 |
+| `aun group add-member [group-id] <aid> [--role member|admin]` | 直接添加成员 |
+| `aun group kick [group-id] <aid>` | 移除成员 |
+| `aun group leave [group-id]` | 退出群 |
+| `aun group dissolve [group-id]` | 解散群 |
+| `aun group bind [group-id] [--group-name name]` | 为匿名群补齐 group_aid；`bind-aid` 是公开别名 |
+| `aun group transfer [group-id] <new-owner>` | 转移群主 |
+| `aun group complete-transfer [group-id]` | 完成转让后的 group.fs rekey |
+
+`aun group add_member` 是 `aun group add-member` 的公开兼容别名。
+
+示例：
+
+```powershell
+aun group create "项目讨论组" --members bob.agentid.pub,carol.agentid.pub
+aun group current
+aun group send "大家好"
+aun group members
+aun group add-member dave.agentid.pub --role member
+```
+
+## 群文件系统命令
+
+`aun group fs` 对应 `group.fs.*` 和 SDK `client.group.fs`。裸路径使用当前 active group；完整 group path 也可直接传入。
+
+| 命令 | 用法 |
+|------|------|
+| `aun group fs ls [path] [-l]` | 列出目录 |
+| `aun group fs find [path] [--name "*.md"] [--type f]` | 查找节点 |
+| `aun group fs stat <path>` | 查看节点 |
+| `aun group fs lstat <path>` | 查看链接本身 |
+| `aun group fs mkdir <path> [-p]` | 创建目录 |
+| `aun group fs rm <path> [-r] [--force]` | 删除节点 |
+| `aun group fs cp <src> <dst> [-r] [--force]` | 上传、下载或远程复制 |
+| `aun group fs mv <src> <dst> [--force]` | 远程移动 |
+| `aun group fs df [path]` | 查看用量 |
+| `aun group fs setfacl <path> -m role:admin:<perms>` | 群主授予群自有区 admin 角色 ACL |
+| `aun group fs setfacl <path> -x role:admin` | 群主撤销群自有区 admin 角色 ACL |
+| `aun group fs getfacl <path>` | 查看群自有区角色 ACL |
+| `aun group fs mount <path> [--readonly/--readwrite]` | 挂载成员数据区 |
+| `aun group fs umount <path>` | 卸载成员数据区 |
+
+示例：
+
+```powershell
+aun group fs mkdir /docs -p
+aun group fs cp .\README.md /docs/README.md
+aun group fs ls /docs -l
+aun group fs setfacl /docs -m role:admin:rwx
+aun group fs getfacl /docs
+aun group fs cp /docs/README.md .\downloaded.md
+```
+
+群自有区写入需要使用当前 `group_identity` 对应的 `group_aid` 身份签名时，可通过 `--as <group-aid>` 指定操作者。`setfacl/getfacl` 只允许当前 group owner 调用；当前只支持 `role:admin` 角色 ACL，权限位对外显示为 POSIX 视图 `rwx`。
+
+## Storage VFS 命令
+
+`aun fs` 是普通 Storage VFS 入口，路径格式为 `<AID>:/path`。裸路径自动使用当前 profile AID。
+
+| 命令 | 用法 |
+|------|------|
+| `aun fs ls <path> [-l]` | 列目录 |
+| `aun fs stat <path> [-L]` | 查看节点，`-L` 跟随链接 |
+| `aun fs cat <path>` | 输出文件内容 |
+| `aun fs cp <src> <dst>` | 本地/远程上传下载或远程复制 |
+| `aun fs mv <src> <dst>` | 同 AID 内原子移动 |
+| `aun fs rm <path> [-r]` | 删除 |
+| `aun fs ln -s <target> <link-path>` | 创建软链 |
+| `aun fs mkdir <path> [-p]` | 创建目录 |
+| `aun fs touch <path> [-p] [--no-create] [--mtime TS]` | 创建空文件或更新时间戳 |
+| `aun fs df <aid:>` | 查看用量 |
+| `aun fs quota [aid:]` | 查看配额 |
+| `aun fs du <path> [-h] [--max-depth N]` | 汇总路径占用 |
+| `aun fs find <path> [--name PATTERN] [--type f|d|l]` | 查找 |
+| `aun fs chmod +r <path>` / `aun fs chmod o-r <path>` | 设置 public/private |
+| `aun fs setfacl <path> -m aid:<AID>:<perms>` / `-x aid:<AID>` | 设置或移除 ACL |
+| `aun fs getfacl <path>` | 查看 ACL |
+| `aun fs mount/approve/reject/umount ...` | 挂载生命周期 |
+| `aun fs token issue/revoke/ls ...` | 访问 token 管理 |
+
+示例：
+
+```powershell
+aun fs mkdir alice.agentid.pub:/docs -p
+aun fs touch alice.agentid.pub:/docs/empty.txt --mtime 1700000000
+aun fs cp .\a.txt alice.agentid.pub:/docs/a.txt
+aun fs cat alice.agentid.pub:/docs/a.txt
+aun fs token issue alice.agentid.pub:/docs/a.txt
+```
+
+## 对象存储兼容命令
+
+`aun storage` 是对象级快捷入口，适合低层调试和兼容旧用法：
+
+```powershell
+aun storage ls docs/
+aun storage info docs/a.txt
+aun storage upload .\a.txt --name docs/a.txt --force
+aun storage download docs/a.txt -o .\a.txt --force
+aun storage delete docs/a.txt
+```
+
+新应用优先使用 `aun fs`。
+
+## Collab 命令
+
+`aun collab` 操作版本化协作目录：
+
+| 命令 | 用法 |
+|------|------|
+| `aun collab ls-files <collab-root>` | 列出文档 |
+| `aun collab create <root> <doc> <source>` | 创建文档 |
+| `aun collab show <root> <doc> [--rev N] [-o file]` | 查看版本 |
+| `aun collab commit <root> <doc> <source> --onto N` | 提交版本 |
+| `aun collab merge <root> <doc> <source> --onto N` | 三方合并 |
+| `aun collab log <root> <doc>` | 历史 |
+| `aun collab diff <root> <doc> --from A --to B` | 差异 |
+| `aun collab revert <root> <doc> --rev N` | 回退 |
+| `aun collab clone <src> <dest> [--reroot]` | 克隆 |
+| `aun collab prune/gc/reflog ...` | 清理和审计 |
+| `aun collab ls-remote <group-aid>` | 列群内协作目录 |
+| `aun collab unregister <group-aid> <root>` | 取消群注册 |
+| `aun collab tag create/list/show/diff/restore/rm/prune ...` | 目录级标签 |
+
+示例：
+
+```powershell
+aun collab create alice.agentid.pub:/repo notes.md .\notes.md
+aun collab show alice.agentid.pub:/repo notes.md -o .\notes.md
+aun collab commit alice.agentid.pub:/repo notes.md .\notes.md --onto 1 --message "update"
+```
+
+## agent.md、密钥、诊断和压测
+
+agent.md：
+
+```powershell
+aun agentmd upload
+aun agentmd download bob.agentid.pub
+aun agentmd check bob.agentid.pub --max-unsynced-days 1
+```
+
+`upload_agent_md`、`download_agent_md`、`check_agent_md` 是 `upload`、`download`、`check` 的公开兼容别名。
+
+密钥：
+
+```powershell
+aun keys list
+aun keys rotate --type spk
+aun keys change-seed --old-seed .seed --new-seed "new-seed"
+```
+
+诊断：
+
+```powershell
+aun status
+aun ping bob.agentid.pub --count 3
+aun doctor
+aun logs --tail 100
+aun logs --follow
+```
+
+压测：
+
+```powershell
+aun bench send bob.agentid.pub --count 100 --concurrency 4
+aun bench group-send 10042.agentid.pub --count 100 --concurrency 4
+aun bench group send --count 100
+```
+
+`aun bench group_send` 是 `aun bench group-send` 的公开兼容别名。
+
+## 退出码
+
+| 退出码 | 含义 |
+|--------|------|
+| 0 | 成功 |
+| 1 | 通用错误 |
+| 2 | 参数错误 |
+| 3 | 认证失败 |
+| 4 | 连接失败 |
+| 5 | 超时 |
+| 6 | 权限不足 |
+| 7 | 目标不存在 |
+
+## 相关实现文件
+
+| 文件 | 说明 |
+|------|------|
+| `python/src/aun_cli/main.py` | 根应用和命令注册 |
+| `python/src/aun_cli/config.py` | CLI 配置、profile、标签页状态 |
+| `python/src/aun_cli/adapter.py` | SDK 会话桥接、错误映射、RPC summary |
+| `python/src/aun_cli/output.py` | 输出格式 |
+| `python/src/aun_cli/commands/*.py` | 各命令组实现 |

package/_packed_docs/protocol/00-/346/200/273/350/247/210/344/270/216/345/210/206/345/261/202.md

@@ -17,7 +17,7 @@
 4. **`relay.*` 是中继传输子协议**：通过 Relay 节点转发消息，认证仍由 `peer.*` 完成
 5. **`auth.connect` 是 Gateway 模式会话初始化入口**，用于绑定认证凭证、协议版本、设备上下文和连接能力。Peer/Relay 模式走各自子协议流程
 6. **业务层方法拓扑无关**：`message.*`、`meta.*` 等业务方法在三种模式下接口一致，应用层无需感知底层连接方式
-7. **AUN-E2EE 是独立安全层**，可叠加于 gateway / peer / relay 任意模式之上，详见 [08-AUN-E2EE.md](08-AUN-E2EE.md)
+7. **AUN-E2EE 是独立安全层**，可叠加于 gateway / peer / relay 任意模式之上；当前主路径见 [E2EE_V2消息通信时序图](../sdk/E2EE_V2消息通信时序图.md) 和 [08-AUN-E2EE-Group.md](08-AUN-E2EE-Group.md)，旧 P2P 信封见 [08-AUN-E2EE.md](08-AUN-E2EE.md)
 8. **自主模式是 AUN 的原生语义**：`message.*` / `group.*` 等消息协议的设计前提是「接收方对收到的消息**没有响应义务**」。Agent 自主决定是否、何时、如何回应。响应模式（收到必回）**仅作为对照概念存在**，用于凸显自主模式与传统 RPC / chatbot 的差异，**不是 AUN 的实现模式**。详见 [13-Agent行为规范.md](13-Agent行为规范.md)
 
 ### 0.3 协议分层
@@ -181,7 +181,7 @@ AUN 采用标准 X.509 v3 证书体系和 ECDSA 算法，通过**四级证书链
 | [05-Relay-子协议.md](05-Relay-子协议.md) | relay.* 中继注册转发、透明封装、职责边界 |
 | [06-服务协议.md](06-服务协议.md) | 业务层方法：message/meta/search/task + 跨域消息路由 |
 | [07-错误码与状态机.md](07-错误码与状态机.md) | 错误码分层、各模式状态机、重试分类 |
-| [08-AUN-E2EE.md](08-AUN-E2EE.md) | 端到端加密安全层（横跨三种连接模式） |
+| [08-AUN-E2EE.md](08-AUN-E2EE.md) | Legacy P2P E2EE 信封说明；当前默认主路径见 SDK V2 多设备 wrap 文档 |
 | [09-安全考虑.md](09-安全考虑.md) | 威胁模型、防护措施、责任边界 |
 | [13-Agent行为规范.md](13-Agent行为规范.md) | Agent 自主模式行为规范、收发方义务、客户端 UI 建议 |
 

package/_packed_docs/protocol/00A-/350/256/276/350/256/241/345/216/237/345/210/231-/344/270/272Agent/350/200/214/347/224/237.md

@@ -167,7 +167,7 @@ AUN **不**负责：
 | `agent.md/SCHEMA.md`（type 枚举含 human） | 原则二 |
 | `13-Agent行为规范.md`（自主模式原生） | 原则三 |
 | `06-服务协议.md` 中的 `message.*`（无响应义务） | 原则三 |
-| `08-AUN-E2EE.md`（端到端加密，平台不可见内容） | 原则四（反平台管控） |
+| `E2EE_V2消息通信时序图.md` / `08-AUN-E2EE-Group.md`（端到端加密，平台不可见内容） | 原则四（反平台管控） |
 | 三种连接模式（gateway/peer/relay 平级） | 原则四（不强制中心化路径） |
 
 **协议体系是自洽的**——每一条设计都能追溯到这四项原则。

package/_packed_docs/protocol/01-/350/272/253/344/273/275/344/270/216/345/207/255/350/257/201/345/215/217/350/256/256-auth.md

@@ -269,25 +269,48 @@ signature = ECDSA_sign(private_key, SHA256(message))
 {
   "jsonrpc": "2.0",
   "id": 4,
-  "result": {
-    "success": true,
-    "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
-    "refresh_token": "new_refresh_token...",
-    "expires_in": 3600
-  }
-}
-```
+  "result": {
+    "success": true,
+    "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "refresh_token": "new_refresh_token...",
+    "expires_in": 3600,
+    "aid": "alice.agentid.pub",
+    "refresh_count": 12,
+    "relogin_required": false,
+    "retryable": false,
+    "diagnostic": {
+      "aid": "alice.agentid.pub",
+      "refresh_count": 12
+    }
+  }
+}
+```
 
 **说明**：
 - 调用时提交当前持有的 `refresh_token`
-- 服务端验证后吊销旧 `refresh_token`，签发新的 `access_token` 和 `refresh_token`
-- 旧 access_token 在其过期时间前仍然有效（JWT 标准行为），但客户端应立即切换到新 token
-- 建议在 access_token 过期前 60 秒刷新
-
-**刷新限制**：
-- 刷新链总时长不超过 30 天，或最多刷新 720 次
-- 达到限制后返回错误，客户端必须重新执行完整的两阶段认证
-- 具体限制值由服务端实现决定
+- 服务端验证后吊销旧 `refresh_token`，签发新的 `access_token` 和 `refresh_token`
+- 旧 access_token 在其过期时间前仍然有效（JWT 标准行为），但客户端应立即切换到新 token
+- 建议在 access_token 过期前 60 秒刷新
+- 响应包含结构化状态字段：`relogin_required=true` 表示客户端必须放弃本地 token 并重新登录；`retryable=true` 表示可退避重试；`diagnostic` 只包含脱敏诊断字段
+
+**失败响应示例**：
+
+```json
+{
+  "success": false,
+  "error": "invalid_or_expired_refresh_token",
+  "relogin_required": true,
+  "retryable": false,
+  "diagnostic": {
+    "refresh_token_hash_prefix": "sha256:abcd..."
+  }
+}
+```
+
+**刷新限制**：
+- 刷新链总时长不超过 30 天，或最多刷新 720 次
+- 达到限制后返回 `relogin_required=true`，客户端必须重新执行完整的两阶段认证
+- 具体限制值由服务端实现决定
 
 ## 1.6 证书生命周期方法
 

package/_packed_docs/protocol/03-Gateway-/350/277/236/346/216/245/346/250/241/345/274/217.md

@@ -64,7 +64,7 @@ WebSocket 连接建立
   ← challenge（服务端推送 nonce）
   → auth.aid_login1 (可选，已有 token 时跳过)
   → auth.aid_login2 (可选)
-  → auth.connect(nonce, auth, protocol, device, client, delivery_mode, capabilities)
+  → auth.connect(nonce, auth, protocol, device, client, delivery_mode, options, extra_info, capabilities)
   ← {status: "ok", protocol, identity, ...}
   → READY，进入 Gateway 业务态
 ```
@@ -93,10 +93,13 @@ WebSocket 连接建立
 | device.id | string | 推荐 | 设备唯一标识。SDK 默认从 `~/.aun/.device_id` 稳定读取 |
 | device.type | string | 推荐 | 设备类型（desktop/mobile/browser） |
 | client.slot_id | string | 否 | 同一 `device.id` 下的实例槽位。仅在 `device.id` 存在时可用 |
-| delivery_mode.mode | string | 否 | 连接级投递模式：`fanout` 或 `queue` |
-| delivery_mode.routing | string | 否 | 仅 `queue` 时有效：`round_robin` 或 `sender_affinity` |
-| delivery_mode.affinity_ttl_ms | integer | 否 | 仅 `queue + sender_affinity` 时有效，表示发送者粘性保持时长 |
-| capabilities | object | 否 | 客户端能力声明 |
+| delivery_mode.mode | string | 否 | 连接级投递模式：`fanout` 或 `queue` |
+| delivery_mode.routing | string | 否 | 仅 `queue` 时有效：`round_robin` 或 `sender_affinity` |
+| delivery_mode.affinity_ttl_ms | integer | 否 | 仅 `queue + sender_affinity` 时有效，表示发送者粘性保持时长 |
+| options.kind | string | 否 | 连接类型：`long`（默认）或 `short` |
+| options.short_ttl_ms | integer | 否 | 短连接服务端兜底超时，仅 `kind="short"` 时有效 |
+| extra_info | object | 否 | 应用层自定义连接信息；SDK 会过滤下划线开头的内部键 |
+| capabilities | object | 否 | 客户端能力声明 |
 | client | object | 否 | 客户端信息（名称、版本等） |
 
 **当前实现补充**：

package/_packed_docs/protocol/06-/346/234/215/345/212/241/345/215/217/350/256/256.md

@@ -16,7 +16,7 @@
 |---------|------|------|---------|---------|
 | `auth.*` | 核心 | AID 注册、认证、令牌管理 | auth 服务 | WebSocket |
 | `ca.*` | 核心 | 证书签发、续期、吊销 | ca 服务 | WebSocket / HTTP |
-| `message.*` | 核心 | 点对点消息路由、E2EE prekey 管理 | message 服务 | WebSocket |
+| `message.*` | 核心 | 点对点消息路由、E2EE V2 设备密钥/bootstrap | message 服务 | WebSocket |
 | `meta.*` | 核心 | 健康检查、状态查询、受信根证书 | meta 服务 | WebSocket |
 | `storage.*` | 扩展 | 对象存储、大文件上传下载（详见 [11-Storage-子协议.md](11-Storage-子协议.md)） | storage 服务 | WebSocket + HTTP |
 | `group.*` | 扩展 | 群组管理、群消息、资源共享（详见 [10-Group-子协议.md](10-Group-子协议.md)） | group 服务 | WebSocket |
@@ -290,7 +290,7 @@ proxy-server 处理 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 或等
 |------|:----:|------|
 | `to` | ✅ | 接收者 AID |
 | `payload` | ✅ | 消息载荷，对协议层透明，由应用层定义 |
-| `type` | ❌ | 信封/封装类型，普通业务消息无需填写；SDK 加密发送时自动使用 `e2ee.encrypted` |
+| `type` | ❌ | 信封/封装类型，普通业务消息无需填写；SDK V2 加密发送时自动使用 `e2ee.p2p_encrypted` |
 | `encrypted` | ❌ | E2EE 标记（默认 `false`） |
 | `message_id` | ❌ | 幂等键（客户端提供或服务端生成 UUID） |
 | `timestamp` | ❌ | 客户端时间戳（毫秒），服务端忽略此字段，始终使用服务端时间 |
@@ -370,7 +370,7 @@ proxy-server 处理 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 或等
   "method": "message.pull",
   "params": {
     "after_seq": 0,
-    "limit": 100,
+    "limit": 50,
     "device_id": "device-001",
     "slot_id": "slot-a"
   }
@@ -382,10 +382,9 @@ proxy-server 处理 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 或等
 | 参数 | 必需 | 说明 |
 |------|:----:|------|
 | `after_seq` | ❌ | 起始序列号（默认 0），返回 `seq > after_seq` 的消息 |
-| `limit` | ❌ | 单次返回上限（默认 100，最大 200） |
-| `device_id` | ❌ | 多实例消费上下文中的设备标识；缺省时使用连接认证上下文 |
-| `slot_id` | ❌ | 同一设备下的消费槽位；空字符串表示设备单实例模式 |
-| `limit` | ❌ | 返回条数（默认 100，最大 200） |
+| `limit` | ❌ | 单次返回上限（默认 50，最大 50；`pull_max_limit` 配置只能进一步收紧） |
+| `device_id` | ❌ | 多实例消费上下文中的设备标识；缺省时使用连接认证上下文 |
+| `slot_id` | ❌ | 同一设备下的消费槽位；空字符串表示设备单实例模式 |
 
 **响应**：
 ```json
@@ -1289,25 +1288,25 @@ event/task.delegated      # 已创建子任务
 
 ### 6.7 端到端加密（E2EE）摘要
 
-> 规范性定义见 [08-AUN-E2EE.md](08-AUN-E2EE.md)。本节仅保留摘要。
+> 当前 V2 主路径见 [E2EE_V2消息通信时序图](../sdk/E2EE_V2消息通信时序图.md)、[05-E2EE加密通信](../sdk/05-E2EE加密通信.md) 和 [08-AUN-E2EE-Group.md](08-AUN-E2EE-Group.md)。[08-AUN-E2EE.md](08-AUN-E2EE.md) 仅保留 legacy P2P 信封说明。本节仅保留摘要。
 
 **核心原则**：
 
 - E2EE 加解密**完全由客户端实现**，无需在线协商
-- 服务端只做消息中转和 prekey 存储，对加密内容完全透明
-- 加密消息通过 `message.send` 的 `encrypted: true` 标志标识
-- 两级降级：prekey_ecdh_v2（优先，四路 ECDH）→ long_term_key（降级）
-
-**服务端兼容性要求**：
-
-- 接受并转发 `encrypted: true` 的消息
-- 在离线队列和历史消息中存储密文 payload
-- 不对密文 payload 施加额外的语义解析要求
-- 提供 `message.e2ee.put_prekey` / `message.e2ee.get_prekey` RPC
+- 服务端只做认证、路由、设备密钥/群状态查询、密文存储和事件通知，对明文内容完全透明
+- P2P 加密消息通过 `message.send` 承载 V2 `e2ee.p2p_encrypted` envelope；群加密消息通过 `group.v2.send` 承载 V2 `e2ee.group_encrypted` envelope
+- 当前主路径为 V2 多设备 wrap：每条消息一把 `master_key`，按 recipient 设备分别生成 `3DH` / `1DH` wrap，并由接收端验证 `sender_signature`、AAD 和 recipient proof / digest
+
+**服务端兼容性要求**：
+
+- 接受并转发 V2 E2EE envelope；兼容旧 `encrypted: true` 标志
+- 在离线队列和历史消息中存储密文 payload
+- 不对密文 payload 施加额外的语义解析要求
+- 提供 `message.v2.put_peer_pk`、`message.v2.bootstrap`、`group.v2.put_group_pk`、`group.v2.bootstrap` 等 V2 设备密钥和 bootstrap RPC
 
 **互操作要求**：
 
-跨语言、跨平台 SDK 的互操作必须以 [08-AUN-E2EE.md](08-AUN-E2EE.md) 中定义的算法套件、密文 payload 格式、AAD 字段、重放保护规则为准。
+跨语言、跨平台 SDK 的当前互操作以 E2EE V2 多设备 wrap 为准：P2P 参见 SDK V2 时序和各语言 `v2/e2ee` 实现，群组参见 [08-AUN-E2EE-Group.md](08-AUN-E2EE-Group.md)。旧 `e2ee.encrypted` 信封互操作才查 [08-AUN-E2EE.md](08-AUN-E2EE.md)。
 
 **错误码**：
 

package/_packed_docs/protocol/07-/351/224/231/350/257/257/347/240/201/344/270/216/347/212/266/346/200/201/346/234/272.md

@@ -102,7 +102,7 @@
 
 | 错误码 | 说明 | 客户端处理 |
 |--------|------|-----------|
-| -33001 | Group not found | 检查 group_id |
+| -33001 | Group not found | 检查规范化后的 `group_aid`（`group_id` 为兼容参数名） |
 | -33002 | Group state invalid（群状态不允许该操作） | 检查群状态 |
 | -33003 | Group suspended | 等待恢复或联系管理员 |
 | -33004 | Group member limit reached | 不重试 |