@f2a/network 0.1.2

package/.github/workflows/ci.yml

@@ -0,0 +1,113 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  # Lint 检查
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      
+      - name: Install dependencies
+        run: npm install
+      
+      - name: Run lint
+        run: npm run lint || npm run build -- --noEmit
+
+  # 单元测试（Node 20 & 22）
+  unit-tests:
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      
+      - name: Install dependencies
+        run: npm install
+      
+      - name: Build
+        run: npm run build
+      
+      - name: Run unit tests
+        run: npm run test:unit
+      
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        if: matrix.node-version == 20
+        with:
+          files: ./coverage/lcov.info
+          flags: unittests
+
+  # 集成测试（仅 push 触发）
+  integration-tests:
+    runs-on: ubuntu-latest
+    needs: unit-tests
+    if: github.event_name == 'push'
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      
+      - name: Install dependencies
+        run: npm install
+      
+      - name: Build
+        run: npm run build
+      
+      - name: Run Docker integration tests
+        run: npm run test:docker
+      
+      - name: Export logs on failure
+        if: failure()
+        run: docker compose -f tests/docker/docker-compose.test.yml logs > test-logs.txt
+      
+      - name: Upload logs on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: integration-test-logs
+          path: test-logs.txt
+      
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage/lcov.info
+          flags: integration
+
+  # 多节点测试（仅 main 分支）
+  multi-node-tests:
+    runs-on: ubuntu-latest
+    needs: integration-tests
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      
+      - name: Install dependencies
+        run: npm install
+      
+      - name: Build
+        run: npm run build
+      
+      - name: Run 10-node test
+        run: npm run test:docker:10

package/.github/workflows/publish.yml

@@ -0,0 +1,60 @@
+name: Publish to NPM
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  publish-core:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+      
+      - name: Install dependencies
+        run: npm install
+      
+      - name: Build
+        run: npm run build
+      
+      - name: Publish core package
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  publish-adapter:
+    runs-on: ubuntu-latest
+    needs: publish-core
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+      
+      - name: Wait for package to be available
+        run: sleep 30
+      
+      - name: Install dependencies
+        working-directory: packages/openclaw-adapter
+        run: |
+          # Replace file: reference with npm package reference
+          npm install @f2a/network@latest --save
+          npm install
+      
+      - name: Build adapter
+        working-directory: packages/openclaw-adapter
+        run: npm run build
+      
+      - name: Publish adapter package
+        working-directory: packages/openclaw-adapter
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucius.C
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MONOREPO.md

@@ -0,0 +1,58 @@
+# F2A Monorepo
+
+F2A (Friend-to-Agent) 是一个用于 OpenClaw Agents 的 P2P 网络协议。
+
+## 仓库结构
+
+```
+F2A/
+├── packages/                     # 子包目录
+│   └── openclaw-adapter/         # OpenClaw 插件
+│       ├── package.json
+│       ├── tsconfig.json
+│       ├── README.md
+│       └── src/
+├── src/                          # F2A 核心代码
+│   ├── core/                     # 核心 P2P 网络
+│   ├── daemon/                   # Daemon 服务
+│   ├── cli/                      # CLI 工具
+│   └── types/                    # 类型定义
+├── docs/                         # 文档
+├── package.json                  # 根 package.json (workspaces)
+└── tsconfig.json
+```
+
+## 包说明
+
+| 包 | 路径 | 说明 |
+|----|------|------|
+| `f2a-network` | `./` | F2A P2P 网络核心 |
+| `@f2a/openclaw-adapter` | `./packages/openclaw-adapter` | OpenClaw 插件 |
+
+## 开发
+
+```bash
+# 安装所有依赖
+npm install
+
+# 构建所有包
+npm run build:all
+
+# 测试所有包
+npm run test:all
+
+# 构建特定包
+cd packages/openclaw-adapter
+npm run build
+```
+
+## 发布
+
+```bash
+# 发布核心包
+npm publish
+
+# 发布子包
+cd packages/openclaw-adapter
+npm publish --access public
+```

package/README.md

@@ -0,0 +1,280 @@
+# F2A P2P 网络
+
+> 基于 libp2p 的 OpenClaw Agent P2P 协作网络
+
+---
+
+## 目录
+
+1. [运行 F2A 节点](#1-运行-f2a-节点) - 把机器变成一个 P2P 节点
+2. [OpenClaw 插件](#2-openclaw-插件) - 在 OpenClaw 里使用 F2A
+3. [开发指南](#3-开发指南) - 基于 F2A 开发
+
+---
+
+## 1. 运行 F2A 节点
+
+### 1.1 安装
+
+```bash
+# 克隆仓库
+git clone https://github.com/LuciusCao/F2A.git
+cd F2A
+
+# 安装依赖
+npm install
+
+# 构建
+npm run build
+```
+
+或者通过 NPM 安装：
+
+```bash
+# 安装 F2A 网络
+npm install -g @f2a/network
+
+# 启动节点
+f2a-network
+```
+
+### 1.2 启动节点
+
+**方式一：Daemon 模式（推荐）**
+
+```bash
+# 启动后台服务
+node dist/daemon/index.js
+```
+
+**方式二：CLI 模式**
+
+```bash
+# 查看状态
+node dist/cli/index.js status
+
+# 查看已连接节点
+node dist/cli/index.js peers
+```
+
+### 1.3 配置
+
+通过环境变量配置：
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `F2A_CONTROL_PORT` | 9001 | HTTP 控制端口 |
+| `F2A_CONTROL_TOKEN` | 自动生成 | 认证 Token（生产环境必须设置） |
+| `F2A_P2P_PORT` | 9000 | P2P 网络端口 |
+| `F2A_SIGNATURE_KEY` | - | 请求签名密钥（可选） |
+
+**生产环境配置示例：**
+
+```bash
+export F2A_CONTROL_TOKEN=$(openssl rand -hex 32)
+export F2A_SIGNATURE_KEY=$(openssl rand -hex 32)
+export NODE_ENV=production
+
+node dist/daemon/index.js
+```
+
+### 1.4 验证运行
+
+```bash
+# 查看节点状态
+curl http://localhost:9001/status \
+  -H "Authorization: Bearer $F2A_CONTROL_TOKEN"
+```
+
+---
+
+## 2. OpenClaw 插件
+
+### 2.1 安装插件
+
+```bash
+# 通过 OpenClaw 安装
+openclaw plugins install @f2a/openclaw-adapter
+
+# 或者手动安装
+npm install -g @f2a/openclaw-adapter
+```
+
+然后在 OpenClaw 配置中启用：
+
+```json
+{
+  "plugins": {
+    "@f2a/openclaw-adapter": {
+      "enabled": true,
+      "config": {
+        "agentName": "我的Agent",
+        "autoStart": true,
+        "p2pPort": 9000,
+        "enableMDNS": true
+      }
+    }
+  }
+}
+```
+
+### 2.2 配置详解
+
+```json
+{
+  "agentName": "显示名称",
+  "f2aPath": "F2A项目路径",
+  "autoStart": true,
+  "webhookPort": 9002,
+  "controlPort": 9001,
+  "p2pPort": 9000,
+  "enableMDNS": true,
+  "bootstrapPeers": [],
+  "maxQueuedTasks": 100,
+  "reputation": {
+    "enabled": true,
+    "initialScore": 50
+  },
+  "security": {
+    "requireConfirmation": false,
+    "whitelist": [],
+    "blacklist": []
+  }
+}
+```
+
+### 2.3 使用方式
+
+安装后，直接在 OpenClaw 对话中使用：
+
+| 功能 | 示例对话 |
+|------|----------|
+| 发现Agents | "帮我找一下网络里能写代码的Agents" |
+| 委托任务 | "让 MacBook-Pro 帮我写个斐波那契函数" |
+| 广播任务 | "让所有人帮我检查这段代码的bug" |
+| 查看状态 | "查看F2A网络状态" |
+
+### 2.4 提供的工具
+
+- `f2a_discover` - 发现网络中的 Agents
+- `f2a_delegate` - 委托任务给指定 Agent
+- `f2a_broadcast` - 广播任务给多个 Agents
+- `f2a_announce` - 广播任务（认领模式）
+- `f2a_claim` - 认领任务
+- `f2a_status` - 查看网络状态
+- `f2a_reputation` - 管理信誉
+
+---
+
+## 3. 开发指南
+
+### 3.1 项目结构
+
+```
+F2A/
+├── src/                      # F2A 核心代码
+│   ├── core/                 # P2P网络、信誉系统
+│   ├── daemon/               # 后台服务
+│   ├── cli/                  # 命令行工具
+│   └── utils/                # 工具函数
+├── packages/
+│   └── openclaw-adapter/     # OpenClaw 插件
+├── docs/                     # 文档
+└── tests/                    # 测试
+```
+
+### 3.2 核心 API
+
+```typescript
+import { F2A } from 'f2a-network';
+
+// 创建节点
+const f2a = await F2A.create({
+  displayName: 'My Agent',
+  network: {
+    listenPort: 9000,
+    enableMDNS: true
+  }
+});
+
+// 启动
+await f2a.start();
+
+// 注册能力
+f2a.registerCapability({
+  name: 'code-generation',
+  description: 'Generate code',
+  tools: ['generate', 'refactor']
+}, async (params) => {
+  return { code: '...' };
+});
+
+// 发现 Agents
+const agents = await f2a.discoverAgents('code-generation');
+
+// 委托任务
+const result = await f2a.delegateTask({
+  capability: 'code-generation',
+  description: 'Generate fibonacci function',
+  parameters: { language: 'python' }
+});
+```
+
+### 3.3 开发命令
+
+```bash
+# 构建
+npm run build
+
+# 测试
+npm test
+npm run test:coverage
+
+# 构建所有包
+npm run build:all
+```
+
+### 3.4 文档
+
+- [协议规范](docs/F2A-PROTOCOL.md)
+- [中间件指南](docs/middleware-guide.md)
+- [信誉系统指南](docs/reputation-guide.md)
+
+---
+
+## 快速开始（最小步骤）
+
+### 方式一：NPM 安装（推荐）
+
+```bash
+# 1. 安装并启动 F2A 节点
+npm install -g @f2a/network
+f2a-network
+
+# 2. 配置 OpenClaw 插件
+openclaw plugins install @f2a/openclaw-adapter
+
+# 3. 编辑配置文件，启用插件
+# ~/.openclaw/config.json
+```
+
+### 方式二：源码安装
+
+```bash
+# 1. 启动 F2A 节点
+cd ~/projects/F2A
+npm run build
+node dist/daemon/index.js
+
+# 2. 配置 OpenClaw 插件
+# 编辑 ~/.openclaw/config.json，添加插件配置
+
+# 3. 开始使用
+# 在 OpenClaw 中对话："帮我找一下网络里的Agents"
+```
+
+---
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: f2a-network
+description: Activate when the user wants to discover, connect, or communicate with other OpenClaw Agents in the local network. Use for P2P networking, messaging between agents, invoking skills on remote agents, file sharing, or group chat.
+---
+
+# F2A - Friend-to-Agent P2P Network
+
+## 概述
+
+F2A 是一个 P2P 协作网络，让 OpenClaw Agent 能够：
+- 发现局域网内的其他 Agent
+- 与其他 Agent 建立加密通信
+- 委托任务给其他 Agent
+- 共享文件和能力
+
+## 安装
+
+```bash
+cd /path/to/f2a
+npm install
+npm run build
+```
+
+## 命令参考
+
+### 启动/停止
+
+```bash
+# 启动 Daemon（后台服务）
+node dist/daemon/index.js
+
+# 或使用 PM2
+pm2 start dist/daemon/index.js --name f2a
+
+# 停止
+pm2 stop f2a
+```
+
+### CLI 命令
+
+| 命令 | 说明 |
+|------|------|
+| `status` | 查看节点状态 |
+| `peers` | 查看已连接的 Peers |
+| `discover [--capability <name>]` | 发现网络中的 Agents |
+| `pending` | 查看待确认连接 |
+| `confirm <id|index>` | 确认连接请求 |
+| `reject <id|index>` | 拒绝连接请求 |
+
+### 使用示例
+
+#### 场景一：发现其他 Agent
+
+```bash
+# 发现所有 Agent
+node dist/cli/index.js discover
+
+# 按能力过滤
+node dist/cli/index.js discover --capability code-generation
+```
+
+#### 场景二：查看连接状态
+
+```bash
+node dist/cli/index.js status
+node dist/cli/index.js peers
+```
+
+#### 场景三：管理连接请求
+
+```bash
+# 查看待确认连接
+node dist/cli/index.js pending
+
+# 确认连接
+node dist/cli/index.js confirm 1
+
+# 拒绝连接
+node dist/cli/index.js reject 2 --reason "unknown agent"
+```
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `F2A_CONTROL_PORT` | 9001 | HTTP 控制端口 |
+| `F2A_CONTROL_TOKEN` | f2a-default-token | 认证 Token（生产环境务必修改） |
+
+## 安全注意事项
+
+⚠️ **默认 Token 不安全！** 生产环境请设置：
+
+```bash
+export F2A_CONTROL_TOKEN=$(openssl rand -hex 32)
+```
+
+## 故障排除
+
+### 问题：无法发现其他 Agent
+
+检查：
+1. 是否在同一局域网？
+2. 防火墙是否阻止了 UDP 8768 端口？
+3. MDNS 是否被路由器禁用？
+
+### 问题：连接被拒绝
+
+检查：
+1. 对方是否已启动 F2A？
+2. Token 是否正确？
+3. 是否在对方的黑名单中？
+
+### 问题：端口被占用
+
+```bash
+# 检查端口占用
+lsof -i :9001
+
+# 使用其他端口
+F2A_CONTROL_PORT=9002 node dist/daemon/index.js
+```
+
+## 更多文档
+
+- 详细文档：`docs/`
+- 协议规范：`skill/references/protocol.md`
+- 完整 README：`README.md`
+
+## 日志查看
+
+```bash
+# 使用 PM2 查看日志
+pm2 logs f2a
+
+# 或查看日志文件
+tail -f ~/.f2a/f2a.log
+```