项目管理
Chronicle 如何将来自各种 AI 工具的会话归入逻辑项目、始终将它们关联到正确的代码文件夹，并支持同步、重命名、关联和导航。
在 Chronicle 中，一个项目是一个物理代码文件夹，而不是某个工具专属的孤岛。只要它们运行在同一目录下，来自 Claude Code、Codex、Cursor、OpenCode、Gemini CLI 和 Copilot Chat 的会话就会全部汇聚到同一个项目下——因此一张项目卡片会展示一个代码库跨越所有触及过它的工具的完整历史。本页介绍这种聚合是如何工作的、每个项目上的各项控制，以及如何在项目和会话之间移动而不迷失当前位置。
逻辑项目与自动聚合
每个解析器都会记录会话运行所在的物理工作目录（cwd）。在导入时，Chronicle 会依据该路径将会话归入某个项目——因此如果你在同一个仓库里同时用过 Claude Code 和 Cursor，它们会自动落在同一张卡片上，无需手动关联。卡片会体现这一点：为每个贡献了会话的工具显示一个来源标签（✳ claude-code、⬡ codex、▮ cursor、✦ gemini-cli……），外加会话数、消息数和最近活跃时间戳。
最新的 cwd 胜出（仓库移动）
在你移动或重命名仓库之后恢复的会话，其早期日志记录中携带的是旧路径。Chronicle 使用它看到的最后一个 cwd——也就是仓库及其 Git 历史现在所在的位置——来将会话归入项目，并将子目录 cwd 向上折叠到某个已见过的祖先目录。为了以低成本捕捉到这一点，扫描器会同时嗅探每个日志文件的头部和尾部各 64 KB。其结果是：移动仓库不会把它的历史散落到一堆幽灵项目里。
Git 徽标
如果项目文件夹是一个 Git 仓库，卡片上会显示一个带有实时分支和提交数的标签（⎇ main，悬停查看提交数）。这是真正实时的——Chronicle 在每次项目请求时都会调用 git 且不做任何缓存，因此它始终反映工作树的当前状态。如果你以为已经合并了，标签却仍显示某个功能分支，那么标签是对的，而你的检出仍停留在那个分支上。没有 Git 仓库的项目则会显示*“No Git repo — time travel unavailable”*：回放依然可用，但没有代码快照可供重建。
每张卡片上的齿轮菜单
每张项目卡片上的 ⚙ 菜单包含四个操作：
| 操作 | 作用 |
|---|---|
| ⟳ Sync Update | 重新扫描该项目的各个来源，并重新导入任何新增或变更的会话。幂等——重新导入一个会话是先删除再重新插入，会保留你在 Chronicle 中的重命名。 |
| ⓘ View Details | 打开项目分析主页（统计卡片、趋势图、来源环形图、调用排名）。 |
| ✎ Rename | 为项目设置一个显示名称。磁盘上的源文件夹不会被改动。 |
| 🗑 Remove from Chronicle | 从 Chronicle 的数据库中移除该项目。你的源日志和项目文件夹永远不会被删除。 |
关联没有真实路径的来源
大多数工具都会报告一个真实的 cwd，但 Gemini CLI 不会——它的会话会得到一个虚拟路径（gemini-project:<hash>）和一个**“Needs association”（需要关联）横幅。将它指向实际的代码文件夹并点击 Associate；如果该路径下已存在一个匹配的项目，Chronicle 会迁移这些会话并将它们合并进那个匹配的项目**。任何项目都可以用这种方式进行手动关联。
取消关联某个来源
聚合的反向操作：当一个项目包含来自多个工具的会话时，项目头部会为每个来源显示一个取消关联标签（⛓✕ cursor）。取消关联会把该来源的会话拆分到它们各自独立的项目中——当两个工具恰好共用了同一目录、但你想把它们分开跟踪时很有用。
导航：面包屑切换器
在项目视图或会话视图内部，顶部的面包屑由两个下拉框组成——一个项目选择器和一个会话选择器。它们让你可以就地跳转到另一个项目或另一个会话，而无需退回到项目网格。会话视图以会话 id 为键，因此切换时会干净地重新挂载，面包屑、选择器和标题会一起更新。
同步单个会话
在一个会话内部，你可以用 ⇧⌘U（Sync Update 该会话）只重新导入这一个会话——当某个会话仍在被写入、而你想把最新的对话拉入数据库时很方便。这只会重新导入当前会话，而不是整个项目。
会话卡片与真实上下文用量
每张会话卡片会显示它的显示名称——由一条统一的优先级规则解析得出：你在 Chronicle 中的重命名 → 解析出的标题 → 第一条提示词（参见 src/ProjectDetail.jsx 中的 sessionDisplayName()）——以及它的来源标签和一个上下文指示器：
⧉ 42k ctx— 会话最后一条消息处的真实上下文窗口大小，读取自工具自身的用量记录。⧉ ~38k tokens— 当没有真实用量数据时显示的回退估算值（约每 4 个字符 1 个 token）。真实上下文只在导入时填充，因此升级后请执行 Sync Update 或重新导入来回填它。
时间范围选择器（Today / All time / 7 / 30 / 365 天）会重新界定项目统计数据和图表的范围。