@gobing-ai/ts-llm-jsonl-importer

中文文档
0.7.1发布于 2026/10/25Apache-2.0TypeScriptES Module构建来源已验证近 30 天下载 6672

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

中文使用文档
文档目录14 节
  1. 它提供什么
  2. 安装
  3. 基本导入
  4. 导入模式
  5. 流线
  6. 取消
  7. 导入特定文件
  8. 编辑
  9. 结果形状
  10. 存储的表格
  11. 拆分记录
  12. 自定义
  13. 技能呼叫能力事实(E93)
  14. 边界说明

@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_SQLSQL 明确迁移流量的 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') (中文(简体) ).

安装

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

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

基本导入

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 编号 : Spur ADR-112 (英语):

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 保留现有行为.

导入特定文件

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

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

编辑

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

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]' },
    ],
});

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

结果形状

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表格.

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 表格, 需要的字段必须存在).

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 无标记 匹配命令记录或技能块分类为未知。 通过一个已验证的出处索引 已解析的进口合同来源部分( 无效的条目在写入前拒绝运行) :

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 共发布 130 个版本,首次发布于 2026/06/01;过去 12 个月发布了 130 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.7.1latest2026/10/2522 天前
0.7.02026/10/2522 天前
0.6.42026/10/2423 天前
0.6.32026/10/2423 天前
0.6.22026/10/2324 天前
0.6.12026/10/2324 天前

关于 @gobing-ai/ts-llm-jsonl-importer 的常见问题

@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 和提交记录判断。