# @absolutejs/execution 中文文档

规范地址：https://npmcn.com/package/%40absolutejs/execution/

版本：0\.14\.12
npm 元数据更新时间：2026-11-01T13:21:32.090Z
中文译文更新时间：2026-11-06T16:55:51.865Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：293 kB，29 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：drizzle-orm \>=1\.0\.0-rc\.4 \<2，@absolutejs/agent-runtime \>=0\.2\.1 \<0\.3\.0
- 首次发布：2026-07-15T21:01:58.470Z
- 最新版本发布：2026-11-01T13:21:31.937Z
- 近 30 天下载量：2676（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：43（近 12 个月 43 个）

## 中文简介

对带有交易发包箱,队列集成,调和,补偿的AI代理实施崩溃安全外部效果.

## 安装

```sh
npm install @absolutejs/execution
```

也可以使用：`pnpm add @absolutejs/execution`、`yarn add @absolutejs/execution`、`bun add @absolutejs/execution`

## README

# @ absolutejs/ 执行

人工智能特工的崩溃安全外部效应. 枪决将特工分开 永远的意向,从错误的提供者呼叫 满足它.

生产路径为 PostgreSQL- first并重用绝对JS 队列:

1.  `store.enqueue(effect)` 从解剖角度插入效果和一个发包事件.
2.  `createExecutionOutboxDispatcher()` 将事件化为 `@absolutejs/queue` 存储( 使用) `@absolutejs/queue-postgres` (a) 在生产方面.
3.  排队拥有排行榜,工人租赁,回放,后退,和死信.
4.  `createExecutionQueueHandler()` 拥有提供者的一能 尝试历史, 结果 未知结果隔离 和解.

不需要雷迪丝。 发件箱发布前的进程崩溃 可主张; 队列排队后的崩溃是无害的, 因为事件 id 也是 队列一能键.

```ts
import {
  createExecutionOutboxDispatcher,
  createExecutionQueueHandler,
  createPostgresEffectStore,
  executionJobs,
  executionPostgresSchemaSql,
  executionTenantInventoryPostgresSchemaSql,
} from "@absolutejs/execution";
import { createJobRegistry, createQueueWorker } from "@absolutejs/queue";

await sql.unsafe(executionPostgresSchemaSql());
await sql.unsafe(executionTenantInventoryPostgresSchemaSql());
const effects = createPostgresEffectStore({ client });
const dispatch = createExecutionOutboxDispatcher({
  store: effects,
  queue: queueStore,
});
const registry = createJobRegistry(executionJobs).on(
  "absolutejs.execution.effect",
  createExecutionQueueHandler({
    store: effects,
    handlers: {
      "email.send": {
        execute: (input, { idempotencyKey, signal }) =>
          email.send(input, { idempotencyKey, signal }),
      },
    },
  }),
);
const worker = createQueueWorker({ registry, store: queueStore });
```

`ExecutionSqlClient` 接受序列化的 JSON 值作为普通查询 参数。 执行通过 PostgreSQL 明确解析这些值 `text` 转换为 `jsonb`因此,Bun SQL的适配器, postgres.js, 和尼昂必须通过提供的数值 通过不变的 比JSON再次编码他们.

如果一个供应商在接受请求后超时,就扔出去 `UnknownEffectOutcomeError`. 执行不会盲目重复试验:它隔离 效果为 `unknown` 直至授权的操作员、提供者查询,或 提供者通过 webhook 解决 `createEffectRecoveryOperations()`。 。 。 . 回收在原子状态过渡前核实证据,保留 只有附件的演员/来源/证据记录、每个案例的租户围栏和许可 只有在证据证实提供者没有适用该效力时才重新进行试验。 那个 过渡 解析后创建调和范围外框事件,以便队列 将原事件耗尽后的安全重试时间排出 。 应用 `effectRecoveryPostgresSchemaSql()` 在使用 PostgreSQL 恢复 API 之前. 成功效果可通过下列方式明确逆转: `compensateEffect()` 当处理器提供 `compensate`。 。 。 .

经验证的提供者webhooks和查询结果可以通过 `createEffectEvidenceIngestion()`。仅保留摄入边界 正式的、有房客约束的证据,授权在持续使用前具有约束力, 复制供应商交付ID、拒绝 试图将现有交货重新组合到另一种效果,并恢复 当服务商在主机崩溃后重试时进行校正。 生产主机 应适用 `effectEvidencePostgresSchemaSql()` 和使用情况 `createPostgresEffectEvidenceStore()`. 原始Webhook有效载荷和供应商 证书不属于证据库.

运行时代理主机应该使用 `createAgentRuntimeEffectExecutor()` 而不是说 返回一个等效结果,好像它是已完成的效果。 桥铺 一次租户/跑栅效应,请运行时间等待队列处理器 记录终端结果。 内容 `authorize` 调用必须返回准确 机构行动识别和输入摘要留作执行时间租赁.

## 经核证的适配器和租户设施

`createEffectAdapterRegistry()` 是全球已关闭的边界。 适配器 说明者宣布效果、目的地、证书时间档、一能性、, 和解、补偿和动用权力。 激活需要新鲜的 精确描述摘要和主机验证证据的证书. Webhook 和解描述符也必须声明其亲属 `{tenantId}` 回调模板、 生体签名头、 项目秘密 别名、提供者事件集、健康信号、替换或重叠旋转 行为 查询调节描述符将其提供者的查询绑定在一个 已宣布的证明时间档和宣布结果、投票理由、健康状况 新鲜度和旋转核查 登记拒绝不完整或不安全的设置,以及 `effectAdapterWebhookCallbackPath()` 让租户安全回电,没有 提供者特定主机分支.

`createEffectAdapterReconciliationRuntime()` 扫描隔离效应和 在任何提供商查询之前,它要求获得耐用性能租赁。 授权 在解决确切的证书别名之前先安装租户,然后询问 驱动程序只影响身份元数据,而不是原有效载荷 传回正常证据 `createEffectEvidenceIngestion()`。 。 。 . 使用 `createPostgresEffectReconciliationLeaseStore()` 财务报告和审定财务报表 `createPostgresEffectAdapterHealthStore()` 应用后 `effectAdapterReconciliationPostgresSchemaSql()`. 健康是固定的 包含安全代码和计数器的信号; 原始提供者错误和证书 永远不会被保留. 操作员触发所有者流量必须调用 `runOnce({ tenantId })`租户 过滤器在任何租赁之前传入耐用效应库存, 安装授权、证书解析或提供者查询.

使用已签名的webhook作为主路径和提供者查询的适配器 倒置声明 `mode: "webhook-query"`. 查询合同明确规定 是否要求提供商提供参考。 执行驱动程序只能提取 边框 `{ provider, resourceId }` 成功提供商提供的参考文献 结果; 执行中添加了认证的适配器 ID, 并且绝不暴露任意性 结果或原始有效载荷到查询驱动程序。 如果当地完工失败 租赁, `quarantineUnknown()` 在保留之前比较精确的尝试数 那个参考 因此,老工人不能取代新的尝试或 终极效应。 需要引用的后退会先跳过 当一个模棱两可的提供者的电话从未回过电话时,验证性解答.

`createManagedEffectReconciliationScheduler()` 增加一个持久,明确 默认关闭控制飞机的时间表 围绕运行时间。 它的商店保留 间隔,下跑,复制租赁,定界计数器,安全出错码. A 类 政策得以继续 `initialize()` 从不覆盖操作员的 现有选择。 使用 `createPostgresEffectReconciliationSchedulerStore()` 应用后 `effectReconciliationSchedulerPostgresSchemaSql()`地方 投票循环可能运行在每个复制品上,因为只有持久的正当要求才能 启动和解通行证.

`createEffectAdapterInstallationRegistry()` 窄径,用于认证授权 一个租户。 每次安装都会将适配器版本和文摘接上,开始 禁用, 选择一个效果和目的子集, 所需的映射适配器 在不存储值的情况下对主机拥有的秘密化名进行认证,并且可以 将每个影响支出上限与任务挂钩。 授权和每项授权 重新检查全球适配器、描述针、证书别名、任务、, 目的地,效果,房客,和支出上限。 描述符漂移或被撤销 因此,证据在不推出的情况下停止了每个依赖性安装.

生产主机应适用 `effectAdapterRegistryPostgresSchemaSql()` 财务报告和审定财务报表 `effectAdapterInstallationsPostgresSchemaSql()`,然后使用相应的 PostgreSQL店铺. 宿主召回 仍然负责解密 (b) 原始证书从未输入任何登记册.

`createEffectAdapterExecutionHandler()` 是最后提供者边界。 这个 接受安装信封,重新授权 确切的租户,效果, 目的地,并花费, 首先重算 犬类授权输入文摘, 验证运行时的司机身份,版本, 能力、核对和补偿能力与经认证的相符 描述器,然后解决授权的秘密别名。 证书 值只存在于驱动程序上下文中,从未置于持久 安装记录或桥接结果。 未知的提供者结果应该是 升为 `UnknownEffectOutcomeError` 所以排队隔离他们 而不是重试一种模棱两可的副作用.

当一个授权的信封携带正支出时,桥需要 只有在供应商成功后, 才恢复并运行, 然后再返回 成功效果结果。 正常化的结果保留了授权,货币, 在不保留全权证书的情况下退还赔偿金所需的数额. 支出信封有同样的任务和货币,所以 即使安装,未知效果仍保留其原始结算权 在提供者证据到达之前,政策有所改变。 任务的开支是 (原始内容存档于2018-09-26). cononical 持久效果-输入文摘. 确认成功 webhook, 提供者- query, 以及操作员调节路径 还需要在制作未知效果终端前结算。 结算 退款回调必须在效果身份下具有一能性 所以坠入 要么可以安全地重试边界.

## 固定背景步骤

`runCheckpointedSteps` 执行一个不可改变的有限计划 在呼叫者拥有,更新 执行租赁。 其适配器必须在解剖上使用 预期订正。 保存一个覆盖每个执行输入的独有的计划密钥 . 已完成的步骤重新使用。 飞行中恢复标记投出 `UnknownEffectOutcomeError`: 不盲目重试该提供者的操作 . 从 `runStep` 只有在已知的习惯之后,才能写出排水口。 虚假 `beforeStep` 结果持续地停止了计划(例如,在商定的信贷上限).

`createExecutionQueueHandler` 延长其效力租约(默认为30秒), 每10秒更新一次),通过处理器转发关闭/租赁损失 信号 和隔离 不确定完成。 每次援引都有独特的租约 拥有者。 排队工作租赁也必须超过限定的工作期限或延长 以排队工人盟誓, 这个API并不使任意提供者具有一能性.

### 恢复供资暂停

返回时 `{ pause: "funding" }` 从 `runCheckpointedSteps.beforeStep` 坚持下去 下一个供应商呼叫前的备用站。 资金核实后 获得独家执行租赁,通过 `resume: { expectedRevision, reason: "funding" }`跑者检查检查站的准确修改,不可改变 \* 计划并暂停理由,保留已完成的结果,拒绝任何飞行 运行不稳定。 一个平地 `false` 仍然是终点站 永不重设 检查点或制定新计划 只是为了重试资金中断.

## 常见问题

### @absolutejs/execution 是什么？

对带有交易发包箱,队列集成,调和,补偿的AI代理实施崩溃安全外部效果\.

### 如何安装 @absolutejs/execution？

在项目目录运行 npm install @absolutejs/execution，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：drizzle-orm（\>=1\.0\.0-rc\.4 \<2）、@absolutejs/agent-runtime（\>=0\.2\.1 \<0\.3\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @absolutejs/execution 支持 TypeScript 吗？

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

### @absolutejs/execution 支持 ESM 还是 CommonJS？

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

### @absolutejs/execution 可以商用吗？

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

### @absolutejs/execution 的下载量有多少？

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

### @absolutejs/execution 还在维护吗？

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