[建议 / Feature] 本地用量数据 db.sqlite 缺稳定性承诺与变更文档，第三方集成随版本更新静默失效

提交前确认 · Pre-submission checklist

• 我已搜索过现有 issue，确认这不是重复提议 / I searched existing issues and confirmed this isn't a duplicate.
• 我已阅读 CONTRIBUTING.md / I've read CONTRIBUTING.md.

问题类别 · Category

其他 / 不确定 · Other / Not sure

涉及的 Agent 框架 · Agent framework

ZCode Agent（自研）

使用场景 · Use case

我是 ZCode 重度用户（日均 4-8 小时），同时是 WakaTime 长期用户。因为 ZCode 暂无官方 WakaTime 集成，我基于 wakatime-cli 内置的 ZCode 解析器（读取 ~/.zcode/cli/db/db.sqlite）+ 自建 hook 插件实现了编码时长与 AI 用量统计（已开源：https://github.com/COSMICAL-CONTAINER/zcode-wakatime ）。

过程中发现：db.sqlite 已经是事实上的第三方集成数据源，但没有稳定性承诺，也没有变更文档，生态工具随时可能随版本更新静默失效。

现状与证据：

• db.sqlite 记录了高质量的逐请求用量数据（model_usage 表 25,000+ 行：模型、token、缓存命中、耗时、是否子代理调用等字段齐全），足以支撑生态级统计工具；
• 但表结构无文档、无变更日志。一个近期实例：WakaTime 侧的 ZCode AI 统计自 2026-09-03 起静默丢失。排查中发现本地 session 表的 summary_additions / summary_deletions / summary_diffs 等字段在当前库全部为空（跨 2026-06-14 至 09-06 共 319 个会话）——既无文档说明这些字段的预期行为，也无从判断是「从未回填」还是「某版本停止回填」。最终定位是 wakatime-cli 侧的查询行数上限所致（wakatime/wakatime-cli#1560），但整个排查过程恰恰说明：第三方在无文档的内部结构上做集成，连「谁变了」都难以判断。

建议方案 · Proposal

三选一即可，可组合：

1. 对 db.sqlite 中第三方可读的表/字段给出向后兼容承诺，破坏性变更前在 Release Notes 中公告；
2. 或提供官方用量导出接口（CLI 子命令或本地 API），把「导出自己的用量数据」变成受支持的能力；
3. 最低成本方案：在文档注明「db.sqlite 为内部结构，不保证兼容」，让生态开发者有明确预期，避免按稳定接口设计。

预期价值 · Expected value

• 用户可以安全地把本地编码数据接入 WakaTime 等已有统计面板，不被版本更新打断；
• 生态工具开发者（看板、周报、成本分析）敢于基于本地数据构建，反哺 ZCode 生态活跃度。

你认为的优先级 · Your perceived priority

中 · Medium

你使用的 ZCode 版本 / 环境 · ZCode version / environment

Windows 11 x64（10.0.26200）、ZCode Desktop 3.11.2、GLM Coding Plan（BigModel 通道）

补充材料 · Additional context

• 站内以 wakatime、sqlite、用量 导出 等关键词搜索，未发现重复提议；
• 需要的话可补充：回归前后的 sqlite 查询对比、日志片段、最小复现查询语句。

Start by inspecting ~/.zcode/cli/db/db.sqlite, especially the model_usage and session tables, and review how schema changes are communicated in release notes. Determine which compatibility or export contract can be supported; done means the chosen policy or interface is documented, including how future breaking changes will be announced.