@gate-forge/pack-task

中文文档
0.19.2发布于 2026/11/10Apache-2.0TypeScriptES Module构建来源已验证近 30 天下载 2461

背景任务发现包:为BullMQ / Bee-Que /自定义队列 / 消息处理器 / 经常性任务 / @ 任务 @Que 装饰器 等同性能 + 重试- 政策 + 终端- on + 可观察性合同 审计- 运行的实体-a

中文使用文档
文档目录14 节
  1. 引擎级别证明: 队列观察员
  2. 这算什么 deliver 案件确实如此
  3. 真是个 attempts 规则解决
  4. 证明一下
  5. 如何发现工作
  6. 分类信号(第4阶段):无
  7. 探测器词汇
  8. 合同义务词汇
  9. 设置
  10. 实体适配器计划+审计线索
  11. 示例应用程序
  12. 横向覆盖
  13. 决定主义
  14. 发展

@ gate- forge/ pack- task

背景任务发现包: 纯TypeScript GPP/3 进程内探测器, 在其中查找背景任务签名 .ts编号 :.js编号 :.mjs 出处——没有Python子进程,没有执行,没有外部解析——加上一个审计-拖拉式实体适应器计划和一个实例服务器,可以证明五项义务与包索赔合同.

引擎级别证明: 队列观察员

一份背景工作的尝试, 终极状态和自强度生活在 QUEUE,所以引擎会读取队列本身. 测试本身的"工作" 成功"从来不是证明——完全像一个测试本身的HTTP状态. A 类 选择使用引擎拥有的仓库 queueObserver 块中 .gateforge.yml数字 :

queueObserver:
  kind: bullmq                       # or a module path whose default export is a factory
  connection:
    urlEnv: GATEFORGE_QUEUE_REDIS_URL   # host/port form: {host, port}
  queues:
    - name: mailer                   # the queue the engine reads
      taskResourceId: task.email.send
  pollIntervalMs: 100                # transition-sampling interval (default 200)
  terminalTimeoutMs: 30000           # bound on waiting for the delivery to settle
  • 这个街区住在这里 .gateforge.yml,所以它是在信任的政策内 文摘:候选人不能将引擎指向它控制的队列.
  • 连接材料从不带秘密内线—— URL 格式名称 wITNESS 进程私下解决的环境变量 值永远不会被封入记录、报表或 argv.
  • kind: bullmq 读取项目本身的队列 bullmq 财务报告和审定财务报表 ioredis (可选的同行 @gate-forge/witness: 下一个安装 对应用, npm install --save-dev bullmq ioredis) (中文(简体) ). 一个项目 宣布没有 BullMQ 观察者从未安装或加载过它们; 其中之一 宣告没有安装命令的关闭失败 .
  • 没有障碍 task 名称空间是 无 (每个 task:* 合同未终止,原因 VERIFIER_UNSUPPORTED和每个 engine-task 带有命名诊断的病例块. gateforge init 因此,建议这个包的病例 只有在块是 已配置 .
  • test-gates 将声明交给证人 (单位:千美元)GATEFORGE_QUEUE_OBSERVER + 键 GATEFORGE_QUEUE_OBSERVER_CONFIG页:1 没有块的寄存器没有传递任何信息 及其产卵环境 字节相同.

这算什么 deliver 案件确实如此

引擎生产送货,而不是套房,它给送货盖上印章 身份、一能键和受约束的尝试(取自 案件属于自己 attempts 规则,所以政策宣布重试约束 然后投票排队,直到每个工作都解决 封住它读的. count 一. 一体原则 密钥——这就是使一个重复的密钥案件成为重复的情况——而每个重复的密钥都成为重复 送货者有自己的身份.

真是个 attempts 规则解决

外地含义
resourceId案件交付的任务资源(必须与动作匹配)
count已声明的尝试绑定: 任何任务都不得超过它, 队列本身已声明的约束也不得超过它
terminalsucceeded (每一项工作) completed, (中文(简体) ), failed (每一项工作) failed, (中文(简体) ), rejected (每份工作都失败了)
minAttempts (可选)每一个工作至少使用这么多尝试——"重复到N"无法满足于从未重复过的队列
recoveredFromStall (可选)引擎本身的时间表必须显示一个丢失的工人回收:与UNCHANGED尝试再次完成的同样工作,没有失败原因(错误重试会同时引起两个问题)——交货仍然结算

宣布不交货的案件 attempts 规则解决无 并且是 被屏蔽( e)BEHAVIOR_BINDING_MISMATCH),以及一个带有HTTP的病例 尝试或浏览器观察被断然拒绝: 运输索赔,不是背景工作.

证明一下

packages/cli/test/task-queue-behavior-e2e.test.ts 运行真正的CLI, 真正的证人和真实的BullMQ申请(example/task-bullmq/数字 : 排队加工人流程,其中之一是真正失去中途工作) 对一个一次性的Redis。 每艘合同船都有一个故障变体 必须屏蔽。 套房 SPIPS 除非 GATEFORGE_TEST_REDIS_URL 名称 a live Redis — 引擎的队列读取器需要真实的队列,以及假的队列 作为证据

docker run -d --rm --name gateforge-queue-redis -p 127.0.0.1:6379 redis:7-alpine
GATEFORGE_TEST_REDIS_URL=redis://127.0.0.1:6379 npm test -- task-queue-behavior-e2e

如何发现工作

探测器扫描 .ts编号 :.tsx编号 :.js编号 :.mjs 带有基于 regex 的 AST 光线图案的文件(匹配) pack-auth战略 它承认下面的任务构造,并通过发现结果的被打入的阻塞词汇来报告其判断——包没有发出自己的资源,也没有分类信号:

源构造确认为
new Queue('email.send', ...) 编号 : new BullMQ.Queue(...)BullMQ 任务 + 重试策略 defaultJobOptions
new Bee('image.resize', ...)Bee 队列任务
register('webhook.dispatch', handler)自定义队列任务( 单行)
new CustomQueue({ name, handler, ... })自定义队列任务( 多行、 平衡的行走)
navigator.serviceWorker.register(...) 编号 : *.serviceWorker.register(...) 编号 : serviceWorkerRegistration.register(...) 编号 : workbox.* 编号 : caches.* 编号 : window.* 编号 : document.*无-浏览器/平台注册 API,从不任务队列(在匹配前被排除). 接收器链通过MULTI-LINE调用表达式重建,所以 navigator.serviceWorker 在自己的线路上方 register(...) 续行仍然被排除在外(准确的 统一狗粮假阳性)
onmessage = handler 编号 : .on('message', ...) 编号 : addEventListener('message', ...)信件处理器任务
setInterval(handler, ms, ...) 编号 : setImmediate(handler, ...)经常性任务
@Task(...) 编号 : @Queue(...) 装饰说明装饰任务

分类信号(第4阶段):无

薄荷薄荷包 没有 classificationSignals它曾经排放过 internality编号 :worker 以模型名称为目标的可达到性信号 从工人档案(模型/存储器导入路径段, 每一个 PascalCase 标识符,被剥去的任务名碎片). 这些 目标是猜测其他探测器的资源——这个包 发现没有资源本身, 因此在真实的重置中它们大多匹配 无所事事 每一次失事都浮出水面 STALE_SIGNAL_TARGET 屏蔽器 (统一狗粮中236个),而未添加信息:未知 曝光已经默认了用户化和未知的生命周期 启用了默认值( ADR 0003 D5), 因此删除不翻转分类和 缩放未设定义务。 科雷尔的 STALE_SIGNAL_TARGET 检测 留作真正僵硬的权威信号 这个 trustedInternalEntryPoints 约束工人类别 (单位:千美元)detector: gateforge.pack-task(在战术上仍然有效,但 未执行:依赖被猜想的工人的内部特性证明 现在完全无法到达 (单位:千美元)INCOMPLETE_PROOF_SCOPE, 保守的用户提示默认值) 根据猜测.

探测器词汇

  • 公认的任务清单 - 每种公认的建筑都载有:

    • retryPolicy: { maxAttempts: number, backoff: 'fixed' | 'exponential' } - 从 defaultJobOptions.attempts 编号 : .backoff.type,默认为 {maxAttempts: 1, backoff: 'fixed'}。 。 。 .
    • idempotencyKey: boolean ——如果 jobId 编号 : dedupKey 编号 : idempotencyKey 编号 : dedupe 显示于源代码.
    • terminalOn: string[] ——错误类型 terminalOn: [...] (terminal = 不重试).
    • observability: boolean ——如果 metrics 编号 : tracing 编号 : .on('completed'|'failed'|'stalled', ...) 出现.
    • source: { file, line, col } ——申报位置.
    • framework: 'bullmq' | 'bee-queue' | 'custom-queue' | 'message-handler' | 'recurring' | 'decorator'。 。 。 .

    库存本身没有排放在电线上(没有资源,没有) 它驱动下面的阻塞词汇和 债务与一揽子索赔合同.

  • 调查结果

    • DUPLICATE_TASK_ID ——同名id发现两次;先取胜.
    • AMBIGUOUS_HANDLER —— 说 register(...) 或者说 new CustomQueue(...) 没有可解决的处理器参考。 单行 register(...) 形状此火 只在文件显示真实队列证据时( 从已知队列库导入) - bullmq, (中文(简体) ), bull, (中文(简体) ), bee-queue, (中文(简体) ), celery, (中文(简体) ), kue, (中文(简体) ), agenda, (中文(简体) ), pg-boss, (中文(简体) ), sidekiq ——队列命名模块,或队列构造器等 new Queue(...) 编号 : new CustomQueue(...)) (中文(简体) ).
    • PARSE_ERROR 文件无法读取 .
  • 未解决

    • UNPROVEN_QUEUE_REGISTRATION - 一个没有处理器的人 register('name') 在没有队列证据的文件中: 形状不能证明是任务登记, 因此检测器不会发出工人信号, 并且报告这个输入的阻塞原因而不是模糊 AMBIGUOUS_HANDLER 查找(浏览器服务-工人注册根本不产生任何结果).

合同义务词汇

5份合同,每个发现的任务产生全部:

合同含义示例测试 example/task/
task:retry-policy-enforcedflash 任务重试至 maxAttempts 最终失败前平面剖面,5次尝试成功
task:idempotent相同的一能键被复制重复配置文件, 副作用运行一次
task:terminal-handled类型在其中的错误 terminalOn 未重审终端配置文件, 仅试一次
task:observability-recorded每次执行( 成功 + 失败) 都会在 runs.json每个配置
task:duplicate-delivery-handled重复交货产生完全一种副作用复制配置文件

完全义务 id <resourceId>:<contract> - 比如说. task.email.send:task:retry-policy-enforced。 。 。 .

设置

# .gateforge.yml
plugins:
  - id: gateforge.pack-task
    version: 0.1.0
    transport: in-process
    module: '@gate-forge/pack-task'

包的默认导出是被绑定的 { discover(paths) } 合同.

实体适配器计划+审计线索

每个检测到的任务生成 runs.json 运行于实例服务器时的审计行 。 证人通过适配器合同读取:

{
  resourceId: 'task.runs',
  read(ctx, id)         -> Promise<{ runId, attempts, sideEffectCount, terminal, ... }>,
  normalize(body)       -> { entityId, fields: { id, retries, sideEffectCount, terminal } },
  deletion: 'archive',
  environmentFingerprint: 'task-loopback-v1',
}

TaskAuditAdapterSchema + 键 validateTaskAuditAdapter (缩写) pack-sqlalchemy是因为 EntityAdapterSchema执行合同 失败关闭 .

示例应用程序

example/task/server.js (端口3004号), node:http 仅限:

路线方法行为
/health获取{ ok: true }
/tasks获取已注册的任务名称列表
/enqueue邮政{ name, key?, profile, payload } - 完成一项任务
/runs获取审计线索(runs.json(中文(简体) )

简介 :

  • flaky - 尝试失败 1..maxAttempts-1,在最后一个上成功
  • duplicate - 总是成功的 key 已经去除
  • terminal - 掷出 AuthError 立即; 不重试
  • normal - 总是成功的

用法 :

node example/task/server.js --port 3004

横向覆盖

大小写声称的行为 test/e2e.test.ts
(a) 片状5次尝试, 上一次尝试成功, 4个重试行+ 1个成功行
(b+e) 重复同样的钥匙被解开, sideEffectCount 保持1对2次通话
(c) 终点站只有一次尝试,没有重试, terminal: true
(d) 可观察性每一个附件 runs.json
(一) 假绿色同位素sideEffectCount 重复键上的qq 2( 递归线)
(二) 假绿色终端处理终端不重试( 递归线)

决定主义

相同的输入路径 + 相同的文件字节 → 字节- 相同的发现输出 : 没有 Date.now() 编号 : Math.random(); 每个阵列排序; 每个名称 a 出自词源;电线上固定的密钥顺序.

发展

npm test                    # vitest run
npm run typecheck
npm run build               # tsc → dist/
node ../example/task/server.js --port 3004  # ad-hoc serve

版本与发布记录

@gate-forge/pack-task 共发布 46 个版本,首次发布于 2026/09/17;过去 12 个月发布了 46 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.19.2latest2026/11/105 天前
0.19.12026/11/106 天前
0.19.02026/10/2917 天前
0.18.32026/10/2522 天前
0.18.22026/10/2125 天前
0.18.12026/10/2125 天前

关于 @gate-forge/pack-task 的常见问题

@gate-forge/pack-task 是什么?

背景任务发现包:为BullMQ / Bee-Que /自定义队列 / 消息处理器 / 经常性任务 / @ 任务 @Que 装饰器 等同性能 + 重试- 政策 + 终端- on + 可观察性合同 审计- 运行的实体-a

如何安装 @gate-forge/pack-task?

在项目目录运行 npm install @gate-forge/pack-task,或使用 pnpm add / yarn add / bun add。

@gate-forge/pack-task 支持 TypeScript 吗?

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

@gate-forge/pack-task 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gate-forge/pack-task 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gate-forge/pack-task 可以商用吗?

@gate-forge/pack-task 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@gate-forge/pack-task 的下载量有多少?

根据 npm 官方下载统计,@gate-forge/pack-task 在 2026/10/16 – 2026/11/14 这 30 天内被下载 2,461 次,日均约 82 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gate-forge/pack-task 还在维护吗?

最新版本 0.19.2 发布于 2026/11/10(5 天前);至今共发布 46 个版本,其中过去 12 个月发布了 46 个;首次发布于 2026/09/17。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。