项目资料跨平台迁移

📦 项目资料跨平台迁移 · Project Cross Migration（免费版 v2.4.2）

备份 → 搬运 → 还原：把一个项目（含 Agent 人格、工具与环境）的全部资料完整搬到新框架 / 新机器。 本 Skill 是 raw-conversation-backup v1.x 的项目级升级版：JSONL schema 完全兼容，范围覆盖项目工作状态全量。

⚠️ 当前为免费版 v2.4.2。以下能力已锁定，需获取完整版解锁：

• 五道分步确认闸门（confirm_gate.py）
• 框架环境快照采集（environment_snapshot.py）
• 分享包脱敏器（desensitize.py）

获取完整版：

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

这个 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 才执行）：

• `` = 原值 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 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 环境快照（完整版）：跑 environment_snapshot.py 生成 _environment.json。> 免费版锁定。
8. Step 6.5 打包（完整版）：前置条件——五道确认闸门全通过。> 免费版锁定。
9. Step 7 脱敏分享包（完整版）：仅当用户主动要求时，跑 desensitize.py --share 生成 _share/ 脱敏副本。> 免费版锁定。

五、还原侧 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）。

六、故障排查（十六条）

七、配套文件

完整版能力简介

免费版提供备份 → 搬运 → 还原的核心流程（L1/L2 备份校验还原），覆盖项目工作状态基础迁移。

完整版解锁以下能力：

• 五道分步确认闸门（G1-G5 逐道确认 + 随机抽检 + 打包前置校验）
• 框架环境快照采集（生成 _environment.json，含框架版本 / 工具 / OS / 模型配置）
• 分享包脱敏器（--share 模式，生成脱敏副本 + 本地映射清单）
• 完整验收清单 15 项、故障排查 16 条全量覆盖

获取完整版：