@f2a/openclaw-f2a 0.2.20

package/dist/agent-manager.js

@@ -0,0 +1,206 @@
+"use strict";
+/**
+ * Agent Manager
+ *
+ * 管理 Agent 身份和生命周期。
+ * Phase 1: 引入 AgentID，独立于 Node 的 PeerID。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentManager = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const crypto_1 = require("crypto");
+const logger_js_1 = require("./logger.js");
+/** Agent 数据文件名 */
+const AGENT_DATA_FILE = 'agent.json';
+/**
+ * Agent Manager
+ *
+ * 职责：
+ * - 生成或加载 Agent 身份
+ * - 持久化 Agent 数据
+ * - 提供 Agent 相关 API
+ */
+class AgentManager {
+    dataDir;
+    identity = null;
+    config;
+    constructor(dataDir, config = {}) {
+        this.dataDir = dataDir;
+        this.config = config;
+        // 同步初始化（避免插件异步注册问题）
+        this.initializeSync();
+    }
+    /**
+     * 同步初始化 Agent 身份
+     * - 如果已存在则加载
+     * - 如果不存在则创建
+     */
+    initializeSync() {
+        // 尝试加载已有身份
+        const existing = this.loadIdentity();
+        if (existing) {
+            this.identity = existing;
+            logger_js_1.pluginLogger.info('[F2A:Agent] 已加载 Agent 身份: %s', existing.agentId);
+            return;
+        }
+        // 创建新身份
+        this.identity = this.createIdentity();
+        this.saveIdentity(this.identity);
+        logger_js_1.pluginLogger.info('[F2A:Agent] 已创建新 Agent 身份: %s', this.identity.agentId);
+    }
+    /**
+     * 异步初始化（兼容旧 API）
+     * @deprecated 使用构造函数自动初始化
+     */
+    async initialize() {
+        if (!this.identity) {
+            this.initializeSync();
+        }
+        return this.identity;
+    }
+    /**
+     * 获取当前 Agent 身份
+     */
+    getIdentity() {
+        return this.identity;
+    }
+    /**
+     * 获取 AgentID
+     */
+    getAgentId() {
+        return this.identity?.agentId || null;
+    }
+    /**
+     * 获取 Agent 名称
+     */
+    getAgentName() {
+        return this.identity?.name || 'Unknown Agent';
+    }
+    /**
+     * 创建新 Agent 身份
+     */
+    createIdentity() {
+        const agentId = this.config.id || this.generateAgentId();
+        const name = this.config.name || this.generateDefaultName();
+        return {
+            agentId,
+            name,
+            createdAt: Date.now()
+        };
+    }
+    /**
+     * 生成 AgentID
+     * 格式: agent-{timestamp}-{random}
+     */
+    generateAgentId() {
+        const timestamp = Date.now().toString(36);
+        const random = (0, crypto_1.randomBytes)(6).toString('hex');
+        return `agent-${timestamp}-${random}`;
+    }
+    /**
+     * 生成默认 Agent 名称
+     */
+    generateDefaultName() {
+        const names = ['Alpha', 'Beta', 'Gamma', 'Delta', 'Epsilon', 'Zeta', 'Eta', 'Theta'];
+        const randomName = names[Math.floor(Math.random() * names.length)];
+        return `Agent-${randomName}`;
+    }
+    /**
+     * 加载已存在的 Agent 身份
+     */
+    loadIdentity() {
+        const filePath = (0, path_1.join)(this.dataDir, AGENT_DATA_FILE);
+        if (!(0, fs_1.existsSync)(filePath)) {
+            return null;
+        }
+        try {
+            const data = (0, fs_1.readFileSync)(filePath, 'utf-8');
+            const identity = JSON.parse(data);
+            // 验证必要字段
+            if (!identity.agentId || !identity.name || !identity.createdAt) {
+                logger_js_1.pluginLogger.warn('[F2A:Agent] 身份文件格式无效，将创建新身份');
+                return null;
+            }
+            return identity;
+        }
+        catch (error) {
+            logger_js_1.pluginLogger.warn('[F2A:Agent] 加载身份文件失败: %s', error);
+            return null;
+        }
+    }
+    /**
+     * 保存 Agent 身份到文件
+     */
+    saveIdentity(identity) {
+        // 确保目录存在
+        if (!(0, fs_1.existsSync)(this.dataDir)) {
+            (0, fs_1.mkdirSync)(this.dataDir, { recursive: true });
+        }
+        const filePath = (0, path_1.join)(this.dataDir, AGENT_DATA_FILE);
+        const data = JSON.stringify(identity, null, 2);
+        (0, fs_1.writeFileSync)(filePath, data, { mode: 0o600 }); // 仅所有者可读写
+        logger_js_1.pluginLogger.debug('[F2A:Agent] 身份已保存到: %s', filePath);
+    }
+    /**
+     * 导出 Agent 身份（用于迁移）
+     */
+    exportIdentity() {
+        if (!this.identity) {
+            throw new Error('No agent identity loaded');
+        }
+        return JSON.stringify(this.identity);
+    }
+    /**
+     * 导入 Agent 身份（用于迁移）
+     */
+    importIdentity(data) {
+        // P1-3 修复：输入验证
+        // 1. 长度限制：防止过大的输入导致内存问题
+        const MAX_IDENTITY_SIZE = 4096; // 4KB 足够存储 AgentIdentity
+        if (data.length > MAX_IDENTITY_SIZE) {
+            throw new Error(`Identity data too large: ${data.length} bytes (max: ${MAX_IDENTITY_SIZE})`);
+        }
+        // 2. 基础格式校验：确保是有效的 JSON
+        let identity;
+        try {
+            identity = JSON.parse(data);
+        }
+        catch (parseError) {
+            throw new Error('Invalid JSON format for identity data');
+        }
+        // 3. 类型验证：确保解析结果是一个对象
+        if (typeof identity !== 'object' || identity === null || Array.isArray(identity)) {
+            throw new Error('Identity data must be a JSON object');
+        }
+        // 4. 验证必要字段
+        if (!identity.agentId || !identity.name || !identity.createdAt) {
+            throw new Error('Invalid agent identity data: missing required fields (agentId, name, createdAt)');
+        }
+        // 5. 字段格式验证
+        if (typeof identity.agentId !== 'string' || identity.agentId.length === 0) {
+            throw new Error('Invalid agentId: must be a non-empty string');
+        }
+        if (typeof identity.name !== 'string' || identity.name.length === 0) {
+            throw new Error('Invalid name: must be a non-empty string');
+        }
+        if (typeof identity.createdAt !== 'number' || identity.createdAt <= 0) {
+            throw new Error('Invalid createdAt: must be a positive number');
+        }
+        this.identity = identity;
+        this.saveIdentity(identity);
+        logger_js_1.pluginLogger.info('[F2A:Agent] 已导入 Agent 身份: %s', identity.agentId);
+        return identity;
+    }
+    /**
+     * 重置 Agent 身份（创建新的）
+     */
+    resetIdentity() {
+        this.identity = this.createIdentity();
+        this.saveIdentity(this.identity);
+        logger_js_1.pluginLogger.info('[F2A:Agent] 已重置 Agent 身份: %s', this.identity.agentId);
+        return this.identity;
+    }
+}
+exports.AgentManager = AgentManager;
+//# sourceMappingURL=agent-manager.js.map

package/dist/agent-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-manager.js","sourceRoot":"","sources":["../src/agent-manager.ts"],"names":[],"mappings":"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"}

package/dist/announcement-queue.d.ts

@@ -0,0 +1,152 @@
+/**
+ * F2A Announcement Queue
+ * 管理任务广播和认领（Claim Pattern）
+ *
+ * 设计说明：
+ * - 默认导出类而非单例，便于测试和依赖注入
+ * - createAnnouncementQueue() 工厂函数提供默认实例
+ */
+import type { TaskAnnouncement, TaskClaim } from './types.js';
+import { EventEmitter } from 'eventemitter3';
+/** Logger 接口 */
+interface Logger {
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    debug?(message: string, ...args: unknown[]): void;
+}
+/**
+ * 任务广播队列统计信息
+ *
+ * 提供任务广播各状态的数量统计，用于监控队列健康状态和任务处理进度。
+ *
+ * @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 declare class AnnouncementQueue extends EventEmitter<AnnouncementQueueEvents> {
+    private announcements;
+    private maxSize;
+    private maxAgeMs;
+    /** 正在处理的广播 ID 集合，用于防止并发操作 */
+    private processingLocks;
+    private logger;
+    constructor(options?: {
+        maxSize?: number;
+        maxAgeMs?: number;
+        logger?: Logger;
+    });
+    /**
+     * 创建任务广播
+     */
+    create(announcement: Omit<TaskAnnouncement, 'announcementId' | 'timestamp' | 'status' | 'claims'>): TaskAnnouncement;
+    /**
+     * 获取所有开放的广播
+     */
+    getOpen(): TaskAnnouncement[];
+    /**
+     * 获取特定广播
+     */
+    get(announcementId: string): TaskAnnouncement | undefined;
+    /**
+     * 提交认领
+     */
+    submitClaim(announcementId: string, claim: Omit<TaskClaim, 'claimId' | 'timestamp' | 'status' | 'announcementId'>): TaskClaim | null;
+    /**
+     * 接受认领
+     * 使用锁机制防止竞态条件
+     *
+     * P1 修复：确保锁在任何情况下都能被释放，包括异常情况
+     */
+    acceptClaim(announcementId: string, claimId: string): TaskClaim | null;
+    /**
+     * 拒绝认领
+     */
+    rejectClaim(announcementId: string, claimId: string): TaskClaim | null;
+    /**
+     * 标记为已委托
+     */
+    markDelegated(announcementId: string): boolean;
+    /**
+     * 获取我的认领（作为认领方）
+     */
+    getMyClaims(claimantId: string): TaskClaim[];
+    /**
+     * 获取我的广播（作为发布方）
+     */
+    getMyAnnouncements(fromId: string): TaskAnnouncement[];
+    /**
+     * 获取统计
+     */
+    getStats(): AnnouncementQueueStats;
+    /**
+     * 清理过期
+     */
+    cleanup(): void;
+    /**
+     * 清空
+     */
+    clear(): void;
+    /**
+     * 强制清除孤立锁
+     * P1 修复：用于处理异常导致的锁未释放情况
+     *
+     * @param maxLockAgeMs 锁的最大存活时间（毫秒），默认 30 秒
+     * @returns 清除的锁数量
+     */
+    forceClearOrphanLocks(maxLockAgeMs?: number): number;
+    /**
+     * 检查是否有孤立锁
+     * 用于监控和调试
+     */
+    hasOrphanLocks(): boolean;
+}
+export declare function createAnnouncementQueue(options?: {
+    maxSize?: number;
+    maxAgeMs?: number;
+}): AnnouncementQueue;
+export declare const announcementQueue: AnnouncementQueue;
+export {};
+//# sourceMappingURL=announcement-queue.d.ts.map

package/dist/announcement-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"announcement-queue.d.ts","sourceRoot":"","sources":["../src/announcement-queue.ts"],"names":[],"mappings":"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"}

package/dist/announcement-queue.js

@@ -0,0 +1,307 @@
+"use strict";
+/**
+ * F2A Announcement Queue
+ * 管理任务广播和认领（Claim Pattern）
+ *
+ * 设计说明：
+ * - 默认导出类而非单例，便于测试和依赖注入
+ * - createAnnouncementQueue() 工厂函数提供默认实例
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.announcementQueue = exports.AnnouncementQueue = void 0;
+exports.createAnnouncementQueue = createAnnouncementQueue;
+const crypto_1 = require("crypto");
+const eventemitter3_1 = require("eventemitter3");
+class AnnouncementQueue extends eventemitter3_1.EventEmitter {
+    announcements = new Map();
+    maxSize;
+    maxAgeMs;
+    /** 正在处理的广播 ID 集合，用于防止并发操作 */
+    processingLocks = new Set();
+    logger;
+    constructor(options) {
+        super();
+        this.maxSize = options?.maxSize || 100;
+        this.maxAgeMs = options?.maxAgeMs || 30 * 60 * 1000; // 30分钟
+        this.logger = options?.logger || console;
+    }
+    /**
+     * 创建任务广播
+     */
+    create(announcement) {
+        // 清理过期
+        this.cleanup();
+        // 检查容量
+        if (this.announcements.size >= this.maxSize) {
+            this.logger.error('[F2A:Announce]  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-${(0, crypto_1.randomUUID)()}`;
+        const created = {
+            ...announcement,
+            announcementId: id,
+            timestamp: Date.now(),
+            status: 'open',
+            claims: []
+        };
+        this.announcements.set(id, created);
+        this.logger.info('[F2A:Announce]  create: announcementId=%s, from=%s, taskType=%s', id, announcement.from, announcement.taskType);
+        // 发出创建事件
+        this.emit('announcement:created', created);
+        return created;
+    }
+    /**
+     * 获取所有开放的广播
+     */
+    getOpen() {
+        // 在获取开放广播前先清理过期数据，避免返回过期数据
+        this.cleanup();
+        return Array.from(this.announcements.values())
+            .filter(a => a.status === 'open')
+            .sort((a, b) => a.timestamp - b.timestamp);
+    }
+    /**
+     * 获取特定广播
+     */
+    get(announcementId) {
+        return this.announcements.get(announcementId);
+    }
+    /**
+     * 提交认领
+     */
+    submitClaim(announcementId, claim) {
+        const announcement = this.announcements.get(announcementId);
+        if (!announcement) {
+            this.logger.warn('[F2A:Announce]  submitClaim: announcement not found, id=%s, claimant=%s', announcementId, claim.claimant);
+            return null;
+        }
+        if (announcement.status !== 'open') {
+            this.logger.warn('[F2A:Announce]  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) {
+            this.logger.info('[F2A:Announce]  submitClaim: duplicate claim ignored, id=%s, claimant=%s, existingClaimId=%s', announcementId, claim.claimant, existingClaim.claimId);
+            // 返回已存在的认领，而不是创建新的
+            return existingClaim;
+        }
+        // 使用 crypto.randomUUID() 生成唯一 ID
+        const claimId = `claim-${(0, crypto_1.randomUUID)()}`;
+        const created = {
+            ...claim,
+            claimId,
+            announcementId,
+            timestamp: Date.now(),
+            status: 'pending'
+        };
+        if (!announcement.claims) {
+            announcement.claims = [];
+        }
+        announcement.claims.push(created);
+        this.logger.info('[F2A:Announce]  submitClaim: claimId=%s, announcementId=%s, claimant=%s', claimId, announcementId, claim.claimant);
+        return created;
+    }
+    /**
+     * 接受认领
+     * 使用锁机制防止竞态条件
+     *
+     * P1 修复：确保锁在任何情况下都能被释放，包括异常情况
+     */
+    acceptClaim(announcementId, claimId) {
+        const announcement = this.announcements.get(announcementId);
+        if (!announcement) {
+            this.logger.warn('[F2A:Announce]  acceptClaim: announcement not found, id=%s, claimId=%s', announcementId, claimId);
+            return null;
+        }
+        // 检查是否已被锁定（正在被其他操作处理）
+        if (this.processingLocks.has(announcementId)) {
+            this.logger.warn('[F2A:Announce]  acceptClaim: announcement is being processed, id=%s, claimId=%s', announcementId, claimId);
+            return null;
+        }
+        // 检查广播状态
+        if (announcement.status !== 'open') {
+            this.logger.warn('[F2A:Announce]  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) {
+            this.logger.warn('[F2A:Announce]  acceptClaim: claim not found, announcementId=%s, claimId=%s', announcementId, claimId);
+            return null;
+        }
+        // 获取锁
+        this.processingLocks.add(announcementId);
+        try {
+            // 再次检查广播状态（双重检查）
+            if (announcement.status !== 'open') {
+                this.logger.warn('[F2A:Announce]  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';
+            this.logger.info('[F2A:Announce]  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，但不改变状态
+            this.logger.error('[F2A:Announce]  acceptClaim: unexpected error, id=%s, claimId=%s, error=%s', announcementId, claimId, error);
+            // 注意：不恢复状态，因为操作可能已部分完成
+            // 但锁会在 finally 中释放
+            return null;
+        }
+        finally {
+            // 确保锁在任何情况下都能被释放
+            this.processingLocks.delete(announcementId);
+        }
+    }
+    /**
+     * 拒绝认领
+     */
+    rejectClaim(announcementId, claimId) {
+        const announcement = this.announcements.get(announcementId);
+        if (!announcement) {
+            this.logger.warn('[F2A:Announce]  rejectClaim: announcement not found, id=%s, claimId=%s', announcementId, claimId);
+            return null;
+        }
+        const claim = announcement.claims?.find(c => c.claimId === claimId);
+        if (!claim) {
+            this.logger.warn('[F2A:Announce]  rejectClaim: claim not found, announcementId=%s, claimId=%s', announcementId, claimId);
+            return null;
+        }
+        claim.status = 'rejected';
+        this.logger.info('[F2A:Announce]  rejectClaim: claimId=%s, announcementId=%s, claimant=%s', claimId, announcementId, claim.claimant);
+        return claim;
+    }
+    /**
+     * 标记为已委托
+     */
+    markDelegated(announcementId) {
+        const announcement = this.announcements.get(announcementId);
+        if (!announcement)
+            return false;
+        announcement.status = 'delegated';
+        return true;
+    }
+    /**
+     * 获取我的认领（作为认领方）
+     */
+    getMyClaims(claimantId) {
+        const claims = [];
+        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) {
+        return Array.from(this.announcements.values())
+            .filter(a => a.from === fromId)
+            .sort((a, b) => b.timestamp - a.timestamp);
+    }
+    /**
+     * 获取统计
+     */
+    getStats() {
+        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() {
+        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 = {
+                        announcementId: announcement.announcementId,
+                        taskType: announcement.taskType,
+                        from: announcement.from,
+                        timestamp: announcement.timestamp,
+                        reason: 'timeout'
+                    };
+                    this.emit('announcement:expired', expiredEvent);
+                    this.logger.info('[F2A:Announce] 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) {
+            this.logger.info('[F2A:Announce]  cleanup: expired=%d, deleted=%d, remaining=%d', expiredCount, deletedCount, this.announcements.size);
+        }
+    }
+    /**
+     * 清空
+     */
+    clear() {
+        this.announcements.clear();
+        // P1 修复：同时清理孤立锁
+        this.processingLocks.clear();
+    }
+    /**
+     * 强制清除孤立锁
+     * P1 修复：用于处理异常导致的锁未释放情况
+     *
+     * @param maxLockAgeMs 锁的最大存活时间（毫秒），默认 30 秒
+     * @returns 清除的锁数量
+     */
+    forceClearOrphanLocks(maxLockAgeMs = 30000) {
+        // 由于当前实现没有记录锁的获取时间，我们只能清除所有锁
+        // 这是一个安全操作，因为锁只是为了防止并发，不会丢失数据
+        const count = this.processingLocks.size;
+        this.processingLocks.clear();
+        if (count > 0) {
+            this.logger.warn('[F2A:Announce]  forceClearOrphanLocks: cleared %d orphan locks', count);
+        }
+        return count;
+    }
+    /**
+     * 检查是否有孤立锁
+     * 用于监控和调试
+     */
+    hasOrphanLocks() {
+        return this.processingLocks.size > 0;
+    }
+}
+exports.AnnouncementQueue = AnnouncementQueue;
+// 工厂函数：创建新的 AnnouncementQueue 实例
+function createAnnouncementQueue(options) {
+    return new AnnouncementQueue(options);
+}
+// 默认实例（向后兼容，但建议使用依赖注入）
+exports.announcementQueue = new AnnouncementQueue();
+//# sourceMappingURL=announcement-queue.js.map