@agentunion/fastaun-browser 0.3.6 → 0.4.0

package/_packed_docs/INDEX.md

@@ -8,8 +8,9 @@
 
 | 文档 | 定位 |
 | --- | --- |
-| [aun测试运行指南](aun测试运行指南.md) | 当前 Docker 单域、双域、多语言 SDK 测试运行命令 |
-| [跨语言容器E2E测试方案](design/跨语言容器E2E测试方案.md) | 多语言 SDK 同网同服、test-runner 控制面的跨语言 E2E 方案 |
+| [aun测试运行指南](aun测试运行指南.md) | 当前 Docker 单域、双域、多语言 SDK 测试运行命令 |
+| [AUN SDK 重构修改清单](AUN_SDK_重构修改清单.md) | 本轮 SDK 重构的实际修改点、测试结果和遗留事项 |
+| [跨语言容器E2E测试方案](design/跨语言容器E2E测试方案.md) | 多语言 SDK 同网同服、test-runner 控制面的跨语言 E2E 方案 |
 | [E2EE V2 简化为 1DH + Per-AID Wrap 方案](design/E2EE_V2简化为1DH加Per-AID_Wrap方案.md) | SDK bootstrap 能力声明 + 服务端 policy 控制 1DH/per-AID wrap 的兼容方案 |
 | [AUN RPC Trace 增强设计](design/2026-05-22-aun-rpc-trace-enhancement.md) | RPC trace 诊断字段与 enter/exit span 设计 |
 | [远程 agent.md 缓存与 ETag 透传方案](agent.md/远程agent.md缓存与etag透传方案.md) | 远程 agent.md per-AID 缓存、SQLite 表、消息信封与 RPC 响应 ETag 透传方案 |
@@ -25,8 +26,9 @@
 
 ### 测试与 E2E
 
-- 现有测试命令、容器名、单域/双域运行入口 → [aun测试运行指南](aun测试运行指南.md)
-- Python / TypeScript / Go / C++ 跨语言容器 E2E、test-runner、test-control API、用例矩阵 → [aun测试运行指南](aun测试运行指南.md)、[跨语言容器E2E测试方案](design/跨语言容器E2E测试方案.md)
+- 现有测试命令、容器名、单域/双域运行入口 → [aun测试运行指南](aun测试运行指南.md)
+- 本轮 SDK 重构阶段进度、修改点和测试结果 → [AUN SDK 重构修改清单](AUN_SDK_重构修改清单.md)
+- Python / TypeScript / Go / C++ 跨语言容器 E2E、test-runner、test-control API、用例矩阵 → [aun测试运行指南](aun测试运行指南.md)、[跨语言容器E2E测试方案](design/跨语言容器E2E测试方案.md)
 - 多语言 SDK 测试缺口与补测清单 → [审查与路线图目录](audit/)
 
 ### SDK 使用与协议
@@ -52,13 +54,17 @@
 
 ## Layer 3：重点文档摘要
 
-### aun测试运行指南
-
-记录当前 AUN 服务与 SDK 在 Docker 单域、双域环境中的实际测试入口。包含 Python、TypeScript、Go、JavaScript、C++ 五语言测试矩阵，Python / TypeScript / Go / C++ 跨语言容器 E2E 的 69 用例矩阵，覆盖 P2P 明文/E2EE、群聊 pairwise 明文/E2EE，以及四语言 agent 同群的明文/E2EE 矩阵，另包含固定身份目录、容器名、典型命令、浏览器 E2E、C++ Docker 测试、双域 federation 测试和数据保护规则。
-
-### 跨语言容器E2E测试方案
-
-定义多语言 SDK 同时作为真实客户端运行的目标测试体系。核心模型是每个语言一个客户端容器，全连接同一 AUN server / gateway；业务消息走 AUN，test-runner 通过每个客户端暴露的 test-control HTTP API 编排动作和断言结果。当前单域落地覆盖 Python / TypeScript / Go / C++，浏览器 JavaScript 仍按宿主机 Playwright 运行。
+### aun测试运行指南
+
+记录当前 AUN 服务与 SDK 在 Docker 单域、双域环境中的实际测试入口。包含 Python、TypeScript、Go、JavaScript、C++ 五语言测试矩阵，Python / TypeScript / Go / C++ 跨语言容器 E2E 的 69 用例矩阵，覆盖 P2P 明文/E2EE、群聊 pairwise 明文/E2EE，以及四语言 agent 同群的明文/E2EE 矩阵，另包含固定身份目录、容器名、典型命令、浏览器 E2E、C++ Docker 测试、双域 federation 测试和数据保护规则。
+
+### AUN SDK 重构修改清单
+
+记录本轮 AUN SDK 重构执行中的阶段进度、实际修改点、测试命令、测试结果和遗留事项。它是实施过程中的工作清单，最终以 SDK 文档和 skill 同步结果为准。
+
+### 跨语言容器E2E测试方案
+
+定义多语言 SDK 同时作为真实客户端运行的目标测试体系。核心模型是每个语言一个客户端容器，全连接同一 AUN server / gateway；业务消息走 AUN，test-runner 通过每个客户端暴露的 test-control HTTP API 编排动作和断言结果。当前单域落地覆盖 Python / TypeScript / Go / C++，浏览器 JavaScript 仍按宿主机 Playwright 运行。
 
 ### E2EE V2 简化为 1DH + Per-AID Wrap 方案
 

package/_packed_docs/KITE_DOCS_GUIDE.md

@@ -8,18 +8,18 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 
 ### Step 1：先读根级 Layer 1
 
-- `docs/INDEX.md` L7-20：根级文档地图。
+- `docs/INDEX.md` L7-21：根级文档地图。
 
 ### Step 2：按主题读根级 Layer 2
 
-- 测试与 E2E：`docs/INDEX.md` L25-29。
-- SDK 使用与协议：`docs/INDEX.md` L31-36。
-- 诊断与可观测性：`docs/INDEX.md` L38-42。
-- E2EE 与跨语言一致性：`docs/INDEX.md` L45-49。
+- 测试与 E2E：`docs/INDEX.md` L27-32。
+- SDK 使用与协议：`docs/INDEX.md` L34-39。
+- 诊断与可观测性：`docs/INDEX.md` L41-45。
+- E2EE 与跨语言一致性：`docs/INDEX.md` L47-51。
 
 ### Step 3：需要判断文档价值时读 Layer 3 摘要
 
-- `docs/INDEX.md` L53-81：重点文档摘要。
+- `docs/INDEX.md` L55-87：重点文档摘要。
 
 ### Step 4：再读目标文档章节
 
@@ -27,10 +27,11 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 
 ## 常见查阅场景
 
-| 场景 | 推荐读取 |
-| --- | --- |
-| 当前 Docker 单域/双域测试怎么跑 | `docs/aun测试运行指南.md` L5-46、L65-80 |
-| 测试环境数据保护规则 | `docs/aun测试运行指南.md` L48-63 |
+| 场景 | 推荐读取 |
+| --- | --- |
+| 当前 Docker 单域/双域测试怎么跑 | `docs/aun测试运行指南.md` L5-46、L65-80 |
+| 本轮 SDK 重构修改清单 | `docs/AUN_SDK_重构修改清单.md` |
+| 测试环境数据保护规则 | `docs/aun测试运行指南.md` L48-63 |
 | 单域 Docker 测试容器和命令 | `docs/aun测试运行指南.md` L113-533 |
 | 跨语言容器 E2E 执行方式 | `docs/aun测试运行指南.md` L146-263 |
 | 双域 federation 测试容器和命令 | `docs/aun测试运行指南.md` L534-714 |

package/_packed_docs/sdk/01-/345/277/253/351/200/237/345/274/200/345/247/213.md

@@ -1,6 +1,6 @@
-# AUN SDK Python - 快速开始
+# AUN SDK - 快速开始
 
-**版本**: 0.2.8 | **Python**: >= 3.11
+**版本**: 0.4.0+ | **Python**: >= 3.11
 
 ---
 
@@ -12,128 +12,87 @@ pip install fastaun
 
 ---
 
+## 核心模型
+
+重构后的 SDK 分为三个主体：
+
+| 主体 | 职责 |
+|------|------|
+| `AIDStore` | 管理本地 keystore，负责注册、加载、解析 AID |
+| `AID` | 不可变身份值对象，持有证书和私钥能力 |
+| `AUNClient` | 管理认证、连接、状态机、RPC 和事件 |
+
+构造规则：
+
+- `AUNClient()`：无身份客户端，状态为 `no_identity`，随后用 `load_identity(AID对象)` 加载身份。
+- `AUNClient(aid)`：带身份客户端，`aid` 必须是 `AIDStore.load()` 返回的 AID 对象，状态为 `standby`。
+- TS/JS/Go 同构：只允许 `options` 或 `AID对象 + options`；字符串 AID、把 aid 放进 options、旧 `(config, debug)` 都不是公开入口。
+
+---
+
 ## 最小示例
 
 ```python
-import asyncio, random
+import asyncio
+import random
 from datetime import datetime
-from aun_core import AUNClient
-from aun_core.errors import AUNError, ConnectionError, AuthError
+
+from aun_core import AIDStore, AUNClient
+from aun_core.errors import AUNError
+
+DOMAIN = "agentid.pub"
+ALICE = f"alice-{random.randint(1000, 9999)}.{DOMAIN}"
+BOB = f"bob-{random.randint(1000, 9999)}.{DOMAIN}"
+
 
 def ts():
     return datetime.now().strftime("%H:%M:%S.%f")[:-3]
 
-# ── 配置（按需修改）──
-DOMAIN = "agentid.pub"  # 也支持其它 AP，如 agentcp.io
-ALICE = f"alice{random.randint(1000,9999)}.{DOMAIN}"
-BOB = f"bob{random.randint(1000,9999)}.{DOMAIN}"
-
-
-async def create_client(aid: str) -> tuple[AUNClient, dict]:
-    """创建客户端 → 注册 AID → 认证 → 返回 (client, auth)"""
-    client = AUNClient()  # 默认 aun_path: ~/.aun
-
-    # 先检查本地是否已有该 AID 的身份
-    known = any(item["aid"] == aid for item in client.list_identities())
-    if not known:
-        # 不存在则注册
-        try:
-            await client.auth.register_aid({"aid": aid})
-        except AuthError as e:
-            print(f"[错误] 注册 AID 失败 ({aid}): {e}")
-            raise
-        except ConnectionError as e:
-            print(f"[错误] 网络连接失败: {e}")
-            raise
-        except Exception as e:
-            print(f"[错误] 未知错误: {e}")
-            raise
 
-    try:
-        auth = await client.auth.authenticate({"aid": aid})
-        return client, auth
-    except AuthError as e:
-        print(f"[错误] 认证失败 ({aid}): {e}")
-        raise
-    except ConnectionError as e:
-        print(f"[错误] 网络连接失败: {e}")
-        raise
+async def load_or_register(store: AIDStore, aid: str):
+    loaded = store.load(aid)
+    if loaded["ok"]:
+        return loaded["data"]["aid"]
+
+    registered = await store.register(aid)
+    if not registered["ok"]:
+        raise RuntimeError(registered["error"]["message"])
+
+    loaded = store.load(aid)
+    if not loaded["ok"]:
+        raise RuntimeError(loaded["error"]["message"])
+    return loaded["data"]["aid"]
+
+
+async def create_client(aid: str) -> AUNClient:
+    store = AIDStore(aun_path="~/.aun/myapp", encryption_seed="")
+    identity = await load_or_register(store, aid)
+    client = AUNClient(identity, debug=True)
+    await client.connect({"slot_id": "main", "auto_reconnect": True})
+    return client
 
 
 async def main():
-    alice = None
-    bob = None
+    alice = await create_client(ALICE)
+    bob = await create_client(BOB)
+
+    received = asyncio.Event()
+    bob.on("message.received", lambda e: (print(f"[{ts()}] Bob 收到: {e['payload']}"), received.set()))
+
+    await alice.call("message.send", {
+        "to": BOB,
+        "payload": {"type": "text", "text": "Hello from Alice!"},
+    })
 
     try:
-        # 1. 创建两个客户端
-        alice, alice_auth = await create_client(ALICE)
-        bob, bob_auth = await create_client(BOB)
-
-        # 2. Bob 订阅消息事件
-        received = asyncio.Event()
-        def on_bob_message(event):
-            print(f"[{ts()}] [Bob 收到] {event['payload']}")
-            received.set()
-
-        bob.on("message.received", on_bob_message)
-
-        # 3. 双方连接到网关
-        try:
-            await alice.connect(alice_auth, {})
-            await bob.connect(bob_auth, {})
-            print(f"[{ts()}] Alice ({ALICE}) 已连接")
-            print(f"[{ts()}] Bob   ({BOB}) 已连接")
-        except ConnectionError as e:
-            print(f"[错误] 连接网关失败: {e}")
-            raise
-
-        # 4. Alice 发消息给 Bob
-        try:
-            result = await alice.call("message.send", {
-                "to": BOB,
-                "payload": {"type": "text", "text": "Hello from Alice!"},
-            })
-            print(f"[{ts()}] [Alice 发送] {result}")
-        except AUNError as e:
-            print(f"[错误] 发送消息失败: {e}")
-            raise
-
-        # 5. 等待 Bob 收到消息（最多 5 秒）
-        try:
-            await asyncio.wait_for(received.wait(), timeout=5.0)
-        except asyncio.TimeoutError:
-            # 事件推送未触发，尝试主动拉取
-            try:
-                pull = await bob.call("message.pull", {"after_seq": 0, "limit": 10})
-                msgs = pull.get("messages", [])
-                if msgs:
-                    print(f"[{ts()}] [Bob 拉取] 收到 {len(msgs)} 条消息:")
-                    for m in msgs:
-                        print(f"  {m.get('payload')}")
-                else:
-                    print(f"[{ts()}] [Bob] 未收到消息")
-            except AUNError as e:
-                print(f"[错误] 拉取消息失败: {e}")
-
-        print(f"[{ts()}] 完成")
-
-    except KeyboardInterrupt:
-        print(f"\n[{ts()}] 用户中断")
-    except Exception as e:
-        print(f"[{ts()}] 程序异常: {e}")
-        raise
-    finally:
-        # 6. 关闭连接
-        if alice:
-            try:
-                await alice.close()
-            except Exception:
-                pass
-        if bob:
-            try:
-                await bob.close()
-            except Exception:
-                pass
+        await asyncio.wait_for(received.wait(), timeout=5)
+    except asyncio.TimeoutError:
+        pull = await bob.call("message.pull", {"after_seq": 0, "limit": 10})
+        for msg in pull.get("messages", []):
+            print(f"[{ts()}] Bob 拉取: {msg.get('payload')}")
+
+    await alice.close()
+    await bob.close()
 
 
 asyncio.run(main())
@@ -143,81 +102,98 @@ asyncio.run(main())
 
 ## 配置
 
-### 构造参数
+`AIDStore` 持有本地数据目录和密钥保护配置：
+
+```python
+store = AIDStore(
+    aun_path="~/.aun/myapp",
+    encryption_seed="",
+    device_id=None,
+    slot_id="default",
+    debug=True,
+)
+```
+
+`AUNClient` 只接收 AID 对象和连接级选项：
 
 ```python
-client = AUNClient({
-    "aun_path": "~/.aun/myapp",        # 应用级数据目录（AID 数据在其下的 AIDs/{aid}/ 中）
-    "root_ca_path": "/path/to/ca.pem", # 额外 Root CA（可选）
-    "seed_password": "seed",           # 本地存储保护口令（可选）
-})
+identity = store.load("alice.agentid.pub")["data"]["aid"]
+client = AUNClient(identity, debug=True, protected_headers={"sdk": "python"})
+await client.connect({"slot_id": "main", "connection_kind": "long"})
 ```
 
-`verify_ssl` 不在构造参数中配置。Python / TS / Go SDK 会根据环境变量自动决定：
+`verify_ssl` 不在 `AUNClient` 构造参数中配置。Python / TS / Go SDK 会根据环境变量自动决定：
 
 - `AUN_ENV` 优先，其次 `KITE_ENV`
 - 值为 `development` / `dev` / `local` 时关闭证书校验
 - 其他值或未配置时开启证书校验
 
-> **默认行为**：SDK 默认启用 P2P E2EE；Group E2EE 为必选能力并固定启用。`message.send` 和 `group.send` 默认加密发送，`group.thought.put` 强制加密发送；如需发送明文普通消息，显式传入 `encrypt=False`。`slot_id` 和 `delivery_mode` 只在 `connect(...)` 阶段传入。
-
-完整参数列表见 [API 手册](06-API手册.md)。
+---
 
-### 数据目录布局
+## 数据目录布局
 
 SDK 使用 `{aun_path}/AIDs/{aid}/` 存储每个 AID 的专属数据：
 
-```
-{aun_path}/                              # 应用级数据根目录
-├── .device_id                           # 设备级稳定标识（默认写在 ~/.aun/.device_id）
-└── AIDs/                                # AID 数据根
-    ├── alice.agentid.pub/               # Alice 的全部数据
-    │   ├── private/key.json             # ECDSA 私钥（加密保护）
-    │   ├── public/cert.pem              # X.509 证书
-    │   └── tokens/meta.json             # 令牌 + E2EE 密钥 + 元数据
-    └── bob.agentid.pub/                 # Bob 的全部数据（多 AID 共存）
+```text
+{aun_path}/
+├── .device_id
+└── AIDs/
+    ├── alice.agentid.pub/
+    │   ├── private/key.json
+    │   ├── public/cert.pem
+    │   └── tokens/meta.json
+    └── bob.agentid.pub/
         ├── private/key.json
         ├── public/cert.pem
         └── tokens/meta.json
 ```
 
-**路径模型要点**：
+要点：
 
-- **`aun_path`** 是应用级目录，不是 AID 级目录。一个 `aun_path` 下可管理多个 AID
-- **`aun_path` 不要用 AID 命名**（如 `~/.aun/{aid}`），否则会产生 `~/.aun/{aid}/AIDs/{aid}/` 的冗余嵌套
-- 默认路径为 `~/.aun`
-- 推荐用应用名或用途命名：`~/.aun/myapp`、`~/.aun/testing`
+- `aun_path` 是应用级目录，一个目录可管理多个 AID。
+- 不要用 AID 名称作为 `aun_path`，避免出现 `~/.aun/{aid}/AIDs/{aid}/` 冗余嵌套。
+- 私钥、令牌、群密钥等敏感数据由 SDK 的本地保护机制保存，不应手工删除或迁移单个文件。
 
-### connect 阶段的多实例参数
+---
 
-```python
-await client.connect(auth, {
-    "slot_id": "slot-a",
-    "delivery_mode": {
-        "mode": "queue",
-        "routing": "sender_affinity",
-        "affinity_ttl_ms": 300000,
-    },
-})
+## 多语言构造示例
+
+TypeScript / Node：
+
+```ts
+const store = new AIDStore({ aunPath: "~/.aun/myapp", encryptionSeed: "" });
+const loaded = store.load("alice.agentid.pub");
+const client = new AUNClient(loaded.data!.aid, { debug: true });
+```
+
+JavaScript / 浏览器：
+
+```js
+const store = new AIDStore({ aunPath: "browser-demo", encryptionSeed: "" });
+const loaded = await store.load("alice.agentid.pub");
+const client = new AUNClient(loaded.data.aid, { debug: true });
 ```
 
-- `slot_id` 由应用层传入；空字符串表示该设备只运行一个实例
-- `delivery_mode` 只在 `connect(...)` 传入；同一 AID 的所有在线实例必须保持一致
+Go：
 
-**敏感数据保护**：`private/key.json` 和 `tokens/meta.json` 中的私钥、令牌、群密钥等敏感字段不以明文存储，而是通过平台密钥链（Windows DPAPI / macOS Keychain / Linux libsecret）加密保护。
+```go
+store := aun.NewAIDStore("~/.aun/myapp", "")
+aid, err := store.Load("alice.agentid.pub")
+if err != nil {
+    return err
+}
+client := aun.NewAUNClient(aid, aun.AUNClientOptions{Debug: true})
+```
 
 ---
 
 ## 核心流程
 
-完整的使用流程见上方"最小示例"，核心步骤：
-
-1. **创建客户端** - `AUNClient(config)`
-2. **注册 AID** - `check_aid()` → `register_aid()`
-3. **认证** - `authenticate()` 获取令牌
-4. **订阅事件** - `on("message.received", handler)`
-5. **连接** - `connect(auth, options)`
-6. **业务操作** - `call("message.send", params)`
-7. **关闭** - `close()`
+1. 创建 `AIDStore`。
+2. `store.load(aid)` 加载本地 AID；本地不存在时调用 `store.register(aid)` 后再次加载。
+3. 用 AID 对象构造 `AUNClient(aid, ...)`，或先 `AUNClient()` 再 `load_identity(aid)`。
+4. 先注册事件处理器，再调用 `connect(options)`。
+5. 通过 `call(method, params)` 执行业务 RPC。
+6. 通过 `close()` 释放连接和后台任务。
 
-详细 API 说明见 [06-API手册.md](06-API手册.md)，RPC 方法参数见各领域的 RPC 手册。
+详细 API 见 [06-API手册.md](06-API手册.md)，RPC 参数见各领域的 `09-*-rpc-manual.md`。

package/_packed_docs/sdk/02-WebSocket/345/215/217/350/256/256.md

@@ -185,7 +185,7 @@ sequenceDiagram
 ```python
 import asyncio, json, random, secrets
 from datetime import datetime
-from aun_core import AUNClient
+from aun_core import AIDStore, AUNClient
 from aun_core.errors import AUNError, ConnectionError, AuthError
 import websockets
 
@@ -206,13 +206,17 @@ def make_rpc(method: str, params: dict) -> tuple[str, str]:
 
 
 async def authenticate(aid: str) -> dict:
-    """用 SDK 完成 AID 创建和认证，返回 auth 结果（含 access_token + gateway）"""
+    """用 SDK 完成 AID 注册/加载和认证，返回 access_token + gateway。"""
     try:
-        client = AUNClient({"aun_path": f"~/.aun/{aid}"})
-        if not client._auth.load_identity_or_none(aid):
-            await client.auth.register_aid({"aid": aid})
-        auth = await client.auth.authenticate({"aid": aid})
-        return auth
+        store = AIDStore(aun_path="~/.aun/ws-demo", encryption_seed="")
+        loaded = store.load(aid)
+        if not loaded["ok"]:
+            registered = await store.register(aid)
+            if not registered["ok"]:
+                raise AuthError(registered["error"]["message"])
+            loaded = store.load(aid)
+        client = AUNClient(loaded["data"]["aid"])
+        return await client.authenticate()
     except AuthError as e:
         print(f"[错误] 认证失败 ({aid}): {e}")
         raise