Skip to content

Latest commit

 

History

History
204 lines (158 loc) · 9.21 KB

README_zh.md

File metadata and controls

204 lines (158 loc) · 9.21 KB

English | 中文

peerclaw-agent

License

PeerClaw 身份与信任平台的 P2P Agent SDK。让 AI Agent 通过 WebRTC DataChannel 直连通信，以 Nostr relay 作为去中心化兜底，内置 TOFU 信任模型、消息签名验证和端到端加密的 P2P 文件传输。

核心特性

  • WebRTC 直连 — Agent 之间通过 DataChannel 建立低延迟 P2P 通道
  • Nostr 完整传输 — 基于 fiatjaf.com/nostr 库，NIP-44 加密，多 relay 支持与自动故障切换
  • Transport Selector — 自动传输选择：WebRTC 优先，失败自动降级 Nostr，恢复后自动升级
  • 端到端加密 — X25519 ECDH 密钥交换 + XChaCha20-Poly1305 加密，信令阶段建立加密会话
  • TOFU 信任 — 五级信任模型（Unknown / TOFU / Verified / Blocked / Pinned），支持 CLI 管理
  • 消息签名 — 基于 Ed25519 的消息级签名验证，确保消息完整性和来源可信
  • 消息验证管线 — 集成签名验证、时间戳新鲜度（±2 分钟）、基于 nonce 的重放防护、载荷大小限制
  • P2P 白名单（默认拒绝） — 基于 TrustStore 的联系人管理：AddContact / RemoveContact / BlockAgent，连接门控在分配 WebRTC 资源之前拒绝未授权 offer
  • 连接质量监控 — RTT、丢包率、吞吐统计，连接降级自动通知
  • P2P 文件传输 — 通过专用 WebRTC DataChannel 端到端加密大文件传输，流水线推送、背压控制、Challenge-Response 双向鉴权、断点续传、Nostr relay 兜底
  • 自动发现 — 通过 peerclaw-server 注册和发现其他 Agent

架构

┌───────────────────────────────────────┐
│              Agent (顶层 API)          │
│                                       │
│  ┌───────────┐  ┌──────────────────┐  │
│  │ Discovery │  │    Signaling     │  │
│  │  Client   │  │     Client       │  │
│  └───────────┘  └──────────────────┘  │
│  ┌───────────┐  ┌──────────────────┐  │
│  │   Peer    │  │    Security      │  │
│  │  Manager  │  │ Trust+Message+   │  │
│  │           │  │    Sandbox       │  │
│  └───────────┘  └──────────────────┘  │
│  ┌─────────────────────────────────┐  │
│  │     Transport Selector         │  │
│  │  ┌────────┐    ┌────────────┐  │  │
│  │  │ WebRTC │◄──►│Nostr relay │  │  │
│  │  │(primary)│   │ (fallback) │  │  │
│  │  └────────┘    └────────────┘  │  │
│  │     ConnectionMonitor          │  │
│  └─────────────────────────────────┘  │
└───────────────────────────────────────┘

多平台支持

Agent SDK 定义了 platform.Adapter 接口，让 PeerClaw Agent 可以在外部 Agent 平台上运行。提供 4 个官方平台插件：

各插件的配置和使用详情请参阅对应 README。

快速开始

Echo Agent 完整示例

package main

import (
    "context"
    "log/slog"
    "os"
    "os/signal"
    "syscall"

    "github.com/peerclaw/peerclaw-core/envelope"
    "github.com/peerclaw/peerclaw-core/protocol"
    agent "github.com/peerclaw/peerclaw-agent"
)

func main() {
    logger := slog.New(slog.NewTextHandler(os.Stdout, nil))

    a, err := agent.New(agent.Options{
        Name:         "echo-agent",
        ServerURL:    "http://localhost:8080",
        Capabilities: []string{"echo"},
        Protocols:    []string{"a2a"},
        KeypairPath:  "echo.key",       // 自动生成并持久化密钥
        Logger:       logger,
    })
    if err != nil {
        logger.Error("create agent failed", "error", err)
        os.Exit(1)
    }

    // 收到消息后原样回复
    a.OnMessage(func(ctx context.Context, env *envelope.Envelope) {
        reply := envelope.New(a.ID(), env.Source, protocol.ProtocolA2A, env.Payload)
        reply.MessageType = envelope.MessageTypeResponse
        a.Send(ctx, reply)
    })

    ctx := context.Background()
    a.Start(ctx)
    defer a.Stop(ctx)

    logger.Info("echo agent running", "id", a.ID(), "pubkey", a.PublicKey())

    sig := make(chan os.Signal, 1)
    signal.Notify(sig, syscall.SIGINT, syscall.SIGTERM)
    <-sig
}

发现其他 Agent

results, _ := a.Discover(ctx, []string{"search"})
for _, r := range results {
    fmt.Printf("Found: %s (pubkey: %s)\n", r.Name, r.PublicKey)
}

API 参考

方法 说明
agent.New(opts) 创建 Agent 实例
agent.Start(ctx) 注册到平台并开始接受连接
agent.Stop(ctx) 注销并关闭所有连接
agent.Send(ctx, env) 发送签名 + 加密消息到对端
agent.OnMessage(handler) 注册消息处理回调
agent.Discover(ctx, caps) 按能力发现 Agent
agent.EstablishSession(peerID, peerX25519) 建立 E2E 加密会话
agent.SetBridgeHandler(handler) 注册协议桥接消息处理回调
agent.X25519PublicKeyString() 获取 X25519 公钥（hex）
agent.ID() 获取注册后的 Agent ID
agent.PublicKey() 获取 Base64 编码的公钥
agent.AddContact(agentID) 将 peer 加入白名单，允许消息和连接（TrustVerified）
agent.RemoveContact(agentID) 从白名单移除 peer
agent.BlockAgent(agentID) 拉黑 peer — 所有消息和连接被拒绝
agent.ListContacts() 列出所有信任条目
agent.SendFile(ctx, peerID, path) 向 peer 发送文件，端到端加密 P2P 传输
agent.ListTransfers() 列出活跃和最近的文件传输
agent.GetTransfer(fileID) 获取特定文件传输状态
agent.CancelTransfer(fileID) 取消进行中的文件传输
agent.OnConnectionRequest(handler) 注册未知 peer 连接请求的回调

Options 配置

字段 说明
Name Agent 显示名称
ServerURL peerclaw-server 地址
Capabilities 能力列表（如 "chat", "search"）
Protocols 支持的协议（如 "a2a", "mcp"）
KeypairPath 密钥文件路径（为空则每次生成新密钥）
TrustStorePath 信任存储文件路径
NostrRelays Nostr relay URL 列表（如 "wss://relay.damus.io"）
FileTransferDir 接收文件存放目录（默认当前目录）
ResumeStatePath 文件传输断点续传状态持久化路径
Logger 结构化日志器

安全模型

PeerClaw 采用多层安全架构：

1. 连接级 — TOFU (Trust-On-First-Use)

首次连接时记录对端公钥指纹到本地 Trust Store。后续连接自动校验公钥是否一致，检测中间人攻击。

2. 消息级 — Ed25519 签名

每条消息使用发送方私钥签名。接收方使用发送方公钥验证签名，确保消息未被篡改且来源可信。

3. 传输级 — 端到端加密

信令握手阶段交换 X25519 公钥，通过 ECDH 计算共享密钥，使用 XChaCha20-Poly1305 加密消息 Payload。Nostr 传输额外使用 NIP-44 格式封装。

4. 执行级 — 沙箱

对外部 Agent 的请求实施权限约束和资源限制，防止恶意操作。

5. P2P 通信 — 白名单 + 消息验证

默认拒绝的联系人管理：Agent 必须通过 AddContact() 加入白名单后才能连接或交换消息。每条入站消息都经过 MessageValidator 验证（签名、时间戳新鲜度 ±2 分钟、nonce 重放检查、1MB 大小限制）。ConnectionGate 在分配任何资源之前拒绝未授权的 WebRTC offer。未知 peer 触发 OnConnectionRequest 回调，让 owner 实时审批或拒绝。

Trust CLI

peerclaw-trust 命令行工具管理信任条目：

peerclaw-trust list -store trust.json          # 列出所有信任条目
peerclaw-trust verify -store trust.json -id <agent-id>  # 升级为 Verified
peerclaw-trust pin -store trust.json -id <agent-id>     # 固定信任（Pinned）
peerclaw-trust revoke -store trust.json -id <agent-id>  # 撤销信任
peerclaw-trust export -store trust.json -out backup.json # 导出
peerclaw-trust import -store trust.json -in backup.json  # 导入

许可证

基于 Apache License 2.0 开源。

Copyright 2025 PeerClaw Contributors.