@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') (中文(简体) ).
安装
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。 。 。 .