@agentunion/fastaun-browser 0.2.19 → 0.2.20

package/_packed_docs/protocol/11-Storage-/345/255/220/345/215/217/350/256/256.md

@@ -0,0 +1,271 @@
+# 11. Storage 子协议
+
+> **适用版本**：AUN 1.0 | **状态**：Draft
+
+Storage 服务是 AUN 协议的应用层扩展，提供对象存储能力。负责大文件、附件、二进制数据的上传、下载与持久保存。客户端通过 `storage.*` 命名空间方法访问，小对象（≤64KB）通过 RPC 内联传输，大对象通过预签名 URL 直接 HTTP 传输。
+
+---
+
+## 11.1 设计原则
+
+- **控制面与数据面分离**：小对象内联 RPC；大对象通过 `create_upload_session` / `create_download_ticket` 获取预签名 URL，走 HTTP 数据面
+- **per-AID 隔离**：每个 AID 拥有独立的存储命名空间和配额，跨 AID 访问受 `is_private` 控制
+- **对象键路径化**：`object_key` 支持 `/` 分隔的层级路径，便于组织和前缀查询
+- **版本化**：每次写入递增 `version`，支持 `expected_version` 做 CAS（Compare-And-Swap）并发控制
+
+---
+
+## 11.2 约束与限制
+
+| 约束 | 默认值 | 说明 |
+|------|--------|------|
+| 内联内容上限 | 64 KB | `put_object` / `get_object` 的 base64 内容上限 |
+| 单对象上限 | 10 MB | 含数据面上传 |
+| 对象键长度 | ≤ 1024 字节 | 不含 `..`，不含前导/尾随/连续 `/` |
+| 列表分页上限 | 200 条/页 | `list_objects` 单次最大返回 |
+| 预签名 URL 有效期 | 3600 秒 | upload / download ticket |
+
+对象键合法字符：字母、数字、`.`、`_`、`/`、`-`。
+
+---
+
+## 11.3 控制面方法
+
+### `storage.put_object`
+
+内联写入小对象（≤ 内联上限）。
+
+**参数**：
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|:----:|------|
+| `owner_aid` | string | ❌ | 默认调用者 AID |
+| `bucket` | string | ❌ | 默认 `"default"` |
+| `object_key` | string | ✅ | 对象路径 |
+| `content` | string | ✅ | base64 编码的内容 |
+| `content_type` | string | ❌ | MIME 类型，默认 `application/octet-stream` |
+| `is_private` | boolean | ❌ | 默认 `true`，公开对象可被其他 AID 读取 |
+| `overwrite` | boolean | ❌ | 默认 `true`，`false` 时对象已存在则拒绝 |
+| `expected_version` | integer | ❌ | CAS 并发控制，版本不匹配则拒绝 |
+| `expire_in_seconds` | integer | ❌ | 过期时间，`0` 表示永不过期 |
+| `metadata` | object | ❌ | 用户自定义元数据 |
+
+**响应**：`{ owner_aid, bucket, object_key, size_bytes, content_type, sha256, version, etag, updated_at }`
+
+**权限**：仅对象所有者可写（`requester_aid == owner_aid`）。
+
+**副作用**：成功后发布 `event/storage.object_changed`（`action: "put"`）。
+
+### `storage.get_object`
+
+内联读取小对象。对象超过内联上限时须使用 `create_download_ticket`。
+
+**参数**：
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|:----:|------|
+| `owner_aid` | string | ❌ | 默认调用者 AID |
+| `bucket` | string | ❌ | 默认 `"default"` |
+| `object_key` | string | ✅ | 对象路径 |
+
+**响应**：`{ owner_aid, bucket, object_key, content (base64), content_type, size_bytes, sha256, version, updated_at }`
+
+**权限**：私有对象仅所有者可读；公开对象（`is_private=false`）任何 AID 可读。
+
+### `storage.head_object`
+
+查询对象元数据，不返回内容。
+
+**参数**：同 `get_object`。
+
+**响应**：`{ owner_aid, bucket, object_key, content_type, size_bytes, sha256, version, etag, is_private, expire_at, created_at, updated_at }`
+
+**权限**：同 `get_object`。
+
+### `storage.delete_object`
+
+删除单个对象。
+
+**参数**：同 `get_object`。
+
+**响应**：`{ deleted (bool), owner_aid, object_key }`
+
+**权限**：仅所有者可删。
+
+**副作用**：成功后发布 `event/storage.object_changed`（`action: "delete"`）。
+
+### `storage.list_objects`
+
+列出对象，支持前缀过滤和分页。
+
+**参数**：
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|:----:|------|
+| `owner_aid` | string | ❌ | 默认调用者 AID |
+| `bucket` | string | ❌ | 默认 `"default"` |
+| `prefix` | string | ❌ | 路径前缀过滤 |
+| `page` | integer | ❌ | 页码，默认 1 |
+| `size` | integer | ❌ | 每页条数，默认 50，最大 200 |
+| `marker` | string | ❌ | 深度分页游标；传入时优先按游标分页 |
+
+**响应**：`{ items: [{ object_key, size_bytes, content_type, sha256, version, is_private, updated_at }...], total, page, size, marker, next_marker }`
+
+**权限**：仅所有者可列。
+
+### `storage.list_prefixes`
+
+列出指定前缀下的子目录（类似 S3 CommonPrefixes）。
+
+**参数**：
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|:----:|------|
+| `owner_aid` | string | ❌ | 默认调用者 AID |
+| `bucket` | string | ❌ | 默认 `"default"` |
+| `prefix` | string | ❌ | 路径前缀 |
+| `size` | integer | ❌ | 返回上限，默认 50，最大 200 |
+
+**响应**：`{ prefixes: [string...], count, size }`
+
+**权限**：仅所有者可列。
+
+### `storage.get_quota`
+
+查询存储配额使用情况。
+
+**参数**：
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|:----:|------|
+| `owner_aid` | string | ❌ | 默认调用者 AID |
+
+**响应**：`{ owner_aid, used_bytes, object_count, quota_bytes }`
+
+**权限**：仅所有者可查。
+
+---
+
+## 11.4 数据面方法
+
+用于超过内联上限的大对象传输。客户端通过 RPC 获取预签名 URL，然后直接 HTTP PUT/GET。
+
+### `storage.create_upload_session`
+
+申请上传预签名 URL。
+
+**参数**：
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|:----:|------|
+| `owner_aid` | string | ❌ | 默认调用者 AID |
+| `bucket` | string | ❌ | 默认 `"default"` |
+| `object_key` | string | ✅ | 对象路径 |
+| `size_bytes` | integer | ❌ | 预期大小（客户端追踪用） |
+| `content_type` | string | ❌ | 默认 `application/octet-stream` |
+| `expected_version` | integer | ❌ | CAS 版本检查（签 URL 前校验） |
+| `expire_in_seconds` | integer | ❌ | URL 有效期，默认 3600 秒 |
+
+**响应**：`{ upload_url, blob_key, expire_at, owner_aid, bucket, object_key, content_type, size_bytes }`
+
+**权限**：仅所有者可申请。
+
+**流程**：客户端获取 `upload_url` 后，直接 HTTP PUT 上传文件内容，完成后调用 `complete_upload` 确认。
+
+**当前实现补充**：`create_upload_session` 签发 URL 时不做配额与最终文件大小的强校验；配额、`max_file_size_bytes`、SHA-256/size 校验在 `complete_upload` 阶段执行。
+
+### `storage.complete_upload`
+
+确认上传完成，将 blob 关联为正式对象。
+
+**参数**：
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|:----:|------|
+| `owner_aid` | string | ❌ | 默认调用者 AID |
+| `bucket` | string | ❌ | 默认 `"default"` |
+| `object_key` | string | ✅ | 对象路径 |
+| `content_type` | string | ❌ | 默认 `application/octet-stream` |
+| `is_private` | boolean | ❌ | 默认 `true` |
+| `sha256` | string | ❌ | 期望哈希，服务端校验 |
+| `size_bytes` | integer | ❌ | 期望大小，服务端校验 |
+| `expire_in_seconds` | integer | ❌ | 过期时间，默认永不过期 |
+| `metadata` | object | ❌ | 用户自定义元数据 |
+| `expected_version` | integer | ❌ | CAS 并发控制 |
+
+**响应**：`{ owner_aid, bucket, object_key, size_bytes, content_type, sha256, version, etag, updated_at }`
+
+**权限**：仅所有者可确认。
+
+### `storage.create_download_ticket`
+
+申请下载预签名 URL。
+
+**参数**：
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|:----:|------|
+| `owner_aid` | string | ❌ | 默认调用者 AID |
+| `bucket` | string | ❌ | 默认 `"default"` |
+| `object_key` | string | ✅ | 对象路径 |
+| `expire_in_seconds` | integer | ❌ | URL 有效期，默认 3600 秒 |
+
+**响应**：`{ download_url, expire_at, file_name, size_bytes, content_type, sha256, version, etag }`
+
+**权限**：私有对象仅所有者；公开对象任何 AID 可申请。
+
+---
+
+## 11.6 事件
+
+### `event/storage.object_changed`
+
+对象变更时推送给所有者。
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "event/storage.object_changed",
+  "params": {
+    "module_id": "storage",
+    "action": "put",
+    "owner_aid": "alice.aid.pub",
+    "object_key": "docs/report.pdf"
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `action` | string | `"put"` 或 `"delete"` |
+| `owner_aid` | string | 对象所有者 AID |
+| `object_key` | string | 变更的对象路径 |
+
+---
+
+## 11.7 错误码
+
+| 错误码 | 含义 | 说明 |
+|--------|------|------|
+| -32008 | Object not found | 对象不存在 |
+| -32009 | Version conflict | CAS 版本不匹配 |
+| -32004 | Permission denied | 非所有者访问私有对象 |
+
+---
+
+## 11.8 大对象上传流程
+
+```
+客户端                          Storage 服务                    HTTP 数据面
+  │                                │                              │
+  │─ storage.create_upload_session ►│                              │
+  │◄─ { upload_url, blob_key }  ───│                              │
+  │                                │                              │
+  │─────────── HTTP PUT upload_url ─────────────────────────────► │
+  │◄──────────────── 200 OK ─────────────────────────────────────│
+  │                                │                              │
+  │─ storage.complete_upload ─────►│                              │
+  │◄─ { object_key, sha256, ... } ─│                              │
+```
+
+大对象下载流程类似：`create_download_ticket` 获取 `download_url`，客户端直接 HTTP GET。

package/_packed_docs/protocol/12-Stream-/345/255/220/345/215/217/350/256/256.md

@@ -0,0 +1,329 @@
+# 12. Stream 子协议
+
+> **适用版本**：AUN 1.0 | **状态**：Draft
+
+Stream 服务是 AUN 协议的应用层扩展，提供实时流式数据传输能力。典型场景包括 LLM 逐字输出、实时数据推送、JSON 对象流等。Stream 服务采用控制面与数据面分离架构：控制面通过 `stream.*` JSON-RPC 方法管理流的生命周期，数据面通过独立端口的 WebSocket（推流）和 HTTP SSE（拉流）传输数据。
+
+---
+
+## 12.1 设计原则
+
+- **控制面与数据面分离**：`stream.*` RPC 方法管理流的创建、关闭和查询；实际数据通过独立的 WebSocket / HTTP SSE 端点传输
+- **能力 URL 鉴权**：当前实现中，推流和拉流都以 token 作为主要能力凭证；`target_aid` 仅对拉流侧提供可选附加约束
+- **URL 即凭证**：`stream.create` 返回的 push_url / pull_url 内含 token，持有 URL 即可操作流，便于通过 `message.send` 传递给接收方
+- **无协商流程**：不需要 accept/reject，创建即可推流，适合 LLM 等单向输出场景
+- **内存缓冲 + 实时广播**：推送的数据帧先写入内存缓冲区，同时广播到所有在线拉流端；后加入的拉流端先回放缓冲区再接收实时数据
+
+---
+
+## 12.2 架构与角色
+
+```mermaid
+sequenceDiagram
+    participant Pusher as 推流方 (本域 AID)
+    participant Gateway as Gateway
+    participant Stream as Stream 服务
+    participant Puller as 拉流方 (可跨域)
+    
+    Pusher->>Gateway: 1. stream.create (RPC)
+    Gateway->>Stream: 转发
+    Stream-->>Gateway: {push_url, pull_url}
+    Gateway-->>Pusher: 返回 URL
+    
+    Pusher->>Puller: 2. message.send(pull_url)
+    
+    Pusher->>Stream: 3. WebSocket 推流<br/>stream.{issuer}:9490/push/xxx
+    Puller->>Stream: 4. HTTP SSE 拉流<br/>stream.{issuer}:9490/pull/xxx
+    
+    Pusher->>Stream: 5. cmd: close
+    Stream-->>Puller: event: done
+```
+
+- **Stream 服务**：独立模块，控制面通过 JSON-RPC 2.0 提供流管理方法，数据面监听独立端口（默认 9490）
+- **推流方**：创建流的 AID，通过 WebSocket 连接 push_url 发送数据帧
+- **拉流方**：持有 pull_url 的任意客户端，通过 HTTP SSE 接收数据
+
+---
+
+## 12.3 约束与限制
+
+| 约束 | 默认值 | 说明 |
+|------|--------|------|
+| 最大并发流数 | 200 | 服务全局活跃流上限 |
+| 单帧大小 | 无显式限制 | 受 WebSocket 帧上限约束（64 MB） |
+| 流空闲超时 | 300 秒 | 无推送也无拉取时自动关闭 |
+| 推流端离线超时 | 120 秒 | 推流 WebSocket 断开后等待重连 |
+| SSE 心跳间隔 | 10 秒 | 无数据时发送 `: keep-alive` 注释 |
+| 单流最大拉流端 | 10 | 同一流的并发拉流连接数 |
+| push_token / pull_token | 32 字节 hex | 随机生成，流关闭即失效 |
+
+---
+
+## 12.4 数据模型
+
+### StreamSession 对象
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `stream_id` | string | 流唯一 ID（16 位 hex） |
+| `creator_aid` | string | 创建者 AID |
+| `content_type` | string | 内容类型（如 `text/plain`、`application/json-stream`） |
+| `metadata` | object | 自定义元数据 |
+| `status` | string | `"waiting"` / `"active"` / `"done"` |
+| `is_online` | boolean | 推流端是否在线 |
+| `seq` | integer | 当前最大序列号 |
+| `frames_pushed` | integer | 已推送帧数 |
+| `bytes_pushed` | integer | 已推送字节数 |
+| `puller_count` | integer | 当前拉流端数量 |
+| `age_seconds` | float | 流存活时间 |
+| `idle_seconds` | float | 最近一次活动距今时间 |
+
+### 流状态说明
+
+| 状态 | 含义 |
+|------|------|
+| `waiting` | 已创建，推流端尚未连接 |
+| `active` | 推流端在线，正在传输数据 |
+| `done` | 流已关闭（推流方主动关闭或超时） |
+
+---
+
+## 12.5 控制面方法（JSON-RPC 2.0，通过 Gateway）
+
+### `stream.create`
+
+创建一条新的流，返回推流和拉流 URL。
+
+**参数**：
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|:----:|------|
+| `content_type` | string | ❌ | 内容类型，默认 `"text/plain"` |
+| `metadata` | object | ❌ | 自定义元数据 |
+| `target_aid` | string | ❌ | 绑定拉流方 AID。当前实现中，只有拉流方显式提供 `aid` 时才会做该匹配校验 |
+
+**返回**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `stream_id` | string | 流 ID |
+| `push_url` | string | 推流 WebSocket URL（含 push_token） |
+| `pull_url` | string | 拉流 HTTP SSE URL（含 pull_token） |
+| `push_token` | string | 推流凭证 |
+| `pull_token` | string | 拉流凭证（便于单独传递） |
+| `push_headers` | object | 推流推荐使用的 Header（`{"Authorization": "Bearer {push_token}"}`） |
+| `pull_headers` | object | 拉流推荐使用的 Header（`{"Authorization": "Bearer {pull_token}"}`） |
+
+**示例**：
+
+```json
+// 请求
+{"jsonrpc":"2.0","id":"1","method":"stream.create","params":{"content_type":"text/plain"}}
+
+// 响应
+{
+  "jsonrpc":"2.0","id":"1",
+  "result":{
+    "stream_id":"4d5067f203cf42ba",
+    "push_url":"wss://stream.aid.com:9490/push/4d5067f203cf42ba?token=ec80...",
+    "pull_url":"https://stream.aid.com:9490/pull/4d5067f203cf42ba?token=c438...",
+    "push_token":"ec80...",
+    "pull_token":"c438953be0ca887b...",
+    "push_headers":{"Authorization":"Bearer ec80..."},
+    "pull_headers":{"Authorization":"Bearer c438953be0ca887b..."}
+  }
+}
+```
+
+---
+
+### `stream.close`
+
+关闭流。仅流的创建者可调用。关闭后所有拉流端收到 `event: done`。
+
+**参数**：
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|:----:|------|
+| `stream_id` | string | ✅ | 流 ID |
+
+**返回**：`{ "success": true }`
+
+---
+
+### `stream.get_info`
+
+获取流的状态和统计信息。
+
+**参数**：
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|:----:|------|
+| `stream_id` | string | ✅ | 流 ID |
+
+**返回**：StreamSession 对象（见 12.4）。
+
+---
+
+### `stream.list_active`
+
+列出当前 AID 创建的所有活跃流。
+
+**参数**：无。
+
+**返回**：`{ "streams": [StreamSession, ...] }`
+
+---
+
+## 12.6 数据平面（独立端口）
+
+Stream 服务在独立端口（默认 9490）上监听，提供推流和拉流端点。
+
+### 推流端点
+
+```
+GET /push/{stream_id}?token={push_token}  →  WebSocket 升级
+```
+
+**认证**：当前实现优先读取 `Authorization: Bearer {push_token}`，回退兼容 `?token={push_token}` 查询参数。
+
+**WebSocket 帧格式**（客户端 → 服务端）：
+
+```json
+{"cmd": "data", "data": "chunk内容", "seq": 1}
+{"cmd": "data", "data": "chunk内容", "seq": 2}
+{"cmd": "close"}
+```
+
+| 字段 | 类型 | 必需 | 说明 |
+|------|------|:----:|------|
+| `cmd` | string | ✅ | `"data"` 或 `"close"` |
+| `data` | string | `data`时✅ | 数据内容，无大小限制（受 WS 帧 64MB 上限约束） |
+| `seq` | integer | ❌ | 序列号，不提供则服务端自增 |
+
+**关闭流**：发送 `{"cmd": "close"}` 后服务端关闭流并通知所有拉流端。
+
+**断线重连**：推流 WebSocket 断开后，服务端保留流状态最多 120 秒（`pusher_offline_timeout`），期间重连可继续推送。
+
+---
+
+### 拉流端点
+
+```
+GET /pull/{stream_id}?token={pull_token}&aid={puller_aid}  →  HTTP SSE
+```
+
+**认证**：
+- `token`：当前实现优先读取 `Authorization: Bearer {pull_token}`，回退兼容 `?token={pull_token}`
+- `aid`：当前实现优先读取 `X-Stream-AID` 请求头，回退兼容 `?aid={puller_aid}`
+- `target_aid`：若流配置了 `target_aid` 且请求方显式提供了 `aid`，二者必须匹配；未提供 `aid` 时当前实现仍以 `pull_token` 为准
+
+**SSE 响应格式**：
+
+```
+HTTP/1.1 200 OK
+Content-Type: text/event-stream
+Cache-Control: no-cache
+Connection: keep-alive
+
+data: Hello 
+
+data: World
+
+event: done
+data: {}
+```
+
+- `data:` 字段是推流方发送的原始数据内容
+- 流结束时发送 `event: done`
+- 无数据期间每 10 秒发送 `: keep-alive` 注释（SSE 标准心跳）
+
+**断线续拉**：当前实现支持标准 SSE `Last-Event-ID`。服务端在每个 SSE 数据块中输出 `id: {seq}`，客户端重连时可携带 `Last-Event-ID`，服务端会跳过 `seq <= Last-Event-ID` 的缓冲数据后继续推送。
+
+**当前实现补充**：历史仅保留在内存缓冲中。早于当前缓冲区最小 seq 的缺口不会返回显式 gap 错误，服务端会从仍保留的最早帧继续推送。
+
+**Late Joiner**：拉流端连接时，先回放缓冲区中的历史数据，再切换为实时接收。
+
+---
+
+### 健康检查
+
+```
+GET /health  →  JSON
+```
+
+返回：`{"status": "healthy", "active_streams": 0, "uptime_seconds": 123}`
+
+---
+
+## 12.7 典型流程
+
+### 流程一：LLM 流式输出
+
+```mermaid
+sequenceDiagram
+    participant Alice as Alice (aid.com)
+    participant Stream as Stream Service
+    participant Bob as Bob (aid.net)
+    
+    Alice->>Stream: stream.create
+    Stream-->>Alice: {push_url, pull_url}
+    
+    Alice->>Bob: message.send(pull_url)
+    
+    Alice->>Stream: WS /push/xxx (data frames)
+    Bob->>Stream: SSE /pull/xxx
+    Stream-->>Bob: data:Hello
+    Stream-->>Bob: data:World
+    
+    Alice->>Stream: WS cmd:close
+    Stream-->>Bob: event:done
+```
+
+### 流程二：Late Joiner 回放
+
+```mermaid
+sequenceDiagram
+    participant Alice
+    participant Stream as Stream Service
+    participant Bob
+    
+    Alice->>Stream: push seq:1 "A"
+    Alice->>Stream: push seq:2 "B"
+    Note over Stream: buffer: [1:A, 2:B]
+    
+    Bob->>Stream: SSE /pull/xxx
+    Stream-->>Bob: 回放 data:A
+    Stream-->>Bob: 回放 data:B
+    
+    Alice->>Stream: push seq:3 "C"
+    Stream-->>Bob: 实时 data:C
+```
+
+---
+
+## 12.8 安全考量
+
+1. **推流域限制**：push_token 在 `stream.create` 时生成，仅返回给创建者（本域已认证 AID），外域无法获取
+2. **拉流 token 鉴权**：pull_token 为 32 字节随机 hex，持有即可拉流；`target_aid` 在当前实现里是附加校验，而不是替代 token 的强绑定
+3. **URL 传递安全**：pull_url 应通过 E2EE 加密的 `message.send` 传递，避免 token 泄露；新客户端优先使用 `push_headers` / `pull_headers`，减少 token 出现在日志、Referer 和浏览器历史中的机会
+4. **传输加密**：数据平面支持 TLS（wss:// / https://），生产环境必须启用
+5. **资源保护**：单流最大 10 个拉流端，全局最大 200 条活跃流，空闲自动关闭
+
+---
+
+## 12.9 错误码
+
+| code | message | 说明 |
+|------|---------|------|
+| -33401 | Stream not found | stream_id 无效或流已被清理 |
+| -33402 | Stream limit exceeded | 活跃流数超过上限 |
+| -33403 | Stream permission denied | 非创建者执行受限操作 |
+| -33404 | Stream already closed | 流已关闭 |
+| -33405 | Stream invalid params | 参数无效（如缺少 stream_id） |
+| -33406 | Stream rate limited | 速率限制 |
+| -33407 | Stream internal error | 服务内部错误 |
+| HTTP 403 | — | push/pull token 无效，或请求方显式提供的 `aid` 与 `target_aid` 不匹配 |
+| HTTP 404 | — | 数据平面找不到流 |
+| HTTP 410 | — | 流已关闭 |
+| HTTP 429 | — | 拉流端数量已达上限 |