@gt-fe/eap-runtime 0.0.8

package/dist/checkpoint/pg-checkpoint-saver.js

@@ -0,0 +1,140 @@
+/**
+ * PostgresCheckpointSaver — PostgreSQL 存储（主存储）
+ *
+ * 使用接口抽象，不引入 pg 依赖。参数占位符用 $1/$2 替代 MySQL 的 ?。
+ * 支持审计字段和软删除。
+ *
+ * @see design.md §1.3 checkpoints 数据模型
+ * @see checkpoint-saver.contract.ts ICheckpointSaver 接口定义
+ */
+// ─────────────────────────────────────────────
+// PostgresCheckpointSaver
+// ─────────────────────────────────────────────
+export class PostgresCheckpointSaver {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /**
+     * 持久化 Checkpoint（INSERT or UPDATE）
+     */
+    async save(threadId, data) {
+        const sql = `
+      INSERT INTO checkpoints (id, thread_id, checkpoint_id, current_node_id, history_path, state, created_by, created_at, updated_by, updated_at)
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+      ON CONFLICT (thread_id, checkpoint_id) DO UPDATE SET
+        current_node_id = EXCLUDED.current_node_id,
+        history_path = EXCLUDED.history_path,
+        state = EXCLUDED.state,
+        updated_by = EXCLUDED.updated_by,
+        updated_at = EXCLUDED.updated_at
+    `;
+        await this.pool.query(sql, [
+            data.checkpointId,
+            threadId,
+            data.checkpointId,
+            data.currentNodeId,
+            JSON.stringify(data.historyPath),
+            JSON.stringify(data.state),
+            data.createdBy || 'system',
+            data.createdAt,
+            data.updatedBy || 'system',
+            data.updatedAt,
+        ]);
+    }
+    /**
+     * 加载指定 thread 的最新 Checkpoint
+     * Excludes soft-deleted records
+     */
+    async load(threadId) {
+        const sql = `SELECT * FROM checkpoints WHERE thread_id = $1 AND is_deleted = FALSE ORDER BY created_at DESC LIMIT 1`;
+        const { rows } = await this.pool.query(sql, [threadId]);
+        return rows[0] ? this.toCheckpointData(rows[0]) : null;
+    }
+    /**
+     * 按 checkpointId 加载特定 Checkpoint
+     * Excludes soft-deleted records
+     */
+    async loadByCheckpointId(checkpointId) {
+        const sql = `SELECT * FROM checkpoints WHERE checkpoint_id = $1 AND is_deleted = FALSE LIMIT 1`;
+        const { rows } = await this.pool.query(sql, [checkpointId]);
+        return rows[0] ? this.toCheckpointData(rows[0]) : null;
+    }
+    /**
+     * 列出指定 thread 的所有 Checkpoint
+     * Excludes soft-deleted records
+     */
+    async list(threadId) {
+        const sql = `SELECT * FROM checkpoints WHERE thread_id = $1 AND is_deleted = FALSE ORDER BY created_at ASC`;
+        const { rows } = await this.pool.query(sql, [threadId]);
+        return rows.map(r => this.toCheckpointData(r));
+    }
+    /**
+     * Soft delete checkpoint
+     */
+    async softDelete(checkpointId, deletedBy) {
+        const sql = `
+      UPDATE checkpoints
+      SET is_deleted = TRUE, deleted_by = $1, deleted_at = NOW()
+      WHERE checkpoint_id = $2 AND is_deleted = FALSE
+    `;
+        await this.pool.query(sql, [deletedBy, checkpointId]);
+    }
+    /**
+     * Fork：从指定 Checkpoint 创建新的执行线程
+     *
+     * 用于用户调试场景，从某个 Checkpoint 恢复执行，支持修改参数后重新执行。
+     *
+     * @param sourceCheckpointId - 源 Checkpoint ID
+     * @param newThreadId - 新线程 ID
+     * @param overrides - 覆盖的参数（可选）
+     * @returns 新的 CheckpointData
+     */
+    async fork(sourceCheckpointId, newThreadId, overrides) {
+        // 1. 加载源 Checkpoint
+        const source = await this.loadByCheckpointId(sourceCheckpointId);
+        if (!source) {
+            throw new Error(`Source checkpoint not found: ${sourceCheckpointId}`);
+        }
+        // 2. 创建新的 CheckpointData
+        const now = new Date().toISOString();
+        const newCheckpointId = crypto.randomUUID();
+        const newData = {
+            checkpointId: newCheckpointId,
+            threadId: newThreadId,
+            currentNodeId: source.currentNodeId,
+            historyPath: source.historyPath,
+            state: overrides ? { ...source.state, ...overrides } : source.state,
+            createdBy: 'fork',
+            createdAt: now,
+            updatedBy: 'fork',
+            updatedAt: now,
+            isDeleted: false,
+        };
+        // 3. 保存新的 Checkpoint
+        await this.save(newThreadId, newData);
+        return newData;
+    }
+    // ─────────────────────────────────────────────
+    // Private Helpers
+    // ─────────────────────────────────────────────
+    /**
+     * 将 PostgreSQL 行数据转换为 CheckpointData
+     */
+    toCheckpointData(row) {
+        return {
+            checkpointId: row.checkpoint_id,
+            threadId: row.thread_id,
+            currentNodeId: row.current_node_id,
+            historyPath: typeof row.history_path === 'string' ? JSON.parse(row.history_path) : row.history_path,
+            state: typeof row.state === 'string' ? JSON.parse(row.state) : row.state,
+            createdBy: row.created_by,
+            createdAt: row.created_at.toISOString(),
+            updatedBy: row.updated_by,
+            updatedAt: row.updated_at.toISOString(),
+            isDeleted: row.is_deleted,
+            deletedBy: row.deleted_by,
+            deletedAt: row.deleted_at?.toISOString(),
+        };
+    }
+}

package/dist/checkpoint/redis-checkpoint-saver.d.ts

@@ -0,0 +1,68 @@
+/**
+ * RedisCheckpointSaver — 基于 Redis 的 Checkpoint 持久化实现
+ *
+ * Key 模式：
+ * - 单个 Checkpoint: `thread:{threadId}:cp:{checkpointId}` → JSON 序列化的 CheckpointData
+ * - Thread 索引（Sorted Set）: `thread:{threadId}:checkpoints` → member=checkpointId, score=createdAt timestamp
+ * - 最新指针: `thread:{threadId}:latest` → 存储最新 checkpointId
+ * - 反向索引: `cp:{checkpointId}:thread` → 存储 threadId（供 loadByCheckpointId 使用）
+ *
+ * @see design.md §1.3 checkpoints 数据模型
+ */
+import type { Redis } from 'ioredis';
+import type { ICheckpointSaver } from './contracts/checkpoint-saver.contract.js';
+import type { CheckpointData } from '../graph/contracts/executable-graph.js';
+/**
+ * RedisCheckpointSaver 配置选项
+ */
+export interface RedisCheckpointSaverOptions {
+    /** Key 前缀（默认无前缀） */
+    keyPrefix?: string;
+    /** Checkpoint TTL（秒），默认不过期 */
+    ttl?: number;
+}
+/**
+ * RedisCheckpointSaver — ICheckpointSaver 的 Redis 实现
+ *
+ * 通过构造函数注入 ioredis 实例（DI 友好），支持可选的 TTL 和 key 前缀配置。
+ */
+export declare class RedisCheckpointSaver implements ICheckpointSaver {
+    private readonly redis;
+    private readonly keyPrefix;
+    private readonly ttl;
+    constructor(redis: Redis, options?: RedisCheckpointSaverOptions);
+    private checkpointKey;
+    private threadIndexKey;
+    private latestKey;
+    private reverseIndexKey;
+    /**
+     * 持久化 Checkpoint
+     *
+     * 原子操作：SET checkpoint JSON + ZADD 到 thread 索引 + SET latest 指针 + SET 反向索引
+     * 使用 Redis pipeline 保证原子性和性能。
+     */
+    save(threadId: string, data: CheckpointData): Promise<void>;
+    /**
+     * 加载指定 thread 的最新 Checkpoint
+     *
+     * 流程：GET latest 指针 → GET checkpoint JSON → 解析返回
+     */
+    load(threadId: string): Promise<CheckpointData | null>;
+    /**
+     * 按 checkpointId 加载特定 Checkpoint
+     *
+     * 流程：通过反向索引 `cp:{checkpointId}:thread` 找到 threadId → GET checkpoint JSON
+     */
+    loadByCheckpointId(checkpointId: string): Promise<CheckpointData | null>;
+    /**
+     * 列出指定 thread 的所有 Checkpoint
+     *
+     * 流程：ZRANGE thread 索引获取所有 checkpointId → 批量 GET → 解析返回
+     * 结果按 createdAt 升序排列（Sorted Set score 升序）。
+     */
+    list(threadId: string): Promise<CheckpointData[]>;
+    /**
+     * Fork: 从指定 Checkpoint 创建新的执行线程
+     */
+    fork(sourceCheckpointId: string, newThreadId: string, overrides?: Record<string, unknown>): Promise<import('../graph/contracts/executable-graph.js').CheckpointData>;
+}

package/dist/checkpoint/redis-checkpoint-saver.js

@@ -0,0 +1,173 @@
+/**
+ * RedisCheckpointSaver — 基于 Redis 的 Checkpoint 持久化实现
+ *
+ * Key 模式：
+ * - 单个 Checkpoint: `thread:{threadId}:cp:{checkpointId}` → JSON 序列化的 CheckpointData
+ * - Thread 索引（Sorted Set）: `thread:{threadId}:checkpoints` → member=checkpointId, score=createdAt timestamp
+ * - 最新指针: `thread:{threadId}:latest` → 存储最新 checkpointId
+ * - 反向索引: `cp:{checkpointId}:thread` → 存储 threadId（供 loadByCheckpointId 使用）
+ *
+ * @see design.md §1.3 checkpoints 数据模型
+ */
+/**
+ * RedisCheckpointSaver — ICheckpointSaver 的 Redis 实现
+ *
+ * 通过构造函数注入 ioredis 实例（DI 友好），支持可选的 TTL 和 key 前缀配置。
+ */
+export class RedisCheckpointSaver {
+    redis;
+    keyPrefix;
+    ttl;
+    constructor(redis, options) {
+        this.redis = redis;
+        this.keyPrefix = options?.keyPrefix ?? '';
+        this.ttl = options?.ttl;
+    }
+    // ─────────────────────────────────────────────
+    // Key 构建辅助
+    // ─────────────────────────────────────────────
+    checkpointKey(threadId, checkpointId) {
+        return `${this.keyPrefix}thread:${threadId}:cp:${checkpointId}`;
+    }
+    threadIndexKey(threadId) {
+        return `${this.keyPrefix}thread:${threadId}:checkpoints`;
+    }
+    latestKey(threadId) {
+        return `${this.keyPrefix}thread:${threadId}:latest`;
+    }
+    reverseIndexKey(checkpointId) {
+        return `${this.keyPrefix}cp:${checkpointId}:thread`;
+    }
+    // ─────────────────────────────────────────────
+    // ICheckpointSaver 实现
+    // ─────────────────────────────────────────────
+    /**
+     * 持久化 Checkpoint
+     *
+     * 原子操作：SET checkpoint JSON + ZADD 到 thread 索引 + SET latest 指针 + SET 反向索引
+     * 使用 Redis pipeline 保证原子性和性能。
+     */
+    async save(threadId, data) {
+        const cpKey = this.checkpointKey(threadId, data.checkpointId);
+        const idxKey = this.threadIndexKey(threadId);
+        const ltKey = this.latestKey(threadId);
+        const revKey = this.reverseIndexKey(data.checkpointId);
+        const json = JSON.stringify(data);
+        const score = new Date(data.createdAt).getTime();
+        const pipeline = this.redis.pipeline();
+        // 存储 Checkpoint JSON
+        if (this.ttl) {
+            pipeline.set(cpKey, json, 'EX', this.ttl);
+        }
+        else {
+            pipeline.set(cpKey, json);
+        }
+        // Thread 索引 (Sorted Set): checkpointId 作为 member, createdAt timestamp 作为 score
+        pipeline.zadd(idxKey, score, data.checkpointId);
+        // 最新指针
+        pipeline.set(ltKey, data.checkpointId);
+        // 反向索引: checkpointId → threadId
+        if (this.ttl) {
+            pipeline.set(revKey, threadId, 'EX', this.ttl);
+        }
+        else {
+            pipeline.set(revKey, threadId);
+        }
+        // 对索引和 latest 指针也设置 TTL（如果配置了）
+        if (this.ttl) {
+            pipeline.expire(idxKey, this.ttl);
+            pipeline.expire(ltKey, this.ttl);
+        }
+        await pipeline.exec();
+    }
+    /**
+     * 加载指定 thread 的最新 Checkpoint
+     *
+     * 流程：GET latest 指针 → GET checkpoint JSON → 解析返回
+     */
+    async load(threadId) {
+        const ltKey = this.latestKey(threadId);
+        const latestCheckpointId = await this.redis.get(ltKey);
+        if (!latestCheckpointId) {
+            return null;
+        }
+        const cpKey = this.checkpointKey(threadId, latestCheckpointId);
+        const json = await this.redis.get(cpKey);
+        if (!json) {
+            return null;
+        }
+        return JSON.parse(json);
+    }
+    /**
+     * 按 checkpointId 加载特定 Checkpoint
+     *
+     * 流程：通过反向索引 `cp:{checkpointId}:thread` 找到 threadId → GET checkpoint JSON
+     */
+    async loadByCheckpointId(checkpointId) {
+        const revKey = this.reverseIndexKey(checkpointId);
+        const threadId = await this.redis.get(revKey);
+        if (!threadId) {
+            return null;
+        }
+        const cpKey = this.checkpointKey(threadId, checkpointId);
+        const json = await this.redis.get(cpKey);
+        if (!json) {
+            return null;
+        }
+        return JSON.parse(json);
+    }
+    /**
+     * 列出指定 thread 的所有 Checkpoint
+     *
+     * 流程：ZRANGE thread 索引获取所有 checkpointId → 批量 GET → 解析返回
+     * 结果按 createdAt 升序排列（Sorted Set score 升序）。
+     */
+    async list(threadId) {
+        const idxKey = this.threadIndexKey(threadId);
+        // ZRANGE 默认升序（按 score 即 createdAt timestamp）
+        const checkpointIds = await this.redis.zrange(idxKey, 0, -1);
+        if (checkpointIds.length === 0) {
+            return [];
+        }
+        // 批量获取所有 Checkpoint JSON（使用 pipeline 减少 RTT）
+        const pipeline = this.redis.pipeline();
+        for (const cpId of checkpointIds) {
+            pipeline.get(this.checkpointKey(threadId, cpId));
+        }
+        const results = await pipeline.exec();
+        const checkpoints = [];
+        if (results) {
+            for (const [err, json] of results) {
+                if (!err && json && typeof json === 'string') {
+                    checkpoints.push(JSON.parse(json));
+                }
+            }
+        }
+        return checkpoints;
+    }
+    /**
+     * Fork: 从指定 Checkpoint 创建新的执行线程
+     */
+    async fork(sourceCheckpointId, newThreadId, overrides) {
+        const source = await this.loadByCheckpointId(sourceCheckpointId);
+        if (!source) {
+            throw new Error(`Source checkpoint not found: ${sourceCheckpointId}`);
+        }
+        const now = new Date().toISOString();
+        const { randomUUID } = await import('node:crypto');
+        const newData = {
+            checkpointId: randomUUID(),
+            threadId: newThreadId,
+            currentNodeId: source.currentNodeId,
+            historyPath: source.historyPath,
+            state: overrides ? { ...source.state, ...overrides } : source.state,
+            createdBy: 'fork',
+            createdAt: now,
+            updatedBy: 'fork',
+            updatedAt: now,
+            isDeleted: false,
+        };
+        await this.save(newThreadId, newData);
+        return newData;
+    }
+}

package/dist/checkpoint/restore-checkpoint.d.ts

@@ -0,0 +1,33 @@
+/**
+ * restoreCheckpoint — 供 05-Trace/Replay 模块使用的便捷函数
+ *
+ * 薄封装 ICheckpointSaver.loadByCheckpointId，提供明确的语义入口：
+ * 通过 checkpointId 恢复特定 Graph 状态，用于 Replay/Fork 场景。
+ *
+ * @see design.md §1.3 Checkpoint 数据模型
+ * @see requirements.md Requirement 2 AC4（按 checkpointId 加载 Replay/Fork）
+ */
+import type { ICheckpointSaver } from './contracts/checkpoint-saver.contract.js';
+import type { CheckpointData } from '../graph/contracts/executable-graph.js';
+/**
+ * 通过 checkpointId 恢复特定的 Graph 状态快照
+ *
+ * 供 05-Trace/Replay 模块调用，实现 Replay（重放）和 Fork（分叉）功能。
+ * 内部委托给注入的 ICheckpointSaver 实例。
+ *
+ * @param checkpointId - 目标 Checkpoint 唯一 ID
+ * @param saver - ICheckpointSaver 实现实例（通常为 CompositeCheckpointSaver）
+ * @returns 对应的 CheckpointData，不存在时返回 null
+ *
+ * @example
+ * ```typescript
+ * import { restoreCheckpoint, CompositeCheckpointSaver } from '@eap/runtime';
+ *
+ * const checkpoint = await restoreCheckpoint('cp-abc-123', compositeCheckpointSaver);
+ * if (checkpoint) {
+ *   // 使用 checkpoint.state 恢复 Graph 执行
+ *   // 使用 checkpoint.currentNodeId 确定恢复起点
+ * }
+ * ```
+ */
+export declare function restoreCheckpoint(checkpointId: string, saver: ICheckpointSaver): Promise<CheckpointData | null>;

package/dist/checkpoint/restore-checkpoint.js

@@ -0,0 +1,33 @@
+/**
+ * restoreCheckpoint — 供 05-Trace/Replay 模块使用的便捷函数
+ *
+ * 薄封装 ICheckpointSaver.loadByCheckpointId，提供明确的语义入口：
+ * 通过 checkpointId 恢复特定 Graph 状态，用于 Replay/Fork 场景。
+ *
+ * @see design.md §1.3 Checkpoint 数据模型
+ * @see requirements.md Requirement 2 AC4（按 checkpointId 加载 Replay/Fork）
+ */
+/**
+ * 通过 checkpointId 恢复特定的 Graph 状态快照
+ *
+ * 供 05-Trace/Replay 模块调用，实现 Replay（重放）和 Fork（分叉）功能。
+ * 内部委托给注入的 ICheckpointSaver 实例。
+ *
+ * @param checkpointId - 目标 Checkpoint 唯一 ID
+ * @param saver - ICheckpointSaver 实现实例（通常为 CompositeCheckpointSaver）
+ * @returns 对应的 CheckpointData，不存在时返回 null
+ *
+ * @example
+ * ```typescript
+ * import { restoreCheckpoint, CompositeCheckpointSaver } from '@eap/runtime';
+ *
+ * const checkpoint = await restoreCheckpoint('cp-abc-123', compositeCheckpointSaver);
+ * if (checkpoint) {
+ *   // 使用 checkpoint.state 恢复 Graph 执行
+ *   // 使用 checkpoint.currentNodeId 确定恢复起点
+ * }
+ * ```
+ */
+export async function restoreCheckpoint(checkpointId, saver) {
+    return saver.loadByCheckpointId(checkpointId);
+}

package/dist/common/agent-code.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Agent 对外主键解析（迁移期双读）
+ *
+ * 正式字段为 agentCode；历史 agentId 仅作同义兜底。
+ */
+export declare function resolveAgentCode(input: {
+    agentCode?: string | null;
+    agentId?: string | null;
+    fallback?: string;
+}): string;

package/dist/common/agent-code.js

@@ -0,0 +1,12 @@
+/**
+ * Agent 对外主键解析（迁移期双读）
+ *
+ * 正式字段为 agentCode；历史 agentId 仅作同义兜底。
+ */
+export function resolveAgentCode(input) {
+    const code = input.agentCode ?? input.agentId ?? input.fallback;
+    if (code == null || code === '') {
+        throw new Error('agentCode is required (agentId synonym accepted during migration)');
+    }
+    return String(code);
+}

package/dist/common/concurrency.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 并发控制模块
+ *
+ * 提供两种并发限制机制：
+ * 1. ConcurrencyLimiter — 基于 amqplib channel.prefetch 的 Agent 级并发控制
+ *    通过 RabbitMQ consumer prefetch 限制单 Agent 实例同时处理的任务数
+ * 2. Semaphore — 纯内存信号量，用于本地并发控制（不依赖 RabbitMQ）
+ *
+ * @see Requirement 14 AC2: 系统通过消息消费者 prefetch 参数控制单 Agent 实例的并发上限（默认 prefetch=5）
+ */
+import type { Channel } from 'amqplib';
+/** ConcurrencyLimiter 默认 prefetch 值 */
+export declare const DEFAULT_PREFETCH = 5;
+/**
+ * 基于 amqplib consumer prefetch 的 Agent 级并发限制器
+ *
+ * RabbitMQ 的 channel.prefetch(n) 表示该 Channel 上的消费者最多同时
+ * 持有 n 条未确认消息。超出限制的消息留在 Queue 中排队等待。
+ *
+ * 整体 QPS = Pod 数 × prefetch。
+ */
+export declare class ConcurrencyLimiter {
+    private readonly prefetchCount;
+    /**
+     * @param prefetchCount 单 Agent 实例最大并发任务数，默认 5
+     */
+    constructor(prefetchCount?: number);
+    /**
+     * 配置 amqplib Channel 的 prefetch
+     *
+     * 调用后该 Channel 上的消费者最多同时处理 prefetchCount 条消息。
+     * 超出限制的消息在 RabbitMQ Queue 中排队等待。
+     *
+     * @param channel amqplib Channel 实例
+     */
+    configure(channel: Channel): Promise<void>;
+    /**
+     * 获取配置的最大并发数
+     */
+    getMaxConcurrency(): number;
+}
+/**
+ * 内存信号量 — 用于本地并发控制
+ *
+ * 当无需依赖 RabbitMQ 时（如单进程内限流、测试场景），
+ * 使用 Semaphore 控制并发执行数。
+ *
+ * 用法:
+ * ```ts
+ * const sem = new Semaphore(3);
+ * await sem.acquire(); // 等待可用槽位
+ * try {
+ *   // 执行并发受限的操作
+ * } finally {
+ *   sem.release(); // 释放槽位
+ * }
+ * ```
+ */
+export declare class Semaphore {
+    private readonly maxSlots;
+    private currentSlots;
+    private readonly waitQueue;
+    /**
+     * @param maxConcurrency 最大并发数
+     */
+    constructor(maxConcurrency: number);
+    /**
+     * 获取一个可用槽位。如果当前无可用槽位，则等待直到有释放。
+     */
+    acquire(): Promise<void>;
+    /**
+     * 释放一个槽位。如果有等待者，唤醒队列中最先等待的。
+     */
+    release(): void;
+    /**
+     * 当前可用槽位数
+     */
+    get availableSlots(): number;
+}

package/dist/common/concurrency.js

@@ -0,0 +1,121 @@
+/**
+ * 并发控制模块
+ *
+ * 提供两种并发限制机制：
+ * 1. ConcurrencyLimiter — 基于 amqplib channel.prefetch 的 Agent 级并发控制
+ *    通过 RabbitMQ consumer prefetch 限制单 Agent 实例同时处理的任务数
+ * 2. Semaphore — 纯内存信号量，用于本地并发控制（不依赖 RabbitMQ）
+ *
+ * @see Requirement 14 AC2: 系统通过消息消费者 prefetch 参数控制单 Agent 实例的并发上限（默认 prefetch=5）
+ */
+// ─────────────────────────────────────────────
+// ConcurrencyLimiter — RabbitMQ prefetch 并发控制
+// ─────────────────────────────────────────────
+/** ConcurrencyLimiter 默认 prefetch 值 */
+export const DEFAULT_PREFETCH = 5;
+/**
+ * 基于 amqplib consumer prefetch 的 Agent 级并发限制器
+ *
+ * RabbitMQ 的 channel.prefetch(n) 表示该 Channel 上的消费者最多同时
+ * 持有 n 条未确认消息。超出限制的消息留在 Queue 中排队等待。
+ *
+ * 整体 QPS = Pod 数 × prefetch。
+ */
+export class ConcurrencyLimiter {
+    prefetchCount;
+    /**
+     * @param prefetchCount 单 Agent 实例最大并发任务数，默认 5
+     */
+    constructor(prefetchCount = DEFAULT_PREFETCH) {
+        if (prefetchCount < 1) {
+            throw new Error(`prefetchCount must be >= 1, got ${prefetchCount}`);
+        }
+        this.prefetchCount = prefetchCount;
+    }
+    /**
+     * 配置 amqplib Channel 的 prefetch
+     *
+     * 调用后该 Channel 上的消费者最多同时处理 prefetchCount 条消息。
+     * 超出限制的消息在 RabbitMQ Queue 中排队等待。
+     *
+     * @param channel amqplib Channel 实例
+     */
+    async configure(channel) {
+        await channel.prefetch(this.prefetchCount);
+    }
+    /**
+     * 获取配置的最大并发数
+     */
+    getMaxConcurrency() {
+        return this.prefetchCount;
+    }
+}
+// ─────────────────────────────────────────────
+// Semaphore — 内存级信号量
+// ─────────────────────────────────────────────
+/**
+ * 内存信号量 — 用于本地并发控制
+ *
+ * 当无需依赖 RabbitMQ 时（如单进程内限流、测试场景），
+ * 使用 Semaphore 控制并发执行数。
+ *
+ * 用法:
+ * ```ts
+ * const sem = new Semaphore(3);
+ * await sem.acquire(); // 等待可用槽位
+ * try {
+ *   // 执行并发受限的操作
+ * } finally {
+ *   sem.release(); // 释放槽位
+ * }
+ * ```
+ */
+export class Semaphore {
+    maxSlots;
+    currentSlots;
+    waitQueue = [];
+    /**
+     * @param maxConcurrency 最大并发数
+     */
+    constructor(maxConcurrency) {
+        if (maxConcurrency < 1) {
+            throw new Error(`maxConcurrency must be >= 1, got ${maxConcurrency}`);
+        }
+        this.maxSlots = maxConcurrency;
+        this.currentSlots = maxConcurrency;
+    }
+    /**
+     * 获取一个可用槽位。如果当前无可用槽位，则等待直到有释放。
+     */
+    acquire() {
+        if (this.currentSlots > 0) {
+            this.currentSlots--;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this.waitQueue.push(resolve);
+        });
+    }
+    /**
+     * 释放一个槽位。如果有等待者，唤醒队列中最先等待的。
+     */
+    release() {
+        if (this.waitQueue.length > 0) {
+            const next = this.waitQueue.shift();
+            // 使用 microtask 调度，确保调用者的 finally 块先完成
+            Promise.resolve().then(next);
+        }
+        else {
+            this.currentSlots++;
+            if (this.currentSlots > this.maxSlots) {
+                this.currentSlots = this.maxSlots;
+            }
+        }
+    }
+    /**
+     * 当前可用槽位数
+     */
+    get availableSlots() {
+        return this.currentSlots;
+    }
+}