> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 数据迁移

> 通过 GUI 迁移向导，从其他 AI 助手零风险导入数据。

## 概述

Myrm 提供完整的数据迁移系统，支持从多个平台导入 AI 助手数据——包括记忆、技能、API 密钥、MCP 配置和工作区规则——具备完整预览、冲突处理和一键回滚能力。

**支持的数据源（14 种，11 种已就绪）**：Hermes、OpenClaw、**Pi**、Claude Code、Cursor、Codex、ChatGPT、gbrain、Mem0、原生 JSON、Myrm Archive、AgentMemory —— Windsurf、Trae、MemWeaver 处于规划开发中

## 迁移向导（3 步 GUI）

### 第 1 步：发现

前往 **设置 → 记忆中心 → 迁移** 启动向导。

* **本地/桌面端**：点击 **扫描** 自动检测系统中已安装的 AI 助手
* **云端**：拖拽上传来自其他助手的 `.zip` 导出文件

扫描器检查已知目录（macOS、Windows、Linux），并以置信度评分（高/中/低）报告发现结果。

### 第 2 步：预览（Dry-Run）

点击任意检测到的数据源上的 **预览**，查看将要导入的内容——不会写入任何数据：

* **覆盖矩阵**：展示哪些数据类别已就绪、需审核或需手动操作
* **迁移车道**：人设 → Agent、事实 → 记忆、技能 → 审核队列、密钥 → 显式确认、MCP → 审核
* **Token 经济性**：对比迁移前后的 token 用量
* **MCP 服务预览**：查看导入后可用的 MCP 工具
* **冲突检测**：高亮标注将覆盖现有数据的条目

### 第 3 步：确认并导入

选择目标 Agent（或创建新 Agent），然后确认导入：

* 密钥仅在用户显式同意后导入（绝不静默导入）
* 技能进入审核队列——由你逐个批准后才激活
* 每次导入生成唯一的事务批次 ID
* ZIP 技能迁移在预览和确认阶段使用一致的错误契约（`message + error_code`），前端提示行为确定可预期

## 导入后 Readiness（首聊引导）

导入成功后，Myrm 会在**首条消息前 live-resolve readiness**——不会让用户猜「为什么聊不了」。

| 状态           | 用户看到什么                   | 去哪修复                 |
| ------------ | ------------------------ | -------------------- |
| **Warning**  | Toast + 流内提示：MCP 已导入但未启用 | **设置 → MCP**         |
| **Critical** | Toast：诊断失败或模型未就绪         | **设置 → 记忆** 或 **模型** |

**设计原则：**

* **软门禁** — assistant 仍可回复，给引导而非硬阻断
* **Issue-aware CTA** — 每个 gap 直达对应设置页（`settings_path` SSOT）
* **Wizard recheck** — 迁移结果页可重新检查 readiness 再「开始聊天」
* **Queue anchor** — handoff 状态跨页面保留至首聊消费

**验证（2026-07-29）**：Chrome E2E **sequential 3-leg 签收 3/3 PASS**（mcp\_warning · provider\_critical · diagnostic\_critical，8 路并行 wave 下未停其他 pytest）· 65+ 单元/集成测试 · 竞品多为导入后 silent fail 或无 GUI 引导。

Hermes 迁移后，Readiness 还可能提示 **voice** 或 **MoA 顾问叠加** 配置引导（Hermes 用过但 Myrm 智能体未开启 overlay 时）——各链对应设置页，不阻断聊天。

## Hermes 定时任务导入（默认暂停）

从 **Hermes** 迁移时，向导可导入 `cron/jobs.json` 中的定时任务：

| 步骤           | 行为                                                 |
| ------------ | -------------------------------------------------- |
| **Dry-run**  | 预览将导入的任务与 skip 列表（如 `no_agent`、纯 script）及原因        |
| **Confirm**  | 可映射的 agent 类任务以 **PAUSED** 创建——需你在设置中 Resume 后才会运行 |
| **Result**   | 汇总计数 + **配置定时任务** 按钮深链至 **设置 → 定时任务**              |
| **Rollback** | 批次 `cron_rollback` 撤销该次导入创建的 cron                  |

**诚实边界：**

* 不迁移 Hermes **model** 字段——任务使用目标 Agent 默认模型
* **Kanban** 看板**不**自动迁移（覆盖矩阵显示 `kanban_not_migrated`）
* Cron 导入**尚无** Chrome MCP E2E 签收——后端由 **`test_hermes_cron_converter.py` 7/7 通过**（2026-08-03）覆盖

竞品（Hermes CLI `claw migrate`、OpenClaw、Pi、deer-flow、LobsterAI、CoPaw、jiuwenclaw）均无 GUI 迁移向导 + cron 预览/暂停导入/回滚。

## Pi 迁移（五车道映射）

从 **Pi** 迁移时，向导自动扫描 `~/.pi/agent/` 目录并提供五车道映射：

| Pi 数据                   | 导入车道               | 说明                                         |
| ----------------------- | ------------------ | ------------------------------------------ |
| `AGENTS.md`             | Agent 人设 (persona) | Pi 的系统提示词导入为 Agent 指令                      |
| `settings.json`         | 配置补充 (supplement)  | 默认 provider、模型等配置信息                        |
| `sessions/*.jsonl` (v3) | 情景记忆 (episodic)    | 对话历史导入为记忆，支持多轮消息、工具调用过滤、list content 合并    |
| `skills/*/SKILL.md`     | 技能审核队列             | Markdown + YAML frontmatter 格式完全兼容，自动发现并导入 |
| `auth.json`             | 凭证 (env\_keys)     | API 密钥映射为 Myrm 环境变量格式（需显式确认）               |

**边界保护：**

* 未知 session 版本（≠ v3）自动跳过，不报错
* 空消息、非法 JSON、非 dict content 等异常行均安全跳过
* Pi 无 MCP 配置（技术栈差异），不影响迁移完整性

**验证（2026-08-03）：** `test_pi_migration.py` **25/25 PASS**（覆盖发现/加载/会话解析/技能/凭证/边界保护共 6 类 25 场景）

## Hermes MoA 参考模型导入（向导 Confirm）

Hermes `config.yaml` 含 `moa` 块时，迁移向导 confirm 可将参考模型写入目标智能体 **`engine_params.moa_overlay`**：

| 步骤          | 行为                                                                    |
| ----------- | --------------------------------------------------------------------- |
| **Dry-run** | 预览含 `hermes_moa` 链路 — 显示 default（或首个 enabled）preset 名称与 ref 数量        |
| **Confirm** | `hermes_moa_migrator` 映射 Hermes refs → Myrm overlay；无法解析的 provider 跳过 |
| **导入后**     | 打开聊天 → 模型选择器 **多智能体混合** 分组 → 按会话选 **标准 / 深度审查 / 快速**                  |

**诚实边界：**

* 仅导入 **default** preset 的 ref 集（多个 preset **不同** ref 池 → 请建多个智能体 Profile）
* **不**迁移 Hermes **aggregator** 模型 — Myrm 主模型吸收顾问输出（设计如此）
* 须先在 Myrm 配置 provider；不可解析的 ref 会跳过并写日志

**验证（2026-08-03）：** **`test_hermes_moa_migrator.py` 19/19** + import confirm 集成 — 属 **30/30** MoA server pytest 套件。

## 回滚

每次导入都可完全撤销：

1. 前往 **设置 → 记忆中心 → 近期导入**
2. 点击任意导入批次的 **回滚**
3. 预览将要撤销的内容（回滚 dry-run）
4. 确认后恢复到之前的状态

## 备份与远程同步

### 本地备份

随时创建所有记忆的手动备份：

* **设置 → 系统 → 备份** → 创建备份
* 存储内容：所有记忆类型、共享上下文、对话历史
* 支持列表查看、恢复或删除备份

### 远程备份（S3 / WebDAV）

配置自动同步到云存储：

* **S3 兼容**：任何提供商（AWS S3、Cloudflare R2、MinIO 等）
* **WebDAV**：NAS 设备、Nextcloud、ownCloud 等

## 新用户引导

首次启动 Myrm 时，**引导向导** 会自动检查系统中是否存在其他 AI 助手的数据。如果发现，将提供一键迁移路径——让你的第一次对话就已拥有你的人格、记忆和工具。

聊天窗口中也会在检测到外部数据时显示 **发现横幅**，提供快速访问迁移向导的入口。

## 导出

### 全量归档备份与恢复

将整个 Myrm 工作区导出为结构化归档，保留所有数据关系：

* **对话**：完整消息历史，包含压缩状态（摘要）、会话笔记、工具使用统计和 token 费用汇总
* **记忆**：所有记忆类型（情景、语义、程序性、偏好、共享上下文）
* **Agent 配置**：完整 Agent 配置文件（模型、提示词、技能、MCP 绑定）通过 JSON 导出/导入
* **分区选择性恢复**：导入完整归档或选择特定分区（仅对话、仅记忆等）

这是灾难恢复、跨实例克隆或团队入职的推荐路径。

### 跨部署迁移（本地 ↔ 云端）

Myrm 在所有部署模式中使用 SQLite 作为单一数据存储。在本地 WebUI、Tauri 桌面端和云托管之间迁移是无缝的：

* **Volume 复制**：直接复制 SQLite 数据库文件——零数据丢失、零格式转换
* **归档路径**：从一个部署导出完整归档，在另一个部署通过分区选择恢复

没有竞品支持这种级别的部署可移植性；大多数被锁定在单一部署模式中。

### 数据集导出

将对话数据导出为训练就绪格式：

* **ShareGPT**：标准微调格式
* **PII 脱敏**：可选移除个人信息
* **质量过滤**：最少轮数、最少内容长度、仅成功对话
* **增量导出**：仅导出上次导出后的新数据

## 竞品对比

| 功能                   |       Myrm      |    Hermes   | OpenClaw |  Pi | Claude Code |
| -------------------- | :-------------: | :---------: | :------: | :-: | :---------: |
| GUI 迁移向导             |        ✅        |   ❌ 仅 CLI   |     ❌    |  ❌  |      ❌      |
| Dry-Run 预览           |        ✅        |    ✅（文本）    |     ❌    |  ❌  |      ❌      |
| 一键回滚                 |        ✅        |      ❌      |     ❌    |  ❌  |      ❌      |
| 多源发现                 |  ✅（14 源，11 就绪）  |    ❌（1 源）   |     ❌    |  ❌  |      ❌      |
| 云端 ZIP 上传            |        ✅        |      ❌      |     ❌    |  ❌  |      ❌      |
| 确定性导入错误码             |     ✅（预览+确认）    |      ❌      |     ❌    |  ❌  |      ❌      |
| 远程备份（S3/WebDAV）      |        ✅        |      ❌      |     ❌    |  ❌  |      ❌      |
| Token 经济性对比          |        ✅        |      ❌      |     ❌    |  ❌  |      ❌      |
| MCP 配置迁移             |        ✅        |   ✅（直接覆盖）   |     ❌    |  ❌  |      ❌      |
| 技能审核队列               |        ✅        |      ❌      |     ❌    |  ❌  |      ❌      |
| 目标 Agent 选择          |        ✅        |      ❌      |     ❌    |  ❌  |      ❌      |
| 全量归档备份/恢复            |        ✅        |      ❌      |     ❌    |  ❌  |      ❌      |
| 分区选择性恢复              |        ✅        |      ❌      |     ❌    |  ❌  |      ❌      |
| 跨部署迁移                |     ✅（3 种模式）    |    ❌（单一）    |   ❌（单一）  |  ❌  |   ❌（仅 CLI）  |
| Agent 配置导出/导入        |      ✅ JSON     |      ❌      |     ❌    |  ❌  |      ❌      |
| 对话导出含压缩状态            |        ✅        |      ❌      |     ❌    |  ❌  |      ❌      |
| 对话分享（只读链接）           | ✅（HMAC+TTL，可撤销） |      ❌      |     ❌    |  ❌  |      ❌      |
| Hermes 定时任务导入（暂停+回滚） |        ✅        | ❌ 仅 CLI，无预览 |     ❌    |  ❌  |      ❌      |
| Pi 五车道映射迁移           |        ✅        |      ❌      |     ❌    | N/A |      ❌      |