@agentunion/fastaun-browser 0.2.19 → 0.3.0

package/_packed_docs/python-sdk-v2-only-changelog.md

@@ -0,0 +1,189 @@
+# Python SDK V2-Only 改动清单
+
+基线：`d8b79f44` (v0.2.20 之后，master_1.0.0 分支)
+日期：2026-05-20
+
+## 一、源码改动（`python/src/aun_core/`）
+
+### 1. client.py：8588 行 → 4502 行（净删 4086 行）
+
+#### 删除的 V1 E2EE 代码（共 ~95 个方法）
+
+**V1 P2P 加密：**
+- `_send_encrypted`, `_build_self_sync_copies`, `_build_recipient_device_copies`
+- `_encrypt_copy_payload`, `_ensure_encrypt_result`, `_resolve_self_copy_peer_cert`
+- `_log_e2ee_error`
+
+**V1 群组加密：**
+- `_send_group_encrypted`, `_put_group_thought_encrypted`, `_put_message_thought_encrypted`
+- `_call_group_encrypted_rpc`, `_prepare_group_encrypted_rpc_params`
+
+**V1 Epoch 管理：**
+- `_recover_group_epoch_key`, `_do_recover_group_epoch_key`, `_try_recover_epoch_key_from_server`
+- `_recover_initial_group_epoch_if_needed`, `_request_group_key_from_candidates`
+- `_request_group_key_from_online`, `_request_group_key_from`
+- `_group_epoch_secret_ready_for_recovery`, `_pending_group_secret_still_current`
+- `_ensure_group_epoch_ready`, `_wait_for_group_membership_epoch_floor`
+- `_committed_group_epoch`, `_committed_group_epoch_state`
+- `_ensure_committed_group_secret_for_send`, `_committed_rotation_membership_gap`
+
+**V1 密钥控制面：**
+- `_try_handle_group_key_message`, `_verify_active_group_rotation_distribution`
+- `_verify_group_key_response_epoch`, `_discard_group_distribution_if_stale`
+- `_ack_group_rotation_key`
+
+**V1 Epoch 轮换：**
+- `_build_rotation_signature`, `_attach_rotation_id`, `_build_epoch_encrypted_keys`
+- `_distribute_group_epoch_key`, `_heartbeat_group_rotation`, `_abort_group_rotation`
+- `_schedule_group_rotation_retry`, `_sync_epoch_to_server`
+- `_maybe_lead_rotate_group_epoch`, `_ranked_group_rotation_candidates`, `_rotate_group_epoch`
+- `_delayed_rotate_after_join`, `_maybe_backfill_key_to_joined_member`
+- `_distribute_key_to_new_member`, `_start_group_epoch_tasks`
+- `_is_rotation_leader`, `_group_epoch_rotate_loop`, `_group_epoch_cleanup_loop`
+
+**V1 解密：**
+- `_decrypt_messages`, `_decrypt_single_message`
+- `_decrypt_group_message`, `_decrypt_group_messages`
+- `_decrypt_group_thoughts`, `_decrypt_message_thoughts`
+
+**V1 Pending queue：**
+- `_enqueue_pending_decrypt`, `_schedule_retry_pending_decrypt_msgs`
+- `_retry_pending_decrypt_msgs`, `_schedule_recovery_timeout`, `_cleanup_group_state`
+
+**V1 Prekey：**
+- `_upload_prekey`, `_prekey_refresh_loop`, `_start_prekey_refresh_task`
+- `_schedule_prekey_replenish_if_consumed`, `_invalidate_peer_prekey_cache`
+- `_fetch_peer_prekeys`, `_fetch_peer_prekey`, `_normalize_peer_prekeys`
+- `_refresh_peer_prekeys`, `_clear_peer_cert_cache`
+
+**V1 错误辅助：**
+- `_is_group_epoch_too_old_error`, `_is_group_epoch_rotation_pending_error`
+- `_is_group_epoch_changed_during_send_error`, `_is_recoverable_group_epoch_error`
+- `_is_expected_group_rotation_skip_error`
+
+**V1 成员轮换辅助：**
+- `_membership_rotation_trigger_id`, `_membership_rotation_changed`
+- `_membership_rotation_expected_epoch`, `_extract_group_id_from_result`
+- `_get_group_member_aids`, `_local_group_members_match`, `_extract_group_join_mode`
+- `_group_allows_member_epoch_rotation`, `_group_key_recovery_candidates`
+- `_joined_member_aids_from_payload`
+
+**V1 群组推送处理：**
+- `_process_and_publish_group_message`, `_auto_pull_group_messages`, `_fill_group_gap`
+
+**V1 公开 API：**
+- `e2ee` property, `group_e2ee` property
+- `send_v2`, `pull_v2`, `ack_v2`, `send_group_v2`, `pull_group_v2`, `ack_group_v2`
+  （独立方法合并进 `call()` 路由）
+
+#### 删除的 V1 实例变量
+
+- `self._e2ee` (E2EEManager)
+- `self._group_e2ee` (GroupE2EEManager)
+- `self._pending_decrypt_msgs`
+- `self._recovery_timeout_scheduled`
+- `self._group_epoch_rotation_inflight`
+- `self._group_epoch_rotation_retry_tasks`
+- `self._group_epoch_recovery_inflight`
+- `self._group_membership_rotation_done`
+- `self._group_member_key_backfill_done`
+
+#### 新增/修改的逻辑
+
+- `_on_raw_group_message_created`：简化为明文消息透传 + seq 跟踪（不再做 V1 解密）
+- `_process_and_publish_message`：移除 V1 解密调用，明文直接透传
+- `_on_raw_group_changed`：移除 V1 epoch 轮换编排，保留 V2 `_v2_auto_propose_state` + event gap 检测
+- `call()` 中 `message.pull` / `group.pull` 后处理：移除 V1 解密，保留 seq 跟踪 + auto-ack
+- `_stop_background_tasks`：移除 V1 epoch 任务清理
+- `_start_background_tasks`：移除 `_start_group_epoch_tasks()` 调用
+- V2 解密元数据：`e2ee` 字段增加 `encryption_mode` 和 `forward_secrecy`
+- V2 group pull：移除返回值去重（pull 始终返回所有解密成功的消息）
+
+### 2. seq_tracker.py：+14 行
+
+- `on_pull_result` 新增 `after_seq` 参数
+- gap fill 场景（`after_seq == contiguous_seq`）：直接把 pull 到的最大 seq 作为新 `contiguous_seq`，跳过服务端永久空洞
+
+### 3. `__init__.py`：无变化（`ProtectedHeaders` 保留）
+
+### 4. `e2ee.py`：不动（3544 行保留作为参考）
+
+### 5. 保留的 e2ee.py 引用（非 E2EE 加解密）
+
+- `from .e2ee import ProtectedHeaders` — 纯数据类，V2 也用
+- `from .e2ee import compute_state_hash` (2处) — 群组 state hash 验证工具函数
+
+## 二、测试改动（`python/tests/`）
+
+### 删除的测试文件（纯 V1 E2EE）
+
+- `e2e_test_epoch_key_server.py` — V1 epoch key 服务端托管
+- `integration_test_e2ee.py` — V1 P2P E2EE 集成
+- `integration_test_multi_device_e2ee.py` — V1 多设备 E2EE
+- `unit/test_client_group_e2ee.py` — V1 群组 E2EE 单元测试（93 个用例）
+
+### 删除的测试用例（从现有文件中移除）
+
+- `test_client.py`：24 个 V1 测试（prekey、send_encrypted V1、decrypt_group 等）
+- `test_py_issues.py`：`TestPY004PrekeyRefreshLoop`
+- `test_py_issues_batch2.py`：`TestPY001DecryptFailStillAutoAck`、`TestPY002KeyRecoveryRetry`、`TestPY003DissolveCleanup`、`TestPY005RotateLoopLeaderElection`
+- `test_py_issues_batch3.py`：`TestPY002PushedSeqsLimit`、`TestPY005EpochWait`
+
+### 修改的测试
+
+- `test_client.py`：`test_e2ee_property` 改为断言 `e2ee` 属性不存在
+- `integration_test_storage.py`：自定义 redirect handler 支持 PUT 302 重定向
+
+## 三、服务端改动（`extensions/services/`）
+
+| 文件 | 改动 |
+|------|------|
+| `gateway/entry.py` | kernel event 订阅补全 V2 事件（fallback）；`_handle_event_notification` 路由补全 V2 事件 |
+| `gateway/ws_server.py` | `_dispatch_event_from_service` 白名单补全 `group.state_committed` |
+| `gateway/relay.py` | `_should_forward_event` 补全 `group.state_committed`；`_V2_ONLY_GROUP_METHODS` 补全 `propose_state/confirm_state/get_proposal` |
+| `message/entry.py` | `AUN_DIRECT_EVENT_MESSAGE` 默认改为 True；V2 send 返回 status 对齐 V1 语义（`delivered`/`sent`） |
+| `group/entry.py` | `AUN_DIRECT_EVENT_GROUP` 默认改为 True；`_targets_for_group_event` / `is_client_event` 补全 `group.state_committed`；`_rpc_v2_pull` / `_rpc_v2_ack` 补全成员权限检查 |
+
+## 四、Bug 修复（需要其它 SDK 对齐）
+
+### BUG-1: gap fill 时 contiguous_seq 卡死
+
+**根因：** `on_pull_result` 从 `contiguous_seq` 开始 pull，如果服务端返回的消息跳过了某些 seq（永久空洞：竞态跳跃/未持久化/过期清理），`_try_advance` 逐个检查时会卡在第一个缺失的 seq 上，永远无法推进。新消息被阻塞在 SDK 内部有序队列中，上层收不到。
+
+**修复：** `on_pull_result` 新增 `after_seq` 参数。当 `after_seq == contiguous_seq`（gap fill 场景）时，直接把 pull 到的最大 seq 作为新的 `contiguous_seq`。
+
+**影响范围：** P2P pull、group pull、event pull 三条路径。
+
+### BUG-2: V2 group pull 返回值去重导致手动 pull 拿不到已 push 的消息
+
+**根因：** `_pull_group_v2_internal` 中 `_is_published_seq` 去重导致已通过 push 自动 pull 消费的消息在手动 pull 时被跳过，返回空列表。
+
+**修复：** pull 返回值不再做 `_is_published_seq` 去重。`_publish_ordered_message` 内部仍做事件投递去重（防止重复触发应用层回调），但 pull 的返回值始终包含所有解密成功的消息。
+
+### BUG-3: V2 message.send 返回 status 不对齐 V1 语义
+
+**根因：** V2 send 返回 `"status": "accepted"`，但 SDK 和应用层已按 V1 语义（`sent`/`delivered`）实现。
+
+**修复：** 服务端 `delivered_count > 0` 时返回 `delivered`，否则返回 `sent`。
+
+### BUG-4: V2 解密元数据缺少 encryption_mode
+
+**根因：** V2 解密后 `e2ee` 字段只有 `version` + `suite`，缺少 `encryption_mode` 和 `forward_secrecy`，导致依赖这些字段的测试/应用层判断失败。
+
+**修复：** 补全 `encryption_mode: "v2_{suite}"` 和 `forward_secrecy: True`。
+
+## 五、验证结果
+
+| 测试 | 结果 |
+|------|------|
+| 单元测试 | 501 passed |
+| V2 P2P E2EE | 12/12 |
+| V2 Group E2EE | 8/8 |
+| V2 Multi-device | 6/6 |
+| Echo | 5/5 |
+| Message Ack | 4/4 |
+| Storage | 4/4 |
+| 双域明文 | PASS |
+| 双域加密 | PASS |
+| 双域离线 | PASS |
+| 双域群组 | 2/2 |

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

@@ -0,0 +1,223 @@
+# AUN SDK Python - 快速开始
+
+**版本**: 0.2.8 | **Python**: >= 3.11
+
+---
+
+## 安装
+
+```bash
+pip install fastaun
+```
+
+---
+
+## 最小示例
+
+```python
+import asyncio, random
+from datetime import datetime
+from aun_core import AUNClient
+from aun_core.errors import AUNError, ConnectionError, AuthError
+
+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.create_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 main():
+    alice = None
+    bob = None
+
+    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
+
+
+asyncio.run(main())
+```
+
+---
+
+## 配置
+
+### 构造参数
+
+```python
+client = AUNClient({
+    "aun_path": "~/.aun/myapp",        # 应用级数据目录（AID 数据在其下的 AIDs/{aid}/ 中）
+    "root_ca_path": "/path/to/ca.pem", # 额外 Root CA（可选）
+    "seed_password": "seed",           # 本地存储保护口令（可选）
+})
+```
+
+`verify_ssl` 不在构造参数中配置。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 共存）
+        ├── 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`
+
+### connect 阶段的多实例参数
+
+```python
+await client.connect(auth, {
+    "slot_id": "slot-a",
+    "delivery_mode": {
+        "mode": "queue",
+        "routing": "sender_affinity",
+        "affinity_ttl_ms": 300000,
+    },
+})
+```
+
+- `slot_id` 由应用层传入；空字符串表示该设备只运行一个实例
+- `delivery_mode` 只在 `connect(...)` 传入；同一 AID 的所有在线实例必须保持一致
+
+**敏感数据保护**：`private/key.json` 和 `tokens/meta.json` 中的私钥、令牌、群密钥等敏感字段不以明文存储，而是通过平台密钥链（Windows DPAPI / macOS Keychain / Linux libsecret）加密保护。
+
+---
+
+## 核心流程
+
+完整的使用流程见上方"最小示例"，核心步骤：
+
+1. **创建客户端** - `AUNClient(config)`
+2. **加载或创建 AID** - `load_identity_or_none()` → `create_aid()`
+3. **认证** - `authenticate()` 获取令牌
+4. **订阅事件** - `on("message.received", handler)`
+5. **连接** - `connect(auth, options)`
+6. **业务操作** - `call("message.send", params)`
+7. **关闭** - `close()`
+
+详细 API 说明见 [06-API手册.md](06-API手册.md)，RPC 方法参数见各领域的 RPC 手册。