@agentunion/fastaun-browser 0.2.18 → 0.2.20

package/_packed_docs/protocol/07-/351/224/231/350/257/257/347/240/201/344/270/216/347/212/266/346/200/201/346/234/272.md

@@ -0,0 +1,234 @@
+# 7. 错误码与状态机
+
+## 7.1 错误码分层
+
+### 7.1.1 JSON-RPC 2.0 通用错误码
+
+| 错误码 | 说明 | 客户端处理 |
+|--------|------|-----------|
+| -32700 | Parse error | 检查请求格式 |
+| -32600 | Invalid Request | 检查请求格式 |
+| -32601 | Method not found | 检查方法名 |
+| -32602 | Invalid params | 检查参数 |
+| -32603 | Internal error | 重试或报告 |
+
+### 7.1.2 AUN 协议级错误码（认证与权限）
+
+| 错误码 | 说明 | 客户端处理 |
+|--------|------|-----------|
+| -32001 | Authentication failed（认证失败） | 检查凭据，重新登录 |
+| -32002 | Certificate/Nonce invalid（凭据无效） | 检查证书链或 nonce |
+| -32003 | Signature verification failed（签名验证失败） | 检查私钥，不重试 |
+| -32004 | Permission denied（权限拒绝） | 提示用户，不重试 |
+| -32005 | Authentication expired（Token 过期） | 刷新 token 或重新登录 |
+
+### 7.1.3 AUN 协议级错误码（连接与会话）
+
+| 错误码 | 说明 | 客户端处理 |
+|--------|------|-----------|
+| -32010 | Agent not online | 稍后重试 |
+| -32011 | Session not found | 重新连接 |
+| -32013 | Initialization required | 先调用 auth.connect |
+
+### 7.1.3 Peer 握手错误码 (-3210x)
+
+| 错误码 | 说明 | 客户端处理 |
+|--------|------|-----------|
+| -32100 | Peer certificate validation failed | 终止握手，检查证书链 |
+| -32101 | Peer nonce expired | 重新发起 peer.hello |
+| -32102 | Peer nonce reuse detected | 关闭连接，记录告警 |
+| -32103 | Peer signature invalid | 终止握手，拒绝信任 |
+| -32104 | Peer aid mismatch | 拒绝对端，检查证书配置 |
+| -32105 | Peer handshake state invalid | 重试握手 |
+
+### 7.1.4 Relay 错误码 (-3215x)
+
+| 错误码 | 说明 | 客户端处理 |
+|--------|------|-----------|
+| -32150 | Relay registration required | 先 relay.register |
+| -32151 | Relay target not found | 稍后重试或回退模式 |
+| -32152 | Relay sender mismatch | 检查注册 AID |
+| -32153 | Relay payload too large | 缩小负载 |
+| -32154 | Relay rate limited | 退避重试 |
+
+### 7.1.5 搜索错误码 (-3216x)
+
+| 错误码 | 说明 | 客户端处理 |
+|--------|------|-----------|
+| -32160 | Search unavailable | 切换 AP |
+| -32161 | Agent not found | 检查 AID |
+| -32162 | Invalid search query | 修正查询 |
+| -32163 | Snapshot stale | 等待同步 |
+| -32164 | Change cursor expired | 用 snapshot 重建 |
+
+### 7.1.6 任务错误码 (-3217x)
+
+| 错误码 | 说明 | 客户端处理 |
+|--------|------|-----------|
+| -32170 | Task not found | 检查 task_id |
+| -32171 | Task state invalid | 先读取状态 |
+| -32172 | Task input required | 调 task.send_input |
+| -32173 | Task canceled | 停止推进 |
+| -32174 | Task output too large | 用 storage.* |
+| -32175 | Task access denied | 无权限 |
+| -32176 | Task already accepted | 不重复 accept |
+| -32177 | Task rejected | 停止或重建 |
+| -32178 | Task delegation denied | 无委派权限 |
+| -32179 | Task child limit exceeded | 减少子任务 |
+| -32185 | Task completion blocked | 等子任务完成 |
+| -32186 | Task failure recorded | 已终态 |
+
+### 7.1.7 连接升级错误码 (-3218x)
+
+| 错误码 | 说明 | 客户端处理 |
+|--------|------|-----------|
+| -32180 | Peer upgrade unsupported | 保持当前模式 |
+| -32181 | Peer upgrade expired | 重新发起 |
+| -32182 | Peer upgrade rejected | 保持当前模式 |
+| -32183 | Peer upgrade invalid endpoint | 丢弃提议 |
+| -32184 | Peer switch denied | 等新通道认证 |
+
+### 7.1.8 E2EE 错误码 (-3204x)
+
+| 错误码 | 说明 | 客户端处理 |
+|--------|------|-----------|
+| -32040 | Group secret missing（缺少群密钥） | 发送 key_request 请求补发 |
+| -32041 | Group epoch mismatch（epoch 不匹配） | 请求对应 epoch 的密钥 |
+| -32042 | Group commitment invalid（成员承诺验证失败） | 告警，检查成员列表 |
+| -32043 | Group not member（请求者非群成员） | 不重试 |
+| -32044 | Group decrypt failed（群消息解密失败） | 检查密钥，可能需 key_request |
+
+### 7.1.9 Group 错误码 (-3300x)
+
+| 错误码 | 说明 | 客户端处理 |
+|--------|------|-----------|
+| -33001 | Group not found | 检查 group_id |
+| -33002 | Group state invalid（群状态不允许该操作） | 检查群状态 |
+| -33003 | Group suspended | 等待恢复或联系管理员 |
+| -33004 | Group member limit reached | 不重试 |
+| -33005 | Group already member | 不重试 |
+| -33006 | Group not member | 先加入群 |
+| -33007 | Group role insufficient | 检查权限 |
+| -33008 | Group invite code invalid | 获取新邀请码 |
+| -33009 | Group join rejected | 不重试 |
+
+### 7.1.10 Stream 错误码 (-3340x)
+
+| 错误码 | 说明 | 客户端处理 |
+|--------|------|-----------|
+| -33401 | Stream not found（流不存在） | 检查 stream_id |
+| -33402 | Stream limit exceeded（达到流上限） | 等待其他流关闭后重试 |
+| -33403 | Stream permission denied（权限不足） | 不重试 |
+| -33404 | Stream already closed（流已关闭） | 不重试 |
+| -33405 | Stream invalid params（参数无效） | 检查参数 |
+| -33406 | Stream rate limited（速率限制） | 稍后重试 |
+| -33407 | Stream internal error（内部错误） | 稍后重试 |
+| HTTP 403 | push/pull token 无效，或 `target_aid` 不匹配 | 检查 URL / aid |
+| HTTP 404 | 数据平面找不到流 | 检查 stream_id |
+| HTTP 410 | 流已关闭 | 不重试 |
+| HTTP 429 | 拉流端数已达上限 | 稍后重试 |
+
+## 7.2 可重试 / 不可重试分类
+
+| 分类 | 错误码 | 说明 |
+|------|--------|------|
+| **可重试** | -32010, -32101, -32151, -32154, -32163, -32040, -32041 | 临时状态，稍后可能恢复 |
+| **不可重试** | -32001, -32003, -32004, -32100, -32102, -32103, -32104, -32175, -32043, -33001 | 永久性拒绝 |
+| **需操作后重试** | -32002, -32005, -32013, -32150, -32164, -32172, -32044 | 需要先完成特定操作 |
+
+## 7.3 连接状态机
+
+### 7.3.1 Gateway 模式状态机
+
+```
+CONNECTED
+  → auth.aid_login1
+  → auth.aid_login2 (获取 token)
+  → auth.connect(nonce, auth, protocol)
+  → AUTHENTICATED
+  → READY (可调用所有业务方法)
+```
+
+规则：
+- auth.* 可在 auth.connect 之前调用
+- auth.connect 成功即完成认证
+- token 失效需重连
+
+### 7.3.2 Peer 模式状态机
+
+```
+CONNECTED
+  → initialize(mode=peer)
+  → INITIALIZED
+  → peer.hello
+  → PEER_CHALLENGED
+  → peer.hello_reply
+  → PEER_VERIFIED
+  → peer.confirm
+  → AUTHENTICATED
+  → notification/initialized
+  → READY
+```
+
+规则：
+- initialize 只建立模式上下文
+- 任一 peer.* 失败应关闭连接
+- AUTHENTICATED 后可调业务方法
+
+### 7.3.3 Relay 模式状态机
+
+```
+CONNECTED
+  → initialize(mode=relay)
+  → INITIALIZED
+  → relay.register
+  → RELAY_REGISTERED
+  → relay.forward(peer.hello)
+  → ...peer.* 穿透认证...
+  → AUTHENTICATED
+  → notification/initialized
+  → READY
+```
+
+规则：
+- relay.register 仅建立 AID→连接映射
+- 身份认证以 peer.confirmed 为准
+- 未完成 peer.* 的连接不可投递业务消息
+
+### 7.3.4 通用连接状态表
+
+| 状态 | 允许的方法 | 说明 |
+|------|-----------|------|
+| CONNECTED | auth.connect, auth.*（仅 gateway 预认证） | 刚建立 WebSocket |
+| INITIALIZED | peer.*, relay.* | 仅 peer/relay 模式 |
+| AUTHENTICATED | 所有已协商方法 | 认证完成 |
+| READY | 所有已协商方法 | notification/initialized 后 |
+
+## 7.4 任务状态机
+
+```
+submitted → working → completed
+         → rejected   → input_required → working
+                       → failed
+                       → canceled
+```
+
+| 状态 | 终态 | 可转到 |
+|------|:----:|--------|
+| submitted | | working, rejected |
+| working | | input_required, completed, failed, canceled |
+| input_required | | working, failed, canceled |
+| rejected | 是 | |
+| completed | 是 | |
+| failed | 是 | |
+| canceled | 是 | |
+
+## 7.5 处理原则
+
+- **-3210x**：Peer 握手错误，中止当前认证（参见 [04-Peer-子协议](04-Peer-子协议.md)）
+- **-3215x**：Relay 错误，修正状态或回退模式（参见 [05-Relay-子协议](05-Relay-子协议.md)）
+- **-3216x**：搜索错误，修正查询或切换 AP（参见 [08-服务协议](08-服务协议.md)）
+- **-3217x**：任务错误，根据错误类型决定重试/放弃（参见 [08-服务协议](08-服务协议.md)）
+- **-3218x**：升级错误，保留当前稳定通道（参见 [04-Peer-子协议](04-Peer-子协议.md)）
+- **-3204x**：E2EE 错误，群密钥缺失时请求补发，解密失败时检查密钥版本（参见 [08-AUN-E2EE-Group](08-AUN-E2EE-Group.md)）
+- **-3300x**：群组错误，根据错误类型决定重试/提示用户（参见 [10-Group-子协议](10-Group-子协议.md)）