@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.
- package/CHANGELOG.md +14 -0
- 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
- 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
- package/_packed_docs/CHANGELOG.md +14 -0
- package/_packed_docs/INDEX.md +17 -11
- package/_packed_docs/KITE_DOCS_GUIDE.md +11 -10
- package/_packed_docs/sdk/01-/345/277/253/351/200/237/345/274/200/345/247/213.md +134 -158
- package/_packed_docs/sdk/02-WebSocket/345/215/217/350/256/256.md +11 -7
- package/_packed_docs/sdk/03-/346/240/270/345/277/203/346/246/202/345/277/265.md +98 -119
- package/_packed_docs/sdk/04-/350/277/236/346/216/245/344/270/216/350/256/244/350/257/201.md +147 -374
- package/_packed_docs/sdk/05-E2EE/345/212/240/345/257/206/351/200/232/344/277/241.md +153 -153
- package/_packed_docs/sdk/06-API/346/211/213/345/206/214.md +163 -1364
- package/_packed_docs/sdk/07-/351/224/231/350/257/257/345/244/204/347/220/206.md +71 -91
- package/_packed_docs/sdk/08-/346/234/200/344/275/263/345/256/236/350/267/265.md +76 -63
- package/_packed_docs/sdk/09-custody-api-manual.md +7 -6
- package/_packed_docs/sdk/09-meta-rpc-manual.md +13 -14
- package/_packed_docs/sdk/09-storage-rpc-manual.md +89 -0
- package/_packed_docs/sdk/AUN_DOCS_GUIDE.md +37 -49
- package/_packed_docs/sdk/INDEX.md +72 -98
- package/_packed_docs/sdk/README.md +85 -266
- package/dist/aid-store.d.ts +64 -0
- package/dist/aid-store.d.ts.map +1 -0
- package/dist/aid-store.js +855 -0
- package/dist/aid-store.js.map +1 -0
- package/dist/aid.d.ts +50 -0
- package/dist/aid.d.ts.map +1 -0
- package/dist/aid.js +106 -0
- package/dist/aid.js.map +1 -0
- package/dist/auth.d.ts +17 -1
- package/dist/auth.d.ts.map +1 -1
- package/dist/auth.js +27 -4
- package/dist/auth.js.map +1 -1
- package/dist/bundle.js +1981 -2048
- package/dist/cert-utils.d.ts +26 -0
- package/dist/cert-utils.d.ts.map +1 -0
- package/dist/cert-utils.js +221 -0
- package/dist/cert-utils.js.map +1 -0
- package/dist/client.d.ts +93 -58
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +775 -170
- package/dist/client.js.map +1 -1
- package/dist/error-codes.d.ts +25 -0
- package/dist/error-codes.d.ts.map +1 -0
- package/dist/error-codes.js +31 -0
- package/dist/error-codes.js.map +1 -0
- package/dist/errors.d.ts +4 -0
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +4 -0
- package/dist/errors.js.map +1 -1
- package/dist/index.d.ts +6 -6
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +5 -5
- package/dist/index.js.map +1 -1
- package/dist/keystore/index.d.ts +1 -1
- package/dist/keystore/index.d.ts.map +1 -1
- package/dist/result.d.ts +19 -0
- package/dist/result.d.ts.map +1 -0
- package/dist/result.js +10 -0
- package/dist/result.js.map +1 -0
- package/dist/transport.d.ts +3 -0
- package/dist/transport.d.ts.map +1 -1
- package/dist/transport.js +17 -2
- package/dist/transport.js.map +1 -1
- package/dist/types.d.ts +13 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +22 -0
- package/dist/types.js.map +1 -1
- package/dist/v2/e2ee/encrypt-p2p.js +1 -1
- package/dist/v2/e2ee/encrypt-p2p.js.map +1 -1
- package/dist/version.d.ts +2 -0
- package/dist/version.d.ts.map +1 -0
- package/dist/version.js +5 -0
- package/dist/version.js.map +1 -0
- package/package.json +1 -1
|
@@ -1,307 +1,126 @@
|
|
|
1
|
-
# AUN Protocol
|
|
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
|
-
|
|
12
|
-
|
|
13
|
-
**
|
|
14
|
-
|
|
15
|
-
-
|
|
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
|
-
|
|
51
|
-
|
|
52
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
69
|
+
## 多语言构造约束
|
|
227
70
|
|
|
228
|
-
|
|
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
|
-
##
|
|
82
|
+
## 协议分层
|
|
247
83
|
|
|
248
|
-
```
|
|
249
|
-
|
|
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
|
-
|
|
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
|
-
|
|
291
|
-
|
|
93
|
+
| 模式 | 当前 SDK 状态 | 说明 |
|
|
94
|
+
|------|---------------|------|
|
|
95
|
+
| Gateway | 已实现 | 浏览器、移动端、服务端标准接入 |
|
|
96
|
+
| Peer | 未实现或明确报未实现 | 协议命名空间已定义 |
|
|
97
|
+
| Relay | 未实现或明确报未实现 | 协议命名空间已定义 |
|
|
292
98
|
|
|
293
|
-
|
|
294
|
-
```
|
|
99
|
+
---
|
|
295
100
|
|
|
296
|
-
|
|
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
|
|
303
|
-
| [04-连接与认证](04-连接与认证.md) |
|
|
304
|
-
| [05-E2EE加密通信](05-E2EE加密通信.md) |
|
|
305
|
-
| [06-API手册](06-API手册.md) | AUNClient /
|
|
306
|
-
| [07-错误处理](07-错误处理.md) |
|
|
307
|
-
| [08-最佳实践](08-最佳实践.md) |
|
|
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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"}
|