# @alma-harness/history 中文文档

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

版本：0\.41\.0
npm 元数据更新时间：2026-11-04T12:53:42.402Z
中文译文更新时间：2026-11-09T22:51:58.953Z
软件包许可：Apache-2\.0

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

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

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

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

## 中文简介

原子同位素中立会话历史导入阿尔玛.

## 安装

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

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

## README

# @alma-harness/历史

将中立历史 刻意输入阿尔玛会议 没有供应商, 媒体获取、历史工具执行或财务写入。 主机转换, 来源授权和实际削减仍然是单独的责任.

运行 `migrateHistoryImportStore(pool)` 作为迁移本金,给予运行时间 在配置的应用角色中登录成员, 然后构建 `new PostgresHistoryImportStore(pool, {statementTimeoutMs: 30000})`. 移徙 重新使用现有会话表并添加三个FORCE-RLS元数据表加无效 `alma_sessions.history_import_generation`。运行时不需要超级用户权限. 使用可信任的 schema 搜索路径和正常的被范围化的池合同 .

```ts
const first = await imports.append({
  source: {
    scope: {org: 'organization', uid: 'user'}, sessionId: 'conversation',
    source: 'archive', sourceSessionId: 'old-conversation',
    sourceRevision: 'fixed-export-v1', importId: 'migration-1',
  },
  ordinal: 0, previousChecksum: null, final: false,
  entries: [{sourceId: 'message-1', message: {
    role: 'user', blocks: [{type: 'text', text: 'Earlier message'}],
    meta: {at: '2025-01-01T00:00:00.000Z'},
  }}],
});
// Next chunk: same source, ordinal 1, previousChecksum first.checksum.
// Set final only when the entire fixed export has been imported.
```

`read(source)` 返回最近不可变的收发/检查点; `receipt(source, ordinal)` 读前一个. `append` 计算其SHA256;精确 即使在内容去除后再播放返回原收发. 改变的来源, 内容、顺序、前身、最终旗帜或再利用源条目ID相冲突。 每个 块有1~100个消息,最多1个米B犬UTF-8 JSON和深度64. 所有输入 必须是平庸的 JSON , 带有成型良好的字符串, 有限的数字和闭合的中性 信件/块/元件形状。 所需时间戳按时间顺序排列。 工具必须 在一个块内完成匹配交换;拒绝内置介质。 旋转 跨度不能超过导入历史或切换工具。 布尔 输入元数据中的边框旗可以验证交叉切口而不装入旧的 内容。 拒绝 Sparse/ extra 数组属性和内置数据 URI 。 角色和订货内容都活下来了.

最初必须排除目标。 停下来 **全部** 写作和维护 改写历史(包括工具流量过期),使消费者远离,直至 最终收据存在。 Live supports between 块块冲突在计数器上。 这个 导入生成 防止被擦除并重新创建的会话冒用 老目标 没有在线双写或与已存在的活历史合并. 旧读取器与已失效的添加剂列相兼容; 旧迁移 重放不会删除它 。 在导入作者前运行匹配的新迁移 .

收据、描述和输入绘图只储存源识别器、散列、, 序列/时间戳元数据和生成。 内容有一份,现有 会话条目。 App 元数据权限为 SELECT/ INSERT; 没有删除/覆盖 API 存在 。 会话擦除可以保存收据, 永远不要重现重放的数据, 并堵住失踪或娱乐后的新块。 整体遗产来源 重新授权仍然是主机水印/蒸发边界。 不清理收据 没有明确的未来留存合同:这样做结束于重新发挥保护作用.

承诺块是原子及其消息和顺序; 重放修复丢失的块 承认。 A 类 `final` 收据证明进口完成,而不是授权 生产激活。 历史成本/期初余额保持不变;从未 制造型号使用或重新安装进口的文字记录内容.

`@alma-harness/history/testing` 出口 `InMemoryHistoryImportStore`,合同 与检查/记录/实况附录的帮助者有关。 这不是第二件书信 会话主机或生产迁移后端。 共享验收套件 运行此引用和 PostgreSQL 导入器,读取实际导入行 结束 `PostgresSessionStore`。这是可执行的消费者;没有普鲁莫场景 加上,因为它不是一个移徙工具,其来源预算几乎已满.

## 历史成本来源

`migrateHistoricalCostStore(pool)` 安装单独的不可移动报告分类账. `PostgresHistoricalCostStore` 支持相同的范围集合选项; 其测试 引用为 `InMemoryHistoricalCostStore`也没有写直播费计数器, 结算、审计事件或投影箱。 导入历史从未创建 模式使用。 开口量是历史报告,不是活封顶播种.

```ts
await costs.append({
  scope: {org: 'organization', uid: 'user'}, key: 'archive-before-cutover',
  sessionId: 'conversation', source: 'archive', sourceRevision: 'export-v1',
  authorityRevision: 'cutover-v1',
  from: '2025-01-01T00:00:00.000Z', until: '2025-02-01T00:00:00.000Z',
  representation: 'opening', costUsd: 12.5,
});
```

替代使用 `representation: 'itemized'` 财务报告和审定财务报表 `entries` 联 合 国 `{sourceId, at, costUsd, model?}` (1-1000),无上层金额. 行排序 即时/源ID在散发和相声之前. 美元是有限和非负数的;模式 只是一个不透明的历史标签。 快照是关闭平原JSON,最大一米B. 精确的正态重放保留了原始收件/时间. 更改了关键内容, 任何来源/代表之间重叠的会话间隔和重复的来源 同一范围/来源/修订冲突的身份证。 间距为半开;相邻 间隔有效。 分离边界出口或使用一个开口 以一个不可分割的大间隔来计算和保存外部档案.

`get(scope,key)` 包括完整的快照. `list(scope,{sessionId?,afterKey?,limit?})` 返回 ASCII- key 元数据页(max100),不包含项目数组. `summary(scope,sessionId)` 返回历史美元和覆盖范围/代表数,不计算时间. 浮动总额遵循现有的成本惯例。 App 角色无法更新/删除 收据或源头映射;内容去除保证保存这些财务记录.

主机必须发布一个版本化的权威 显示地图的遗留会话/来源 身份证发给他们的目标,不包括土著居住区所有的费用. Dashboard 总和可能将不相干的历史总和添加到原生项目中一次 成本; root/batch包容性预测不是额外收费。 活盖 连续性需要一个明确的主机基线:这个分类账从来不会默默地播下它. 东道方拥有出口授权、身份测绘和切换;收据赠款 没有权限运行真正的导入或激活产品.

## 常见问题

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

原子同位素中立会话历史导入阿尔玛\.

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

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

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

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

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

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

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

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

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

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

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

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

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

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