@agentunion/fastaun-browser 0.3.3 → 0.3.4

package/_packed_docs/protocol//351/231/204/345/275/225N-/345/210/206/345/270/203/345/274/217Trace/345/215/217/350/256/256.md

@@ -0,0 +1,257 @@
+# 附录 N — 分布式 Trace 协议
+
+## 设计目标
+
+为 AUN RPC 调用链路（SDK → Gateway → Service → Gateway → SDK）提供轻量级的分布式追踪能力，
+支持两种使用场景：
+
+1. **日志关联（log 模式）** — 全链路日志通过 `trace_id` 串联，零开销，可在生产环境常开
+2. **诊断回传（diag 模式）** — 各环节追加 span，response 携带完整链路返回调用者，
+   仅用于疑难问题诊断，需通过开关启用
+
+不依赖 OpenTelemetry / Jaeger 等外部体系，自定义 `_trace` 字段即可，跨语言实现成本极低。
+
+---
+
+## 一、协议层
+
+### 1.1 字段位置
+
+`_trace` 字段位于 JSON-RPC `params` 内，沿用 AUN 现有框架字段约定（与 `_caller_id`、`_auth` 同级）：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "message.send",
+  "params": {
+    "to": "bob.aid.com",
+    "body": "hello",
+    "_trace": {
+      "trace_id": "a1b2c3d4e5f6...",
+      "mode": "log"
+    }
+  }
+}
+```
+
+### 1.2 字段定义
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `trace_id` | string | 是 | 32 hex chars（16 bytes 随机），由 SDK 生成，全链路唯一 |
+| `mode` | string | 是 | `"log"` 或 `"diag"`，缺失视为 `"log"` |
+| `spans` | array | 否 | 仅 `diag` 模式存在，各环节追加 |
+
+**说明**：`mode: "off"` 不需要显式表示——不带 `_trace` 字段即为 off 状态。
+
+### 1.3 Span 结构
+
+```json
+{
+  "node": "gateway",
+  "ts": 1716300000156,
+  "action": "relay_in",
+  "ms": 0,
+  "detail": "route→message"
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `node` | string | 环节标识：`sdk-{aid}`、`gateway`、`{service_name}` |
+| `ts` | number | Unix 毫秒时间戳（入站时刻） |
+| `action` | string | 动作：`send` / `relay_in` / `process` / `relay_out` / `deliver` |
+| `ms` | number | 本环节处理耗时（出站时填写，入站初始为 0） |
+| `detail` | string | 可选，关键上下文（路由目标、错误码等），最多 256 字符 |
+
+---
+
+## 二、链路传播流程
+
+```
+SDK-A                Gateway              Service             Gateway              SDK-B
+  │                    │                    │                    │                    │
+  │─── params._trace ─▶│                    │                    │                    │
+  │  {trace_id, mode,  │                    │                    │                    │
+  │   spans:[sdk-send]}│                    │                    │                    │
+  │                    │── 追加 gateway ───▶│                    │                    │
+  │                    │   转发到 service   │                    │                    │
+  │                    │                    │── 追加 svc span ──▶│                    │
+  │                    │                    │   返回 response    │                    │
+  │                    │◀── response ───────│                    │                    │
+  │                    │   追加 gateway-out │                    │                    │
+  │◀── response._trace─│                    │                    │                    │
+  │                    │                    │                    │                    │
+  │                    │─── event._trace ──────────────────────▶│── deliver ────────▶│
+```
+
+### 2.1 各环节职责
+
+| 环节 | 入站行为 | 出站行为 |
+|------|----------|----------|
+| SDK 发起 | 生成 trace_id；mode≠off 时构造 `_trace` 注入 params | — |
+| Gateway 入站 | 读取 _trace，应用降级；diag 模式追加 `relay_in` span | — |
+| Service 处理 | 读取 _trace 写入日志（log）或追加 span（diag） | response 透传 _trace |
+| Gateway 出站 | diag 模式追加 `relay_out` span | log 模式剥离 _trace；diag 模式注入 response 顶层 |
+| SDK 接收 | 提取 response._trace 回调 trace observer | — |
+
+---
+
+## 三、Response 回传（仅 diag 模式）
+
+Gateway 在 `deliver_response_to_client` 中将 `_trace` 注入 response 顶层（与 `_meta` 平级）：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {"status": "ok", "message_id": "..."},
+  "_meta": {"agent_md_etag": "..."},
+  "_trace": {
+    "trace_id": "a1b2c3...",
+    "mode": "diag",
+    "spans": [
+      {"node": "sdk-alice.aid.com", "ts": 1716300000100, "action": "send"},
+      {"node": "gateway", "ts": 1716300000123, "action": "relay_in", "ms": 2, "detail": "→message"},
+      {"node": "message", "ts": 1716300000125, "action": "process", "ms": 15},
+      {"node": "gateway", "ts": 1716300000142, "action": "relay_out", "ms": 1}
+    ]
+  }
+}
+```
+
+**注意**：log 模式下 response 不带 `_trace`（保持 envelope 干净，零开销）。
+
+---
+
+## 四、开关层级
+
+### 4.1 三态定义
+
+| 值 | 行为 |
+|---|---|
+| `off` | 不生成 `_trace`，零开销（默认） |
+| `log` | 生成 trace_id + 各环节写本地日志，response 不回传 |
+| `diag` | 同 log + spans 追加 + response 回传完整链路 |
+
+### 4.2 控制点
+
+| 层级 | 配置位置 | 默认值 | 作用 |
+|------|----------|--------|------|
+| 服务端上限 | Gateway 环境变量 `AUN_TRACE_MAX_MODE` | `"log"` | 超过此级别自动降级 |
+| SDK 会话级 | `client.set_trace_mode("log")` | `"off"` | 连接内所有请求默认 mode |
+| SDK 调用级 | `client.rpc("method", params, trace="diag")` | 继承会话级 | 单次覆盖，优先级最高 |
+
+### 4.3 优先级规则
+
+```
+最终 mode = min(SDK 调用级 || SDK 会话级, 服务端上限)
+其中 off < log < diag
+```
+
+### 4.4 服务端降级逻辑（Gateway 入站时）
+
+```python
+client_mode = trace.get("mode", "off")
+server_max = config.trace_max_mode  # "off" | "log" | "diag"
+effective = min(client_mode, server_max)
+if effective != client_mode:
+    trace["mode"] = effective
+    if effective != "diag":
+        trace.pop("spans", None)  # 降级到 log/off 时丢弃已有 spans
+```
+
+**生产环境推荐配置**：`AUN_TRACE_MAX_MODE=log`，diag 需运维手动开启。
+
+---
+
+## 五、各组件改动点
+
+### 5.1 SDK 侧
+
+**`transport.py`**：
+- `call()` 方法：会话/调用级 mode 非 off 时，构造 `_trace` 注入 params
+- response 处理：提取 `_trace` 回调 trace observer（与现有 `_meta_observer` 模式一致）
+
+**`client.py`**：
+- 新增 `set_trace_mode(mode: str)`：设置会话级默认 mode
+- `rpc()` 方法新增 `trace` 参数：单次覆盖 mode
+- 暴露 `set_trace_observer(callback)`：接收 diag 模式回传的 spans
+
+### 5.2 Gateway 侧
+
+**`ws_server.py`**：
+- `_resolve_ws_message_trace()` 改造：读取 mode，应用服务端降级
+- 入站时追加 `relay_in` span（diag 模式）
+- `_strip_internal_route()` 保持现状：log 模式仍剥离 `_trace`，diag 模式由 response 路径专门处理
+
+**`relay.py`**：
+- `deliver_response_to_client()`：diag 模式追加 `relay_out` span，将 `_trace` 注入 response 顶层
+
+### 5.3 Service 侧
+
+通用 pattern（适用于 message / group / storage / stream / mail 等所有服务）：
+1. RPC 入口提取 `params._trace`
+2. 处理过程中通过 trace_id 写入日志
+3. diag 模式追加自身 span
+4. response 透传 `_trace` 字段
+
+---
+
+## 六、日志格式（log 模式）
+
+各环节按现有日志规范输出，前缀加 trace_id：
+
+```
+[2026-05-21 10:00:00.123][INFO][gateway] [trace=a1b2c3d4] relay_in method=message.send conn=42
+[2026-05-21 10:00:00.125][INFO][message] [trace=a1b2c3d4] process persist=true target=bob.aid.com
+[2026-05-21 10:00:00.140][INFO][gateway] [trace=a1b2c3d4] relay_out duration_ms=17
+```
+
+排查时 `grep trace=a1b2c3d4` 即可串联全链路。
+
+---
+
+## 七、安全约束
+
+| 约束 | 限制 |
+|------|------|
+| spans 数组最大长度 | 32 条，超出由 Gateway 截断尾部 |
+| 单个 detail 最大长度 | 256 字符 |
+| trace_id 长度 | 严格 32 hex chars，不合规由 Gateway 重新生成 |
+| 敏感信息 | spans 禁止包含消息体、密钥、Token 等，只记录路由/耗时/错误码等元数据 |
+| 生产环境默认 | `AUN_TRACE_MAX_MODE=log`，diag 需运维手动开启 |
+| 跨域传播 | 跨 federation 边界时保留 trace_id，spans 在边界节点视为新链路起点 |
+
+---
+
+## 八、跨语言实现要点
+
+所有 SDK（Python / Go / TypeScript / JavaScript / C++）需保持一致：
+
+1. **trace_id 生成**：16 字节加密随机数，hex 编码
+2. **时间戳**：Unix 毫秒（不使用秒/纳秒），统一单位
+3. **字段顺序**：JSON 字段顺序不影响语义，但建议按 `trace_id, mode, spans` 顺序输出便于阅读
+4. **observer 接口**：各 SDK 提供 `set_trace_observer(callback)` 接口，签名一致
+5. **会话/调用级 API 命名**：
+   - 设置：`set_trace_mode(mode)` / `setTraceMode(mode)`
+   - 单次覆盖：`rpc(method, params, trace=mode)` / `rpc(method, params, {trace: mode})`
+
+---
+
+## 九、未实现 / 后续扩展
+
+以下能力本附录暂不覆盖，留作后续扩展：
+
+- **采样率控制**：当前 SDK 完全控制 mode，未引入概率采样（如 1% diag）
+- **OpenTelemetry 适配**：未来如需对接 Jaeger / Zipkin，可在 Gateway 端增加导出适配层，
+  将 spans 转为 OTLP 格式
+- **跨域链路连续性**：当前跨 federation 边界视为新链路，未实现端到端 trace_id 透传
+- **span 父子关系**：当前 spans 数组仅按时间排序，未引入 parent_span_id（保持极简）
+
+---
+
+## 文档版本
+
+- v1.0 — 2026-05-21 初稿，定义协议字段、链路传播、开关层级、安全约束

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

@@ -30,17 +30,17 @@ BOB = f"bob{random.randint(1000,9999)}.{DOMAIN}"
 
 
 async def create_client(aid: str) -> tuple[AUNClient, dict]:
-    """创建客户端 → 加载或创建 AID → 认证 → 返回 (client, auth)"""
+    """创建客户端 → 注册 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})
+            await client.auth.register_aid({"aid": aid})
         except AuthError as e:
-            print(f"[错误] 创建 AID 失败 ({aid}): {e}")
+            print(f"[错误] 注册 AID 失败 ({aid}): {e}")
             raise
         except ConnectionError as e:
             print(f"[错误] 网络连接失败: {e}")
@@ -213,7 +213,7 @@ await client.connect(auth, {
 完整的使用流程见上方"最小示例"，核心步骤：
 
 1. **创建客户端** - `AUNClient(config)`
-2. **加载或创建 AID** - `load_identity_or_none()` → `create_aid()`
+2. **注册 AID** - `check_aid()` → `register_aid()`
 3. **认证** - `authenticate()` 获取令牌
 4. **订阅事件** - `on("message.received", handler)`
 5. **连接** - `connect(auth, options)`

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

@@ -210,7 +210,7 @@ async def authenticate(aid: str) -> dict:
     try:
         client = AUNClient({"aun_path": f"~/.aun/{aid}"})
         if not client._auth.load_identity_or_none(aid):
-            await client.auth.create_aid({"aid": aid})
+            await client.auth.register_aid({"aid": aid})
         auth = await client.auth.authenticate({"aid": aid})
         return auth
     except AuthError as e:

package/_packed_docs/sdk/03-/346/240/270/345/277/203/346/246/202/345/277/265.md

@@ -19,8 +19,8 @@ AID 是 Agent 的全局唯一身份，格式为域名形式：`alice.agentid.pub
 import random
 MY_AID = f"alice-{random.randint(1000,9999)}.agentid.pub"
 
-# 创建（仅首次）
-await client.auth.create_aid({"aid": MY_AID})
+# 注册（仅首次）
+await client.auth.register_aid({"aid": MY_AID})
 
 # 认证
 auth = await client.auth.authenticate({"aid": MY_AID})