1. 多工具链对接时数据格式为什么总是对不齐如果你同时用 Claude Code 写后端、用 Cursor 调前端、偶尔在 Codex CLI 里跑 Agent 任务大概率动过一个念头把这些工具里的对话记录统一收拢起来做检索、做归档、做二次分析。然后你打开它们的数据目录念头就凉了一半——Claude Code 是 JSONLCursor 是 SQLite 的state.vscdbCopilot 又是带快照语义的 JSONL字段名、嵌套层级、消息类型标记全都不一样。这不是某个工具设计得烂。Claude Code 从终端起步追加写入的 JSONL 天然抗崩溃Cursor 是 VS Code 的 fork直接继承了state.vscdb这套键值存储Codex CLI 走事件溯源路线因为它要记录的是工具调用、代码执行这类非线性交互。每个格式都是各自技术起点的合理产物谁也不会为了第三方解析方便去改自己的存储层。所以真正的问题不是能不能统一格式而是统一这件事该放在哪一层做。把差异硬塞进业务代码里每接一个新工具就要改一遍解析、摘要、索引逻辑维护成本会指数级上升。工程上更稳的解法是适配器模式定义一个SourceAdapter接口让每个工具的实现去消化自己的格式差异核心流程只认一种内部结构。下面我把这套骨架拆成可复制的代码和配置你可以直接拿去改。2. 前置准备TaoToken 接入与工程环境在写适配器之前先把模型调用这条链路打通否则你解析出来的对话没法做摘要和 Embedding。我这边统一走 TaoToken 的 OpenAI 兼容接口好处是 Claude、GPT 系列用同一套 SDK 调用适配器层不用再关心模型厂商差异。先去控制台建一个 API Key地址是 https://taotoken.net/api-keys 登录后在密钥管理页新建即可。拿到sk-开头的 Key 之后记下两个端点用途地址对话补全https://taotoken.net/api/v1/chat/completions模型列表https://taotoken.net/api/v1/models工程侧建议用 Node 18 或 Python 3.10本文示例用 TypeScript因为适配器接口用 interface 表达最清晰。初始化项目mkdir ai-source-adapter cd ai-source-adapter npm init -y npm i better-sqlite3 undici npm i -D typescript tsx types/node types/better-sqlite3 npx tsc --init --target ES2022 --module NodeNext --moduleResolution NodeNextbetter-sqlite3用来读 Cursor / Trae 的state.vscdbundici负责调 TaoToken 接口。环境变量里放 Keyexport TAOTOKEN_API_KEYsk-你的密钥 export TAOTOKEN_BASE_URLhttps://taotoken.net/api/v1注意Key 不要写进代码提交到仓库用.env加.gitignore或者直接走系统环境变量。团队协作时建议每人各自申请方便按调用量排查问题。如果你还想先确认模型名和返回结构可以打开模型对话页 https://taotoken.net/model-chat 手动发一条消息观察返回 JSON 里choices[0].message.content的形态后面写摘要适配器时会用到。3. 可复制配置SourceAdapter 接口与注册表核心思路是把读哪个目录、怎么解析、怎么过滤噪声全部封进适配器对外只暴露三个方法。先定义统一输出结构这是整个系统的普通话// src/types.ts export interface ParsedMessage { id: string; parentId: string | null; type: user | assistant | system; content: string; hasToolUse: boolean; hasCode: boolean; timestamp: string; } export interface ParsedConversation { id: string; source: string; projectDir: string; cwd: string | null; messages: ParsedMessage[]; firstMessageAt: string; lastMessageAt: string; } export interface ConversationMeta { id: string; filePath: string; sizeBytes: number; mtime: string; } export interface SourceInfo { name: string; displayName: string; rootDir: string; fileCount: number; }接着是接口本体三个方法对应探测—扫描—解析三段式流程// src/adapter.ts import type { SourceInfo, ConversationMeta, ParsedConversation, } from ./types.js; export interface SourceAdapter { readonly name: string; readonly displayName: string; /** 检测本机是否存在该工具的数据目录 */ detect(): PromiseSourceInfo | null; /** 只列元数据不解析内容用于快速建索引 */ scan(): PromiseConversationMeta[]; /** 解析单个会话输出统一结构 */ parse(meta: ConversationMeta): PromiseParsedConversation; }注册表用一个 Map 管理新增工具只加一行// src/registry.ts import type { SourceAdapter } from ./adapter.js; import { ClaudeCodeAdapter } from ./adapters/claude-code.js; import { CursorAdapter } from ./adapters/cursor.js; const registry new Mapstring, SourceAdapter(); export function register(adapter: SourceAdapter): void { registry.set(adapter.name, adapter); } export function getAdapter(name: string): SourceAdapter { const a registry.get(name); if (!a) throw new Error(未注册的适配器: ${name}); return a; } export function listAdapters(): SourceAdapter[] { return [...registry.values()]; } // 集中注册新增数据源只改这里 register(new ClaudeCodeAdapter()); register(new CursorAdapter());Claude Code 适配器的关键在噪声过滤它的 JSONL 里混着file-history-snapshot、progress这类非对话行必须按type字段跳过// src/adapters/claude-code.ts import { readFile, readdir, stat } from node:fs/promises; import { join } from node:path; import { homedir } from node:os; import type { SourceAdapter } from ../adapter.js; import type { SourceInfo, ConversationMeta, ParsedConversation, ParsedMessage, } from ../types.js; const SKIP_TYPES new Set([ file-history-snapshot, progress, system-reminder, ]); export class ClaudeCodeAdapter implements SourceAdapter { readonly name claude-code; readonly displayName Claude Code; private root join(homedir(), .claude, projects); async detect(): PromiseSourceInfo | null { try { const dirs await readdir(this.root); let count 0; for (const d of dirs) { const files await readdir(join(this.root, d)).catch(() []); count files.filter((f) f.endsWith(.jsonl)).length; } return { name: this.name, displayName: this.displayName, rootDir: this.root, fileCount: count }; } catch { return null; } } async scan(): PromiseConversationMeta[] { const out: ConversationMeta[] []; const dirs await readdir(this.root).catch(() []); for (const d of dirs) { const full join(this.root, d); const files await readdir(full).catch(() []); for (const f of files) { if (!f.endsWith(.jsonl)) continue; const p join(full, f); const s await stat(p); out.push({ id: f.replace(/\.jsonl$/, ), filePath: p, sizeBytes: s.size, mtime: s.mtime.toISOString() }); } } return out; } async parse(meta: ConversationMeta): PromiseParsedConversation { const raw await readFile(meta.filePath, utf8); const messages: ParsedMessage[] []; for (const line of raw.split(\n)) { if (!line.trim()) continue; let obj: any; try { obj JSON.parse(line); } catch { continue; } if (SKIP_TYPES.has(obj.type)) continue; const msg obj.message; if (!msg) continue; const content this.extractText(msg.content); if (!content) continue; messages.push({ id: obj.uuid ?? crypto.randomUUID(), parentId: obj.parentUuid ?? null, type: msg.role user ? user : assistant, content, hasToolUse: Array.isArray(msg.content) msg.content.some((b: any) b.type tool_use), hasCode: //.test(content), timestamp: obj.timestamp ?? new Date().toISOString(), }); } return { id: meta.id, source: this.name, projectDir: meta.filePath.split(/).slice(-2, -1)[0] ?? , cwd: null, messages, firstMessageAt: messages[0]?.timestamp ?? , lastMessageAt: messages.at(-1)?.timestamp ?? , }; } private extractText(content: unknown): string { if (typeof content string) return content; if (!Array.isArray(content)) return ; return content .filter((b: any) b.type text) .map((b: any) b.text) .join(\n); } }Cursor 适配器要读 SQLite用better-sqlite3同步查询更省事注意state.vscdb是键值表得先按 key 前缀捞出 composer 相关记录// src/adapters/cursor.ts import Database from better-sqlite3; import { readdir, stat } from node:fs/promises; import { join } from node:path; import { homedir, platform } from node:os; import type { SourceAdapter } from ../adapter.js; import type { SourceInfo, ConversationMeta, ParsedConversation, ParsedMessage, } from ../types.js; function cursorRoot(): string { const home homedir(); if (platform() win32) { return join(process.env.APPDATA ?? home, Cursor, User, workspaceStorage); } if (platform() darwin) { return join(home, Library, Application Support, Cursor, User, workspaceStorage); } return join(home, .config, Cursor, User, workspaceStorage); } export class CursorAdapter implements SourceAdapter { readonly name cursor; readonly displayName Cursor; private root cursorRoot(); async detect(): PromiseSourceInfo | null { try { const dirs await readdir(this.root); let count 0; for (const d of dirs) { const db join(this.root, d, state.vscdb); const ok await stat(db).then(() true).catch(() false); if (ok) count; } return { name: this.name, displayName: this.displayName, rootDir: this.root, fileCount: count }; } catch { return null; } } async scan(): PromiseConversationMeta[] { const out: ConversationMeta[] []; const dirs await readdir(this.root).catch(() []); for (const d of dirs) { const db join(this.root, d, state.vscdb); const s await stat(db).catch(() null); if (!s) continue; out.push({ id: d, filePath: db, sizeBytes: s.size, mtime: s.mtime.toISOString() }); } return out; } async parse(meta: ConversationMeta): PromiseParsedConversation { const db new Database(meta.filePath, { readonly: true }); const rows db.prepare( SELECT key, value FROM ItemTable WHERE key LIKE bubbleId:% ).all() as { key: string; value: string }[]; db.close(); const messages: ParsedMessage[] []; for (const r of rows) { let v: any; try { v JSON.parse(r.value); } catch { continue; } const text typeof v.text string ? v.text : ; if (!text.trim()) continue; messages.push({ id: r.key, parentId: null, type: v.role user ? user : assistant, content: text, hasToolUse: Array.isArray(v.toolFormerData), hasCode: //.test(text), timestamp: v.timestamp ? new Date(v.timestamp).toISOString() : new Date().toISOString(), }); } messages.sort((a, b) a.timestamp.localeCompare(b.timestamp)); return { id: meta.id, source: this.name, projectDir: meta.id, cwd: null, messages, firstMessageAt: messages[0]?.timestamp ?? , lastMessageAt: messages.at(-1)?.timestamp ?? , }; } }4. 验证请求同一份输入喂两类工具比对字段差异适配器写完必须验证否则你只是以为统一了。验证方法很直接拿同一段对话内容分别走 Claude Code 和 Cursor 的解析路径打印字段做 diff。先写一个跑批脚本// src/verify.ts import { listAdapters } from ./registry.js; async function main() { for (const adapter of listAdapters()) { const info await adapter.detect(); if (!info) { console.log([跳过] ${adapter.displayName} 未检测到数据目录); continue; } console.log([命中] ${adapter.displayName} 文件数${info.fileCount}); const metas await adapter.scan(); if (!metas.length) continue; const parsed await adapter.parse(metas[0]); console.log(JSON.stringify({ source: parsed.source, msgCount: parsed.messages.length, firstType: parsed.messages[0]?.type, hasCode: parsed.messages.some((m) m.hasCode), hasToolUse: parsed.messages.some((m) m.hasToolUse), firstAt: parsed.firstMessageAt, }, null, 2)); } } main().catch(console.error);跑起来npx tsx src/verify.ts预期输出类似[命中] Claude Code 文件数12 { source: claude-code, msgCount: 34, firstType: user, hasCode: true, hasToolUse: true, firstAt: 2025-01-15T10:30:00.000Z } [命中] Cursor 文件数3 { source: cursor, msgCount: 18, firstType: user, hasCode: true, hasToolUse: false, firstAt: 2025-01-14T08:12:33.000Z }关键看三个字段是否语义一致msgCount是否和工具里肉眼可见的轮次对得上firstType是否都是user开头hasCode是否和实际含代码块的会话吻合。如果 Claude Code 的msgCount明显偏大八成是SKIP_TYPES漏了某类噪声行如果 Cursor 的hasToolUse恒为 false说明toolFormerData的字段名猜错了去数据库里捞一条真实记录看看。再进一步把解析结果直接喂给 TaoToken 做摘要验证下游链路不感知来源差异// src/summarize.ts import { request } from undici; import type { ParsedConversation } from ./types.js; export async function summarize(conv: ParsedConversation): Promisestring { const transcript conv.messages .map((m) ${m.type}: ${m.content}) .join(\n) .slice(0, 8000); const res await request( ${process.env.TAOTOKEN_BASE_URL}/chat/completions, { method: POST, headers: { content-type: application/json, authorization: Bearer ${process.env.TAOTOKEN_API_KEY}, }, body: JSON.stringify({ model: claude-3-5-sonnet, messages: [ { role: system, content: 用三句话总结这段编程对话的核心任务。 }, { role: user, content: transcript }, ], temperature: 0.3, }), }, ); const data: any await res.body.json(); return data.choices?.[0]?.message?.content ?? ; }调用时你会发现summarize完全不需要知道conv来自 JSONL 还是 SQLite——这正是适配器层存在的意义。如果返回 401检查 Key 是否带上了Bearer前缀如果返回 404确认TAOTOKEN_BASE_URL结尾是/api/v1而不是/api。5. 本篇常见错排查报错一Cannot find module better-sqlite3原生模块编译失败多半是 Node 版本和预编译包不匹配。先node -v确认在 18 以上然后删掉node_modules和package-lock.json重装。Windows 上如果还报node-gyp相关错误装一次 Visual Studio Build Tools 的 C 工作负载即可。报错二Cursor 解析出 0 条消息先确认state.vscdb路径对不对。macOS 在~/Library/Application Support/Cursor/User/workspaceStorageWindows 在%APPDATA%\Cursor\User\workspaceStorageLinux 在~/.config/Cursor/User/workspaceStorage。路径对了还为空就用sqlite3 state.vscdb SELECT key FROM ItemTable LIMIT 20看看 key 的真实前缀不同 Cursor 版本可能从bubbleId:变成别的命名。报错三Claude Code 消息数虚高SKIP_TYPES没覆盖全。把解析时跳过的obj.type值打出来统计一下出现频率高但内容为空的类型直接加进集合。另外注意message.content是数组时只有type text的块才是正文thinking和tool_use要单独处理或丢弃。报错四TaoToken 返回 429并发太高触发限流。批量摘要时加个简单的串行队列或p-limit控制并发数在 3 以内重试间隔用指数退避。长期跑批任务建议直接上 Coding Plan配额更宽松适合 Agent 这类持续调用的场景入口在 https://taotoken.net/coding-plan 。报错五时间戳排序错乱不同工具的时间格式不统一有的是 ISO 字符串有的是毫秒时间戳。统一在适配器内部转成 ISO 再输出别把原始格式透传到ParsedMessage否则下游排序会踩坑。6. 把差异关进适配层让核心逻辑保持干净走到这里你应该能感觉到适配器模式的价值不在于消灭格式差异——那是不可能的工具厂商不会为你改存储。它的价值在于把差异收敛到一个可枚举的边界内新增一个数据源你只需要实现detect、scan、parse三个方法然后在注册表加一行摘要、Embedding、搜索索引这些下游代码一行都不用动。如果你打算把这套东西接到长期运行的编码 Agent 上建议把模型调用也统一收口用同一套 Key 和端点管理 Claude、GPT 系列省得每个适配器里再写一遍鉴权逻辑。接入文档在 https://taotoken.net/doc 里面有完整的请求示例和错误码说明配合本文的summarize函数改一改就能用。最后留一个实操建议先把verify.ts跑通确认两个适配器的输出字段语义对齐再去写下游的摘要和索引。顺序反了的话格式问题会以摘要结果莫名其妙的形式暴露出来排查成本高得多。
