导入历史对话之前，先确认读取的是哪台机器上的哪个目录，再确认解析后保留了什么。能在列表看到一个会话，说明应用创建了记录；它不证明原文件中的每个事件都已经完整保存。
本文针对 ChatCrystal 提交 7642768 的 Claude Code 适配器，说明可检查的导入流程。这里描述的是应用支持的数据形状，不是 Claude Code 文件格式永远不变的承诺。
当前适配器扫描哪些文件
适配器默认读取 ~/.claude/projects。scan() 遍历它的直接子目录，再寻找这些目录直接包含的 .jsonl 文件，并跳过小于 100 字节的文件。
~/.claude/projects/
└── encoded-project-directory/
├── session-a.jsonl
└── session-b.jsonl这个扫描并不是任意深度递归：更深层的子代理历史不应被假定自动纳入。会话 ID 来自文件名；项目显示名则由目录名启发式提取，优先寻找 Project 或 projects 分段，回退时取末尾一到两个分段。它不是可靠还原任意原始路径的解码器。
自定义路径应在服务启动前设置
CLAUDE_PROJECTS_DIR 由服务进程加载。对于尚未启动的新本机服务，POSIX shell 示例是：
CLAUDE_PROJECTS_DIR=/absolute/path/to/claude/projects crystal serve -dPowerShell 使用 $env:CLAUDE_PROJECTS_DIR = 'C:\path\to\projects' 后再启动服务。已有服务不会因为后来在 crystal import 前设置一个环境变量就重新加载路径；先确认目标服务及其启动配置，需要更换路径时再安排重启。
本文使用默认本机连接。远端云服务的 CLI 导入会在客户端扫描并上传解析结果，目录和数据传输边界都不同；操作前核对状态中的连接目标。
手动扫描与检查导入结果
crystal import
crystal --json conversations --source claude-code --limit 20第一条命令在当前本机流程中扫描已启用的来源；第二条使用 --json 走非交互分支，按 claude-code 筛选已存储的会话，在返回对象的 items 中核对项目、消息数与状态。当前 CLI 导入实现虽然注册了 --source，但本机交互面板与流式扫描分支没有传递该选项，所以不能用 crystal import --source claude-code 承诺只扫描这一来源。
空库启动可能插入演示数据，列表中的 demo- 记录不证明真实文件已经导入。按测试原文件的会话 ID 核对，不能只看来源标签或记录总数。
重复导入也不等于重复新增。导入服务先检查文件大小和修改时间；重新解析时再比较规范化内容的哈希。内容未变时跳过或仅更新元数据，内容改变时按当前替换流程处理原记录。修改过原文件后，应核对会话及其关联笔记状态，不能把旧摘要自动当作新内容的结论。
解析保留的是经过筛选的消息
JSONL 文件按行读取。无法解析为 JSON 的行会被跳过；有 uuid、顶层类型为 user 或 assistant 的记录才进入相关消息处理。系统记录、进度、流式增量等不会作为普通对话消息保留。
对于消息内的内容数组，适配器收集 text 块；thinking 块另外保存到思考字段，tool_use 设置标志，tool_result 不进入正文提取。没有正文但带思考或工具调用的消息仍可能保留。因此，“过滤 thinking 噪音”不能被理解为“所有思考块都被删除”。
部分命令回显和 system-reminder 标签会按现有规则清理，消息随后按时间戳排序。这个过程不是通用脱敏或完整事件归档；原文件应另行备份，需要敏感信息保护时也应单独检查。
跳过不一定是失败
| 结果 | 可以检查的原因 |
|---|---|
| 没有扫描到文件 | 路径不存在、层级不符合扫描范围、文件太小或没有读取权限 |
| 已扫描但跳过 | 大小和修改时间未变、解析内容未变、有效消息少于两条 |
| 解析缺少部分内容 | 噪音过滤、内容块提取规则、无效 JSON 行或历史写入尚未完成 |
| 错误计数增加 | 查看对应文件和导入日志，不只查看总对话数 |
确认两条消息只是当前导入门槛，不代表对话完整、内容重要或适合生成笔记。导入与摘要是两个阶段；选择一条记录执行摘要后，还要核对笔记的内容及向量处理状态。
自动监听需要单独验收
监听器在本机模式默认启动，监听新增与变化事件并做防抖；云模式不启动本机监听。但当前实现向 Chokidar 传入 Claude Code 的 **/*.jsonl glob，所用 Chokidar 5 已不支持 glob，见官方升级说明。因此，本版本不能保证新对话自动导入，需要单独验证监听。
验收时先手动导入一个已知文件，再创建或更新另一条非敏感测试历史，观察监听日志和会话列表。如果第二步没有变化，手动 crystal import 是明确的检查入口。防抖存在也不证明监听目标有效；出现问题时应保留实际路径、依赖版本与日志。