# @gobing-ai/ts-llm-jsonl-importer 中文文档

规范地址：https://npmcn.com/package/%40gobing-ai/ts-llm-jsonl-importer/

版本：0\.7\.1
npm 元数据更新时间：2026-10-25T00:56:17.070Z
中文译文更新时间：2026-11-16T17:44:41.147Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40gobing-ai/ts-llm-jsonl-importer
原文对照：https://npmcn.com/package/%40gobing-ai/ts-llm-jsonl-importer/?lang=original
项目主页：https://github.com/gobing-ai/ts-libs#readme
源码仓库：https://github.com/gobing-ai/ts-libs

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

- 包体积（解压后）：622 kB，66 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-06-01T00:01:08.247Z
- 最新版本发布：2026-10-25T00:56:16.717Z
- 近 30 天下载量：6672（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：130（近 12 个月 130 个）

## 中文简介

@gobing-ai/ts-llm-jsonl-importer-通用JSONL导入器用于LLM代理历史文件.

## 安装

```sh
npm install @gobing-ai/ts-llm-jsonl-importer
```

也可以使用：`pnpm add @gobing-ai/ts-llm-jsonl-importer`、`yarn add @gobing-ai/ts-llm-jsonl-importer`、`bun add @gobing-ai/ts-llm-jsonl-importer`

## README

# @gobing-ai/ts-llm-jsonl-进口商

通用 JSONL 为AI - 代理历史风格文件导入管道:发现文件,解析行,正态源字段,校正敏感值,被分类散列所分解,并持续ETL行.

## 它提供什么

`ts-llm-jsonl-importer` 是普通的JSONL进口商。 它故意不是一个对话-历史域模型。 内置的源定义覆盖了常见的代理文件形状,但下游系统消耗了已正常化的ETL行和分类账元数据.

| 导出 | 目的 |
| --- | --- |
| `runJsonlImport()` | 运行出发现,解析,验证,编辑,去dupe,并有持久性. 接受内置源字符串 **或者说** 习惯 `SourceDefinition`。 。 。 . |
| `applyHistoryImportSchema()` | 安装进口商拥有的检查站、分类账和打字合同表格 |
| `SOURCE_DEFINITIONS` | 内置源定义 |
| `getSourceDefinition()` | 按密钥返回一个内置定义( 扔出) `HistoryImportError` 未知密钥) |
| `resolveSourceDefinition()` | 决定a `string | SourceDefinition` 成为经验证的定义 |
| `validateSourceDefinition()` | 在管道输入前验证自定义(目标表名称、所需字段) |
| `VALID_TABLE_NAME` | 规范每个进口商拥有的ETL 表格名称的 Regex |
| `redactRecord()` 编号 : `redactValue()` | 在持久性之前应用编辑规则 |
| `sha256()` 编号 : `stableJson()` | 分类账所用的稳定散列辅助工具 |
| `HISTORY_IMPORT_SCHEMA_SQL` | SQL 明确迁移流量的 SQL 计划字符串 |

内置源密钥为 `claude`, (中文(简体) ), `codex`, (中文(简体) ), `gemini`, (中文(简体) ), `pi`, (中文(简体) ), `opencode`, (中文(简体) ), `antigravity`, (中文(简体) ), `openclaw`, (中文(简体) ), `omp`, (中文(简体) ), `grok`, (中文(简体) ), `agy`,以及 `deepseek`编辑 `agy` 源扫描 `~/.gemini/antigravity-cli`,涵盖两者 `history.jsonl` 财务报告和审定财务报表 `brain/**` 记录; 谈话 `.db` 存储于 `conversations/` 未导入.

这个 `deepseek` 源扫描 `$DSH_HOME/sessions` (倒计时) `~/.dsh/sessions`用于 `session-<uuid>/` 包含 `session.v3.jsonl` 或者说 `session.v3.jsonl.zstd`。压缩会话日志通过系统解压 `zstd` CLI——必须打开 `PATH`,否则导入失败,将出现可操作错误,命名为zstd和文件。 会话头行作为导入 `meta` 与会话一行 `cwd`· ; `user/message` 财务报告和审定财务报表 `assistant/message` 事件映射到用户/助理信件行(合并文本内容、时代) `time` ISO 时间戳, `source.model` ),而其他任何插件可扩展的事件类型(比较、钩子、标题)则被容忍并跳过;撕裂的崩溃尾巴被跳过(`corruptLinePolicy: 'skip'`) (中文(简体) ).

## 安装

```bash
bun add @gobing-ai/ts-llm-jsonl-importer @gobing-ai/ts-db
```

进口商希望 `DbAdapter`\- 兼容对象来自 `@gobing-ai/ts-db`。 。 。 .

## 基本导入

```ts
import { createDbAdapter } from '@gobing-ai/ts-db';
import { runJsonlImport } from '@gobing-ai/ts-llm-jsonl-importer';

const db = await createDbAdapter({ driver: 'bun-sqlite', url: './history-import.db' });

const result = await runJsonlImport('codex', {
    db,
    roots: ['./agent-history'],
    mode: 'incremental',
});

result.importedRecords;
result.skippedDuplicates;
```

`runJsonlImport()` 在处理前自动应用软件包自有计划。 使用 `applyHistoryImportSchema(db)` 当您的申请有明确的迁移步骤时,您可以直接申请.

## 导入模式

| 模式 | 行为 |
| --- | --- |
| `incremental` | 从最后一个导入的行检点读取每个文件 |
| `full` | 清除选定文件的检查点, 扫描所有行, 并且仍然通过分类散列来调试 |
| `force-file` | 在不使用检查站的情况下扫描所选文件,同时保留基于分类账的重复保护 |

所有模式保存返回的解析和验证问题 `ImportResult`; 不插入错误的行.

## 流线

对于未压缩的JSONL,进口商使用 `FileSystem.readFileStream` (ADR-021),读作 一次一行—— **O(行)内存** 用于行读组件, 因此多MB 或多GB历史 文件不需要全文缓冲。 行为与前一个相同 `readFile` + 拆分办法(相同) `source_line` 数值, 不变 `ImportResult`) (中文(简体) ).

两条路径在分行前缓冲完整文本,因此它们的内存缩放 **已解压 或文件大小** 而不是行数 :

-   `*.jsonl.zstd` 文档( `deepseek` (原始内容存档于2019-03-26) (中文(简体) ). ). . `zstd` 国 际 在分开之前.
-   何时 `readFileStream` 无法使用(例如Cloudflare工人),进口商返回到 `readFile` + 透明分割.

这个 `O(line)` 绑定只描述行读取器——登记发现、检查站地图和分类账 批次不在索赔之列.

## 取消

两个入口都接受合作社 `signal` (单位:千美元)`AbortSignal`, (中文(简体) ), [Spur 特性 A21](https://github.com/gobing-ai/spur/blob/main/docs/features/A21_reusable-execution-deadlines-and-unlimited-jobs.md) 编号 : [Spur ADR-112 (英语)](https://github.com/gobing-ai/spur/blob/main/docs/00_ADR.md):

```ts
const controller = new AbortController();
const resultPromise = runJsonlImport('codex', {
    db,
    roots: ['./agent-history'],
    mode: 'incremental',
    signal: controller.signal,
});
controller.abort(); // cancel from a watchdog, shutdown hook, or deadline
```

取消是合作性的:在安全边界检查信号——在图和 检查点在每一个源文件之前, 并在限定的批次之间写到 交易。 一批已经在飞行中先结算(记录、分类账和检查站写着) 进行解剖,然后运行 拒绝与 `ImportCancelledError` 联合国 `HistoryImportError`) (中文(简体) ). 和解后不再出现援引自有书写 最后一个已执行的检查点;一个被取消的中层文件运行时从不武装文件识别短路. `runOpenCodeImport` 取消时丢弃已队列但未发布的操作, 因此 OpenCode 存储在下次运行时保持权威 。 取消不能中断同步 SQLite —— 抑制过程仍然是阻断工作的硬后退. 选择 `signal` 保留现有行为.

## 导入特定文件

```ts
const result = await runJsonlImport('pi', {
    db,
    files: ['/tmp/session-1.jsonl', '/tmp/session-2.jsonl'],
    mode: 'full',
    now: () => new Date(),
});
```

何时 `files` 提供,根被忽略。 当提供根时,导入者会走出每个根并选择与源定义模式相匹配的文件.

## 编辑

在散发和持久性之前进行重排,所以分类散发代表了被重排的恒定重载荷.

```ts
import { DEFAULT_REDACTION_RULES, runJsonlImport } from '@gobing-ai/ts-llm-jsonl-importer';

await runJsonlImport('openclaw', {
    db,
    roots: ['./history'],
    redactionRules: [
        ...DEFAULT_REDACTION_RULES,
        { name: 'account-id', pattern: /acct_[a-z0-9]+/gi, replacement: '[REDACTED:account]' },
    ],
});
```

规则被递归地应用于正则记录中的字符串字段.

## 结果形状

```ts
interface ImportResult {
    source: string;
    mode: 'incremental' | 'full' | 'force-file';
    scannedFiles: number;
    processedLines: number;
    importedRecords: number;
    skippedDuplicates: number;
    parseErrors: ImportIssue[];
    validationErrors: ImportIssue[];
    checkpointUpdates: number;
}
```

使用 `parseErrors` 用于无效的 JSON 或非对象行。 使用 `validationErrors` 用于解析但失败源定义的源行.

## 存储的表格

计划包括:

| 图表 | 目的 |
| --- | --- |
| `history_import_checkpoint` | 最后一个导入的行 |
| `history_import_ledger` | 稳定散列分解和出处分类账 |
| `history_message` | 从内置的法证地图上打印的普通消息 |
| `history_tool_call` | 从内置的法证地图员打来的普通工具呼叫 |
| `history_etl_<source>` | 通用/海关定义的修改有效载荷;仅在被接受一行目标之后产生 |

通用ETL表存储了正常有效载荷JSON外加源文件,源行,分出索引,散列和时间戳. Schema设置,空扫描,验证失败,干运行不会创建空的ETL表格. Claude 工具结果复制本地 `toolUseResult.durationMs` 或者说 `durationSeconds` 输入 `duration_ms`; 没有时间 留下来 `NULL` 并且从未从信息时间戳中推断出来.

## 拆分记录

一个来源可以将一行JSONL分割成几个打出或通用的记录. 内置源映射器将所支持的记录正常化为 `history_message` 财务报告和审定财务报表 `history_tool_call`;自定义可以针对一个通用的ETL表格.

```ts
const result = await runJsonlImport('pi', { db, files: ['session.jsonl'], mode: 'full' });
```

下游消费者应治疗 `source_file`, (中文(简体) ), `source_line`,以及 `split_index` 作为稳定出处的tuple.

## 自定义

除了内置源密钥, `runJsonlImport()` 接受完全指定的 `SourceDefinition` 用于任何自定义代理历史格式。 未知的字符串抛出 `HistoryImportError`; 自定义 在任何I/O(目标表名称必须匹配)之前验证 `VALID_TABLE_NAME` =: `/^history_[a-z_]+$/`, (中文(简体) ), 覆盖 `history_etl_*` blob 表格和类型 `history_message` 编号 : `history_tool_call` 表格, 需要的字段必须存在).

```ts
import { z } from 'zod';
import { createDbAdapter } from '@gobing-ai/ts-db';
import { runJsonlImport, type SourceDefinition } from '@gobing-ai/ts-llm-jsonl-importer';

const acme: SourceDefinition = {
    source: 'acme',
    displayName: 'Acme Assistant',
    defaultRoots: ['.acme'],
    filePatterns: ['*.jsonl'],
    targetTable: 'history_etl_acme',
    splitConfig: { mode: 'one-to-one' },
    fieldMap: { id: 'source_record_id', timestamp: 'created_at', content: 'content' },
    fieldTransforms: {},
    schema: z.object({
        source_record_id: z.string().min(1),
        created_at: z.string().min(1),
        content: z.string().min(1),
    }),
};

const db = await createDbAdapter({ driver: 'bun-sqlite', url: './history.db' });
const result = await runJsonlImport(acme, { db, roots: ['~/.acme'], mode: 'incremental' });
```

习惯 `source` 通过检查站、分类账和 `ImportResult.source` 没错 就像内置钥匙 如果不存在目标ETL表,则由进口商按需创建目标ETL表 (专有权) `CREATE TABLE IF NOT EXISTS`),所以内置表格不会受到影响.

## 技能呼叫能力事实(E93)

`history_skill_call` 将每个观察到的技巧引用分为四个无效的事实加一个 稳定身份:

-   `invocation_id` - 内容 - 隐藏身份结束 `(source, session, kind, id, ordinal, file, line)`· ; 一种援引的相关表述(例如编码x) `$skill` 标记加其伴 `<skill>` block)共享一个标识.
-   `capability_kind` —— 说 `skill`, (中文(简体) ), `command`,或 `subagent` ——引用目标文物的地方 决心(首先进行本土分类,然后是独特的供应来源); `NULL` 当未知时).
-   `origin_identity` ——已解决文物的出土索引标识.
-   `evidence_kind` —— 说 `load` (已执行/已执行技能), `request` (命令拼写由 用户),或 `delegation` (代理对代理代理发送).
-   `status` —— 说 `unknown` 直至一对一工具结果将行上(`ok`编号 :`error`或绳子 包装本身就是经过验证的注射.

能力分类从不从名称拼写中推断:a `$sp-dev-run` 无标记 匹配命令记录或技能块分类为未知。 通过一个已验证的出处索引 已解析的进口合同来源部分( 无效的条目在写入前拒绝运行) :

```ts
const result = await runJsonlImport('codex', {
    db,
    files,
    mode: 'incremental',
    capabilityOrigins: [
        {
            source: 'codex',
            skillName: 'sp:dev-run',
            skillPath: '/skills/sp-dev-run/SKILL.md',
            artifactDigest: sha256Text(body.trim()),
            capabilityKind: 'skill',
            originIdentity: 'sp/src/skills/dev-run',
        },
    ],
});
```

文摘错配和相冲突的出处条目从不引起沉默的猜测:行归类为 未知,运行中报告一个有界限、有缺陷的验证结果。 贝壳读取 `SKILL.md` 文档(`cat`, (中文(简体) ), `sed -n '<range>p'`(b) 工具内的有效载荷——包括嵌入式 `tools.exec_command({cmd: ...})` 升-表面为隐性负载. 稍后可能会有结果 递增跑;对等倒回数据库并升级已设置的现有行.

## 边界说明

-   此软件包导入 JSONL 文件并写入进口商拥有的表格;它不建模对话,转会,工具调用,或分析语义.
-   源的定义是正常化边界. 下游应用程序拥有对ETL行的专有域解释.
-   进口商从不储存不正确的原始行. 通过内存报告解析和验证失败 `ImportResult`。 。 。 .

## 常见问题

### @gobing-ai/ts-llm-jsonl-importer 是什么？

@gobing-ai/ts-llm-jsonl-importer-通用JSONL导入器用于LLM代理历史文件\.

### 如何安装 @gobing-ai/ts-llm-jsonl-importer？

在项目目录运行 npm install @gobing-ai/ts-llm-jsonl-importer，或使用 pnpm add / yarn add / bun add。

### @gobing-ai/ts-llm-jsonl-importer 支持 TypeScript 吗？

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

### @gobing-ai/ts-llm-jsonl-importer 支持 ESM 还是 CommonJS？

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

### @gobing-ai/ts-llm-jsonl-importer 可以商用吗？

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

### @gobing-ai/ts-llm-jsonl-importer 的下载量有多少？

根据 npm 官方下载统计，@gobing-ai/ts-llm-jsonl-importer 在 2026/10/17 – 2026/11/15 这 30 天内被下载 6,672 次，日均约 222 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gobing-ai/ts-llm-jsonl-importer 还在维护吗？

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

