# @alma-harness/batch 中文文档

规范地址：https://npmcn.com/package/%40alma-harness/batch/

版本：0\.41\.0
npm 元数据更新时间：2026-11-04T12:52:42.086Z
中文译文更新时间：2026-11-06T21:19:26.223Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：136 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- peer 依赖：@alma-harness/core ^0\.41\.0，@alma-harness/execution ^0\.41\.0
- 首次发布：2026-09-08T21:18:45.944Z
- 最新版本发布：2026-11-04T12:52:41.851Z
- 近 30 天下载量：2325（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：47（近 12 个月 47 个）

## 中文简介

为阿尔玛管理单发批量执行.

## 安装

```sh
npm install @alma-harness/batch
```

也可以使用：`pnpm add @alma-harness/batch`、`yarn add @alma-harness/batch`、`bun add @alma-harness/batch`

## README

# @alma-harness/批量

管理单发批次执行. 节点 QQ22 并匹配 Alma 需要软件包. `createGovernedBatchRunner` 编剧: Batch Submission Store, BatchUsageStore, Batch Accounting Store, ExecutiveResultStore, 受管的定居点, (原始内容存档于2018-10-21) (英语). same-counter spend.peek, 审计和单发卡卡通能力.

供应不可移动的配置 请求/输出/汇总大小,运行时出站Ms QQ5分,并在BackgroundError上. 主机创建授权的完整列表: 范围/会话,项目身份, 原始价格/政策/控制、内容/配置修订和结果保留. 主机获得允许的工具/ media/schema; 此原始不路径政策 或执行处理器。 绝不接受模型输出的表/镜/手 未验证浏览器输入 。 更改配置需要新修订; 旧批次 还必须解决其原始配置、价格和提供者账户.

`submit({input,rationale,loadItems,signal?})` 保留每项结果并等待审计 在装入内容之前。 请求必须匹配所订购的ID、型号、批量级和 控制系统。 只有第一个持久发送:真实的响应允许提供者尝试. 平等重放从不加载输入或再次提交 。 在输入文件上等待的选项 钩子在创建前可以保留上传引用; 没有它没有持久的孤儿文件 库存索赔。 任何模棱两可的呈文即使在期满后仍未得到解决. 不存在退货、自动重新提交或租赁接管。 明确提供者 注销与提交书的所有权和结算分开.

`collect({scope,key},{signal?})` 解析存储的控件并收集每个 终端状态,包括失败/过期/取消。 每个观察都刊登在日志上 包括管理下的结算和包容性核算。 这些是唯一的财务 编剧:SpendStore.add或AuditLog.cost运行. Hashes 复制元数据 ; 原始的明细结算身份本身收费。 不详, 无价和自相矛盾的证据仍有待明确核对.

只有在完成独立验证的EOF之后才能保留新的输出. 腐败 或尾部缺失不能授权部分新输出。 内容界限/失败 没有停止已知的排水. `eof` 描述这种援引,而不是持久的 完成证书. `reconciliationRequired` 报告此收藏待收 财务/内容工作。 现有输出在后期失败 GET 后仍可读取 . 夹克之间发生相撞 需要另一个GET,但从不 另一个模型提交.

**供应商的复制件** (谱:提供-批-保留). `collect` 永远 删除它们 : 工作常规会再次收集, 直到它完成 . `discard({scope,key})` 通过客户端删除它们 `discard`,为主机 这直接收集。 自己送货后再打电话 它拒绝批发 尚未核算和决定的项目.

`read({scope,key})` 持续返回元数据、包容性财务证据和 目前保留的项目结果;它不声称有EOF或交货。 成功 `output` 是一个后台 `governed-batch-v1` 带有命令中性块的信封 停下来 理由不是公开答复;东道主验证其商业计划 授权任何效果。 拒绝/拒绝/无效/封锁/不可允许的区别停留. 原始整块决定压制成功产出;缺少总收入 在对这些决定进行评价之前,保持区块模式的成功;警告予以保留。 货币 警告是持久的证据,而不是对外通知服务的电话.

`reconcile({scope,key},query?)` 无提供者/内容的日记财务 访问。 它返回扫描/修复/待清点和待清点。 页面默认50, 最大100; 开始时重新启动未来通行证。 已经通过的意见 必须仍然修复缺失的汇总收据,所以默认查询包括这些收据.

保留结果始于提交保留。 收藏从不准备 新的保留、延长保留或恢复消除。 阅读/投放 尊重 原始绑定; 注册结果擦除/ 清洗主机 。 成功的公众 提交/收受承诺以超时/超时为限(提交还以 ;取消并不证明依赖性终止。 迟到 遵守验收/财务工作,背景故障仅报告范围 阶段元数据。 永久程序损失不能保证提供者的证据缺失.

迁移分批核算(包括提交、使用和管理费用), 在启用这一跑者之前,先进行结果和审计。 PostgreSQL 存储期限仍未到期 用于读取/校正。 常规和渠道/业务交付需要自己的 持续的说法;这名跑者从不发送真实的信息,也不认证交付. 见 [光谱](https://npmcn.com/package/docs/specs/099-governed-batch-runner.md)。 。 。 .

任何寄出赠款之前的失败,包括 已确认的索赔、记录 `not_submitted` 当清理成功时( 请参见 : (未提交) 损失的索赔确认没有留下围栏和清理 写入失败; 商店的过期扫描然后在最后期限后记录状态 . `collect` 在它返回时 `{eof:false, reconciliationRequired:false}` 没有提供者访问; 重放 `submit` 返回它,并且从不发送。 跑者没有扫地:拨打批次 商店的 `reconcileExpired` 从主持人的日程安排器.

## 状态和取消( 规格: 受管- 批- 取消- 采纳)

`status({scope,key},{signal?})` 财务报告和审定财务报表 `cancel({scope,key},{signal?})` 解决 跑者配置下的原始接受手柄. 他们拒绝失踪 hTTP 之前的操作、外部范围/配置和不支持的取消. 这些文件在提交期限后仍可提供,但须以本援引文件为准 运行时输出 M/ signal. 不加载输入,也不改变持久执行或财务.

取消返回 `{status:"requested",progress}`: 一个经过验证的供应商 承认,而不是终端注销或退款。 请求失败/ 含糊不清 永远不会自动复试; 明确的后呼是另一个取消 请求。 继续明确状况/收缴情况,以说明已完成的项目和 保留未知证据。 关闭连接不能证明依赖性终止 .

## 工具选择

每个项目 `execution.controls.toolChoice` 必须等于已装入 `request.toolChoice`。支持的中性模式是自动的、无的、需要的和 `{type:"tool",name}`;供应商/模型限制仍由 供应商包。 命名的选择根据实际授权进行验证 ToolSpecs在发送前,包括带有自定义的运输验证器. 选择是 不可变的批量身份的一部分; 更改选择冲突而不另作输入 装入或提交。 缺席保留了旧的电线和重播合同.

成功提取项目保留 `tool_use` 停止并订购 `tool_call` 街道,连同原始财务收据。 检查结果、 停止、 预期名称 并在使用这些理由之前验证其论据。 选择不引用商务处理器 或个人记忆写作。 读取/状态/收集/核对/取消权力 从缺失的内容、未知用途或缺失的手柄再次提交.

## 批量呼叫( 规格: 批量呼叫)

`createBatchCallRunner(config)` 逐批发送一个结构化提取 依由故而重试,不取倒扣或取消. 它的配置是 被管制的跑者加上呼叫者:

-   `policy`,版本,批量级 `prices`, (中文(简体) ), `caps` 财务报告和审定财务报表 `consumers`· ;
-   `system`, (中文(简体) ), `tools`, (中文(简体) ), `toolChoice`, (中文(简体) ), `maxTokens` 财务报告和审定财务报表 `resultRetentionMs`· ;
-   可选纯 `validate(output)`· ;
-   `retries: { provider, invalid, not_sent, uncertain }`,从 0 到 4,没有 默认;
-   `retryDelayMs`,以及 `submitWindowMs` 最多一小时.

变动 `configRevision` 每当重复,等待或 `validate` 变化.

主机调度器运行了两个回路:

```ts
const r = await calls.attempt({ scope, sessionId, key, inputRevision, intent, loadInput });
// pending: call again later. completed: publish r.output. failed: show r.reason.
if (r.status !== 'pending' && !r.settled) await calls.settle(scope, key);   // repeat until settled
```

**供应商的复制件** (谱:提供-批-保留). 何时 `attempt` 或者说 `settle` 报告 `settled: true` 和最近的尝试被决定 运行器丢弃 每一个尝试的批次 在提供者。 以后不打电话了 又来了 失败的丢弃物一无所获并报告给 `onBackgroundError` 带有舞台 `discard`。客户端没有 `discard` 保留它 分批进行,直到供应商自行失效.

**什麽 `attempt` 是否为:**

-   **它只是对最近的尝试.** 它提交新的批次,或收集, 或对项目进行分类.
-   **尝试 k+1 开始** 只有在理由津贴保留的情况下,并且 `k × retryDelayMs`。在那之前它会返回 `pending`。 。 。 .
-   **早先的尝试** 他们的日记支持的每一个原因都算在内 所以 计数从不下降.
-   **运行呼叫一个关键一个一次,** 作为工作租赁或交易 民意调查已经做了 重试的表格, 仅更新和 `settled` 准确 根据合同.
-   **即使通话重叠,** 每次尝试都不超过一次, 或五次以上尝试.
-   **在结束或提交之前,** `attempt` 再次读取链条 是否移动了:延迟接受、消除或 之前的呼叫的背景工作.

**结束呼叫的是:**

-   `too_long`, (中文(简体) ), `refusal`, (中文(简体) ), `cap` 财务报告和审定财务报表 `invalid_validator`· ;
-   `unavailable`: 被删除或过期的结果。 从来没有产生过 再来一次;
-   减员,或五次尝试.

**停止键 :** 停止打电话 `attempt`电话 `settle` 直到它结束 返回时 `{ settled: true }`。 。 。 .

-   `settle` 收集已发送的每批件,并关闭一个提交件 死了,在商店自己的钟.
-   它不提交任何内容,也不装入任何输入.
-   击出 `lost` 从不返回一个把手, 并且需要操作员.

主机的加载器应该拒绝它不再想要的密钥:拒绝加载 发送什么.

使用量未知或价格不高的批次 `pending` 直至 这是和解的.

## 常见问题

### @alma-harness/batch 是什么？

为阿尔玛管理单发批量执行\.

### 如何安装 @alma-harness/batch？

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

### @alma-harness/batch 支持 TypeScript 吗？

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

### @alma-harness/batch 支持 ESM 还是 CommonJS？

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

### @alma-harness/batch 需要什么版本的 Node\.js？

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

### @alma-harness/batch 可以商用吗？

@alma-harness/batch 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @alma-harness/batch 的下载量有多少？

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

### @alma-harness/batch 还在维护吗？

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