swarmmind/README.zh-CN.md at main · KuaaMU/swarmmind

English | 中文

SwarmMind 是一个自主运行的多 AI Agent DeFi 情报网络。5 个专业化 AI Agent 在 X Layer 上发现、评估和执行交易机会，并通过 x402 微支付协议互相付费。编排器采用 ReAct（推理 + 行动）循环，由 LLM 动态决定调用哪些 Agent、以什么顺序调用、以及如何根据结果做出反应。

为 X Layer AI Hackathon (Phase 1: 2026年3月12-26日) 构建。

为什么 SwarmMind 能赢

评审标准	SwarmMind 的表现
深度 AI-Agent 链上集成	5 个 AI Agent，各有独立钱包，链上注册，通过 ReAct 工具调用循环实现自主决策
自主支付流程	Agent 间 x402 HTTP 微支付，USDC 在 X Layer 上结算 - 由 LLM 决定何时付款
多 Agent 协作架构	经济激励：Scout 卖信号赚钱，Oracle 卖风险评估赚钱，PM 动态编排
生态影响力	可复用基础设施：AgentRegistry、WalletFactory、PaymentSettlement + MCP 服务器、CLI 工具、SKILL.md 插件
OKX OnchainOS	使用 Market API 获取数据，Trade API 执行 DEX 交易，兼容 onchainos-skills

架构

ReAct 编排

Portfolio Manager 采用 ReAct（推理 + 行动）循环，由 LLM 动态决定调用哪些 Agent：

ReActOrchestrator.runOnce():
  messages = [系统提示词 + 投资组合上下文]
  loop (最多 10 次迭代):
    response = llm.chatWithTools(messages, tools)
    if response.hasToolCalls:
      for each toolCall:
        result = execute(toolCall)     // 调用 Agent HTTP API
        messages.push(toolResult)      // 将结果反馈给 LLM
        emit("TOOL_CALL", result)      // WebSocket 广播
    else:
      break  // LLM 决定已完成

LLM 动态决定：

调用哪些 Agent，以什么顺序
根据风险评分决定继续还是中止
如何应对异常结果（如流动性不足、滑点过高）
编排周期何时结束

Agent 角色

Agent	角色	端口	付费模式
Portfolio Manager	ReAct 编排器 - LLM 驱动的工具调用循环	3000	通过 x402 付费给其他 Agent
Alpha Scout	市场情报 - 用 AI 分析市场数据生成交易信号	3001	出售信号 ($0.001-$0.005 USDC/次)
Risk Oracle	风险评估 - 用 AI 评估交易提案的风险	3002	出售评估 ($0.001-$0.002 USDC/次)
Liquidity Agent	流动性分析 - 评估 DEX 流动性池深度	-	出售评估 ($0.001 USDC/次)
Trade Executor	DEX 执行 - 在 X Layer 上执行代币交换	3003	内部调用 (API Key 保护)

支付流程 (x402 协议)

Portfolio Manager  ──GET /signals/latest──>  Alpha Scout
                   <──402 Payment Required──
                   ──签名 EIP-712 授权────>
                   <──200 OK + 信号数据────  (USDC 在 X Layer 上结算)

已部署合约 (X Layer 测试网)

合约	地址	用途
AgentRegistry	`0xf159428B...`	链上 Agent 目录与信誉追踪
AgentWalletFactory	`0xE1c33aaC...`	CREATE2 确定性钱包工厂
PaymentSettlement	`0xEF334ADc...`	USDC 支付审计链

链上交易证明

Agent 注册交易：

Alpha Scout: 0x86195729...
Risk Oracle: 0x53bb8f78...
Trade Executor: 0x0ecfed4f...
Portfolio Manager: 0xcc8fb97b...

Agent 间支付交易 (x402 模拟)：

PM -> Alpha Scout: 0xaa788ab3...
PM -> Risk Oracle: 0x3f941778...

技术栈

层	技术
智能合约	Solidity 0.8.24 + Hardhat + OpenZeppelin
Agent 后端	TypeScript + Node.js + Express
AI 推理	ReAct 工具调用循环，多模型支持 (Claude, GPT, DeepSeek, OpenRouter)
DEX 交易	OKX OnchainOS Trade API
市场数据	OKX OnchainOS Market API
支付	x402 HTTP 协议 + USDC 直接结算
前端	Next.js + TailwindCSS + Recharts
区块链	ethers.js v6, X Layer (Chain ID 196)
集成	MCP 服务器、Claude Code SKILL.md 插件、CLI 工具
项目管理	Turborepo + npm workspaces
测试	Vitest (Agent) + Hardhat/Chai (合约)

快速开始

前置要求

Node.js 20+
npm 10+
X Layer 上的 OKB 作为 gas (~$0.001/笔)
一个 AI API Key (Anthropic、OpenAI、DeepSeek 或 OpenRouter)

安装

git clone https://github.com/KuaaMU/swarmmind.git
cd swarmmind
npm install

# 配置环境变量
cp .env.example .env
# 编辑 .env，填入你的 API Key 和钱包私钥

# 构建所有包
npm run build

运行测试

# 所有测试 (185 个全部通过)
npm test

# 或单独运行:
# 智能合约测试 (29 个)
cd packages/contracts && npx hardhat test

# Agent 单元测试 (156 个)
# shared: 47 | alpha-scout: 8 | risk-oracle: 21 | portfolio-manager: 40 | trade-executor: 25 | liquidity-agent: 15
npx vitest run

部署合约

cd packages/contracts

# 测试网
npx hardhat run scripts/deploy.ts --network xlayerTestnet

# 注册 Agent 到链上
npx hardhat run scripts/register-agents.ts --network xlayerTestnet

# 主网
npx hardhat run scripts/deploy.ts --network xlayer

运行 E2E 演示

# 完整演示: Agent 验证 -> 信号生成 -> 风险评估 -> 链上支付
npx tsx scripts/demo-e2e.ts

启动 Agent

# 开发模式 (通过 Turborepo 启动所有 Agent)
npm run dev

# 或单独启动
cd packages/agents/alpha-scout && npm run dev
cd packages/agents/risk-oracle && npm run dev
cd packages/agents/trade-executor && npm run dev
cd packages/agents/portfolio-manager && npm run dev

智能合约

AgentRegistry.sol (~130 行)

链上 Agent 服务目录。存储钱包地址、名称、角色 (SCOUT/ORACLE/EXECUTOR/MANAGER)、服务端点、定价、收入/支出计数器。

AgentWalletFactory.sol (~80 行)

通过 OpenZeppelin Clones (最小代理模式) 实现 CREATE2 确定性钱包创建。每个钱包约 $0.001 部署成本。

PaymentSettlement.sol (~120 行)

记录 Agent 间 USDC 转账，提供链上审计追踪。支持单笔和批量结算。

项目结构

swarmmind/
├── packages/
│   ├── contracts/                  # Solidity 智能合约
│   │   ├── contracts/              # 3 个核心合约
│   │   ├── scripts/                # 部署和注册脚本
│   │   └── test/                   # 29 个 Hardhat 测试
│   ├── agents/
│   │   ├── shared/                 # 公共基础设施
│   │   │   └── src/
│   │   │       ├── ai/            # 多模型 AI 客户端 + 工具调用
│   │   │       ├── okx/           # OnchainOS Market + Trade API
│   │   │       ├── payments/      # x402 客户端/服务端 + 直接支付
│   │   │       ├── wallet/        # Agent 钱包 (ethers.js)
│   │   │       └── config/        # X Layer 配置 + 环境变量
│   │   ├── alpha-scout/           # 市场信号 Agent (端口 3001)
│   │   ├── risk-oracle/           # 风险评估 Agent (端口 3002)
│   │   ├── trade-executor/        # DEX 交易 Agent (端口 3003)
│   │   ├── liquidity-agent/       # 流动性池分析
│   │   └── portfolio-manager/     # ReAct 编排器 Agent (端口 3000)
│   │       └── src/
│   │           ├── tools/         # ReAct 循环的工具定义
│   │           └── services/      # ReActOrchestrator + 旧版编排器
│   ├── mcp-server/                # MCP 服务器 (模型上下文协议)
│   ├── cli/                       # CLI 工具 (@swarmmind/cli)
│   └── dashboard/                 # Next.js 前端
│
├── skills/                        # Claude Code SKILL.md 插件
│   ├── swarm-orchestrate/
│   ├── swarm-signals/
│   ├── swarm-risk/
│   └── swarm-trade/
│
├── .claude-plugin/plugin.json     # 插件清单
├── .mcp.json.example              # MCP 服务器配置模板
├── scripts/                       # E2E 演示和 AI 测试脚本
├── docker-compose.yml
└── turbo.json

X Layer 集成

	主网	测试网
Chain ID	196	1952
RPC	`https://rpc.xlayer.tech`	`https://testrpc.xlayer.tech`
浏览器	oklink.com/xlayer	oklink.com/xlayer-test
Gas	OKB (~$0.0001/笔)	OKB (水龙头)
USDC	`0x74b7F16337b8972027F6196A17a631aC6dE26d22`	-

AI 模型配置

SwarmMind 支持多种 AI 模型。在 .env 中配置：

# 选择: anthropic | openai | deepseek | openrouter
AI_PROVIDER=anthropic
ANTHROPIC_API_KEY=your_key

# 可选: 指定模型
AI_MODEL=claude-haiku-4-5-20251001

# 可选: 中转站/代理端点
AI_BASE_URL=https://your-relay.com

支持的默认模型: Claude Haiku 4.5 (anthropic), GPT-4o-mini (openai), DeepSeek Chat (deepseek)。

MCP 服务器

SwarmMind 提供 MCP（模型上下文协议）服务器，任何兼容 MCP 的客户端（Claude Code、Cursor 等）都可以与 Agent 集群交互。

配置

# 复制配置模板
cp .mcp.json.example .mcp.json

# 先启动 Agent
npm run dev

# MCP 服务器通过 HTTP 连接到运行中的 Agent

.mcp.json 配置：

{
  "mcpServers": {
    "swarmmind": {
      "command": "npx",
      "args": ["ts-node", "packages/mcp-server/src/index.ts"],
      "env": {
        "PORTFOLIO_MANAGER_URL": "http://localhost:3000",
        "ALPHA_SCOUT_URL": "http://localhost:3001",
        "RISK_ORACLE_URL": "http://localhost:3002",
        "TRADE_EXECUTOR_URL": "http://localhost:3003"
      }
    }
  }
}

可用工具

工具	说明
`get_signals`	从 Alpha Scout 获取最新交易信号
`assess_risk`	通过 Risk Oracle 评估交易风险
`execute_trade`	通过 Trade Executor 执行交易
`get_portfolio`	获取当前投资组合状态
`run_cycle`	运行一个完整的 ReAct 编排周期

资源

URI	说明
`swarmmind://agents`	所有已注册 Agent 及其状态
`swarmmind://portfolio`	当前投资组合状态
`swarmmind://reasoning`	最新 ReAct 推理链路

CLI 命令行工具

# 获取最新交易信号
npx swarmmind signals

# 仅套利信号
npx swarmmind signals --arbitrage

# 评估信号风险
npx swarmmind risk <signalId>

# 执行交易
npx swarmmind trade <signalId> -a 100

# 查看投资组合
npx swarmmind portfolio

# 列出已注册 Agent
npx swarmmind agents

# 运行一次 ReAct 编排周期
npx swarmmind orchestrate

# 启动/停止持续编排
npx swarmmind orchestrate --start
npx swarmmind orchestrate --stop

# JSON 输出（用于脚本集成）
npx swarmmind signals --json

Claude Code 插件 (SKILL.md)

SwarmMind 作为 Claude Code 插件发布，包含 4 个可发现的技能：

技能	说明
`swarm-orchestrate`	运行自主 DeFi 情报编排周期
`swarm-signals`	从 Alpha Scout 获取实时交易信号
`swarm-risk`	通过 Risk Oracle 评估交易风险
`swarm-trade`	通过 Trade Executor 执行交易

使用方式

将 .claude-plugin/ 和 skills/ 复制到你的项目中，或直接引用本仓库。技能兼容 onchainos-skills，可与 dex-signal、dex-swap、wallet-portfolio 等技能配合使用。

许可证

MIT

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

为什么 SwarmMind 能赢

架构

ReAct 编排

Agent 角色

支付流程 (x402 协议)

已部署合约 (X Layer 测试网)

链上交易证明

技术栈

快速开始

前置要求

安装

运行测试

部署合约

运行 E2E 演示

启动 Agent

智能合约

AgentRegistry.sol (~130 行)

AgentWalletFactory.sol (~80 行)

PaymentSettlement.sol (~120 行)

项目结构

X Layer 集成

AI 模型配置

MCP 服务器

配置

可用工具

资源

CLI 命令行工具

Claude Code 插件 (SKILL.md)

使用方式

许可证

FilesExpand file tree

README.zh-CN.md

Latest commit

History

README.zh-CN.md

File metadata and controls

为什么 SwarmMind 能赢

架构

ReAct 编排

Agent 角色

支付流程 (x402 协议)

已部署合约 (X Layer 测试网)

链上交易证明

技术栈

快速开始

前置要求

安装

运行测试

部署合约

运行 E2E 演示

启动 Agent

智能合约

AgentRegistry.sol (~130 行)

AgentWalletFactory.sol (~80 行)

PaymentSettlement.sol (~120 行)

项目结构

X Layer 集成

AI 模型配置

MCP 服务器

配置

可用工具

资源

CLI 命令行工具

Claude Code 插件 (SKILL.md)

使用方式

许可证