# @alma-harness/loop 中文文档

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

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

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

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

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

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

## 中文简介

阿尔玛统治了转弯引擎:步骤,工具发送,授权和缓存卫生.

## 安装

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

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

## README

# @alma-harness/loop (英语)

内部调节的转动引擎 [阿尔玛](https://github.com/FabioFernandesCarneiro/alma) a 包括: TypeScript 运行于敏感数据的多租户代理的运行时间. 它运行 反对 [`@alma-harness/core`](https://npmcn.com/package/%40alma-harness/core)。使用的主机 [`@alma-harness/conversation`](https://npmcn.com/package/%40alma-harness/conversation) 或编成 [`@alma-harness/runtime`](https://npmcn.com/package/%40alma-harness/runtime);这个包裹没有独立的代理工厂.

> **状况:1.0前.** API仍在移动中;见 [路线图](https://npmcn.com/package/docs/architecture.md#12-adoption-roadmap) 为它的位置.

## 它拥有的

-   **循环** 步骤、工具发送、授权和生命周期钩。 这个 匹配版内部 API 需要受控执行和主路由 入院前验证快照. 对话拥有身份,盖子和商店.
-   **波动的后缀,每个转弯** (谱:起伏起伏起伏)- `volatile` 是一个每个转弯一次的函数, 与转弯的范围,会话,意图, 触发和时钟; 其文本加入 `system` 作为输入后附加的一个块,标记 `origin: "harness"` 如此的屏幕 可以隐藏, 坚持和重放字节相同, 所以缓存读取 通过它。 简本省略. 入院后来源失败 `reconciliation_required` 所有权.
-   **被推迟的工具和内置搜索** (规格:递延工具)——一种工具 登记 `deferred: true` 除非模型问: 转弯的赠款会推迟任何工具,无论是否装入,每个步骤的广告 `search_tools`,其描述将全部取名;搜索会载入 匹配,记录在 `loads` 在结果块上记录负载 并告诉模型现在可以叫什么 一个负载 当对话的视角显示结果时,每个回合内 自主补助(种类:稳定工具广告)。 每个请求都携带 `deferredTools`这笔赠款全部延期按登记顺序排列,所以 适配器可以原地装入并保存缓存前缀. 专有核心:从未 档案,从未向代表作广告, `tool:pre` 适用. `names: [...]` 精确地装入以全名或唯一名称命名的工具 简称,从不排序,也不以 `limit`; 它报告 `alreadyAvailable`, (中文(简体) ), `ambiguous` 财务报告和审定财务报表 `unknown` (规格:搜索-工具-名称). 单位 `query`,首先工具查询名称加载( spec:named-tool-search):一个全名, 最后一个 `__` 当一个转弯的工具有 这个 名称未用到的单词( spec: named- search- words) 等级 其余用BM25在每一工具的名称和说明上,按方式加权 很少的转弯工具共享一个单词( spec: bm25-tool- 排名); a 工具只装入了最佳分数的一半以上, 所以 `limit` 是一个帽子,从来没有 一个配额, 和匹配的搜索 没有很好的载货。 其结果是: `alreadyAvailable` 对于已命名的工具已调用和 `ambiguous` (单位:千美元) 几个工具共享。 只有转弯的工具 咨询:补助金以外的一个名字与任何项目都不符,从未列出. 确定性基准`test/tool-search-bench`,光谱 : 工具搜索基准标记)在三个目录和整个目录上给搜索打分 与承诺的基线相对的序列可能只会收紧.
-   **预期工具失败** ( spec: tool- error) — 处理器返回 `toolError(payload)` 用于完成预期的失败(“未找到”). 呼叫的结果是有效载荷 `isError: true`, (中文(简体) ), `tool:post` 看见 旗帜,转弯继续。 仅以身份确认:一个域对象 带有 `isError` 字段保持普通输出。 掷出一掷还轮回 和归宿 `toolError` 永远无法澄清一个不确定的转折.
-   **提供者执行的网络搜索** (规格:提供者-工具) - `providerTools` 注册类型; 按类型分列的配置赠款, 无法命名 未注册的 每个广告只发布到一个转弯时或以下 `maxSensitivity` (单位:千美元)`internal` (b) 绝不应委托代表 通话结果以中性格式坚持提供商到场顺序,并在下一步重播,每个结果都是一个访问事件 (单位:千美元)`tool: "web_search"`, (中文(简体) ), `resource: "provider:<id>:<n> results"`从来没有 查询),溪流描述它们,a `pause` 停止将转弯为 另一步骤对 `maxSteps` 还有帽子 按请求价格 表格,已关闭. `maxUses` 是一个每圈的封顶,每圈的环绕 提供者(规格:什么是电线剪接):在封顶处,工具被扣入 转弯的后台阶.
-   **电线剪了多少** (规格:what-the-wire-cuts)——一个工具呼叫谁 未解析参数的解析结果为无效输入结果 `tool_use` 时 `max_tokens` 保留步骤输出;原始文本永远不会被坚持. 输入中一个媒体屏障是 Egress and land on the access track by by 提供者和类型,从不通过 URI:通过 URL,适配器将 URI 交给 要获取的提供者 .
-   **钩子边界输出方案** (规格:提供者-请求-控制) - `step:pre` 无法添加或更改 `ModelRequest.output`。拒绝尝试 并记录为元数据,线索中没有计划内容。 公共代理人 调用尚未选择结构化输出 .
-   **缓存的持续时间** (规格:缓存-ttl)——政策选择可能携带 `cache: { ttl: "1h" }`将它复制到每一步 以及一个代表的 记录在路由线索上 `step:pre` 如分级;一个一小时的写法按自己的行计价,倒闭.
-   **按字节排列的媒体** (规格:媒体字节) `media` 配置, 设置 字节一个块载,或产品 `media.source` 向每个裁判询问一次 转过身去作为基数64的提供者;会议只安排裁判; ; 内容类型在 适配器看见了. 无 `media`,拒绝包含内容的块 (规格:近-066-069-调查). 后期的历史媒体是占位符文本 默认块( 字节去一次) 或 `replay: "bytes"`字节 再来一次. `maxBytes` (32 MiB)防止过大的媒体到达提供者. 入院后的源失败保留了不确定性;它不授权重试.
-   **呼叫限制** (规格:呼叫-限制-最后回答)——当执行时 报告其呼吁`TurnExecution.calls`),循环读取左侧的呼叫 在每一个主要步骤和每个工具调用之前。 最后一个电话是带子 当它给工具做广告时通知,而它要求运行的功能工具(a) 服务商搜索在呼叫内进行;没有剩下的,转弯结束,a 代表的工具,没有呼叫 阅读它永远不会运行。 主循环 `maxSteps` 以同样的方式结束转弯,因为 `TurnResult.stepLimit` (规格: 步骤限制-最后回答); 代表自己的步数上限仍为倒数. `TurnResult.callLimit: { maxCalls, answered }` 这么说, 而不回答的回合是空的。 缺席 `calls`,仅限 `maxSteps` 约束计划。 当执行报告时间短 (单位:千美元)`lastByTime`),第一个之后的主要步骤是最后一个相同的方式,如同 `TurnResult.timeLimit: { answered }`(一) 自行通知; `finalAnswerNotice` 替换每份通知的文本(请注明:召回).
-   **终端工具** (规格:终端-工具)- `terminalTools` 名称 已注册的工具,其成功结束回合。 当每个主呼叫 步骤返回一个非错误的结果,其中之一命名为 终端工具,回合结束 `completed` 在那个台阶上 `tool_use` 没有 进一步模式调用:一个对人说话的工具不需要关闭调用. 台阶的每个调用都运行; 任何台阶的调用都会出现错误 结束转弯,所以模型读取它(光谱:终端-兄弟-error);在最后呼叫时,或何时 一个孩子使用它,后来的呼叫没有运行,极限结束站. 各位代表对此视而不见. 最多64个注册名称,从未 `search_tools`。 。 。 .
-   **一转两相** —— 说 `runTurn` 返回结果; `streamTurn` 观察确定的主要步骤输出并携带 相同结果 `.result`和他们一起 一个执行,所以 执法不能有不同.
-   **一次性工作** 住在这里 `@alma-harness/batch` 财务报告和审定财务报表 `@alma-harness/single-call`遗留的工作工厂被拆除; 批发所有权、原始财务收入和现在的明确不确定性 管理这些路径(规格:遗留-工作-管理者-清除).
-   **常规** 运行通过此循环, 但与时钟同住 : 管理正常适配器 `@alma-harness/schedule` 由于 spec : 例行公事 与时俱进.
-   **长篇大论政策** (单位:千美元)`longContext`) 届会轮流举行 在寒冷的边界(§6.6, spec: long-context)上摘要. 寒冷的开始 (最后一个消息比 `coldAfterMs`,默认5分钟)结束 `rotateAtTokens` 总结历史 `summaryTier` 结束 代表路径——路由、充电、在小道上——保留最后一条 `keepLastMessages` 从用户消息中逐字发送,然后从 `[summary, tail, input]`;摘要以标记和每个 后一步的视野从那里开始. 只有经证实的、已解决的零使用上下文拒绝才能允许一种反应 轮换和重试;任意的提供者例外从来不给予这种授权。 从来没有中历史记录; 缺席 整个日志像以前一样发送. `rotateAtTokens` 以历史衡量 内容(角色、文本、工具调用和结果;从未) `meta`JSON钥匙, 不透明的有效载荷或介质) `estimateTokens` 当主机设置一个 (指: 长文度量. `speechTools` 与您交谈的名称工具 人和他们的论点, 所以摘要读 整个演讲; `summaryFrame` 设置摘要周围的行.
-   **金融执法** ——执行构成为权威支出 并使用规范的盖子。 主要电话、代表、直接电话和摘要 通过原始的受管收据进行结算;循环从不写出遗留成本.
-   **记录的事件** (规格:对话-事件)——每个请求的视角去 结束 `renderEvents`(单位:千美元) `human` 或者说 `system` 消息到达模型为 个人的标签一方(`eventLabels`,英语默认值),永远不会 作为自己的演讲。 转弯记录的每条消息 `meta.turn`,则 转来转去的id,在创记录的时间盖上印章,所以回复保留了被坚持的对象. 旋转摘要标记相同的行并标出未交付的回函.
-   **协调和观察** 住的对话。 永久性录取取代 租赁接管到期。 主机保留繁忙请求的输入和重试的密钥 完成后。 WhatsApp break community 也是东道主的责任.
-   **缓存卫生观察者** (单位:千美元)`cacheHygieneGuard`)——警告某会时 保持冷写它的前缀, 这是一个错误的配置法案会 否则,几个月后报告.

## 东西在哪里

`engine.ts` 界定内部构造和共享结果/活动类型; `turn.ts` 集合起一转并运行起步; `step.ts` 应用钩子边界; `dispatch.ts` 拥有工具和接通电话; `recall.ts` 组装召回。 共享 内部,钩子,状态,缓存的卫生和上下文帮助者仍然是单独的文件. 没有遗留的流控制器、租赁协调员或收费执行. 匹配版本 `/internal` 子路径不是一个稳定的独立主机 API .

## 永远不能做的事

-   扩大什么 `core` 许可。 敏锐度缩小了代表的视野 从来没有 升级; 钩子可能不会重写路由或被公布的工具集, 并且可能 降低每步输出上限,但永远不提高(第029段)。 这算什么 `step:pre` 钩被触碰——荣耀或被拒—— `context` 线索.
-   到达文件系统,产出一个子进程,或者运送一个外壳.
-   取决于供应商SDK。 中性消息格式为边界.
-   讲述了模型的推理. 一直坚持着助理信息 并重新播放给提供者; `reply` 而溪流从不携带(请参见: 逻辑障碍.

## 使用和流动

开始于 [快速启动](https://npmcn.com/package/examples/quickstart)一次峡谷 `runner` 已配置,两个切入点需要相同的明确身份:

```ts
const request = { scope, sessionId, idempotencyKey, input, intent };
const view = await runner.runTurn(request);
// Or observe a new request; a completed retry replays the original result.
const turn = runner.streamTurn(request);
for await (const event of turn) {
  if (event.type === "text") render(event.text);
}
const finalView = await turn.result;
```

`break`,显示器返回/扔出和套接字关闭时只将观察者分离出。 他们 永远不要中止执行。 明确执行的取消或期限到期保留 和解的不确定性。 慢读器有边框队列并重同步 结束 `read`它无法阻挡转弯.

文本按已结算的主要步骤发布,先检查所规范的产出,然后更新 保留/过期读取。 早期可见步骤可能先于后期工具失败,或 预算停止。 没有任何标志性三角洲、代表文本或推理被曝光。 最终 结果事件和 `.result` 使用相同的犬形视图. 无效的输入拒绝; 非可持久路由拒绝为 `not_admitted`,重叠的工作是 `busy`,以及 承认的失败是 `reconciliation_required`,而不是可重试的错误信封.

## 测试助手

`@alma-harness/loop/testing` 脚本上的船 `ModelClient` 循环是自己的 测试与——确定事件序列,无网络,无时机. 里面没有进口维特.

```ts
import { FakeModelClient, scriptedText } from "@alma-harness/loop/testing";

const client = new FakeModelClient([scriptedText("Hello!")]);
```

## 文档

[文件索引](https://npmcn.com/package/docs/README.md) • 妇女 [建筑](https://npmcn.com/package/docs/architecture.md) • 妇女 [变化因素](https://npmcn.com/package/docs/invariants.md) • 妇女 [快速启动](https://npmcn.com/package/examples/quickstart)

阿帕奇 - 2.0

温度和产出控制仍以 `step:pre`; 尝试更改 被记录而不包含计划内容。 Canonical 公共电话不选择这些 控制系统。 纯上下文助手来自 `@alma-harness/memory/context` 并保留 身份通过循环再导出;内存是一个匹配版本的对等依赖.

执行接合需要被快照的主要选择. 摘要和儿童 确定自己的路线并保留血统、使用和根限。 已解决主线 步骤在不等待观察员或控制取消的情况下对引用进行排序.

### 明确拒绝代表团

`ctx.models.tryDelegate(request)` 返回( n) `{ status: "completed", text, usage }` 或不可改变 `{ status: "refused", reason }`时 `depth`, (中文(简体) ), `sensitivity` 或者说 `tool_grant`工具 可能处理该数据或返回拒绝发送受限数据的确切对象 `isError` 工具结果。 克隆和外星物体是普通输出. 这个 现有 `delegate` 不断投掷; 两种方法都不放弃处理器/ 儿童故障, 取消或不确定的持久性。 只有现场操作员才能使用TerDelegate.

请求在孩子的路由前被简要描述: 纯数据属性, 有效 分级/敏感度、成型良好的UTF-16单位,最多为256台 工具名称。 存取器, 稀有数组和未知字段无效 . 结构性拒绝先于儿童政策、钩子和保留。 一个正常 返回的拒绝仍然通过执行健康检查和现有工具:, 产出上限和咨询处理。 见 spec 受管 - 委托 - 反驳.

受管主回路只对对话中信任的解答反应 标记,在记录/观察拒绝的输出之前。 预流拒绝标记 (规格:预流-回放) 转弯的唯一呼号,只有 输入, 结束转弯 `error` 并且没有记录,包含输入. `turn:end` 它的失败会毒害行刑 任何其它地点 标记被丢弃,作为任何失败。 它最多旋转一次; 摘要和重试使用相同的根限制。 没有基于例外的后退后退(指: safe-context-rejection-rotation).

可选请求 `toolChoice` 也作为副本被冻结并被封住,包括: 缺席,截至 `step:pre`. 拒绝注射、取出或替换虎克 记录为元数据。 Canonical 对话不能提供全球强制工具 设置;使用官方规范的阶梯跑取器进行一次呼叫结构提取.

## 常见问题

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

阿尔玛统治了转弯引擎:步骤,工具发送,授权和缓存卫生\.

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

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

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

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

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

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

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

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

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

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

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

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

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

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