📦 项目资料跨平台迁移 · Project Cross Migration

> 备份 → 搬运 → 还原：把项目资料（含 Agent 人格、工具与环境）完整迁移到新框架 / 新机器——逐字还原、恢复即用，不用向新机器从头解释你的项目。
> 本 Skill 是 raw-conversation-backup v1.x 的项目级升级版：JSONL schema 完全兼容，范围覆盖项目工作状态全量，内置隐私分层规范与还原验收清单。
> v2.1 修订：人格层按迁移模式恢复；新增工具与环境层。
> v2.2 修订（三项）：① 脱敏从"迁移必经步骤"降级为可选隐私配件——私有备份/本机还原/换机默认完全不动原文，凭据随包、恢复即用；② 备份范围新增框架环境快照 _environment.json；③ 运行入口强制校验平台框架与任务名称，备份目录以任务名命名并落显眼位置。
> v2.3 修订（三项）：① 关键决策拆成五道分步确认闸门（G1 备份范围 / G2 内容抽检 / G3 落位确认 / G4 附件与成果 / G5 模型一致性）——逐道向用户确认、逐道落库，未全确认拒绝打包（confirm_gate.py --check）；② 备份默认落位改桌面；③ 环境快照新增 source_model，还原侧提示"建议用同一模型恢复"。
> v2.4 修订（整合收口）：把 v2.2.1 测评修复与 v2.3.0 闸门改造做一次一致性对账——① 六个脚本版本号统一为 2.4.0 且全部脚本均可自报版本（restore_dialogue.py / validate_jsonl.py 此前无 VERSION 常量，现已补齐并在启动时打印）；② 平台边界、Python 运行要求等 v2.2.1 文档修复在 v2.3.0 中的回退项一并回归；③ 六脚本全量用例复跑（含新增一致性断言）通过。

〇、主作用声明（先读这个）

这个 Skill 的主作用：跨平台迁移某个项目的全部资料。

> 平台边界（v2.2.1 明示）：Coze / Dify / 扣子 / 腾讯元器 等在线 SaaS 平台架构性不支持——对话数据在服务侧、无本地文件形态。preflight 命中此类框架名会给 warning 但不拦截（用户可先走平台自带导出/API 落地为本地文件，再进入备份流程）。

迁移的不是"聊天记录"，而是"项目工作状态"：

验收标准：零丢失 + 可续聊 + 环境可复现——新 Agent 读完资料包，用户不需要重新交代背景，也不需要重新摸索环境。

> 人类层说明：对 Agent 说「迁移项目」「对话搬家」「从备份恢复」即可。资料只走本地，不上传云端。

一、迁移范围：五层模型 + 环境快照（v2.3 修订）

L4 人格层：两种迁移模式（v2.1 核心修订）

还原向导第一步必须确认模式：

> v2.0 的"L4 不覆盖"仅适用于 persona-keep 场景；把它当默认是场景假设错误，v2.1 已修正——大多数迁移（换机/换框架）人格恰恰是最需要恢复的资产。

兼容性边界（v2.2.0）：与 raw-conversation-backup v1.0.1（WorkBuddy 管道）完全兼容；与 MindVault OpenClaw/Marvis 模式导出包兼容还原（其 tool 条目仅含 key_param/args_summary，校验器按兼容模式放行并输出 INFO 说明）。

L5 工具与环境层细则（v2.1 新增，v2.2 扩环境快照）

• 打包内容：TOOLS.md（工具约定与本地环境备注）、skills/（自装技能源目录）、HEARTBEAT.md（定时任务清单）、config 片段、_environment.json（框架环境快照）。
• 还原纪律：跨框架时工具格式/路径可能不兼容——逐项评估后恢复，不盲目覆盖目标框架的现有工具；技能类按目标框架的目录规范安装。
• 凭据纪律（v2.2 重新划线，见 §二）：私有迁移场景凭据随包、恢复即用，不再强制生成凭据缺口清单；只有隐私副本才脱敏并出 _credentials_needed.md。

框架环境快照 _environment.json（v2.2 新增）

回答的问题：这套资料当年跑在什么框架、什么版本、装了哪些工具、config/hooks/权限规则在哪、模型怎么配的、系统是什么。
为什么需要：资料搬过去了、环境对不上，等于没迁——尤其换机后 Node/Python 版本、CLI 依赖、hooks 路径常常是隐形的坑。

字段结构（scripts/environment_snapshot.py 采集，纯 Python 标准库，mac/win/linux 尽力采集）：

采集命令：

python3 scripts/environment_snapshot.py --task-name "<任务名称>" \
    --source-framework "Marvis@2.2.0" --target-framework "OpenClaw@1.4" \
    --scan-root ~/WorkBuddy/<项目> --config-file ~/WorkBuddy/<项目>/config.json \
    --out <备份目录>/_environment.json

> 三道防线说明：路径发现只 walk 指定根目录且只登记文件名命中项（不读内容）；模型配置走白名单提取；成品再跑一次自检打码。该文件永远不承载凭据——凭据只走私有包或将由用户在目标端配置。

备份打包清单（v2.2）

<任务名称>_<时间戳>/
├── _index.json / _index_unified.json   # 对话索引（v1 兼容）
├── _manifest.json                      # 逐文件 sha256
├── _environment.json                   # 框架环境快照（v2.2 新增）
├── *_rounds-*.jsonl                    # L1 对话分片
├── memory/                             # L2 项目记忆
├── persona/                            # L4 人格四件（SOUL/IDENTITY/USER/AGENTS）
├── tools/                              # L5 工具与环境（TOOLS.md、skills/、HEARTBEAT.md、config 片段）
├── credentials/                        # 凭据文件（私有备份：随包，恢复即用；隐私副本：剔除）
├── output/                             # 项目产出（选迁）
└── _share/                             # 仅"生成分享包"时出现：脱敏副本
    └── _credentials_needed.md          # 仅隐私副本携带：被脱敏凭据项清单

> 私有包与分享包的区别只有一处：credentials/ 与 _share/。私有迁移不带 _share/、凭据原样在包内；分享场景不带 credentials/、改出 _share/ 与 _credentials_needed.md。

二、隐私脱敏规范（v2.2 重定位：脱敏是可选隐私配件）

原则（v2.2 重写）：默认不脱敏。 私有备份、本机还原、自己换机这类"资料不出自己设备/账号"的场景，原文照搬、凭据随包、恢复即用——脱敏只服务于不想让明文凭据留在备份文件里的场景（隐私副本）。

> 为什么改：v2.1 把"脱敏 + 凭据永不入包 + 生成缺口清单"写成了通用流程，导致纯粹的私人换机备份也要倒腾一遍凭据、还原后还得手工回填——把隐私场景的约束误当成了迁移必经步骤（与 v2.0 的 L4 缺陷同类）。
> 安全边界不变：一旦资料要离开你的私有环境，_share/ 是唯一出口。

脱敏规则（scripts/desensitize.py 实现，v2.2 起必须显式 --share 才执行）：

• <hash4> = 原值 sha256 前 4 位：同一原值 → 同一占位符（可对账），不可逆。
• v2.2.0 修复 F9：apikey / email / openid 三类正则原用 \b 词边界，在中文/全角字符紧邻敏感值时静默失效（Python 3 中 CJK 属 \w，apikey是sk-xxxx 里 sk 前取不到词边界）——现改为负向断言 (?<![A-Za-z0-9])。
• 映射清单 _desensitize_map.json（占位符 ↔ 原值指纹）只留本地，不随隐私副本走。
• 发布 Skill 文档 / 示例 / 截图时一律用虚构值；真实 key、open_id、本机路径不得出现在任何对外产物里。

三、JSONL 数据规范（raw-v1.0 兼容速查）

> 存储层完整、展示层可截断；写盘不改编、不删除任何消息。

四、备份侧 Step 0-6.5（v2.3 修订）

Step 0 运行入口校验（v2.2 新增，不通过不许开工）

迁移事故大多发生在动手之前：框架没对齐、任务名随手起、备份目录落在 agent 安装目录里被卸载连坐。备份第一件事是跑入口校验：

python3 scripts/preflight_check.py --task-name "<任务名称>" \
    --source-framework "<源框架[@版本]>" --target-framework "<目标框架[@版本]>"

• 平台框架：源框架 + 目标框架都要确认（框架名必填，版本尽力提供）；同名（同框架换机）不算错，仅提示。
• 任务名称：缺失即停止并向用户索要，不得自行编造 backup / new / test 之类占位名；名称需 ≤64 字符且不含 <>:"/\|?*。
• 目录落位：备份目录 = ~/Desktop/<任务名称>_<时间戳>/（默认桌面，所见即所得；--backup-root 可改到文档等其他显眼位置），脚本显式打印绝对路径。
• 硬性禁止（命中即拒绝，退出码 3）：不得写入 agent 安装目录 / 数据目录 / 系统保护路径 / skills、node_modules、site-packages 等安装型目录。原因：这些位置会随 agent 卸载或重装被一并删除，"备份"备份了个寂寞。
• 落位被拒时的正确做法：换到用户自己的显眼位置（默认桌面，或文档等其他显眼位置），不要把备份藏进 agent 目录。

Step 0.5 五道确认闸门（v2.3 新增，逐道确认、未全确认不许打包）

> 为什么：部分框架会把所有对话存在同一个库里（不按项目分目录），一旦备份/还原搬错段，事后极难排查是哪一段串了。所以 v2.3 起把关键决策拆成 5 道必须逐道向用户确认的闸门——禁止一次把 5 个问题全抛给用户，也禁止在打包前集中补签。

# 查看五道闸门定义与当前状态（不指定 --backup-dir 时只显示定义）
python3 scripts/confirm_gate.py --list [--backup-dir <备份目录>]

# 随机抽检（G2 的取证动作）：从 rounds-*.jsonl 随机抽 N 轮完整对话
python3 scripts/confirm_gate.py --backup-dir <备份目录> --sample --rounds 3 [--seed 42]

# 逐道落库（一次只落一道；--reset 可把某道打回待确认）
python3 scripts/confirm_gate.py --backup-dir <备份目录> --gate G1 --set --value "<用户确认内容>"

# 打包前校验（Step 6.5 前置）：五道全 confirmed 才放行
python3 scripts/confirm_gate.py --backup-dir <备份目录> --check     # 未全确认 → 退出码 2，拒绝打包

• 记录落在 <备份目录>/_confirm_gates.json，随包走，还原侧可回看"当时确认了什么"。
• 顺序说明：实际执行顺序为 G1 → G3 → G4 → G5 → G2（G2 要等备份完成才有内容可抽检），编号按问题重要性排列。
• Agent 纪律：一次只问一道，用户答一道、落库一道；--value 必须来自用户的实际回复，不得代答。

Step 1-6.5

1. Step 1 定范围：会话级 / 项目级（默认项目级：L1+L2+L4+L5+output+凭据）。
2. Step 2 建目录：用 Step 0 输出的绝对路径建 <任务名称>_<时间戳>/，建前复算一次禁止位置。
3. Step 3 全量导出：逐条写全字段 + raw；源无时间戳则继承上一条并置 ts_inherited。
4. Step 4 切割写盘：每 15 轮一个 {task}_<日期>_rounds-{起}-{止}.jsonl，追加式，永不覆盖。
5. Step 5 双索引：更新 _index.json 与 _index_unified.json。
6. Step 6 校验：validate_jsonl.py 全文件跑通（退出码 0）+ 抽查 ≥3 条一致性。
7. Step 6.4 环境快照（v2.2 新增，v2.3 扩模型字段）：跑 environment_snapshot.py 生成 _environment.json（见 §一），随包落位；--model "<本次所用模型>" 写入顶层 source_model，供闸门 G5 与还原侧对照。
8. Step 6.5 打包：前置条件——五道确认闸门全通过（confirm_gate.py --check 退出码 0，未通过拒绝打包）；随后生成 _manifest.json（逐文件 sha256）；私有场景凭据文件原样入包（credentials/）；仅当用户主动要求分享时另出 _share/ 脱敏副本 + _credentials_needed.md。

五、还原侧 Phase A-E（v2.3 修订）

Phase A 源端自检 + 模式确认 + 环境预读

读 _index.json 获知轮次 / 条数 / 文件清单；有 _manifest.json 先做完整性校验；有 _environment.json 先读框架版本 / 工具 / 系统 / source_model 四项，与目标环境做一次对照；有 _confirm_gates.json 时回看五道闸门的确认轨迹（当时确认的范围 / 落位 / 附件选项 / 模型），据此复现用户原始意图。
确认迁移模式：persona-follow（默认）还是 persona-keep？向用户二选一确认，未答则按默认。

Phase B 转移落地

> ⚠️ 实战坑 ①（沙箱）：目标框架的文件工具常被限制在 workspace 内，读不了外部 backup_root。
> 正确姿势：cp -R 整目录复制进目标工作区，源目录原样保留。

校验先行三步：
1. validate_jsonl.py 跑全部数据文件 → 必须 0 问题；
2. 三方对账：JSONL 实际行数 = _index.total_messages = files[].entries 累加；
3. 有 _manifest.json → 逐文件核对 sha256。

Phase C 全量还原

> ⚠️ 实战坑 ②（排序）：数据文件按文件名里的 rounds 范围排序，不要按 mtime（复制会改 mtime）。
> ⚠️ 实战坑 ③（顺序）：行序即真实对话流。源数据存在轮内毫秒级时间回退，禁止按时间戳重排。

流程：
1. 收集全部 *rounds-*.jsonl，按 rounds 范围升序；
2. 逐行读入，seq 连续性校验（断点记录告警，不中断）；
3. 统计角色分布与轮次连续性（1..max 无缺轮）；
4. raw 字段存在时以 raw 为原文真相源，结构化字段仅作索引展示；
5. 产出可读还原稿 _restored_dialogue.md + 统计报告 _restored_stats.json（v2.2 起自动附带环境快照摘要与补齐提示；v2.3 起含 model_consistency_hint 模型一致性提示）。

> ⚠️ 实战坑 ④（如实还原）：源对话里的"上下文摘要注入轮""API 超时重试痕迹"是当时的原始状态，逐字保留并标注，不算迁移损失。
> ⚠️ 实战坑 ⑤（大文件）：还原稿 2MB+ 属正常，阅读用分片 / 按轮定位。

Phase D 记忆与人格写入（v2.1 修订）

Phase E 工具与环境恢复（v2.1 新增，v2.2 扩环境对照）

1. TOOLS.md → 恢复为 live 工具约定文件；
2. skills/ → 按目标框架的技能目录规范逐个安装；跨框架时先比对格式，不兼容的列清单告知用户；
3. HEARTBEAT.md → 恢复定时任务清单；
4. config / hooks / 权限规则 → 按 _environment.json 的路径清单找回对应文件，按目标框架 config 结构合并，不整文件覆盖；
5. 环境对照补齐（v2.2 新增，v2.3 扩模型一致性）：按 _environment.json 逐项核对——框架版本、tools / tools_missing、OS 差异、模型配置项（模型名/端点），缺口列清单交给用户补齐；source_model 提示：本次备份由该模型完成，恢复时建议使用同一模型（减少语气/行为漂移，闸门 G5）；
6. 凭据交接（v2.2 改）：
   - 私有迁移（默认）→ 包内 credentials/ 恢复即用，无需用户回填；如目标框架要求重新授权，按框架流程逐项确认；
   - 隐私副本场景 → _credentials_needed.md 交给用户，逐项在目标框架配置（Skill 永不代填凭据）。

还原完成验收清单（v2.3 扩至十五项，缺一不可）

> 验收操作提醒：凡涉及 ***xxxx 形态占位符的核对，一律以文件级 / hex 级比对为准——部分平台展示层会对"疑似脱敏痕迹"做二次遮盖，直接看终端输出会误判"脚本丢了哈希"（实测教训，2026-09-15 测评 F8）。

六、故障排查（十六条）

七、配套文件

八、Agent 评估信息块

agent_evaluation:
  deploy_time: "5 分钟以内（纯 Python 标准库，六脚本零第三方依赖）"
  roundtrip: "1418 条迁移还原实测 < 2 分钟；v2.4.0 六脚本 23 组用例全量实测 < 15 秒"
  concrete_values:
    - backup_entry: "preflight_check.py（框架 + 任务名称 + 目录落位，先过闸再动手）"
    - backup_dir: "~/Desktop/<任务名称>_<时间戳>/（默认桌面、显式打印绝对路径；--backup-root 可改）"
    - backup_dir_forbidden: "agent 安装目录 / 数据目录 / 系统保护路径（随卸载连坐删除）"
    - rounds_per_file: 15
    - timezone: "ISO 8601 +08:00"
    - seq: 全局递增，还原保序唯一依据
    - persona_modes: ["follow(默认)", "keep"]
    - desensitize_moment: "仅隐私副本场景（默认不脱敏）"
    - credentials: "私有包随包、恢复即用；隐私副本剔除 + _credentials_needed.md"
    - environment_snapshot: "_environment.json（框架版本/工具/系统/config-paths/模型配置白名单/source_model）"
    - confirm_gates: "G1 备份范围 / G2 内容抽检（随机 3 轮）/ G3 落位 / G4 附件与成果 / G5 模型一致性——逐道确认、逐道落库；打包前 --check 未全确认 rc=2"
  failure_paths:
    - 任务名称缺失就开工 → 停止并索要，勿用 backup/new/test 占位名
    - 备份写进 agent 目录 → 卸载连坐删除；preflight 拦截，默认落位桌面 ~/Desktop/
    - 沙箱读外部路径 → cp 进工作区，源不动
    - 按 mtime/时间戳排序 → 按文件名 rounds + 行序
    - 换机场景沿用 v2.0 的 L4 不覆盖 → 用 v2.1+ persona-follow
    - 只顾倒腾脱敏忘了迁移本身 → 私有迁移默认不脱敏，凭据随包
    - 中文紧邻敏感值脱敏失效 → v2.2.0 负向断言修复（F9）
    - 环境没采/没对照 → Phase A 预读 _environment.json，Phase E 逐项补齐
    - 只还原不写记忆通道 → Phase D/E 缺一即未完成
    - 跳过五道确认闸门直接打包 → 范围没界定、内容没抽检，串项目事后难查；confirm_gate.py --check 硬拦（rc=2）
    - 恢复时换模型 → 语气/行为漂移；按 _environment.json 的 source_model 用同一模型（闸门 G5）
  compat:
    baseline: "raw-conversation-backup v1.0.1 / MindVault v3.1"
    upgrades: ["项目级范围", "五层模型", "人格按模式恢复", "L5 工具层", "框架环境快照", "脱敏降级为隐私配件", "凭据随包恢复即用", "运行入口校验", "备份目录规范（默认桌面）", "_manifest sha256", "五道分步确认闸门", "模型一致性", "验收清单 15 项"]
  v220_fixes:
    - "F9 中文紧邻 \\b 失效 → 负向断言 (?<![A-Za-z0-9])（apikey/email/openid）"
    - "R1 脱敏误置为迁移必经 → 降级为可选隐私配件（--share 闸门，默认拒绝）"
    - "R2 备份范围缺环境 → 新增 _environment.json + environment_snapshot.py"
    - "R3 入口无校验 → 新增 preflight_check.py，任务名缺失停止、禁写 agent 目录"
  v230_changes:
    - "新增 confirm_gate.py：五道分步确认闸门（G1 范围 / G2 抽检 / G3 落位 / G4 附件 / G5 模型），逐道落库、打包 --check 未全确认 rc=2"
    - "备份默认落位桌面 ~/Desktop（显眼位置，用户一眼能找到）"
    - "environment_snapshot.py 增顶层 source_model；restore_dialogue.py 增 model_consistency_hint 提示"
    - "验收清单 14 → 15 项（+五道确认闸门全通过）；故障排查 15 → 16 条"

九、装了之后你能做到什么（功能预览）

> 更多部署详情（各框架版本对照、逐层验证标准、时间与轮次优化）：<https://jinengpu.chat/cross-migration.html>