去中心化多 Agent 协作网络

让已有的 Agent 通过添加一个 tool，就能加入 P2P 网络——接单或派单，无需改动原有架构。

核心理念：一个 Tool，双向接入

你的 HermesAgent / OpenClaw / 任意 Agent
         │
         ├─ 加 wrapAgent tool          → 变成 P2P 服务端，接收来自全网的任务
         └─ 加 DelegateToNetwork tool  → 变成 P2P 客户端，向全网派发任务

原 Agent 的代码、架构、其他 tool 全部不动。

快速接入

服务端：让你的 Agent 接受网络任务

import { AgentNode, wrapAgent } from 'blockchain-multi-agent'
import { MyAgent } from './my-agent.js'   // 你现有的 Agent，一行不改

const node = await AgentNode.create({ port: 9010 })

node.registerCapability(wrapAgent({
  id: 'my-agent',
  shortDescription: 'Research and summarize any topic via web search',
  description: '接受 { topic: string }，返回结构化摘要。支持中英双语。',
  inputSchema:  { type: 'object', properties: { topic: { type: 'string' } }, required: ['topic'] },
  outputSchema: { type: 'object', properties: { summary: { type: 'string' } } },
  createAgent: () => new MyAgent(),   // 每次调用 new 隔离副本，原 Agent 不感知
}))

await node.publishCapabilities()   // 注册到 DHT，全网可发现

wrapAgent 每次收到任务都会 new MyAgent()，调用 run(input) 拿结果。原 Agent 只作模板，从不被外部直接调用。

客户端：让你的 Agent 向全网派发任务

import { AgentNode, DelegateToNetworkCapability } from 'blockchain-multi-agent'

const node = await AgentNode.create({ port: 0 })
const delegateTool = new DelegateToNetworkCapability(node)

// 对框架来说，这就是一个普通 tool
openClawAgent.addTool(delegateTool)

// 框架内部调用（对框架透明）：
const output = await delegateTool.execute({
  query: 'research and summarize a topic',   // 自然语言描述所需能力
  input: { topic: '量子计算的最新进展' },
  peerAddr: '/ip4/...',                      // 或用 capabilityId 走 DHT 发现
})
// output: { result: {...}, summary: '...' }

execute() 内部自动完成 发现 → 握手 → 派任务 → 拿结果 → 声誉打分，框架侧零感知。

从已有 OpenAI / Anthropic 工具一键转换

import { wrapAgent, fromOpenAITool, fromAnthropicTool } from 'blockchain-multi-agent'

// OpenAI function calling 格式
const meta = fromOpenAITool({
  type: 'function',
  function: { name: 'get_weather', description: 'Get current weather', parameters: {...} }
})
node.registerCapability(wrapAgent({ ...meta, createAgent: () => new WeatherAgent() }))

// Anthropic tool_use 格式
const meta2 = fromAnthropicTool({
  name: 'search_web', description: 'Search the web', input_schema: {...}
})
node.registerCapability(wrapAgent({ ...meta2, createAgent: () => new SearchAgent() }))

测试

# 单元测试
npm test                            # 全部（similarity / reputation / discovery / registry / sandbox / openclaw）

# 自动化 E2E（无需手动启动服务端）
npm run e2e:multi                   # happy-path + sandbox-isolation

# 手动 E2E（先启动服务端，再分别跑客户端）
npm run e2e:service
PEER_ADDR="<地址>" npm run e2e:basic
PEER_ADDR="<地址>" npm run e2e:streaming
npm run e2e:discovery
PEER_ADDR="<地址>" npm run e2e:failure

详见 TESTING.md。

沙箱隔离：安全执行外来代码

import { AgentNode, wrapAgent } from 'blockchain-multi-agent'

node.registerCapability(wrapAgent({
  id: 'sandboxed-agent',
  shortDescription: 'Run in process sandbox',
  description: '...',
  inputSchema: { type: 'object', properties: { text: { type: 'string' } } },
  createAgent: () => new MyAgent(),
  sandbox: {
    level: 'process',              // L1 worktree | L2 process | L3 container
    timeout: 10000,
    workerModule: './worker.ts',   // 子进程 import() 此模块实现真隔离
  },
  toolPolicy: {
    allow: ['web_search', 'tts'],  // 白名单
    deny: ['bash', 'write'],       // 黑名单
  },
}))

三级隔离：L1 Git Worktree（文件隔离）→ L2 Process（进程隔离 + workerModule）→ L3 Container（Docker，桩）。

OpenClaw 适配器：双向工具转换

import {
  openClawToolToCapability,
  toOpenClawTool,
  wrapOpenClawAgent,
  openClawToolsToCapabilities,
} from 'blockchain-multi-agent'

// OpenClaw 工具 → P2P 能力（单个 / 批量）
const cap = openClawToolToCapability(myOpenClawTool)
const caps = openClawToolsToCapabilities(allTools)  // 自动过滤内部工具

// P2P 能力 → OpenClaw 工具（反向注入）
const tool = toOpenClawTool(remoteCapability)
openClawAgent.addTool(tool)

// 整个 OpenClaw Agent 作为单个 P2P 能力
const agentCap = wrapOpenClawAgent({
  id: 'claw-bot',
  shortDescription: 'Full assistant',
  description: '...',
  runAgent: async (input) => clawAgent.run(input),
  externalTools: ['web_search', 'tts'],
})

不依赖 openclaw 包，通过兼容类型接口实现零依赖双向转换。

工作原理

渐进式三阶段握手

派任务前，客户端自动走三阶段协议，避免无效连接：

Stage 0  声誉守卫    查本地黑名单，毫秒级，零网络开销
Stage 1  向量探测    先校验 modelVersion 一致，再算余弦相似度，< 阈值立即放弃
Stage 2  能力协商    拉取完整 CapabilityDescriptor，确认 Schema 兼容
执行      发任务拿结果，记录成功/失败到声誉系统

所有 Stage 1 消息都携带 modelVersion 字段（如 bge-m3-v1），版本不一致直接拒绝——向量空间不同，余弦相似度没有意义。

语义向量匹配

Stage 1 使用 bge-m3（1024 维，中英双语，MTEB 小模型最强）做语义匹配，而非关键词搜索。

• 客户端描述需求，服务端描述能力，跨语义也能匹配
• 模型部署在公共 Embedding 服务器（222.187.130.67:9002），所有节点共用同一向量空间，余弦相似度才有意义
• 向量版本化管理，模型升级时全网统一切换，节点自动重新注册

NAT 穿透（三层兜底）

第一层  AutoNAT      检测自身是否公网可达
第二层  DCUtR        打洞，尝试建立直连
第三层  Circuit Relay 走 Bootstrap 中继，NAT 后节点也能参与

网络基建

| 服务 | 地址 | 用途 | |------|------|------| | Bootstrap TCP | 222.187.130.67:9000 | DHT 入网点 + Circuit Relay | | Bootstrap WS | 222.187.130.67:9001 | 浏览器 / WebSocket 节点入网 | | Embed 服务 | 222.187.130.67:9002 | bge-m3 统一向量化 |

这三个服务构成协议基建，所有节点无需手动配置，启动时自动连接。

目录结构

src/
├── index.ts                  # AgentNode 高层封装，统一入口
├── agent/                    # 能力管理 + 消息路由
├── network/                  # libp2p、DHT、embedding、声誉、签名
├── protocol/                 # 三阶段握手 + 消息类型
├── interop/                  # 互操作适配器
│   ├── delegate.ts           #   DelegateToNetworkCapability（客户端）
│   ├── wrap-agent.ts         #   wrapAgent()（服务端工厂）+ 沙箱执行
│   ├── schema.ts             #   OpenAI / Anthropic → JSON Schema
│   └── openclaw.ts           #   OpenClaw AgentTool ↔ Capability
├── sandbox/                  # 沙箱隔离
│   ├── worktree.ts           #   L1 Git Worktree
│   ├── process.ts / worker.ts#   L2 Process + workerModule
│   ├── container.ts          #   L3 Docker（桩）
│   └── tool-filter.ts        #   工具策略 + 内外部分类
├── test-harness/             # E2E 测试基建（模板 + 控制面 + worker）
├── bootstrap.ts              # Bootstrap 基建节点
└── embed-server.ts           # Embedding 服务（bge-m3）
tests/
├── *.test.ts                 # 单元测试（similarity / reputation / discovery / registry / sandbox / openclaw）
└── e2e-multi/                # 自动化 E2E（orchestrator + scenarios）
examples/                     # 手动 E2E + 原始示例

自行部署 Bootstrap 节点

git clone https://github.com/YapengTeng/blockchain-multi-agent.git
cd blockchain-multi-agent && npm install

ANNOUNCE_IP=<你的公网IP> \
BOOTSTRAP_TCP_PORT=9000 \
BOOTSTRAP_WS_PORT=9001 \
npm run bootstrap

bootstrap-key.json 决定节点 peerId，请妥善备份，切勿提交 git。

路线图

| 阶段 | 内容 | 状态 | |------|------|------| | 基建 | Bootstrap DHT、bge-m3 Embed 服务、NAT 穿透 | ✅ | | 接入层 | wrapAgent + DelegateToNetworkCapability、Schema 转换 | ✅ | | 协议 | 三阶段握手、流式响应、声誉系统、hybrid 发现 | ✅ | | 沙箱 | L1 Worktree / L2 Process（workerModule）/ 工具策略 | ✅ | | 互操作 | OpenClaw 适配器、OpenAI/Anthropic Schema 转换 | ✅ | | 测试 | 6 组单元测试 + 自动化 E2E（happy-path + sandbox） | ✅ | | 经济层 | 结算模块、TEE 可信执行 | 规划中 | | 入口 | 轻客户端 App（Web / iOS / CLI）、Siri / Telegram 适配 | 规划中 |

技术栈

• libp2p v3 — Kademlia DHT、Noise 加密、yamux、Circuit Relay v2、AutoNAT、DCUtR
• bge-m3 via Transformers.js — 中英双语语义匹配
• TypeScript — 类型安全
• pm2 — 生产环境进程守护