导入与同步

本地处理先于云同步

Contextify 会先在你的设备上读取对话记录（transcript）文件，为其建立索引并写入本地数据库。云同步是另一个独立步骤：它把符合同步条件的已索引历史记录上传到托管版 Contextify Cloud 或你的自托管服务器，或从中下载。

如果你积累了多年的 Claude Code 或 Codex 会话，首次本地处理可能需要一些时间。这并不代表 Cloud 卡住了。

对话记录 Claude Code 和 Codex 在本地写入会话文件。

导入 Contextify 在本地为项目、对话和消息建立索引。

同步符合条件的已索引历史记录可以经由 Cloud 传输。

两项任务

任务	作用	运行位置
导入与建立索引	读取对话记录文件、解析消息、按项目分组，并更新本地搜索索引。	你的 Mac，或运行 `contextify ingest` 的 Linux 设备。
云同步	为所选 Cloud 工作空间上传和下载符合同步条件的已索引记录。	在你的设备与托管版 Contextify Cloud 或你的自托管 Cloud 服务器之间。

首次运行耗时较长，通常是因为在导入，而不是在同步。Contextify 在本地读取某个对话并为其建立索引之前，Cloud 无法上传它。

应用会扫描受支持的 Claude Code 和 Codex 对话记录文件夹，创建本地项目记录，并开始处理它能读取的对话。

对话继续时，Contextify 会检测对话记录的新变化，并为新消息建立索引。这是正常的后台工作，不是一次性导入。

消息建立索引后，本地摘要和元数据队列可能仍在工作。即使搜索已经可用，你也可能看到 Processing N items（正在处理 N 项）。

在大规模本地处理期间，应用可能显示 Indexing 3/40 projects（正在为项目建立索引）、Processing many items...（正在处理大量条目）或 Up to date（已是最新）等状态。这些状态描述的都是本地工作。

Contextify 针对大量历史记录做了优化，首次运行时也能批量导入大量数据。但它仍需解析实际文件、写入大量数据库行，并建立搜索索引。

影响首次运行的因素：对话记录的数量、超大会话、磁盘速度、电池和睡眠状况、文件夹访问权限，以及应用是否正在重建全新的数据库。

该怎么做：保持应用打开；如果历史记录很多，让 Mac 保持唤醒；在认定 Cloud 失败之前，先查看状态栏。

如果你在大规模处理期间退出，Contextify 的设计支持稍后继续。不过，最稳妥的首次运行方式仍是让初始处理完成。

云同步以本地数据库为起点：将符合条件的本地记录上传到已配置的工作空间，并从中下载符合条件的远程记录。

托管版 Cloud 和自托管 Cloud 使用相同的基本客户端模型。
Project Sync（项目同步）控制这台设备上哪些本地项目会上传。
导入运行期间，同步可能会等待，以免本地数据库写入相互冲突。
如果云端目标无法访问，已索引的历史记录会留在本地数据库。目标恢复可访问后，同步可以重试；但身份验证问题、Project Sync 设置或服务器错误仍可能需要你处理。

切换云端目标不是服务器之间的迁移，它只改变这台设备接下来同步到哪里。在托管版和自托管 Cloud 之间切换前，请先阅读云端切换指南。

Linux 上没有实时监视对话记录的 Mac 应用。CLI 会分批导入。

contextify status
contextify ingest
contextify install-service

contextify ingest 运行一次后即退出。contextify install-service 会在 Linux 上配置定期后台导入；如果 systemd 定时器可用，就使用它。默认间隔为 15 分钟。

Cloud 命令与导入命令相互独立：

contextify cloud status
contextify cloud projects
contextify cloud sync

部分标签会因应用版本和界面略有不同，但大致分为以下几类。

状态	通常表示	怎么做
Processing N items	本地摘要或元数据队列仍在工作。	稍等片刻；如果还看不到最新的上下文，再搜索一次。
Indexing X/Y projects	应用仍在本地导入已知项目。	先等首次处理完成，再判断云同步进度。
Waiting（等待中）	云同步正在等待对话记录导入完成。	通常无需操作。
Deferred（已推迟）	本地导入或数据库写入正在运行，同步已暂停。	它会自动重试，你也可以稍后手动同步。
Syncing（同步中）	设备正在上传或下载 Cloud 变更。	补同步需要上传大量数据时，请保持应用打开。
Offline（离线）	无法连接已配置的 Cloud 目标。	请检查配置的托管版或自托管目标是否可访问，不要只检查互联网是否连通。
Attention needed（需要处理）	某个服务器端补同步会话似乎已停滞，或已完成但存在问题。	点击“Retry”（重试）；如果该状态再次出现，请查看云同步故障排查。