# Soraecho + Maian OS 融合方案：升级为 Agent 专用区块链

**Date**: 2026-08-21  
**Status**: Draft（承接 Maian 工作，Soraecho 主导）  
**Author**: Soraecho Core Team（索籁）  
**背景**: Maian OS 团队转其他工作，Soraecho 全面承接融合任务  

---

## 1. 融合目标

将 **Soraecho ANP（通信层）** + **Maian OS（节点客户端）** 融合升级为：

```
Soraecho Agent Chain = 通信层（ANP）+ 结算层（新链）+ Maian OS（节点客户端）
```

**核心定位**：
- **Soraecho**：提供 Agent 通信网络 + 区块链结算层（主导）
- **Maian OS**：作为链节点客户端 + Human-Agent 运行时（融合进来）
- **Maian 资料**：已全部归档到 Soraecho 官网（`/downloads/maian-archive/`）

---

## 2. 技术栈整合

### 2.1 当前状态

| 组件 | 技术栈 | 状态 |
|------|--------|------|
| **Soraecho ANP** | Go + libp2p | ✅ v1.33 部署（3 节点） |
| **Maian OS** | Python + Flask | ✅ v1.4.0 归档 |
| **Maian Agent Factory** | Python (8877) | ✅ 已归档 |
| **Maian Unified Gateway** | Python (8888) | ✅ 已归档 |
| **Soraecho Agent Chain 方案** | Go + CometBFT | ✅ 方案已发布 |

### 2.2 融合架构

```
┌─────────────────────────────────────────────────────────┐
│ Layer 3: 生态应用层                                      │
│   Agent 市场 / Human-Agent 聊天 / 治理 / 预言机           │
│   Maian OS Web Dashboard (PWA) 作为前端                  │
├─────────────────────────────────────────────────────────┤
│ Layer 2: Soraecho Agent Chain（新，Go）                  │
│   结算账本 / DID 注册 / 信誉锚定 / 争议仲裁               │
│   共识: PoA（Maian OS 节点 = 验证者）                    │
│   Maian OS 作为验证者节点 + Human-Agent 运行时            │
├─────────────────────────────────────────────────────────┤
│ Layer 1: Soraecho ANP（现有，Go）                        │
│   A2A 通信 / DHT 发现 / E2E 加密 / Chat / Presence      │
│   Maian OS 作为 Agent 节点（通过 Gateway 对接）           │
└─────────────────────────────────────────────────────────┘
```

### 2.3 节点角色定义

| 节点类型 | 软件 | 角色 |
|---------|------|------|
| **Chain 验证者** | Soraecho Agent Chain（Go） | 出块 / 验证交易 |
| **ANP Agent 节点** | Soraecho ANP（Go） | A2A 通信 / 发现 |
| **Maian OS 节点** | Maian OS（Python） | Human-Agent 运行时 / 链验证者 |
| **融合节点** | Soraecho ANP + Maian OS | 同时运行 ANP + Maian OS |

**融合方式**：Maian OS 通过 `Unified Gateway (8888)` 对接 Soraecho ANP，同时作为 Chain 验证者。

---

## 3. 融合实施路线图

### Phase 1：资料整合 + 环境准备（本周）

**目标**：Maian 资料完全融入 Soraecho 项目，准备开发环境

- [x] Maian 资料复制到 Soraecho 官网（`/downloads/maian-archive/`）
- [x] 验证归档内容（14 模块 + 4 文档 + 规范）
- [ ] 将 Maian 核心模块整合到 Soraecho 仓库（`/maian/` 子目录）
- [ ] 写 `FUSION-ROADMAP.md`（融合专用路线图）
- [ ] 更新 `AGENT_CHAIN_DESIGN.md`（加入 Maian 融合细节）

**交付**：Maian 资料完全整合，融合路线图发布

### Phase 2：Maian OS 作为 ANP Agent 节点（1-2 周）

**目标**：Maian OS 作为 Agent 注册到 Soraecho ANP 网络

- [ ] 启动 Soraecho 3 节点（v1.33）
- [ ] 在 Maian 服务器部署 Soraecho ANP（作为 Agent 节点）
- [ ] Maian `Unified Gateway` 对接 Soraecho ANP（`/api/v1/agentcard/register`）
- [ ] 验证 Maian Agent 可被 discover（`/api/v1/agentcard/discover`）
- [ ] 测试 A2A 调用：Soraecho Agent → Maian Agent

**交付**：Maian OS 作为 Agent 加入 Soraecho 网络

### Phase 3：Human-Agent 融合通信（2 周）

**目标**：Human-Agent 协议在 Soraecho + Maian 上完整实现

- [ ] Soraecho 侧：已完成（v1.31，chat.message + presence）
- [ ] Maian 侧：升级 `maian_human_agent.py` 为协议兼容版本
  - 实现 `chat.message` 发送/接收（P0）
  - 实现 Presence 状态更新（P0）
  - Human DID 体系集成（`did:anp:human:*`）
- [ ] 端到端测试：Human（Maian）→ Agent（Soraecho）聊天
- [ ] E2E 加密测试（ChaCha20-Poly1305）

**交付**：Human-Agent 融合通信演示

### Phase 4：Agent Chain Phase A（1-2 周）

**目标**：中心化账本，结算 API 可用

- [ ] 基于现有 `SettlementQueue` 实现账本
- [ ] 余额管理 + 转账端点
- [ ] A2A 调用 → 自动生成 `SettlementProof` → 提交到账本
- [ ] Maian OS 作为第一个结算用户（测试）

**交付**：结算 API 可用，Maian OS 可调用

### Phase 5：Agent Chain Phase B（3-4 周）

**目标**：PoA 多节点链，Maian OS 作为验证者

- [ ] 技术选型确认（CometBFT vs 轻量 PoA）
- [ ] 实现 PoA 共识
- [ ] Maian OS 节点注册为验证者（DID 绑定）
- [ ] `SettlementProof` 作为交易载荷上链
- [ ] 区块浏览器（简单 Web UI）

**交付**：PoA 测试网，Maian OS 验证者加入

### Phase 6：生态功能（4-6 周）

**目标**：Agent 原生功能 + 代币经济

- [ ] SORAE 代币部署（10 亿总量）
- [ ] DID 注册上链
- [ ] 信誉锚定
- [ ] 争议仲裁
- [ ] Agent 市场（链上）
- [ ] Maian OS 前端集成（PWA）

**交付**：功能完整的 Agent Chain 测试网

---

## 4. 关键融合点

### 4.1 Maian OS 对接 Soraecho ANP

**当前 Maian 架构**：
```
Maian Agent Factory (8877) → Unified Gateway (8888) → Soraecho ANP (4002)
```

**对接方式**：
1. Maian `Unified Gateway` 调用 Soraecho ANP 的 `POST /api/v1/agentcard/register` 注册自己
2. Maian Agent 信息映射到 `AgentCard` 结构（已有 `maian_did_auth.py` 处理 DID）
3. A2A 调用通过 `POST /api/v1/a2a/stream` 路由到 Maian Agent

**需要修改的 Maian 模块**：
- `hermes_adapter.py`（Unified Gateway）：增加 Soraecho ANP 对接
- `maian_did_auth.py`：DID 格式兼容（`did:anp:*`）
- `maian_human_agent.py`：升级为协议兼容版本

### 4.2 结算融合

**流程**：
```
Maian Agent 调用 Soraecho Agent
    ↓
Soraecho ANP 生成 SettlementProof
    ↓
提交到 Agent Chain（Phase A 中心化账本）
    ↓
Maian OS 查询结算结果（通过 API）
```

**Maian 侧需要**：
- 调用 Soraecho 结算 API（`POST /api/v1/settlement/proof`）
- 查询结算状态（`GET /api/v1/settlement/pending`）

### 4.3 Human-Agent 融合

**协议层**（Soraecho 已完成）：
- `AgentCard.type = "human"`
- `chat.message` 端点
- `presence` 端点
- E2E 加密框架

**Maian 侧需要**（P0）：
- 升级 `maian_human_agent.py` 实现 `chat.message` 协议
- 实现 `maian_human_runtime.py` 作为 HumanAgent 运行时
- 对接 Soraecho `presence` 端点

---

## 5. 开发环境规划

### 5.1 代码仓库结构

```
soraecho/                    # 主仓库（Go）
├── cmd/anpd/                # ANP 节点
├── pkg/a2a/                 # A2A 服务
├── pkg/chain/               # Agent Chain（新）
├── maian/                   # Maian OS 整合（Python）
│   ├── core/                # Maian 核心模块（从归档复制）
│   ├── gateway/             # Unified Gateway 对接 ANP
│   └── human/               # Human-Agent 运行时
├── docs/
│   ├── AGENT_CHAIN_DESIGN.md
│   ├── FUSION-ROADMAP.md    # 融合路线图（新）
│   └── maian-archive/       # Maian 资料（已复制）
└── scripts/
    ├── deploy-maian.sh      # 部署 Maian 到 ANP 网络
    └── test-fusion.sh       # 融合测试脚本
```

### 5.2 服务器规划

| 服务器 | 用途 | 软件 |
|--------|------|------|
| **129.226.217.205**（主节点） | Soraecho ANP + Agent Chain + 官网 | Go + Nginx |
| **129.226.217.205:4010**（Boot2） | Soraecho ANP Boot2 | Go |
| **129.226.202.231**（Boot3） | Soraecho ANP Boot3 | Go |
| **43.156.25.118**（Maian 官网） | Maian OS 节点 + 官网 | Python + Nginx |
| **本地**（开发） | 开发测试 | Go + Python |

---

## 6. 下一步行动（立即执行）

### 6.1 今天（资料整合完成）

- [x] Maian 资料复制到 Soraecho 官网
- [x] 验证归档内容
- [ ] 写 `FUSION-ROADMAP.md`（融合路线图）
- [ ] 更新 `memory`：记录 Maian 融合任务承接

### 6.2 本周（Phase 1 完成）

- [ ] 创建 `soraecho/maian/` 目录，整合 Maian 核心模块
- [ ] 写融合部署脚本（`deploy-maian.sh`）
- [ ] 启动 Maian OS 作为 Soraecho Agent 节点测试

### 6.3 下周（Phase 2 开始）

- [ ] Maian OS 注册到 Soraecho ANP
- [ ] 测试 A2A 跨平台调用
- [ ] 开始 Agent Chain Phase A 开发

---

## 7. 风险与对策

| 风险 | 概率 | 影响 | 对策 |
|------|------|------|------|
| **Maian 代码 Python，Soraecho Go，整合复杂** | 高 | 中 | 通过 Gateway 对接，不直接整合代码 |
| **Maian 团队离开，知识流失** | 中 | 高 | 资料已完全归档，代码自包含 |
| **Chain 开发量大** | 中 | 中 | 用 CometBFT，不自研共识 |
| **时间线延长** | 中 | 中 | 分阶段交付，每阶段可验证 |

---

## 8. 总结

**当前状态**：
- ✅ Maian 资料已完全复制到 Soraecho 官网
- ✅ Soraecho ANP v1.33 稳定运行（3 节点）
- ✅ Agent Chain 方案已发布
- ✅ Human-Agent 协议 Soraecho 侧完成

**下一步**：
1. 写 `FUSION-ROADMAP.md` 融合路线图
2. 整合 Maian 模块到 Soraecho 仓库
3. 启动 Phase 2：Maian OS 作为 Agent 节点加入 ANP

**目标**：将 Soraecho + Maian OS 融合升级为独立的 Agent 专用区块链。

---

**End of Fusion Plan v1.0**