会话实时更新
Mantra v0.10.0 引入了会话实时更新功能，让你可以像看直播一样，打开正在进行中的 AI 编程会话，实时看到新消息出现。
什么是会话实时更新？
传统上，Mantra 查看的是已完成的会话记录。现在，当你的 AI 工具（Claude Code、Cursor、Gemini CLI、Codex）正在工作时，你可以同时打开 Mantra，看到每一条新消息实时出现在叙述面板中，无需手动刷新。
这对以下场景特别有用：
- 在另一台显示器上监控长时间运行的 AI 任务
- 随时了解 AI 正在做什么，而不用切换窗口
- 验证 AI 是否按照预期的方向推进
支持的数据源
| AI 工具 | 监听机制 | 说明 |
|---|---|---|
| Claude Code | JSONL 文件监听 | 增量读取，仅处理新增内容 |
| Codex | JSONL 文件监听 | 增量读取，仅处理新增内容 |
| Cursor | SQLite 定时轮询 | 只读轮询，不干扰 Cursor 自身操作 |
| Gemini CLI | JSON 文件监听 | 全量重解析后与上次状态对比 |
核心功能
实时消息渲染
新消息以淡入动画的方式出现在叙述面板中：
- 滚动跟随：如果你停留在底部，面板会自动跟随新消息向下滚动
- 悬浮提示：当你向上翻阅历史时，底部会出现「N 条新消息」浮动按钮，点击即可跳回最新位置
实时状态指示器
会话标题旁会显示当前监听状态：
| 状态 | 含义 |
|---|---|
| 🟢 Live | 正在实时监听，连接正常 |
| ⏸ 已停止 | 监听已停止，点击重新连接 |
| 🔄 重连中 | 连接中断，正在自动恢复 |
自动错误恢复
实时监听支持智能的自动恢复机制：
- 指数退避重连：连接中断时自动重试，最多 3 次，每次间隔递增
- 手动重连按钮：自动恢复失败后，提供手动重连按钮
- 空闲检测：当会话看起来已结束时，自动降低轮询频率，减少资源消耗
如何使用
打开正在进行的会话
- 启动 AI 工具开始一个编程任务
- 在 Mantra 的项目列表中找到对应项目
- 点击项目，Mantra 会自动检测并开启实时监听
- 会话标题旁出现 🟢 Live 标识，表示实时更新已激活
自动检测
Mantra 会自动判断当前会话是否正在进行中。如果会话文件最近有写入，就会自动开启实时监听。
跟踪新消息
开启实时监听后，Mantra 会处理以下情况：
- 正常追加：AI 每次回复后，新消息自动出现
- 工具调用：工具调用请求和结果会实时显示
- 错误处理：如果 AI 工具输出了无法解析的内容，Mantra 会跳过并继续监听
远程会话的实时更新
如果你通过 远程 SSH 接入 连接了远程服务器，实时更新同样支持远程会话：
- Claude Code / Codex：通过 SSH 流式读取远程 JSONL 文件尾部（类似
tail -f） - Cursor：通过 SSH 远程执行数据库查询
- Gemini CLI：通过 SSH 远程轮询 JSON 文件变化
- SSH 断线恢复：断线重连后，从上次读取的偏移量继续，不会遗漏消息
常见问题
为什么没有看到 Live 状态指示器？
可能的原因：
- 会话已完成：如果 AI 工具已经结束了该会话，Mantra 不会对其开启实时监听
- 导入的是历史会话：通过导入向导手动导入的过去会话不支持实时更新
- 文件权限：Mantra 需要有权限监听日志文件，请检查文件访问权限
解决方法：打开 AI 工具开始一个新任务，然后在 Mantra 中刷新项目列表。
实时更新会影响性能吗？
影响极小。Mantra 的实时监听经过专门优化：
- JSONL 监听：只读取增量内容，不重复解析已有部分
- SQLite 轮询：只读查询，不写入 Cursor 的数据库
- 空闲降频：会话结束后自动降低检查频率
- 单连接复用：远程 SSH 实时监听复用现有连接，不额外建立连接
实时更新会自动停止吗？
会。当 Mantra 检测到以下情况时，会自动暂停或停止监听：
- AI 工具会话正常结束（文件不再更新超过一段时间）
- 你切换到其他会话或关闭项目
- 应用后台运行时会降低检查频率（不完全停止）
你也可以随时手动点击状态指示器旁的停止按钮。
如何区分历史消息和实时新消息？
实时新消息会以淡入动画出现，与已有的历史消息视觉上有短暂的区别。动画结束后，外观与历史消息相同，保持界面的一致性。