@agentunion/fastaun 0.5.15 → 0.5.17

package/_packed_docs/sdk/09-group-rpc-manual.md

@@ -38,13 +38,19 @@
 | [group.get_members](#groupget_members) | 获取成员列表 |
 | [group.kick](#groupkick) | 踢出成员 |
 | [group.leave](#groupleave) | 主动退群 |
-| [group.set_role](#groupset_role) | 设置角色 |
-| [group.transfer_owner](#grouptransfer_owner) | 转让群主 |
-| [group.bind_group_aid](#groupbind_group_aid) | 为匿名群绑定群身份 |
+| [group.set_role](#groupset_role) | 设置角色 |
+| [group.transfer_owner](#grouptransfer_owner) | 转让群主 |
+| [group.complete_transfer](#groupcomplete_transfer) | 完成群主转让与群身份换钥 |
+| [group.bind_group_aid](#groupbind_group_aid) | 为匿名群绑定群身份 |
 | [group.renew_group_aid](#grouprenew_group_aid) | 轮换群身份密钥 |
-| [group.ban](#groupban) | 封禁成员 |
-| [group.unban](#groupunban) | 解封成员 |
-| [group.get_banlist](#groupget_banlist) | 获取封禁列表 |
+| [group.ban](#groupban) | 封禁成员 |
+| [group.unban](#groupunban) | 解封成员 |
+| [group.get_banlist](#groupget_banlist) | 获取封禁列表 |
+| [group.block](#groupblock) | 屏蔽成员接收群消息 |
+| [group.unblock](#groupunblock) | 取消屏蔽 |
+| [group.get_blocklist](#groupget_blocklist) | 获取屏蔽列表 |
+| [group.report_status](#groupreport_status) | 上报自己的群内状态 |
+| [group.get_member_statuses](#groupget_member_statuses) | 获取群成员状态列表 |
 
 ### 入群流程
 
@@ -161,7 +167,9 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 ### group.create
 
-创建群组。调用者自动成为 owner。支持创建命名群（传入 `group_name` + `public_key`）。新建群主标识以 `group_aid` 为准；`group_id` 仅作为兼容字段保留。
+创建群组。调用者自动成为 owner。支持创建命名群（传入 `group_name` + `public_key`）。新建群主标识以 `group_aid` 为准；`group_id` 仅作为兼容字段保留。
+
+四种 SDK 的高层建群接口均支持崩溃恢复。命名群在 RPC 前持久化群密钥，并按 `group_name + public_key` 重放已提交结果；匿名群在 RPC 前持久化群密钥和创建上下文，重试会取回同一数字群并继续 `group_aid` 证书绑定与 `agent.md` 上传。群记录、群主成员、成员索引、入群设置、首个 `group.changed` 事件及匿名创建映射由服务端在同一数据库事务提交；证书服务和存储服务不参与该数据库事务，由 SDK pending 状态和服务端幂等重放恢复。
 
 **参数**：
 
@@ -347,7 +355,7 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 
 ### group.suspend
 
-暂停群组。暂停期间不能发送消息。需要 **admin 及以上**权限。
+暂停群组。暂停期间 owner/admin 可以继续通过 `group.send`、`group.v2.send` 和 `group.thought.put` 发言；member 禁止发言，入群、邀请、申请审批等准入操作继续拒绝。需要 **admin 及以上**权限。
 
 **参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`）
 
@@ -530,26 +538,72 @@ SDK 发起 `group.*` 调用时会把传入的 `group_id` / `groupId` / `group_ai
 }
 ```
 
-### group.transfer_owner
-
-转让群主。需要 owner 权限。原 owner 转为 admin。
+### group.transfer_owner
+
+发起两阶段群主转让。需要 owner 权限；该调用只记录待换钥状态，不会立即变更群主。新群主完成 `group.complete_transfer` 后，原 owner 才转为 admin。
 
 **参数**：
 
 | 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
-| `new_owner` | string | 是 | 新群主 AID（也接受 `aid`） |
+|------|------|------|------|
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_aid` | string | 否 | 群身份；高层 SDK 会查询并补齐 |
+| `new_owner` | string | 是 | 新群主 AID（也接受 `aid`） |
+| `transfer_auth` | object | 是 | 旧群主使用当前 group_aid 私钥签名的授权，包含 `nonce`、`issued_ms`、`signature` |
 
 **响应**：
 
 ```json
-{
-    "group": { ... },
-    "old_owner": "alice.agentid.pub",
-    "new_owner": "bob.agentid.pub"
-}
-```
+{
+    "status": "pending_rekey",
+    "requires_ca_rekey": true,
+    "complete_rpc": "group.complete_transfer",
+    "group": { ... },
+    "group_id": "team.agentid.pub",
+    "group_aid": "team.agentid.pub",
+    "old_owner": "alice.agentid.pub",
+    "new_owner": "bob.agentid.pub",
+    "pending_owner_transfer": {
+        "status": "pending_rekey",
+        "old_owner": "alice.agentid.pub",
+        "new_owner": "bob.agentid.pub",
+        "group_aid": "team.agentid.pub",
+        "transfer_auth": { ... }
+    }
+}
+```
+
+四语言 SDK 会在新群主在线收到 `owner_transfer_rekey_pending` 事件，或重连发现本地 pending 状态时自动尝试完成转让。发起方的高层转让方法返回上述 `pending_rekey`，不会等待新群主完成。Python / TypeScript / JavaScript 门面需要传入 `aid_store` / `aidStore` 才执行签名编排；Go 的高层发起入口为 `AUNClient.StartGroupTransfer`，`GroupFacade.TransferOwner` 当前是原始 RPC 门面。
+
+### group.complete_transfer
+
+由 pending 中的新群主完成群身份换钥和所有权切换。成功后响应状态为 `transferred`，新群主成为 owner，原群主转为 admin。
+
+**参数**：
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `group_id` | string | 是 | 群组标识；兼容字段，值语义为目标态 `group_aid` |
+| `group_aid` | string | 否 | 群身份；高层 SDK 会查询并补齐 |
+| `public_key` | string | 是 | 新 group_aid 公钥 DER base64（SPKI 格式） |
+| `curve` | string | 否 | 曲线名称，默认 `P-256` |
+| `transfer_accept` | object | 是 | 新群主使用自身 AID 私钥签名的接受证明，包含 `nonce`、`issued_ms`、`signature` |
+
+**响应**：
+
+```json
+{
+    "status": "transferred",
+    "group": { ... },
+    "group_id": "team.agentid.pub",
+    "group_aid": "team.agentid.pub",
+    "old_owner": "alice.agentid.pub",
+    "new_owner": "bob.agentid.pub",
+    "aid_cert": { "cert": "-----BEGIN CERTIFICATE-----..." }
+}
+```
+
+高层 SDK 会生成并暂存新群身份密钥，签名 `transfer_accept`，成功后导入新的 group_aid 身份；重复提交同一已完成转让时，服务端可幂等返回已完成结果。
 
 ### group.bind_group_aid
 
@@ -704,7 +758,7 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
 }
 ```
 
-### group.get_banlist
+### group.get_banlist
 
 获取封禁列表。需要 **admin 及以上**权限。
 
@@ -728,10 +782,88 @@ aun-group-aid-renew-v1|{group_id}|{group_aid}|{sha256(old_public_key)}|{sha256(n
     "total": 1,
     "page": 1,
     "size": 200
-}
-```
-
----
+}
+```
+
+禁言与屏蔽是两个独立状态，可以同时设置。禁言成员仍能接收群消息，但不能发送；屏蔽成员仍能发送群消息，但不再收到该群的实时消息 Push、离线消息 Push、Pull 或 E2EE wrap。
+
+### group.block
+
+屏蔽成员接收群消息。owner/admin 可以屏蔽其权限范围内的成员；所有成员都可以屏蔽自己。屏蔽只影响接收，不影响该成员向群内发送消息，也不改变已有禁言状态。
+
+**参数**：`group_id`（string，必填；兼容字段，值使用目标态 `group_aid`），`subject` 或 `aid`（string，必填；传入自己的 AID 即可屏蔽自己），`reason`（string，可选）。
+
+**响应**：
+
+```json
+{
+    "group_id": "g-abc123.agentid.pub",
+    "group_aid": "g-abc123.agentid.pub",
+    "block": {
+        "group_id": "g-abc123.agentid.pub",
+        "subject": "bob.agentid.pub",
+        "blocked_by": "alice.agentid.pub",
+        "reason": "暂不接收群消息",
+        "created_at": 1234567890000
+    }
+}
+```
+
+### group.unblock
+
+取消屏蔽。owner/admin 可以取消其权限范围内成员的屏蔽；所有成员都可以取消自己的屏蔽。取消屏蔽不改变禁言状态。
+
+**参数**：`group_id`（string，必填），`subject` 或 `aid`（string，必填；传入自己的 AID 即可取消自己的屏蔽）。
+
+**响应**：`{ "group_id": "g-abc123.agentid.pub", "group_aid": "g-abc123.agentid.pub", "subject": "bob.agentid.pub", "status": "removed" }`
+
+### group.get_blocklist
+
+获取群屏蔽列表。需要 **admin 及以上**权限。
+
+**参数**：`group_id`（string，必填）
+
+**响应**：`{ "group_id": "g-abc123.agentid.pub", "group_aid": "g-abc123.agentid.pub", "items": [ ... ], "total": 1, "page": 1, "size": 1 }`
+
+每个条目包含 `group_id`、`subject`、`blocked_by`、`reason` 和 `created_at`。
+
+### group.report_status
+
+上报当前成员在指定群内的在线状态和工作状态。调用者只能上报自己的状态；`updated_at` 由服务端记录。消息发送成功后，服务端独立维护该成员的 `last_message_at` 和 `last_payload_type`。
+
+**参数**：`group_id`（string，必填），`online_status`（string，必填），`work_status`（string，必填）。
+
+**响应**：`{ "group_id": "g-abc123.agentid.pub", "group_aid": "g-abc123.agentid.pub", "status": { ... } }`
+
+### group.get_member_statuses
+
+查询群内所有成员状态。调用者必须是群成员。响应始终以数组返回，并包含尚未上报状态的成员。
+
+**参数**：`group_id`（string，必填）
+
+**响应**：
+
+```json
+{
+    "group_id": "g-abc123.agentid.pub",
+    "group_aid": "g-abc123.agentid.pub",
+    "items": [
+        {
+            "group_id": "g-abc123.agentid.pub",
+            "aid": "alice.agentid.pub",
+            "online_status": "online",
+            "work_status": "busy",
+            "updated_at": 1234567890000,
+            "last_message_at": 1234567890123,
+            "last_payload_type": "text"
+        }
+    ]
+}
+```
+
+`online_status` 和 `work_status` 是成员上报值；未上报时为空字符串。`last_message_at` 为该成员在此群最后一条成功发送消息的时间，`last_payload_type` 为该消息的 `payload.type`；没有历史消息时分别为 `0` 和空字符串。
+
+---
 
 ## 入群流程
 
@@ -1113,7 +1245,7 @@ SDK 观察到 `_meta.group_indexes` 只记录远端 etag，不会自动覆盖本
 
 ### group.send
 
-发送群消息。需要 member 权限。
+发送群消息。需要 member 权限。群为 `suspended` 时仅 owner/admin 可以发送，member 会被拒绝。
 
 群消息的持久化 `mention_mode` 来自群设置，取值为 `"disabled"` / `"mention-only"`；服务端会写入消息对象并在 pull / push 中返回。运行时是否广播全员或分发给值班 Agent，由响应中的 `dispatch` / `message_dispatch` 描述。V2 加密消息把快照放在既有 `envelope_json` 元数据中，不改变 `per_device` 投递列。
 
@@ -1179,7 +1311,7 @@ SDK 观察到 `_meta.group_indexes` 只记录远端 etag，不会自动覆盖本
 
 ### group.thought.put
 
-写入某个发送者针对一个群上下文的思考内容。该内容不是普通群消息：服务端不分配消息 `seq`，不广播，不进入 `group.pull`，不需要 ack，也不持久化；只在内存中保留当前 head。
+写入某个发送者针对一个群上下文的思考内容。该内容不是普通群消息：服务端不分配消息 `seq`，不广播，不进入 `group.pull`，不需要 ack，也不持久化；只在内存中保留当前 head。群为 `suspended` 时仅 owner/admin 可以写入，member 会被拒绝。
 
 SDK 调用时必须走群组 E2EE。应用层传入明文 `payload`，SDK 会加密成 V2 `e2ee.group_encrypted` 信封、补齐 `thought_id` / `timestamp`，并附加 `client_signature`。裸 WebSocket 客户端若绕过 SDK，至少必须自行完成 V2 envelope、`sender_signature`、AAD 和 state commitment 生成；`client_signature` 按 Gateway 连接级身份语义携带。
 
@@ -1502,7 +1634,7 @@ SDK Group FS 门面使用票据执行 HTTP GET 并校验 sha256。应用自行
 
 ### group.fs.create_upload_session
 
-创建上传会话。参数同 `check_upload`。响应包含 `upload_url`、`session_id`、可选 `headers`。SDK 使用该 URL 执行 HTTP PUT。
+创建上传会话。参数同 `check_upload`。响应透传 Storage session 字段并增加 Group FS 路径视图，包含 `upload_url`、`content_type`、`size_bytes` 等；当前 Storage 服务不返回 `session_id` 或 `headers`。四个 SDK 的 Group FS 门面会按实际字节识别 MIME，并在 session、HTTP PUT 与 complete 中保持 `Content-Type` 一致；若 session 返回 headers，SDK 保留其它 header 并替换其中的 Content-Type，避免 OSS 签名不一致导致 403。
 
 ### group.fs.complete_upload
 
@@ -1805,8 +1937,9 @@ SDK 交付给应用层的群事件信封字段统一放在 `envelope`。0.5.x
 | `member_added` | 成员加入 |
 | `member_left` | 成员退出 |
 | `member_removed` | 成员被踢出 |
-| `role_changed` | 角色变更 |
-| `owner_transferred` | 群主转让 |
+| `role_changed` | 角色变更 |
+| `owner_transfer_rekey_pending` | 群主转让已发起，等待新群主完成群身份换钥 |
+| `owner_transferred` | 群主转让 |
 | `rules_updated` | 规则更新 |
 | `announcement_updated` | 公告更新 |
 | `join_requested` | 收到入群申请 |
@@ -1817,8 +1950,10 @@ SDK 交付给应用层的群事件信封字段统一放在 `envelope`。0.5.x
 | `invite_code_created` | 邀请码创建 |
 | `invite_code_used` | 邀请码使用 |
 | `invite_code_revoked` | 邀请码撤销 |
-| `member_banned` | 成员封禁 |
-| `member_unbanned` | 成员解封 |
+| `member_banned` | 成员封禁 |
+| `member_unbanned` | 成员解封 |
+| `member_blocked` | 成员被屏蔽 |
+| `member_unblocked` | 成员取消屏蔽 |
 | `suspended` | 群组暂停 |
 | `resumed` | 群组恢复 |
 | `dissolved` | 群组解散 |
@@ -2017,6 +2152,3 @@ Group 服务定义了以下专用错误码（-33xxx 段）：
 | -33009 | Resource request not found | 检查 request_id |
 
 > SDK 客户端将 -33001 映射为 `GroupNotFoundError`，-33002~-33003 映射为 `GroupStateError`，其余映射为 `GroupError`。未识别的错误码 fallback 到 `AUNError`。
-
-
-

package/_packed_docs/sdk/09-message-rpc-manual.md

@@ -61,8 +61,10 @@ P2P `message.*` 的最终投递语义由连接阶段声明的 `delivery_mode`
     "jsonrpc": "2.0",
     "method": "message.send",
     "params": {
-        "to": "bob.agentid.pub",
-        "payload": {"type": "text", "text": "Hello!"},
+        "to": "bob.agentid.pub",
+        "device_id": "bob-phone",
+        "ttl": 300,
+        "payload": {"type": "text", "text": "Hello!"},
         "encrypted": false,
         "message_id": "550e8400-e29b-41d4-a716-446655440000",
         "timestamp": 1234567890000
@@ -75,16 +77,23 @@ P2P `message.*` 的最终投递语义由连接阶段声明的 `delivery_mode`
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
-| `to` | string | 是 | — | 接收方 AID |
-| `payload` | object | 是 | — | 消息内容（任意 JSON 对象） |
+| `to` | string | 是 | — | 接收方 AID |
+| `device_id` | string | 否 | — | 目标接收设备。非空时仅投递该设备；未指定时按接收方 AID 投递全部设备 |
+| `to_device_id` | string | 否 | — | `device_id` 的兼容别名；两者均非空时以 `device_id` 为准 |
+| `ttl` | integer | 否 | `0` | 秒。`ttl <= 0` 持久化；`ttl > 0` 钳制到 1–3600 秒并只保存在消息服务内存中 |
+| `payload` | object | 是 | — | 消息内容（任意 JSON 对象） |
 | `type` | string | 否 | — | 信封/封装类型，普通业务消息无需填写；SDK V2 加密发送时自动使用 `e2ee.p2p_encrypted` |
 | `encrypted` | boolean | 否 | `false` | 底层 RPC 的 E2EE 标记。Python SDK 便捷层通常使用 `encrypt` 入参并由 SDK 自动填充此字段 |
 | `message_id` | string | 否 | — | 幂等键（客户端提供或服务端生成 UUID） |
 | `timestamp` | integer | 否 | — | 客户端时间戳（毫秒）。**服务端忽略此字段，始终使用服务端时间** |
 | `protected_headers` / `headers` | object | 否 | — | SDK 加密前读取的 E2EE 信封元数据，类似 HTTP headers；推荐使用 `protected_headers`，`headers` 仅作为兼容别名；服务端不解释，接收端验 `_auth` 后在 `e2ee.protected_headers` 暴露 |
 
-> 连接级 `delivery_mode` 在 `auth.connect` 阶段声明，结构见 `02-WebSocket协议.md`。Python SDK 的 P2P 消息发送会沿用当前连接的 `delivery_mode`，应用层发送时无需重复指定。
-> `protected_headers` 只在 SDK 加密路径生效；裸 RPC 发送明文或已加密信封时，调用方需自行遵守 [05-E2EE加密通信](05-E2EE加密通信.md#protectedheaders-与可验证上下文) 的格式和校验规则。
+> 连接级 `delivery_mode` 在 `auth.connect` 阶段声明，结构见 `02-WebSocket协议.md`。Python SDK 的 P2P 消息发送会沿用当前连接的 `delivery_mode`，应用层发送时无需重复指定。
+> `protected_headers` 只在 SDK 加密路径生效；裸 RPC 发送明文或已加密信封时，调用方需自行遵守 [05-E2EE加密通信](05-E2EE加密通信.md#protectedheaders-与可验证上下文) 的格式和校验规则。
+
+`message.send.device_id` 表示接收目标，不是发送方设备，也不同于 `message.pull` / `message.ack` 中表示当前消费实例的 `device_id`。指定目标设备时，SDK 的 V2 加密信封只选择该设备对应的 peer wrap（AID scope 使用对应 AID wrap），同时保留发送方 self-sync 和监管 audit wrap。目标设备不存在或不可用时发送失败，不会降级为 AID 全设备广播。
+
+`ttl` 与连接级 `delivery_mode` 相互独立。正 TTL 消息不写数据库或 WAL、不分配持久 `seq`；跨域只转发剩余 TTL，目标域不会重新执行 1 秒下限钳制。
 
 ### Payload 参考约定
 
@@ -117,17 +126,24 @@ P2P `message.*` 的最终投递语义由连接阶段声明的 `delivery_mode`
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `message_id` | string | 消息 ID |
-| `seq` | integer | 接收方收件箱序号 |
+| `message_id` | string | 消息 ID |
+| `storage` | string | `persistent` 或 `volatile`；旧服务端未返回时按 `persistent` 处理 |
+| `seq` | integer | 持久消息的接收方收件箱序号；volatile 消息不返回 |
+| `volatile_cursor` | string | volatile 消息的 opaque 游标；不得解析 |
+| `volatile_cursors` | string[] | 未指定目标设备且投递多个设备时的 volatile 游标列表 |
+| `created_at` | integer | volatile 消息的服务端创建时间（毫秒） |
+| `expires_at` | integer | volatile 消息的服务端过期时间（毫秒） |
 | `timestamp` | integer | 服务端时间戳（毫秒） |
-| `status` | string | `"sent"` / `"delivered"` / `"duplicate"` |
+| `status` | string | `"sent"` / `"delivered"` / `"accepted"` / `"duplicate"` |
 | `delivery_mode` | string | 最终生效的连接级投递语义：`fanout` 或 `queue` |
 | `envelope` | object | SDK 回填的发送结果信封，包含发送方、接收方、业务类型、时间戳、加密标志、protected headers 等可转发元数据 |
 | `payload` | object | SDK 回填的应用层业务 payload；裸 RPC 或内部 `_skip_send_result_envelope` 路径可能没有该字段 |
 | `cross_domain` | boolean | 仅跨域投递时出现，当前值为 `true` |
 | `target_issuer` | string | 仅跨域投递时出现，表示目标 issuer |
 
-> **duplicate 响应**：当 `message_id` 重复时，若服务端仍缓存首次结果，返回完整首次响应并附加 `"status": "duplicate"`；若缓存已过期，仅返回 `message_id`、`timestamp`、`status`，**不含** `seq` 和 `delivery_mode`。客户端收到 `"duplicate"` 状态时应视为幂等成功，无需重试。
+> **duplicate 响应**：当 `message_id` 重复时，若服务端仍缓存首次结果，返回完整首次响应并附加 `"status": "duplicate"`；若缓存已过期，仅返回 `message_id`、`timestamp`、`status`，**不含** `seq` 和 `delivery_mode`。客户端收到 `"duplicate"` 状态时应视为幂等成功，无需重试。
+
+volatile 成功响应以 `storage="volatile"`、`volatile_cursor`（多设备时还可含 `volatile_cursors`）、`created_at`、`expires_at` 和 `status="accepted"` 表示，不含 `seq`。到期或服务重启后消息允许丢失。
 
 ### 错误
 
@@ -136,16 +152,18 @@ P2P `message.*` 的最终投递语义由连接阶段声明的 `delivery_mode`
 | -32002 | 服务暂不可用（如数据库未连接、服务证书未加载） |
 | -32603 | 参数缺失（to 或 payload） |
 | -32603 | payload 超过大小限制（默认 1 MB） |
-| -32603 | 目标 AID 不存在 |
-| -32603 | 频率限制超限 |
+| -32603 | 目标 AID 不存在 |
+| -32603 | 指定的目标设备不存在、未注册或 V2 bootstrap 中不可用 |
+| -32603 | 频率限制超限 |
 
 ### 示例
 
 ```python
-result = await client.call("message.send", {
-    "to": "bob.agentid.pub",
-    "payload": {"type": "text", "text": "Hello!"},
-})
+result = await client.call("message.send", {
+    "to": "bob.agentid.pub",
+    "device_id": "bob-phone",
+    "payload": {"type": "text", "text": "Hello!"},
+})
 # result: {"message_id": "...", "seq": 42, "status": "delivered", ...}
 ```
 
@@ -278,7 +296,7 @@ result = await client.call("message.thought.get", {
 
 ## message.pull
 
-按游标增量拉取消息。合并持久化消息和临时消息，按 seq 升序返回。
+按两个独立游标增量拉取持久消息和 volatile 消息。volatile 消息不进入持久 `seq` 空间。
 
 ### 请求
 
@@ -287,10 +305,10 @@ result = await client.call("message.thought.get", {
     "jsonrpc": "2.0",
     "method": "message.pull",
     "params": {
-        "after_seq": 100,
-        "limit": 50,
-        "device_id": "device-001",
-        "slot_id": "slot-a"
+        "after_seq": 100,
+        "after_volatile_cursor": "v1:i1:7:20",
+        "limit": 50,
+        "device_id": "device-001"
     },
     "id": 2
 }
@@ -300,12 +318,12 @@ result = await client.call("message.thought.get", {
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
-| `after_seq` | integer | 否 | 0 | 拉取 seq > after_seq 的消息 |
-| `limit` | integer | 否 | 50 | 单次返回上限（最大 50；`pull_max_limit` 配置只能在 1-50 内进一步收紧） |
-| `device_id` | string | 否 | 当前连接实例 | 多实例消费上下文中的设备标识 |
-| `slot_id` | string | 否 | 当前连接实例 | 同一设备下的消费槽位；可用 `/`、`:`、空格表达共享隔离键，如 `evolclaw cli` |
-
-> 四个 SDK 都会自动为 `message.pull` 注入当前实例的 `device_id` / `slot_id`。显式传入 `slot_id` 时按 `slotIsolationKey` 比较，`evolclaw cli` 与 `evolclaw daemon` 视为同一隔离键；不同隔离键会在发出 RPC 前被拒绝。
+| `after_seq` | integer | 否 | 0 | 拉取 seq > after_seq 的消息 |
+| `after_volatile_cursor` | string | 否 | SDK 当前游标 | 拉取该 opaque volatile 游标之后的消息；应用通常无需传入 |
+| `limit` | integer | 否 | 50 | 单次返回上限（最大 50；`pull_max_limit` 配置只能在 1-50 内进一步收紧） |
+| `device_id` | string | 否 | 当前连接实例 | 多实例消费上下文中的设备标识 |
+
+> 四个 SDK 自动管理 `after_volatile_cursor`，并在传输层注入当前消费实例的内部 slot。slot 不属于应用参数，也不会出现在消息、响应或事件中。
 
 ### 响应
 
@@ -336,9 +354,13 @@ result = await client.call("message.thought.get", {
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `messages` | array | 消息列表（按 seq 升序）。消息对象含 `encrypted` 字段（仅 `encrypted=true` 时出现） |
+| `messages` | array | 持久与 volatile 消息按服务端时间合并；持久消息子序列仍按 `seq` 升序。消息对象含 `encrypted` 字段（仅 `encrypted=true` 时出现） |
 | `count` | integer | 本次返回的消息数 |
-| `latest_seq` | integer | 返回的最大 seq |
+| `latest_seq` | integer | 返回的最大 seq |
+| `latest_volatile_cursor` | string\|null | 本页最后一个 volatile 游标；不影响 `latest_seq` |
+| `volatile_has_more` | boolean | 是否仍有未返回的 volatile 消息；SDK 在 volatile cursor 前进时据此继续分页 |
+| `volatile_earliest_cursor` | string\|null | 当前 boot epoch 内仍可读取的最早 volatile 游标 |
+| `volatile_dropped_count` | integer | 当前 boot epoch 内因过期或容量淘汰而不可读的累计数 |
 | `server_ack_seq` | integer | 服务端已确认的 ack_seq（仅设备视图路径返回）。客户端用此值跳过 retention window 之外的空洞 |
 | `retention_floor_seq` | integer | 持久化保留窗口的下界 seq；seq 小于等于此值的消息已过期不可再拉取 |
 | `earliest_available_seq` | integer\|null | 当前可拉取的最小 seq（`retention_floor_seq + 1`）；`retention_floor_seq=0` 时为 `null` |
@@ -347,6 +369,8 @@ result = await client.call("message.thought.get", {
 
 `message.pull` 是公开的 Forward Pull。实时 A/T/H 最新页同步由 SDK 内部自动完成，不提供需要应用传入的模式参数。Forward 页通过结构校验后，本地 A 按原始页最大 seq 推进。页内缺号视为服务端永久空号；单条解密失败通过 `message.undecryptable` 报告，不阻塞后续水位。Forward 仍支持 Piggy ACK：存在待提交 ACK 时，即使当前页非满页也会再拉一页并携带 ACK，空页后停止。
 
+四个 SDK 只让含正 `seq` 的持久消息进入 seq tracker。volatile push 与 pull 在进程内按发送方和 `message_id` 去重，成功交付后自动 ACK；epoch 不匹配时清空本地 volatile 游标并重试一次。`message.history` 永远不返回 volatile 消息。
+
 `message.pull` 与 `message.history` 进入当前 `AUNClient` 的客户端级 Pull Gate。该 Gate 与 Group Message、Group Event Pull 共享，始终 single-inflight；相同请求 key 折叠并共享结果，不同 key 按前台 FIFO（Tail/History）优先于后台 FIFO（Forward/Gap Fill/Group Event）排队。不同 `AUNClient` 实例之间不共享 Gate，应用层无需自行实现并发控制。
 
 解密当前消息时若缺少 sender IK，SDK 会把同发送端请求 single-flight 合并，最多同步等待 3 秒执行 bootstrap；获取成功立即重试当前消息，失败或超时才进入 pending。该补救不改变 Forward 按原始页推进 A 的规则。
@@ -395,7 +419,7 @@ while page.get("has_older"):
 
 ## message.ack
 
-确认已收到消息。推进接收方的 ack_seq 游标。
+确认已收到消息。持久 ACK 与 volatile ACK 可以单独提交，也可以在同一请求中提交。
 
 ### 请求
 
@@ -404,9 +428,9 @@ while page.get("has_older"):
     "jsonrpc": "2.0",
     "method": "message.ack",
     "params": {
-        "seq": 150,
-        "device_id": "device-001",
-        "slot_id": "slot-a"
+        "seq": 150,
+        "volatile_cursors": ["v1:i1:7:21"],
+        "device_id": "device-001"
     },
     "id": 3
 }
@@ -416,11 +440,13 @@ while page.get("has_older"):
 
 | 参数 | 类型 | 必填 | 默认值 | 说明 |
 |------|------|------|--------|------|
-| `seq` | integer | 是 | — | 确认 seq ≤ 此值的所有消息 |
-| `device_id` | string | 否 | 当前连接实例 | 多实例消费上下文中的设备标识 |
-| `slot_id` | string | 否 | 当前连接实例 | 同一设备下的消费槽位；可用 `/`、`:`、空格表达共享隔离键，如 `evolclaw cli` |
-
-> 四个 SDK 都会自动为 `message.ack` 注入当前实例的 `device_id` / `slot_id`。显式传入 `slot_id` 时按 `slotIsolationKey` 比较，`evolclaw cli` 与 `evolclaw daemon` 视为同一隔离键；不同隔离键会在发出 RPC 前被拒绝。
+| `seq` | integer | 否 | — | 确认 seq ≤ 此值的所有持久消息；未提交 volatile ACK 时必填 |
+| `volatile_cursor` | string | 否 | — | 单个 volatile 游标的兼容形式 |
+| `volatile_cursors` | string[] | 否 | — | 确认指定 volatile 游标；可独立于 `seq` 使用 |
+| `volatile_ids` | string[] | 否 | — | 按 `message_id` 确认 volatile 消息 |
+| `device_id` | string | 否 | 当前连接实例 | 多实例消费上下文中的设备标识 |
+
+> 四个 SDK 在传输层注入当前消费实例的内部 slot；应用不传入或读取 slot。
 
 ### 响应
 
@@ -437,8 +463,9 @@ while page.get("has_older"):
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `success` | boolean | 操作是否成功 |
-| `ack_seq` | integer | 本次推进到的 ack_seq |
+| `success` | boolean | 操作是否成功 |
+| `ack_seq` | integer | 本次推进到的 ack_seq |
+| `volatile_ack` | object | volatile ACK 的 `accepted`、`expired` 等幂等结果；只提交持久 ACK 时可省略 |
 
 ### 副作用
 
@@ -574,7 +601,8 @@ result = await client.call("message.ack", {"seq": 150})
         "encrypted": false
     },
     "message_id": "uuid-1",
-    "from": "alice.agentid.pub",
+    "from": "alice.agentid.pub",
+    "sender_device_id": "alice-phone",
     "to": "bob.agentid.pub",
     "seq": 42,
     "timestamp": 1234567890000,
@@ -594,7 +622,9 @@ result = await client.call("message.ack", {"seq": 150})
 }
 ```
 
-SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；信封字段统一放在 `envelope`。`envelope` 只保留可转发的归一化元数据，`from` 由 `from_aid` / `sender_aid` 归一化而来，`timestamp` 由 `created_at` / `t_server` 归一化而来。0.5.x 当前仍保留顶层 `message_id` / `from` / `to` / `seq` / `timestamp` 等兼容别名；新代码应优先通过 `msg["envelope"]["from"]`、`msg["envelope"]["timestamp"]` 等路径访问。`envelope.agent_md.sender` / `envelope.agent_md.group` 是 agent.md 云端版本提示，SDK 会自动观察并写入本地 `remote_etag`。Gateway 可能附加 `proximity` 及 `same_device` / `same_egress_ip` / `same_network`，表示由 Gateway 基于连接上下文判断的近端关系提示，不参与 E2EE AAD 或业务鉴权。
+SDK 交付给应用层的 `payload` 是明文业务 JSON 对象；信封字段统一放在 `envelope`。`sender_device_id` 是发送方设备标识，四个 SDK 均会保留给应用层，可用于把回复定向到原发送设备。`envelope` 只保留可转发的归一化元数据，`from` 由 `from_aid` / `sender_aid` 归一化而来，`timestamp` 由 `created_at` / `t_server` 归一化而来。0.5.x 当前仍保留顶层 `message_id` / `from` / `to` / `seq` / `timestamp` 等兼容别名；新代码应优先通过 `msg["envelope"]["from"]`、`msg["envelope"]["timestamp"]` 等路径访问。`envelope.agent_md.sender` / `envelope.agent_md.group` 是 agent.md 云端版本提示，SDK 会自动观察并写入本地 `remote_etag`。Gateway 可能附加 `proximity` 及 `same_device` / `same_egress_ip` / `same_network`，表示由 Gateway 基于连接上下文判断的近端关系提示，不参与 E2EE AAD 或业务鉴权。
+
+volatile 事件额外包含 `storage="volatile"`、`volatile_cursor`、`created_at` 和 `expires_at`，不含持久 `seq`。四个 SDK 保留这些字段、自动去重和 ACK，并确保应用可见对象不含内部 slot。
 
 ### 订阅
 

package/_packed_docs/sdk/09-storage-rpc-manual.md

@@ -120,7 +120,11 @@
 
 ## SDK 封装状态
 
-Python / Go / TypeScript / JavaScript SDK 均提供 storage low-level 与 VFS 门面。普通应用优先使用 SDK VFS：`write_bytes` / `upload_file` 会先 `check_upload`，小对象走 `put_object`，大对象走 `create_upload_session` → HTTP PUT → `complete_upload`，秒传路径用 `complete_upload(skip_blob=true)`；`read_bytes` / `download_file` 优先尝试 inline `get_object`，超限时回退 `create_download_ticket`；`touch` 直接封装 `storage.fs.touch`。需要精确控制 ACL、token、软链、卷、批量操作或 URL 字段时，再直接调用本手册中的 `storage.*` RPC。
+Python / Go / TypeScript / JavaScript SDK 均提供 storage low-level 与 VFS 门面。普通应用优先使用 SDK VFS：`write_bytes` / `upload_file` 会先 `check_upload`，小对象走 `put_object`，大对象走 `create_upload_session` → HTTP PUT → `complete_upload`，秒传路径用 `complete_upload(skip_blob=true)`；`read_bytes` / `download_file` 优先尝试 inline `get_object`，超限时回退 `create_download_ticket`；`touch` 直接封装 `storage.fs.touch`。需要精确控制 ACL、token、软链、卷、批量操作或 URL 字段时，再直接调用本手册中的 `storage.*` RPC。
+
+四个 SDK 的 VFS 会优先按实际字节识别 PNG、JPEG、GIF、BMP、WebP、PDF、gzip、ZIP、MP4、JSON、HTML 和 UTF-8 文本，再回退文件扩展名及 `application/octet-stream`。大文件上传时，`create_upload_session`、HTTP PUT 和 `complete_upload` 使用同一个 `Content-Type`；如果 session 响应额外提供 `headers`，SDK 会保留其它 header 并以实际识别结果替换其中的 Content-Type。OSS 预签名 PUT 会把 Content-Type 纳入签名校验，缺失或不一致时可直接返回 403。
+
+直接调用底层 RPC 的高级客户端必须自行完成相同编排：先确定内容类型，再把同一个值传给 session 和 complete，并在 PUT 请求中发送一致的 `Content-Type`。绕过 VFS 后未遵守该约束属于调用方式错误。
 
 ## storage.put_object
 
@@ -561,22 +565,27 @@ for obj in result["items"]:
 
 ### 响应
 
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `upload_url` | string | 上传用 presigned URL |
-| `blob_key` | string | Blob 存储 key |
-| `expire_at` | integer | URL 过期时间戳 |
-| `owner_aid` | string | 所有者 AID |
-| `bucket` | string | 存储桶 |
-| `object_key` | string | 对象路径 |
-| `content_type` | string | MIME 类型 |
-| `size_bytes` | integer | 声明的文件大小 |
-
-客户端获得 `upload_url` 后，通过 HTTP PUT 上传文件数据。
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `upload_url` | string | 上传用 presigned URL |
+| `expire_at` | integer | URL 过期时间戳 |
+| `owner_aid` | string | 所有者 AID |
+| `bucket` | string | 存储桶 |
+| `object_key` | string | 对象路径 |
+| `name` | string | 对象名称 |
+| `path` | string | 对象路径 |
+| `path_url` | string | Storage path URL |
+| `url` / `download_url` | string | AID 风格对象 URL |
+| `logical_url` | string | Storage 直链 URL |
+| `content_type` | string | MIME 类型 |
+| `size_bytes` | integer | 声明的文件大小 |
+| `overwrite` | boolean | 是否覆盖已有对象 |
+
+客户端获得 `upload_url` 后，通过 HTTP PUT 上传文件数据。当前服务响应不包含 `blob_key`、`session_id` 或 `headers`；调用方不得依赖这些字段。
 
 > 当前实现会对 BlobStore 返回的 loopback URL 做对外地址规范化：优先使用 `KITE_STORAGE_EXTERNAL_URL`，否则按 `storage.{issuer}` 形式改写。对外地址不可使用 `127.0.0.1` 或 `localhost`。
 
-> 当前实现不会在 `create_upload_session` 阶段强校验配额或最终文件大小；这些检查会在 `storage.complete_upload` 阶段执行。
+> 当前实现会在 `create_upload_session` 阶段按声明的 `size_bytes` 校验最大文件限制；实际 blob 大小、SHA-256 和配额在 `storage.complete_upload` 阶段校验。
 
 ---