# @alma-harness/single-call 中文文档

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

版本：0\.41\.0
npm 元数据更新时间：2026-11-04T12:55:18.018Z
中文译文更新时间：2026-11-06T18:41:24.979Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：206 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:48.241Z
- 最新版本发布：2026-11-04T12:55:17.854Z
- 近 30 天下载量：2460（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：47（近 12 个月 47 个）

## 中文简介

管理着阿尔玛的一发模式处决.

## 安装

```sh
npm install @alma-harness/single-call
```

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

## README

# @alma-harness/单声道

管理单发模式呼叫. 文本/ JSON 跑车没有工具 有结构的步跑者保留了本地工具调用。 使用匹配的核心, 执行, 提供商,内存和PostgreSQL包. 节点QQ22. 这个引擎是分开的 从遗产对话 和批量跑者.

`createSingleCallRunner(config)` 拥有政策,版本价格,货币上限, 完整的缓存控制,输出计划/验证器和技术限制. `run` 接受经核实的范围/会话/操作密钥/投入修订/意向,可选 停止信号和懒惰 `loadInput(): Promise<Msg[]>`。主机解决身份 和不可变的输入授权; 永不转发浏览器提供范围/修改 没有这个决议。 只支持文本用户/助理消息.

供应执行 Store, ExecutiveResultStore, UsageInbox, Governed CostSettlementStore, 互联网档案馆的存檔,存档日期2011-12-21, a 读取 **不变** 和等待的审计日志。 使用 在MemoryGoverned CostSettlementStore.peek拥有自己的不稳定的定居地商店; Postgres SpendStore和Postgres CostSettlementStore共享耐用表格. 只有管理下的结算才写财务行。 审计记录、成本和开支 此引擎从未引用 。 跑道/接入操作/试听/呼叫身份证.

配置包括政策Version,价格Version,产出ContractVersion,价格, 上限、消费者、系统、最大托肯斯、最大输入查尔斯、最大输出查尔斯, 结果保留、客户端和背景错误。 可选 `cache` 覆盖 策略缓存,包括 `false`;省略使用政策选择。 可选输出 实值 `{name, schema, validate}` 用于本地 JSON; 验证必须同步返回 没错 配置数据被快照; 主机版本标识符必须描述 不可改变的政策/产出合同。 客户/政策/验证人都是可靠的能力. 使用提供者软件包的清晰单发包构建器:默认客户端 自动复试则被拒绝。 禁止倒置,修复,工具或用户流.

在加载上下文前保留结果 。 复制密钥读取状态或 原授权信封,绝不加载输入或再发送. 更改会话, 意图、修订或政策/产出/价格版本冲突。 货币警告 保存结果。 明确区块盖保留飞行前/呼叫后屏蔽;已知 成本总是在成功产出被压制之前解决.

`read(scope,key)` 返回为无效或视图:在 进程、调节 需要, 未发送或完成。 已完成,包括目前的授权信封, 原始财务收据和历史期刊元数据。 报废/过期产出 即使在历史完成成功时也无法使用。 持久性 失败拒绝; 重新读取/ 恢复解决没有提供者重试而执行的内容 .

A 类 `not_dispatched` 视图 `record.notDispatchedCause` 说为什么 声称的电话 从未被送到供货商那里,当有人观察的时候: `invalid` (续) 以配置或装入的方式)支持压制未修改的重试; `input` 是主装入器的 本身的失败; `aborted`, (中文(简体) ), `audit` 财务报告和审定财务报表 `store` 通常通过;缺席或 `expired` 意为未知. 只在新密钥下重试,并有限定的政策. 结构化 runch's root- only view 没有记录和原因( spec: not-displayed-cause).

`recover(scope,key,{leaseMs})` 购买符合资格的专用会计围栏,使用 原始政策/价格/日,并完成可用或不可用产出。 一项政策 未完成回收期间的拒绝请求 a 以前储存的信封。 从来没有 获取输入 。 打电话 `reconcileExpired(scope,{limit?})` 从主排程器到 准备/分发处决逾期未交的围栏。 需要未知/价格不高的证据 运算符调节; 延迟收件箱证据不会自动重写 .

`reconcileUsage(scope,{limit?,after?})` 仅确认其准确意见 已完成的会计或未分发的证明具有持久性。 页面大小默认为50, 最多100个。 它返回扫描/确认的清点和最后检查的光标. 从头开始,每一次都重新开始 以看到迟到的承诺。 未知/ 冲突 意见仍未提出。 财务预测有独立的消费者. 可选的第三个参数 `{ skip(operationKey) }` 留行待决。 运行时间 维护用它来保持 控制调用在步道上的用法,它也 请检查root 会计( spec: 运行时间维护).

公共经营承诺受期限/违反的限制,包括挂靠关系. 发送的流体因证据不足而耗尽 在BackgroundError召回中只要求元数据。 处理死亡或永久死亡 挂起自定义适配器无法保证最终使用到达 。 主机未解决 记录和时间表恢复; 此套件不会持续工作.

移动日记、结果、收件箱、管理费用 **审计** 在部署之前 匹配读取器/写取器。 结果保留必须允许执行/回收及其 擦除表面必须被主机注册。 完成不意味着生意 发生了突变或门户/WhatsApp发送:这些有独立身份. Erasure 在最后的保留检查后仍然可以进行 Egress; 存储内容 无法被复活 。 见 [光谱](https://npmcn.com/package/docs/specs/085-governed-single-call-runner.md)。 。 。 .

可选 `temperature` 是一个主机配置快照, 执行时持续 发送前控制 在索赔之前适用提供方的审定。 重播和 会计回收保留原值;调用者不能凌驾于其上。 弹出 `policyVersion` 当更改此不可改变的配置时。 见提供商 软件包的刻意限定支持矩阵(光谱:显式-温度控制).

## 管理模式步骤

`createGovernedStepRunner(config)` 是一个官方缓冲原始 单调结构化反应 和原始的谈话。 它接受一个值得信赖的 已经规划好的 输入和根栅栏行动, 加上懒惰的载荷 请求和路线原理。 提供相同的执行/结果/ 收件箱/结算/支出/审计能力、TreeStore行动、会计业务 存储, 单发送客户端和运行 TimeoutMs/max 请求Chars/maxOutputChars(可选) (原始内容存档于2018-09-31). MaxOutputChars. 东道主 建立登记册衍生工具,在移交前执行授权. 投入价格、政策、控制、身份证和留存是不可改变的原始快照.

在分会索赔之前保留了根槽;结果政策和相关审计 内容加载前 。 一个发送生成一个受控电荷和一个根 收讫. 没有遗留的财务作者、工具处理器、会话附录或频道发送 运行在这里。 警告保存输出; 配置的块盖使用包容性根 费用。 成功视图包括原始收据和 `step`:中性文本, 工具呼叫、 推理、 提供者Blocks、 stop and an `order` 索引保存 交际. 文本范围使用UTF-16 偏移;相邻的文本三角形被连接. 这是后台带数据, 不是公开答复。 采纳的循环必须隐藏推理并授权工具. 不透明 JSON 被保存;无效/非 JSON/超大小输出不能授权工具. 错误的工具参数保留了空输入和布尔标记,从不原始文本.

**为何输出无效** (规格:无效输出-理由). 跑步解决 调用 `invalid` 携带 `invalidReason`第一次检查 收藏家拒绝, 以封闭名称( 以`INVALID_OUTPUT_REASONS`: `output_chars`, (中文(简体) ), `reasoning_chars`, (中文(简体) ), `text_malformed`, (中文(简体) ), `tool_call`, (中文(简体) ), `block_malformed`, (中文(简体) ), `stop_conflict` 或者说 `event_type`它从不携带内容。 无所存 `read`,重放和 `recover` 没有。 文本和工具/提供者块 JSON 计数 `maxOutputChars`; 推理块 JSON( 一个 OpenAI) `encrypted_content` 联 合 国 (摘要)计算 `maxOutputChars` 文本和工具,最多 1 000 000(规格:去除理由-上限)。 可选 `maxConsecutiveReasoning` 探测器 一步,它的模型 喷出超过连续的很多 `reasoning` 事件 没有 `text_delta` 或者说 `tool_call`: 采集器标记输出 无效, 有原因 `reasoning_loop` 超过极限的第一个事件 (谱:推理-走-探测),跑者停止读取溪 在那里(指: 环-bort-unsettled). 提供商只在最后报告使用情况, 所以剪接的成本是未知的: `reconciliation_required`,没有 结算或根收,供操作员调节,该运行视图 携带 `invalidReason` (初拒绝名. 当终端使用时 在剪接前就来了 电话就解决了 `invalid` 和它的成本。 任何其他 拒绝被读取到结束。 忽略其信号的适配器读取到其 结束或结束 `runTimeoutMs`。 。 。 .

`read({scope,rootKey,operationKey})` 财务报告和审定财务报表 `recover(key,{leaseMs})` 将呼叫绑定到 它的注册根。 完成状态需要两种财务收据; 即使日记已经完成, 仍可收回缺少的修复集合 . 回收没有请求,也没有发送提供者/工具. 重新检查记录, 而不是读取记录 ,并只读取内容 。 损失的产出变为 不可用; 无法重生成已删除/ 过期的内容 。 根关闭防止 新招生,但不会在截止日期前取消先前的保留电话. 根所有者会关闭/调节根并拥有全转/效果的不确定性.

`reconcileUsage({scope,rootKey},query?)` 只有在下列情况下才承认确切证据: 根的完成/会计(或未分发的证明)是持久的。 扫描范围 范围化的收件箱页面; 重新启动后续的通行证以查看迟到的输入 。 大众奔跑 以TimeoutMs(最多10分钟)、外部中止和新电话为界, 原始期限。 它的背景排出只报告元数据故障. 对话包采用这一步骤;遗留的跑者仍然分开. `isStepInterruption(error)` 只有这个赛跑者自生自灭才是真实的 (它的超时,它的截止时间或它的呼叫者的信号),而没有商店写入 流失败; 商店本身 `AbortError` 不是一个( 请检查: call- retry) . 见 [光谱](https://npmcn.com/package/docs/specs/090-governed-model-step.md)。 。 。 .

清空经证实的 Anthropic 上下文拒绝在之后存储只保存元数据的拒绝 原始零结算和根收。 任何内容(甚至被 、 缺少引用、 重复/ 不同的停止或流失败无效 证据 会计回收从不自动恢复对话 (指: 安全-文字-拒绝-旋转).

预流拒绝证明(规格:预流-拒绝)需要参考, 没有内容,没有停止和溪道的失败。 通话完毕 结果 `unavailable` 财务报告和审定财务报表 `stopReason: null`,其根为零 接收,在文本中,结构化和步跑者。 这些电话曾经读 `reconciliation_required`。任何其他与证据的组合是: `unknown`编号 :`invalid`。 。 。 .

### 明确工具选择

设置相同 `toolChoice` 打开 `call.execution.controls` 和懒惰的仆人, 比如说 `{type:"tool",name:"extract_record"}`。要求的工具必须来 从东道主授权的登记簿。 原始验证所选名称 对照这些实际工具Specs,即使一个自定义客户端验证器无所作为; 供应商验证在前进一步应用其文件支持矩阵 网络接入. 选择从来不会执行一个工具,也不会批准这样做.

选择是不可改变的执行元数据。 同样的回放返回原作 接收和保留输出而不加载输入; 更改选择(包括 在相同身份冲突下不存在与明确的自动). 会计回收 从不发出另一个请求。 没有工具的旧记录Choice仍然可以读取. 案文/JSON `createSingleCallRunner` 在配置或运行时拒绝工具选择 输入; 使用 `createGovernedStepRunner` 用于结构化工具响应.

仅完成视图是不够的:检查 `result.outcome`, (中文(简体) ), `step.stop`,则 预期名称在 `step.toolCalls` 联 合 国 `malformed` 在验证其 提出反对商业阴谋的论据。 拒绝、截断、无法输出和 不当的论证不得视为有效的提取. 未成功的意见 可在保留原停站和财务收据的同时扣取部分区块.

## 结构化的单次通话

`createStructuredCallRunner(config)` 与 文本运行器的调用形状 : `run({scope, sessionId, operationKey, inputRevision, intent, loadInput, signal?})`。用于强制工具作为提取 计划 配置是文本运行器的, 不包含 `output`附加时 `trees`, (中文(简体) ), `accounting`,可信任的注册 `tools` 和可选 `toolChoice`工具名称 在施工时验证和复制.

跑者拥有操作根,身份,重放检查和 关闭。 每个标识符是 `alma-structured-v1:<kind>:<sha256>` 范围 和主机密钥: 被绑定,域分隔,并且从未嵌入密钥. 那个 前缀为保留;不要用于其他密钥。 重放比较根 没有期限就具有不可改变的约束力,因此不需要时间。 这个 包含会话、意图、输入修改和所有配置摘要 数据,包括价格和工具。 信任的更改 `policy.resolve` 行为 无法被消化: 凸起 `policyVersion`。会话/每日块飞行前运行 在任何根存在之前.

完整视图是未修改的受控步骤视图:检查 `result.outcome`, (中文(简体) ), `step.stop`,选择的呼叫及其 `malformed` 在使用前标记。 A 类 失败的根关闭永远不会隐藏一个完成的结果:关闭是独立的内务管理,一个未关闭的根过期并被调和. 没有处决记录, `read` 报告 `not_dispatched` 仅用于保留为零的非活性根 电话,由商店在它的根锁下证明。 保留电话,没有 日记记录已读取 `reconciliation_required`; 活动根读取 `in_progress`不论应用时钟怎么说 一个关键是: 无法使用的结果是最终的,所以用新键重试.

`recover(scope, key, {leaseMs})` 财务报告和审定财务报表 `reconcileUsage(scope, key, query?)` 拿着 主机密钥 . `reconcileExpired(scope, {limit?})` 属于全范围和返回 `{roots, executions}`。见 [光谱](https://npmcn.com/package/docs/specs/168-structured-single-call.md)。 。 。 .

## 常见问题

### @alma-harness/single-call 是什么？

管理着阿尔玛的一发模式处决\.

### 如何安装 @alma-harness/single-call？

在项目目录运行 npm install @alma-harness/single-call，或使用 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/single-call 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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

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

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