CURRENT SOURCE · v1.4
先证明 Library 健康，再相信派生结果。
Library Health 检查写入状态、索引新鲜度和会话身份冲突；Diagnostics 把可以安全自动处理的重复项与必须人工判断的问题分开。
本地只读检测安全隔离源码快照能力
版本边界
本页记录当前 v1.4 源码中的诊断能力。若你的设置里没有 Diagnostics，已安装版本尚未包含它，请使用 FAQ 与故障排查；不要据此判断 Library 已通过检查。
健康状态
| 状态 | 意味着什么 | 动作 |
|---|---|---|
| Healthy | 当前没有阻断写入或已知结构问题 | 继续使用，必要时查看 freshness |
| writer-blocked | 写入器被锁、冲突或环境阻断 | 查看锁与进程证据，不要强行删锁 |
| read-only | Library 只能读取，无法安全更新 | 检查权限、同步状态和存储可用性 |
| corrupt | 检测到结构或内容一致性问题 | 停止自动写入，先备份并查看诊断详情 |
身份冲突如何处理
诊断在本地用内容哈希和元数据比较疑似重复会话。只有被证明是安全重复的副本才允许进入隔离区；隔离不是删除，可用于复核和恢复。
- 唯一内容不会被自动移动。
- 不确定的冲突保持原位并要求人工判断。
- 隔离操作应保留来源、原因和恢复线索。
- 同步盘或 File Provider 上的文件不能被当成可随意删除的缓存。
新鲜度与自动恢复
Health 会区分扫描、派生 transcript、索引和来源记录是否落后。后台重试只处理明确安全且幂等的工作；连续失败应显示状态，而不是无限静默重试。
CLI 检查
| 命令 | 用途 |
|---|---|
swob doctor locks [--json] |
只读检查 Library 锁与写入阻断证据 |
swob doctor library [--json] |
检查 Library 结构、身份与派生状态 |
swob transcript status <id-or-prefix> [--json] |
查看单条会话的 transcript 状态 |
swob transcript rebuild <id-or-prefix> [--dry-run] |
重建单条派生 transcript；先 dry-run |
不要用这些“修复”
- 不要在没有诊断证据时手动删除锁文件。
- 不要直接编辑原始 JSONL、transcript 或来源数据库来消除冲突。
- 不要把同步服务的占位文件当成已经丢失或可删除的文件。
- 不要在没有独立备份时清空 Library 重新扫描。