@f2a/network 0.1.2

package/src/index.ts

@@ -0,0 +1,72 @@
+/**
+ * F2A SDK 入口
+ * P2P networking protocol for OpenClaw Agents
+ */
+
+// 核心 P2P 网络
+export { F2A } from './core/f2a.js';
+export { P2PNetwork } from './core/p2p-network.js';
+export { TokenManager, defaultTokenManager } from './core/token-manager.js';
+export { E2EECrypto, defaultE2EECrypto } from './core/e2ee-crypto.js';
+
+// 信誉系统 (Phase 1-4)
+export { ReputationManager, REPUTATION_TIERS } from './core/reputation.js';
+export type { 
+  ReputationEntry, 
+  ReputationEvent, 
+  ReputationLevel,
+  ReputationTier,
+  ReputationConfig,
+  ReputationStorage
+} from './core/reputation.js';
+
+export { ReviewCommittee } from './core/review-committee.js';
+export type {
+  TaskReview,
+  ReviewResult,
+  ReviewDimensions,
+  RiskFlag,
+  ReviewCommitteeConfig,
+  PendingReview
+} from './core/review-committee.js';
+
+export { AutonomousEconomy } from './core/autonomous-economy.js';
+export type {
+  TaskRequest,
+  TaskCost,
+  TaskReward,
+  EconomyConfig,
+  PriorityQueueItem,
+  TaskExecutionResult
+} from './core/autonomous-economy.js';
+
+// 信誉安全机制 (Phase 3)
+export { 
+  ChainSignatureManager, 
+  InvitationManager, 
+  ChallengeManager 
+} from './core/reputation-security.js';
+export type {
+  SignedReputationEvent,
+  ReviewerSignature,
+  InvitationRecord,
+  InvitationConfig,
+  ChallengeRecord,
+  ChallengeResult
+} from './core/reputation-security.js';
+
+// 工具模块
+export { Logger } from './utils/logger.js';
+export { RateLimiter } from './utils/rate-limiter.js';
+export { RequestSigner } from './utils/signature.js';
+export { 
+  createMessageSizeLimitMiddleware,
+  createMessageTypeFilterMiddleware 
+} from './utils/middleware.js';
+export type { Middleware, MiddlewareContext, MiddlewareResult } from './utils/middleware.js';
+
+// 类型定义
+export * from './types/index.js';
+
+// 版本号
+export const VERSION = '1.0.1';

package/src/types/index.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from 'vitest';
+import {
+  AgentCapability,
+  AgentInfo,
+  F2AMessage,
+  F2AOptions,
+  Result,
+  TaskDelegateOptions,
+  WebhookConfig
+} from './index.js';
+
+describe('Types', () => {
+  it('should allow creating AgentCapability', () => {
+    const cap: AgentCapability = {
+      name: 'test-cap',
+      description: 'Test capability',
+      tools: ['tool1'],
+      parameters: {
+        param1: { type: 'string', required: true }
+      }
+    };
+    expect(cap.name).toBe('test-cap');
+  });
+
+  it('should allow creating AgentInfo', () => {
+    const info: AgentInfo = {
+      peerId: 'test-peer-id',
+      displayName: 'Test Agent',
+      agentType: 'openclaw',
+      version: '1.0.0',
+      capabilities: [],
+      protocolVersion: 'f2a/1.0',
+      lastSeen: Date.now(),
+      multiaddrs: []
+    };
+    expect(info.peerId).toBe('test-peer-id');
+  });
+
+  it('should allow creating F2AOptions', () => {
+    const options: F2AOptions = {
+      displayName: 'Test',
+      agentType: 'openclaw',
+      network: {
+        listenPort: 9000,
+        enableMDNS: true
+      }
+    };
+    expect(options.displayName).toBe('Test');
+  });
+
+  it('should allow creating Result types', () => {
+    const successResult: Result<string> = {
+      success: true,
+      data: 'test'
+    };
+    expect(successResult.success).toBe(true);
+
+    const errorResult: Result<string> = {
+      success: false,
+      error: 'Error message'
+    };
+    expect(errorResult.success).toBe(false);
+  });
+
+  it('should allow creating TaskDelegateOptions', () => {
+    const options: TaskDelegateOptions = {
+      capability: 'test-cap',
+      description: 'Test task',
+      parameters: { key: 'value' },
+      timeout: 30000,
+      parallel: true,
+      minResponses: 2
+    };
+    expect(options.capability).toBe('test-cap');
+  });
+
+  it('should allow creating WebhookConfig', () => {
+    const config: WebhookConfig = {
+      url: 'http://localhost:8080',
+      token: 'test-token',
+      timeout: 5000,
+      retries: 3,
+      retryDelay: 1000
+    };
+    expect(config.url).toBe('http://localhost:8080');
+  });
+});

package/src/types/index.ts

@@ -0,0 +1,341 @@
+/**
+ * F2A P2P 网络核心类型定义
+ * 基于 libp2p 的 Agent 协作网络
+ */
+
+import { Multiaddr } from '@multiformats/multiaddr';
+import { EventEmitter } from 'eventemitter3';
+
+// ============================================================================
+// 基础类型
+// ============================================================================
+
+export type SecurityLevel = 'low' | 'medium' | 'high';
+
+export type LogLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
+
+// ============================================================================
+// Agent 能力与身份
+// ============================================================================
+
+export interface AgentCapability {
+  /** 能力名称，如 "file-operation", "web-browsing", "code-generation" */
+  name: string;
+  /** 能力描述 */
+  description: string;
+  /** 支持的工具/操作 */
+  tools: string[];
+  /** 能力参数schema（可选） */
+  parameters?: Record<string, ParameterSchema>;
+}
+
+export interface ParameterSchema {
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  required?: boolean;
+  default?: unknown;
+  description?: string;
+}
+
+export interface AgentInfo {
+  /** libp2p PeerID */
+  peerId: string;
+  /** 可读名称 */
+  displayName?: string;
+  /** Agent 类型 */
+  agentType: 'openclaw' | 'claude-code' | 'codex' | 'custom';
+  /** 版本 */
+  version: string;
+  /** 支持的能力列表 */
+  capabilities: AgentCapability[];
+  /** 支持的协议版本 */
+  protocolVersion: string;
+  /** 最后活跃时间 */
+  lastSeen: number;
+  /** 网络地址 */
+  multiaddrs: string[];
+  /** 端到端加密公钥 (base64) */
+  encryptionPublicKey?: string;
+}
+
+// ============================================================================
+// P2P 网络配置
+// ============================================================================
+
+export interface P2PNetworkConfig {
+  /** 监听端口 */
+  listenPort?: number;
+  /** 监听地址 */
+  listenAddresses?: string[];
+  /** 引导节点列表 */
+  bootstrapPeers?: string[];
+  /** 是否启用 MDNS 本地发现 */
+  enableMDNS?: boolean;
+  /** 是否启用 DHT (默认 true) */
+  enableDHT?: boolean;
+  /** DHT 服务器模式 (默认 false，即客户端模式) */
+  dhtServerMode?: boolean;
+}
+
+export interface F2AOptions {
+  /** 节点可读名称 */
+  displayName?: string;
+  /** Agent 类型 */
+  agentType?: string;
+  /** P2P 网络配置 */
+  network?: P2PNetworkConfig;
+  /** 安全级别 */
+  security?: SecurityConfig;
+  /** 日志级别 */
+  logLevel?: LogLevel;
+  /** 数据目录 */
+  dataDir?: string;
+}
+
+export interface SecurityConfig {
+  level: SecurityLevel;
+  /** 是否要求确认连接 */
+  requireConfirmation: boolean;
+  /** 是否验证签名 */
+  verifySignatures: boolean;
+  /** 白名单 */
+  whitelist?: Set<string>;
+  /** 黑名单 */
+  blacklist?: Set<string>;
+  /** 速率限制 */
+  rateLimit?: RateLimitConfig;
+}
+
+export interface RateLimitConfig {
+  maxRequests: number;
+  windowMs: number;
+}
+
+// ============================================================================
+// F2A 消息协议
+// ============================================================================
+
+export type F2AMessageType = 
+  | 'DISCOVER'      // 发现广播
+  | 'DISCOVER_RESP' // 发现响应
+  | 'CAPABILITY_QUERY'   // 查询能力
+  | 'CAPABILITY_RESPONSE' // 能力响应
+  | 'TASK_REQUEST'  // 任务请求
+  | 'TASK_RESPONSE' // 任务响应
+  | 'TASK_DELEGATE' // 任务转委托
+  | 'DECRYPT_FAILED' // 解密失败通知
+  | 'PING'          // 心跳
+  | 'PONG';         // 心跳响应
+
+export interface F2AMessage {
+  /** 消息ID */
+  id: string;
+  /** 消息类型 */
+  type: F2AMessageType;
+  /** 发送方 PeerID */
+  from: string;
+  /** 目标 PeerID（广播可为空） */
+  to?: string;
+  /** 时间戳 */
+  timestamp: number;
+  /** TTL */
+  ttl?: number;
+  /** 载荷 */
+  payload: unknown;
+}
+
+// 发现广播
+export interface DiscoverPayload {
+  agentInfo: AgentInfo;
+}
+
+// 能力查询
+export interface CapabilityQueryPayload {
+  /** 查询特定能力，空表示查询所有 */
+  capabilityName?: string;
+  /** 查询特定工具 */
+  toolName?: string;
+}
+
+// 能力响应
+export interface CapabilityResponsePayload {
+  agentInfo: AgentInfo;
+}
+
+// 任务请求
+export interface TaskRequestPayload {
+  /** 任务ID */
+  taskId: string;
+  /** 任务类型 */
+  taskType: string;
+  /** 任务描述 */
+  description: string;
+  /** 任务参数 */
+  parameters?: Record<string, unknown>;
+  /** 超时时间（秒） */
+  timeout?: number;
+}
+
+// 任务响应
+export interface TaskResponsePayload {
+  /** 任务ID */
+  taskId: string;
+  /** 状态 */
+  status: 'success' | 'error' | 'rejected' | 'delegated';
+  /** 结果数据 */
+  result?: unknown;
+  /** 错误信息 */
+  error?: string;
+  /** 如果转委托，指向新节点 */
+  delegatedTo?: string;
+}
+
+// ============================================================================
+// 事件定义
+// ============================================================================
+
+export interface PeerDiscoveredEvent {
+  peerId: string;
+  agentInfo: AgentInfo;
+  multiaddrs: Multiaddr[];
+}
+
+export interface PeerConnectedEvent {
+  peerId: string;
+  direction: 'inbound' | 'outbound';
+}
+
+export interface PeerDisconnectedEvent {
+  peerId: string;
+}
+
+export interface TaskRequestEvent {
+  taskId: string;
+  from: string;
+  taskType: string;
+  description: string;
+  parameters?: Record<string, unknown>;
+  timeout?: number;
+}
+
+export interface TaskResponseEvent {
+  taskId: string;
+  from: string;
+  status: 'success' | 'error' | 'rejected' | 'delegated';
+  result?: unknown;
+  error?: string;
+}
+
+export interface NetworkStartedEvent {
+  peerId: string;
+  listenAddresses: string[];
+}
+
+export interface F2AEvents {
+  'peer:discovered': (event: PeerDiscoveredEvent) => void;
+  'peer:connected': (event: PeerConnectedEvent) => void;
+  'peer:disconnected': (event: PeerDisconnectedEvent) => void;
+  'task:request': (event: TaskRequestEvent) => void;
+  'task:response': (event: TaskResponseEvent) => void;
+  'network:started': (event: NetworkStartedEvent) => void;
+  'network:stopped': () => void;
+  'error': (error: Error) => void;
+}
+
+export type F2AEventEmitter = EventEmitter<F2AEvents>;
+
+// ============================================================================
+// 结果类型 (从 result.ts 重新导出)
+// ============================================================================
+
+// Result 和 AsyncResult 从 ./result 导出
+
+// ============================================================================
+// Webhook 配置
+// ============================================================================
+
+export interface WebhookConfig {
+  url: string;
+  token: string;
+  timeout?: number;
+  retries?: number;
+  retryDelay?: number;
+}
+
+// ============================================================================
+// 任务委托
+// ============================================================================
+
+/** 任务委托重试选项 */
+export interface TaskRetryOptions {
+  /** 最大重试次数（默认 3） */
+  maxRetries?: number;
+  /** 重试间隔毫秒（默认 1000） */
+  retryDelayMs?: number;
+  /** 发现超时毫秒（默认 5000） */
+  discoverTimeoutMs?: number;
+}
+
+export interface TaskDelegateOptions {
+  /** 目标能力 */
+  capability: string;
+  /** 任务描述 */
+  description: string;
+  /** 任务参数 */
+  parameters?: Record<string, unknown>;
+  /** 超时时间（秒） */
+  timeout?: number;
+  /** 是否允许多方并行执行 */
+  parallel?: boolean;
+  /** 最少响应数（parallel=true时） */
+  minResponses?: number;
+  /** 重试选项 */
+  retryOptions?: TaskRetryOptions;
+}
+
+export interface TaskDelegateResult {
+  taskId: string;
+  results: {
+    peerId: string;
+    status: 'success' | 'error' | 'timeout';
+    result?: unknown;
+    error?: string;
+    latency: number;
+  }[];
+}
+
+// ============================================================================
+// 路由表
+// ============================================================================
+
+export interface PeerInfo {
+  peerId: string;
+  agentInfo?: AgentInfo;
+  multiaddrs: Multiaddr[];
+  connected: boolean;
+  latency?: number;
+  /** 信誉分 */
+  reputation: number;
+  /** 连接时间 */
+  connectedAt?: number;
+  /** 最后活跃 */
+  lastSeen: number;
+}
+
+// ============================================================================
+// 能力注册
+// ============================================================================
+
+export interface CapabilityHandler {
+  (params: Record<string, unknown>): Promise<unknown>;
+}
+
+export interface RegisteredCapability extends AgentCapability {
+  handler: CapabilityHandler;
+}
+
+// ============================================================================
+// 统一 Result 类型
+// 从 result.ts 重新导出，用于统一的错误处理模式
+// ============================================================================
+
+export * from './result.js';

package/src/types/result.ts

@@ -0,0 +1,68 @@
+/**
+ * 统一的错误类型和错误码
+ */
+
+export type ErrorCode = 
+  // 网络错误
+  | 'NETWORK_NOT_STARTED'
+  | 'NETWORK_ALREADY_RUNNING'
+  | 'PEER_NOT_FOUND'
+  | 'CONNECTION_FAILED'
+  | 'TIMEOUT'
+  // DHT 错误
+  | 'DHT_NOT_AVAILABLE'
+  | 'DHT_LOOKUP_FAILED'
+  // 加密错误
+  | 'ENCRYPTION_NOT_READY'
+  | 'ENCRYPTION_FAILED'
+  // 任务错误
+  | 'TASK_NOT_FOUND'
+  | 'TASK_REJECTED'
+  | 'TASK_FAILED'
+  | 'CAPABILITY_NOT_SUPPORTED'
+  | 'INVALID_OPTIONS'
+  // 安全错误
+  | 'UNAUTHORIZED'
+  | 'FORBIDDEN'
+  | 'RATE_LIMITED'
+  // 通用错误
+  | 'INVALID_PARAMS'
+  | 'INTERNAL_ERROR'
+  | 'UNKNOWN';
+
+export interface F2AError {
+  code: ErrorCode;
+  message: string;
+  details?: Record<string, unknown>;
+  cause?: Error;
+}
+
+export function createError(
+  code: ErrorCode,
+  message: string,
+  details?: Record<string, unknown>,
+  cause?: Error
+): F2AError {
+  return { code, message, details, cause };
+}
+
+/**
+ * 统一的 Result 类型
+ */
+export type Result<T> = 
+  | { success: true; data: T; error?: never }
+  | { success: false; error: F2AError; data?: never };
+
+export function success<T>(data: T): Result<T> {
+  return { success: true, data };
+}
+
+export function failure<T>(error: F2AError): Result<T> {
+  return { success: false, error };
+}
+
+export function failureFromError<T>(code: ErrorCode, message: string, cause?: Error): Result<T> {
+  return { success: false, error: createError(code, message, undefined, cause) };
+}
+
+export type AsyncResult<T> = Promise<Result<T>>;