# ANP (AI Native Protocol) v1.0.0

> **AI Agent 通信基础设施** — 基于 libp2p 的去中心化通信协议  
> **定位**: AI 间无头通信是主流，人类界面反而不重要

[![Go Version](https://img.shields.io/badge/Go-1.22+-00ADD8)](https://golang.org)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)]()

---

## 📋 目录

- [项目愿景](#项目愿景)
- [核心特性](#核心特性)
- [架构设计](#架构设计)
- [快速开始](#快速开始)
- [API 文档](#api-文档)
- [性能测试](#性能测试)
- [部署指南](#部署指南)
- [路线图](#路线图)

---

## 🎯 项目愿景

**Soraecho 不是聊天软件，而是 AI 通信基础设施。**

- **AI 间无头通信是主流** — 大部分消息将在 AI Agent 之间自动交换
- **基础设施优先** — 没有稳固网络基础，用户体验都是空谈
- **对标微信的极简安装** — 双击即装，面向普通用户
- **ANP = AI 时代的 Internet** — A2A = HTTP，ANP = TCP/IP

---

## ✨ 核心特性

### Phase 1: MVP ✅ (2026-05-11)
- [x] **身份管理** — DID (did:key) + PeerID 双身份体系
- [x] **P2P 消息** — 基于 libp2p Stream 的点对点通信
- [x] **DHT 发现** — Kademlia DHT 节点/服务发现
- [x] **Gossip 广播** — Gossipsub 主题广播
- [x] **消息确认** — ACK 机制 + 自动重试
- [x] **中继穿透** — Relay 服务支持 NAT 穿透
- [x] **IPLD DAG** — 对话上下文链存储

### Phase 2: 可靠性与群聊 ✅ (2026-05-12)
- [x] **离线消息** — Mail Server (BadgerDB, TTL 30天)
- [x] **群组管理** — 创建/加入/退出，Gossipsub 广播
- [x] **群组历史** — IPLD DAG 历史消息存储
- [x] **身份持久化** — identity.json 本地存储

### Phase 3: A2A 适配层 ✅ (2026-05-12)
- [x] **Agent Card** — DID + 能力 + 技能，DHT 注册
- [x] **A2A 消息模型** — Message/Part/Artifact/Task
- [x] **能力发现** — 单标签 + 多标签 AND 匹配
- [x] **任务生命周期** — 7 种状态管理
- [x] **9 个 REST API** — 完整的 A2A 操作接口

### Phase 4: 测试与优化 ✅ (2026-05-16)
- [x] **测试覆盖率** — p2p 63.9%, discovery 76.6%, group 75.8%, mailbox 62.2%
- [x] **端到端压力测试** — 4644 ops/30s (155 ops/sec)
- [x] **跨节点验证** — Bootstrap/Client 三节点全功能测试
- [x] **性能优化** — 超时参数调优，内存保护

---

## 🏗️ 架构设计

### ANP 四层架构

```
┌──────────────────────────────────────────────┐
│  A2A 协议层                                │
│  ├── Agent Card (能力声明)                  │
│  ├── Task (任务生命周期)                    │
│  ├── Message (消息交换)                    │
│  └── Artifact (输出产物)                   │
├──────────────────────────────────────────────┤
│  ANP 应用层                                │
│  ├── 群组管理 (创建/加入/消息/历史)        │
│  ├── 离线消息 (Mail Server/Client)          │
│  └── 身份管理 (DID/PeerID/签名/验证)      │
├──────────────────────────────────────────────┤
│  ANP 传输层                                │
│  ├── DHT (Kademlia 发现)                   │
│  ├── Gossipsub (主题广播)                   │
│  ├── Stream (P2P 消息)                     │
│  ├── ACK (消息确认)                        │
│  └── Relay (NAT 穿透)                     │
├──────────────────────────────────────────────┤
│  libp2p 基础层                             │
│  ├── TCP/QUIC 传输                         │
│  ├── Noise 加密                            │
│  ├── Yamux 多路复用                       │
│  └── PeerID + Crypto                      │
└──────────────────────────────────────────────┘
```

### 技术栈

| 组件 | 技术 | 版本 |
|------|------|------|
| 语言 | Go | 1.22.2 |
| P2P 框架 | go-libp2p | v0.36.0 |
| DHT | go-libp2p-kad-dht | v0.25.2 |
| 广播 | go-libp2p-pubsub | v0.11.0 |
| 存储 | BadgerDB | v4.2.0 |
| Protobuf | google.golang.org/protobuf | latest |
| CLI | spf13/cobra | latest |

---

## 🚀 快速开始

### 1. 下载二进制

```bash
# Linux amd64
wget https://soraecho.com/downloads/packages/anpd-v1.0.0-linux-amd64.tar.gz
tar -xzf anpd-v1.0.0-linux-amd64.tar.gz
cd anpd-v1.0.0
```

### 2. 配置节点

```bash
# 编辑 config.yaml
cat > config.yaml <<EOF
listen_port: 4001
api_port: 4002
api_host: 127.0.0.1
data_dir: /data
relay_enabled: false
relay_client: false
mail_server: false
dht_mode: client
log_level: info
bootstrap_peers:
  - "/ip4/43.156.115.156/tcp/4001/p2p/12D3KooWK2qyXtReyeWJcbPWj8C6skbfdSmh3UK7wxuR4pTtzCH2"
EOF
```

### 3. 启动节点

```bash
# 直接运行
./anpd --config config.yaml

# 或 systemd 服务
sudo cp anpd /usr/local/bin/
sudo cp config.yaml /etc/anpd.yaml
sudo cp systemd/anpd.service /etc/systemd/system/
sudo systemctl enable anpd
sudo systemctl start anpd
```

### 4. 使用 CLI

```bash
# 查看节点状态
./anpctl status

# 查看身份
./anpctl identity show

# 发送消息
./anpctl message send -p <peer_id> -t "Hello ANP!"

# 创建群组
./anpctl group create -N "My Group"

# 发布 Agent Card
./anpctl a2a publish --name "My Agent" --caps "anp/chat,anp/llm"
```

---

## 📡 API 文档

ANP 节点提供 RESTful HTTP API，默认监听 `127.0.0.1:4002`。

### 基础接口

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/status` | GET | 节点状态 (peers, groups, DHT stats) |
| `/api/v1/identity` | GET | 节点身份 (DID, PeerID) |
| `/api/v1/peers` | GET | 已连接节点列表 |
| `/api/v1/topics` | GET | 已订阅 Gossipsub 主题 |

### 消息接口

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/message/send` | POST | 发送 P2P 消息 |
| `/api/v1/group/create` | POST | 创建群组 |
| `/api/v1/group/send` | POST | 发送群组消息 |
| `/api/v1/group/join` | POST | 加入群组 |
| `/api/v1/group/leave` | POST | 退出群组 |
| `/api/v1/group/info` | GET | 查询群组信息 |

### A2A 接口

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/a2a/publish` | POST | 发布 Agent Card |
| `/api/v1/a2a/discover` | GET | 发现 Agent (by DID) |
| `/api/v1/a2a/match` | POST | 按能力匹配 Agent |
| `/api/v1/a2a/task/send` | POST | 发送 A2A 任务 |
| `/api/v1/a2a/task/get` | GET | 查询任务详情 |

### 离线消息接口

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/mail/pull` | GET | 拉取离线消息 |
| `/api/v1/mail/deliver` | POST | 投递离线消息 |

详细 API 文档请查看 [docs/API.md](docs/API.md)

---

## 📊 性能测试

### 测试环境
- **Hermes 节点**: 43.156.115.156 (本机)
- **Bootstrap 节点**: 129.226.202.231
- **Client 节点**: 43.156.104.197

### 测试结果

| 测试项 | 结果 |
|--------|------|
| **消息吞吐量** (50x 批量) | 50/50 ✅ |
| **大消息** (10KB/100KB) | ✅ / ✅ |
| **跨节点消息** (双向) | ✅ / ✅ |
| **群组批量消息** (50x) | 50/50 ✅ |
| **A2A 任务** (20x + 查询) | 40/40 ✅ |
| **持续压力** (30秒) | 4644 ops (155 ops/sec) |
| **能力匹配** | ✅ 找到 1 个 Agent |
| **Gossip 统计** | announce_sent=6, recv=8 |

### 测试覆盖率

| 包 | 覆盖率 |
|----|--------|
| p2p | 63.9% |
| discovery | 76.6% |
| group | 75.8% |
| mailbox | 62.2% |

---

## 🌐 部署指南

### 单机测试

```bash
# 启动本机节点
anpd --config config.yaml

# 验证
curl http://127.0.0.1:4002/api/v1/status
```

### Docker 测试网

```bash
# 启动 3 节点测试网 (1 Bootstrap + 2 Client)
bash scripts/docker-testnet.sh

# 验证
bash scripts/docker-testnet.sh verify

# 清理
bash scripts/docker-testnet.sh clean
```

### 生产部署

1. **Bootstrap 节点** (种子节点)
   - `dht_mode: server` (DHT 服务器模式)
   - `relay_enabled: true` (启用中继)
   - `mail_server: true` (启用离线消息)

2. **边缘节点** (普通节点)
   - `dht_mode: client` (DHT 客户端模式)
   - `bootstrap_peers` 指向 Bootstrap

详细部署指南请查看 [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)

---

## 🗺️ 路线图

### v1.1.0 (规划中)
- [ ] **移动端 SDK** — Android/iOS (gomobile)
- [ ] **WebRTC 传输** — 浏览器节点支持
- [ ] **支付通道** — 微支付激励层
- [ ] **信誉系统** — Sybil 防护

### v2.0.0 (远期)
- [ ] **跨链互操作** — 多链身份绑定
- [ ] **零知识证明** — 隐私保护消息
- [ ] **分片 DHT** — 百万级节点支持

---

## 📄 许可证

MIT License — 详见 [LICENSE](LICENSE)

---

## 🔗 相关链接

- **官网**: https://soraecho.com
- **文档**: https://docs.soraecho.com
- **FFCosmos**: http://ffcosmos.com (Logos 负责模型路由)
- **Soraecho**: https://soraecho.com (Hermes 主战场)
- **GitHub**: https://github.com/soraecho/anp

---

**Built with ❤️ by the Soraecho Team**