AgentView 存储规则全解SQLite 归档、DuckDB 镜像与多后端一致性设计【免费下载链接】agentsviewLocal-first session search, analytics, insights, and token use statistics for coding agents, supporting Claude Code, Codex, and more than 20 other agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agentsviewAgentView 是一个本地优先local-first的编码 Agent 会话搜索、分析与 Token 用量统计工具其存储层由 SQLite 归档、PostgreSQL/CockroachDB 远端后端与 DuckDB 派生镜像三部分组成。本文基于仓库中的 存储规则文档 逐节展开读完你可以掌握该项目的非破坏性 schema 迁移原则、Codex 增量导入状态机、archive_content内容策略的投影机制、DuckDB 镜像的重建约束以及各后端之间必须保持一致性的查询契约。总体原则SQLite 是唯一持久归档文档开篇就给出了一条铁律任何涉及 SQLite、PostgreSQL、CockroachDB、DuckDB、归档重同步或存储查询的改动都必须先阅读 存储规则。SQLite 是持久归档persistent archive。规则明确禁止通过删除、DROP、TRUNCATE或重建数据库文件来应对数据版本变化。允许的 schema 演进方式只有非破坏性迁移例如ALTER TABLE和UPDATE。当一次解析器parser变更确实需要全量重同步full resync时规定的工作流程是四步构建一个全新的数据库从源文件同步数据进去从旧数据库拷贝其中孤儿会话orphaned sessions即源文件已不存在但归档中仍有记录的会话原子地交换两个文件。核心目标是即使源文件已消失会话也必须保留在归档中——这与session_signal_state等状态表一起保证了增量导入的可恢复性。Codex 增量导入状态Codex 的本地导入依赖四张仅存在于 SQLite的表它们在 schema.sql 中定义表名职责parser_checkpoints保存断点续传元数据resume metadataparser_checkpoint_blobs保存游标cursor与哈希hash状态session_signal_state保存增量信号归约器signal reducertool_call_occurrence_agent_state保存每个 Agent 的结果坐标仅在某个调用收到迟到结果late result时惰性填充其他 Provider 不维护 Codex 信号状态。几个值得注意的实现细节提交绑定全量写入时信号种子signal seed随内容一起提交并在 SQLite 内部绑定到已存储的 transcript revision。种子失败会回滚内容不存在提交后再读 revision的窗口。全量重同步一次性替换归档会推迟工具调用 ID 与结果元数据的索引创建直到批量装载bulk load完成之后索引重建必须成功替换归档才能安装。原始内容摘要Codex 结果事件保留一份 raw-content digest并标记该 raw 事件是否参与 summary。这些本地字段用于区分经清洗后变得相同的事件并保留空白字符与 blocked-result 规则。旧会话若缺少这些元数据会在应用迟到结果前先从源文件重新解析。首次重写可能推进 transcript revision之后相同的解析结果保持 no-op。这些字段被排除在导出export与镜像指纹mirror fingerprint之外。大体积 Codex 导入的 scratch 数据库大型 Codex 导入会引入一个一次性的 scratch SQLite 数据库来承载结果 payload。发布publication阶段把它挂到归档写入器上将内容、checkpoint、已启用的派生状态三者一起提交。取消操作会中止发布清理阶段使用的 context 能在取消之后存活确保 detach 完成。文档特别强调scratch 存储不是归档、也不是镜像导入完成后即删除。工具结果图片保留db strip --images工具结果图片保留使用统一的config.ToolResultImages策略作用于可写 SQLite 句柄零值zero value 保留内容keep modeDrop 模式在派生长度、展示比较与持久化之前把合法的data:image/...;base64内联块投影为agentsview_image占位符。关键保证包括投影前先抓取原始事件 digest保证不同的 Provider 事件保持可区分重放的迟到结果仍为 no-op投影保留普通文本、元数据、块顺序、不支持的形状以及未来的占位符合并摘要按 JSON 边界投影有标签与匿名的 section数组内部的空行不会把它们切断当旧事件早于 drop 模式时迟到结果写入也会对重建后的 summary 做同样投影。db strip --images命令对已有数据做投影其行为约束很细逐会话处理每个会话一个事务直接更新tool_calls.result_content与tool_result_events.content重算存储长度且不改动任何事件坐标与元数据列每个被修改的会话在同一事务内对其投影后的 transcript 做一次完整 secret 扫描保留发现项的当前偏移量与规则版本被修改的会话走完整的发布序列transcript revision、Recall、信号、artifact 导出、用量通知、提交后吊销未被修改的会话则完全不触发这些发布全量重同步仅对已废弃/孤儿会话拷贝返回的 ID 应用同一投影且发生在替换归档发布之前——刚解析出的会话本身已带投影该命令分别统计原始tool_calls.result_content与tool_result_events.content字节数和解码后的图片字节数文件大小的回收由db compact单独报告。此外仅 transcript 写入与仅用量写入都会省略 parser checkpoint——因为可恢复的哈希状态里可能含原始 transcript 尾部字节。它们保留分阶段解析但发布的是投影后的消息与工具元数据不带分阶段输出。Archive Content Policy归档内容策略archive_content对应internal/config.ArchiveContent决定 SQLite 归档保存多少内容。该策略在 archive_content.go 中实现为三档有序策略full → transcripts → usage*db.DB句柄是唯一权威各种Open变体和sync.NewEngine只能收紧策略不能放宽从源码结构看SetArchiveContent用原子 CAS 保证策略在句柄生命周期内单调收紧archive_content.go 的注释明确写道一旦进程承诺不持久化某些内容后续调用者不能悄悄弱化该承诺所有写路径在行落库前都要通过internal/db/archive_content.go中的投影函数。文档给出的工程约束任何新的会话、消息、工具调用、信号或发现项finding写入都必须走现有投影 helper而不是在调用点内联检查策略重同步用ATTACH拷贝归档行会绕过写路径——因此applyArchiveContentToCopiedSessionsTx用 SQL 镜像了 Go 侧的投影逻辑两侧必须同步修改拷贝的工具渲染rendering优先使用精确重建文本当存储的输入无法重建出可识别的工具渲染时transcript 投影保留前面的散文与工具标签但丢弃剩余的消息尾部因为其参数边界未知仅用量行usage-only rows保留归一化的 context/output token 值及存在性标记外加token_usage列模型混合model-mix统计依赖这些列PostgreSQL 推送会按源归档策略逐会话记录prompt_evidence_discarded自动化审计仅在该标记能解释提示词证据缺失时保留存储的判定verdict全内容行始终有资格被纠正。仅用量模式usage-only mode的副作用禁用向量构建、服务与导出。打开可写归档时会在向量写锁下清空本地消息索引与 recall 索引。PostgreSQL 推送会清除己方会话包括本地已删除的会话所有代次的已索引内容清理流程先在 PostgreSQL 中找候选再在会话锁下复核所有权后才删除。派生值信号、secret 发现项必须从投影后的消息计算保证日后从存储行重新计算能复现同样结果。db migrate --images把内联图片搬进资产存储db migrate --images将保留的内联 payload 从 SQLite 移出写入资产存储每个解码后的 payload 写入{dataDir}/assets/sha256hexext且在会话事务的任何 UPDATE 提交之前完成事务失败时已完成的对象留在磁盘上成为无引用状态重试时会被复用没有对无引用资产的自动清理已有对象只有在字节数与 SHA-256 摘要都匹配时才复用对象缺失或损坏时只要源字节还在就会被替换内联块被替换为agentsview_image占位符image_ref字段存asset://sha256hexexttext字段承载 Markdown 图片Image: type, n bytes迁移块的判别字段是image_ref之后切换到 keep 模式的重新解析或全量重同步可以从 Provider 源文件恢复内联字节只有四种被动媒体类型被迁移image/png、image/jpeg、image/webp、image/gifSVG 保持内联如果分离出独立服务主机serving host需要把对应的{dataDir}/assets目录连同数据库内容一起拷贝过去除上述差异外命令与db strip --images遵循相同的事务、revision 与发布序列。备份时必须把{dataDir}/assets与归档一起备份。后端一致性Backend Parity文档要求在可行的范围内SQLite 与 PostgreSQL/CockroachDB 的可观察行为和查询形状保持一致——查询、索引、聚合、过滤与排序都应匹配除非有文档记录的约束要求差异。规则还强调不要只在某一个主后端上修正确性或性能除非用户明确限定任务范围实现必须差异时要解释原因并保证行为一致DuckDB 是派生镜像不属于该一致性规则的范围报表中的 project-label key 不是仓库身份标识报表目录reporting catalog必须从同一个读事务解析所有贡献会话忽略未知观察值的聚合目录无法提供这种证据。身份修正identity-only corrections留在报表 digest 中线上契约参见 报表导出文档 的项目身份证据一节。用量缓存的架构分叉这是文档中最复杂的一节。SQLite 的聚合用量 API 从一个一次性的兄弟数据库disposable sibling database读取带时区的每日滚动daily rollups。同一数据库中的归一化、未计价事实normalized, unpriced facts是精确的构建底料而不是热聚合读路径。逐会话明细仍走实时行路径PostgreSQL 则继续对实时的归一化归档行做聚合。实时路径永远不会作为 SQLite 聚合读失败或过期时的回退。两个实现在同一行为契约下共同维护每日用量、top 会话、计费会话数、宽松匹配计数、逐会话用量必须可观察地相等。文档指出pgtest的 complete-result parity 夹具fixture是验收边界PostgreSQL 原生优化另有跟踪 issue。缓存文件名与代际文件名由格式版本format version与归档database_id派生。格式或 database-ID 变化会选出新一代缓存但不会迁移或重写归档。事实facts只含消息与用量事件派生数据聚合指纹额外烤入会话的agent与started_at因为它们影响去重与按天分桶。其余会话元数据与过滤条件来自归档读快照。文档警告不要隐式扩大或收窄这条实时/烤入边界。格式版本即提取器兼容版本只要事实提取、priceUsageFact、web-search 费用、去重、滚动语义或查询时模型规范化有任何变化就必须提升usageCacheFormatVersion当前值见 usage_cache_schema.go当前为 12。目录与用户定价变化由定价内容摘要单独覆盖不要新增只写型的提取器版本元数据键。去重分组的两级结构每日行finalized tier去重组在滚动构建时逐组分类。只有当组的解析结果可证明不随查询窗口或实时过滤条件变化时才固化成每日行——所有成员共享同一源会话与同一本地日期通用source:/usage:组还须共享同一模型与 headless 状态无成员同时挂接快照去重与通用去重无成员携带 Copilot 权威成本组的身份不出现在任何缓存的其他会话中对 usage key 还包括不出现在 Cursor 事实存储中。时区例外层exception tier其余不可约的组进入该层在读取时解析窄行保留窗口范围去重语义。Cursor 事实完全留在例外层。由于查询窗口是整天本地日单日期组整体位于窗口内或窗口外。跨会话身份检查是保守的由usage_facts上专用的身份索引提供而非成员表。任何填充fill、Cursor 批量或删除一旦改变了某会话或 Cursor 存储贡献的去重身份集合必须在同一个缓存事务中删除所有持有被改变身份的其他会话的时区滚动安装install滚动安装在其事务内重新验证——若某已固化身份获得了组外成员则针对新提交的事实重新分类而不是让调用者失败。一条已固化的每日行绝不能在获得兄弟后继续存活。缓存文件的可识别性与租约只有当 SQLiteapplication_id与usage_cache_metadata.cache_kind同时匹配时缓存文件才被视为可识别仅凭文件名匹配绝不允许删除或替换。租约感知代次对所有打开的 SQLite 池持有跨进程共享租约退役retirement需要独占租约外加对精确文件名做的 application-ID、cache-kind、协议版本、格式版本、源 database-ID 五重检查。退役后要保留租约文件防止竞争中的打开者锁住替换后的 inode。保留协议之前的代次旧二进制可能持有无租约的闲置句柄也保留比当前格式新的代次降级二进制不应迫使新版重建。持久缓存不可用或当前代次不兼容时改用进程自有的临时文件走相同 schema 与查询路径并警告重启后缓存会重建。用量读取的精确性一次冷聚合请求先填充事实、构建所需时区滚动、再在单个钉住的缓存事务中读取。须验证每个候选会话的事实指纹、精确烤入元数据、规范化定价摘要、解析后的费率哈希与 Cursor 高水位high-water mark。结果不新于读操作开始时捕获的归档快照但对填充期间事实被重新回填的会话可以更新填充期间确认已删除的会话从请求中剔除。cached_at仅为诊断字段。分层隔离避免活归档否决读填充在单个归档读事务内读取一个会话的事实与其源版本并一起安装、报告实际读到的版本可能比调用者要求的更新。滚动聚合之后只从用量缓存读已提交事实绝不碰归档所以构建中途落地的追加不会使其中止。安装install在其构建所依据的事实版本与缓存现持有版本不同时过期且只有这些安装会被重建。构建期间写入的会话由其自身的变更通知重新填充出现在下一次聚合中——数秒级的陈旧是预期且有意的设计。文档明确警告不要重新引入对整个快照与归档的再检查——对逐会话变化的源校验快照会使请求活锁livelock。时区滚动身份包含解析后的时区名称与其规则指纹两者。缓存代次退役会立即取消分离工作但会保持不可变的协调器指针与缓存数据库存活直到活动查询、回填、填充与滚动租约全部排空。sync_marker是指纹分量不是单调版本号其触发器重算可变时间戳字段的最大值因此可能变小。填充必须在与所安装事实相同的事务中读取完整源指纹。不要用指纹比较排序也不要因为缓存指纹看起来更新就跳过回填。Activity 报告索引活动会话选择即使在会话ended_at早于报告时也要检查终端工具执行事件。要求保持部分索引idx_tool_result_events_terminal在(session_id, timestamp)上在 SQLite 与 PostgreSQL 间对齐。它包含时间戳非空的 completed 与 errored 执行使查询可以跳过无关的结果 payload、直接定位到报告下界。下一次可写的 SQLite 打开或 PostgreSQL schema 装配会为既有归档建一次索引PostgreSQL 推送在走 schema-current 快路径前必须先检测索引缺失建索引会扫描既有工具结果可能拖慢首次启动但不需要会话重同步。用量归档索引用量缓存通过idx_messages_usage_timestamp与idx_messages_activity_timestamp发现有界窗口候选再通过索引-only 的idx_messages_usage_session_covering扫描逐会话提取。注意分工全局活动索引用于用量缓存的候选发现而不是 Activity 报告——后者继续避免全局时间戳扫描。除这个带token_usage的单会话键覆盖索引外这些索引应保持窄。改动任何索引的列列表会在下一次可写打开时重建受影响的归档索引且发生在 HTTP ready 之前必须记录启动正在等待迁移的日志。只读打开要求当前索引齐备因此可能拒绝尚未被匹配的可写版本打开过的归档。文档要求把这当作可执行文件/归档版本偏斜处理而不是只读命令修改归档的理由。全量重同步在批量装载期间于临时库中删除这些索引FTS 权衡一次加载后构建而非逐行维护 B-tree并在交换前必须重建重建失败会中止交换因为只读打开要求索引存在。transcript 用量身份与工具结果摘要transcript 用量身份token 用量、Claude 消息/请求身份与源 UUID 都参与 transcript revision 相等性判断。因此流式消息的终结可能推进transcript_revision与local_modified_at、使 secret 扫描新鲜度失效、将会话标记为已更新用于读进度/UI、并触发常规的 artifact/recall/PostgreSQL/DuckDB 刷新队列。全量重同步的对账必须比较同样字段让增量与重同步路径一致。no-op 消息替换保留既有 secret 发现项transcript 内容变化则清空它们以待新扫描。工具结果摘要tool_calls.result_content是同步时从该调用的tool_result_events行派生的展示摘要。当调用恰有一个事件且摘要等于该事件内容时摘要不存储——列为空而result_content_length仍记录摘要大小。这对空列 非零长度就是信号告诉读取者从单个事件取文本。多事件摘要、与事件不同的单事件摘要、无事件的调用以及 blocked 类别则原样存储解析器的产出。要求工具调用必须经消息加载器读取事件挂上后回填摘要直接 select 该列的查询必须应用同样的回退PostgreSQL 与 DuckDB 应用相同的写规则使工具调用指纹与 SQLite 匹配。手工读取归档或镜像的人看到空列时必须 join 事件表才能恢复文本。DuckDB 镜像规则DuckDB 被定义为 SQLite 的可丢弃只读镜像disposable read mirror绝不是记录系统system of record——删除镜像不能丢失任何东西。文档给出的六条硬性规则禁止就地镜像迁移in-place mirror migration。schema 或源数据版本变化必须提升internal/duckdb.SchemaVersion、重建新文件、验证后原子交换。不得添加ALTER迁移、版本桥接读取或旧镜像兼容垫片。该版本常量与探测逻辑见 probe.go版本不一致会直接报schema version %d vs %d。所有 DuckDB 推送游标与版本存于镜像自身的sync_metadata绝不把 DuckDB 同步状态存进 SQLite。增量更新以整会话替换为单位用逐会话指纹把关不得添加按表、按列或 diff 式更新。Quack 保持只读duckdb push只写本地镜像从不写远端 DuckDB 服务。替换文件前必须先确认它是 agentsview 的 DuckDB 镜像对未知文件失败关闭fail closed。运行 PostgreSQL 集成测试文档末尾给出后端测试的操作规程PostgreSQL 集成测试只能针对专用测试数据库运行因为测试会创建并删除agentsviewschema使用 Makefile 中的目标管理测试容器make test-postgres启动容器并运行套件且容器会保持运行如果容器是你启动的用完后执行make postgres-down停止它。针对已存在的专用实例运行命令为TEST_PG_URLpostgres://user:passhost:5432/dbname?sslmodedisable \ CGO_ENABLED1 go test -tags fts5,pgtest ./internal/postgres/... -v小结约束速查约束规则SQLite 归档只允许非破坏性迁移resync 走建库→同步→拷贝孤儿→原子交换Codex 状态表四张 SQLite 专用表scratch 库发布后删除不是镜像内容策略只能收紧不能放宽写路径一律过投影ATTACH拷贝需 SQL 侧镜像投影图片处理db strip --images投影占位符db migrate --images搬运资产备份时带上assets目录用量缓存事实层/滚动层/例外层分离身份索引保证去重读路径永不回退实时行索引变更下次可写打开时重建只读打开可拒绝偏斜归档DuckDB可丢弃镜像整会话替换版本升级重建原子交换fail closed后端一致性行为与查询形状跨 SQLite/PG 对齐DuckDB 除外这套规则的共同底色是归档是不可变承诺镜像是可丢弃副本跨后端行为是可测试的契约。理解并遵守这些边界是改动 AgentView 存储层代码如 internal/db、internal/duckdb、internal/postgres的前提。【免费下载链接】agentsviewLocal-first session search, analytics, insights, and token use statistics for coding agents, supporting Claude Code, Codex, and more than 20 other agents.项目地址: https://gitcode.com/GitHub_Trending/ag/agentsview创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
