@agentunion/fastaun-browser 0.4.4 → 0.4.6

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 (73) hide show
  1. package/CHANGELOG.md +41 -0
  2. package/_packed_docs/CHANGELOG.md +41 -0
  3. package/_packed_docs/INDEX.md +2 -2
  4. package/_packed_docs/KITE_DOCS_GUIDE.md +1 -1
  5. package/_packed_docs/agent.md//350/277/234/347/250/213agent.md/347/274/223/345/255/230/344/270/216etag/351/200/217/344/274/240/346/226/271/346/241/210.md +73 -84
  6. package/_packed_docs/sdk/01-/345/277/253/351/200/237/345/274/200/345/247/213.md +16 -15
  7. package/_packed_docs/sdk/02-WebSocket/345/215/217/350/256/256.md +2 -2
  8. package/_packed_docs/sdk/03-/346/240/270/345/277/203/346/246/202/345/277/265.md +22 -5
  9. package/_packed_docs/sdk/04-/350/277/236/346/216/245/344/270/216/350/256/244/350/257/201.md +42 -26
  10. package/_packed_docs/sdk/05-E2EE/345/212/240/345/257/206/351/200/232/344/277/241.md +2 -2
  11. package/_packed_docs/sdk/06-API/346/211/213/345/206/214.md +61 -35
  12. package/_packed_docs/sdk/08-/346/234/200/344/275/263/345/256/236/350/267/265.md +3 -3
  13. package/_packed_docs/sdk/09-message-rpc-manual.md +6 -6
  14. package/_packed_docs/sdk/AUN_DOCS_GUIDE.md +6 -4
  15. package/_packed_docs/sdk/INDEX.md +2 -2
  16. package/_packed_docs/sdk/README.md +3 -3
  17. package/dist/agent-md.d.ts +111 -0
  18. package/dist/agent-md.d.ts.map +1 -0
  19. package/dist/agent-md.js +656 -0
  20. package/dist/agent-md.js.map +1 -0
  21. package/dist/aid-store.d.ts +8 -40
  22. package/dist/aid-store.d.ts.map +1 -1
  23. package/dist/aid-store.js +89 -172
  24. package/dist/aid-store.js.map +1 -1
  25. package/dist/auth.d.ts +8 -13
  26. package/dist/auth.d.ts.map +1 -1
  27. package/dist/auth.js +37 -130
  28. package/dist/auth.js.map +1 -1
  29. package/dist/bundle.js +6540 -6033
  30. package/dist/client.d.ts +8 -65
  31. package/dist/client.d.ts.map +1 -1
  32. package/dist/client.js +193 -762
  33. package/dist/client.js.map +1 -1
  34. package/dist/index.d.ts +4 -2
  35. package/dist/index.d.ts.map +1 -1
  36. package/dist/index.js +3 -1
  37. package/dist/index.js.map +1 -1
  38. package/dist/keystore/index.d.ts +49 -22
  39. package/dist/keystore/index.d.ts.map +1 -1
  40. package/dist/keystore/index.js +6 -1
  41. package/dist/keystore/index.js.map +1 -1
  42. package/dist/keystore/indexeddb-identity-store.d.ts +59 -0
  43. package/dist/keystore/indexeddb-identity-store.d.ts.map +1 -0
  44. package/dist/keystore/indexeddb-identity-store.js +489 -0
  45. package/dist/keystore/indexeddb-identity-store.js.map +1 -0
  46. package/dist/keystore/indexeddb-shared.d.ts +76 -0
  47. package/dist/keystore/indexeddb-shared.d.ts.map +1 -0
  48. package/dist/keystore/indexeddb-shared.js +382 -0
  49. package/dist/keystore/indexeddb-shared.js.map +1 -0
  50. package/dist/keystore/indexeddb-token-store.d.ts +119 -0
  51. package/dist/keystore/indexeddb-token-store.d.ts.map +1 -0
  52. package/dist/keystore/indexeddb-token-store.js +1086 -0
  53. package/dist/keystore/indexeddb-token-store.js.map +1 -0
  54. package/dist/keystore/indexeddb.d.ts +11 -1
  55. package/dist/keystore/indexeddb.d.ts.map +1 -1
  56. package/dist/keystore/indexeddb.js +167 -18
  57. package/dist/keystore/indexeddb.js.map +1 -1
  58. package/dist/register-flow.d.ts +53 -0
  59. package/dist/register-flow.d.ts.map +1 -0
  60. package/dist/register-flow.js +401 -0
  61. package/dist/register-flow.js.map +1 -0
  62. package/dist/v2/session/keystore.d.ts +5 -0
  63. package/dist/v2/session/keystore.d.ts.map +1 -1
  64. package/dist/v2/session/keystore.js +29 -0
  65. package/dist/v2/session/keystore.js.map +1 -1
  66. package/dist/version.d.ts +1 -1
  67. package/dist/version.js +1 -1
  68. package/package.json +1 -1
  69. package/_packed_docs/0.4.0_/345/267/256/345/274/202/346/240/270/345/256/236/345/206/263/347/255/226/350/256/260/345/275/225.md +0 -302
  70. package/_packed_docs/AUN_SDK_0.4.0_/350/256/276/350/256/241/345/257/271/346/257/224/345/210/206/346/236/220.md +0 -194
  71. package/_packed_docs/AUN_SDK_/351/207/215/346/236/204/345/256/236/346/226/275/350/256/241/345/210/222.md +0 -596
  72. 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 +0 -1698
  73. package/_packed_docs/python-sdk-v2-only-changelog.md +0 -189
@@ -12,7 +12,7 @@
12
12
  - [RPC 方法参考](#rpc-方法参考)
13
13
  - [Stream 使用指南](#stream-使用指南)
14
14
 
15
- > **多语言命名约定**:Python 使用 `snake_case`(如 `aun_path`、`fetch_agent_md`),TS/JS 使用 `camelCase`(如 `aunPath`、`fetchAgentMd`),Go 使用 `PascalCase` 公开方法(如 `Load`、`Register`)。本手册表格中各列对应各语言的实际命名。
15
+ > **多语言命名约定**:Python 使用 `snake_case`(如 `aun_path`、`download_agent_md`),TS/JS 使用 `camelCase`(如 `aunPath`、`downloadAgentMd`),Go 使用 `PascalCase` 公开方法(如 `Load`、`Register`)。本手册表格中各列对应各语言的实际命名。
16
16
 
17
17
  ---
18
18
 
@@ -63,17 +63,16 @@ store := aun.NewAIDStore(aunPath, encryptionSeed, aun.AIDStoreOptions{
63
63
  |--------|-------|----|------|
64
64
  | `load(aid)` | `load(aid)` | `Load(aid)` | 从本地加载 AID |
65
65
  | `register(aid)` | `register(aid)` | `Register(ctx, aid)` | 注册并落盘证书和私钥 |
66
- | `list()` | `list()` | `List()` | 列出本地 AID |
67
- | `exists(aid)` | `exists(aid)` | `Exists(ctx, aid)` | 远端存在性检查 |
68
- | `resolve(aid, opts=None)` | `resolve(aid, opts?)` | `Resolve(ctx, aid, opts...)` | 拉证书、缓存、拉 agent.md 并验签;`opts.timeout` / `context.WithTimeout` 控制超时 |
69
- | `fetch_agent_md(aid, timeout_ms=30000)` | `fetchAgentMd(aid, timeoutMs=30000)` | `FetchAgentMd(ctx, aid)` | 下载 agent.md,返回 `FetchAgentMdResult` / `AgentMDInfo` |
70
- | `head_agent_md(aid)` | `headAgentMd(aid)` | `HeadAgentMd(ctx, aid)` | HEAD agent.md |
71
- | `check_agent_md(aid, ttl_days=1)` | `checkAgentMd(aid, ttlDays?)` | `CheckAgentMd(ctx, aid, maxUnsyncedDays...)` | 缓存一致性检查 |
72
- | `diagnose(aid)` | `diagnose(aid)` | `Diagnose(ctx, aid)` | 本地 + 远端诊断 |
73
- | `renew_cert(aid)` / `rekey(aid)` | `renewCert(aid)` / `rekey(aid)` | `RenewCert(ctx, aid)` / `Rekey(ctx, aid)` | 证书运维 |
74
- | `change_seed(old, new)` | `changeSeed(old, new)` | `ChangeSeed(old, new)` | 本地密钥保护种子迁移 |
75
-
76
- Python / TS / JS 返回 Result 对象;Go 使用惯用 `(value, error)`。
66
+ | `list()` | `list()` | `List()` | 列出本地 AID |
67
+ | `exists(aid)` | `exists(aid)` | `Exists(ctx, aid)` | 远端存在性检查 |
68
+ | `resolve(aid, opts=None)` | `resolve(aid, opts?)` | `Resolve(ctx, aid, opts...)` | 拉证书并缓存;默认下载 agent.md,可用 `skip_agent_md` / `skipAgentMd` 跳过 |
69
+ | `download_agent_md(aid, timeout_s=None)` | `downloadAgentMd(aid, timeoutMs=30000)` | `DownloadAgentMD(ctx, aid)` | 下载 agent.md,返回 `DownloadAgentMdResult` / `AgentMDInfo` |
70
+ | `check_agent_md(aid, ttl_days=1)` | `checkAgentMd(aid, ttlDays=1)` | `CheckAgentMD(ctx, aid, maxUnsyncedDays...)` | 通过 HEAD 和本地记录检查一致性 |
71
+ | `diagnose(aid)` | `diagnose(aid)` | `Diagnose(ctx, aid)` | 本地 + 远端诊断 |
72
+ | `renew_cert(aid)` / `rekey(aid)` | `renewCert(aid)` / `rekey(aid)` | `RenewCert(ctx, aid)` / `Rekey(ctx, aid)` | 证书运维 |
73
+ | `change_seed(old, new)` | `changeSeed(old, new)` | `ChangeSeed(old, new)` | 本地密钥保护种子迁移 |
74
+
75
+ Python / TS / JS / Go 的 `AIDStore` 方法都返回 Result 包装;Go 形态为 `Result[T]`,字段为 `Ok` / `Data` / `Error`。
77
76
 
78
77
  ### Result 类型
79
78
 
@@ -85,16 +84,37 @@ Python / TS / JS 返回 Result 对象;Go 使用惯用 `(value, error)`。
85
84
  {"ok": False, "error": {"code": "ERROR_CODE", "message": "..."}}
86
85
  ```
87
86
 
88
- ### FetchAgentMdResult
89
-
90
- | 字段 | 类型 | 说明 |
91
- |------|------|------|
92
- | `aid` | str | AID 字符串 |
93
- | `content` | str | agent.md 原始内容 |
94
- | `verification` | `{status, reason?}` | 验签结果;`status` 为 `"ok"` / `"no_cert"` / `"invalid"` 等 |
95
- | `cert_pem` | str | 签名所用证书 PEM |
96
- | `etag` | str | HTTP ETag |
97
- | `last_modified` | str | HTTP Last-Modified |
87
+ ### DownloadAgentMdResult
88
+
89
+ | 字段 | 类型 | 说明 |
90
+ |------|------|------|
91
+ | `aid` | str | AID 字符串 |
92
+ | `content` | str | agent.md 原始内容 |
93
+ | `verification` | `{status, reason?}` | 验签结果;`status` 为 `"ok"` / `"no_cert"` / `"invalid"` 等 |
94
+ | `signature` | dict | 低层签名解析和验签结果 |
95
+ | `cert_pem` | str | 签名所用证书 PEM |
96
+ | `etag` | str | HTTP ETag |
97
+ | `last_modified` | str | HTTP Last-Modified |
98
+ | `status` | int | HTTP 状态码;异常 304 且本地有内容时可返回 304 |
99
+ | `in_sync` | bool\|null | 目标是当前 AID 时表示本地内容 ETag 是否等于远端 ETag;对端 AID 通常为 null |
100
+ | `saved_to` | str | SDK 管理的本地 agent.md 位置或浏览器 logical key |
101
+
102
+ ### CheckAgentMdResult
103
+
104
+ | 字段 | 类型 | 说明 |
105
+ |------|------|------|
106
+ | `aid` | str | AID 字符串 |
107
+ | `local_found` | bool | 本地是否有 agent.md 内容或本地 ETag |
108
+ | `remote_found` | bool | 远端 HEAD 是否发现 agent.md |
109
+ | `local_etag` | str | 本地内容 SHA-256 ETag |
110
+ | `remote_etag` | str | 远端 HTTP ETag |
111
+ | `in_sync` / `needs_update` | bool | 是否同步 / 是否需要下载 |
112
+ | `last_modified` | str | 远端 Last-Modified |
113
+ | `status` | int | HEAD 状态码 |
114
+ | `cached` | bool | 是否命中 TTL 窗口内的本地检查记录 |
115
+ | `verify_status` / `verify_error` | str | 最近一次下载验签状态 |
116
+
117
+ agent.md 本地记录不写入 SQLite。Python / TypeScript / Go 使用 `{aun_path}/AIDs/{aid}/agent.md` 与 `agentmd.json`;浏览器 JavaScript 使用 IndexedDB 等价 key,存储不可用时退化为内存缓存。
98
118
 
99
119
  > **v0.4.2 变更**:`discoveryPort` 配置项已移除,Gateway 地址完全由 SDK 根据 AID issuer 自动发现,无需手动指定端口。
100
120
 
@@ -114,7 +134,7 @@ AID 由 `AIDStore.load()` 返回,应用层不直接构造。
114
134
  | `cert_fingerprint` | `certFingerprint` | `CertFingerprint()` | 证书指纹 |
115
135
  | `aun_path` | `aunPath` | `AUNPath()` | 所属数据目录 |
116
136
  | `device_id` | `deviceId` | `DeviceID` | 设备 ID |
117
- | `slot_id` | `slotId` | `SlotID` | 密钥槽 ID |
137
+ | `slot_id` | `slotId` | `SlotID` | 实例槽位 ID;允许 `/`、`:`、空格作为共享隔离键分隔符 |
118
138
  | `verify_ssl` | `verifySsl` | `VerifySSL` | 是否校验 TLS 证书 |
119
139
  | `root_ca_path` | `rootCaPath` | `RootCaPath` | 自定义根证书路径 |
120
140
  | `debug` | `debug` | `Debug` | 是否开启调试日志 |
@@ -169,7 +189,7 @@ client := aun.NewAUNClient(aid)
169
189
 
170
190
  | Python | TS/JS | Go | 说明 |
171
191
  |--------|-------|----|------|
172
- | `load_identity(aid)` | `loadIdentity(aid)` | `LoadIdentityFromAID(aid)` | 在 `no_identity` / `closed` 状态加载身份 |
192
+ | `load_identity(aid)` | `loadIdentity(aid)` | `LoadIdentity(aid)` | 在 `no_identity` / `closed` 状态加载身份 |
173
193
  | `state` | `state` | `ConnectionState()` | 九态公开状态 |
174
194
  | `gateway_url` | `gatewayUrl` | `GetGatewayURL()` | 当前连接的 Gateway URL(只读,自动发现,连接前为空) |
175
195
  | `current_aid` | `currentAid` | `CurrentAID()` | 当前 AID 对象 |
@@ -206,7 +226,7 @@ await client.close()
206
226
  - `disconnect()` 断开当前传输连接,对象仍可重新连接。
207
227
  - `close()` 关闭连接和后台任务;之后只能重新加载身份再复用。
208
228
 
209
- TS/JS/Go 目前保留底层双参数连接形态以兼容现有调用链,但构造入口、AID 值对象、状态机和 capability getter 已与 Python 对齐。
229
+ 四个 SDK 的公开构造入口均已对齐为“无参或 AID 对象”。调试、TLS、根证书、device_id、slot_id 等配置由 `AIDStore` 传递到 AID,再由 `AUNClient` 继承;连接级选项只传给 `connect()`。
210
230
 
211
231
  ### RPC
212
232
 
@@ -227,11 +247,11 @@ await client.call("meta.trust_roots", {})
227
247
 
228
248
  ### protected_headers
229
249
 
230
- ```python
231
- client = AUNClient(aid, protected_headers={"sdk": "python"})
232
- client.set_protected_headers({"sdk": "python", "trace": "abc"})
233
- headers = client.get_protected_headers()
234
- ```
250
+ ```python
251
+ client = AUNClient(aid)
252
+ client.set_protected_headers({"sdk": "python", "trace": "abc"})
253
+ headers = client.get_protected_headers()
254
+ ```
235
255
 
236
256
  只合并到以下 RPC:
237
257
 
@@ -242,11 +262,17 @@ headers = client.get_protected_headers()
242
262
 
243
263
  ### agent.md
244
264
 
245
- | Python | TS/JS | Go | 说明 |
246
- |--------|-------|----|------|
247
- | `publish_agent_md(content=None)` | `publishAgentMd(content?)` | `PublishAgentMD(ctx)` | 发布当前 AID 的 agent.md |
248
- | 推荐 `AIDStore.fetch_agent_md(aid)` | 推荐 `store.fetchAgentMd(aid)` | 当前用 RPC/HTTP 组合实现 | 下载并验签 |
249
- | 推荐 `AIDStore.check_agent_md(aid)` | 推荐 `store.checkAgentMd(aid)` | 当前用 RPC/HTTP 组合实现 | 检查一致性 |
265
+ | Python | TS/JS | Go | 说明 |
266
+ |--------|-------|----|------|
267
+ | `upload_agent_md(content=None)` | `uploadAgentMd(content?)` | `UploadAgentMD(ctx, content...)` | 发布当前 AID 的 agent.md |
268
+ | `AIDStore.download_agent_md(aid)` | `store.downloadAgentMd(aid)` | `store.DownloadAgentMD(ctx, aid)` | 下载并验签 |
269
+ | `AIDStore.check_agent_md(aid)` | `store.checkAgentMd(aid)` | `store.CheckAgentMD(ctx, aid, maxUnsyncedDays...)` | 检查一致性 |
270
+
271
+ 说明:
272
+
273
+ - `AUNClient` 只保留上传入口;下载和检查入口在 `AIDStore`。
274
+ - SDK 发起 GET 时只发送 `Accept: text/markdown`,不主动发送 `If-None-Match` / `If-Modified-Since`。如果服务端异常返回 304,本地有内容则复用;无内容时再发一次无条件 GET。
275
+ - `Accept: text/markdown` 与 agent.md 的 YAML frontmatter + Markdown 格式兼容;agent.md 仍是 Markdown 媒体类型上的结构化约定。
250
276
 
251
277
  ---
252
278
 
@@ -16,7 +16,7 @@ async def ensure_ready(aid: str) -> AUNClient:
16
16
  loaded = store.load(aid)
17
17
 
18
18
  me = loaded["data"]["aid"]
19
- client = AUNClient(me, debug=True)
19
+ client = AUNClient(me)
20
20
  await client.connect({"slot_id": "main", "auto_reconnect": True})
21
21
  return client
22
22
  ```
@@ -78,8 +78,8 @@ recv_cursor = cursor.get("latest_seq", 0)
78
78
  实例级 `protected_headers` 适合放 SDK 版本、运行环境、调用方链路标识等需要签名保护的元数据:
79
79
 
80
80
  ```python
81
- client = AUNClient(me, protected_headers={"sdk": "python", "app": "demo"})
82
- client.set_protected_headers({"sdk": "python", "trace": "abc"})
81
+ client = AUNClient(me)
82
+ client.set_protected_headers({"sdk": "python", "trace": "abc"})
83
83
  ```
84
84
 
85
85
  只对 `message.send`、`group.send`、`message.thought.put`、`group.thought.put` 生效。
@@ -289,9 +289,9 @@ result = await client.call("message.thought.get", {
289
289
  | `after_seq` | integer | 否 | 0 | 拉取 seq > after_seq 的消息 |
290
290
  | `limit` | integer | 否 | 100 | 单次返回上限(最大 200) |
291
291
  | `device_id` | string | 否 | 当前连接实例 | 多实例消费上下文中的设备标识 |
292
- | `slot_id` | string | 否 | 当前连接实例 | 同一设备下的消费槽位;空字符串表示设备单实例模式 |
293
-
294
- > Python SDK 会自动为 `message.pull` 注入当前实例的 `device_id` / `slot_id`。原始客户端若显式传参,必须与认证连接上下文一致。
292
+ | `slot_id` | string | 否 | 当前连接实例 | 同一设备下的消费槽位;可用 `/`、`:`、空格表达共享隔离键,如 `evolclaw cli` |
293
+
294
+ > 四个 SDK 都会自动为 `message.pull` 注入当前实例的 `device_id` / `slot_id`。显式传入 `slot_id` 时按 `slotIsolationKey` 比较,`evolclaw cli` 与 `evolclaw daemon` 视为同一隔离键;不同隔离键会在发出 RPC 前被拒绝。
295
295
 
296
296
  ### 响应
297
297
 
@@ -366,9 +366,9 @@ for msg in result["messages"]:
366
366
  |------|------|------|--------|------|
367
367
  | `seq` | integer | 是 | — | 确认 seq ≤ 此值的所有消息 |
368
368
  | `device_id` | string | 否 | 当前连接实例 | 多实例消费上下文中的设备标识 |
369
- | `slot_id` | string | 否 | 当前连接实例 | 同一设备下的消费槽位;空字符串表示设备单实例模式 |
370
-
371
- > Python SDK 会自动为 `message.ack` 注入当前实例的 `device_id` / `slot_id`。原始客户端若显式传参,必须与认证连接上下文一致。
369
+ | `slot_id` | string | 否 | 当前连接实例 | 同一设备下的消费槽位;可用 `/`、`:`、空格表达共享隔离键,如 `evolclaw cli` |
370
+
371
+ > 四个 SDK 都会自动为 `message.ack` 注入当前实例的 `device_id` / `slot_id`。显式传入 `slot_id` 时按 `slotIsolationKey` 比较,`evolclaw cli` 与 `evolclaw daemon` 视为同一隔离键;不同隔离键会在发出 RPC 前被拒绝。
372
372
 
373
373
  ### 响应
374
374
 
@@ -25,8 +25,9 @@ AUN SDK 文档位于 `docs/sdk/`,索引文件 `docs/sdk/INDEX.md` 分三层:
25
25
  - 身份与认证:AIDStore / AID / 注册 / 加载 / 证书
26
26
  - 连接与状态:AUNClient / 九态状态机 / Gateway / 重连
27
27
  - E2EE:默认加密、ProtectedHeaders、P2P / Group V2
28
- - RPC 与事件:`client.call()`、`client.on()`、RPC 手册
29
- - 错误处理:Result、异常、错误码、重试
28
+ - RPC 与事件:`client.call()`、`client.on()`、RPC 手册
29
+ - agent.md:`AUNClient.upload_agent_md()`、`AIDStore.download_agent_md()`、`AIDStore.check_agent_md()`
30
+ - 错误处理:Result、异常、错误码、重试
30
31
 
31
32
  ### Step 3:读 Layer 3 摘要
32
33
 
@@ -53,8 +54,9 @@ AUN SDK 文档位于 `docs/sdk/`,索引文件 `docs/sdk/INDEX.md` 分三层:
53
54
  |------|----------|
54
55
  | 首次使用 SDK | [01-快速开始](01-快速开始.md) |
55
56
  | 理解新构造入口 | [01-快速开始](01-快速开始.md)、[06-API手册](06-API手册.md) |
56
- | 注册或加载 AID | [04-连接与认证](04-连接与认证.md) |
57
- | 状态机和重连 | [03-核心概念](03-核心概念.md)、[04-连接与认证](04-连接与认证.md) |
57
+ | 注册或加载 AID | [04-连接与认证](04-连接与认证.md) |
58
+ | 发布、下载或检查 agent.md | [04-连接与认证](04-连接与认证.md)、[06-API手册](06-API手册.md) |
59
+ | 状态机和重连 | [03-核心概念](03-核心概念.md)、[04-连接与认证](04-连接与认证.md) |
58
60
  | 查方法签名 | [06-API手册](06-API手册.md) |
59
61
  | 查消息或群组 RPC | 对应 `09-*-rpc-manual.md` |
60
62
  | 查 payload 格式 | [09-payload-reference.md](09-payload-reference.md) |
@@ -39,7 +39,7 @@
39
39
 
40
40
  ### 连接与状态
41
41
 
42
- - 九态状态机 → [03-核心概念](03-核心概念.md)
42
+ - 九态状态机、device_id / slot_id 隔离键 → [03-核心概念](03-核心概念.md)
43
43
  - `connect()` 选项、长短连接、网关发现 → [04-连接与认证](04-连接与认证.md)
44
44
  - capability getter、事件、生命周期 API → [06-API手册](06-API手册.md)
45
45
  - 裸 WebSocket 握手 → [02-WebSocket协议](02-WebSocket协议.md)
@@ -83,7 +83,7 @@
83
83
 
84
84
  ### 03-核心概念
85
85
 
86
- 解释 AID 身份、三主体职责、九态状态机、认证挑战-响应、默认 E2EE 行为和 RPC/事件模型。
86
+ 解释 AID 身份、三主体职责、device_id / slot_id 隔离键、九态状态机、认证挑战-响应、默认 E2EE 行为和 RPC/事件模型。
87
87
 
88
88
  ### 04-连接与认证
89
89
 
@@ -39,7 +39,7 @@ async def create_client(aid: str) -> AUNClient:
39
39
  raise RuntimeError(registered["error"]["message"])
40
40
  loaded = store.load(aid)
41
41
 
42
- client = AUNClient(loaded["data"]["aid"], debug=True)
42
+ client = AUNClient(loaded["data"]["aid"])
43
43
  await client.connect({"slot_id": "main", "auto_reconnect": True})
44
44
  return client
45
45
 
@@ -68,14 +68,14 @@ asyncio.run(main())
68
68
 
69
69
  ## 多语言构造约束
70
70
 
71
- | 语言 | options-only | AID + options |
71
+ | 语言 | 无身份构造 | 带身份构造 |
72
72
  |------|--------------|---------------|
73
73
  | Python | `AUNClient()` | `AUNClient(aid)` |
74
74
  | TypeScript | `new AUNClient()` | `new AUNClient(aid)` |
75
75
  | JavaScript | `new AUNClient()` | `new AUNClient(aid)` |
76
76
  | Go | `aun.NewAUNClientEmpty()` | `aun.NewAUNClient(aid)` |
77
77
 
78
- `aid` 必须是 AIDStore.load() 返回的 AID 对象,不是字符串。debug/verify_ssl/root_ca_path 等配置由 AID 携带,不再通过构造参数传入。
78
+ `aid` 必须是 `AIDStore.load()` 返回的 AID 对象,不是字符串。debug / verify_ssl / root_ca_path 等配置由 AID 携带,不再通过 `AUNClient` 构造参数传入。
79
79
 
80
80
  ---
81
81
 
@@ -0,0 +1,111 @@
1
+ import { AID } from './aid.js';
2
+ import type { TokenStore } from './keystore/index.js';
3
+ import type { ModuleLogger } from './logger.js';
4
+ import { type JsonObject } from './types.js';
5
+ export type AgentMdVerification = {
6
+ status: string;
7
+ reason?: string;
8
+ };
9
+ export type AgentMdDownloadResult = {
10
+ aid: string;
11
+ content: string;
12
+ verification: AgentMdVerification;
13
+ signature: Record<string, unknown>;
14
+ cert_pem: string;
15
+ etag: string;
16
+ last_modified: string;
17
+ status: number;
18
+ in_sync: boolean | null;
19
+ saved_to: string | null;
20
+ save_error: string | null;
21
+ };
22
+ export type AgentMdCheckResult = {
23
+ aid: string;
24
+ local_found: boolean;
25
+ remote_found: boolean;
26
+ local_etag: string;
27
+ remote_etag: string;
28
+ in_sync: boolean;
29
+ needs_update: boolean;
30
+ last_modified: string;
31
+ status: number;
32
+ cached: boolean;
33
+ verify_status: string;
34
+ verify_error: string;
35
+ ttl_days: number;
36
+ };
37
+ export interface AgentMdManagerOptions {
38
+ aunPath: string;
39
+ tokenStore?: TokenStore;
40
+ logger?: ModuleLogger | null;
41
+ ownerAidGetter?: () => string | null | undefined;
42
+ currentAidGetter?: () => AID | null | undefined;
43
+ gatewayResolver?: (aid: string) => Promise<string> | string;
44
+ peerResolver?: (aid: string) => Promise<AID> | AID;
45
+ accessTokenResolver?: (aid: string, gatewayUrl: string) => Promise<string> | string;
46
+ aidValidator?: (aid: string) => void;
47
+ }
48
+ export declare class AgentMdManager {
49
+ private _aunPath;
50
+ private _agentMdPath;
51
+ private _tokenStore?;
52
+ private _log;
53
+ private _ownerAidGetter?;
54
+ private _currentAidGetter?;
55
+ private _gatewayResolver?;
56
+ private _peerResolver?;
57
+ private _accessTokenResolver?;
58
+ private _aidValidator?;
59
+ private _cache;
60
+ private _memoryStorage;
61
+ private _fetchInflight;
62
+ private _lock;
63
+ private _localAgentMdEtag;
64
+ private _remoteAgentMdEtag;
65
+ constructor(opts: AgentMdManagerOptions);
66
+ get root(): string;
67
+ setAunPath(aunPath: string): void;
68
+ setRoot(root?: string | null): string;
69
+ upload(content?: string | null): Promise<Record<string, unknown>>;
70
+ download(aid?: string | null, timeoutMs?: number): Promise<AgentMdDownloadResult>;
71
+ check(aid?: string | null, ttlDays?: number): Promise<AgentMdCheckResult>;
72
+ observeMeta(aid: string, etag?: string, lastModified?: string, source?: string): Promise<void>;
73
+ observeRpcMeta(meta: JsonObject, ownerAid?: string | null): Promise<void>;
74
+ observeEnvelope(envelope: unknown): Promise<void>;
75
+ eventSnapshot(): {
76
+ local_etag: string;
77
+ remote_etag: string;
78
+ } | null;
79
+ readContent(aid: string): Promise<string | null>;
80
+ writeContent(aid: string, content: string): Promise<void>;
81
+ loadRecord(aid: string): Promise<Record<string, unknown> | null>;
82
+ saveRecord(aid: string, fields: Record<string, unknown>): Promise<Record<string, unknown>>;
83
+ static contentEtag(content: string): Promise<string>;
84
+ private static checkedAtFresh;
85
+ private static lastModifiedFresh;
86
+ private _defaultRoot;
87
+ private _joinPath;
88
+ private _logicalPath;
89
+ private _safeAid;
90
+ private _metaKey;
91
+ private _contentKey;
92
+ private _ownerAid;
93
+ private _currentAid;
94
+ private _resolveGateway;
95
+ private _resolvePeer;
96
+ private _accessToken;
97
+ private _url;
98
+ private _uploadHttp;
99
+ private _downloadHttp;
100
+ private _head;
101
+ private _readStorage;
102
+ private _writeStorage;
103
+ private _withLock;
104
+ private _normalizeRecord;
105
+ private _writeRecordUnlocked;
106
+ private _readRecordUnlocked;
107
+ private _hasLocalContent;
108
+ private _scheduleFetchIfMissing;
109
+ private _refreshOwnerEtags;
110
+ }
111
+ //# sourceMappingURL=agent-md.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agent-md.d.ts","sourceRoot":"","sources":["../src/agent-md.ts"],"names":[],"mappings":"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"}