遇到问题，先找你看到的症状。

你遇到了什么？

macOS 阻止打开或提示安装包异常

当前公开 macOS v1.3.1 安装包使用 Developer ID 签名并完成公证。遇到阻止时，先核对是否从官网或 GitHub Release 下载、是否选择了正确芯片、是否仍在运行旧下载副本。

• 从“应用程序”目录启动，不要长期直接运行 DMG 或下载目录中的副本。
• 历史版本、本地自构建包和第三方镜像不继承当前公开包的签名结论。
• 系统提示“已损坏”或来源不明时，重新从官方发行页下载并核对版本；不要全局关闭 Gatekeeper。
• Windows 是否存在安装资产、签名和自动更新，以当前 Release Notes 为准。

首次扫描不到任何会话

1. 确认原客户端确实有本地历史

   Swob 读取本机来源保存的记录；云端存在但本机从未落盘的会话不会凭空出现。

2. 检查来源是否在首次启动时被关闭

   排除来源意味着不扫描、不显示、也不生成 Library 副本，不是临时筛选器。

3. 确认当前安装版本支持该来源

   当前源码登记 14 个来源，但公开稳定包、Windows Beta 和 current main 可能不同。

4. 查看 Library Health / Diagnostics

   先看扫描、writer、索引和错误状态；旧版本没有该入口时运行 swob doctor library --json。

不要通过手动复制原始 JSONL 到 Library 来“补会话”。Library 包含 manifest、派生 transcript、索引和来源证据，单个文件不构成完整会话包。

有会话标题，但正文不可用或不完整

先到来源矩阵核对 transcript、tools、thinking 能力，再看详情中的可用性状态。来源未保存 thinking、附件或工具结果时，空缺是证据边界；若来源支持正文但详情降级为 transcript-only 或 unavailable，再检查备份、来源路径和 Diagnostics。

• 切到 Full，确认不是 Compact 折叠了早期段落或工具结果。
• 检查会话是否只有 Library transcript，原始 source 已被客户端清理。
• 如果新会话持续出现正文缺失，优先解决解析或写入健康问题，不要对旧副本做全库重建。
• 只在 transcript status 证明派生 transcript 异常时，对单条会话先跑 rebuild --dry-run。

搜索不到预期内容

顶部会话搜索和 Spotlight 更适合标题、项目、来源与文件夹；transcript 正文由全文索引搜索。先用同一句原文分别测试元数据搜索和正文搜索，判断是哪一层缺失。

1. 清除来源、项目、日期和文件夹筛选。
2. 使用原文中连续、少见的 2–5 个词，避免只搜常见停用词。
3. 在目标会话内用 ⌘F / Ctrl+F 验证文本确实存在。
4. 运行 swob grep "原文" --limit 10；CLI 也无结果时检查索引新鲜度。
5. 只有健康状态指向索引问题时才执行对应修复，不要改标题来掩盖正文索引缺口。

Insights 没有 token、成本或部分图表

没有数字不一定是故障。会话可以被读取和计数，但来源没有权威 usage 时，token 与成本必须保持 unavailable；没有匹配价格规则时应是 unpriced，而不是 0。

• 先清除日期、来源、模型和项目筛选，确认统计母集不是空集。
• 查看来源矩阵中的 usage 能力；不同来源不能默认横向同质。
• API 等价值是估算，不是订阅账单；缺少模型、时间或可信用量时不会强行计价。
• 新会话未进入图表时，检查 Usage / Insights 新鲜度和 Library Health，而不是反复切换页签。

AI Profile、Keychain 或智能功能失败

依次检查“功能是否已绑定 Profile → Profile 是否存在 → 凭据是否在系统 Keychain → 模型和 Base URL 是否有效”。Base URL 不能内嵌用户名、密码、查询参数或片段。

• PROFILE_NOT_BOUND：为对应智能功能选择 Profile。
• PROFILE_NOT_FOUND：绑定指向已删除或不可用的 Profile，重新选择。
• PROFILE_KEY_MISSING / KEYCHAIN_UNAVAILABLE：在设置中重新保存凭据或修复系统凭据访问；不要在终端打印 API Key。
• LLM_REQUEST_FAILED：检查提供商、模型和明确授权的网络环境；问题报告只带错误类别，不带请求正文或凭据。
• LLM_RESPONSE_INVALID：模型没有返回规定 JSON；先用更稳定模型和小样本，不要手改 Library 元数据伪造成功。

CLI 提示 command not found 或输出不适合脚本

打开“设置 → CLI & Agent”，分别检查 CLI 文件、swob 命令入口和 Agent Skill。安装或修复后新开一个终端，再运行：

swob --version
swob --help
swob doctor library --json

仍找不到命令时，使用设置页显示的实际 CLI 路径核对安装，不要自己猜写系统目录。脚本消费时使用 --json 或 show --format=jsonl；stdout 应只含机器数据，诊断信息在 stderr。

Resume 只打开客户端、进入错误会话或没有反应

“启动客户端”“打开工作区”和“进入指定历史会话”是三个等级。先到来源矩阵核对 terminal-resume / native-resume，再检查当前来源的默认 surface、工作目录和 session ID。

1. 用 swob show <id> --full 核对目标会话来源和内容。
2. 用 swob resume <id> 生成命令，确认它没有因为来源边界退化为只打开应用。
3. 执行后在目标工具中核对上一轮消息或标题；只出现工作区不算成功。
4. 远端会话同时核对 SSH 目标、远端 cwd 和目标机上的 CLI；SSH 设置不会扫描远端磁盘。
5. Library 只有备份而源文件已缺失时，先进入安全复活流程，不要直接覆盖目标目录。

更新、版本或 Library 迁移问题

在“设置 → 更新”核对当前版本、稳定/预览频道和手动检查结果。Windows Beta 的分发和更新能力可能不同。更新后先打开一条熟悉会话并检查 Library 路径，不要立即删除旧安装或旧 Library。

移动 Library 应使用产品内迁移入口并等待完成状态；迁移成功后核对会话数量、一个正文样本和 Diagnostics。同步盘状态不等于独立备份，迁移前保留可恢复副本。卸载应用和删除 Library 是两件事：想保留历史时先记录并备份 Library；想完全删除时分别确认应用、配置与 Library 的范围。

首次扫描很慢、搜索或 Insights 持续落后

首次扫描需要读取来源、生成 Library 包并建立派生索引，耗时会随历史规模和可用字段增加。判断异常不要只看转圈时间：观察 Library Health 中扫描是否仍推进、writer 是否阻塞、搜索/usage lag 是否收敛。

• 先保留应用运行并等待当前单轮扫描完成，避免频繁退出造成重复启动成本。
• 不要同时启动多个 Swob 进程写同一 Library。
• 只对被证明确实陈旧的单条 transcript 做重建；全库重建不是常规性能优化。
• writer 长时间阻塞或 lag 不再变化时，保存错误类别和版本后再重启一次；可稳定复现则附最小诊断，不附 transcript 正文。

为什么会话突然消失？

先确认它是从 Swob 视图消失，还是原客户端源文件真的被清理。Claude Code 的本地保留策略可能删除旧源文件：一次真实审计中，1,621 个会话里有 253 个原路径已缺失，但 Vault 备份仍在。这个比例只描述该审计语料，不是每个人的预言。

1. 检查来源排除

   首启动或设置里排除的来源既不显示也不备份。

2. 搜索 Vault

   用标题、项目或 transcript 全文确认 Swob 副本是否存在。

3. 检查保留期

   对 Claude Code 延长本地会话保留期；它只能降低未来风险，不能凭空恢复已删除文件。

4. 需要续接时再复活

   只有点击 Resume 才进入受控写回；先核对目标实例和冲突。

参考：复活错误代码（当前 23 类）

只有界面或日志给出明确错误代码时才需要查本表。普通 Resume 失败先回到上面的 Resume 症状。

Windows x64 Beta 边界

Beta 当前聚焦 Windows x64 上 Claude Code 与 Codex 的本地发现、阅读、搜索、Library 和 Resume 最小闭环，不是 macOS 功能对等版。

网站只陈述用户能力边界；是否已公开交付以当前 GitHub Release 中是否存在 Windows 安装资产为准，不能把 CI 或源码存在包装成下载承诺。