# @alma-harness/core 中文文档

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

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

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

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

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

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

## 中文简介

Alma核心合同:代理环路,中性信息,范围工具,预算,路线政策,租赁/审计,生命周期事件,常规.

## 安装

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

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

## README

# @alma-harness/ core (英语)

合同和安全核心 [阿尔玛](https://github.com/FabioFernandesCarneiro/alma) ——用于多租户代理在敏感数据上运行的TypeScript运行时间. 冲向他们的引擎是: [`@alma-harness/loop`](https://npmcn.com/package/%40alma-harness/loop)。 。 。 .

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

## 它拥有的

每个软件包都讲词汇,引擎可能不会讲规则 弯曲。 这里定义了允许旋转的动作; 执行的引擎 它住在这里 [`@alma-harness/loop`](https://npmcn.com/package/%40alma-harness/loop)。 。 。 .

-   **信件** (单位:千美元)`Msg`, (中文(简体) ), `Block`)——每个提供者的中性格式是: 翻译来回。 一个文本块 `origin: "harness"` 现附上 由牵引(倒转起伏起后缀,谱:倒转起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起伏起相起相起起相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 由个人输入; `"human"` 财务报告和审定财务报表 `"system"` 标记一个记录的事实 从产品侧面看到 专业信息或 自动通知(规格:对话-事件). `MsgMeta.event` 这是主机的 事实和类型`input`, (中文(简体) ), `message` 或者说 `undelivered`),在一个 会话日志,和 `MsgMeta.turn` 转弯的id记录了 留言。 A 类 `media` 块按引用方式行走:带有 `MediaSource` 配置了循环, 要求产品显示字节, 它们会走 作为基准64, 向提供方提供, 会话将仅限参考( 请参见 : ; 没有一个字节, 引用会交给提供者 按种类和大小逐个记录 绝对不会 URI(规格:What-the-wire-cuts). 绳子本身从不取来.
-   **租赁** (单位:千美元)`Scope`, (中文(简体) ), `scopePath`(b) —— `{org, uid}` 被关闭束缚 模型 从未看到或选择它; 由经过验证的身份产生它就是主机 应用程序的工作.
-   **生命周期事件** (单位:千美元)`LifecycleHooks`, (中文(简体) ), `Interceptor`)——封闭的一组 输入的接缝可附加一个扩展,仅能缩小能力.
-   **工具** (单位:千美元)`defineTool`——登记能力。 模式可能是什么 调用来源于每个步骤的登记簿,而从来不是可以扩展的清单. 产出以登记为准(`maxOutputChars`,默认适用: 并删除 它以后花费比它节省更多。 已声明的工具 `deferred` 离开 在引擎内置搜索器后再装入前缀 (规格:递延工具). 由提供者执行的工具( E)`ProviderToolSpec`, (中文(简体) ), {\\fn华文楷体\\fs16\\1che0e0e0}今天 `web_search`)在请求中宣布,运行在提供者的 侧面,然后回来 作为两个中性块—— `provider_tool_call` 财务报告和审定财务报表 `provider_tool_result`,供应商标记,供应商的有效载荷 `opaque` 用于重放—— a `maxSensitivity` 上限, `internal` 默认 (规格:提供者-工具).
-   **路线** (单位:千美元)`ModelPolicy`, (中文(简体) ), `Sensitivity`, (中文(简体) ), `Tier`——复杂性 – 敏感性, 立即执行,绝不通过代表升级。 政策 也说模型会有多难思考`ModelChoice.reasoning`,光谱 : 它所产生的推理是: `Block` 留下来 后台——在会话中,从不回答.
-   **预算** (单位:千美元)`BudgetCaps`, (中文(简体) ), `priceUsage`, (中文(简体) ), `SpendStore`——美元上限, 失败的封闭定价:无价模型从未花费过 无价服务级或无价网络搜索(`webSearchUsdPerRequest`);表格带有分级和上下文带;以及 定价遵循电线所说的电线等级(规格:定价等级). `perTurnUsd` 数字块时 `{ usd, onExceeded: "warn" }` 继续并报告过境情况;会话和租户日上限核算 通过 `SpendStore` 与人均政策相接—— `warn` 默认( 转弯继续,报告过境情况), `block` 选入.
-   **审计** (单位:千美元)`AuditLog`——接入,出行路线,成本,召回和上下文出行. 他们在哪里 写入可互换; _那个_ 他们没有写.
-   **旋转标记** (单位:千美元)`MsgMeta.rotation`——简讯: 代表较早的(指:长文)。 该日志从未被重写; 引擎的视图从标记开始.
-   **为什么转弯失败** (单位:千美元)`TurnFailure`, (中文(简体) ), `FailureKind`, (中文(简体) ), `ProviderError`)——一个 每个提供方和连接方的闭合词汇,其中一项裁定 a 产品: `retryable`,无论同一请求是否保持不变 后继成功( spec: error- taxonomy). 适配器抛出 `ProviderError`; 数据 引擎对内部故障进行分类。 可重试的提供者诊断不会 授权重播 允许的犬科手术.
-   **一个有栅栏的附属物** (单位:千美元)`AppendOpts`, spec: 栅栏-事件附录:共享的商店 除非被允许的会话为 正在运行, 检查并保存在附件的交易中 。 在记忆中 参考文献同步写出,在勾选框中,跑者检查最后期限.
-   **对话所有权** 活在处决的持久行动接纳. TurnStore及其到期的租赁/索赔类型被删除。 夸夸其谈 重放会绑定输入和配置; 不确定性永远不会允许自动重试 .
-   **请求控制** (单位:千美元)`ModelRequest`, spec: 提供者-请求-控制)——本土 JSON schema输出和明确的Anthropic缓存控制. 这些是适配器 输入,未验证结果或受管制的单调跑者. `cache: false` 禁用断点; `conversationTail: false` 只有稳定系统 前缀。 其他适配器拒绝明确的缓存控制. 输出方案变化 从 `step:pre` 拒绝并登录,包括试图增加.
-   **示范工作** (单位:千美元)`ModelJobClient`() 提供商回答的一次性工作 批量 API( spec: model-jobs). 工作可互换的地方 瞄准 路由 盘查 线索上是跑者 `@alma-harness/loop`。 。 。 .
-   **常规** (单位:千美元)`Routine`, (中文(简体) ), `TriggerSource`, (中文(简体) ), `RoutineStore`, (中文(简体) ), `OutputSink`, (中文(简体) ), `RoutineRunStore`(b) —— 常规是数据:目标、意图、时间表、剖面图或无剖面图 拥有每个运行的封顶,一个被命名的目的地(§8, spec: rout-runner). 这里 计时点火,结果发生地点和记录运行地点 缝合; 执行前声称运行, 封顶并记录 是赛跑者的,在 `@alma-harness/schedule`。 。 。 . `RoutineRunStore.claim` 实值 强制和原子:插入 `running` 只有在缺席或过渡时 `submitted` 改为 `running` 用于收集。 索赔需要中断 校正; 参见 [追回附注](https://npmcn.com/package/%40alma-harness/schedule/README.md#claims-and-recovery)。 。 。 .
-   **内存合同** (单位:千美元)`EpisodeStore`, (中文(简体) ), `ProfileStore`, (中文(简体) ), `MemoryErasure`,(.)—— 由于内存与租赁、审计和 路由; 实施 `@alma-harness/memory`。 。 。 .

## 永远不能做的事

-   到达文件系统,产出一个子进程,或者运送一个外壳. 从来没有.
-   接受模型中的范围,或让钩子重写路径、预算或 已公布工具集.
-   取决于供应商SDK。 中性消息格式为边界.

## 测试助手

`@alma-harness/core/testing` 合同执行情况 此软件包发布 — 一个录音 `AuditLog`和记忆 `SessionStore`, (中文(简体) ), `SpendStore`, (中文(简体) ), `CostSettlementStore` 财务报告和审定财务报表 `RoutineRunStore`里面没有进口维特 共享 每个适配器都必须通过存储合同套房 `@alma-harness/testing`; 内存存储器 `@alma-harness/memory/testing`; 脚本 `ModelClient` 驱动器 引擎进入 [`@alma-harness/loop/testing`](https://npmcn.com/package/%40alma-harness/loop)。 。 。 .

```ts
import { InMemorySessionStore, RecordingAuditLog } from "@alma-harness/core/testing";
```

财务警告的使用 `BudgetCapName` (单位:千美元)`perTurnUsd` 加上不变的 `PersistentCapName`) (中文(简体) ). `normalizePerTurnCap` 验证和复制明确的政策. 例行运行/交付元数据 `capsCrossed`; 空运行数组正态 可在两个参考商店中缺席。 见Spec:金融预警政策.

## 费用结算基础

`CostSettlementStore` 记录已知的定价使用量,并附有主机发布的范围ID. `settle` 返回应用程序/重放的收件。更改其常态输入为 a `SettlementConflictError`。执行者必须在发送前坚持身份 并保留调节用法。 这家店从来不派供应商. 重放总数为历史;当前预算检查使用情况 `SpendStore.peek`。 。 。 .

`normalizeCostSettlement` 拒绝未知字段并快照已关闭的记录 在 I/O 之前。 ID 是 1 - 200 非空格可打印的 ASCII 字符; 范围也服从 `scopePath`。时间戳要求有一个区,最多精确到毫秒。 可选 使用零与缺勤仍然不同. `serviceTier` 已解析价格 等级; `capsCrossed` 保留预先计算的证据,而不评价政策. 消费者(可达16个)是一个明确的列表,可能是空的.

范围d `get`编号 :`list` 读取收据; `list` 默认为 50 (最大100) 和过滤器 按操作、模型、价位和包容性发生间隔计算。 它的上升 `(at, id)` 光标是观测的,不是可靠的预测偏移. `pending` 返回消费者的完整未确认收据 应用一权。 重放从不重现公认的义务. `InMemoryCostSettlementStore` 和拥有单独的柜台。 这个 Postgres的执行共用现有的耐用开支计数器.

请不要通过此连接和遗留的审计/支出来记录一次呼叫. 受管跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑跑 现有作者。 每个调用选择一条会计路径 。 见 [一元成本解决](https://npmcn.com/package/docs/specs/077-idempotent-cost-settlement.md)。 。 。 .

## 单发证据

`SingleDispatchModelClient` 是一个可选择的可信任主机能力( 规格 : 提供者- 发送证据 . `validate` 检查没有I/O请求的支持; `streamEvidence` 单消费,并报告有限度的请求参考 和最后决定 `UsageEvidence` 与内容/停止活动分开。 新方法 调用是一个新发送:执行者必须先持久地声称它.

证据的区别 `known`, (中文(简体) ), `unpriced` (已知的、未解决的归属), `unknown` 和预先堕胎 `not_dispatched`。仅限 `known` 可能定价。 新的 OpenAI 证据规范普通输入,不包括缓存读取和写作, 他们有不同的价格条件。 现有的遗产使用图没有变化. 排出溪流:提前返回会关闭运输,但可能会留下账单未解决. 提供者错误的可重试旗帜不是授权重发送相同的 操作。 还没有一个能耐的跑者采用这种能力.

## 持久执行日记

`ExecutionStore` (规格:持久-执行-记录) 保持无内容要求, 使用证据和原始的定价快照. `InMemoryExecutionStore` 从 `@alma-harness/core/testing` 执行与PostgreSQL相同的合同。 只有 (b) 阅读和准确的复读从未进行. `dispatch` 必须在提供者入侵前做出承诺,不能重放. `receive` 保留 已知/无价/未知的区别. `list` 揭露未解决的有范围元数据; `reconcileExpired` 栅栏已过期准备/分发工作,不再重新发送.

A 类 `not_dispatched` 记录携带 `notDispatchedCause` 当它转型时 为什么(规格:不分发原因): `aborted`, (中文(简体) ), `audit`, (中文(简体) ), `store`, (中文(简体) ), `input` (单位:千美元) 主的装载器抛出, `invalid` (以配置或装入的方式重复)或 `expired` (扫荡关闭了它)。 一个原因是观察,而不是判决: `invalid` 支持压制未修改的重试,而缺省或 `expired` 意为未知. `cancelPrepared(fence, cause?)` 记录所有者的原因一次; 它拒绝 `expired`,只有扫描记录.

索赔重审必须重新利用全部原始投入,包括价格和时间戳. 回收租赁围栏日记只写作;一能解决仍需 `CostSettlementStore` 与原结算 爱德 此日记没有调用 提供者或结算账单、储存答复或标记结果完成。 在此之前 应用、范围化结果存储/检测以及权威的持久收件箱 围栏后抵达的使用是强制性的。 设定发送期限 供应商超时加排水宽限期;保存被拒绝的后期证据.

`ExecutionResultStore` (spec 081) 保留范围广的呼叫/会议身份 上下文在明确敏感性下读取并存储一个封闭的响应信封, 保留和字符封顶。 已删除/已过期的身份无法恢复; 主机 需要清理时间安排和经审计的去除构成。 合同和 无内容错误在这里存在;执行在内存和PostgreSQL中存在.

## 文档

[文件索引](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)

`UsageInbox` 保存范围化的用法观察; 帮助者/参考者存在 `@alma-harness/execution`邮箱里的SQL 它不授予发送或开具账单的权力.

阿帕奇 - 2.0

管理日记输入可选快照 `governance` (盖,消费者,结果) (续). `executionSettlementRequest(record)` 重建原始请求. 管理会计之后, `settle(fence, {request, receipt})` 财务报告和审定财务报表 `complete` 持续 栅栏寿命周期过渡; 从未用 `decisions`。 。 。 . 恢复可能完成已结算记录,永远不再重新发送;完成不是交付. 结果内容/感受仍然分开。 新读者先于被统治的作家. `normalizeBudgetCaps`, (中文(简体) ), `normalizeSpendTotals`, (中文(简体) ), `normalizeCostReceipt` 财务报告和审定财务报表 `costReceiptWarnings` 共享整个日记账和会计的封闭式财务细则. 见 [受管的执行周期](https://npmcn.com/package/docs/specs/084-governed-execution-lifecycle.md)。 。 。 .

运行事件和访问事件 可选携带操作 Id/AttopId/ callId for 受管的单调; turnId保留了它最初的对话意义.

`ModelRequest.temperature` 是可选的;适配器在跳出前验证支持 (规格:显式-温度-控制). 执行控制持续有限 `0..2` 值和正态负零。 缺漏保存提供者默认值 .

`tryDelegate` 返回 a `DelegateAttempt`;转发拒绝是明确的(规格:受管-委托-拒绝).

已知的证据可能证明无用Anthropic上下文拒绝(指: safe-context-rejection-rotation). 普通零使用不能授权重试 . `RejectionProof` 增加了三个前流拒绝, `anthropic_rate_limit_v1`, (中文(简体) ), `anthropic_overloaded_v1` 财务报告和审定财务报表 `openai_rate_limit_v1`,每个约束于其提供者在 `REJECTION_PROVIDERS`,带有零计数,且从未在批量级( spec: pre-stream-rejection).

`ModelRequest.toolChoice` 是可选的主机拥有生成政策 : `{ type: "auto" | "none" | "required" }` 或者说 `{ type: "tool", name: "capture" }`。 。 。 . `normalizeToolChoice` 验证并复制其封闭形状; `validateToolChoice` 检查实际广告 `ToolSpec[]`,拒绝缺失或模糊的名字. 适应者还进一步强制执行其记录模型/控制支持。 缺席 保留现有行为; 显式自动保持与缺席不同 . 执行控制坚持选择,所以在现有的身份下改变 冲突。 选择绝不授权工具执行或个人记忆写入 . 见 [所管理的工具选择](https://npmcn.com/package/docs/specs/159-governed-tool-choice.md)。 。 。 .

## 会话标签

`SessionLabelStore` ( spec: session- labels) 保留主机的归属为 a 会话——绘制假名范围/会话背面的不透明标识符和旗帜 给主机自己的记录——除了不可改变的收据之外,所以可以切除 这个. `normalizeSessionLabels` 接受1-8项,密钥 `^[a-z][a-z0-9_]{0,31}$`, (中文(简体) ), 数值 `^[A-Za-z0-9_.:-]{1,128}$`:只进行综合,从不进行个人数据值. `put` 存储一次( 等重播放返回记录, 不同的标签丢出) `SessionLabelConflictError`(三); `erase(scope, sessionId)` 墓碑, `erase(scope)` 封住瞄准镜,或者在后面 `put` 掷出 `SessionLabelErasedError`。 。 。 . 写作和去除每个范围序列化。 标签从不驱动路径,访问, 定价、审计或范围. `InMemorySessionLabelStore` 进入 `./testing`。 。 。 .

## 常见问题

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

Alma核心合同:代理环路,中性信息,范围工具,预算,路线政策,租赁/审计,生命周期事件,常规\.

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

在项目目录运行 npm install @alma-harness/core，或使用 pnpm add / yarn add / bun add。

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

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

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

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

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

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

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

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

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

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

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

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