AI 工作空间搬家术

把一个「用久了、堆乱了」的 AI 工作台，拆成职责清晰的多空间架构，并把记忆、人设、技能一起搬过去——全程可验证、可回滚、不丢件。

〇、先搞清楚：搬家搬的是四样东西

很多人以为搬家=挪文件夹。不是。AI 工作台的搬家有四层，漏掉任何一层都会"搬完更乱"：

这个技能的价值就在后三层。

一、五条铁律（违反任何一条，立即停手）

铁律 1｜盘符写权限矩阵，开工前先定

搬家前必须与用户确认：哪些盘可写可删、哪些盘只读引用。写成矩阵贴在方案首页。

示例：
  C盘 / D盘  → 可写可删（工作区）
  E盘 及以后 → 只读引用（原始资料源，任何情况不改不删）

> 只读盘只以绝对路径只读打开，不复制、不改名、不清理。用户说"别动那两个盘"就是红线，不是建议。

铁律 2｜删除前必须过 MD5 全量差集

只有 S − T − E == ∅ 才允许删除。

• S = 源目录全部文件的 MD5 集合
• T = 目标（新家）全部文件的 MD5 集合
• E = 已知豁免集（如刻意修订过的文件）

用集合差集而不是逐文件比对，是因为它天然消化三种变形：去重（源里两份相同、目标只留一份）、改名（内容不变换个名）、分流（源一个目录拆到目标多个目录）。逐文件路径比对遇到这三种会疯狂误报。

⚠️ 备份区绝不能算进 T——否则等于"拿备份验备份"，验了也白验。

铁律 3｜删目录前，必先移除空间登记

顺序不可颠倒：

移除客户端空间登记  →  再删磁盘目录

反过来做，注册表里会留下指向不存在路径的死登记：列表里一个灰项，点不开、删不掉、每次启动都尝试加载。

铁律 4｜空间的增 / 删只走客户端界面，禁止脚本直改数据库

客户端的空间注册表通常是 SQLite。可以只读查询用于核对，绝不可写。原因：跨版本表结构可能变、可能有外键与缓存视图、客户端运行时持锁写回会覆盖你的修改。

> 界面看到的列表 ≠ 数据库里的记录。界面可能只显示"最近打开"，删掉的只是显示。核对必须查库，处置必须走界面。

铁律 5｜不直接删，先进暂存区

所有"要删的"统一 move 进 _待删_YYYYMMDD\，观察 7–14 天再清空。全量备份区独立存放，观察期内不动。

> 这条改自"绝不删除"原则。实践中"只增不删"会留下一堆半死不活的旧目录，用户下次还得再纠结一次。"删，但可回滚" 比"不删"更负责任。

二、七阶段执行流程

> 阶段 0–4、6–7 由 AI 执行；阶段 5 必须由用户在客户端手动完成（受铁律 4 约束）。

阶段 0｜诊断：先摸清家底

产出《当前空间状态诊断报告》，必须包含：

1. 空间清单：名称、绝对路径、最后打开时间、文件数、占用体积
2. 活跃度分档：活跃 / 半闲置 / 已废弃（按最后修改时间 + 记忆文件更新频率）
3. 记忆密度：各空间 MEMORY.md 字节数、章节数、最后修改时间
4. 人设现状评估：三文件是否绑死单一业务？是否含已失效的路径引用？
5. 混乱症状定位（逐条列，不要笼统说"很乱"）：
   - 职责重叠：同类内容散在几个空间
   - 边界模糊：某空间同时装工作与私人内容
   - 空壳空间：只有 .workbuddy 无实质内容
   - 死引用：文档/脚本里硬编码了将要废弃的路径
   - 技能冗余：功能重复或已被取代的 skill
6. 建议整理方向

> 🔧 用 scripts/diagnose_workspaces.py 自动生成初稿，再人工补充症状判断。

阶段 1｜设计：先画图，再动手

产出《目标空间架构设计文档》，必须定死：

1）划分逻辑——三选一，不要混着来：
- 按业务领域分（推荐：本职工作 / 副业 / 学习 / 私人）
- 按项目分（适合项目制、生命周期明确）
- 按周期分（适合内容生产、按期归档）

2）目录骨架——各空间内部用统一编号前缀，让排序即优先级：

00-设定   01-<主线>   02-<素材>   03-<底稿>
04-<模板>  08-发布包   09-临时

3）每个空间四条边界（缺一不可）：

4）旧对象处置总表——把每一个旧目录/旧空间列成一行，标明：保留 / 迁移 / 归档 / 删除，以及去向的绝对路径。这张表是后续所有操作的唯一依据。

⚠️ 设计阶段必须与用户逐条确认后再动手。 架构一旦落地再返工，成本是设计阶段的十倍。

阶段 2｜全量备份

备份到  D:\_重构备份_YYYYMMDD\   （或用户指定的可写盘）

• 整树复制所有将被动到的源目录
• 记录：文件数、总体积、备份完成时间
• 备份完成前，禁止执行任何删除或移动

阶段 3｜建骨架 + 迁移 + 校验

1. 按设计文档建立新空间目录骨架（含所有编号子目录）
2. 整树复制源→目标（复制，不是移动；源保持原样直到验收通过）
3. 大文件 MD5 逐个校验（>10MB 的文件单独列表核验）
4. 全量 MD5 差集核验：S − T == ∅
5. 产出《迁移核对报告》，差集非空则逐条追查，不允许"应该没问题"式放行

> 🔧 用 scripts/verify_migration.py 一键完成 4、5 步。

阶段 4｜人设 + 记忆 + 技能三件套整合

这是搬家里技术含量最高的一步，也是最容易被跳过的一步。

4.1 人设三文件中性化

搬家前的人设往往绑死在某一个业务上（例如整份 SOUL 都在讲某个具体项目的红线）。多空间架构下这会导致人格错位——在"私人空间"里 AI 还在念工作场景的合规条款。

处理原则：

操作前三文件各存 .bak_YYYYMMDD。

4.2 记忆三层重组

判定口诀：
- 三个空间都要用 → 用户级
- 一个领域反复用、内容大 → 做成 skill
- 只有这个空间用 → 空间级

空间级 MEMORY 精简法：把大块领域知识抽成 skill，空间 MEMORY 只留"空间专属内容 + 指向 skill 的一行索引"。原版留一份 _旧版快照_YYYYMMDD 备查。

4.3 技能瘦身四动作（顺序不能乱）

① 合并同类   →  ② 抢救专属内容  →  ③ 新建拆分出的 skill  →  ④ 最后才删/移

• ① 合并：功能重叠的 skill，先 diff 再手工归并，逐节确认没有内容只存在于被合并方
• ② 抢救：要删的 skill 里若含用户专属案例/数据，先另存到对应空间，再删
• ③ 新建：把 4.1 从人设抽走的业务条款、4.2 从空间 MEMORY 抽出的领域知识，落成新 skill
• ④ 删/移：必须放最后。前三步任一环节可能还要从旧 skill 里取内容

> ❗ 顺序颠倒的典型事故：先删了旧 skill，才发现合并时漏掉了它独有的一节。

4.4 死引用清理

全局搜索即将废弃的路径字符串，分类处理，不要无脑批量替换：

> 🔧 用 scripts/scan_deadrefs.py 扫描并自动分类。

阶段 5｜空间登记（必须用户手动）

受铁律 4 约束，此阶段 AI 只能出操作单，不能代劳。

给用户的操作单要写清三件事：

1. 添加新空间：客户端 →「添加工作空间」→ 选择已存在的本地文件夹 → 打开一次让其初始化
   > ⚠️ 说清楚：这是"添加工作空间"，不是"新建任务"。二者入口相近，极易搞混。
2. 移除旧登记：在空间列表里对旧空间选「移除工作空间」——只取消登记，不删文件
3. 保留当前对话所在的空间到最后
   > 如果搬家过程本身在某个旧空间里进行，先删它会导致对话失联。必须留到全部验收通过后，最后一步再处理。

用户操作完后，AI 必须查库核对——界面上"看不见"常常只是最近列表过滤，登记可能还在。

阶段 6｜旧空间退役

移除登记（阶段5）  →  MD5 差集核对  →  出《删除前核对报告》
      →  用户放行  →  move 进 _待删_YYYYMMDD\  →  观察期后清空

《删除前核对报告》必须列出：源文件数、目标文件数、差集条目（逐条列路径+大小+MD5前8位）、每条差集的判定结论（良性/需追查）。

> 差集"良性"的唯一合法情形：目标版本是源版本的严格超集（只增不减）。必须用 diff 逐行验证后写明，不能凭印象放行。

阶段 7｜验收

逐项打钩，一项不过就不算完（详见 references/执行检查单.md）：

• [ ] 只读盘完好，一个字节没动
• [ ] 空间数 = 设计数，无多无少
• [ ] MD5 实质差集 = 0
• [ ] 旧目录已清零或已进暂存区
• [ ] 无死登记（查库核对，不看界面）
• [ ] 各空间记忆文件存在且内容正确
• [ ] 人设三文件已中性化，各有 .bak
• [ ] 活跃 skill 清单符合预期，冗余已清
• [ ] 死引用已清理或已立说明
• [ ] 用户级 MEMORY 未超字数，且含废弃路径声明

验收提问法（在各空间里实际问一遍）：
- 主空间："根据你现在的记忆，我是谁？我的核心边界是什么？"
- 子空间："你的职责范围是什么？你能调用哪些 skill？"

三、九个必踩的坑（血泪清单）

> 完整版见 references/避坑清单.md（共 15 条），这里列最致命的九条。

1｜界面 ≠ 数据库。 用户说"删好了"，很可能只是最近列表隐藏了。必须查库核对，别信截图，也别信"应该删了"。

2｜删目录 ≠ 删空间。 移除空间登记不会删文件；删了文件也不会移除登记。两件事，两个动作，有先后。

3｜"添加工作空间"不是"新建任务"。 引导用户时把入口、按钮文字、下一步都写死，别用"你去建一个空间"这种话。

4｜安全删除拦截器 + 类 Unix 路径 = 静默失败。 在 Windows 上，rm -rf /c/Users/... 可能被拦截器原样转交给 Windows 工具，退化成无效路径而失败，且报错极具误导性（看起来像权限或进程锁）。
> 解法：改用 PowerShell 传标准路径 C:\Users\...，一次就过。
> 教训：报错说"Permission denied"不代表真是权限问题，先验证路径格式。

5｜"进程锁"经常是误判。 遇到删不掉先别归因于锁，按顺序排查：① 路径格式 ② 工具链拦截 ③ 才是真锁。

6｜看不到图就直说，不许脑补。 若系统提示图片不可读，必须明说"我看不到，请用文字描述"。
> 真实事故：在看不到截图的情况下"复述"了截图内容，虚构出一个根本不存在的空间名，用户还善意地帮它编来历，白费一整轮。

7｜合并 skill 前先 diff，删 skill 放最后。 见 4.3。

8｜历史脚本里的路径别批量替换。 见 4.4。

9｜记忆/日志只能尾部追加，禁止整体覆盖。 搬家期间多会话并发，另一个会话的一次"覆盖式写入"就能把你几 KB 的过程记录静默抹成几百字节，且无副本可寻。
> 配套保险：关键结论不要只存在日志里——同步落到独立报告文件（《核对报告》《验收单》）和用户级记忆，这些不会被日常会话触碰。

四、交付物清单（六份报告）

模板见 references/报告模板.md。

五、脚本用法

三个脚本均为只读分析 / 生成报告，不执行删除，可放心运行。

# 阶段0：诊断（扫描空间、统计记忆、输出诊断报告）
python scripts/diagnose_workspaces.py --roots "D:\空间根目录" "C:\Users\<用户>\WorkBuddy" --out 诊断报告.md

# 阶段3/6：MD5 全量差集核验（备份区自动排除）
python scripts/verify_migration.py --src "D:\旧空间A" "D:\旧空间B" --dst "D:\新空间根" --exclude "D:\_重构备份_20260802" --out 核对报告.md

# 阶段4.4：死引用扫描（自动区分活文档 / 历史脚本）
python scripts/scan_deadrefs.py --scan "D:\新空间根" --dead "D:\旧路径" --out 死引用清单.md

六、给执行者的三句话

1. 凡是"应该没问题"，就是还没验。 用 MD5，别用直觉。
2. 凡是要删的，先想清楚怎么捞回来。 备份区 + 暂存区 + 观察期，三道保险。
3. 凡是用户手动的环节，写操作单要写到"点哪个按钮"。 说清楚一次，胜过来回三轮。

更新日志

• v1.0.0（2026-08-02）：首版。基于一次完整的四空间重构实战沉淀，覆盖诊断→设计→备份→迁移→整合→登记→退役→验收全链路，含 15 条实战避坑、6 份报告模板、3 个自动化脚本（均已实测通过）。