常见问题

这里汇总了用户最常遇到的问题和解决方案。按类别浏览或使用搜索快速找到答案。

快速查找

使用 Cmd/Ctrl + F 搜索关键词，快速定位你的问题。

安装问题

支持哪些操作系统？

Mantra 支持以下操作系统：

• macOS：12.0 (Monterey) 及以上版本
• Windows：Windows 10/11
• Linux：Ubuntu 20.04+、Fedora 35+、Debian 11+ 等主流发行版

详细的系统要求请参考 兼容性信息。

如何更新 Mantra？

更新 Mantra 有以下几种方式：

1. 自动更新：Mantra 会定期检查更新，有新版本时会在应用内提示
2. 手动检查：打开设置 → 关于 → 检查更新
3. 重新下载：从官网下载最新版本安装包重新安装

建议开启自动更新以获取最新功能和安全修复。

安装失败怎么办？

如果安装过程中遇到问题，请尝试以下步骤：

1. 检查系统要求：确保你的操作系统版本符合 最低要求
2. 以管理员身份运行（Windows）：右键点击安装程序，选择「以管理员身份运行」
3. 允许安装来源（macOS）：系统设置 → 隐私与安全性 → 允许从 App Store 和已知开发者安装
4. 清理旧版本：完全卸载旧版本后重新安装
5. 检查磁盘空间：确保有足够的磁盘空间（至少 500MB）

如果问题仍然存在，请在 GitHub Issues 提交问题报告。

需要多少磁盘空间？

Mantra 的磁盘空间需求如下：

• 应用本身：约 200MB
• 运行缓存：约 100-500MB（取决于导入的项目数量）
• 建议预留：至少 500MB 可用空间

导入的项目数据会额外占用空间，具体取决于你的对话记录大小。

可以同时安装多个版本吗？

不建议同时安装多个版本。Mantra 使用相同的数据目录，多版本可能导致数据冲突。

如果需要测试新版本，建议：

1. 备份当前数据（设置 → 数据 → 导出）
2. 卸载旧版本
3. 安装新版本
4. 如需回退，可恢复备份数据

如何卸载 Mantra？

macOS：

1. 退出 Mantra 应用
2. 将 Mantra 从「应用程序」文件夹拖到废纸篓
3. 清理数据（可选）：删除 ~/Library/Application Support/Mantra

Windows：

1. 打开「设置」→「应用」→「已安装的应用」
2. 找到 Mantra，点击「卸载」
3. 清理数据（可选）：删除 %APPDATA%\Mantra

Linux：

# 如果使用 apt 安装
sudo apt remove mantra

# 清理数据（可选）
rm -rf ~/.config/mantra

导入问题

支持导入哪些 AI 工具？

目前 Mantra 支持导入以下 AI 工具的对话记录：

工具	支持状态	说明
Claude Code	✅ 完全支持	支持所有版本
Gemini CLI	✅ 完全支持	支持 1.0.0+
Cursor	✅ 完全支持	支持 0.40.0+
Codex	✅ 完全支持	支持 1.0.0+
Antigravity	🔜 即将支持	敬请期待

更多 AI 工具支持正在开发中，请关注 版本更新。

导入失败怎么办？

导入失败的常见原因和解决方法：

1. 文件格式不正确

   • 确保选择的是正确的 AI 工具日志目录
   • Claude Code 日志通常在 ~/.claude/projects/
   • Gemini CLI 日志通常在 ~/.gemini/
   • Cursor 日志通常在 ~/.cursor/

2. 文件权限问题

   • 确保 Mantra 有权限读取目标目录
   • macOS 用户需要在系统设置中授予文件访问权限

3. 日志文件损坏

   • 尝试只导入最近的项目
   • 跳过有问题的日志文件

4. 版本不兼容

   • 检查 AI 工具版本是否在支持范围内
   • 更新 Mantra 到最新版本

如果问题持续，请提供错误信息到 GitHub Issues。

为什么找不到对话记录？

可能的原因：

1. 日志目录位置变化

   • AI 工具更新后可能改变日志存储位置
   • 尝试使用导入向导的「自定义路径」选项

2. 对话未保存

   • 某些 AI 工具默认不保存对话历史
   • 检查 AI 工具的设置，确保开启了日志保存

3. 日志被清理

   • 系统清理工具可能删除了日志文件
   • 检查回收站/废纸篓

4. 工作区模式

   • 某些 AI 工具在不同工作区有独立的日志
   • 确保查找的是正确的工作区目录

参考 导入向导 了解详细的导入流程。

可以导入多个项目吗？

可以。Mantra 支持导入和管理多个项目：

1. 在导入向导中可以一次选择多个项目目录
2. 导入后每个项目会独立显示在项目列表中
3. 可以随时添加新的项目
4. 不同 AI 工具的项目可以同时导入

项目管理技巧：

• 使用项目列表的搜索功能快速定位
• 可以为项目添加标签便于分类
• 不需要的项目可以从列表中移除（不会删除原始文件）

导入后原始文件会被修改吗？

不会。Mantra 采用只读模式处理原始日志文件：

• 导入过程只读取日志内容，不做任何修改
• 所有分析和注释都保存在 Mantra 自己的数据目录中
• 即使在 Mantra 中做了任何操作，原始 AI 工具日志保持不变
• 你可以放心导入，不用担心影响原有数据

这意味着你可以继续正常使用 AI 工具，Mantra 会自动同步新的对话。

如何删除导入的项目？

删除导入的项目：

1. 在项目列表中找到要删除的项目
2. 右键点击项目名称
3. 选择「从 Mantra 移除」

注意事项：

• 这只会从 Mantra 中移除项目引用
• 不会删除原始的 AI 工具日志文件
• 移除后可以重新导入
• 如果想清理所有数据，使用设置中的「清除缓存」功能

时光旅行问题

为什么代码快照不显示？

代码快照不显示的可能原因：

1. 没有关联的 Git 仓库

   • 时光旅行功能依赖 Git 历史
   • 确保项目目录是一个 Git 仓库

2. Git 历史不完整

   • 对话发生时的代码版本可能没有被提交
   • 建议在 AI 编程过程中勤提交代码

3. 时间戳不匹配

   • Mantra 根据消息时间戳匹配 Git 提交
   • 如果系统时间不准确可能导致匹配失败

4. 权限问题

   • Mantra 需要访问 Git 仓库的权限
   • 检查仓库目录的读取权限

详细说明请参考 时光旅行功能。

为什么 Git 历史匹配失败？

Git 历史匹配是通过时间戳进行的，失败的原因可能是：

1. 对话时间与提交时间差距过大

   • Mantra 使用一定的时间窗口进行匹配
   • 如果提交时间与对话时间相差太远，可能无法自动匹配

2. 本地时间设置不正确

   • 确保系统时间准确
   • 时区设置不正确也会影响匹配

3. 使用了 rebase 或修改了提交历史

   • 这会改变提交时间戳
   • 建议保持原始的提交历史

手动匹配：如果自动匹配失败，可以在时间线上手动选择对应的提交。

代码快照和当前文件不一致？

这是正常现象。代码快照显示的是 历史时间点 的文件内容：

• 快照反映对话发生时的代码状态
• 当前文件可能已经被后续修改
• 这正是时光旅行功能的价值所在——帮你回顾代码演变过程

如果想对比历史版本和当前版本：

1. 在时光旅行视图中选择历史快照
2. 使用「对比当前」功能查看差异
3. 也可以复制历史代码用于参考

如何浏览历史版本的所有文件？

在时光旅行模式下浏览文件树：

1. 进入时光旅行视图
2. 选择一个时间点
3. 展开左侧的文件树面板（Cmd/Ctrl + \）
4. 浏览该时间点的完整文件结构
5. 点击任意文件查看其历史内容

文件树会显示：

• 当时存在的所有文件
• 被修改的文件会有标记
• 新增/删除的文件会用不同颜色标识

详细操作参考 时光旅行进阶。

没有 Git 仓库能用时光旅行吗？

部分功能可用：

可用功能：

• 浏览对话的时间线
• 查看每个时间点的消息内容
• 消息中的代码块查看

不可用功能：

• 代码快照（需要 Git 历史）
• 文件树浏览（需要 Git 历史）
• 代码版本对比（需要 Git 历史）

建议：如果你经常使用 AI 进行编程，强烈建议为项目初始化 Git 仓库。这样可以充分利用时光旅行功能。

# 初始化 Git 仓库
git init
git add .
git commit -m "Initial commit"

分享问题

如何安全分享项目？

Mantra 提供了安全的分享方式：

1. 使用内容脱敏功能

   • 在分享前，使用 内容脱敏 功能
   • 自动识别并替换敏感信息（API 密钥、密码等）
   • 可自定义脱敏规则

2. 选择性分享

   • 只导出需要分享的对话部分
   • 可以排除包含敏感信息的消息

3. 分享链接设置

   • 可以设置链接的有效期
   • 可以添加访问密码
   • 可以限制查看次数

详细说明参考 内容脱敏功能。

分享链接有效期多久？

分享链接的有效期取决于你的设置：

选项	说明
1 小时	适合临时快速分享
24 小时	适合一天内的协作
7 天	适合项目周期内的分享
30 天	适合长期参考
永久有效	链接永不过期（需要手动删除）

你可以随时在「已分享」列表中查看和管理所有分享链接。

可以取消分享吗？

可以随时取消分享：

1. 打开项目详情
2. 进入「分享」选项卡
3. 在「已分享」列表中找到要取消的链接
4. 点击「删除」按钮
5. 确认删除操作

取消后：

• 链接立即失效
• 已访问的用户无法再次访问
• 不会影响本地的项目数据

脱敏后还能恢复吗？

分享的版本不可恢复：

• 分享时如果启用了脱敏，导出的内容是脱敏后的版本
• 敏感信息已被替换，无法从分享链接中恢复

本地数据不受影响：

• 脱敏只作用于导出/分享的副本
• 你本地的原始数据保持不变
• 可以随时查看原始内容

这是为了确保分享的安全性——即使链接被泄露，敏感信息也已被保护。

性能问题

大项目加载很慢怎么办？

优化大项目加载的方法：

1. 使用增量加载

   • Mantra 默认只加载最近的对话
   • 滚动时自动加载更多内容

2. 过滤不需要的内容

   • 使用消息过滤功能只显示需要的消息
   • 减少同时渲染的内容量

3. 清理旧数据

   • 删除不再需要的项目
   • 清理缓存（设置 → 存储 → 清除缓存）

4. 硬件建议

   • 建议至少 8GB 内存
   • 使用 SSD 可显著提升加载速度

占用内存过高怎么办？

降低内存占用的方法：

1. 关闭不使用的项目

   • 只保持当前需要查看的项目打开
   • 关闭其他项目标签页

2. 禁用预加载

   • 设置 → 性能 → 关闭「预加载相邻内容」

3. 减少时光旅行缓存

   • 设置 → 性能 → 减少「快照缓存数量」

4. 定期重启应用

   • 长时间使用后重启可释放内存

内存使用参考：

• 基础运行：约 200-300MB
• 中等项目：约 500MB-1GB
• 大型项目：可能需要 2GB 以上

如何清理缓存？

清理缓存可以释放磁盘空间和解决某些问题：

清理应用缓存：

1. 打开 Mantra 设置（Cmd/Ctrl + ,）
2. 选择「存储」选项卡
3. 点击「清除缓存」
4. 选择要清理的内容类型
5. 确认清理

可清理的内容：

类型	说明	影响
视图缓存	UI 渲染缓存	下次打开需要重新渲染
搜索索引	搜索功能缓存	下次搜索需要重建索引
Git 快照	时光旅行缓存	需要重新生成快照

注意：清理缓存不会删除你的项目数据。

其他问题

如何反馈问题？

反馈问题的渠道：

1. GitHub Issues（推荐）

   • 访问 https://github.com/gonew/mantra/issues
   • 提供详细的问题描述和复现步骤
   • 附上错误截图和日志信息

2. 应用内反馈

   • 帮助 → 发送反馈
   • 可以自动附加系统信息

3. 社区讨论

   • 加入我们的 Discord 社区
   • 与其他用户交流使用经验

提交问题时请包含：

• Mantra 版本号
• 操作系统版本
• 问题的详细描述
• 复现步骤
• 错误日志（如有）

如何获取最新信息？

获取 Mantra 最新信息的渠道：

• 官方网站：mantra.gonewx.com
• 官方邮箱：mantra@gonewx.com
• GitHub 仓库：查看最新发布和更新日志
• 邮件订阅：在官网订阅更新通知

建议关注 GitHub 的 Release 页面，第一时间获取新版本信息。

更多帮助

如果以上问题没有解决你的疑惑：

• 查看 快捷键列表 提高使用效率
• 了解 兼容性信息 确保环境正确
• 阅读 功能文档 深入了解各项功能
• 访问 GitHub Issues 提交新问题