> 作者 @zzzzzzzp（立意 · 判据 · 取舍）　·　协作 多多 · AI 助手（检索 · 编码 · 核查）
> 版权 著作权归 @zzzzzzzp 所有（All Rights Reserved）　·　版本 v1.4.0

万象-文件整理与去重

把乱掉的文件夹盘清楚、按编号归档、挑出重复、隔离待删，全程不擅自删除。

• 做什么：只读扫描建台账、按编号归档、重复识别、隔离待删区、安全迁移。
• 何时用：要扫描整理目录、给文件建编号台账、清理重复文件或做回收溯源时。
• 不做什么：不替你做删除决定；不碰别处的文件与系统目录。

数据边界与外部连接（必读）

• 文档处理全在本机：所有读写只发生在你显式指定的文件上。
• 不采集、不上传用户的任何内容；不扫描目录、不常驻后台、不联网轮询。
• 唯一的外部连接：技能自带的按量付费组件（a2m/）会与支付宝发生支付校验与履约回执，
  该链路只传订单号与金额，不含你的文件内容；本地服务仅监听 127.0.0.1。
• 凭据：作服务端使用时，商户私钥从你的本机环境变量读取，不落盘、不进包。
• 回流组件默认未启用：包内不含任何收件地址，也不自动注册任何钩子；是否启用完全由你决定。

三条共用红线（三篇都成立，先记这三条）

1. 先扫描、后动手。 第一轮只做只读扫描 + 台账，不移动、不删除。批量操作脚本默认 dry-run，
   加 --confirm 才执行。
2. 绝不硬删。 疑似垃圾先移入 待删除区/，等用户人工确认。真删除要走 A 篇 A8 的
   「跨盘快照 → 物理删除 → 五项复核」三步，顺序不可颠倒。
3. 中文 / 空格路径一律用 Python 处理，不用 bash（本机 bash coreutils 会乱码失败）。

> 本机自用版：正文保留了本机路径（~\...）与历史项目关键词，
> 因为 A 篇的事故复盘与 C 篇的模板路径改了就不再可复现。
> 对外分发前必须出脱敏公开版：本机路径换成占位符、项目名换成虚拟名。
> 已按 万象-技能打包与库治理 §C4.3 在 drop 备注里记账。

脚本总览（全部零依赖，纯 Python 标准库 + openpyxl）

调用约定：python "<skill目录>/scripts/<脚本名>.py" ...

A 篇 · 分类整理（扫描 → 台账 → 隔离 → 真删除）

> 宿主篇。A 篇章节名沿用源技能原文，便于与归档副本逐字比对。

A0 适用场景

用户要整理某个文件夹（如下载目录、百度网盘下载、项目资料盘）里的全部内容，要求：
- 分类整理 / 编号归类：按项目、按类型（方案/初设/施工图/变更…）归并
- 清理垃圾：重复副本、网盘中断下载碎片（UUID_xxx）、.bak/.lnk 临时文件、无关文件
- 形成可复用方法：把这次的整理逻辑沉淀下来

A1 核心原则（红线，始终遵守）

1. 先扫描、后动手：第一轮只做只读扫描 + 台账，绝不移动/删除。
2. 删除必须谨慎：疑似垃圾先移入 待删除区/ 隔离，等用户人工确认，绝不直接删除（用户长期习惯）。
3. 移动用 os.replace（同卷 rename），不用 shutil.move。原因：本机环境会把 shutil.move 拦截成「safe-delete → 回收站」，回收站不可用时失败即停（部分版本会静默丢文件）。os.replace 是底层 rename，绕过该拦截，且更快。跨卷时回退 shutil.move。
4. 任何批量移动都要用户明确确认；脚本默认 dry-run，加 --confirm 才执行。
5. 同名避让（长路径是天坑！）：目标已存在同名 → 加 _2/_3，绝覆盖。
   - ⚠️ safe_name() 的存在性检查必须用 \\?\ 长路径前缀（longpath()）。否则路径 >240 字符时 os.path.exists 返回 False，脚本误判「不存在」→ 返回裸名 → os.replace 直接覆盖并删除同名文件！这是实打实的数据事故（见下「事故复盘」）。
   - os.replace 本身遇到已存在目标会替换(删旧)，所以 safe_name 必须保证目标名全局唯一，且检查走长路径。

A2 一键用法

脚本与本 SKILL.md 同目录，可直接跨电脑复用。

第 1 步：只读扫描 → 台账（安全，可随时跑）

python "<skill目录>/scripts/organize_scan.py" "F:/<下载目录>"
# 或指定输出：organize_scan.py "<目录>" out.xlsx

输出 分类整理台账.xlsx，含 5 个 Sheet：
- 01_编号台账：全量文件（序号｜目录｜路径｜项目｜类型｜大小｜版本｜重复标记｜操作建议）
- 02_按项目统计 / 03_按类型统计：分布概览
- 04_待处理(无关-重复)：待删除区候选清单
- 05_操作建议汇总：保留 / 待删除区 数量

第 2 步：看台账，确认范围

把 05_操作建议汇总 念给用户：多少保留、多少重复副本、多少网盘碎片/临时/无关。
务必先确认再动文件，向用户给出选项（见下「确认话术」）。

第 3 步：执行（dry-run 先预览，再 --confirm）

# 预览：把待删除区候选隔离到 <root>/待删除区/
python "<skill目录>/scripts/organize_apply.py" 分类整理台账.xlsx --root "F:/<下载目录>" --mode isolate
# 确认执行：
python "<skill目录>/scripts/organize_apply.py" 分类整理台账.xlsx --root "F:/<下载目录>" --mode isolate --confirm

# 预览：把保留文件按「项目/类型编号」整理进 <root>/已整理/
python "<skill目录>/scripts/organize_apply.py" 分类整理台账.xlsx --root "F:/<下载目录>" --mode reorg
# 确认执行：... --mode reorg --confirm

执行会写 移动日志.txt（每行 源\t目标），方便回滚核查。

A3 方法详解

1. 分类维度

• 项目：从「文件名 + 父目录名」匹配关键词（如 云澜→云澜山庄）。PROJECT_RULES 顺序敏感，特异性高的放前面。
  > 真实项目名单不在技能包内——放 ~/.workbuddy/omni-project-rules.json（可由 OMNI_PROJECT_RULES 指向别处）；包内只有虚拟示例。
• 类型/阶段：TYPE_RULES 匹配（竣工 > 变更 > 初设 > 方案 > 施工图 > 模型 > 效果图 > 苗木 > 海绵 > 图框 > 估算 > 评审 > 意向 > 素材 > 无关）。扩展名兜底（.skp→模型、.dwg→CAD）。

2. 编号约定（沿用用户习惯）

• 项目内用 00-/01-/02-… 前缀按类型顺序编号（见文件现有命名已如此）。
• 物理整理目标结构：<root>/已整理/<项目编号>-<项目名>/<类型编号>-<类型名>/。
• 项目编号见私有配置 omni-project-rules.json 的 project_code（外置，见上），类型编号见 TYPE_CODE，按需增删。

3. 重复 / 垃圾识别

• 重复副本：归一化文件名（去 (1)/(2)/副本）+ 相同字节大小 分组；同组保留 1 个主件（优先非 .bak、非 UUID、非数字副本、文件名最短），其余建议移入待删除区。
• 注意：CAD 的 .bak 等同 .dwg 字节副本，会被判为重复，可安全隔离。
• 网盘碎片：百度网盘中断下载残留，特征 UUID_原名 或 原名.短十六进制（如 .0be/.913）→ 待删除区。
• 临时文件：.lnk、.bak → 待删除区。
• 无关文件：语文/练习/试题、软件破解、素材站 ID_xxxx 编号 → 待删除区，人工复核。

4. 自定义规则

打开 organize_scan.py 顶部 PROJECT_RULES / TYPE_RULES：改成你自己的项目名与类型词即可，其余逻辑不用动。

A4 确认话术（动文件前必问）

> 台账已生成。共 N 个文件，其中约 X 个建议隔离（重复副本 a + 网盘碎片 b + 临时 c + 无关 d），Y 个保留。
> 你想怎么处理？
> - A. 仅用台账做目录，不移动任何文件（最安全）
> - B. 把待删除区候选隔离到 待删除区/（可恢复，不硬删）← 推荐先做这步
> - C. 在 B 基础上，把保留文件按「项目/类型编号」整理进新文件夹（改动较大，需逐步确认）

A5 反模式（别这么干）

• ❌ 上来就 mv/rm 批量移动或删除。
• ❌ 用 bash 处理中文/空格路径（易乱码失败）→ 用 Python shutil。
• ❌ 直接 os.remove 任何用户文件。
• ❌ 不预览就执行 → 永远先 dry-run。

A6 事故复盘（2026-08-26，网盘下载盘 实景）

首次实战即踩坑，记录以防再犯：
1. shutil.move 被环境拦截：本机把 shutil.move 钩成 safe-delete（送回收站），回收站不可用时失败即停。部分同名文件因此「消失」（拦截层在不可用时未必温柔）。→ 改用 os.replace。
2. safe_name 长路径 bug 导致覆盖删文件：safe_name 当初用非前缀路径做 os.path.exists 检查，路径 >240 字符时返回 False → 误判目标不存在 → 返回裸名 → os.replace 把同名旧文件替换删除。后果：同一目录下多个同名图纸（如 5 个 某某项目BASE.dwg）只活下来 1 个，其余被覆盖。
3. reorg 中途崩溃 + 对账困难：--confirm 跑 reorg 时在写日志前崩溃（退出码 1），导致只移走 2447/4133，且重复名文件被错放到别的「项目/类型」目录。后续用「目录+stem」对账才能区分「真正丢失」与「错位」。
4. 对账方法（务必会）：别信「目录文件数相减」的粗略差（会被同名碰撞掩盖）。正确做法是建 (目标目录, stem) 桶，逐条台账 1:1 消耗匹配；stem 用 re.sub(r"_\d+$","",base) 去 _2/_3 后缀。脚本见工作区 match_lost.py。
5. 教训：① 跑大规模 reorg 前，务必先在小样本验证 safe_name 长路径路径；② 每批移动后立刻跑对账脚本核总数；③ 用户文件一旦疑似丢失，立刻停手、出清单、问用户，绝不擅自继续「补救式移动」。

A7 事故复盘 2（2026-08-27，真实项目盘 实景）——提权模式 + os.rmdir 触发拦截层误删

整理该项目时二次对齐目录结构，脚本在提权（Sandbox bypassed，无沙箱）模式下运行，safe-delete 拦截层把 00_待确认区 整个目录（含 369MB rar）误送进回收站，区内其余 8 个文件被散落到无关目录（04_参考资料/03_素材库）。脚本 stdout 还显示假象（打印「跳过/源不存在」，实际已执行移动）。
1. 拦截层只在提权/无沙箱模式活跃：普通沙箱内 os.replace 正常（第一次 reorg 全程无事故）；一旦脚本因权限被提权运行，safe-delete 拦截层接管，os.rmdir/os.replace 会被升级为「整树 + 邻近目录递归送回收站」。
2. 删除目录是大坑：os.rmdir 删旧结构目录时，拦截层把同级的未删除目标（00_待确认区）也卷进回收站。→ 删除逻辑里绝不允许出现「删除 A 时 B 可能被误伤」的结构；目标目录与操作目录必须物理隔离。
3. 排查：文件疑似丢失先查回收站 $I 索引（格式：8字节头 + 8字节文件大小 + 8字节删除时间 + 4字节路径长度 + UTF-16LE 原路径），解析原名定位；$R* 为数据文件。F 盘回收站在 F:\$RECYCLE.BIN\<SID>\。
4. 修复：shutil.copy2 从回收站恢复（保留回收站原件做双保险），os.replace 移回散落文件，全部就位。
5. 教训：① 批量移动/删除脚本禁止在提权/无沙箱模式运行，除非确认拦截层行为；② 涉及 os.rmdir 时先确认目录为空且独立，任何未确认目录（如 待确认区）必须先行移出操作范围；③ 关键文件区操作前先做副本；④ stdout 输出不可全信，以实际文件系统状态为准（移动日志为准）；⑤ 发生异常立即停手、查回收站、出清单。

A8 第 4 步：真删除（用户确认后）——待删除区只是隔离，不是删除

4.0 去重前的判定：不算「正本存在」，要算「逐文件零差异」

面对「A 是 B 的快照副本，B 还在，所以 A 可删」这类判断，别用目录名推断，也别只用「正本存在」当依据。
正本存在只说明有原件，不说明快照没夹带正本已删掉的内容（快照可能是某个中间状态）。

正确判据 —— 逐文件 sha256 建索引再比对，要求四项同时成立才可删：

实测反例（2026-09-19 归档区）：10 个 -HHMMSS 快照全部「相同=全部、差异 0、独有 0」→ 判为纯冗余，删除；
而另一个 _registry_backup_local_20260918-194916 无正本 → 永久保留，绝不参与去重。

用户看过清单并明确确认后，若要真正腾空间，按下面走。顺序不可颠倒。

先选路（先探通道，别假设）

→ 与核心原则 3 的 shutil.move 拦截同源：自动化环境里「送回收站」随时可能不可用。
→ 降级路线 = 永久删除 + 删前跨盘快照。绝不在无快照的情况下 rmtree，也不许静默降级成裸删。

三步

① 删前快照（必须跨盘）
zipfile.ZipFile(..., ZIP_DEFLATED) 把待删内容完整打包 + 落一份逐文件 sha256 清单（相对路径｜字节数｜sha256）。
- ⚠️ 快照必须落在另一个盘（C: → D:）。同盘快照在整盘事故下等于没有。
- 自检门槛：z.testzip() is None 且 zip 条数 == 清单条数。这一步不过就不许往下走。

② 物理删除
shutil.rmtree(p, onerror=...)，onerror 里先 os.chmod(path, stat.S_IWRITE) 再重试 —— 只读文件会让 rmtree 半途而废。
逐个目录删、逐个打印「释放 X MB / N 文件」。不要一次性 rmtree 整个父目录，否则日志说不清删了谁。

③ 删后五项复核（缺一不可）
1. 目标目录确已不存在（逐个 assert，不靠"命令没报错"）
2. 正式副本仍在 —— 「没误伤」的核心举证。若删的是重复副本，必须逐条确认正本目录还在
3. 无正本项未碰 —— 清单里凡「没有正本」的条目一律不删
4. 父目录计数 —— 如 84 → 83，一眼看出父目录也清理了
5. sha256 抽查 —— 从 zip 里随机取 3 个文件重算并与清单比对，证明「真能还原」，而不只是「文件还在」

交回用户必须包含三件事

删了什么（逐条路径 + 体量）／怎么还原（zip 路径，解压即得）／回收站为什么没用（环境事实，不是你省事）。

4.1 特例：若待删的是「已迁移的旧副本」，哈希全等即是放行凭据

上面 4.0 与三步针对的是「删了无法找回」的场景，故须跨盘快照兜底。但若删除对象已有等价正式副本落在别处
（典型：项目整体迁移后留下的旧位置），那么最硬的凭据不是「能还原」，而是「根本不需要还原」——

删前逐文件 sha256 比对「待删副本 vs 目标位」，四项归零才动手：
相同 = 副本文件数｜内容不同 = 0｜副本独有 = 0｜目标独有 = 0。

此时不必再打 zip 快照：多一层反而让人误以为可逆性来自快照，而真相是可逆性来自目标位。
但校验输出必须留档，交回用户时说清三件事：删的是什么、凭什么敢删、若要复原从哪来。

> 实测（2026-09-19 · 万象标识体系迁移）：旧副本 167 个文件（84 ＋ 83 ＋ 说明 ＋ 3 脚本），
> 四项全零后 shutil.rmtree。「先入待删除区 → 人工确认 → 真删除」流程首度完整走通。

4.2 删改脚本一律自带幂等护栏

本机 Bash 返回 Sandbox bypassed (escalation-approved) 时，同一条命令可能被执行两次（用户确认触发重跑）。
open(p,'a') 追加、lines.insert() 插入这类非幂等写入，第二次执行会静默写入重复内容。

三选一，必选其一：
1. 先查标记再写 —— 读入全文，唯一标记串（如小节标题）已存在即跳过；
2. 改用 Edit 定点插入/替换 —— 天然幂等，匹配不到就失败，绝不会重复加；
3. 整体重写而非追加 —— 读全文 → 内存里改 → 一次性 'w' 写回，内容由数据结构决定，不累积。

> 实测代价（2026-09-19）：一条「追加日志 ＋ 补一条记忆」的脚本被重跑 →
> 用户级 MEMORY.md 多出一条、两份项目日志各多出一整块。
> 写完必须回读计数自检（s.count('小节标题') 应为 1），不能只信脚本打印的「已追加」。

4.3 删「工作区 / 迁移工具包」类目录：判据在库里，不在文件名

触发场景：<工作区>\<时间戳>\ 这类工作区目录，或 _move_to_xxx_<日期>\ 这类一次性迁移工具包。
它们名字像临时件，但绝不能按名字或时间戳批量清 —— 用户工作区多数仍有会话挂在上面，删了记录就断。

三条判据，全过才删（顺序即检查顺序）：

1. 库里查会话指向数，必须为 0。 库在 ~\.workbuddy\workbuddy.db，应用运行时被占用，
   用只读 URI 打开：
   python con = sqlite3.connect('file:~/.workbuddy/workbuddy.db?mode=ro', uri=True) cur.execute('select count(*) from sessions where cwd like ?', ('%'+目录名+'%',))
   （cwd 就是侧栏「空间」分组的归属键。）
2. 无独有数据。 工具包里通常带备份快照（workbuddy.db 全库快照、会话 *.jsonl 副本）。
   逐项与现库比对：现库路径为 ~\.workbuddy\projects\<工作区>\。
   若快照是现库的旧版子集、hash 相同者逐字节相同 ⇒ 零损失；若备份里有现库没有的东西 ⇒ 停手。
3. 该工具包的使命已落地。 迁移工具包的唯一价值是「回滚」，所以删它之前必须验证那次迁移本身成功：
   查 sessions.cwd 是否已指向新工作区、迁移脚本同时改的其它字段（如 is_playground，临时任务标志，
   为 1 时任务不出现在「空间」分组）是否已生效。迁移没验证就删工具包 = 自断退路。

留档：删前把清单（relpath / bytes / sha256[:16]）打印出来随脚本输出留档，交回用户时说清三件事。

> 实测（2026-09-19 · 清除 _move_to_fengshui_20260918，14 文件 / 6.76 MB）：
> 判据 ① 会话指向 0；判据 ② 备份 a7ce250a.jsonl 2,038,925 B 是现库 2,370,768 B 的旧版子集、
> 两份 subagent jsonl 与现库 hash 逐字节相同；判据 ③ 迁移已落地（cwd 已改、is_playground 1→0）。
> 三条全过 → 直接 rmtree，零损失。
>
> ⚠️ 两条教训：① 报体量前先量，别凭印象 —— 我一度向用户报「几十 KB」，实为 6.76 MB（含 3.5 MB 库快照）。
> ② 别被工具包 README 的语气挡住判断 —— 它写着「本工具不会删除任何文件」，那是说它运行时不删，
> 与「这个工具包自己该不该删」是两回事。

4.4 会话归属迁移：客户端没有入口，只能改库 + 同步搬「记录槽位」

触发场景：用户说「显示还没移动过去」—— 项目文件搬完了，但侧栏里那段会话仍挂在旧分组下。

归属键只有一个：sessions.cwd。 侧栏按它分组；workspace-display-names.json 只管显示名
（key = 小写正斜杠路径），workspaces 表只有 path + last_opened_at —— 都不是分组依据。

要同步改两处，缺一不可：

转写规则 = 盘符去冒号 + 反斜杠转横线 + 全小写：<工作区>\X → <盘符>-<路径转写>-X。
只改 ① 不改 ② → 侧栏换了分组，但历史读不到（看着像空会话）。

不要去别处找入口（2026-09-19 实测确认，省得再翻一遍 284 MB 的包）：
- session:move / moveSession 的源码注释原文：「将 Playground 会话转换为普通会话（从 Playground 移动到 Workspace）」
- 界面串 conversation.creating.edit.button.workspace（"移动到工作区"）只在 effectiveIsPlayground 为真时渲染

⇒ 正式工作区会话（is_playground = 0）没有改挂空间的原生入口，只能手工改库。

⚠️ 最硬的一条约束：不能在运行中改。
会话记录的 .jsonl 那时正被进程打开写入（实测本会话 20 MB、status = working）。
热改要么被 Windows 文件锁拦住（半途而废：库已改、记录没搬 → 历史像丢了），
要么搬成了、进程却继续往旧路径写 → 历史从改动点截断。必须 WorkBuddy 完全退出后改。

> 该能力已于 2026-09-23 迁至 omni-context-relay（万象-会话交接与任务迁移）B 线 ——
> 权威说明、脚本（omni-context-relay/scripts/task_relocate.py）、判定与回滚机制都在那边，本节不再重复
> （避免同一事实在两处各写一份、改的时候只改一处）。
>
> 本节只留判断用的最小事实：归属键 = sessions.cwd（侧栏按它分组）；必须与 projects
> 记录槽位同步改；只能在客户端完全退出后改（记录文件正被进程写入）。
> 触发信号：用户说「显示还没移动过去」。
> 详见 → omni-context-relay/SKILL.md 的「B 线 · 任务位置迁移」。

旧包仍可用（换常量法；session_move.py 顶部 SID / TITLE / OLD_CWD / NEW_CWD / OLD_SLOT / NEW_SLOT）：

• <目标工作区>\_会话迁移_<迁移名>_<日期>\ —— 推荐用这份（随目标工作区存放；包内含 01_MIGRATE.bat / 02_ROLLBACK.bat / 03_CHECK.bat）
• 已有三包：技能库自进化包、罗盘包（会话迁移留档目录下的「会话迁移_20260919」）、深业翠微谷包

两个 bat 走 %~dp0 取同目录脚本，故整包可任意搬位置；换会话时不要把旧包的 state.json 与 backup\ 带过来
（那是上一段的回滚快照，会污染 rollback 语义）。

旧包只改常量是不够的 —— 第三次迁移（2026-09-19 · 深业翠微谷）补入的四处必修

前两次的包都是「同一脚本换三个常量」，第三次发现三常量改完仍会迁错。复用旧包时必须补齐：

1. is_playground 必须一起改（1 → 0）。 它的含义是「Playground 临时会话」，
   为 1 时不进侧栏「空间」分组。所以「cwd 改了却还在别处/不进分组」的会话，
   往往就是漏了这一列。state.json 要记下原值，rollback 一并还原。
   > 查法：select cwd, is_playground, deleted_at, status from sessions where id=?
2. 会话私有子目录必须一起搬。 记录槽位里除三个文件（.jsonl / .meta.json / .file-rollback.ndjson）
   外，还有以会话 id 命名的目录（实测 <SID>\tool-results\*.txt，即工具结果缓存）。
   旧包 FILES 只列三个文件 → 会漏掉，新位置读不到工具结果。
   改法：清单改为「三个文件 + <SID>\ 全树」，逐文件 sha256。
3. 移动用 os.replace，不用 shutil.move（与 A1 第 3 条同源：本机把 shutil.move 钩成「送回收站」，
   回收站不可用时失败即停）。目标已存在同名文件则拒绝覆盖并报冲突，不擅自动手。
4. 交付物与本会话日日志要一起 relocate 到目标工作区 —— 见下方配套第 2 条；
   报告类产物放目标工作区根目录（与同类报告同级）更合用户习惯，不必套「留档子目录」。

迁移前先做的四件配套（2026-09-19 第二次补 1~3、第三次补第 4 条，漏了会出问题）：

1. 任务记忆要提前复制到新工作区 —— 定时任务/后台会话的记忆在 <会话工作区>\.workbuddy\memory\automations\<自动化id>\memory.md，
   会话迁走后按新工作区读。不复制 = 任务失忆（既不知道上次跑到哪，也不知道防重复）。
   同时在 automation.cwds 指向的目录内再备一份（两条路径理论并存，成本低）。
   > 第三次实测：查 automations.cwds（7 条）与 automation_runs.source_cwd 去重，均不指向本工作区 ⇒ 免做。
   > 先查再决定，别默认要复制。
2. 日工作日志与审计产物归档，不要留在被腾空的旧工作区（日日志进
   memory\_来自<旧工作区>_<日期>\，产物进业务目录下的留档子目录）。
   > 第三次的做法：目标工作区 memory\ 恰好缺当日（09-11~09-18 齐全、无 09-19）→ 直接补成2026-09-19.md 接续链条，
   > 比另起 _来自…\ 子目录更顺；原文副本另存包内 backup\原文副本\。
3. 同槽位里已软删的会话记录不迁 —— 查 sessions.deleted_at，非空的都是历史每日跑批残留，
   侧栏不显示，留在旧槽位属历史事实；只迁 deleted_at IS NULL 的那个会话。
   反向也要防：本会话自身若 deleted_at 非空，就是不该迁，迁移脚本应先中止。
4. 自己的诊断/暂存脚本要留档带走（_probe*.py / _stage1.py 之类），
   移入包内 诊断留档\，别留在被腾空的旧工作区。搬完记得复核旧工作区只剩 .workbuddy\memory\（空）。

交付前必须真跑一次 check（只读冒烟），不靠「读代码觉得对」。它一次性问清四件事：
清单里到底几个文件（含子目录）｜新槽位有无同名冲突｜守护是否判定应用在运行｜is_playground 与 deleted_at 现状。
> 第三次实测：check 才发现旧模板的 state.json 字段名是 name 而新脚本已改 rel、且清单是 5 个而非 3 个 —— 若不冒烟会带着错漏交付。

内置守卫：

• 进程守卫：扫 ~/.workbuddy/sessions/*.json 的 lastHeartbeat，2 分钟内有活动即中止
  —— 比按 exe 名查进程可靠（不依赖可执行文件名）；--force 可跳过
• 改库前整组备份 workbuddy.db + -wal + -shm（只备份主库会丢未 checkpoint 的事务）
• 先 PRAGMA wal_checkpoint(TRUNCATE) 再备份，保证快照自洽
• 每搬一个文件核对 sha256，不一致立刻停并报明是哪个文件
• 往返状态写 state.json，rollback 依它复原（比整体覆盖库安全：只退这一步，不牵连后续改动）

不要跟着改的东西（都是历史事实，改了等于篡改记录）：
artifact-index/、changes-index/、changes-detail/、file-tree-manifests/、traces/、audit-log/，
以及 ~/.workbuddy/sessions/<pid>.json（运行时心跳，重启自刷新）。
另外 ~/.workbuddy/workspace/sessions/<会话id>/（实测本会话 1055 个文件）按会话 ID 索引、与 cwd 无关，一律不动。

4.5 任务合并 —— 已迁出（2026-09-23）

> 该能力已迁至 omni-context-relay（万象-会话交接与任务迁移）C 线。
> 判定标准（字符 2-gram Jaccard + Kruskal 成组）、三层保留、原任务归档的四道护栏，
> 全部在那边，以及 omni-context-relay/references/任务合并方案.md。本节不再重复。
> 触发词「任务合并 / 合并相似任务 / 把几个任务合起来 / 同类型任务合并」也已随之迁出。

A9 事故复盘 3（2026-09-19，~\.workbuddy\skills_archive 实景）——回收站两条通道全死

用户确认删除待删除区的 5 个目录（46 文件 / 0.63 MB）时，Add-Type 与 COM 两条送回收站的路全被安全策略硬拦，报错明文即「Command blocked for security」。
1. 别把「送回收站」当默认可用：先探通道再定路线。探不通就明说，改走「跨盘快照 + 永久删除」。
2. 快照要跨盘：C: 的待删内容快照到 D:，同盘快照防不了整盘事故。
3. 「没误伤」必须逐条举证，不能只看「命令没报错」：本例逐条确认了 5 个源的正式归档副本仍在，以及那个「无正本」目录没被顺手带走。
4. 父目录计数是最好的旁证：84 → 83。
5. 教训：① 永久删除前必须有 testzip 通过的跨盘快照；② 复核要给「未误伤」逐条举证；③ 交付话术里必须交代回收站为何没用。

B 篇 · 回收溯源（谁删了什么）

> 与 A 篇 A8「真删除」互为表里：A8 教你怎么删，B 篇教你删错了怎么查。

B0 适用场景

用户问："回收站怎么多出文件""是不是你（AI）删的""今天删了什么""某文件哪来的"。

B1 一键用法（推荐）

本 skill 自带自包含脚本，不依赖任何本机特定路径，复制到任意 Windows 电脑即可用：

python "<skill目录>/scripts/recycle_trace.py"            # 查今天
python "<skill目录>/scripts/recycle_trace.py" 2026-08-25 # 查指定日期

脚本自动：定位 $Recycle.Bin → 取 mtime 最新的 SID 目录（当前用户）→ 解析 v2 $I → 按日期筛选 → 输出「来源分类统计 + 明细」。

B2 ⚠️ 最容易错的关键点（务必先看）

Windows 10/11 回收站 $I 索引是版本2格式（头 02 00 00 00 00 00 00 00）：
- 删除时间（FILETIME，8字节小端）在偏移 16（0x10） —— 不是旧资料的偏移 8
- 原路径（UTF-16LE，到首个 \x00\x00）在偏移 28（0x1C） —— 不是偏移 24
- 用旧偏移会解析出错误日期甚至 0 项，误判"今天没删除"。先用 hdr[:8].hex() 确认是否 0200000000000000。

B3 手动排查步骤（无脚本时）

1. 定位目录（沙箱里 PowerShell stdout 常被吞，用 Bash）：ls -la '/c/$Recycle.Bin'，找 mtime 最新的 S-1-5-21-*-1001。
2. 用 Python 解析：遍历 $I*，data[16:24]→删除时间，data[28:]截到\x00\x00→原路径，按日期筛选。
3. 从原路径推断来源软件（见下表）。

B4 来源软件推断表（回收站不记录"删除软件"，只能靠路径）

B5 跨电脑部署

• 本 skill 位于用户级目录 ~/.workbuddy/skills/omni-file-governance/，已跨项目通用。
• 到另一台电脑：把整个 omni-file-governance/ 文件夹复制到该机的 ~/.workbuddy/skills/ 即可；或把 ~/.workbuddy/skills/ 放进 OneDrive/同步盘，多机自动同步。
• 脚本不硬编码用户名/SID/Python 路径，纯标准库，任意 Windows + Python3 可跑。

B6 注意

• 全程只读，不删回收站、不删用户文件。
• 清理任何文件须用户明确授权。

C 篇 · 台账联动（登记表 ↔ 项目文件夹）

> 与 A 篇接力：A 篇把文件整理好，C 篇把「整理结果」登记进台账、
> 并按登记表的阶段勾选自动建/清项目文件夹，保证「表」与「盘」始终一致。

C0 适用场景

• 标准模板结构/条目/联动规则调整后，需要把已创建的项目登记表批量更新为新结构
• 检测项目登记表与标准模板是否一致（结构、条件格式）
• 保留数据前提下的结构迁移
• 登记表阶段勾选（方案/初设/施工图）→ 项目文件夹动态生成/清理（未勾选阶段不建文件夹）

C1 文件与标准模板

• 本目录 sync_register.py：登记表模板结构同步（纯 openpyxl，无需 WPS COM）
• 本目录 sync_folders.py：登记表阶段勾选 ↔ 项目文件夹联动（纯 openpyxl）
• 本目录 auto_stage.py：自动选择阶段——读 F4「合同约定阶段」→ 自动勾选 G4/H4/I4（驱动复选框）→ 可选联动文件夹
• 标准模板：<工作区>\项目归档管理体系_成果\03_项目文件夹模板\03_设计成品归档\01_归档登记表\园林景观项目归档登记表（确认版2026／0）.xlsx
  （即成果02 确认版副本，模板版本号记录在「填写说明」sheet 末行，如 v1.1）

C2 auto_stage.py 用法（自动选择阶段）

python "<skill目录>/scripts/auto_stage.py" --register 登记表路径            # 仅勾选阶段
python "<skill目录>/scripts/auto_stage.py" --register 登记表路径 --sync-folders  # 勾选后联动文件夹

• F4「合同约定阶段」支持值：方案 / 初设 / 施工图 / 方案+初设 / 方案+施工图 / 初设+施工图 / 全部阶段 / 其他
• 数据流：合同约定阶段 → G4/H4/I4 → 复选框 → （可选 sync_folders）目录联动

C3 登记表结构同步 · 用法

1. 仅检查（推荐先跑）

python "<skill目录>/scripts/sync_register.py" \
  --template "<工作区>\项目归档管理体系_成果\03_项目文件夹模板\03_设计成品归档\01_归档登记表\园林景观项目归档登记表（确认版2026／0）.xlsx" \
  --target "<项目盘>\某某项目归档登记表.xlsx" \
  --check

输出：结构一致？条件格式一致？

2. 执行同步

去掉 --check 即可。同步前自动备份为 *.bak-时间戳.xlsx。

3. 批量同步所有项目

python "<skill目录>/scripts/sync_register.py" --template 模板路径

（不指定 --target 时扫描当前目录下所有「归档登记表」xlsx，逐个同步）

C4 同步逻辑

1. 对比数据区条目结构（A/B/C 列，行 7-29）与条件格式定义
2. 若一致 → 报告「已与最新模板一致」
3. 若不一致 → 备份原表 → 用模板文件覆盖结构 → 按「条目名称」回填 D(已归档)/E(存放位置)/F(备注)
   → 回填项目信息区（A2/D2/A3/D3、G4/H4/I4 复选框联动列）与签署栏 → 保存
4. 模板中不存在的条目（数据无法匹配）会列出警告，不丢失不编造

C5 关键约定

• 数据匹配键 = 数据区 B 列「文件名称」文本；模板若重命名条目，旧数据会进「无法匹配」警告，需人工确认
• 复选框联动列 G4/H4/I4 一并同步（项目设计阶段勾选状态保留）
• 纯 openpyxl 实现，规避本机 WPS COM / safe-delete 拦截层的不稳定问题

C6 触发方式

• 手动：改完模板后运行脚本
• 可配合自动化：把脚本设为定期任务（如每周五），或模板改动后由 AI 助手直接调用

C7 文件夹联动（sync_folders.py）

C8 规则

登记表 G4(方案)/H4(初设)/I4(施工图) 勾选状态为唯一依据：
- 勾选阶段 → 补齐该阶段全部文件夹（缺则建，命名与登记表/文件夹模板一致）
- 未勾选阶段 → 清理该阶段文件夹（空目录整树删除；含文件 → 移到 <根>/待删除区_阶段_时间戳/，绝不硬删）
- 只处理登记表映射的阶段目录（02/03 下的 02_方案设计、03_初步设计、04_施工图设计），不碰其他任何目录/文件

C9 文件夹联动 · 用法

# 预览（推荐先跑）
python "<skill目录>/scripts/sync_folders.py" \
  --register "F:\项目\03_设计成品归档\01_归档登记表\xxx项目归档登记表.xlsx" --dry-run
# 执行
python "<skill目录>/scripts/sync_folders.py" --register 登记表路径

• --root 可指定项目根目录；缺省自动从登记表路径推断（<根>/03_设计成品归档/01_归档登记表/）

C10 覆盖场景

• 新建项目：复制「项目文件夹模板」+ 登记表 → 按勾选跑一次 → 只生成勾选阶段文件夹
• 编辑已有项目：改勾选 → 跑一次 → 取消的阶段被清理、新增的阶段被补齐
• 登记表勾选状态与文件夹始终一致（前端表格灰置联动 + 后端文件夹同步）

C11 数据流

勾选复选框 → 联动列 G4/H4/I4（TRUE/FALSE）→ sync_folders.py 读取 → 创建/清理文件夹

常见误用与常见问题（FAQ）

常见误用（反模式）

常见问题

• Q：疑似垃圾可以直接删吗？ A：绝不可以。先移入 待删除区/，等用户人工确认；任何批量移动都要用户明确确认，脚本默认 dry-run。
• Q：待删的是「已迁移的旧副本」，还要跨盘快照吗？ A：不必。最硬的凭据不是「能还原」，而是「根本不需要还原」—— 逐条确认等价正式副本仍落在别处（4.1）。
• Q：真项目名称放在哪里？ A：不在技能包内 —— 放 ~/.workbuddy/omni-project-rules.json（可由 OMNI_PROJECT_RULES 指向别处），包内只留虚拟示例。
• Q：异常发生了怎么办？ A：立即停手 → 查回收站 → 出清单；stdout 输出不可全信，以实际文件系统状态为准。
• Q：三篇的边界怎么分？ A：A 篇动词是整理与隔离；其余两篇不重叠，判据边界见文末「三篇不重叠的判据边界」。

附 · 三篇分工一页纸

三篇不重叠的判据边界：
- A 篇的动词是整理与隔离（产出台账与目录结构）
- B 篇的动词是取证与还原（只读，不改任何文件）
- C 篇的动词是同步与联动（以登记表为唯一依据，改结构不改内容）

> 与相邻技能的分工：
> 文件整理好之后要上传到素材平台 → 走 万象-素材批量上传；
> 要把整件事交接给别人 → 走 万象-交接手册生成；
> 要治理技能库自身 → 走 万象-技能打包与库治理。

附 · 付费与授权

§〇 · 本技能定位为付费技能（Pay Skill）

> 🔴 付费技能一律走完整付费路径 —— 是付费定位，就照着付费通道做完：
> 随包实现 402 链路（见 §〇·2）、接入相应服务、按注册价填单价、走 Pay Skill 向导。

§〇·2 · 随包提供的 402 付费链路实现（平台「付费改造」检测就看这个）

平台在提交时会做一次「支付宝付费改造」检测，判据是技能包内是否存在 402 支付链路的实现，
缺失项会逐条列出：402账单下发 / 携带凭证重试 / 验付调用 / 履约确认 / 订单持久化与幂等。
该检查不阻断提交，但审核阶段会重做一次，不合规即拒。

⇒ 本包自带该实现（目录 a2m/，零密钥、可直接 npm install && npm start）：

配置边界：配置缺失即明确失败（资源路由返回 503），不构造 SDK、不使用占位密钥、不提供任何跳过验付的路径。
密钥只走运行环境变量或本地配置文件，永不入包。

cd a2m && npm install && npm run smoke   # 冒烟：账单结构 / RSA2 签名 / 幂等边界
npm start                                # 默认 http://localhost:3000/demo/a2m/resource

一句话：一台电脑上文件和文件夹的一生——进来时怎么归类、乱了怎么编号、垃圾怎么隔离、
删错了怎么追查、台账与文件夹怎么保持同步。三件事合在一部里，因为它们共用同一套铁律、
同一批零依赖脚本、同一个工作对象（本机文件系统）。