codeburn 接入 Quick Desktop：EMF 指标文件与会话数据库的本地 AI 用量追踪实战指南

【免费下载链接】codeburnFree, local tool to track AI coding token usage and cost across 37 tools and agents (Claude Code, Cursor, Codex, Gemini and more), by model, project, and task. npx codeburn项目地址https://gitcode.com/gh_mirrors/co/codeburn点击查看免费下载本指南以 docs/providers/quickdesk.md 为骨架深入讲解 codeburn 如何以 eager 方式读取 Amazon Quick Desktop 的本地使用数据从~/.quickwork的profiles.json多配置文件解析、AWS Embedded Metric FormatEMFJSONL 指标解析到sessions.db只读 SQLite 富化与会话估算以及缓存、去重与已知坑位。读完你将掌握该提供方的数据发现、存储格式、去重键规则与调试要点并能在自己的集成中复用同样的防御式解析思路。Quick Desktop 是 Amazon 推出的本地开发桌面工具其使用数据落在用户主目录的.quickwork存储中但没有对外发布稳定契约。codeburn 通过 src/providers/quickdesk.ts 将这个私有格式转化为统一的用量记录并作为eager始终加载提供方注册在 src/providers/index.ts 的核心提供方列表中见 docs/providers/README.md 的 Eager 索引表与 Claude、Cursor、Codex 等 37 个工具的追踪能力并列。本文从“读取哪里、如何解析、怎么缓存、怎样去重、有哪些坑”五个维度还原这一集成并结合源码与测试给出可验证的实现证据。数据源定位从~/.quickwork到多配置文件Quick Desktop 的本地使用数据默认存放在~/.quickwork。codeburn 提供方的读取逻辑由quickworkHome()决定src/providers/quickdesk.ts#L83-L85function quickworkHome(): string { return resolve(process.env[QUICKWORK_HOME] || join(homedir(), .quickwork)) }也就是说默认读取~/.quickwork但可以通过环境变量QUICKWORK_HOME覆盖存储根目录——这在测试中也被广泛使用测试在beforeEach中把QUICKWORK_HOME指向临时目录见 tests/providers/quickdesk.test.ts#L25-L30。profiles.json的多配置文件语义存储根目录下可选的profiles.json负责描述 Quick Desktop 的多个“配置文件”profile其结构为{ last_active: profile-alpha, entries: [ { id: profile-alpha, data_path: stores/alpha-data }, { id: profile-beta, data_path: custom-location/beta-data } ] }解析规则对应resolveProfileBases()src/providers/quickdesk.ts#L106-L136如下遍历entries[]每条取id与data_path二者缺一即跳过该条目相对路径以存储根目录为基准解析绝对路径原样使用isAbsolute(dataPath) ? resolve(dataPath) : resolve(root, dataPath)因此data_path可以指向.quickwork之外的外部目录——测试discovers an absolute data_path outside the store root专门覆盖了这一场景last_active不参与过滤仅作为展示字段存在重复的data_path会被去重seenPathsSet如果存储根目录本身还残留迁移前的旧版历史sessions/sessions.db则追加一个profile名为default的旧版根布局条目与 manifest 条目并行扫描测试emits sessions from active profiles and a coexisting migrated legacy root database验证了这一点若profiles.json缺失、不可读、内容损坏或没有可用条目则回退为旧版布局把存储根目录当作defaultprofile 扫描测试falls back to the legacy store root when profiles.json is absent覆盖。源码中catch分支明确注释“Missing, unreadable, or malformed profiles.json is the legacy root layout”。每个 profile 扫描两类文件对每个解析出的 profile 基路径discoverSources()src/providers/quickdesk.ts#L159-L183扫描profile_base/metrics/metrics-YYYY-MM-DD.jsonl按文件名正则^metrics-(\d{4})-(\d{2})-(\d{2})\.jsonl$匹配见 src/providers/quickdesk.ts#L11profile_base/sessions/sessions.db若存在。二者都作为独立的SessionSource上报project字段即 profile 的id。probeRoots()src/providers/quickdesk.ts#L540-L542报告同样的解析结果供codeburn doctor诊断使用。存储格式EMF 指标 JSONL 与只读 SQLite指标文件AWS Embedded Metric Format每个metrics-YYYY-MM-DD.jsonl文件按行存放 AWS Embedded Metric Format 的 JSON 对象一行一条记录。来自测试的真实形态tests/providers/quickdesk.test.ts#L109-L111{ Model: claude-sonnet-4-5, InputTokens: 12, OutputTokens: 6, CostUSD: 0.002 }带完整元数据与工具调用的行tests/providers/quickdesk.test.ts#L172-L185{ _aws: { Timestamp: 1783987200123 }, session_id: session-alpha, thread_id: thread-1, Model: claude-sonnet-4-5, InputTokens: 120, OutputTokens: 30, CostUSD: 0.0042 } { session_id: session-alpha, ToolName: read_file, ToolCallCount: 1 }解析判定规则usageRecord()src/providers/quickdesk.ts#L346-L350明确一条用量行必须同时具备Model、InputTokens、OutputTokenstoken 数须为非负有限数值否则不作为用量记录纯工具行只有ToolName不直接构成调用而是通过session_id关联到同文件内的用量行。时间戳处理metricsTimestamp()与fallbackTimestamp()src/providers/quickdesk.ts#L374-L393优先取_aws.Timestamp单位为 Unix 纪元毫秒毫秒级精度测试断言2026-07-14T00:00:00.123Z缺失时回退为文件名日期对应的 UTC 午夜零点例如metrics-2026-07-19.jsonl→2026-07-19T00:00:00.000Z日期本身不合法如 2 月 30 日则视为无时间戳并跳过该行。成本处理CostUSD存在且非负时原样保留并标记为实测成本costIsEstimated: false缺失时通过 codeburn 的模型定价引擎calculateCost(model, inputTokens, outputTokens, 0, 0, 0)计算并标记为估算src/providers/quickdesk.ts#L461-L473定价实现在 src/models.ts#L1208。测试parses EMF usage, linked tools, real cost, and malformed lines中无CostUSD的调用成本正是calculateCost(claude-sonnet-4-5, 40, 10, 0, 0, 0)的结果。健壮性损坏行被独立跳过——readMetricsRecords()对每行单独JSON.parse一行解析失败不影响后续行src/providers/quickdesk.ts#L323-L344。测试 fixture 中直接塞入{malformed json字符串验证这一点。会话数据库防御式 SQLite 富化profile_base/sessions/sessions.db通过 src/sqlite.ts 的openDatabase()以只读方式打开isSqliteAvailable()不可用或打开失败时静默降级。核心是“先探查再查询”的防御策略loadDatabaseSnapshot()src/providers/quickdesk.ts#L234-L321先查sqlite_master确认sessions与session_messages两张表是否存在tableNames()再用PRAGMA table_info(...)获取表列名tableColumns()selectColumn()对缺失列回退为NULL AS namesessions表缺少id列则整体放弃session_messages缺少session_id/role/content则只保留会话元数据、禁用估算deleted_at列存在与否决定能否识别已删除会话deletionKnown sessionColumns.has(deleted_at)仅在该列存在时才排除deleted_at非空的会话。从数据库中提取的信息用于两类目的富化指标行用量行命中某个会话 id 时把该会话的title、agent_mode、第一条用户消息firstUserMessage、以及从消息表聚合出的工具列表合并进对应调用估算缺失会话对未出现在任何指标文件中的非删除会话生成一条模型名为quickdesk-auto的估算调用非 assistant 角色内容计入输入字符、assistant 内容计入输出字符按“每 4 个字符 1 token”换算estimateTokensFromChars()使用Math.ceil(chars / 4)见 src/token-estimate.ts#L1-L5成本同样走calculateCost并标记为估算。消息表里的tool_names字段兼容三种形态toolNames()src/providers/quickdesk.ts#L201-L218JSON 字符串数组如[write_file]、JSON 对象数组取name/tool_name/toolName字段、旧版逗号分隔字符串。工具原始名再通过toolNameMap归一化为可读短名如read_file→Read、run_command→Bash、write_file→Edit见 src/providers/quickdesk.ts#L18-L32。测试enriches metrics and estimates only non-deleted sessions absent from all metrics完整验证了这一链路metered会话同时出现在指标与数据库中得到富化后的真实成本与工具fallback会话只存在于数据库得到quickdesk-auto估算调用输入 3 token / 输出 3 tokendeleted会话deleted_at非空即使指标文件中有对应行也被排除。需要强调的是磁盘上的 schema 是逆向工程得到的AWS 官方文档只描述了.quickwork根目录的存在并不发布profiles.json、指标 JSONL 或sessions.db的契约因此解析实现以“观察到的 schema 变体”为边界缺表缺列只禁用相应富化/回退功能指标数据始终可用。缓存与持久性eager 提供方的共享会话缓存Quick Desktop 属于eager始终加载提供方见 docs/providers/README.md 中 Eager 索引表以及 src/providers/index.ts#L198 中coreProviders数组并使用 codeburn 的共享会话缓存每个指标文件、每个 profile 的数据库都是独立的缓存源discoverSources()生成的每个SessionSource独立缓存QUICKWORK_HOME的值与 Quick Desktop 解析器版本共同参与缓存指纹环境变量或解析器变化会触发缓存失效避免旧记录被误当新数据提供方声明了durableSources: truesrc/providers/quickdesk.ts#L529Quick Desktop 可能清理自己的受管存储因此当某个之前发现过的源消失时其已缓存的记录会被保留而不是被当作“孤儿”清理——这保证了历史报告在应用侧修剪数据后依然完整。去重键三类稳定键位去重键在多次运行之间必须稳定codeburn 依赖它做跨源、跨运行的去重实现见 src/providers/quickdesk.ts#L456-L458 与 src/providers/quickdesk.ts#L503-L505场景去重键格式带会话的指标调用quickdesk:session_id:timestamp:model:input:output无会话的指标调用quickdesk:profile:file:timestamp:model:input:output仅存在于数据库的估算会话quickdesk-est:session_id测试namespaces session-less metric keys by profile展示了无会话键的实际形态两个 profile 同一天、同模型、同 token 的行产生两个互不冲突的键quickdesk:first-profile:metrics-2026-07-19.jsonl:2026-07-19T00:00:00.000Z:claude-sonnet-4-5:20:5 quickdesk:second-profile:metrics-2026-07-19.jsonl:2026-07-19T00:00:00.000Z:claude-sonnet-4-5:20:5seenKeys集合在单个解析批次内共享跨源重复的键会被跳过。数据库估算的抑制是全局性的createDatabaseParser会先通过allMetricSessionIds()汇总所有 profile 指标文件中出现过的会话 id只要某个会话在任意指标文件里被计量过就不会再生成quickdesk-est估算——测试suppresses database estimates globally when profile metrics contain the migrated session id验证了这一点迁移后的会话在旧版根数据库与 profile 数据库中都存在但只产出一条真实成本调用、零估算调用。已知坑位与边界行为文档明确列出四类 quirk全部有源码佐证委托调用可能重复计量Quick Desktop 可以把任务委托给 Kiro 或 Claude Code。如果 Quick Desktop 的指标计量了与这些原生存储相同的一批委托调用同时启用所有提供方可能导致这些流量被双重计数。截至当前仓库尚无清洗过的真实存储能消解这一疑点。指标目录位置是逆向工程的profile_base/metrics并非 AWS 官方 schema 保证未来应用升级可能改变该目录位置。旧版 schema 无法识别删除sessions.deleted_at列存在时才排除已删除会话旧版无该列时指标行被保留因为删除状态无法确定src/providers/quickdesk.ts#L251。WAL 日志导致的短暂重叠sessions.db使用 WAL 日志模式主文件指纹可能因未 checkpoint 而滞后测试中建库即PRAGMA journal_mode WAL见 tests/providers/quickdesk.test.ts#L59。某次运行中被估算的会话在下次运行中可能已出现首批真实指标行——这种“估算真实短暂共存”会在数据库文件变化后自愈。调试与修复指引如果要在 codeburn 中修改 Quick Desktop 相关逻辑docs/providers/quickdesk.md 给出的清单也是 tests/providers/quickdesk.test.ts 的覆盖策略值得照做同时测试多配置文件 manifest 与旧版根布局两条路径——resolveProfileBases()的两条分支都要有 fixture保持指标解析与可选 SQLite 富化解耦——缺表缺列时指标数据依然可用测试keeps metrics when sessions.db has no session_messages table就是这条原则的回归保护为每个新观察到的 schema 变体补充畸形行与缺表覆盖——readMetricsRecords的逐行容错、tableNames/tableColumns的探查式查询就是为这类变体准备的。运行该提供方的测试可用仓库配置好的 vitest见根目录 vitest.config.ts例如npx vitest run tests/providers/quickdesk.test.ts注意其中依赖node:sqliteDatabaseSync的用例会在isSqliteAvailable()为假时整体跳过其余纯指标用例不受影响。延伸阅读提供方集成总览与索引docs/providers/README.md其中记录了 Quick Desktop 的存储类型EMF JSONL SQLite与源码/测试对应关系提供方抽象与调用结构src/providers/types.tsProvider、SessionSource、ParsedProviderCall与 src/providers/index.tseager/lazy 注册、发现隔离只读 SQLite 基础设施src/sqlite.ts架构总览docs/architecture.md新增提供方的模板docs/providers/NEW_PROVIDER.md。总而言之codeburn 对 Quick Desktop 的集成是“私有格式 防御式解析”的典型范例以profiles.json多配置文件与旧版根布局双路径发现数据源以 EMF JSONL 为用量主证据、SQLite 为可选富化与兜底估算配合稳定去重键、持久缓存和逐行容错在官方无契约的前提下实现了可重复、可审计的本地 AI 用量追踪。赞分享【免费下载链接】codeburnFree, local tool to track AI coding token usage and cost across 37 tools and agents (Claude Code, Cursor, Codex, Gemini and more), by model, project, and task. npx codeburn项目地址https://gitcode.com/gh_mirrors/co/codeburn点击查看免费下载相关推荐codeburn 源码级解析CodebuffManicodeCLI Agent 本地会话的用量与成本追踪实现codeburn 源码级解析CodebuffManicodeCLI Agent 本地会话的用量与成本追踪实现 本篇技术指南围绕 codeburn 开源仓库ccusage 接入 OpenClaw 数据源JSONL 与 SQLite 会话用量聚合实战指南ccusage 接入 OpenClaw 数据源JSONL 与 SQLite 会话用量聚合实战指南 本文是 ccusage 项目中 OpenClaw 数据源EAI 应用CLI开发工具ccusage Antigravity 数据源使用指南从本地 SQLite 会话库统计用量与成本ccusage Antigravity 数据源使用指南从本地 SQLite 会话库统计用量与成本 本文是 ccusage 中 Antigravity 数据源AI 应用CLI开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考