测试与验收要求
本文保留验收条件，进度以 Plan.md 和 最新验收 为准。 适配器版本、价格及来源交换的专项验证结果见 验证目录。 已实现功能不能代替实际验收，GUI、原生平台及真实来源缺口仍独立登记。 每项需要记录对应版本、数据集、命令、退出码和实际结果，不能仅勾选编号。
测试层级
- 纯函数单元测试：字段映射、数学、时间、身份及生命周期，使用独立人工期望。
- 适配器格式测试：固定版本脱敏测试数据，经实际读取→解析→标准化→查询完整流程。
- 本地集成测试：真实临时 SQLite、文件增量/重写、WAL、事务中断和迁移，不只 mock 数据库。
- 桌面验收：真实 Tauri IPC、WebView、配置和刷新；组件测试不能代替原生桌面验收。
- 已授权真实来源核对：与 Agent 自身本机统计/本机会话导出比较，记录差额与覆盖区别。
- 性能及发行：release 制品、全进程资源、真实安装/升级/卸载/恢复。
从根 package.json 选择实际命令：verify 执行静态及单元/格式检查，
test:browser 使用模拟 IPC；test:headless 使用真实可执行文件和 SQLite，
test:desktop 使用 Windows WebView2 的真实 IPC。后两者须先构建并隔离来源环境。
系统任务 API 往返另以显式测试执行，不能据此声称 OS 已启动应用。
无需生成模型请求即可完成前四层的大部分验证。
验收用例
| ID | 场景 | 必须观察的结果 |
|---|---|---|
| V01 | 各 provider 的缓存包含关系、reasoning 子集、cache TTL 子集 | 人工计算等式正确；无重复 token；缺失、零、异常负值、溢出可区分 |
| V02 | 两次合法请求恰好拥有相同 token/模型/时间；同请求重复 final | 前者计两次，后者计一次；更正更新旧贡献，顺序乱序不静默覆盖 |
| V03 | 成功、失败、取消、transport retry、无 usage、用户/工具消息、累计值 | 调用/尝试/消息分别统计，未知 token 不补零，无法确认调用时不产生 request 数 |
| V04 | 跨午夜、闰日、ISO 跨年周、周日起始、DST 23/25 小时 | 半开区间、周所属年和本地日期正确；重复小时可分辨 |
| V05 | 模型切换、同名不同 provider、unknown、别名变更 | 不从未来设置推历史模型；unknown 进入总计；别名不篡改原始记录 |
| V06 | 日→周/月、加权比例、distinct 会话、部分周期、分位数 | 不平均百分比/P95，不叠加每日 distinct；样本范围和缺口可见 |
| V07 | JSONL 半行、跨块 UTF-8、超长行、BOM、坏行、新目录、文件轮转/同长替换 | 不丢完整事件；半行不前移游标；变更检测不限于长度；错误无正文泄露 |
| V08 | file/OTLP 同数据重传，累计 metric 重置，token histogram 双类型，采样 | 重复读取不增加贡献，正确区分 sum/count；跨日未知区间不摊分；采样总计标记不完整 |
| V09 | 在读后/事件写后/游标写后/聚合前/commit 后各点终止进程 | 重启重放结果相同；没有只提交游标丢数据或只提交事件翻倍 |
| V10 | 父子会话、fork 继承、宿主镜像、两个源库重复、辅助调用 | 覆盖集合可解释；有明确关联依据才合并；无关联时主来源选择避免双计 |
| V11 | 真实 SQLite 并发写入、busy、WAL 未 checkpoint、只读权限、schema 变化 | 一致读取；不修改源库及源 journal；无法安全读取时保留旧结果 |
| V12 | 今日刷新、新增/更正昨天数据、双击刷新、一个源失败、休眠恢复 | 真正触发采集；日周月更新同一修订；失败源有状态，其他源继续，无样例回退 |
| V13 | 改时区/周起始、明细已清理、项目采集开关、只隐藏列 | 预览可重建范围；旧汇总不虚构新维度；展示设置与数据删除分离 |
| V14 | 缩短/延长保留、有限/无限切换、清理取消、日期边界、再次全扫 | 恰好保留指定本地日；过期数据不复活，源日志不变；封存日不重复累加 |
| V15 | 清理后磁盘空间、长读者阻塞 checkpoint、磁盘满、备份过期 | 统计主库/WAL/备份；有界退避和提示；备份不绕过最长保留，无无声数据丢失 |
| V16 | 旧库重复导入、范围重叠、更正、取消、迁移失败、旧程序开新 schema | 重复导入不新增贡献，失败可回滚；legacy 标签保留；迁移失败可恢复；旧程序拒绝写入 |
| V17 | 已验证版本、未知/缺失版本但结构兼容、新增可选字段、结构/语义破坏及部分可用 | 已知版本按映射解析；未知版本先尝试该 Agent 最新内置解析器，通过校验的数据可统计且带兼容标记；不兼容有诊断，失败不伪装“成功 0 条” |
| V18 | 表格与图表筛选一致、键盘/缩放/深浅色、无数据/部分数据、用量提醒/费用 | 图表数值与查询相同；单位明确；币种和费用类别不混加；提醒不因重启重发 |
| V19 | 真实安装、运行时缺失、离线、应用重启、后台/托盘关闭 | 核心功能无网络可用；缺 WebView 提示清晰；无隐藏常驻进程；设置正确恢复 |
| V20 | 100 万/1,000 万事件、366 日/多模型/多源、少数超大会话 | 按资源要求核对 GUI 空闲 10 分钟均值/峰值及百万首次导入峰值；全进程、headless、working set 分别报告；吞吐、查询分位数、数据库/WAL 大小记录，无全文件无界载入 |
| V21 | release 包体、启动、刷新、空闲 CPU、卸载/升级 | 达到 architecture.md 的目标或记录未达原因；包含 WebView 子进程与运行时说明 |
| V22 | OTLP 认证/限流/压缩炸弹、CSV 注入、路径逃逸、恶意源字符串、本地导入失败 | 不执行外部文字、不持久化正文/凭据、不访问未授权范围；本地导入中断可恢复 |
| V23 | 全局/逐源间隔与定点、禁用/恢复、手动/监听/定时重叠、时钟回拨、DST、休眠 | 同源不并发，合并待处理触发；禁用后无自动读取；错过时点每源只补扫一次，下次执行正确 |
| V24 | Windows 系统任务注册失败/禁用失败、普通用户、GUI/headless 竞争、退出/注销/升级/卸载 | 实际生效状态可见；无密码或提权需求；单写者，无 WebView/Agent 启动；关闭配置后残留触发也不采集，只清理自有任务 |
| V25 | 本机 WSL/容器、远端同步文件、保存为文件的云账单、账号报表、loopback 转发/伪造 host | 本机实例显式授权且去重；远端/未知来源排除并给原因；无远端用量/API 出站请求，不隐式启动环境 |
| V26 | GitHub Windows/macOS/Linux 矩阵、锁文件、release 制品、测试插桩和权限 | 三 OS 实际构建测试并保留分项状态；Windows 11 实机另验；制品无测试监听器/个人数据，不自动发版 |
| V27 | 本地 WSL 2 Linux 构建、工作副本、缺依赖、AppImage、WSLg 有/无 | revision/未提交差异和环境可追溯；编译/测试/打包/GUI 分项；库不跨系统共用，不将 WSL 等同原生桌面通过 |
| V28 | 主机改名、同名不同主机、目录迁移、复制数据库、清理明细、旧库来源缺失、导出重入、同源修订/部分快照/来源冲突 | 稳定来源参与唯一约束与历史分区；导出保留原始来源，导入机不覆盖归属；重复导入不新增贡献，已接受修订替换旧贡献，互斥来源新增；旧混合汇总不虚构拆分，失败保留旧结果 |
| V29 | 价格渠道依据、模型别名/版本、缓存 TTL、推理包含关系、阶梯/档位/批处理、价格生效边界、多币种、缺价、离线/更新失败 | 价格出处与适用范围可复核；固定 token/单价样本有人工期望；未知不补零、部分计价有覆盖、确定精度舍入；历史估算可复现，无用量上传，不冒充订阅实付 |
| V30 | Agent 目录迁移、历史版本并存、新旧/未知版本混合目录、最新解析器回退、格式冲突、共用逻辑变更及旧游标恢复 | 每 Agent 独立目录，版本实现留在该目录内；已知分派与未知回退正确，兼容状态可追溯；既有已验证版本重构前后身份、用量及恢复结果一致，重复扫描不增长；历史回归保留 |
| V31 | 界面语言切换、缺失键回退、语言协商、数字/日期/单位本地化、导出格式分列 | 切换行为符合 F3 语言规则；缺失键回退默认语言且可诊断；统计口径不随语言改变；CSV 导出格式与界面格式分列说明 |
V28 的来源持久化、迁移和合并判定样本由 M1a 验收，实际导出由 M6 验收 （聚合包为来源注册 + 日/周期/小时层；明细包 另含完整事件和累计）； 聚合与明细导入均已实施，事务、修订、未知、完整日、封存及原生往返分别验收， 不开放跨设备采集。 V29 使用固定价格样本 P1–P6、人工期望 E1–E8、异常场景 A1–A10； 测试与在线失败回退结果见 费用引擎、 在线刷新。当前 API 参考与发生时 估算分别核对，后者须有明确供应商渠道；用量和费用提醒 已实施， 验收默认关闭、用户/周期隔离、精确金额、未知覆盖及重启去重。
V30：适配器目录与历史版本回归
M2 负责现有单文件迁移；M3–M5 及后续 F1 的新适配器沿用 目录约定。 按以下场景分别记录结果，目录存在或编译通过不能代替版本兼容验收：
- 检查每个 Agent 的独立目录、统一入口、版本分派和内部实现，产品特有映射不留在根级单文件。
- 用迁移前已验证版本的固定样本及已提交游标/解析上下文核对迁移后的身份、事件、汇总和增量结果； 移动实现不生成新来源、不重复计数，旧公开入口、examples 和测试仍可用。
- 对每个实际支持的发布版本验证正确分派；同一根目录的新旧历史文件分别进入匹配实现。 未知或缺失版本先进入该 Agent 对应输入类型的最新内置实现，不因未收录的版本号直接拒绝。
- 用未收录版本号但结构不变、版本缺失但 Agent 可识别、仅新增可选字段的样本验证默认回退成功； 经实际探测→扫描→入库→查询过程确认 token 与人工期望一致，并显示未验证兼容状态。 版本探测、扫描及能力声明使用同一策略，不允许仅在探测阶段放行。
- 分别注入必需字段类型错误、token 包含关系矛盾、无法识别的计量记录及格式匹配冲突； 可独立校验的部分数据保留并标注覆盖，依赖未知累计基线的计算停止；失败批次不推进游标或覆盖旧结果。 错误文件不影响独立的已知格式文件，不能仅跳过错误行后宣称完整成功或“成功 0 条”。
- 重启后兼容标记仍可查询，日汇总/封存和导出不丢失解析依据；同一数据重复扫描不增长。 更新解析器、来源变化或显式重扫可重新尝试，后续专用实现替换旧贡献而非再次追加。
- 新增版本后执行全部已支持历史版本的固定回归；共享组件改动覆盖全部实际使用者。 支持矩阵、样本说明和 parser_version 可追溯；不删除旧样本以掩盖新版本回归。
当前仅有一个已证实版本的 Agent 先验目录迁移与现有行为；尚未核验的历史版本保留待验证， 合成的版本分派测试只能证明分派逻辑，不能替代对该 Agent 真实格式样本的核验。
固定数学样本
下列数值进入单元与端到端测试数据，期望写死于测试数据说明，不调用实现自身生成期望。
| 输入 | 期望 |
|---|---|
| 未缓存输入 100，缓存读 800，缓存写 100，输出 100 | 总输入 1000，总 token 1100，缓存输入占比 80% |
| 总输入 1000（缓存读 800 已包含），输出 100（推理 40 已包含） | 总 token 1100，不再加缓存或推理；未缓存输入在可证明无缓存创建时为 200 |
| 甲输入 100/缓存 90，乙输入 900/缓存 90 | 合并比例 18%，不是 50%；甲 90%，乙 10% |
| 输入 100、输出未知 | 已知输入 100；输出及完整总量未知；不能产生完整总 token=100 |
| 同请求 usage 从 100 改成 80 | 当前值 80，调用数 1；不是 180 或取 MAX=100 |
| 两个稳定 ID 的请求 usage 都为 100 | 总量 200，调用数 2；内容相同不能去重 |
| DSH 同 attempt 流式 80→final 100，retry final 40 | 两个已确认尝试的 token 合计 140；具体 model_call 身份随适配器核验依据 |
| 累计 100→150→150，明确新进程 20 | 区间增量 50、0 与新进程 20；首次 100 保留原始区间，不硬塞进今天 |
| 跨两天同一个 session，各日都活动 | 周/月 DISTINCT session=1；活跃天数=2 |
| Hermes 两日累计行 token=1000、api_call_count=3，只有 first_seen/last_seen | 保存来源区间汇总；不产生三条 model_call，不把 1000 全放最后一天；重复扫描不增加 |
| Hermes 主模型累计 100，独立 task 辅助累计 20，sessions 主循环也是 100 | 已证明覆盖互斥时总量 120，不是 220；session 与模型表不双计，辅助任务不遗漏 |
另外覆盖接近 i64 上限、大于 JS 安全整数、毫秒/秒误判、夏令时重复小时和 null 字段传播。
适配器真实核对
实施阶段提取本机真实 Agent 数据验证已获用户允许，按 最小提取流程 执行。 M0 可先只读提取必要字段生成脱敏 fixture，解析器通过后再做真实来源的端到端比较。 F1 本轮已授权核查；无安装/本机文件或数据库的项移出活动计划，限制及未实施状态保留在矩阵。 本轮更多 DPI、完整读屏、宿主登录/注销及 OS 唤醒已取消，活动验收以 Plan.md 为准。
每个发布适配器至少固定一个实际版本；多版本支持必须各有 schema 样本。 来源样本包括单次调用、工具循环、模型切换、子 Agent、失败/取消、重启恢复和辅助请求。 不具备某个场景的产品标记缺口，不能用别的产品数据替代。
与 Agent 本机统计核对时固定时区、时间范围、本机实例、模型和统计单位。 差额先检查源端写入延迟、日志保留、隐藏辅助请求及源界面是否混入了跨设备数据。 token 相符不自动证明 request/cache 相符；每个字段独立验收。 已有本地历史核对优先，不为了验收自动发起付费调用或改为接入账号 API。
调度与平台补充验收
V23 的时钟/DST 用可控时钟，V24 使用实际 Windows 11 普通用户测试任务， 不能用 mock 注册成功证明系统任务可用。任务测试只操作本应用测试命名空间，结束复核无残留。 V25 合成明确的本机、跨设备和未知归属测试数据，出站审计覆盖运行/手动/定时/导入路径； 构建依赖下载与统计运行网络行为分开，不把 Agent 自身访问云端模型误判为采集器出站。 V26 至少有三平台原生构建、Rust/格式/SQLite/调度测试结果，GUI 自动化不足单列， Windows 安装、系统任务和资源目标仍需真实 Windows 11 验收。 2026-10-05 用户取消 macOS 桌面及特定硬件要求，Linux GUI/包生命周期接受独立 WSL/Debian Podman 的实际 GTK/WebKit/IPC 验收；宿主登录/注销、托盘/通知和其他 发行版仍分开记录，FUSE 不可挂载时不能以提取运行报 FUSE 通过。 V27 是可选本地补充；环境不可用记录未执行，不能删掉 Linux CI 或声称其已通过。
不作为通过依据
- 编译成功、schema 存在、目录被发现，不能证明用量正确。
- 原型 README、第三方统计工具的映射和搜索摘要，不能替代上游格式依据。
- 本地固定样本不证明所有发行版本、所有 IDE、真实服务或生产覆盖。
- 空壳 Tauri 的包体数字不能代替包含图表、数据库、采集和遥测后的成品。
- Markdown lint 通过只说明文档格式，不证明任意业务验收完成。