# @gate-forge/pack-task 中文文档

规范地址：https://npmcn.com/package/%40gate-forge/pack-task/

版本：0\.19\.2
npm 元数据更新时间：2026-11-10T03:57:45.851Z
中文译文更新时间：2026-11-16T00:04:51.562Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40gate-forge/pack-task
原文对照：https://npmcn.com/package/%40gate-forge/pack-task/?lang=original
项目主页：https://github.com/umiddey/gateforge#readme
源码仓库：https://github.com/umiddey/gateforge

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

- 包体积（解压后）：97.7 kB，23 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-09-16T21:52:42.856Z
- 最新版本发布：2026-11-10T03:57:45.472Z
- 近 30 天下载量：2461（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：46（近 12 个月 46 个）

## 中文简介

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

## 安装

```sh
npm install @gate-forge/pack-task
```

也可以使用：`pnpm add @gate-forge/pack-task`、`yarn add @gate-forge/pack-task`、`bun add @gate-forge/pack-task`

## README

# @ gate- forge/ pack- task

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

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

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

```yaml
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` | 已声明的尝试绑定: 任何任务都不得超过它, 队列本身已声明的约束也不得超过它 |
| `terminal` | `succeeded` (每一项工作) `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 — 引擎的队列读取器需要真实的队列,以及假的队列 作为证据

```sh
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-enforced` | flash 任务重试至 `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`。 。 。 .

## 设置

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

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

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

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

```ts
{
  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` - 总是成功的

用法 :

```sh
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 出自词源;电线上固定的密钥顺序.

## 发展

```sh
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 是什么？

背景任务发现包:为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 和提交记录判断。

