@agentunion/fastaun 0.5.32 → 0.5.33

package/_packed_docs/sdk/0.5.33-SDK/345/274/200/345/217/221/344/270/216/347/247/273/346/244/215/346/214/207/345/215/227.md

@@ -0,0 +1,304 @@
+# AUN SDK 0.5.33 开发与移植指南
+
+面向 Python、Go、TypeScript、浏览器 JavaScript SDK 维护者及新语言移植者。以仓库 `072b7c69f`（0.5.32）对照截至 2026-11-07 的未提交变更，包含已暂存脚本和相关未跟踪的 Python 压测源码。应用接线见 [0.5.33 应用集成指南](0.5.33-SDK应用集成指南.md)，完整改动索引见 [parity 0.5.33](../../python/CHANGES_FOR_PARITY.md#v0533)。
+
+## 1. 范围与实现分层
+
+| 本轮工作 | SDK 负责 | 配套服务负责 |
+| --- | --- | --- |
+| 控制消息兼容 | 发送前核对能力、准备类别、解密后分派 | Gateway 可信会话；Message／Group 兼容选择投递通道 |
+| Ownership 批次 | 批次上下文、归组事件、逐项审批与结果汇总 | NS 继续处理原有单项关系与名片提交 |
+| 本地共识优先 | 恢复并核验本地快照，按需查询 | NS 返回当前权威事实，管理提交仍做原有校验 |
+| 批量 ACL | VFS／LowLevel 参数贯通、失败时定向失效缓存 | Storage 合并授权对象、逐项处理及权限计数 |
+| Python 专项 | 群 Pull 去重复闸门、退避区分、容量压测 CLI | 保持现有服务接口 |
+
+```mermaid
+%%{init: {"theme":"base","flowchart":{"curve":"linear","nodeSpacing":24,"rankSpacing":32}}}%%
+flowchart TB
+    A["宿主应用"]:::app
+    subgraph SDK["每个 AID 进程中的 SDK"]
+        direction TB
+        F["AUNClient 门面"]:::entry
+        O["Ownership<br/>批次 / 单项审批 / 共识"]:::logic
+        V["Storage VFS / LowLevel<br/>多 AID ACL"]:::logic
+        E["已有 EventService<br/>Pub / Bus / Sub"]:::inherited
+        L["本地身份仓库<br/>agent.md / 共识快照 / 读缓存"]:::local
+        P["RPC 准备与分类交付<br/>能力 / E2EE / 内部消费"]:::entry
+        F --> O & V & E
+        O & V --> L
+        O & V & E --> P
+    end
+    G["Gateway<br/>认证身份 / 设备 / RPC 转发"]:::infra
+    subgraph SERVICES["AUN 服务"]
+        direction LR
+        M["Message / Group<br/>消息通道与 TTL"]:::infra
+        N["NS<br/>名片与 Ownership 事实"]:::infra
+        S["Storage<br/>对象 / ACL / CAS"]:::infra
+        C["Credential<br/>登记 / 状态 / 撤销"]:::infra
+    end
+    A --> F
+    P --> G
+    G --> M & N & S & C
+    classDef app fill:#eff6ff,stroke:#60a5fa,color:#1e3a8a,rx:10,ry:10
+    classDef entry fill:#eef2ff,stroke:#818cf8,color:#312e81,rx:10,ry:10
+    classDef logic fill:#ecfdf5,stroke:#6ee7b7,color:#065f46,rx:10,ry:10
+    classDef local fill:#fff7ed,stroke:#fdba74,color:#9a3412,rx:10,ry:10
+    classDef inherited fill:#f8fafc,stroke:#cbd5e1,color:#475569,rx:10,ry:10
+    classDef infra fill:#f8fafc,stroke:#94a3b8,color:#334155,rx:10,ry:10
+    style SDK fill:#ffffff,stroke:#e2e8f0,rx:12,ry:12
+    style SERVICES fill:#f8fafc,stroke:#e2e8f0,rx:12,ry:12
+```
+
+EventService、VFS 定向缓存、RPC `16/8/4/4` 预算及 Bus 单实例机制沿用 0.5.32；本版不重新定义事件目录或 fanout。Pub／Bus／Sub 使用 `client.EventService`（Go 为 `EventService()`），详细约束见 [0.5.32 移植指南](0.5.32-SDK开发与移植指南.md)与[事件服务移植指南](AUN事件发布订阅开发移植指南.md)。
+
+## 2. 控制消息：先准备语义，再决定传输类别
+
+### 2.1 共同契约与字段位置
+
+| 内容与场景 | 能力已协商 | 类别或 SDK 协议未协商 |
+| --- | --- | --- |
+| 普通消息，P2P／群，明文／加密 | 普通路径 | 普通路径；群普通 TTL 不因控制能力缺失而被阻断 |
+| 应用 `control`，P2P／群，明文／加密 | 保留类别 | 构造请求时移除外层类别和可改写保护头类别，走普通投递 |
+| P2P 加密 `sdk_control` | 保留类别、协议与版本 | 移除外层路由类别；E2EE 内部类别、协议与版本保留 |
+| 明文 `sdk_control`、群 `sdk_control` | 本地拒绝 | 本地拒绝 |
+
+| 位置 | 含义与检查 |
+| --- | --- |
+| RPC 参数 `message_class` | 请求投递类别；降级可省略，Go 不重新补为空字符串或 `normal` |
+| 明文 RPC 参数 `protected_headers` | 明文元数据所在层；服务端直接解析，并结合可信会话身份处理 |
+| E2EE 信封 `protected_headers` | 受认证的消息语义；P2P 通常在 `payload` 信封内，群 V2 在 `envelope` 内 |
+| 送达记录 `delivery_class` | 服务端实际选择的通道；普通通道不抹去信封中的 SDK 语义 |
+
+类别和协议冲突继续报参数错误。信封已加密签名时保持原样；降级调整路由，接收侧仍校验原受保护内容。普通加密信封未声明类别时按 `normal` 校验，不能将缺字段当作解密失败。
+
+### 2.2 发送与交付顺序
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant A as 应用或 SDK 内部模块
+    participant P as 发送准备
+    participant G as Gateway
+    participant M as Message / Group
+    participant R as 接收 SDK
+    participant D as 接收应用
+    A->>P: method / class / encrypt / payload / TTL
+    P->>P: 合并元数据，检查参数和当前协商结果
+    alt 明文或群 sdk_control
+        P-->>A: 本地拒绝，不进入传输
+    else 合法消息
+        alt 应用 control 未协商
+            P->>P: 移除可变类别，保留其它参数
+        else 加密 sdk_control 未协商
+            P->>P: 省略外层类别，保留 SDK 保护头
+        end
+        P->>G: 发送请求与明文正文或 E2EE 信封
+        G->>M: 转发可信身份与请求
+        M->>M: 选择通道，保留 TTL 与信封
+        M-->>R: 实际投递类别与消息
+        R->>R: 明文使用可信投递身份；加密核验信封
+        alt 已认证的 sdk_control
+            R->>R: 交给 SDK 协议处理器
+        else 应用 control 或 normal
+            R-->>D: 应用消息事件
+        end
+    end
+```
+
+以下是语义顺序，不是要求四端照搬同一函数：
+
+```text
+校验 class、场景、SDK 协议及版本
+若 sdk_control 为明文或群消息：拒绝
+若 control 未协商：移除可改写的类别字段
+若 sdk_control 未协商：仅省略传输类别
+明文直接发送；待加密正文按准备结果构造信封
+已签名信封保持不变，交配套服务选择通道
+接收按可信身份与受保护语义分派
+```
+
+Python 群分类 Pull 已由外层序列化，内部直接 fetch，避免同一请求重复进入同一闸门等待自身。移植时保留原有 Pull／ACK、水位与设备范围检查，只移除这一层重复等待。
+
+实现入口：[Python 准备与接收](../../python/src/aun_core/_client/control_messages.py)／[RPC](../../python/src/aun_core/_client/rpc_pipeline.py)、[TS RPC](../../ts/src/client/rpc-pipeline.ts)／[接收](../../ts/src/client/control-messages.ts)、[JS RPC](../../js/src/client/rpc-pipeline.ts)／[接收](../../js/src/client/control-messages.ts)、[Go 类别](../../go/control_messages.go)／[V2 路由](../../go/v2_routing.go)／[P2P](../../go/client_v2_e2ee.go)／[群](../../go/v2_group.go)。
+
+## 3. Ownership：批次归组，单项仍独立完成
+
+### 3.1 API 和固定上下文
+
+| 层 | Python | TS／JS | Go |
+| --- | --- | --- | --- |
+| 申请选项 | `batch_id` 关键字 | `OwnershipRequestOptions.batchId` | `OwnershipRequestOptions.BatchID` |
+| 绑定／转移 | `bind_owner_aid/bind_sub_aid/transfer_sub_aid` | `bindOwneraid/bindSubaid/transferSubaid` | `BindOwneraid/BindSubaid/TransferSubaid` |
+| 批量审批 | `accept_ownership_requests/reject_ownership_requests` | `acceptOwnershipRequests/rejectOwnershipRequests` | `AcceptOwnershipRequests/RejectOwnershipRequests` |
+| 传输字段 | 可选 UUIDv4 `batch_id` | 同左 | 同左 |
+
+原单项调用兼容。`batch_id` 贯穿任务上下文、Ownership 请求和应用事件；同一批次可涉及多个 AID，但每项保持自己的 `operation_id`。批次不是审批权限，也不替代已认证的原始请求。
+
+同一操作的发送者或原始上下文发生变化，包括增删／修改 `batch_id`，按冲突处理。应用将选择的操作 ID 列表交给审批接口；SDK 去重、逐项检查当前身份及代际，Go 还检查 context，返回 `total/succeeded/failed/results`。
+
+### 3.2 请求与审批链路
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant I as 多个申请 AID 的 SDK
+    participant M as AUN 消息投递
+    participant O as Owner SDK
+    participant A as Owner 应用
+    participant N as NS / 名片提交
+    loop 每个绑定或转移请求
+        I->>M: 独立 operation_id，共用 batch_id
+        M-->>O: 原始请求与认证发送方
+        O->>O: 核对固定上下文，保存请求
+        O-->>A: ownership.request，携带 batch_id
+    end
+    A->>A: 按批次展示，冻结本次选择的操作 ID
+    A->>O: accept / reject requests(operation_ids)
+    O->>O: 去重并固定执行身份
+    loop 每个 operation_id
+        O->>O: 检查原请求、当前身份及代际
+        O->>N: 沿用单项刷新、校验与提交流程
+        N-->>O: 单项当前结果
+        O->>O: 保存该项结果或错误，继续其它项
+    end
+    O-->>A: 汇总与逐项结果
+```
+
+批量返回中的成功数表示本次单项接口执行结果，后续关系是否已达共识仍以单项状态／既有工作流为准；`waiting` 不能被应用解释为全部关系已绑定完成。中途失败不会将整个批次回滚，身份变化后剩余项按错误记录。
+
+```text
+ids = 按首次出现顺序去重(operation_ids)
+identity = 当前 AID 与身份代际
+对每个 id：
+    核对 identity 与原始认证请求
+    执行原有单项 accept 或 reject
+    记录单项结果或错误
+返回汇总和 results
+```
+
+实现：[Python 消息校验](../../python/src/aun_core/ownership_v21.py)／[workflow](../../python/src/aun_core/ownership_workflow.py)／[门面](../../python/src/aun_core/client.py)、[TS workflow](../../ts/src/ownership-workflow.ts)／[门面](../../ts/src/client.ts)、[JS workflow](../../js/src/ownership-workflow.ts)／[门面](../../js/src/client.ts)、[Go workflow](../../go/ownership_workflow.go)。该批次扩展不新增服务器批量审批 RPC。
+
+## 4. 本地 agent.md 与共识：有效快照优先，管理仍刷新
+
+启动／连接后先读取本地名片。新的 Client 首次查询也可恢复已保存的 `ownership_snapshot`；恢复条件须同时成立：
+
+| 核对项 | 要求 |
+| --- | --- |
+| 共识和范围 | `status=consensus`、锁定、目标 AID 一致 |
+| 远端观察 | 快照 ETag 非空，与记录已观察远端 ETag 一致，记录不为 missing |
+| 本地正文 | 正文 SHA256 与快照摘要一致 |
+| 关系声明 | 名片中 owner、关系版本与快照一致 |
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant A as 连接 / 查询调用方
+    participant C as Client / AgentMdManager
+    participant L as 本地身份仓库
+    participant N as NS
+    A->>C: 连接后读取或首次共识查询
+    C->>L: 载入正文、观察记录与快照
+    L-->>C: 本地记录
+    alt 非 force，内存或持久快照有效
+        C-->>A: 复用本地结果
+    else 未达共识、记录变化或 force
+        C->>N: 原有权威读取
+        N-->>C: 当前关系与名片
+        C->>C: 核对关系、正文和观察代际
+        C->>L: 仅当前观察仍匹配时保存快照
+        C-->>A: 当前结果
+    end
+    Note over C,N: 绑定、审批、转移、释放等管理流程继续强制刷新
+```
+
+这里的 ETag 是 SDK 已观察到的状态；本地复用不会主动证明远端此刻没有变化。收到名片／Ownership 变化后清理相关快照，未达共识或显式强刷再查询，保持事件驱动，不新增周期首查任务。
+
+查询完成写回前要核对 Client、manager／存储根、缓存对象及观察版本，避免旧身份或旧请求覆盖新记录。群／组织首次访问同样复用有效本地共识；管理方法内部的强制刷新保持不变。
+
+实现：[Python manager](../../python/src/aun_core/agent_md.py)／[client](../../python/src/aun_core/client.py)、[TS manager](../../ts/src/agent-md.ts)／[client](../../ts/src/client.ts)、[JS manager](../../js/src/agent-md.ts)／[client](../../js/src/client.ts)、[Go client](../../go/client.go)。
+
+## 5. Storage ACL：从门面贯通到 RPC
+
+| 层 | 新列表参数 | 旧参数兼容 |
+| --- | --- | --- |
+| Python VFS／LowLevel | `grantee_aids` | `grantee_aid` |
+| TS／JS VFS／LowLevel | `granteeAids` | `granteeAid` |
+| Go VFS 选项 | `GranteeAIDs` | `GranteeAID` |
+| Go LowLevel | 原位置参数后可选 `[]string` | 原位置参数原样可用 |
+| RPC `storage.set_acl/remove_acl` | `grantee_aids` 数组，允许单元素 | `grantee_aid` |
+
+Storage 服务合并并归一化、去重两种字段，owner／grantee 的数据库访问和缓存键统一大小写；`max_uses` 对每个 AID 分别计数。SDK 透传授权意图，权限和次数判断留在服务端。
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant A as 应用
+    participant V as VFS / LowLevel
+    participant C as SDK 读缓存包装层
+    participant S as Storage，经 Gateway
+    A->>V: set / remove ACL，多 AID
+    V->>C: path + grantee_aids，兼容旧单值
+    C->>S: storage.set_acl / remove_acl
+    S->>S: 归一化、去重，逐项写入
+    alt 全部完成
+        S-->>C: 成功结果
+        C->>C: 定向失效受影响路径
+        C-->>A: 原结果
+    else 中途失败，可能已有部分写入
+        S-->>C: 原 RPC 错误
+        C->>C: 同样定向失效受影响路径
+        C-->>A: 继续抛出原错误
+    end
+    Note over C,S: 保留无关路径缓存；不承诺整个批次事务回滚
+```
+
+缓存失效需覆盖 Raw 调用、LowLevel 与 VFS。Go 的 mock／自定义 client LowLevel 路径也在错误返回前失效；Python 异常路径含取消后仍可能已有写入的情况。复用原有资源范围与在途回填保护，避免清空整个 Storage 缓存。
+
+```text
+尝试执行 ACL RPC
+成功：按既有规则失效相关路径并返回
+异常：对 set_acl / remove_acl 失效同一资源范围
+重新抛出原异常
+保留无关资源缓存
+```
+
+入口：[Python VFS](../../python/src/aun_core/storage/vfs.py)／[LowLevel](../../python/src/aun_core/storage/lowlevel.py)／[cache](../../python/src/aun_core/storage/cache.py)、[TS VFS](../../ts/src/storage/vfs.ts)／[LowLevel](../../ts/src/storage/lowlevel.ts)／[cache](../../ts/src/storage/read-cache.ts)、[JS VFS](../../js/src/storage/vfs.ts)／[LowLevel](../../js/src/storage/lowlevel.ts)／[cache](../../js/src/storage/read-cache.ts)、[Go VFS](../../go/storage_vfs.go)／[LowLevel](../../go/storage_lowlevel.go)／[Call](../../go/client.go)。
+
+对象上传、下载票据及共享链接的冗余返回字段精简属于配套服务响应契约变化，元数据保存方式保持原有设计。字段以 [Storage RPC 手册](09-storage-rpc-manual.md)为准；移植者不要重新依赖已移除的空值或重复 URL 字段。
+
+## 6. Python 独有实现与工具
+
+| 改动 | 当前行为 | 移植边界 |
+| --- | --- | --- |
+| 退避提示 | 有效正数 `retry_after_seconds/retry_after_ms` 优先，多个取较长值 | 本轮其它 SDK 没有相同退避调整 |
+| 缺少提示的拥塞 | `-32029/-32429` 且消息含 queue、backpressure、capacity 等拥塞标记，默认 1 秒 | 其它限流默认 60 秒；不因此自动重试应用写请求 |
+| 群分类 Pull | 外层已串行时内部直接 fetch | 保留 cursor／ACK 检查及原调度预算 |
+| 容量压测 | `aun bench run/report`，16 场景、多进程／身份通道、预算与续跑、JSON／HTML | Python CLI 能力，不是要求四端新增网络协议 |
+
+退避入口为 [transport](../../python/src/aun_core/transport.py)。容量工具由 [bench](../../python/src/aun_cli/commands/bench.py)注册 [bench_capacity](../../python/src/aun_cli/commands/bench_capacity.py)，实现拆分为[场景](../../python/src/aun_cli/benchmark/scenarios.py)、[执行与报告](../../python/src/aun_cli/benchmark/runner.py)、[节奏统计](../../python/src/aun_cli/benchmark/runtime.py)、[搜索](../../python/src/aun_cli/benchmark/search.py)。多进程入口与结果协议由工具自行处理，不影响 SDK Client 的单进程 API。
+
+报告区分有效完成量、延迟达标容量、稳态吞吐与发压端瓶颈；`pubsub` 场景包含发压端 Bus，不能解释为纯服务端容量。生成器不足、搜索未界定或持续验证未通过时，保留相应边界，不标记为已确认容量。
+
+## 7. 四端回归与移植验收
+
+| 范围 | Python | TS／JS | Go |
+| --- | --- | --- | --- |
+| 发送／接收类别 | [components](../../python/tests/unit/test_client_components.py) | 各端 `tests/unit/rpc-pipeline.test.ts`、`client.test.ts` | [client](../../go/client_test.go)、[V2 parity](../../go/v2_python_parity_test.go) |
+| 批次与审批 | [workflow](../../python/tests/unit/test_ownership_workflow.py) | 各端 `tests/unit/ownership-workflow.test.ts` | [workflow](../../go/ownership_workflow_test.go) |
+| 本地共识／管理强刷 | [agent.md](../../python/tests/unit/test_client_agent_md_api.py) | 各端 `tests/unit/client-agent-md-api.test.ts` | [agent.md](../../go/client_agent_md_api_test.go) |
+| ACL 与错误缓存 | [cache](../../python/tests/unit/test_storage_read_cache.py)、VFS 测试 | TS `storage-read-cache.test.ts`；JS `storage-vfs-read-cache.test.ts`；各端 VFS 测试 | [cache](../../go/storage_read_cache_test.go)、[VFS](../../go/storage_vfs_test.go) |
+
+实现验收按顺序检查：
+
+1. 明文／加密应用控制消息在 P2P 和群中均可发送；能力缺失时走普通通道，TTL 保留，普通消息继续交付。
+2. P2P 加密 SDK 控制降级后仍经 SDK 消费；群及明文 SDK 控制发送前拒绝；冲突元数据不被静默改写。
+3. 同批绑定与转移贯穿 UUIDv4 批次，原调用兼容；重复 ID 去重，失败结果逐项保留，身份变化后不继续以旧身份审批。
+4. 新 Client／重连复用有效本地记录；改变 ETag／正文／关系或显式 force 时查询；管理流程仍刷新，旧异步结果不覆盖新观察。
+5. VFS／LowLevel／Raw 批量 ACL、单元素列表和旧单值均有效；每 AID 独立计数，部分失败后相关缓存失效、无关缓存保留。
+6. 分别验收四端，再用跨 SDK runner 验证互通；保留实际版本、服务端版本、失败项和结果产物。
+
+[控制消息矩阵 runner](../../tests/cross-sdk/runner/run_control_matrix_e2e.py)定义 96 格：4 发送 SDK × 2 发送端能力状态 × 3 类别 × 2 加密状态 × P2P／群。合法格检查其它三个 SDK 接收，无效格预期发送前拒绝；首失败停止并保存断点。
+
+该矩阵使用 TTL=60、`aun.agent_md.changed` v1，接收端保持能力启用，未覆盖接收端单独缺能力或两端均缺能力的全部组合，也不替代 EventService `aun.pubsub` 验收。Go 观察点与能力开关受 `crosssdk` 构建标签控制，普通构建走 stub。
+
+本轮仅编写指南并做文档校验，没有重新执行 SDK 全量、跨 SDK E2E 或容量压测。既有版本校验和定向测试记录见 [parity 验证边界](../../python/CHANGES_FOR_PARITY.md#v0533)，不能将 runner 中的成功输出条件当作已取得的 96/96 通过产物。

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

@@ -197,19 +197,32 @@ Node.js TypeScript、Python、Go 的索引位于 `{aunPath}/.cache/storage/index
 
 ### 响应
 
+返回写入后的对象元数据。URL 字段收敛为 `url` 和 `logical_url`，供后续 HTTP 读取使用；私有对象仍须通过访问鉴权。SDK 需要 HTTP 下载时，使用 `storage.create_download_ticket` 响应中的地址。
+
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `url` | string | **AID 风格 URL（默认/推荐）**：`https://{owner_aid}/{object_key}`，经 NameService fallback 302 跳转到 storage 服务 |
 | `logical_url` | string | 直链 URL：`https://storage.{issuer}/{user}/{object_key}`，直达 storage 服务，无跳转 |
+| `node_type` | string | 固定为 `"object"` |
+| `type` | string | 固定为 `"file"` |
+| `object_id` | string | 对象 ID |
 | `owner_aid` | string | 所有者 AID |
 | `bucket` | string | 存储桶 |
 | `object_key` | string | 对象路径 |
+| `parent_folder_id` | string | 父目录 ID |
+| `name` | string | 文件名 |
+| `path` | string | 对象路径，与 `object_key` 相同 |
 | `size_bytes` | integer | 对象大小（字节） |
 | `content_type` | string | MIME 类型 |
 | `sha256` | string | SHA-256 哈希 |
 | `version` | integer | 版本号 |
 | `etag` | string | 实体标签 |
-| `updated_at` | integer | 更新时间戳 |
+| `is_private` | boolean | 是否私有 |
+| `expire_at` | integer | 过期时间戳（秒），`0` 表示不过期 |
+| `created_at` | integer | 创建时间戳（毫秒） |
+| `updated_at` | integer | 更新时间戳（毫秒） |
+| `status` | string | 对象状态，通常为 `"active"` |
+| `metadata` | object | 自定义元数据，未设置时为 `{}` |
 
 ### 示例
 
@@ -883,16 +896,14 @@ else:
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `share_id` | string | 10 位 Base62 分享短码 |
-| `url` | string | **默认分享 URL（隐藏路径）**：`https://{owner_aid}/s/{share_id}`，最短直链 |
-| `path_url` | string | **可选分享 URL（暴露路径）**：`https://{owner_aid}/{object_key}?t={share_id}`，可读性强 |
-| `aid_share_url` | string | 同 `url`（兼容旧字段） |
-| `share_url` | string | storage 直链：`https://storage.{issuer}/s/{share_id}`，兼容字段 |
-| `expire_at` | integer | 过期时间戳（Unix 秒），`0` 表示永不过期 |
+| `url` | string | 默认分享 URL：`https://{owner_aid}/s/{share_id}`，经 NameService 跳转 |
+| `share_url` | string | Storage 直链：`https://storage.{issuer}/s/{share_id}`，直接访问 Storage 服务 |
+| `expire_at` | integer | 分享链接过期时间戳（Unix 秒），`0` 表示永不过期 |
 | `max_uses` | integer | 最大使用次数，`0` 表示无限制 |
 | `allowed_aids` | string[] | 授权 AID 列表，`["*"]` 表示公开 |
+| `target` | object | 被分享对象的元数据，不包含空 URL 字段；其中 `expire_at` 为对象过期时间 |
 
-> 两种格式都通过 `share_id` 定位到 `share_links` 记录鉴权。`url` 隐藏文件结构，`path_url` 暴露文件名便于识别，调用者按需选择。
-> 访问 `url` 时经 NameService 302 跳转到 `storage.{issuer}/s/{share_id}`；访问 `path_url` 时经 NameService fallback 到 storage，由 `?t=` token 鉴权。
+> `url` 经 NameService 302 跳转到 `share_url`；两者都通过 `share_id` 定位到同一条分享记录鉴权。
 > share_id 指向 `(owner_aid, bucket, object_key)` 逻辑引用，非内容快照：对象改名/移动后原 share_id 失效，内容覆盖后下载到新内容。
 
 ### 示例
@@ -932,10 +943,10 @@ share_url = result["url"]  # https://alice.agentid.pub/s/Ab3xK9mZ2q
 |------|------|------|
 | `share_id` | string | 分享短码 |
 | `url` | string | 默认分享 URL（隐藏路径）：`https://{owner_aid}/s/{share_id}` |
-| `path_url` | string | 可选分享 URL（暴露路径）：`https://{owner_aid}/{object_key}?t={share_id}` |
-| `aid_share_url` | string | 同 `url`（兼容旧字段） |
-| `share_url` | string | storage 直链（兼容） |
+| `share_url` | string | Storage 直链：`https://storage.{issuer}/s/{share_id}` |
 | `object_key` | string | 被分享对象路径 |
+| `target_type` | string | 分享目标类型 |
+| `target_id` | string | 分享目标 ID |
 | `bucket` | string | 存储桶 |
 | `allowed_aids` | string[] | 授权 AID 列表，`["*"]` 表示公开 |
 | `expire_at` | integer | 过期时间戳（秒），`0` 表示永不过期 |
@@ -1424,16 +1435,19 @@ fs 目录节点视图。
 | 参数 | 类型 | 必填 | 默认 | 说明 |
 |------|------|------|------|------|
 | `path` | string | 是 | — | 授权路径前缀 |
-| `grantee_aid` | string | 是 | — | 被授权 AID；`role:*` 仅限 group 内部调用 |
+| `grantee_aids` | string[] | 二选一 | — | 一个或多个被授权 AID；优先于兼容字段；`role:*` 仅限 group 内部调用 |
+| `grantee_aid` | string | 二选一 | — | 兼容旧调用的单个 AID；未提供 `grantee_aids` 时使用 |
 | `perms` | string | 是 | — | 权限位：`r` 读取、`w` 写入、`x` 删除，可组合 |
 | `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
 | `bucket` | string | 否 | `"default"` | 存储桶 |
 | `expires_at` | integer | 否 | — | 授权过期时间 |
-| `max_uses` | integer | 否 | — | 最大使用次数 |
+| `max_uses` | integer | 否 | — | 每个被授权 AID 的最大使用次数，分别计数；0 表示不限次数 |
 
 ### 响应
 
-ACL 视图。
+使用 `grantee_aids` 返回 `{acls: [ACL视图, ...]}`，单元素数组也返回此结构；仅使用兼容字段 `grantee_aid` 时仍返回单条 ACL 视图。每个 AID 独立保存 `max_uses` 和 `used_count`。
+
+`grantee_aids` 不能为空数组，元素不能为空；重复 AID 去重并保留首次顺序。先校验整批参数，再逐项写入；存储错误会中断，已完成项保留。
 
 ---
 
@@ -1446,13 +1460,16 @@ ACL 视图。
 | 参数 | 类型 | 必填 | 默认 | 说明 |
 |------|------|------|------|------|
 | `path` | string | 是 | — | 授权路径前缀 |
-| `grantee_aid` | string | 是 | — | 被授权 AID |
+| `grantee_aids` | string[] | 二选一 | — | 一个或多个待撤销 AID；优先于兼容字段 |
+| `grantee_aid` | string | 二选一 | — | 兼容旧调用的单个 AID；未提供 `grantee_aids` 时使用 |
 | `owner_aid` | string | 否 | 当前用户 | 所有者 AID |
 | `bucket` | string | 否 | `"default"` | 存储桶 |
 
 ### 响应
 
-`{removed: boolean, owner_aid, bucket, path, grantee_aid}`。
+使用 `grantee_aids` 返回 `{results: [{removed: boolean, owner_aid, bucket, path, grantee_aid}, ...]}`；单元素数组也返回此结构。仅使用 `grantee_aid` 时仍返回 `{removed: boolean, owner_aid, bucket, path, grantee_aid}`。
+
+数组校验和去重规则与 `storage.set_acl` 一致；逐项撤销，存储错误会中断并保留已完成项。
 
 ---
 

package/dist/agent-md.d.ts

@@ -1,7 +1,7 @@
 import { AID } from './aid.js';
 import { type OwnershipRelease, type OwnershipVerificationStatus } from './ownership-proof.js';
 import type { ModuleLogger } from './logger.js';
-import { type OwnershipAgentObservation, type OwnershipSavedFile } from './ownership-v21.js';
+import { type OwnershipAgentObservation, type OwnershipConsensusResult, type OwnershipSavedFile } from './ownership-v21.js';
 export declare function buildOwnershipReleaseAgentMd(content: string, release: OwnershipRelease): string;
 export declare function buildOwnershipAgentMd(content: string, owner: string, proof: Record<string, unknown>): string;
 export declare function updateOwnershipAgentMd(content: string, fields: Record<string, unknown>): string;
@@ -137,6 +137,7 @@ export declare class AgentMdManager {
         version: number;
         content_hash: string;
     }): boolean;
+    localOwnershipConsensus(aid: string, record: Record<string, unknown> | null): OwnershipConsensusResult | null;
     private _clearConfirmedDraft;
     upload(content?: string | null, originalCondition?: OwnershipSavedFile['condition']): Promise<Record<string, unknown>>;
     readAgentMdFresh(aid: string): Promise<{

package/dist/agent-md.js

@@ -440,6 +440,23 @@ export class AgentMdManager {
             return true;
         });
     }
+    localOwnershipConsensus(aid, record) {
+        const snapshot = record?.ownership_snapshot;
+        if (!snapshot || snapshot.status !== 'consensus' || snapshot.sub_aid !== aid || snapshot.lock !== 'locked'
+            || !snapshot.agent_md_etag || snapshot.agent_md_etag !== record?.remote_etag || record.remote_status === 'missing'
+            || typeof record.content !== 'string' || AgentMdManager.contentEtag(record.content).slice(1, -1) !== snapshot.agent_md_sha256)
+            return null;
+        try {
+            const statement = parseOwnershipFile(record.content, 'agent', { expectedSubAid: aid }).statement;
+            if (!statement || statement.owner_aid !== snapshot.owner_aid || statement.relation_version !== snapshot.relation_version)
+                return null;
+            return { status: 'consensus', sub_aid: aid, owner_aid: statement.owner_aid, relation_version: statement.relation_version,
+                lock: 'locked', agent_md_etag: snapshot.agent_md_etag, agent_md_sha256: snapshot.agent_md_sha256 };
+        }
+        catch {
+            return null;
+        }
+    }
     _clearConfirmedDraft(aid, content) {
         this._withRecordLock(aid, () => {
             const record = this._readRecordUnlocked(aid, true);