# web3-agent

**Repository Path**: alan223/web3-agent

## Basic Information

- **Project Name**: web3-agent
- **Description**: A multi-agent system that analyzes smart contracts and Web3 project risks using RAG and tool-based reasoning.
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-07
- **Last Updated**: 2026-04-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Web3 Multi-Agent 系统设计说明

## 项目定位

这是一个面向 Web3 场景的多智能体系统，核心目标不是单次问答，而是把复杂请求拆成可执行任务，再由不同能力域的 Worker 协同完成。

系统覆盖三类主能力：

1. 链上查询（余额、Gas、交易、ENS、NFT、合约判断等）
2. 安全审计（地址/代币/NFT/授权风险）
3. 知识与资讯检索（白皮书检索、新闻同步、新闻摘要）

---

## 设计原则

### 1. 规划与执行解耦

Supervisor 只负责意图识别与任务编排，Worker 只负责域内执行。这样可以把“怎么做”与“做什么”分开，降低耦合。

### 2. 记忆先行

所有请求先进入 memory 节点，再进入 supervisor。先做上下文治理，后做规划，避免长会话退化与路由漂移。

### 3. 结构化输出优先

Supervisor 和 Worker 内部规划均采用结构化输出，避免纯文本协议导致的解析不稳定。

### 4. 可降级但不中断

在检索、重排、向量化、模型调用等环节均保留降级路径，保证系统在外部依赖不稳定时仍可输出可用结果。

---

## 总体架构

系统执行图采用 LangGraph 状态图，主路径如下：

START -> memory -> supervisor -> workers -> supervisor -> finish -> END

其中：

1. memory：三层记忆治理与 token 守卫
2. supervisor：意图识别、任务拆解、路由决策
3. workers：按领域执行具体动作
4. finish：结果收口、统一回答、超长裁剪

共享状态由统一 AgentState 管理，核心字段包括：

1. messages（会话消息）
2. pending_tasks / current_task / results（任务队列与结果）
3. history_summary / memory_window_messages / retrieved_memories（记忆层）
4. token_guard（上下文预算统计）

---

## 多智能体协同机制

## Supervisor

Supervisor 输出结构化决策：

1. intent：qa / research_report / mixed / unknown
2. report_mode：是否进入报告式整合
3. tasks：按顺序执行的任务队列
4. next_agent：下一跳路由

在报告模式下，系统会主动覆盖 onchain + security + rag 三域，避免退化成单域回答。

## Worker 设计

每个 Worker 不是“直接工具转发”，而是先做一次域内子意图规划，再执行单动作：

1. Onchain Worker：eth_balance / token_price / erc20_balance / gas_price / ens_resolve / tx_details / nonce / nft_balance / is_contract
2. Security Worker：token_risk / address_risk / approve_risk / nft_risk
3. RAG Worker：knowledge_retrieval / news_digest / news_sync_then_digest

这保证了真正的多智能体行为：上层负责任务编排，下层负责域内决策。

---

## 三层记忆系统

系统在 memory 节点实现三层记忆：

### 1. 短期窗口记忆

保留最近 N 轮完整 turn（默认 5 轮），保证当前对话连贯。

### 2. 摘要记忆

窗口外历史按批次做增量摘要（默认每 10 轮），保留：

1. 用户核心问题
2. 关键参数（地址/合约/代币/时间）
3. 已解决与未解决事项

### 3. 向量记忆

将每轮 user/assistant 对话写入 Chroma 向量库，并按 thread_id 做会话隔离。命中“之前/刚才/继续”等续问语义时，触发历史召回。

---

## Token 守卫机制

系统在关键调用前执行 token 预算检查：

1. 预算阈值 = LLM_CONTEXT_WINDOW × TOKEN_GUARD_RATIO（默认 32000 × 0.8）
2. 超阈值时优先压缩上下文，再调用模型
3. 计数优先使用模型计数器，失败时降级 chars/4 估算

该机制在 memory（摘要触发）与 finish（回答生成）两端同时生效，避免长会话超窗导致失败。

---

## RAG 设计

RAG 采用“双通道检索 + 统一重排”架构。

## 通道 A：普通文档检索

1. 文档来源：pdf / md / txt
2. 向量库：Chroma collection web3_docs
3. 流程：query rewrite -> 向量召回 -> rerank

## 通道 B：表格 Multi-Vector 检索

1. 抽取 markdown 表格
2. 表格摘要入 summary collection
3. 原始表格入 raw collection
4. 查询时先命中摘要，再按 table_id 回源 raw markdown

最终将 A/B 通道候选合并后二次 rerank，输出给上层工具。

## 关键收益

1. 普通文本保持召回覆盖
2. 表格查询保留结构信息，不因切块丢失行列语义
3. 在复杂 PDF 场景中可选接入 LlamaParse 做结构化预处理

---

## 数据流与执行流

一次复杂请求的实际执行如下：

1. 用户输入进入 messages
2. memory 节点做窗口/摘要/召回与 token 评估
3. supervisor 识别意图并生成任务队列
4. workers 按队列执行并写入 results
5. finish 基于结果统一收口
6. 若无任务结果则回退到聊天模式，保持 bot 连续可用

---

## 技术栈

## 编排与模型

1. LangGraph（状态图编排）
2. LangChain / langchain_openai（模型调用与结构化输出）
3. DeepSeek Chat（主对话与规划模型）

## 检索与向量

1. LlamaIndex（索引与检索抽象）
2. ChromaDB（本地向量存储）
3. DashScope Embedding（text-embedding-v4）
4. DashScope Rerank（候选重排）

## Web3 与外部能力

1. web3.py（链上读操作）
2. GoPlus API（安全审计）
3. CryptoCompare/CoinDesk 数据源（新闻）

---

## 可观测性与评估

系统保留独立评估脚本用于离线回归，重点评估：

1. 路由正确性（是否选择正确 Worker）
2. 工具执行质量（是否提取到正确参数）
3. 综合回答质量（多域任务是否完整覆盖）

---

## 当前边界

1. Worker 当前以“单动作执行”为主，复杂域内多步推理仍可进一步增强
2. 表格抽取主要依赖 markdown 结构，超复杂版式 PDF 仍受解析质量影响
3. 会话 checkpoint 当前为内存模式，持久化可进一步升级

这套架构的核心价值是：在 Web3 复杂问题场景下，通过可编排、可压缩、可检索、可降级的多智能体机制，保持准确性与稳定性的平衡。