# @agentium/queue 中文文档

规范地址：https://npmcn.com/package/%40agentium/queue/

版本：4\.11\.0
npm 元数据更新时间：2026-10-23T22:21:40.146Z
中文译文更新时间：2026-11-08T06:19:58.107Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agentium/queue
原文对照：https://npmcn.com/package/%40agentium/queue/?lang=original
项目主页：https://agentium.in/
源码仓库：https://github.com/agentiumOS/agentium

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：73.7 kB，25 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：^22\.18\.0 \|\| ^24\.11\.0
- 运行依赖：0 个
- peer 依赖：bullmq ^5\.81\.5 \|\| ^6\.3\.11，ioredis ^5\.0\.0，@agentium/core ^4\.11\.0
- 首次发布：2026-05-22T13:04:44.300Z
- 最新版本发布：2026-10-23T22:21:39.940Z
- 近 30 天下载量：1881（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：40（近 12 个月 40 个）

## 中文简介

使用 BullMQ 处理 Aginium 代理的背景工作

## 安装

```sh
npm install @agentium/queue
```

也可以使用：`pnpm add @agentium/queue`、`yarn add @agentium/queue`、`bun add @agentium/queue`

## README

# @ agentium/队列

BullMQ 的背景代理、团队和工作流程执行 **5.81.5+ 在v5或 6.3.11+在v6之内** 需要22.18+或24.11+的节点。 新的队列可以使用 v6;在部署 v6 工人或作家之前,先用 v5 来迁移已持续存在的遗留重复记录.

```sh
npm install @agentium/queue bullmq@^6.3.11 ioredis
```

```ts
import { AgentQueue, AgentWorker } from "@agentium/queue";

const connection = "redis://127.0.0.1:6379/0";
const queue = new AgentQueue({ connection, defaultJobOptions: {
  attempts: 3, backoff: { type: "exponential", delay: 1000 },
} });
const worker = new AgentWorker({ connection, agentRegistry: { assistant: agent } });
await queue.enqueueAgentRun({ agentName: "assistant", input: "Summarize the report" });
await queue.schedule({ id: "daily-summary", cron: "0 9 * * *", timezone: "UTC",
  agent: { name: "assistant", input: "Summarize new reports" },
});
// The same ID updates its schedule; it does not create another scheduler.
await queue.unschedule("daily-summary");
await worker.stop();
await queue.close();
```

默认队列名称现在是 `agentium-jobs`;旧的 `agentium:jobs` 被当前 BullMQ 拒绝,因为队列名称不能包含冒号。 设置相同的显式, 有效 `queueName` 生产者和工人继续现有部署。 通过节点的无害环境管理兼容性加载BullMQ的构造器 `createRequire`。Redis URL 保存证书、数据库和 `rediss:` TLS 设置 .

`schedule` 完全接受一个 `agent`, (中文(简体) ), `team` 或者说 `workflow` 目标,并使用稳定的呼叫器提供的工作调度器ID。 工作流有效载荷 `initialState`, (中文(简体) ), `sessionId`, (中文(简体) ), `userId` 财务报告和审定财务报表 `tenantId` 输入 `Workflow.run`特工和小队还有前方身份 队列访问是一个可信赖的主机边界:在排队前认证出厂商并授权这些诉求;一个Redis有效载荷不是身份证明.

重试配置属于制片人 `defaultJobOptions` 或个人排序选项。 前一个 `WorkerConfig.attempts/backoffDelay` 字段从未控制 BullMQ 工作;它们已经从 TypeScript API 中删除。 JavaScript呼叫器在BullMQ或连接被初始化之前仍然收到迁移诊断. 重试有效剂工作需要应用一能. `cancelJob` 删除等待/延迟的工作,不能取消活动锁定的工作. `stop` 耗尽了积极的工作,并报告了其暂停时间;它没有声称远程效应被卷回了.

## 重复时间表迁移

BullMQ v6去除遗留的重复API. `listLegacySchedules()` 财务报告和审定财务报表 `removeLegacySchedule()` 需要安装 BullMQ v5 , 并在 v6 上明显失败, 包括在干净的队列上。 在v6时, `schedule`,反复排队和 `listSchedules` 拒绝包含遗留元数据的队列;他们不会移动或默默地隐藏它。 见 [官方 v5 至 v6 迁移指南](https://docs.bullmq.io/guide/migrations/migrate-from-v5-to-v6)。 。 。 .

与 BullMQ 5.81.5 (或相容的 v5 发布) 进行以下维护. 遗产记录留在Redis,直到操作员将其取出. 不要同时运行旧的和新的调度写入器 .

1.  停止列表作者, 呼叫 `queue.pause()`,让积极的工作完成,然后阻止工人. `removeLegacySchedule` 需要暂停队列和零活动任务.
2.  保存 `await queue.listLegacySchedules()` 和原始应用有效载荷/选择。 清单包括钥匙、名称、克龙、时区和下个时间戳;它不是完整的有效载荷备份。 更改前备份 Redis .
3.  选择稳定的新ID并调试想要的调度集 。 删除每个遗留密钥 `removeLegacySchedule(key)` 打电话前 `schedule`。新的创建拒绝匹配的后继名称/冠来防止意外重叠.
4.  校验 `listLegacySchedules()` 整个队列均为空并 `listSchedules()` 里面有预定的身份证 关闭v5维护客户端. 部署6名工人和作家,核实 `listSchedules()` 再来一次 `await queue.resume()` 并启用排程写入器.
5.  要回滚,停用v6工人/写作员,在停用并排出水时再回v5. 删除使用替换的ID `unschedule`,用已保存的原始 BullMQ 重复选项和有效载荷(或恢复 Redis 备份)来恢复旧记录,验证库存,并重新启动旧部署. 替换活动时永远不要恢复遗留记录 .

方便之处 `enqueue*({repeat})` API现在使用散列的目标,有效载荷和重复选项来提升排程. 改变散列的有效载荷; 使用 `schedule({id})` 当您需要稳定更新时. `listSchedules` 不包括v5上的遗留记录,并拒绝在v6上的遗留记录. BullMQ 在重复索引中存储两种格式:适配器通过返回的方式识别新的调度器 `iterationCount` 并且还处理旧后遗留键的v6 SDK诊断. 移民检查并不是一个与同时存在的遗产作者对立的锁;仍然需要加以制止.

## 核查

在构建核心后从寄存器根运行此命令 :

```sh
AGENTIUM_REDIS_TEST=1 AGENTIUM_REDIS_PORT=6389 npx vitest run packages/queue/src/__tests__
```

使用一次性的 Redis 数据库 。 Fixtures 创建出独特的队列,并只去除这些队列. 中情局对一个孤立的Redis 7服务进行监视 他们行使真实的公牛MQ 5.81.5和6.3.11 SDKs:调度员升迁/搬运,v5坚持被v6所拒绝的遗留数据,被明确暂停的v5迁移,v6使用迁移的调度员记录,更古老的遗留钥匙拒绝,工人身份/进度隔离和持久交付. 固定装置使用 `bullmq-v5` v5 维护过程的开发别名; 它不模仿 SDK 方法. Redis Cluster和可替代的BullMQ后端在此固定器外.

## 持久交付

`DurableAgentQueue` 财务报告和审定财务报表 `DurableAgentWorker` 使用单独的 `agentium-durable` 队列。 任务商店拥有执行状态;Redis发送一个版本提示,其中只包含租户/任务ID和一个不可改变的定义摘要. 现有代理人/团队/工人保持他们目前的行为.

```ts
import { DurableAgentQueue, DurableAgentWorker } from '@agentium/queue';
// supervisor uses the same initialized durable store on all workers.
const durable = new DurableAgentQueue({ connection, supervisor, admit: admitTask });
const durableWorker = new DurableAgentWorker({
  connection, supervisor, admit: recheckCurrentGrants,
  drivers: [{ id: 'save-document', version: 1, recoverable: true, execute: saveDocument }],
});
await durable.enqueue({
  id: taskId, identity: verifiedIdentity, manifestHash, inputRef,
  policyRevision: 1, grantRefs: approvedGrants,
  driver: { id: 'save-document', version: 1 }, input: { documentRef },
});
```

这两种回调都是强制性的被信任-宿主接收边界. 生产者录取发生在持久性之前;工人录取发生在原子主张前后. 版本驱动程序必须明确支持用稳定的动作ID来重放并调节. 注册普通代理/团队/工作流程功能不能确定该财产.

恒定先于雷地斯入等. 如果 enqueue 失败, 任务仍然可以恢复: 重试相同的不可更改的定义或调用 `wake({tenantId, taskId})`在批准或和解之后醒一醒。 重复交货由商店用栅栏围住;早期再试仍然被拖延,直到现有租约可以收回。 已完成的任务交付只将任务/状态/修改后的元数据返回Redis. 未知的外部结果会阻碍处理器执行直至对齐 .

`cancel` 继续取消并唤醒工人;它不要求立即远程解雇。 主机必须重试 `wake` 当 Redis 不可用时. `stop` 排出积极的工作。 维持一个主机恢复扫描, 以检查持续的工作, 而无需发送提示; 此软件包不会扫描任意存储或启动隐藏的背景服务 。 见 [长期储存和回收合同](https://npmcn.com/package/%40agentium/core/src/durable/README.md)。 。 。 .

## 常见问题

### @agentium/queue 是什么？

使用 BullMQ 处理 Aginium 代理的背景工作

### 如何安装 @agentium/queue？

在项目目录运行 npm install @agentium/queue，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@agentium/core（^4\.11\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @agentium/queue 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @agentium/queue 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @agentium/queue 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.18\.0 \|\| ^24\.11\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @agentium/queue 可以商用吗？

@agentium/queue 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @agentium/queue 的下载量有多少？

根据 npm 官方下载统计，@agentium/queue 在 2026/10/05 – 2026/11/03 这 30 天内被下载 1,881 次，日均约 63 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agentium/queue 还在维护吗？

最新版本 4\.11\.0 发布于 2026/10/24（15 天前）；至今共发布 40 个版本，其中过去 12 个月发布了 40 个；首次发布于 2026/05/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。