@f2a/network 0.1.2 → 0.1.3

package/packages/openclaw-adapter/src/announcement-queue.ts

@@ -1,403 +0,0 @@
-/**
- * F2A Announcement Queue
- * 管理任务广播和认领（Claim Pattern）
- * 
- * 设计说明：
- * - 默认导出类而非单例，便于测试和依赖注入
- * - createAnnouncementQueue() 工厂函数提供默认实例
- */
-
-import type { TaskAnnouncement, TaskClaim } from './types.js';
-import { randomUUID } from 'crypto';
-import { queueLogger as logger } from './logger.js';
-import { EventEmitter } from 'eventemitter3';
-
-/**
- * 任务广播队列统计信息
- * 
- * 提供任务广播各状态的数量统计，用于监控队列健康状态和任务处理进度。
- * 
- * @example
- * ```typescript
- * const stats: AnnouncementQueueStats = {
- *   open: 5,      // 5 个开放认领的任务
- *   claimed: 3,   // 3 个已被认领
- *   delegated: 12, // 12 个已委托执行
- *   expired: 2,   // 2 个已过期
- *   total: 22     // 总计 22 个广播
- * };
- * 
- * // 监控队列健康状态
- * if (stats.open > 10) {
- *   console.warn('待认领任务过多，考虑通知更多 Agent');
- * }
- * ```
- */
-export interface AnnouncementQueueStats {
-  /** 开放认领中的任务数量 */
-  open: number;
-  /** 已被认领的任务数量 */
-  claimed: number;
-  /** 已委托执行的任务数量 */
-  delegated: number;
-  /** 已过期的任务数量 */
-  expired: number;
-  /** 任务广播总数 */
-  total: number;
-}
-
-export interface AnnouncementQueueOptions {
-  maxSize?: number;
-  maxAgeMs?: number;
-}
-
-/** 过期事件载荷 */
-export interface AnnouncementExpiredEvent {
-  announcementId: string;
-  taskType: string;
-  from: string;
-  timestamp: number;
-  reason: 'timeout' | 'manual';
-}
-
-/** 事件类型定义 */
-export interface AnnouncementQueueEvents {
-  'announcement:expired': (event: AnnouncementExpiredEvent) => void;
-  'announcement:created': (announcement: TaskAnnouncement) => void;
-  'announcement:claimed': (announcement: TaskAnnouncement, claim: TaskClaim) => void;
-}
-
-export class AnnouncementQueue extends EventEmitter<AnnouncementQueueEvents> {
-  private announcements = new Map<string, TaskAnnouncement>();
-  private maxSize: number;
-  private maxAgeMs: number;
-  /** 正在处理的广播 ID 集合，用于防止并发操作 */
-  private processingLocks = new Set<string>();
-
-  constructor(options?: { maxSize?: number; maxAgeMs?: number }) {
-    super();
-    this.maxSize = options?.maxSize || 100;
-    this.maxAgeMs = options?.maxAgeMs || 30 * 60 * 1000; // 30分钟
-  }
-
-  /**
-   * 创建任务广播
-   */
-  create(announcement: Omit<TaskAnnouncement, 'announcementId' | 'timestamp' | 'status' | 'claims'>): TaskAnnouncement {
-    // 清理过期
-    this.cleanup();
-
-    // 检查容量
-    if (this.announcements.size >= this.maxSize) {
-      logger.error(' create: queue is full, size=%d, maxSize=%d', this.announcements.size, this.maxSize);
-      throw new Error('Announcement queue is full');
-    }
-
-    // 使用 crypto.randomUUID() 生成唯一 ID，避免碰撞
-    const id = `ann-${randomUUID()}`;
-    const created: TaskAnnouncement = {
-      ...announcement,
-      announcementId: id,
-      timestamp: Date.now(),
-      status: 'open',
-      claims: []
-    };
-
-    this.announcements.set(id, created);
-    logger.info(' create: announcementId=%s, from=%s, taskType=%s', id, announcement.from, announcement.taskType);
-    
-    // 发出创建事件
-    this.emit('announcement:created', created);
-    
-    return created;
-  }
-
-  /**
-   * 获取所有开放的广播
-   */
-  getOpen(): TaskAnnouncement[] {
-    // 在获取开放广播前先清理过期数据，避免返回过期数据
-    this.cleanup();
-    
-    return Array.from(this.announcements.values())
-      .filter(a => a.status === 'open')
-      .sort((a, b) => a.timestamp - b.timestamp);
-  }
-
-  /**
-   * 获取特定广播
-   */
-  get(announcementId: string): TaskAnnouncement | undefined {
-    return this.announcements.get(announcementId);
-  }
-
-  /**
-   * 提交认领
-   */
-  submitClaim(
-    announcementId: string,
-    claim: Omit<TaskClaim, 'claimId' | 'timestamp' | 'status' | 'announcementId'>
-  ): TaskClaim | null {
-    const announcement = this.announcements.get(announcementId);
-    if (!announcement) {
-      logger.warn(' submitClaim: announcement not found, id=%s, claimant=%s', announcementId, claim.claimant);
-      return null;
-    }
-    if (announcement.status !== 'open') {
-      logger.warn(' submitClaim: announcement not open, id=%s, status=%s, claimant=%s', announcementId, announcement.status, claim.claimant);
-      return null;
-    }
-
-    // 检查该 claimant 是否已经提交过认领（防止重复认领）
-    const existingClaim = announcement.claims?.find(c => c.claimant === claim.claimant);
-    if (existingClaim) {
-      logger.info(' submitClaim: duplicate claim ignored, id=%s, claimant=%s, existingClaimId=%s', announcementId, claim.claimant, existingClaim.claimId);
-      // 返回已存在的认领，而不是创建新的
-      return existingClaim;
-    }
-
-    // 使用 crypto.randomUUID() 生成唯一 ID
-    const claimId = `claim-${randomUUID()}`;
-    const created: TaskClaim = {
-      ...claim,
-      claimId,
-      announcementId,
-      timestamp: Date.now(),
-      status: 'pending'
-    };
-
-    if (!announcement.claims) {
-      announcement.claims = [];
-    }
-    announcement.claims.push(created);
-
-    logger.info(' submitClaim: claimId=%s, announcementId=%s, claimant=%s', claimId, announcementId, claim.claimant);
-    return created;
-  }
-
-  /**
-   * 接受认领
-   * 使用锁机制防止竞态条件
-   * 
-   * P1 修复：确保锁在任何情况下都能被释放，包括异常情况
-   */
-  acceptClaim(announcementId: string, claimId: string): TaskClaim | null {
-    const announcement = this.announcements.get(announcementId);
-    if (!announcement) {
-      logger.warn(' acceptClaim: announcement not found, id=%s, claimId=%s', announcementId, claimId);
-      return null;
-    }
-
-    // 检查是否已被锁定（正在被其他操作处理）
-    if (this.processingLocks.has(announcementId)) {
-      logger.warn(' acceptClaim: announcement is being processed, id=%s, claimId=%s', announcementId, claimId);
-      return null;
-    }
-
-    // 检查广播状态
-    if (announcement.status !== 'open') {
-      logger.warn(' acceptClaim: announcement not open, id=%s, status=%s, claimId=%s', announcementId, announcement.status, claimId);
-      return null;
-    }
-
-    const claim = announcement.claims?.find(c => c.claimId === claimId);
-    if (!claim) {
-      logger.warn(' acceptClaim: claim not found, announcementId=%s, claimId=%s', announcementId, claimId);
-      return null;
-    }
-
-    // 获取锁
-    this.processingLocks.add(announcementId);
-
-    try {
-      // 再次检查广播状态（双重检查）
-      if (announcement.status !== 'open') {
-        logger.warn(' acceptClaim: race condition detected, announcement status changed, id=%s, status=%s, claimId=%s', announcementId, announcement.status, claimId);
-        return null;
-      }
-
-      // 标记该认领为接受
-      claim.status = 'accepted';
-
-      // 拒绝其他认领（幂等操作，已拒绝的保持不变）
-      const rejectedCount = announcement.claims?.filter(c => {
-        if (c.claimId !== claimId && c.status !== 'rejected') {
-          c.status = 'rejected';
-          return true;
-        }
-        return false;
-      }).length || 0;
-
-      // 标记广播为已认领
-      announcement.status = 'claimed';
-
-      logger.info(' acceptClaim: claimId=%s, announcementId=%s, claimant=%s, rejectedCount=%d', claimId, announcementId, claim.claimant, rejectedCount);
-      
-      // 发出认领事件（在锁内发出，确保状态一致）
-      this.emit('announcement:claimed', announcement, claim);
-      
-      return claim;
-    } catch (error) {
-      // P1 修复：记录异常并返回 null，但不改变状态
-      logger.error(' acceptClaim: unexpected error, id=%s, claimId=%s, error=%s', announcementId, claimId, error);
-      // 注意：不恢复状态，因为操作可能已部分完成
-      // 但锁会在 finally 中释放
-      return null;
-    } finally {
-      // 确保锁在任何情况下都能被释放
-      this.processingLocks.delete(announcementId);
-    }
-  }
-
-  /**
-   * 拒绝认领
-   */
-  rejectClaim(announcementId: string, claimId: string): TaskClaim | null {
-    const announcement = this.announcements.get(announcementId);
-    if (!announcement) {
-      logger.warn(' rejectClaim: announcement not found, id=%s, claimId=%s', announcementId, claimId);
-      return null;
-    }
-
-    const claim = announcement.claims?.find(c => c.claimId === claimId);
-    if (!claim) {
-      logger.warn(' rejectClaim: claim not found, announcementId=%s, claimId=%s', announcementId, claimId);
-      return null;
-    }
-
-    claim.status = 'rejected';
-    logger.info(' rejectClaim: claimId=%s, announcementId=%s, claimant=%s', claimId, announcementId, claim.claimant);
-    return claim;
-  }
-
-  /**
-   * 标记为已委托
-   */
-  markDelegated(announcementId: string): boolean {
-    const announcement = this.announcements.get(announcementId);
-    if (!announcement) return false;
-
-    announcement.status = 'delegated';
-    return true;
-  }
-
-  /**
-   * 获取我的认领（作为认领方）
-   */
-  getMyClaims(claimantId: string): TaskClaim[] {
-    const claims: TaskClaim[] = [];
-    for (const announcement of this.announcements.values()) {
-      const myClaims = announcement.claims?.filter(c => c.claimant === claimantId);
-      if (myClaims) {
-        claims.push(...myClaims);
-      }
-    }
-    return claims.sort((a, b) => b.timestamp - a.timestamp);
-  }
-
-  /**
-   * 获取我的广播（作为发布方）
-   */
-  getMyAnnouncements(fromId: string): TaskAnnouncement[] {
-    return Array.from(this.announcements.values())
-      .filter(a => a.from === fromId)
-      .sort((a, b) => b.timestamp - a.timestamp);
-  }
-
-  /**
-   * 获取统计
-   */
-  getStats(): AnnouncementQueueStats {
-    const all = Array.from(this.announcements.values());
-    return {
-      open: all.filter(a => a.status === 'open').length,
-      claimed: all.filter(a => a.status === 'claimed').length,
-      delegated: all.filter(a => a.status === 'delegated').length,
-      expired: all.filter(a => a.status === 'expired').length,
-      total: all.length
-    };
-  }
-
-  /**
-   * 清理过期
-   */
-  cleanup(): void {
-    const now = Date.now();
-    let expiredCount = 0;
-    let deletedCount = 0;
-    
-    for (const [id, announcement] of this.announcements) {
-      const age = now - announcement.timestamp;
-      if (age > this.maxAgeMs) {
-        if (announcement.status === 'open') {
-          announcement.status = 'expired';
-          expiredCount++;
-          
-          // 发出过期事件，通知外部系统
-          const expiredEvent: AnnouncementExpiredEvent = {
-            announcementId: announcement.announcementId,
-            taskType: announcement.taskType,
-            from: announcement.from,
-            timestamp: announcement.timestamp,
-            reason: 'timeout'
-          };
-          this.emit('announcement:expired', expiredEvent);
-          logger.info('cleanup: announcement expired, id=%s, taskType=%s, from=%s', 
-            announcement.announcementId, announcement.taskType, announcement.from);
-        }
-        // 删除已过期一段时间的
-        if (age > this.maxAgeMs * 2) {
-          this.announcements.delete(id);
-          deletedCount++;
-        }
-      }
-    }
-    
-    if (expiredCount > 0 || deletedCount > 0) {
-      logger.info(' cleanup: expired=%d, deleted=%d, remaining=%d', expiredCount, deletedCount, this.announcements.size);
-    }
-  }
-
-  /**
-   * 清空
-   */
-  clear(): void {
-    this.announcements.clear();
-    // P1 修复：同时清理孤立锁
-    this.processingLocks.clear();
-  }
-  
-  /**
-   * 强制清除孤立锁
-   * P1 修复：用于处理异常导致的锁未释放情况
-   * 
-   * @param maxLockAgeMs 锁的最大存活时间（毫秒），默认 30 秒
-   * @returns 清除的锁数量
-   */
-  forceClearOrphanLocks(maxLockAgeMs: number = 30000): number {
-    // 由于当前实现没有记录锁的获取时间，我们只能清除所有锁
-    // 这是一个安全操作，因为锁只是为了防止并发，不会丢失数据
-    const count = this.processingLocks.size;
-    this.processingLocks.clear();
-    if (count > 0) {
-      logger.warn(' forceClearOrphanLocks: cleared %d orphan locks', count);
-    }
-    return count;
-  }
-  
-  /**
-   * 检查是否有孤立锁
-   * 用于监控和调试
-   */
-  hasOrphanLocks(): boolean {
-    return this.processingLocks.size > 0;
-  }
-}
-
-// 工厂函数：创建新的 AnnouncementQueue 实例
-export function createAnnouncementQueue(options?: { maxSize?: number; maxAgeMs?: number }): AnnouncementQueue {
-  return new AnnouncementQueue(options);
-}
-
-// 默认实例（向后兼容，但建议使用依赖注入）
-export const announcementQueue = new AnnouncementQueue();

package/packages/openclaw-adapter/src/capability-detector.test.ts

@@ -1,99 +0,0 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { CapabilityDetector } from './capability-detector';
-
-describe('CapabilityDetector', () => {
-  let detector: CapabilityDetector;
-
-  beforeEach(() => {
-    detector = new CapabilityDetector();
-  });
-
-  describe('getDefaultCapabilities', () => {
-    it('should return default capabilities list', () => {
-      const capabilities = detector.getDefaultCapabilities();
-      
-      expect(capabilities.length).toBeGreaterThan(0);
-      // 检查是否包含核心能力
-      expect(capabilities.some(c => c.name === 'file-operation')).toBe(true);
-      expect(capabilities.some(c => c.name === 'command-execution')).toBe(true);
-      expect(capabilities.some(c => c.name === 'web-browsing')).toBe(true);
-      expect(capabilities.some(c => c.name === 'code-generation')).toBe(true);
-      expect(capabilities.some(c => c.name === 'task-delegation')).toBe(true);
-    });
-
-    it('should return capabilities with proper structure', () => {
-      const capabilities = detector.getDefaultCapabilities();
-      
-      for (const cap of capabilities) {
-        expect(cap.name).toBeDefined();
-        expect(cap.description).toBeDefined();
-        expect(cap.parameters).toBeDefined();
-        expect(typeof cap.name).toBe('string');
-        expect(typeof cap.description).toBe('string');
-        expect(typeof cap.parameters).toBe('object');
-      }
-    });
-
-    it('should include tools array for relevant capabilities', () => {
-      const capabilities = detector.getDefaultCapabilities();
-      
-      const fileOp = capabilities.find(c => c.name === 'file-operation');
-      expect(fileOp?.tools).toContain('read');
-      expect(fileOp?.tools).toContain('write');
-    });
-  });
-
-  describe('mergeCustomCapabilities', () => {
-    it('should add custom capabilities to defaults', () => {
-      const defaults = detector.getDefaultCapabilities();
-      const custom = ['custom-ml', 'custom-data-analysis'];
-      
-      const merged = detector.mergeCustomCapabilities(defaults, custom);
-      
-      expect(merged.length).toBe(defaults.length + 2);
-      expect(merged.some(c => c.name === 'custom-ml')).toBe(true);
-      expect(merged.some(c => c.name === 'custom-data-analysis')).toBe(true);
-    });
-
-    it('should not duplicate existing capabilities', () => {
-      const defaults = detector.getDefaultCapabilities();
-      const custom = ['code-generation']; // 已存在的能力
-      
-      const merged = detector.mergeCustomCapabilities(defaults, custom);
-      
-      const count = merged.filter(c => c.name === 'code-generation').length;
-      expect(count).toBe(1);
-    });
-
-    it('should create proper structure for custom capabilities', () => {
-      const defaults = detector.getDefaultCapabilities();
-      const custom = ['my-custom-capability'];
-      
-      const merged = detector.mergeCustomCapabilities(defaults, custom);
-      const customCap = merged.find(c => c.name === 'my-custom-capability');
-      
-      expect(customCap).toBeDefined();
-      expect(customCap?.description).toContain('my-custom-capability');
-      expect(customCap?.parameters).toBeDefined();
-    });
-
-    it('should handle empty custom list', () => {
-      const defaults = detector.getDefaultCapabilities();
-      const merged = detector.mergeCustomCapabilities(defaults, []);
-      
-      expect(merged.length).toBe(defaults.length);
-    });
-
-    it('should preserve default capabilities order', () => {
-      const defaults = detector.getDefaultCapabilities();
-      const custom = ['zzz-custom'];
-      
-      const merged = detector.mergeCustomCapabilities(defaults, custom);
-      
-      // 默认能力应该在前，自定义在后
-      const defaultNames = defaults.map(c => c.name);
-      const mergedDefaultNames = merged.slice(0, defaults.length).map(c => c.name);
-      expect(mergedDefaultNames).toEqual(defaultNames);
-    });
-  });
-});

package/packages/openclaw-adapter/src/capability-detector.ts

@@ -1,183 +0,0 @@
-/**
- * OpenClaw 能力检测器
- * 提供默认能力列表（外部插件无法动态检测 OpenClaw 内部能力）
- */
-
-import type { AgentCapability, ParameterSchema } from './types.js';
-
-export interface OpenClawCapabilities {
-  tools: string[];
-  skills: string[];
-}
-
-export class CapabilityDetector {
-  /**
-   * 获取默认能力列表
-   * 外部插件无法直接访问 OpenClaw 内部，使用预定义的能力列表
-   */
-  getDefaultCapabilities(): AgentCapability[] {
-    return [
-      {
-        name: 'file-operation',
-        description: 'Read and write files on the local system',
-        tools: ['read', 'write', 'edit', 'list'],
-        parameters: {
-          action: {
-            type: 'string',
-            description: 'Action to perform: read, write, edit, list',
-            required: true
-          },
-          path: {
-            type: 'string',
-            description: 'File or directory path',
-            required: true
-          }
-        }
-      },
-      {
-        name: 'command-execution',
-        description: 'Execute shell commands',
-        tools: ['exec', 'bash'],
-        parameters: {
-          command: {
-            type: 'string',
-            description: 'Shell command to execute',
-            required: true
-          },
-          cwd: {
-            type: 'string',
-            description: 'Working directory',
-            required: false
-          }
-        }
-      },
-      {
-        name: 'web-browsing',
-        description: 'Browse web pages and fetch content',
-        tools: ['browser', 'fetch'],
-        parameters: {
-          url: {
-            type: 'string',
-            description: 'URL to browse or fetch',
-            required: true
-          },
-          action: {
-            type: 'string',
-            description: 'Action: fetch, screenshot, click, type',
-            required: false
-          }
-        }
-      },
-      {
-        name: 'image-analysis',
-        description: 'Analyze images using vision models',
-        tools: ['image', 'analyze'],
-        parameters: {
-          image: {
-            type: 'string',
-            description: 'Image path or URL',
-            required: true
-          },
-          prompt: {
-            type: 'string',
-            description: 'Analysis prompt',
-            required: false
-          }
-        }
-      },
-      {
-        name: 'subagent-creation',
-        description: 'Create sub-agents for parallel task execution',
-        tools: ['sessions_spawn', 'subagents'],
-        parameters: {
-          task: {
-            type: 'string',
-            description: 'Task description for sub-agent',
-            required: true
-          },
-          agentId: {
-            type: 'string',
-            description: 'Agent type to spawn',
-            required: false
-          }
-        }
-      },
-      {
-        name: 'messaging',
-        description: 'Send messages to users or channels',
-        tools: ['message', 'notify'],
-        parameters: {
-          target: {
-            type: 'string',
-            description: 'Message target',
-            required: true
-          },
-          content: {
-            type: 'string',
-            description: 'Message content',
-            required: true
-          }
-        }
-      },
-      {
-        name: 'code-generation',
-        description: 'Generate code in various programming languages',
-        tools: ['generate', 'refactor', 'explain'],
-        parameters: {
-          language: {
-            type: 'string',
-            description: 'Programming language',
-            required: true
-          },
-          description: {
-            type: 'string',
-            description: 'What the code should do',
-            required: true
-          }
-        }
-      },
-      {
-        name: 'task-delegation',
-        description: 'Delegate tasks to other agents in the network',
-        tools: ['delegate', 'discover'],
-        parameters: {
-          capability: {
-            type: 'string',
-            description: 'Required capability',
-            required: true
-          },
-          description: {
-            type: 'string',
-            description: 'Task description',
-            required: true
-          }
-        }
-      }
-    ];
-  }
-
-  /**
-   * 合并自定义能力
-   */
-  mergeCustomCapabilities(defaults: AgentCapability[], custom: string[]): AgentCapability[] {
-    const merged = [...defaults];
-    
-    for (const capName of custom) {
-      if (!merged.find(c => c.name === capName)) {
-        merged.push({
-          name: capName,
-          description: `Custom capability: ${capName}`,
-          parameters: {
-            query: {
-              type: 'string',
-              description: 'Input for this capability',
-              required: true
-            }
-          }
-        });
-      }
-    }
-
-    return merged;
-  }
-}