@agentunion/fastaun 0.5.0 → 0.5.1

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

@@ -59,7 +59,7 @@
 
 ### POSIX VFS 方法
 
-> 在对象存储之上提供 Linux 文件系统语义（`ls/find/df/stat/mkdir/rm/mv/cp/mount`）。节点类型：`file` / `dir` / `symlink` / `mount`。
+> 在对象存储之上提供 Linux 文件系统语义（`ls/find/df/stat/lstat/mkdir/touch/rm/mv/cp/mount`）。节点类型：`file` / `dir` / `symlink` / `mount`。
 
 | 方法 | 说明 |
 |------|------|
@@ -69,6 +69,7 @@
 | [storage.fs.stat](#storagefsstat) | 查节点（stat，跟随末级软链） |
 | [storage.fs.lstat](#storagefslstat) | 查节点（lstat，不跟随软链） |
 | [storage.fs.mkdir](#storagefsmkdir) | 建目录（mkdir） |
+| [storage.fs.touch](#storagefstouch) | 创建空文件或更新时间戳（touch） |
 | [storage.fs.remove](#storagefsremove) | 删除文件/目录/软链（rm） |
 | [storage.fs.rename](#storagefsrename) | 同 owner 内移动/改名（mv） |
 | [storage.fs.copy](#storagefscopy) | 复制对象或软链（cp） |
@@ -91,6 +92,8 @@
 ### ACL / 权限方法
 
 > 统一权限求值顺序（硬顺序）：公开位 → token → ACL（最近祖先前缀）→ 角色 → owner → 拒绝。
+>
+> AID storage 的 `storage.set_acl/remove_acl` 面向具体 AID，当前主要用于写/删除授权；直接读授权不通过 ACL 下发，读访问应使用 `storage.create_share_link` / `storage.get_by_share`，撤销分享使用 `storage.revoke_share_link`。`role:*` 伪主体只允许可信 group 内部门面管理，客户端不得直接对 `group_aid` 空间设置角色 ACL；群自有区 admin 写授权使用 `group.fs.set_acl/remove_acl`。
 
 | 方法 | 说明 |
 |------|------|
@@ -113,15 +116,15 @@
 
 ---
 
-> `object_key` 当前仅支持 ASCII 安全字符集合 `[A-Za-z0-9._/-]`，且不允许空路径段、`..`、反斜杠转义后的非法段。
-
-## 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`。需要精确控制 ACL、token、软链、卷、批量操作或 URL 字段时，再直接调用本手册中的 `storage.*` RPC。
-
-## storage.put_object
-
-上传小对象（内容 base64 编码通过 RPC 传输）。
+> `object_key` 当前仅支持 ASCII 安全字符集合 `[A-Za-z0-9._/-]`，且不允许空路径段、`..`、反斜杠转义后的非法段。
+
+## 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。
+
+## storage.put_object
+
+上传小对象（内容 base64 编码通过 RPC 传输）。
 
 ### 参数
 
@@ -885,7 +888,7 @@ share_url = result["url"]  # https://alice.agentid.pub/s/Ab3xK9mZ2q
 
 ## storage.fs.list
 
-列目录（POSIX `ls`）。混合返回子目录/对象/软链/可用挂载点，排序 dir < file < symlink < mount。群 owner 路径回退到 Group FS 子节点。
+列目录（POSIX `ls`）。混合返回子目录/对象/软链/可用挂载点，排序 dir < file < symlink < mount。群 owner 路径回退到 Group FS 子节点。
 
 ### 参数
 
@@ -915,7 +918,7 @@ share_url = result["url"]  # https://alice.agentid.pub/s/Ab3xK9mZ2q
 
 ## storage.fs.find
 
-递归查找（POSIX `find`），支持 name/type/size/mtime 过滤与分页。Group FS 与 `.collab` 注册表有回退。
+递归查找（POSIX `find`），支持 name/type/size/mtime 过滤与分页。Group FS 与 `.collab` 注册表有回退。
 
 ### 参数
 
@@ -1014,6 +1017,36 @@ fs 目录节点视图。
 
 ---
 
+## storage.fs.touch
+
+创建空文件或刷新已有节点的修改时间（POSIX `touch`）。已存在的文件、目录或软链会更新时间戳；不存在时默认创建 0 字节私有文件；`no_create=true` 时不存在不创建并返回 `{touched:false, created:false}`。
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认 | 说明 |
+|------|------|------|------|------|
+| `path` | string | 是 | — | 目标路径 |
+| `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
+| `bucket` | string | 否 | `"default"` | 存储桶 |
+| `parents` | boolean | 否 | `false` | 创建文件时是否递归创建父目录 |
+| `no_create` / `noCreate` | boolean | 否 | `false` | 目标不存在时不创建 |
+| `mtime` | integer | 否 | 当前时间 | Unix 秒或毫秒；小于 `10000000000` 按秒解释 |
+| `follow_symlinks` / `followSymlinks` | boolean | 否 | `false` | 目标为软链时是否跟随末级软链 |
+| `content_type` | string | 否 | `"application/octet-stream"` | 新建空文件的 MIME 类型 |
+| `metadata` | object | 否 | `{}` | 新建空文件的元数据 |
+| `expire_in_seconds` | integer | 否 | `0` | 新建空文件的过期秒数 |
+
+### 响应
+
+成功返回 fs 节点视图，并额外包含：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `touched` | boolean | 是否实际更新或创建 |
+| `created` | boolean | 是否新建了空文件 |
+
+---
+
 ## storage.fs.remove
 
 删除文件/目录/软链（POSIX `rm`，目录用 `recursive`）。**拒绝删除挂载点**（须先 unmount）。
@@ -1107,6 +1140,8 @@ fs 目录节点视图。
 | `mount` | object | 挂载视图 |
 | `status` | string | `active`（直接生效）/ `pending`（待批准） |
 
+> `status` 字段仅在直接调用 lowlevel RPC（`fs_mount`/`FSMount`/`fsMount` 原始返回）时可见。四语言 SDK 的高层 VFS 门面（`vfs.mount()`/`StorageVFS.Mount()`/`vfs.mount()`）会把响应解析为通用 NodeView，该视图不保留顶层 `status` 字段；需要判断是否 `pending` 时请改用 lowlevel 接口读取原始响应，或检查服务端在 `pending` 场景下额外写入的 `request_id`。
+
 ---
 
 ## storage.fs.approve
@@ -1219,7 +1254,7 @@ fs 目录节点视图。
 
 ## storage.atomic_repoint
 
-原子重指软链 target（乐观锁 CAS）。**collab commit / tag 并发正确性的底层核心**。
+原子重指软链 target（乐观锁 CAS）。**collab commit / tag 并发正确性的底层核心**。
 
 ### 参数
 
@@ -1280,14 +1315,16 @@ fs 目录节点视图。
 
 ## storage.set_acl
 
-授予路径前缀 ACL grant（群内部 admin 或群代理写授权）。支持 `role:<role>` 形式 grantee。ACL 对目录前缀授权，子路径默认继承（最近祖先覆盖）。
+授予路径前缀 ACL grant。普通 AID storage 的 `grantee_aid` 必须是具体 AID，主要用于授予写/删除权限；子路径默认继承（最近祖先覆盖）。读取不通过 AID ACL 直接授权，应用应改用 `storage.create_share_link` 并在需要时用 `storage.revoke_share_link` 撤销。
+
+`role:*` 伪主体只允许可信 group 内部门面写入。客户端不能直接对 `group_aid` 空间调用 `storage.set_acl` 设置 `role:admin`；群自有区角色写授权统一使用 `group.fs.set_acl`。
 
 ### 参数
 
 | 参数 | 类型 | 必填 | 默认 | 说明 |
 |------|------|------|------|------|
 | `path` | string | 是 | — | 授权路径前缀 |
-| `grantee_aid` | string | 是 | — | 被授权 AID（或 `role:<role>`） |
+| `grantee_aid` | string | 是 | — | 被授权 AID；`role:*` 仅限 group 内部调用 |
 | `perms` | string | 是 | — | 权限位：`r`/`w`/`rw`/`rwx`（`rwx` 含删除） |
 | `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
 | `bucket` | string | 否 | `"default"` | 存储桶 |
@@ -1302,7 +1339,7 @@ ACL 视图。
 
 ## storage.remove_acl
 
-移除路径 ACL 授权。
+移除路径 ACL 授权。对 AID storage，这是撤销写/删除授权的入口；读分享的撤销入口是 `storage.revoke_share_link`。群自有区角色写授权撤销使用 `group.fs.remove_acl`，不要由客户端直接调用 `storage.remove_acl` 操作 `role:*`。
 
 ### 参数
 
@@ -1339,7 +1376,7 @@ ACL 视图。
 
 ## storage.set_visibility
 
-切换对象或目录的公开/私有（软链不支持）。`allow_roles` 替换 `role:` 类 ACL。
+切换对象或目录的公开/私有（软链不支持）。`allow_roles` 是低层兼容字段，不能作为群自有区 admin 写授权入口；群自有区角色写授权必须使用 `group.fs.set_acl/remove_acl`。
 
 ### 参数
 
@@ -1349,7 +1386,7 @@ ACL 视图。
 | `visibility` | string | 是 | — | `public` / `private` |
 | `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
 | `bucket` | string | 否 | `"default"` | 存储桶 |
-| `allow_roles` | array | 否 | — | 允许的角色列表（替换 role ACL） |
+| `allow_roles` | array | 否 | — | 低层兼容字段，仅表示可见性读角色；不能用于群自有区写授权 |
 
 ### 响应
 
@@ -1502,4 +1539,4 @@ token 列表（hash 摘要 + 元数据）。
 | -32004 | 权限拒绝（requester 不是对象 owner，或非公开对象的读权限不足） |
 | -32008 | 对象不存在（`ErrNotFound`） |
 | -32009 | 版本冲突（`ErrVersionConflict`，`expected_version` 与实际版本不匹配） |
-| -32000 | 通用错误（参数校验失败、配额不足、base64 解码失败、文件大小超限等） |
+| -32000 | 通用错误（参数校验失败、配额不足、base64 解码失败、文件大小超限等） |

package/_packed_docs/sdk/AUN_DOCS_GUIDE.md

@@ -11,10 +11,10 @@ AUN SDK 文档位于 `docs/sdk/`，索引文件 `docs/sdk/INDEX.md` 分三层：
 - `AUNClient`：认证、连接、状态机、事件和 RPC。
 - `ServiceProxyClient`：Python SDK 的 Service Proxy provider 侧客户端，负责 Gateway 控制面注册和 proxy-server 数据面隧道注册。
 
-业务 RPC 的底层参数见 `09-*-rpc-manual.md`，可通过 `client.call(method, params)` 调用；Storage、Collab、Group FS、Service Proxy 等具备高层门面的能力以对应专项文档为准。`message.send`、`message.thought.put`、`group.send`、`group.thought.put` 的业务 payload 见 `09-payload-reference.md`。在线轻量通知和跨域 federation notify 方案见 `Notify通知方案.md`。
-
-Storage 的 SDK VFS、控制面/数据面分离、direct backend 上传下载、类 Linux 权限、mount/symlink 和服务端分层见 `AUN Storage架构设计.md`。
-Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI、`cp/mv` 语义、群自有区 `group_aid` 写身份、`parents` 语义、JS string 差异和 memberdata 服务端映射见 `09-group-rpc-manual.md`。Collab 的 `gc`、`reflog`、`revert`、`clone` 及版本化文档/标签语义见 `09-collab-rpc-manual.md`。
+业务 RPC 的底层参数见 `09-*-rpc-manual.md`，可通过 `client.call(method, params)` 调用；Storage、Collab、Group FS、Service Proxy 等具备高层门面的能力以对应专项文档为准。`message.send`、`message.thought.put`、`group.send`、`group.thought.put` 的业务 payload 见 `09-payload-reference.md`。在线轻量通知和跨域 federation notify 方案见 `Notify通知方案.md`。
+
+Storage 的 SDK VFS、控制面/数据面分离、direct backend 上传下载、类 Linux 权限、mount/symlink 和服务端分层见 `AUN Storage架构设计.md`。
+Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI、`cp/mv` 语义、群自有区角色 ACL 授权/撤销/查询与 `group_aid` 签名、`parents` 语义、JS string 差异和 memberdata 服务端映射见 `09-group-rpc-manual.md`。Collab 的 `gc`、`reflog`、`revert`、`clone` 及版本化文档/标签语义见 `09-collab-rpc-manual.md`。
 
 ## 渐进式查阅流程
 
@@ -29,10 +29,10 @@ Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI
 - 身份与认证：AIDStore / AID / 注册 / 加载 / 证书
 - 连接与状态：AUNClient / 九态状态机 / Gateway / 重连
 - E2EE：默认加密、ProtectedHeaders、P2P / Group V2
-- RPC 与事件：`client.call()`、`client.on()`、`client.notify()`、RPC 手册
-- Storage：SDK VFS、direct backend 数据面、`storage.*` low-level RPC、类 Linux 权限、mount/symlink、Storage Service 分层
-- 群文件系统：`group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` 上传下载、群自有区 `group_aid` 写身份、`parents`、JS string 差异和 memberdata 服务端映射（见 `09-group-rpc-manual.md`）
-- 协作（collab）：`collab.*` 版本化文档、乐观锁 CAS commit、三方合并、标签、GC、reflog、revert（见 `09-collab-rpc-manual.md`）
+- RPC 与事件：`client.call()`、`client.on()`、`client.notify()`、RPC 手册
+- Storage：SDK VFS、direct backend 数据面、`storage.*` low-level RPC、类 Linux 权限、mount/symlink、Storage Service 分层
+- 群文件系统：`group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` 上传下载、群自有区角色 ACL 与 `group_aid` 签名、`parents`、JS string 差异和 memberdata 服务端映射（见 `09-group-rpc-manual.md`）
+- 协作（collab）：`collab.*` 版本化文档、乐观锁 CAS commit、三方合并、标签、GC、reflog、revert（见 `09-collab-rpc-manual.md`）
 - Service Proxy：`ServiceProxyClient`、`proxy.register_services`、proxy-server `register_services`
 - agent.md：`AIDStore.upload_agent_md()`、`AIDStore.download_agent_md()`、`AIDStore.check_agent_md()`
 - 错误处理：Result、异常、错误码、重试
@@ -68,11 +68,11 @@ Group FS 的 `group.fs.*` RPC、`client.group.fs.*` 门面、`aun group fs` CLI
 | 发布、下载或检查 agent.md | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md) |
 | 状态机和重连 | [03-核心概念](03-核心概念.md)、[04-连接与认证](04-连接与认证.md) |
 | 查方法签名 | [06-API手册](06-API手册.md) |
-| 查消息或群组 RPC | 对应 `09-*-rpc-manual.md` |
-| 查群文件系统 RPC / SDK / CLI 入口、群自有区写身份、`parents` 和 JS string 差异 | [09-group-rpc-manual.md](09-group-rpc-manual.md)、[06-API手册](06-API手册.md) |
-| 查 Storage 架构、SDK VFS、权限模型、mount/symlink 和上传下载链路 | [AUN Storage架构设计.md](<AUN Storage架构设计.md>) |
-| 查 Storage RPC 参数 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) |
-| 查协作（版本化文档/乐观锁/标签/GC/reflog/revert）RPC | [09-collab-rpc-manual.md](09-collab-rpc-manual.md) |
+| 查消息或群组 RPC | 对应 `09-*-rpc-manual.md` |
+| 查群文件系统 RPC / SDK / CLI 入口、群自有区角色 ACL 授权/撤销/查询、`parents` 和 JS string 差异 | [09-group-rpc-manual.md](09-group-rpc-manual.md)、[06-API手册](06-API手册.md) |
+| 查 Storage 架构、SDK VFS、权限模型、mount/symlink 和上传下载链路 | [AUN Storage架构设计.md](<AUN Storage架构设计.md>) |
+| 查 Storage RPC 参数 | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) |
+| 查协作（版本化文档/乐观锁/标签/GC/reflog/revert）RPC | [09-collab-rpc-manual.md](09-collab-rpc-manual.md) |
 | 查 notify 在线轻量通知 / 跨域 federation | [Notify通知方案.md](Notify通知方案.md) |
 | 查 Service Proxy 服务注册和路由 | [06-API手册](06-API手册.md)、[09-proxy-rpc-manual.md](09-proxy-rpc-manual.md) |
 | 查 payload 格式 | [09-payload-reference.md](09-payload-reference.md) |

package/_packed_docs/sdk/INDEX.md

@@ -19,12 +19,12 @@
 | [08-最佳实践](08-最佳实践.md) | 幂等连接 · 多 AID · 资源清理 · 测试数据保护 |
 | [09-payload-reference](09-payload-reference.md) | message / group / thought payload 格式 |
 | [09-message-rpc-manual](09-message-rpc-manual.md) | P2P 消息 RPC |
-| [09-group-rpc-manual](09-group-rpc-manual.md) | 群组 RPC（含 `group.fs.*` 群文件系统 RPC、群自有区写身份和 `parents` 语义） |
-| [09-storage-rpc-manual](09-storage-rpc-manual.md) | 存储 RPC（对象 + POSIX VFS / 卷 / 软链 / ACL / token） |
-| [09-collab-rpc-manual](09-collab-rpc-manual.md) | 协作 RPC（版本化文档 / 乐观锁 / 三方合并 / 标签 / GC / reflog / revert） |
-| [group.fs POSIX 化详细设计](../aun-fs/group-fs/group.fs-POSIX化详细设计.md) | 下一版 `client.group.fs.*` / `aun group fs` / `group.fs.*` 群文件系统设计，含群自有区写身份、`parents` 和 JS string 语义 |
-| [group.fs POSIX 化分阶段实施计划](../aun-fs/group-fs/group.fs-POSIX化分阶段实施计划.md) | group.fs 重构的 IPO、Step-by-step、用例集、Checklist、验收和回滚 |
-| [AUN Storage架构设计](<AUN Storage架构设计.md>) | Storage SDK VFS、控制面/数据面分离、服务端分层、类 Linux 权限、mount/symlink 与关键时序 |
+| [09-group-rpc-manual](09-group-rpc-manual.md) | 群组 RPC（含 `group.fs.*` 群文件系统 RPC、群自有区角色 ACL 授权/撤销/查询和 `parents` 语义） |
+| [09-storage-rpc-manual](09-storage-rpc-manual.md) | 存储 RPC（对象 + POSIX VFS / 卷 / 软链 / ACL / token） |
+| [09-collab-rpc-manual](09-collab-rpc-manual.md) | 协作 RPC（版本化文档 / 乐观锁 / 三方合并 / 标签 / GC / reflog / revert） |
+| [group.fs POSIX 化详细设计](../aun-fs/group-fs/group.fs-POSIX化详细设计.md) | `client.group.fs.*` / `aun group fs` / `group.fs.*` 群文件系统设计，含群自有区角色 ACL、`parents` 和 JS string 语义 |
+| [group.fs POSIX 化分阶段实施计划](../aun-fs/group-fs/group.fs-POSIX化分阶段实施计划.md) | group.fs 重构的 IPO、Step-by-step、用例集、Checklist、验收和回滚 |
+| [AUN Storage架构设计](<AUN Storage架构设计.md>) | Storage SDK VFS、控制面/数据面分离、服务端分层、类 Linux 权限、mount/symlink 与关键时序 |
 | [09-meta-rpc-manual](09-meta-rpc-manual.md) | meta RPC 和信任根 |
 | [09-stream-rpc-manual](09-stream-rpc-manual.md) | stream RPC |
 | [09-proxy-rpc-manual](09-proxy-rpc-manual.md) | Service Proxy 控制面 RPC 和数据面隧道注册 |
@@ -62,12 +62,12 @@
 
 - `client.call()` / `client.on()` → [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md)
 - `client.notify()` 在线轻量通知、跨域 federation、在线/离线边界 → [Notify通知方案](Notify通知方案.md)
-- Message RPC → [09-message-rpc-manual](09-message-rpc-manual.md)
-- Group RPC 与群文件系统 `group.fs.*` 控制面、群自有区写身份和 `parents` 语义 → [09-group-rpc-manual](09-group-rpc-manual.md)
-- 下一版群文件系统 `group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` POSIX 化语义和 JS string 差异 → [group.fs POSIX 化详细设计](../aun-fs/group-fs/group.fs-POSIX化详细设计.md)、[分阶段实施计划](../aun-fs/group-fs/group.fs-POSIX化分阶段实施计划.md)
-- Storage 架构、SDK VFS、控制面/数据面分离、类 Linux 权限和 mount/symlink → [AUN Storage架构设计](<AUN Storage架构设计.md>)
-- Storage RPC（对象 + `storage.fs.*` / `storage.volume.*` / 软链 / ACL / token）→ [09-storage-rpc-manual](09-storage-rpc-manual.md)
-- Collab RPC（`collab.*` 版本化文档、乐观锁、标签、GC、reflog、revert）→ [09-collab-rpc-manual](09-collab-rpc-manual.md)
+- Message RPC → [09-message-rpc-manual](09-message-rpc-manual.md)
+- Group RPC 与群文件系统 `group.fs.*` 控制面、群自有区角色 ACL 授权/撤销/查询和 `parents` 语义 → [09-group-rpc-manual](09-group-rpc-manual.md)
+- 下一版群文件系统 `group.fs.*`、`client.group.fs.*`、`aun group fs`、`cp/mv` POSIX 化语义和 JS string 差异 → [group.fs POSIX 化详细设计](../aun-fs/group-fs/group.fs-POSIX化详细设计.md)、[分阶段实施计划](../aun-fs/group-fs/group.fs-POSIX化分阶段实施计划.md)
+- Storage 架构、SDK VFS、控制面/数据面分离、类 Linux 权限和 mount/symlink → [AUN Storage架构设计](<AUN Storage架构设计.md>)
+- Storage RPC（对象 + `storage.fs.*` / `storage.volume.*` / `storage.fs.touch` / 软链 / ACL / token）→ [09-storage-rpc-manual](09-storage-rpc-manual.md)
+- Collab RPC（`collab.*` 版本化文档、乐观锁、标签、GC、reflog、revert）→ [09-collab-rpc-manual](09-collab-rpc-manual.md)
 - Meta RPC → [09-meta-rpc-manual](09-meta-rpc-manual.md)
 - Stream RPC → [09-stream-rpc-manual](09-stream-rpc-manual.md)
 - Service Proxy RPC 和隧道注册 → [09-proxy-rpc-manual](09-proxy-rpc-manual.md)
@@ -118,7 +118,7 @@
 
 ### 09-*-rpc-manual
 
-各业务服务的 RPC 参数、响应和错误语义。Storage、Collab、Group FS、Service Proxy 等明确提供高层门面的能力应优先使用门面；需要精确控制底层参数时再通过 `client.call()` 调用业务 RPC。
+各业务服务的 RPC 参数、响应和错误语义。Storage、Collab、Group FS、Service Proxy 等明确提供高层门面的能力应优先使用门面；需要精确控制底层参数时再通过 `client.call()` 调用业务 RPC。
 
 ### AUN Storage架构设计
 
@@ -126,7 +126,7 @@
 
 ### 09-collab-rpc-manual
 
-定义协作层 `collab.*` RPC（共 21 个）：文档版本线（ls-files/create/show/commit/merge/log/diff/revert/prune）、运维备份迁移（gc/reflog/clone）、目录级标签（tag.create/list/show/diff/restore/rm/prune）、群内发现（ls-remote/unregister）。collab 编排并入 storage 服务进程，以调用者身份直调 storage 原语，授权下沉到 storage ACL。涵盖乐观锁 CAS commit 撞版本响应、三方合并冲突标记、forward-only 标签回滚、垃圾扫描和审计日志语义。
+定义协作层 `collab.*` RPC（共 21 个）：文档版本线（ls-files/create/show/commit/merge/log/diff/revert/prune）、运维备份迁移（gc/reflog/clone）、目录级标签（tag.create/list/show/diff/restore/rm/prune）、群内发现（ls-remote/unregister）。collab 编排并入 storage 服务进程，以调用者身份直调 storage 原语，授权下沉到 storage ACL。涵盖乐观锁 CAS commit 撞版本响应、三方合并冲突标记、forward-only 标签回滚、垃圾扫描和审计日志语义。
 
 ### 09-proxy-rpc-manual
 

package/dist/client/delivery.d.ts

@@ -59,6 +59,15 @@ export declare class MessageDeliveryEngine {
     restoreSeqTrackerState(): void;
     migrateSeqStateGroupIds(state: Record<string, number>): Record<string, number>;
     saveSeqTrackerState(): void;
+    persistSeq(ns: string, forceSeq?: number): void;
+    flushSeqTrackerPending(): void;
+    private dropSeqTrackerPending;
+    private currentSeqTrackerContext;
+    private seqTrackerPending;
+    private mergeSeqTrackerPending;
+    private scheduleSeqTrackerFlush;
+    private cancelSeqTrackerFlushTimer;
+    private writeSeqTrackerState;
     persistRepairedSeq(ns: string): void;
     clampAckSeq(method: string, field: string, ns: string, seq: number): number;
     clampAckParams(method: string, params: RpcParams): RpcParams;

package/dist/client/delivery.js

@@ -1,9 +1,10 @@
 import { slotIsolationKey } from '../config.js';
 import { normalizeGroupId } from '../group-id.js';
-import { isJsonObject } from '../types.js';
+import { ConnectionState, isJsonObject } from '../types.js';
 const PUSHED_SEQS_LIMIT = 50_000;
 const PENDING_ORDERED_LIMIT = 50_000;
 const GROUP_RECALL_SEEN_LIMIT = 10_000;
+const SEQ_TRACKER_PERSIST_FLUSH_DELAY_MS = 200;
 const APP_MESSAGE_ENVELOPE_KEYS = [
     'module_id', 'message_type', 'type', 'kind', 'version',
     'from', 'from_aid', 'sender_aid', 'to', 'to_aid', 'group_id',
@@ -95,7 +96,8 @@ export class MessageDeliveryEngine {
             const eventPayload = payload;
             client._groupState?.handleGroupChangedV2Membership?.(eventPayload);
             if (eventPayload.action === 'dissolved') {
-                const groupId = normalizeGroupId(String(eventPayload.group_id ?? '')) || String(eventPayload.group_id ?? '').trim();
+                const rawGroupId = eventPayload.group_aid ?? eventPayload.group_id ?? '';
+                const groupId = normalizeGroupId(String(rawGroupId)) || String(rawGroupId).trim();
                 if (groupId)
                     client._cleanupDissolvedGroup?.(groupId);
             }
@@ -495,7 +497,7 @@ export class MessageDeliveryEngine {
                 .catch((e) => { client._clientLog.debug(`group recall auto-ack failed: group=${groupId} ${formatDeliveryError(e)}`); });
         }
         if (contig !== contigBefore)
-            this.saveSeqTrackerState();
+            this.persistSeq(ns);
     }
     publishAppEvent(event, payload, source = 'direct') {
         const client = this.runtime.client;
@@ -565,6 +567,8 @@ export class MessageDeliveryEngine {
     }
     logMessageDebug(stage, source, event, message, opts = {}) {
         const client = this.runtime.client;
+        if (client._isMessageDebugEnabled?.() === false)
+            return;
         const record = {
             stage,
             source,
@@ -666,7 +670,7 @@ export class MessageDeliveryEngine {
                     .catch((e) => { client._clientLog.debug(`P2P auto-ack failed: ${formatDeliveryError(e)}`); });
             }
             if (contigAfter !== contigBefore)
-                this.saveSeqTrackerState();
+                this.persistSeq(ns);
             if (encryptedPush)
                 return;
         }
@@ -743,7 +747,7 @@ export class MessageDeliveryEngine {
                         .catch((e) => { client._clientLog.debug(`group recall auto-ack failed: group=${groupId} ${formatDeliveryError(e)}`); });
                 }
                 if (contigAfter !== contigBefore)
-                    this.saveSeqTrackerState();
+                    this.persistSeq(ns);
                 void published;
                 return;
             }
@@ -766,7 +770,7 @@ export class MessageDeliveryEngine {
                     .catch((e) => { client._clientLog.debug(`group message auto-ack failed: group=${groupId} ${formatDeliveryError(e)}`); });
             }
             if (contigAfter !== contigBefore)
-                this.saveSeqTrackerState();
+                this.persistSeq(ns);
             if (encryptedPush)
                 return;
         }
@@ -822,7 +826,7 @@ export class MessageDeliveryEngine {
             this.prunePushedSeqs(ns);
             if (client._seqTracker.getContiguousSeq(ns) !== afterSeq) {
                 await this.drainOrderedMessages(ns, undefined, true);
-                this.saveSeqTrackerState();
+                this.persistSeq(ns);
             }
             const contig = client._seqTracker.getContiguousSeq(ns);
             if (contig > 0 && contig !== afterSeq) {
@@ -836,9 +840,6 @@ export class MessageDeliveryEngine {
         finally {
             client._gapFillDone.delete(dedupKey);
             client._releasePullGate(ns, token);
-            if (filled > 0 && client._seqTracker.getContiguousSeq(ns) > afterSeq) {
-                void this.fillP2pGap();
-            }
         }
     }
     async fillGroupGap(groupId) {
@@ -865,7 +866,7 @@ export class MessageDeliveryEngine {
             this.prunePushedSeqs(ns);
             if (client._seqTracker.getContiguousSeq(ns) !== afterSeq) {
                 await this.drainOrderedMessages(ns, undefined, true);
-                this.saveSeqTrackerState();
+                this.persistSeq(ns);
             }
             client._clientLog.debug(`group message gap fill done: group=${groupId}, after_seq=${afterSeq}, filled=${filled}`);
         }
@@ -963,7 +964,7 @@ export class MessageDeliveryEngine {
                 const ackContig = client._seqTracker.getContiguousSeq(ns);
                 await this.drainOrderedMessages(ns);
                 if (ackContig !== pageContigBefore && !hasDissolvedEvent) {
-                    this.saveSeqTrackerState();
+                    this.persistSeq(ns);
                 }
                 if (eventObjects.length > 0 && ackContig > 0 && ackContig !== pageContigBefore) {
                     const ackSeq = this.clampAckSeq('group.ack_events', 'event_seq', ns, ackContig);
@@ -999,6 +1000,7 @@ export class MessageDeliveryEngine {
     }
     async handleGroupChangedEventSeq(data, groupId) {
         const client = this.runtime.client;
+        groupId = normalizeGroupId(groupId) || String(groupId ?? '').trim();
         let needPull = false;
         const rawEventSeq = data.event_seq;
         const eventSeq = Number(rawEventSeq);
@@ -1027,7 +1029,7 @@ export class MessageDeliveryEngine {
         await this.drainOrderedMessages(ns);
         if (ackContig > 0 && ackContig !== contigBefore) {
             if (data.action !== 'dissolved')
-                this.saveSeqTrackerState();
+                this.persistSeq(ns);
             const ackSeq = this.clampAckSeq('group.ack_events', 'event_seq', ns, ackContig);
             client._transport.call('group.ack_events', {
                 group_id: groupId,
@@ -1132,7 +1134,7 @@ export class MessageDeliveryEngine {
                     const newContig = client._seqTracker.getContiguousSeq(ns);
                     const needPull = pushSeq > newContig && !published;
                     if (newContig !== contigBefore) {
-                        client._saveSeqTrackerState();
+                        this.persistSeq(ns);
                     }
                     if (newContig > 0 && newContig !== contigBefore) {
                         const ackSeq = this.clampAckSeq('message.v2.ack', 'up_to_seq', ns, newContig);
@@ -1204,7 +1206,7 @@ export class MessageDeliveryEngine {
         this.runtime.delivery.setOnlineUnreadHintDrainActive(true);
         try {
             while (client._onlineUnreadHintQueue.size > 0) {
-                if (client.state !== 'ready')
+                if (client.state !== ConnectionState.READY)
                     return;
                 if (client._sessionOptions?.background_sync === false)
                     return;
@@ -1377,23 +1379,132 @@ export class MessageDeliveryEngine {
     }
     saveSeqTrackerState() {
         const client = this.runtime.client;
-        if (!client._aid)
+        const context = this.currentSeqTrackerContext();
+        if (!context) {
+            this.flushSeqTrackerPending();
             return;
+        }
         const state = client._seqTracker.exportState();
-        if (Object.keys(state).length === 0)
+        const pending = this.seqTrackerPending();
+        if (pending.size > 0 && client._seqTrackerPendingPersistContext === context) {
+            const liveNamespaces = new Set(Object.keys(state));
+            for (const ns of [...pending.keys()]) {
+                if (!liveNamespaces.has(ns))
+                    pending.delete(ns);
+            }
+            if (pending.size === 0)
+                client._seqTrackerPendingPersistContext = null;
+        }
+        if (Object.keys(state).length > 0)
+            this.mergeSeqTrackerPending(context, state);
+        this.flushSeqTrackerPending();
+    }
+    persistSeq(ns, forceSeq) {
+        const client = this.runtime.client;
+        const context = this.currentSeqTrackerContext();
+        if (!context) {
+            this.flushSeqTrackerPending();
+            return;
+        }
+        const seq = forceSeq ?? client._seqTracker.getContiguousSeq(ns);
+        if (!ns || !Number.isFinite(seq) || seq <= 0)
+            return;
+        if (forceSeq !== undefined) {
+            client._seqTracker.forceContiguousSeq(ns, seq);
+        }
+        this.mergeSeqTrackerPending(context, { [ns]: seq });
+        this.scheduleSeqTrackerFlush();
+    }
+    flushSeqTrackerPending() {
+        const client = this.runtime.client;
+        this.cancelSeqTrackerFlushTimer();
+        const context = client._seqTrackerPendingPersistContext;
+        const pending = this.seqTrackerPending();
+        if (!context || pending.size === 0) {
+            client._seqTrackerPendingPersistContext = null;
+            return;
+        }
+        const [aid, deviceId, slotId] = JSON.parse(context);
+        const state = Object.fromEntries(pending.entries());
+        pending.clear();
+        client._seqTrackerPendingPersistContext = null;
+        this.writeSeqTrackerState(aid, deviceId, slotId, state);
+    }
+    dropSeqTrackerPending(ns) {
+        const client = this.runtime.client;
+        const pending = this.seqTrackerPending();
+        pending.delete(ns);
+        if (pending.size === 0) {
+            client._seqTrackerPendingPersistContext = null;
+            this.cancelSeqTrackerFlushTimer();
+        }
+    }
+    currentSeqTrackerContext() {
+        const client = this.runtime.client;
+        if (!client._aid)
+            return null;
+        return JSON.stringify([client._aid, client._deviceId, client._slotId]);
+    }
+    seqTrackerPending() {
+        const client = this.runtime.client;
+        if (!(client._seqTrackerPendingPersist instanceof Map)) {
+            client._seqTrackerPendingPersist = new Map();
+        }
+        return client._seqTrackerPendingPersist;
+    }
+    mergeSeqTrackerPending(context, state) {
+        const client = this.runtime.client;
+        const pending = this.seqTrackerPending();
+        const pendingContext = client._seqTrackerPendingPersistContext;
+        if (pendingContext && pendingContext !== context && pending.size > 0) {
+            this.flushSeqTrackerPending();
+        }
+        client._seqTrackerPendingPersistContext = context;
+        for (const [ns, seq] of Object.entries(state)) {
+            const seqNum = Number(seq);
+            if (ns && Number.isFinite(seqNum) && seqNum > 0) {
+                pending.set(ns, seqNum);
+            }
+        }
+    }
+    scheduleSeqTrackerFlush() {
+        const client = this.runtime.client;
+        const pending = this.seqTrackerPending();
+        if (pending.size === 0)
+            return;
+        if (client._seqTrackerFlushTimer)
+            return;
+        client._seqTrackerFlushTimer = setTimeout(() => {
+            client._seqTrackerFlushTimer = null;
+            this.flushSeqTrackerPending();
+        }, SEQ_TRACKER_PERSIST_FLUSH_DELAY_MS);
+    }
+    cancelSeqTrackerFlushTimer() {
+        const client = this.runtime.client;
+        if (client._seqTrackerFlushTimer) {
+            clearTimeout(client._seqTrackerFlushTimer);
+            client._seqTrackerFlushTimer = null;
+        }
+    }
+    writeSeqTrackerState(aid, deviceId, slotId, state) {
+        const client = this.runtime.client;
+        if (!aid || Object.keys(state).length === 0)
             return;
         try {
             const saveFn = client._tokenStore.saveSeq;
             if (typeof saveFn === 'function') {
                 for (const [ns, seq] of Object.entries(state)) {
-                    saveFn.call(client._tokenStore, client._aid, client._deviceId, client._slotId, ns, seq);
+                    saveFn.call(client._tokenStore, aid, deviceId, slotId, ns, seq);
                 }
                 return;
             }
             const updater = client._tokenStore.updateInstanceState;
             if (typeof updater === 'function') {
-                updater.call(client._tokenStore, client._aid, client._deviceId, client._slotId, (metadata) => {
-                    metadata.seq_tracker_state = state;
+                updater.call(client._tokenStore, aid, deviceId, slotId, (metadata) => {
+                    const existing = isJsonObject(metadata.seq_tracker_state)
+                        ? { ...metadata.seq_tracker_state }
+                        : {};
+                    metadata.seq_tracker_state = { ...existing, ...state };
                     return metadata;
                 });
             }
@@ -1403,9 +1514,9 @@ export class MessageDeliveryEngine {
             client._clientLog.warn(`save SeqTracker state failed: ${error}`);
             client._dispatcher.publish('seq_tracker.persist_error', {
                 phase: 'save',
-                aid: client._aid,
-                device_id: client._deviceId,
-                slot_id: client._slotId,
+                aid,
+                device_id: deviceId,
+                slot_id: slotId,
                 error: String(error),
             }).catch(() => { });
         }
@@ -1415,6 +1526,7 @@ export class MessageDeliveryEngine {
         if (!client._aid || !ns)
             return;
         const seq = client._seqTracker.getContiguousSeq(ns);
+        this.dropSeqTrackerPending(ns);
         try {
             if (seq > 0 && typeof client._tokenStore.saveSeq === 'function') {
                 client._tokenStore.saveSeq(client._aid, client._deviceId, client._slotId, ns, seq);
@@ -1425,6 +1537,18 @@ export class MessageDeliveryEngine {
                 deleteSeq.call(client._tokenStore, client._aid, client._deviceId, client._slotId, ns);
                 return;
             }
+            const updater = client._tokenStore.updateInstanceState;
+            if (seq <= 0 && typeof updater === 'function') {
+                updater.call(client._tokenStore, client._aid, client._deviceId, client._slotId, (metadata) => {
+                    if (isJsonObject(metadata.seq_tracker_state)) {
+                        const next = { ...metadata.seq_tracker_state };
+                        delete next[ns];
+                        metadata.seq_tracker_state = next;
+                    }
+                    return metadata;
+                });
+                return;
+            }
             if (seq > 0) {
                 this.saveSeqTrackerState();
             }
@@ -1484,6 +1608,7 @@ export class MessageDeliveryEngine {
         const queue = client._pendingOrderedMsgs.get(ns);
         if (!queue || queue.size === 0)
             return;
+        let delivered = false;
         while (true) {
             const contig = client._seqTracker.getContiguousSeq(ns);
             const ready = [...queue.keys()]
@@ -1512,10 +1637,14 @@ export class MessageDeliveryEngine {
             await this.publishOrderedQueueItem(ns, item.event, seq, item.payload, 'ordered-drain', pullResponse);
             this.markPublishedSeq(ns, seq);
             client._markOrderedSeqDelivered(ns, seq);
+            delivered = true;
             client._clientLog.debug(`publish ordered drain delivered: ns=${ns}, seq=${seq}, event=${item.event}`);
         }
-        if (queue.size === 0)
+        if (queue.size === 0) {
             client._pendingOrderedMsgs.delete(ns);
+            if (delivered)
+                this.saveSeqTrackerState();
+        }
     }
     async publishOrderedMessage(event, ns, seq, payload) {
         const client = this.runtime.client;
@@ -1561,6 +1690,8 @@ export class MessageDeliveryEngine {
         client._markOrderedSeqDelivered(ns, seqNum);
         client._clientLog.debug(`publish ordered delivered: event=${event}, ns=${ns}, seq=${seqNum}`);
         await this.drainOrderedMessages(ns);
+        if (!client._pendingOrderedMsgs.get(ns))
+            this.saveSeqTrackerState();
         return true;
     }
     async publishOrderedGroupRecall(ns, seq, message) {
@@ -1580,6 +1711,8 @@ export class MessageDeliveryEngine {
         this.markPublishedSeq(ns, seqNum);
         client._markOrderedSeqDelivered?.(ns, seqNum);
         await this.drainOrderedMessages(ns);
+        if (!client._pendingOrderedMsgs.get(ns))
+            this.saveSeqTrackerState();
         return true;
     }
     async publishPulledMessage(event, ns, seq, payload) {