@f2a/network 0.1.2

package/docs/F2A-PROTOCOL.md

@@ -0,0 +1,61 @@
+# F2A Protocol Specification
+
+F2A (Federated Agent Architecture) Protocol 是 Agent 之间的通用通信协议。
+
+## 版本
+
+当前版本: **1.0.0**
+
+## 消息格式
+
+```typescript
+interface F2AMessage {
+  version: "1.0";
+  type: MessageType;
+  from: string;
+  to?: string;
+  timestamp: number;
+  payload: unknown;
+  signature?: string;
+}
+```
+
+## 消息类型
+
+- `discover` - 发现 Agents
+- `announce` - 广播任务（认领模式）
+- `claim` - 认领任务
+- `delegate` - 明确委托
+- `accept` / `reject` - 接受/拒绝委托
+- `response` - 任务响应
+- `review` - 评审提交
+- `heartbeat` - 心跳
+
+## 委托模式
+
+### 1. 直接委托
+
+```
+Agent A --delegate--> Agent B --response--> Agent A
+```
+
+### 2. 广播并行
+
+```
+Agent A --delegate--> All Agents --response--> Agent A
+```
+
+### 3. 广播认领
+
+```
+Agent A --announce--> All Agents
+Agent B --claim--> Agent A
+Agent A --delegate--> Agent B --response--> Agent A
+```
+
+## 安全机制
+
+- 白名单/黑名单
+- 信誉系统
+- 评审团（高价值任务）
+- 消息签名验证

package/docs/MOBILE_BOOTSTRAP_DESIGN.md

@@ -0,0 +1,126 @@
+# 手机作为移动引导节点设计提案
+
+## 背景
+
+当前 F2A 的 P2P 网络局限于单一局域网，无法实现跨网络（如家里和公司）的 Agent 发现和通信。
+
+## 设计目标
+
+让手机作为**移动引导节点（Mobile Bootstrap Node）**，连接不同网络的 Agent：
+
+```
+场景1: 家里
+┌─────────────────────────┐
+│  家里的 WiFi 网络        │
+│  ┌─────┐ ┌─────┐ ┌─────┐│
+│  │Agent│ │Agent│ │Agent││
+│  │  1  │ │  2  │ │  3  ││
+│  └──┬──┘ └──┬──┘ └──┬──┘│
+│     └────────┼───────┘   │
+│              ▼            │
+│         ┌─────────┐       │
+│         │  手机   │◄──────┐
+│         │引导节点 │       │
+│         └─────────┘       │
+└─────────────────────────┘
+
+场景2: 公司
+┌─────────────────────────┐
+│  公司的 WiFi 网络        │
+│  ┌─────┐ ┌─────┐        │
+│  │Agent│ │Agent│        │
+│  │  4  │ │  5  │        │
+│  └──┬──┘ └──┬──┘        │
+│     └────────┼───────┐   │
+│              ▼       │   │
+│         ┌─────────┐  │   │
+│         │  手机   │◄─┘   │
+│         │引导节点 │      │
+│         └────┬────┘      │
+└──────────────┼──────────┘
+               │
+               ▼
+        家里的3个Agent 和 公司的2个Agent
+        通过手机节点串联
+```
+
+## 核心机制
+
+### 1. 手机作为 DHT 节点
+
+- 手机运行 F2A 节点，启用 DHT 服务器模式
+- 在家时：发现并记录家里的 Agent 到 DHT
+- 在公司时：发现并记录公司的 Agent 到 DHT
+- DHT 路由表自动同步，实现跨网络发现
+
+### 2. NAT 穿透
+
+- 启用 libp2p 的 autoNAT 和 upnpNAT 服务
+- 自动检测 NAT 类型，尝试端口映射
+- 为跨网络直连提供技术支持
+
+### 3. 发现流程
+
+```
+Agent 4 (公司) 想联系 Agent 1 (家里)
+
+1. Agent 4 通过 DHT 查询 Agent 1
+2. 手机作为 DHT 节点，返回 Agent 1 的地址信息
+3. Agent 4 尝试 NAT 穿透直连 Agent 1
+4. 成功：直接 P2P 通信
+5. 失败：需要公共中继节点（未来扩展）
+```
+
+## 技术方案
+
+### 依赖添加
+
+```json
+{
+  "@libp2p/autonat": "^1.0.0",
+  "@libp2p/upnp-nat": "^1.0.0"
+}
+```
+
+### P2P 网络配置
+
+```typescript
+services.autonat = autoNAT();
+services.upnp = upnpNAT();
+```
+
+### 部署方式
+
+- **Termux** (Android)：使用脚本启动
+- **iSH** (iOS)：Alpine Linux 环境
+- **原生 App**：未来可选
+
+## 待解决问题
+
+| 问题 | 状态 | 方案 |
+|------|------|------|
+| NAT 穿透成功率 | 🔴 未验证 | 依赖 autoNAT/upnpNAT，需测试 |
+| 手机后台运行 | 🟡 部分可行 | Termux + 关闭电池优化 |
+| 跨网络直连 | 🔴 未验证 | 需要至少一方有可穿透的 NAT |
+| 公共中继备份 | 🔴 未实现 | 打洞失败时的备选方案 |
+
+## 实现状态
+
+🚧 **设计阶段** - 等待本地测试验证
+
+## 下一步
+
+1. 本地局域网测试验证基础功能
+2. Termux 真机测试
+3. NAT 穿透成功率测试
+4. 根据测试结果决定是否继续推进
+
+## 相关资源
+
+- [Termux 安装指南](./docs/TERMUX.md)（待创建）
+- [libp2p NAT 穿透文档](https://docs.libp2p.io/concepts/nat/)
+
+---
+
+*Created: 2026-03-05*
+*Status: Design Proposal*

package/docs/a2a-lessons.md

@@ -0,0 +1,316 @@
+# F2A 借鉴 A2A 协议的设计改进
+
+> 本文档记录从 Google A2A (Agent2Agent) 协议中可以借鉴的设计思路，用于改进 F2A 协议。
+
+---
+
+## 1. Agent Card 概念
+
+### 现状
+当前 F2A 的发现消息仅包含基础信息：
+```javascript
+{
+  type: 'F2A_DISCOVER',
+  agentId: 'xxx',
+  publicKey: 'xxx',
+  port: 9000
+}
+```
+
+### 借鉴 A2A 的改进
+将发现消息扩展为包含更多元数据，类似 A2A 的 Agent Card：
+```javascript
+{
+  type: 'F2A_DISCOVER',
+  agentId: 'xxx',
+  publicKey: 'xxx',
+  port: 9000,
+  displayName: 'WeatherAgent',
+  capabilities: ['chat', 'file_transfer', 'skill_invocation'],
+  skills: [
+    { 
+      name: 'weather', 
+      description: 'Get weather info for a location',
+      parameters: {
+        location: { type: 'string', required: true },
+        units: { type: 'string', enum: ['celsius', 'fahrenheit'], default: 'celsius' }
+      }
+    },
+    { 
+      name: 'translate', 
+      description: 'Translate text between languages' 
+    }
+  ],
+  authentication: {
+    requireConfirmation: true,
+    securityLevel: 'medium'
+  }
+}
+```
+
+### 好处
+- **能力发现**: 其他 Agent 可以在连接前了解你能做什么
+- **动态协商**: 支持交互模式的协商（文本、文件、结构化数据）
+- **自描述**: 减少人工配置，实现真正的即插即用
+
+---
+
+## 2. 任务生命周期管理
+
+### 现状
+F2A 目前只有简单的消息发送，缺乏任务状态跟踪：
+```javascript
+p2p.sendToPeer(peerId, {
+  type: 'message',
+  content: '...'
+});
+```
+
+### 借鉴 A2A 的改进
+引入 A2A 的任务状态机模型：
+```
+submitted → working → input-required → completed
+                    ↓
+                failed / canceled
+```
+
+### 实现示例
+```javascript
+// 发送任务
+const taskId = await p2p.sendTask(peerId, {
+  skill: 'weather',
+  parameters: { location: 'Beijing' }
+});
+
+// 任务状态流转
+p2p.on('task_update', ({ taskId, status, artifact }) => {
+  switch (status) {
+    case 'working':
+      console.log(`任务 ${taskId} 处理中...`);
+      break;
+    case 'input-required':
+      // 需要用户提供额外信息
+      console.log(`需要更多信息: ${artifact.description}`);
+      break;
+    case 'completed':
+      console.log(`任务完成: ${artifact.content}`);
+      break;
+    case 'failed':
+      console.log(`任务失败: ${artifact.error}`);
+      break;
+  }
+});
+
+// 取消任务
+await p2p.cancelTask(peerId, taskId);
+
+// 查询任务状态
+const task = await p2p.getTask(peerId, taskId);
+```
+
+### 好处
+- **长任务支持**: 适合需要长时间运行的任务
+- **人机协作**: 支持 human-in-the-loop 场景
+- **可观测性**: 可以跟踪任务进度和状态
+- **容错性**: 支持任务取消和失败处理
+
+---
+
+## 3. 标准化消息格式
+
+### 现状
+F2A 使用简单的 JSON 消息，缺乏严格的结构定义：
+```javascript
+{
+  type: 'message',
+  content: '...'
+}
+```
+
+### 借鉴 A2A 的改进
+参考 A2A 的 Protocol Buffer 定义，设计更严格的 JSON Schema：
+
+#### 3.1 消息结构标准化
+```javascript
+// 基础消息结构
+{
+  // 协议元数据
+  "protocol": {
+    "name": "F2A",
+    "version": "1.0.0"
+  },
+  
+  // 消息元数据
+  "meta": {
+    "messageId": "uuid",
+    "timestamp": 1700000000000,
+    "senderId": "f2a-xxx-xxx",
+    "correlationId": "uuid"  // 用于关联请求和响应
+  },
+  
+  // 消息负载
+  "payload": {
+    "type": "task_request",  // task_request | task_response | notification | etc.
+    "data": { ... }
+  },
+  
+  // 扩展字段
+  "extensions": {
+    "customField": "value"
+  }
+}
+```
+
+#### 3.2 Part 结构（内容单元）
+借鉴 A2A 的 Part 概念，统一内容表示：
+```javascript
+// 文本
+{ "type": "text", "content": "Hello" }
+
+// 文件
+{ 
+  "type": "file", 
+  "filename": "report.pdf",
+  "mimeType": "application/pdf",
+  "size": 1024000,
+  "fileId": "uuid"  // 引用文件传输系统的 ID
+}
+
+// 结构化数据
+{ 
+  "type": "data", 
+  "mimeType": "application/json",
+  "content": { "temperature": 25, "unit": "celsius" }
+}
+
+// 表单/输入请求
+{
+  "type": "form",
+  "fields": [
+    { "name": "location", "type": "text", "required": true },
+    { "name": "units", "type": "select", "options": ["C", "F"] }
+  ]
+}
+```
+
+#### 3.3 版本兼容性处理
+```javascript
+{
+  "protocol": {
+    "name": "F2A",
+    "version": "1.1.0",  // 发送方版本
+    "minCompatibleVersion": "1.0.0"  // 最低兼容版本
+  },
+  
+  // 接收方如果不支持某个字段，可以安全忽略
+  "payload": {
+    "type": "task_request",
+    "data": { ... },
+    "deprecatedField": "..."  // 标记废弃的字段
+  }
+}
+```
+
+#### 3.4 扩展机制
+```javascript
+{
+  "payload": {
+    "type": "task_request",
+    "data": { ... }
+  },
+  
+  // 厂商/应用特定扩展
+  "extensions": {
+    "com.example.customFeature": { ... },
+    "org.f2a.streaming": { "enabled": true }
+  }
+}
+```
+
+### 好处
+- **互操作性**: 严格的结构定义确保不同实现能正确通信
+- **向前兼容**: 版本机制支持平滑升级
+- **可扩展性**: 扩展机制允许自定义功能而不破坏核心协议
+- **类型安全**: 明确的字段类型减少解析错误
+
+---
+
+## 实施建议
+
+### 优先级
+1. **高**: Agent Card - 立即提升发现机制的能力
+2. **中**: 任务生命周期 - 支持更复杂的协作场景
+3. **低**: 消息格式标准化 - 在需要与其他系统集成时实施
+
+### 向后兼容
+- 新字段使用可选（optional）方式添加
+- 保留旧版发现消息解析支持
+- 版本协商机制：连接时交换支持的协议版本
+
+---
+
+## 参考
+
+- [A2A Protocol Specification](https://a2a-protocol.org/latest/specification/)
+- [A2A GitHub Repository](https://github.com/a2aproject/A2A)
+
+---
+
+# F2A 未来改进方向
+
+## 1. mDNS 服务发现
+
+### 现状
+当前 F2A 使用 UDP 多播（239.255.255.250:8768）进行设备发现，但部分路由器会阻止该多播地址。
+
+### mDNS 优势
+```
+mDNS (Multicast DNS) - 224.0.0.251:5353
+- 更可靠：路由器通常允许（用于 AirDrop、打印机发现）
+- 服务类型：只发现 F2A Agent，不混杂其他流量
+- 元数据：可以携带 Agent ID、公钥、版本等 TXT 记录
+- 冲突解决：自动处理主机名冲突
+```
+
+### 推荐方案：混合发现机制
+```javascript
+// 发现优先级
+1. mDNS (Bonjour/Avahi)      ← 首选
+2. UDP 多播 239.255.0.250    ← 备用
+3. UDP 广播 255.255.255.255  ← 最后手段
+```
+
+### 实现示例
+```javascript
+const bonjour = require('bonjour')();
+
+// 发布 F2A 服务
+bonjour.publish({
+  name: `F2A-${agentId.slice(0, 8)}`,
+  type: 'f2a',
+  port: 9000,
+  txt: {
+    agentId: 'f2a-xxx-xxx',
+    publicKey: 'xxx...',
+    version: '1.0.0',
+    capabilities: 'chat,file_transfer'
+  }
+});
+
+// 发现其他 F2A Agent
+bonjour.find({ type: 'f2a' }, (service) => {
+  console.log('发现:', service.name);
+  console.log('地址:', service.referer.address);
+  console.log('端口:', service.port);
+  console.log('元数据:', service.txt);
+});
+```
+
+### 参考
+- [Bonjour](https://github.com/watson/bonjour) - Node.js mDNS 实现
+- [Avahi](https://www.avahi.org/) - Linux mDNS/DNS-SD 实现
+- [RFC 6762](https://tools.ietf.org/html/rfc6762) - mDNS 标准
+
+---
+
+*最后更新：2026-03-02*