@agentunion/fastaun-browser 0.3.5 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/_packed_docs/AUN_SDK_/351/207/215/346/236/204/345/256/236/346/226/275/350/256/241/345/210/222.md +596 -0
  3. package/_packed_docs/AUN_SDK_/351/207/215/346/236/204/350/256/276/350/256/241/346/226/271/346/241/210_v3.md +1633 -0
  4. package/_packed_docs/CHANGELOG.md +14 -0
  5. package/_packed_docs/INDEX.md +17 -11
  6. package/_packed_docs/KITE_DOCS_GUIDE.md +11 -10
  7. package/_packed_docs/sdk/01-/345/277/253/351/200/237/345/274/200/345/247/213.md +134 -158
  8. package/_packed_docs/sdk/02-WebSocket/345/215/217/350/256/256.md +11 -7
  9. package/_packed_docs/sdk/03-/346/240/270/345/277/203/346/246/202/345/277/265.md +98 -119
  10. package/_packed_docs/sdk/04-/350/277/236/346/216/245/344/270/216/350/256/244/350/257/201.md +147 -374
  11. package/_packed_docs/sdk/05-E2EE/345/212/240/345/257/206/351/200/232/344/277/241.md +153 -153
  12. package/_packed_docs/sdk/06-API/346/211/213/345/206/214.md +163 -1364
  13. package/_packed_docs/sdk/07-/351/224/231/350/257/257/345/244/204/347/220/206.md +71 -91
  14. package/_packed_docs/sdk/08-/346/234/200/344/275/263/345/256/236/350/267/265.md +76 -63
  15. package/_packed_docs/sdk/09-custody-api-manual.md +7 -6
  16. package/_packed_docs/sdk/09-meta-rpc-manual.md +13 -14
  17. package/_packed_docs/sdk/09-storage-rpc-manual.md +89 -0
  18. package/_packed_docs/sdk/AUN_DOCS_GUIDE.md +37 -49
  19. package/_packed_docs/sdk/INDEX.md +72 -98
  20. package/_packed_docs/sdk/README.md +85 -266
  21. package/dist/aid-store.d.ts +64 -0
  22. package/dist/aid-store.d.ts.map +1 -0
  23. package/dist/aid-store.js +855 -0
  24. package/dist/aid-store.js.map +1 -0
  25. package/dist/aid.d.ts +50 -0
  26. package/dist/aid.d.ts.map +1 -0
  27. package/dist/aid.js +106 -0
  28. package/dist/aid.js.map +1 -0
  29. package/dist/auth.d.ts +17 -1
  30. package/dist/auth.d.ts.map +1 -1
  31. package/dist/auth.js +27 -4
  32. package/dist/auth.js.map +1 -1
  33. package/dist/bundle.js +1981 -2048
  34. package/dist/cert-utils.d.ts +26 -0
  35. package/dist/cert-utils.d.ts.map +1 -0
  36. package/dist/cert-utils.js +221 -0
  37. package/dist/cert-utils.js.map +1 -0
  38. package/dist/client.d.ts +93 -58
  39. package/dist/client.d.ts.map +1 -1
  40. package/dist/client.js +775 -170
  41. package/dist/client.js.map +1 -1
  42. package/dist/error-codes.d.ts +25 -0
  43. package/dist/error-codes.d.ts.map +1 -0
  44. package/dist/error-codes.js +31 -0
  45. package/dist/error-codes.js.map +1 -0
  46. package/dist/errors.d.ts +4 -0
  47. package/dist/errors.d.ts.map +1 -1
  48. package/dist/errors.js +4 -0
  49. package/dist/errors.js.map +1 -1
  50. package/dist/index.d.ts +6 -6
  51. package/dist/index.d.ts.map +1 -1
  52. package/dist/index.js +5 -5
  53. package/dist/index.js.map +1 -1
  54. package/dist/keystore/index.d.ts +1 -1
  55. package/dist/keystore/index.d.ts.map +1 -1
  56. package/dist/result.d.ts +19 -0
  57. package/dist/result.d.ts.map +1 -0
  58. package/dist/result.js +10 -0
  59. package/dist/result.js.map +1 -0
  60. package/dist/transport.d.ts +3 -0
  61. package/dist/transport.d.ts.map +1 -1
  62. package/dist/transport.js +17 -2
  63. package/dist/transport.js.map +1 -1
  64. package/dist/types.d.ts +13 -2
  65. package/dist/types.d.ts.map +1 -1
  66. package/dist/types.js +22 -0
  67. package/dist/types.js.map +1 -1
  68. package/dist/v2/e2ee/encrypt-p2p.js +1 -1
  69. package/dist/v2/e2ee/encrypt-p2p.js.map +1 -1
  70. package/dist/version.d.ts +2 -0
  71. package/dist/version.d.ts.map +1 -0
  72. package/dist/version.js +5 -0
  73. package/dist/version.js.map +1 -0
  74. package/package.json +1 -1
@@ -1,307 +1,126 @@
1
- # AUN Protocol Python SDK
1
+ # AUN Protocol - SDK 文档
2
2
 
3
- ## 概述
4
-
5
- AUN(Agent Union Network)定义 Agent 之间安全通信的标准接口——基于 WebSocket + JSON-RPC 2.0,涵盖身份、认证、消息和 Agent 间自主交互,不绑定单一通信拓扑。
3
+ AUN(Agent Union Network)定义 Agent 之间安全通信的标准接口,基于 WebSocket + JSON-RPC 2.0,涵盖身份、认证、消息、群组、存储、流式传输和端到端加密。
6
4
 
7
5
  ---
8
6
 
9
7
  ## 核心要点
10
8
 
11
- **问题**:AI Agent 被困在各自的平台里,无法跨域通信与协作。
12
-
13
- **AUN 的答案**:
14
-
15
- - **AID 身份**:`{name}.{issuer}` 格式的全局唯一标识(如 `alice.agentid.pub`),基于 X.509 证书链
16
- - **三种连接模式**:协议层定义 Gateway(标准接入)、Peer(点对点直连)、Relay(中继转发)三种模式;当前各语言 SDK 的连接层稳定支持 Gateway,Peer/Relay 仍处于协议定义状态
17
- - **Agent 工具使用展示**:原生 `tool_call` / `tool_result` payload 类型,用于在 IM/查看端可视化展示 Agent 的工具使用过程(**不是跨 Agent 能力调用契约**)
18
-
19
- ```
20
- ┌─ Gateway ──→ 标准接入(浏览器/移动端/服务端)
21
- Agent A ← WSS → ─┤─ Peer ─────→ 点对点直连(同内网/低延迟)
22
- └─ Relay ────→ 中继转发(NAT 穿透/轻量部署)
23
- ```
24
-
25
- **本 SDK** 是 AUN 协议的 Python 客户端实现。`pip install fastaun` 即可使用。
9
+ - **AID 身份**:`{name}.{issuer}` 格式的全局唯一标识,例如 `alice.agentid.pub`,基于 X.509 证书链。
10
+ - **三主体 SDK 模型**:`AIDStore` 管理 keystore,`AID` 是不可变身份值对象,`AUNClient` 管理连接与会话。
11
+ - **Gateway 连接**:当前各语言 SDK 稳定支持 Gateway 接入;Peer / Relay 仍处于协议定义或未实现状态。
12
+ - **默认 E2EE**:P2P 和 Group V2 消息默认加密;普通明文消息需要显式关闭加密。
13
+ - **统一 RPC**:业务方法通过 `client.call(method, params)` 调用,事件通过 `client.on(event, handler)` 订阅。
26
14
 
27
15
  ---
28
16
 
29
- ## 深入了解
30
-
31
- ### AID 身份体系
32
-
33
- AID(Agent Identifier)是 AUN 的核心身份标识,格式为 `{name}.{issuer}`:
17
+ ## 快速开始
34
18
 
19
+ ```bash
20
+ pip install fastaun
35
21
  ```
36
- alice.agentid.pub ← agentid.pub 签发的 Agent
37
- weather-bot.aun.pub ← aun.pub 签发的天气 Agent
38
- data-agent.corp.io ← 企业自有域名签发的内部 Agent
39
- ```
40
-
41
- 任何拥有域名的组织都可以成为 Issuer,签发自己的 AID。AUN 采用标准 X.509 v3 证书和 ECDSA 算法,通过**四级证书链**建立联邦信任机制:
42
-
43
- ```
44
- Root CA → Registry CA → Issuer CA → Agent 证书
45
- ```
46
-
47
- ### 协议分层
48
22
 
49
- ```
50
- Layer 4: 服务层 — auth服务、ca服务、message服务、storage服务、group服务、mail服务、
51
- stream服务、meta服务、search服务、relay服务、泛域名解析服务
52
- (peer.*、task.* 仅有协议定义,无对应服务)
53
- Layer 3: 协议层 — auth.* / ca.* / message.* / storage.* / group.* / mail.* / stream.* /
54
- meta.* / search.* / task.* / peer.* / relay.*
55
- Layer 2: 通信层 — WebSocket + JSON-RPC 2.0 / HTTP/HTTPS
56
- Layer 1: 安全层 — TLS 1.3(传输加密)+ AUN E2EE(端到端加密)
57
- ```
23
+ ```python
24
+ import asyncio
25
+ import random
26
+ from aun_core import AIDStore, AUNClient
58
27
 
59
- ### 三种连接模式
28
+ DOMAIN = "agentid.pub"
29
+ ALICE = f"alice-{random.randint(1000,9999)}.{DOMAIN}"
30
+ BOB = f"bob-{random.randint(1000,9999)}.{DOMAIN}"
60
31
 
61
- | 模式 | 认证方式 | 适用场景 |
62
- |------|---------|---------|
63
- | **Gateway** | `auth.*` JWT 认证 | 浏览器、移动端、标准接入 |
64
- | **Peer** | `peer.*` 证书互验 | 同内网、已知地址、低延迟 |
65
- | **Relay** | `relay.*` 穿透中继 | 双方在 NAT 后、轻量中继 |
66
32
 
67
- 三种模式共享相同的 AID 身份、X.509 证书信任体系和业务层 API(`message.*`、`meta.*` 等)。
33
+ async def create_client(aid: str) -> AUNClient:
34
+ store = AIDStore(aun_path="~/.aun/myapp", encryption_seed="")
35
+ loaded = store.load(aid)
36
+ if not loaded["ok"]:
37
+ registered = await store.register(aid)
38
+ if not registered["ok"]:
39
+ raise RuntimeError(registered["error"]["message"])
40
+ loaded = store.load(aid)
68
41
 
69
- **当前 SDK 实现状态**:
42
+ client = AUNClient(loaded["data"]["aid"], debug=True)
43
+ await client.connect({"slot_id": "main", "auto_reconnect": True})
44
+ return client
70
45
 
71
- | SDK | Gateway | Peer | Relay |
72
- |-----|---------|------|-------|
73
- | Python | 已实现 | `connect(topology={"mode":"peer"})` 明确报未实现 | `connect(topology={"mode":"relay"})` 明确报未实现 |
74
- | Browser JS | 已实现 | 明确报未实现 | 明确报未实现 |
75
- | TypeScript | 已实现 | 明确报未实现 | 明确报未实现 |
76
- | Go | 已实现(当前按 `gateway` URL 建立会话) | 未实现独立 peer 传输 | 未实现独立 relay 传输 |
77
46
 
78
- > `peer.*` / `relay.*` 出现在协议表中,表示协议命名空间已定义,不代表 SDK 的 `connect()` 已支持对应拓扑。
47
+ async def main():
48
+ alice = await create_client(ALICE)
49
+ bob = await create_client(BOB)
79
50
 
80
- ### 消息类型
51
+ received = asyncio.Event()
52
+ bob.on("message.received", lambda e: (print(f"Bob 收到: {e['payload']}"), received.set()))
81
53
 
82
- | type | 说明 | 场景 |
83
- |------|------|------|
84
- | `text` | 纯文本消息 | Agent 间自然语言交流 |
85
- | `json` | 结构化数据消息 | 传递参数、配置、状态 |
86
- | `tool-call` | **Agent 工具调用过程标注**(请求段) | 由发送方标注自身正在调用的本地工具,供查看端渲染 |
87
- | `tool-result` | **Agent 工具调用过程标注**(结果段) | 由同一发送方标注本地工具的执行结果,供查看端渲染 |
88
- | `event` | 事件通知 | 状态变更、异步回调 |
89
- | `binary-ref` | 文件引用 | 文件分享(图片、视频、文档等,实际数据走 storage,通过 `mime_type` 区分文件类型) |
54
+ await alice.call("message.send", {
55
+ "to": BOB,
56
+ "payload": {"type": "text", "text": "Hello from Alice!"},
57
+ })
90
58
 
91
- `tool-call` / `tool-result` 由**同一发送方**先后发出,描述自己的工具使用过程;接收方收到后**不需要执行、不需要响应**,仅用于结构化展示(如 IM 的工具气泡、折叠卡片)。它不是跨 Agent 调用契约。
59
+ await asyncio.wait_for(received.wait(), timeout=5)
60
+ await alice.close()
61
+ await bob.close()
92
62
 
93
- ---
94
63
 
95
- ## 协议详解
96
-
97
- ### 架构总览
98
-
99
- ```mermaid
100
- graph TD
101
- subgraph Client["客户端 / Agent"]
102
- Browser["浏览器"]
103
- Mobile["移动端"]
104
- Desktop["桌面/服务器 Agent"]
105
- end
106
-
107
- subgraph Access["接入模式"]
108
- GW["Gateway"]
109
- Peer["Peer 直连"]
110
- Relay["Relay 中继"]
111
- end
112
-
113
- subgraph Infra["基础设施"]
114
- Auth["Auth 服务 / Issuer CA"]
115
- Roots["Root CA 列表"]
116
- end
117
-
118
- subgraph Services["AUN 服务"]
119
- direction LR
120
- Message["Message"] --- Group["Group"] --- Storage["Storage"] --- Stream["Stream"]
121
- end
122
-
123
- Browser --> GW
124
- Mobile --> GW
125
- Desktop --> GW
126
- Desktop -.-> Peer
127
- Desktop --> Relay
128
-
129
- GW --> Services
130
-
131
- Browser -.证书/JWT.-> Auth
132
- Desktop -.证书/JWT.-> Auth
133
- Auth --> Roots
134
- ```
135
-
136
- - **Auth 服务 / Issuer CA** 是必须的基础设施(AID 注册、证书签发、JWT 签发)
137
- - **Gateway** 是最常见的接入方式,但不是协议唯一入口
138
- - **Peer / Relay** 模式下,身份验证基于证书链,本地即可完成
139
-
140
- ### 协议层(RPC 方法)
141
-
142
- | 命名空间 | 职责 | 关键方法 |
143
- |----------|------|----------|
144
- | `auth.*` | 身份认证、JWT 签发与刷新 | register_aid / authenticate / refresh_token |
145
- | `peer.*` | 对等认证、证书互验 | hello / verify / establish |
146
- | `relay.*` | 中继注册与转发 | register / forward / unregister |
147
- | `message.*` | 消息收发、离线队列、P2P 思考内容 | send / pull / ack / recall / thought.put / thought.get |
148
- | `meta.*` | 元信息查询 | ping / status / trust_roots |
149
- | `group.*` | 群组生命周期、成员管理、群设置、群消息 | create / invite / set_settings / send / thought.put / thought.get / dissolve |
150
- | `storage.*` | 文件上传下载、权限管理 | upload / download / share |
151
- | `stream.*` | 实时流式传输(推流 WS / 拉流 SSE) | create / close / get_info / list_active |
152
- | `mail.*` | 异步邮件式消息 | send / list / read |
153
- | `search.*` | Agent 与能力搜索发现 | query / browse |
154
- | `task.*` | 跨 Agent 任务协作 | create / assign / update / complete |
155
-
156
- 协议层可由用户自定义扩展命名空间。
157
-
158
- > `peer.*` / `relay.*` 目前主要是协议规范与服务侧能力定义;当前 SDK 的连接建立与会话生命周期仍以 Gateway 为主。
159
-
160
- ### 消息层
161
-
162
- AUN 使用 JSON-RPC 2.0 原生三类消息:
163
-
164
- | 类型 | 有 `id` | 说明 |
165
- |------|:-------:|------|
166
- | **Request** | 是 | 调用方法,期望对端返回 Response |
167
- | **Response** | 是 | 对 Request 的回复(`result` 或 `error`) |
168
- | **Notification** | 否 | 单向通知,无需回复 |
169
-
170
- 命名约定区分用途:
171
-
172
- | 前缀 | 示例 | 用途 |
173
- |------|------|------|
174
- | `namespace.action` | `message.send` | Request 方法名 |
175
- | `event/xxx` | `event/message.received` | 业务层事件推送 |
176
- | `notification/xxx` | `notification/initialized` | 协议级通知 |
177
-
178
- ### 安全模型
179
-
180
- - **四级证书链**:Root CA → Registry CA → Issuer CA → Agent 证书,双向验证
181
- - **Challenge-Response**:Nonce 防重放 + 时间戳验证
182
- - **Token 体系**:access_token(短期)+ refresh_token(长期,一次性)
183
- - **E2EE**:协议层可扩展多种密码学套件,当前 Python SDK 仅实现 P-256 + HKDF-SHA256 + AES-256-GCM。可叠加于任意连接模式
184
-
185
- > **⚠️ V2 群 E2EE 安全等级警示**
186
- >
187
- > V2 群消息加密强度取决于群的 `join_mode`:
188
- >
189
- > - **end_to_end(真正端到端)**:`approval` / `closed` 群。新成员必须经 owner/admin 签名确认,可防服务端注入幽灵成员窃听
190
- > - **transport(仅传输加密)**:`open` / `invite_code` / `invite_only` 群。任何人可自由入群,wrap 接收方不绑定到授权成员,**E2EE 等同传输层加密,不提供"仅授权成员可读"保证**
191
- >
192
- > `group.v2.bootstrap` 响应中的 `e2ee_security_level` 字段标识当前群的安全等级。**UI 应在 transport 等级群中显著提示用户"非端到端加密"**,避免用户对安全保证产生误判。
193
-
194
- ### Gateway 模式连接流程
195
-
196
- ```mermaid
197
- sequenceDiagram
198
- participant C as Agent
199
- participant G as Gateway
200
-
201
- C->>G: WebSocket 连接
202
- G->>C: challenge(nonce, protocol, auth_methods)
203
- C->>G: auth.connect(nonce, token, protocol)
204
- G->>C: hello-ok(identity, capabilities)
205
- Note over C,G: 握手完成,进入双向 RPC / 事件通信
206
- C->>G: message.send / group.create / ...
207
- G->>C: event/message.received / ...
64
+ asyncio.run(main())
208
65
  ```
209
66
 
210
- ### Agent 生命周期
211
-
212
- ```mermaid
213
- stateDiagram-v2
214
- [*] --> 未注册
215
- 未注册 --> 已注册: register_aid(生成密钥对 + 签发证书)
216
- 已注册 --> 已认证: authenticate(Challenge-Response)
217
- 已认证 --> 已连接: connect(WebSocket)
218
- 已连接 --> 已连接: call / on(业务操作)
219
- 已连接 --> 断线重连: 网络断开
220
- 断线重连 --> 已连接: Token 有效
221
- 断线重连 --> 已注册: Token 过期
222
- 已连接 --> 已注册: close / logout
223
- 已注册 --> [*]: deregister
224
- ```
67
+ ---
225
68
 
226
- ### AUN 协议完整文档
69
+ ## 多语言构造约束
227
70
 
228
- 协议文档随 SDK 包一起分发,安装后位于 `aun_core/docs/protocol/`:
71
+ | 语言 | options-only | AID + options |
72
+ |------|--------------|---------------|
73
+ | Python | `AUNClient(debug=True)` | `AUNClient(aid, debug=True)` |
74
+ | TypeScript | `new AUNClient({ debug: true })` | `new AUNClient(aid, { debug: true })` |
75
+ | JavaScript | `new AUNClient({ debug: true })` | `new AUNClient(aid, { debug: true })` |
76
+ | Go | `aun.NewAUNClient(aun.AUNClientOptions{Debug: true})` | `aun.NewAUNClient(aid, aun.AUNClientOptions{Debug: true})` |
229
77
 
230
- | 文档 | 内容 |
231
- |------|------|
232
- | [00-总览与分层](../src/aun_core/docs/protocol/00-总览与分层.md) | 协议总览、分层架构 |
233
- | [01-身份与凭证协议](../src/aun_core/docs/protocol/01-身份与凭证协议-auth.md) | auth.* 方法定义 |
234
- | [02-证书与信任体系](../src/aun_core/docs/protocol/02-证书与信任体系.md) | 四级证书链、信任模型 |
235
- | [03-Gateway连接模式](../src/aun_core/docs/protocol/03-Gateway-连接模式.md) | Gateway 连接流程 |
236
- | [04-Peer子协议](../src/aun_core/docs/protocol/04-Peer-子协议.md) | 对等认证 |
237
- | [05-Relay子协议](../src/aun_core/docs/protocol/05-Relay-子协议.md) | 中继转发 |
238
- | [06-服务协议](../src/aun_core/docs/protocol/06-服务协议.md) | message/meta/search/task/group/stream |
239
- | [08-AUN-E2EE](../src/aun_core/docs/protocol/08-AUN-E2EE.md) | 端到端加密 |
240
- | [10-Group子协议](../src/aun_core/docs/protocol/10-Group-子协议.md) | 群组管理 |
241
- | [11-Storage子协议](../src/aun_core/docs/protocol/11-Storage-子协议.md) | 对象存储 |
242
- | [12-Stream子协议](../src/aun_core/docs/protocol/12-Stream-子协议.md) | 实时流式传输 |
78
+ `aid` 必须是 AID 对象,不是字符串。不要把 aid 放进 options,也不要使用旧的 `(config, debug)` 构造形态。
243
79
 
244
80
  ---
245
81
 
246
- ## SDK 快速开始
82
+ ## 协议分层
247
83
 
248
- ```bash
249
- pip install fastaun
84
+ ```text
85
+ Layer 4: 服务层 auth / ca / message / group / storage / stream / meta / search
86
+ Layer 3: 协议层 JSON-RPC 方法命名空间
87
+ Layer 2: 通信层 WebSocket + JSON-RPC 2.0 / HTTP
88
+ Layer 1: 安全层 TLS + AUN E2EE
250
89
  ```
251
90
 
252
- ```python
253
- import asyncio, random
254
- from aun_core import AUNClient
255
-
256
- DOMAIN = "agentid.pub"
257
- ALICE = f"alice-{random.randint(1000,9999)}.{DOMAIN}"
258
- BOB = f"bob-{random.randint(1000,9999)}.{DOMAIN}"
259
-
260
- async def create_client(aid: str) -> tuple[AUNClient, dict]:
261
- client = AUNClient({"aun_path": f"~/.aun/{aid}"})
262
- identity = client._auth.load_identity_or_none(aid)
263
- if not identity:
264
- await client.auth.register_aid({"aid": aid})
265
- auth = await client.auth.authenticate({"aid": aid})
266
- return client, auth
267
-
268
- async def main():
269
- alice, alice_auth = await create_client(ALICE)
270
- bob, bob_auth = await create_client(BOB)
271
-
272
- received = asyncio.Event()
273
- bob.on("message.received", lambda e: (print(f"Bob 收到: {e['payload']}"), received.set()))
274
-
275
- await alice.connect(alice_auth, {})
276
- await bob.connect(bob_auth, {})
277
-
278
- await alice.call("message.send", {
279
- "to": BOB,
280
- "payload": {"type": "text", "text": "Hello from Alice!"},
281
- })
282
-
283
- try:
284
- await asyncio.wait_for(received.wait(), timeout=5.0)
285
- except asyncio.TimeoutError:
286
- pull = await bob.call("message.pull", {"after_seq": 0, "limit": 10})
287
- for m in pull.get("messages", []):
288
- print(f"Bob 拉取: {m.get('payload')}")
91
+ ### 连接模式
289
92
 
290
- await alice.close()
291
- await bob.close()
93
+ | 模式 | 当前 SDK 状态 | 说明 |
94
+ |------|---------------|------|
95
+ | Gateway | 已实现 | 浏览器、移动端、服务端标准接入 |
96
+ | Peer | 未实现或明确报未实现 | 协议命名空间已定义 |
97
+ | Relay | 未实现或明确报未实现 | 协议命名空间已定义 |
292
98
 
293
- asyncio.run(main())
294
- ```
99
+ ---
295
100
 
296
- ### SDK 文档
101
+ ## 文档入口
297
102
 
298
103
  | 章节 | 说明 |
299
104
  |------|------|
300
- | [01-快速开始](01-快速开始.md) | 安装、配置、双客户端消息收发完整示例 |
105
+ | [01-快速开始](01-快速开始.md) | 安装、三主体模型、最小示例、多语言构造 |
301
106
  | [02-WebSocket协议](02-WebSocket协议.md) | 握手流程、消息格式、裸 WebSocket 示例 |
302
- | [03-核心概念](03-核心概念.md) | AID、连接状态机、认证流程、E2EE |
303
- | [04-连接与认证](04-连接与认证.md) | 认证封装、call()、on()、网关发现 |
304
- | [05-E2EE加密通信](05-E2EE加密通信.md) | 端到端加密收发、ProtectedHeaders、密钥管理、自定义存储 |
305
- | [06-API手册](06-API手册.md) | AUNClient / AuthNamespace / E2EEManager 完整 API |
306
- | [07-错误处理](07-错误处理.md) | 错误类层级、错误码速查、重试策略 |
307
- | [08-最佳实践](08-最佳实践.md) | 幂等初始化、多 AID 隔离、资源清理 |
107
+ | [03-核心概念](03-核心概念.md) | AID、AIDStore、AUNClient、九态状态机、E2EE |
108
+ | [04-连接与认证](04-连接与认证.md) | 注册、加载、认证、连接、事件、agent.md |
109
+ | [05-E2EE加密通信](05-E2EE加密通信.md) | E2EE 收发、ProtectedHeaders、密钥管理 |
110
+ | [06-API手册](06-API手册.md) | AIDStore / AID / AUNClient / 事件 / RPC 索引 |
111
+ | [07-错误处理](07-错误处理.md) | Result、异常层级、错误码、重试策略 |
112
+ | [08-最佳实践](08-最佳实践.md) | 幂等连接、多 AID、资源清理、测试数据保护 |
113
+
114
+ RPC 专项手册:
115
+
116
+ | 手册 | 范围 |
117
+ |------|------|
118
+ | [09-message-rpc-manual.md](09-message-rpc-manual.md) | P2P 消息、ack、thought |
119
+ | [09-group-rpc-manual.md](09-group-rpc-manual.md) | 群组生命周期、成员、群消息、群 thought |
120
+ | [09-storage-rpc-manual.md](09-storage-rpc-manual.md) | 文件和对象存储 |
121
+ | [09-meta-rpc-manual.md](09-meta-rpc-manual.md) | ping / status / trust_roots |
122
+ | [09-stream-rpc-manual.md](09-stream-rpc-manual.md) | 流式数据传输 |
123
+ | [09-payload-reference.md](09-payload-reference.md) | message / group payload 结构 |
124
+ | [09-custody-api-manual.md](09-custody-api-manual.md) | 可选 AID 托管 HTTP API |
125
+
126
+ 协议文档随 SDK 包分发,位于 `aun_core/docs/protocol/`。
@@ -0,0 +1,64 @@
1
+ import { AID } from './aid.js';
2
+ import { type Result } from './result.js';
3
+ export interface AIDInfo {
4
+ aid: string;
5
+ certFingerprint: string;
6
+ certNotAfter: Date;
7
+ certIssuer: string;
8
+ }
9
+ export interface ResolveOpts {
10
+ forceRefresh?: boolean;
11
+ timeout?: number;
12
+ skipAgentMd?: boolean;
13
+ }
14
+ export declare class AIDStore {
15
+ readonly aunPath: string;
16
+ readonly deviceId: string;
17
+ readonly slotId: string;
18
+ private _encryptionSeed;
19
+ private _keystore;
20
+ private _auth;
21
+ private _crypto;
22
+ private _discovery;
23
+ private _verifySsl;
24
+ private _discoveryPort;
25
+ private _gatewayCache;
26
+ private _agentMdCache;
27
+ constructor(opts: {
28
+ aunPath: string;
29
+ encryptionSeed: string;
30
+ deviceId?: string;
31
+ slotId?: string;
32
+ rootCaPem?: string | null;
33
+ verifySsl?: boolean;
34
+ discoveryPort?: number | null;
35
+ });
36
+ close(): void;
37
+ load(aid: string): Promise<Result<{
38
+ aid: AID;
39
+ }>>;
40
+ list(): Promise<Result<{
41
+ identities: AIDInfo[];
42
+ }>>;
43
+ changeSeed(oldSeed: string, newSeed: string): Promise<Result<{
44
+ changed: boolean;
45
+ count: number;
46
+ }>>;
47
+ register(aid: string): Promise<Result<{
48
+ registered: true;
49
+ }>>;
50
+ exists(aid: string): Promise<Result<{
51
+ exists: boolean;
52
+ }>>;
53
+ resolve(aid: string, opts?: ResolveOpts): Promise<Result<Record<string, unknown>>>;
54
+ fetchAgentMd(aid: string): Promise<Result<Record<string, unknown>>>;
55
+ headAgentMd(aid: string): Promise<Result<Record<string, unknown>>>;
56
+ checkAgentMd(aid: string, ttlDays?: number): Promise<Result<Record<string, unknown>>>;
57
+ diagnose(aid: string): Promise<Result<Record<string, unknown>>>;
58
+ renewCert(aid: string): Promise<Result<Record<string, unknown>>>;
59
+ rekey(aid: string): Promise<Result<Record<string, unknown>>>;
60
+ private _resolveGateway;
61
+ private _loadCachedGatewayUrl;
62
+ private _persistGatewayUrl;
63
+ }
64
+ //# sourceMappingURL=aid-store.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"aid-store.d.ts","sourceRoot":"","sources":["../src/aid-store.ts"],"names":[],"mappings":"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"}