noname-shuying/diagnostics/README.md

# 术樱包自动诊断日志

扩展加载后自动记录本扩展的关键业务步骤，发生错误时自动生成独立报告。
无需开启控制台或手动开始录制；不上传任何数据。

## 文件位置

PC 和安卓客户端均写入游戏目录下的 `extension/术樱包/logs/`。

- `runtime-*.jsonl`：按行保存时间、模块、步骤、关联 ID 和上下文。
- `report-*.json`：错误报告，包含首次/最近异常、错误栈、cause、内部异常、
  运行版本、错误前操作、当前结算阶段和存档状态。

同一异常在存档层、结算层等多个入口被观察时，共用报告编号并更新修订号；
occurrences 表示被捕获的次数，不表示奖励发放次数。最近报告不会因普通日志
轮转被删除。保存回执绑定对应修订和真实通道，旧版本写入成功不会误标新版本。

扩展设置中的“诊断日志位置”显示实际位置和最近报告保存状态。
只需要保留相应报告和附近的 runtime 文件；如何发送由用户自行处理。

## 采集范围

- 主动记录术樱包加载、更新、梦三战斗、结算、存档、手牌、地图及菜单错误。
- 全局错误仅接收来源文件或异常栈属于本扩展的情况，包含编码后的中文路径。
- 不因为当前开启梦三就收集所有错误，也不根据错误消息包含“术樱包”归因。
- 原引擎错误处理仍会执行；不替换引擎事件、Promise 或 console 的原型。

## 存档诊断

报告分别记录 storageStatus、memoryPublished 和 commitReceipt：

- storageStatus=committed 表示存档事务完成，或 localStorage 写入已返回。
- memoryPublished=true 表示运行内存已发布成功存档。
- commitReceipt=true 表示结算协调器收到了提交成功结果。

资源清理、技能释放或地图展示随后失败时，不能据此判断存档失败。
重试沿用现有去重和奖励提交规则，日志不参与存档事务，也不触发自动重试。

## 容量与兼容

默认每秒批量保存普通日志；错误报告立即排入写入队列。运行日志按约
256 KiB 分段；内存保留最近约 512 KiB / 400 条记录。日志目录自动清理
系统自己生成的旧文件，保留总量约 5 MiB、最多 64 个文件。报告包含截断和
丢弃计数；“完整诊断”指受限的错误链与现场记录，不是无限保留整个游戏过程。

待写队列默认最多 12 项、合计 2 MiB，优先保存错误报告；另有最多一项正在写入。
错误报告复用已脱敏的记录文本，按字节预算一次裁剪，保留首次和最近异常。

PC 使用异步文件操作，安卓使用 Cordova 目录和 FileWriter 回调，写入前截断旧
内容，使用 UTF-8 Blob。单次保存操作设置 5 秒观察超时；超时后停止使用该
文件通道，避免迟到写入与后续写入重叠。写入异常不会中断游戏业务。

原生文件不可用时，降级到独立的 `shuying-diagnostics` IndexedDB；它不与
游戏存档共用数据库。若两种持久化方式都不可用，仅保留本次运行的内存
记录，菜单会明确显示未持久化，不能宣称文件已生成。

切入后台或页面隐藏时尝试保存缓冲；被系统强制杀死或断电时，最后尚未完成的
异步写入可能丢失。结算内部等待超过 15 秒会记录观察日志，选择奖励、地图节点
和剧情等待不会被当作超时错误；观察器不会结束业务事件。

字段过滤会隐藏凭据字段、常见 URL 凭据参数和 Bearer 内容。报告不会复制完整
玩家对象、DOM、引擎状态或整个存档。日志文件不进入发布清单和 Git。