数据管理与故障排查¶
适用范围：桌面端。 本页列出用户需要了解的实际数据位置与维护操作；原理章节只解释设计，不列源码路径。
配置与数据位置¶
| 内容 | 默认位置或入口 | 说明 |
|---|---|---|
| 数据根目录 | ~/.echo-agent/ |
启动前可用 ECHO_AGENT_HOME 调整 |
| 模型连接 | config.toml |
桌面端配置；保护其中的 API Key |
| MCP 配置 | mcp.json |
连接与工具设置 |
| 专家团 | collaboration.sqlite |
聊天、工作、决定等持久化记录 |
| 会话与记忆 | 数据根目录内对应目录 | 不与 Python Runtime 自动同步 |
| 工作文件 | 任务选择的工作目录 | 应独立纳入项目备份 |
两端可能使用相同的默认数据根目录，但配置格式与存储结构不同。进行独立测试或同时使用两端时，明确各自数据目录与备份范围。
本地保存与远端处理¶
会话、工作台状态、记忆和工作文件主要存于本机。模型推理接收所选上下文；Browser Use / Computer Use 可提供网页、控件内容与截图。桌面记忆检索配置了远端嵌入与重排服务，相关文本可能发送至这些服务。启用的 MCP、连接器、通知、云存储或组织服务也有独立网络交互。
API Key 存在本机配置中。排查问题和提交 Issue 时，应去除密钥、个人数据与业务内容，避免公开整份配置或会话。
备份与恢复¶
在“设置 → 数据管理”使用备份与恢复功能。备份覆盖应用登记的会话、记忆、专家团、项目、会议、代码工作台状态与部分界面状态。工作目录中的业务文件应另行备份；模型密钥和外部账号配置也应单独妥善保存。
恢复前查看备份预览，再确认应用。恢复在服务启动前处理，并有中断恢复记录；恢复历史不会自动重放已中断的外部操作。重要数据应定期验证备份是否能读取。
按症状排查¶
| 现象 | 优先检查 | 下一步 |
|---|---|---|
| 模型无法回复 | 连接测试、网络、Key、模型 ID | 改用已验证连接，再重试简单消息 |
| 有文本回复但工具失败 | 模型工具能力、参数、任务权限 | 查看具体工具错误 |
| IDE 无法打开 | 工作区授权、本地后端、项目依赖 | 保留未保存内容后重新连接 |
| 浏览器能力不可用 | 是否安装 Chromium 系浏览器 | 检查任务能力检测结果 |
| 电脑操作无法开始 | 系统权限与交互桌面 | macOS 核对实际运行应用的权限 |
| 文档未出现 | 实际输出路径、工具回执 | 打开目录并检查文件，勿重复覆盖 |
| 记忆内容过时 | 作用域、来源与旧事实 | 在设置中更正或遗忘 |
| 计划未执行 | 应用是否运行、电脑是否休眠 | 查看运行记录，再手动验证 |
| 专家团中断 | 对应工作的实际状态与已有产物 | 检查后重试指定工作 |
日志与更新¶
IDE 失败可检查 theia.log。默认配置使用系统应用数据目录；自定义 ECHO_AGENT_HOME 时，IDE 配置与日志位于该目录的 theia/ 下。
通过“设置 → 帮助与更新”检查更新。更新前保存编辑内容、完成或停止任务并备份重要数据。两端独立发布，更新桌面端不会更新独立 Python Runtime。