系统架构
从用户点击到链上广播，AI Crypto Wallet 如何编排 UI、智能体、安全网关与链数据？本篇拆解四层架构、六大设计原则与关键数据流，帮助你理解一个「会交易」的钱包到底如何运作。
01四层架构总览
系统整体划分为四层，自顶向下分别是用户交互层、智能体核心层、安全与风控层、数据与链上层。每一层职责单一、边界清晰，上层只能通过既定接口调用下层，从而保证安全与可维护性。
用户交互层
负责界面渲染与用户输入采集。主页承载「资产 / 行情 / 交易 / 发现 / 我的」五大 Tab；AI 交易界面在「详情 / 聊天」两种模式间切换。本层不承载任何业务逻辑，只做展示与转发。
智能体核心层
AI 的「大脑」。AgentRuntime 运行思考循环，AgentToolRegistry 声明 12 个可调用工具，AgentMemory 保存 AI 的自述文件与记忆，AIAnalyzer 封装 LLM 调用。参考 Trae 的 Agent 架构实现。
安全与风控层
所有写入操作的「闸门」。SafetyGate 做交易前五步校验，RiskManager 做交易中风控，TradeAuthManager 控制 AI 交易启动条件。任何资金变更都必须穿越本层。
数据与链上层
链上与现实数据的「地基」。ChainAPI 封装多链 RPC，NodeManager 管理节点切换，MultiChainMarketData 计算技术指标，WalletManager 在内存中持有并管理私钥、完成本地签名。
02核心设计原则
架构的每一个取舍都源于以下六条原则：
| 原则 | 含义 | 落地体现 |
|---|---|---|
| 证据驱动 | AI 决策必须基于链上数据与技术指标，不凭感觉 | 决策前调用 get_market_data / get_position 等只读工具 |
| 安全优先 | 所有写入操作必须经过 SafetyGate | 写入工具在 AgentToolRegistry 中强制门控 |
| 用户可控 | 自动交易由用户手动开启/关闭，AI 不能自行启动 | TradeAuthManager 启动条件 + UI 开关 |
| 白名单机制 | 非白名单代币必须用户确认，60 秒超时自动拒绝 | SafetyGate 白名单检查 |
| 脱敏存储 | API Key 脱敏，钱包地址实时获取不静态存储 | apiKeyMasked 前4后4；address 实时从 WalletManager 取 |
| 可审计 | 所有工具调用记录完整日志，可追溯 | Logger 记录 [时间][级别][模块] 全链路 |
安全优先与用户可控是「自动交易」的前提。AI 只拥有「发起意图」的能力，真正的放行权始终握在安全网关与用户手中。脱敏与可审计则确保即使 AI 出错，也能被记录、被追责、被纠正。
03关键流程
AI 自动交易流程
用户对话流程
两条流程共享同一套「构建上下文 → 调用 LLM → 执行工具 → 返回」的循环骨架，区别仅在于触发来源（定时 vs 用户）与是否允许写入。
04异常处理机制
系统针对三类异常分别设计了处置策略：
网络异常
| 异常类型 | 处理方式 |
|---|---|
| ConnectException | 切换备用节点，重试当前批次 |
| SocketTimeout | 超时缩短至 3s，快速失败快速回退 |
| Cloudflare 403 | 切换 User-Agent 与 HttpClient |
| GFW 阻断 | 使用自建代理节点（如 BSC AVE 代理） |
交易异常
| 异常类型 | 处理方式 |
|---|---|
| 交易失败 | 记录错误，通知 SafetyGate 更新错误率 |
| 滑点过大 | 拒绝交易，提示调整滑点容忍度 |
| Gas 不足 | 提示用户充值原生币 |
| 合约调用失败 | 返回错误信息，AI 可调整策略重试 |
应用异常
| 异常类型 | 处理方式 |
|---|---|
| onCreate 崩溃 | try-catch(Throwable) + Toast + 写 crash_log |
| onResume 冲突 | 延迟 500ms 执行网络请求 |
| 空指针 | 所有 View 操作前判空 |
| View 初始化失败 | try-catch + Toast，不闪退 |
主线程禁止做 OkHttp 网络请求（易被系统限制）；批量查询 getAllTokenBalances 比单查更稳定；BscScan 的 Cloudflare Challenge 无法绕过，需走自建代理节点。这些踩坑经验均已沉淀进架构。