inspired-by-atmosphere/ops-troubleshooting-skills/workspace-audit-cleanup

本地工作区整理与归档（打扫战场）

面向"多个知识库/工作区散落文件"的清理工作流（盘点→归属确认→去重→字节校验→搬迁→复扫）。

触发场景

• 用户说"打扫一下战场 / 整理规范一下部门 / 清理 / 归档 / 盘点布局"
• 用户要查磁盘占用/腾空间方案（盘级+目录级明细，如"详细调查储存占用"）
• 需要摸清某项目在本机的文件分布（布局地图），或批量删除/迁移散落文件

工作流（先盘点，后动手，每步留痕）

1. 全盘扫描（只读）

• 先并行 ls 各候选根（Documents / Desktop / 用户根 / 数据盘），顶层看全貌，发现新目录再逐层钻
• 大目录（含 .venv/site-packages）禁 git-bash du 全量（NTFS 百万文件 10-20 分钟才出结果）；用快扫三件套（实测）：
• Sysinternals du64.exe（live.sysinternals.com 直连可下，~465KB）：du64.exe -nobanner -accepteula -q -l 1 '<data-drive>:\' 顶层明细秒出；⚠️输出别接 `| sort`（sort 缓冲整段输出，扫完才吐）；单位是 KB 带千分位
• python scandir 扫描器：scripts/diskscan.py，PYTHONIOENCODING=utf-8 python diskscan.py '%USERPROFILE%' 钻取指定目录（depth=1 顶层+自动二级明细），比 du 快数倍
• 后台长扫描输出重定向到文件再 read_file（process log 中间段会被 noisegate 折叠）
• ⚠️ du64 与 scandir 都跳过 junction/symlink：显示 0B 的目录可能是链接（实例：某数据集目录显示 0B，实为空壳链接，真数据在另一盘）——用 PowerShell Get-Item <path> | Select FullName,LinkType,Target 或 ls -la 核实，再 find /e -maxdepth 3 -iname "*DEAP*" 定位真身
• ⚠️ MSYS 会把 /export=... 这类参数做路径转换（加 MSYS2_ARG_CONV_EXCL='*'）；命令里带盘符反斜杠路径（如 <data-drive>:\）会触发 lifecycle_guard embedded null 误报——长命令一律 write_file 成 runner .sh 再执行
• 中文路径用 terminal 的 ls/grep，不用 search_files（ripgrep 中文路径 IO error）
• 并行探测：git remote -v + git log（找多 clone 及活跃度）、cronjob list（找自动化依赖的路径）、读 AGENTS.md/README（既定结构）

2. 盘点结果先呈现，等批准再动

• 用户硬性要求：扫描结论 + 整理方案先交付内容，批准后才执行删除/移动
• 方案用表格：动作 | 风险 | 是否需要确认；标注哪些项可直接做、哪些等拍板

2.5 大整理/大打包（多区并行收尾型）：关键文件保护清单先行 + 三态处置

适用：用户要求"大整理大清理全更新大打包"这类横跨多区的收尾。用户连纠三次确立的纪律（"先讨论方案，不要冲动"、"这些有关键文件"、"还没校赛但我的工作结束了"）：

• 关键文件保护清单先行：动任何文件前，先把"一字不动"名单列给用户确认，再谈清理。项目里提交基线/口径SSOT/报名件/答辩件（策划书111、42报告、43证据包、47/49、44/45/46、34/35、48、PPT1）是命根子——整理=归位+打包，绝不改写内容
• 三态处置（用户拍板 schema）：①该更新的旧版本→更新内容（按口径SSOT对齐）②合并精简冗余文档 ③其他人写的日志/记录→暂时保持不动（可能仍有引用价值）。清理=只归档不删除（临时产物/渲染缓存才真删）
• 多开子代理只读审计：按区域各派一个子代理，只读盘点+写审计清单到 scratch 目录（如 _system\_audit\），任务里显式"只读、禁止修改/删除/移动任何文件"；主会话汇总成逐文件处置清单（文件|生效度|处置A/B/C/E）给用户审批后才动手
• 口径统一类更新：先正则扫全库旧口径关键词（如 69.42/215Hz/8.6K/86-92）量化残留分布，再区分"历史记录不动"vs"生效文档更新"；口径对照以项目 SSOT（42 报告 v3 类）为准，不要凭记忆
• 打包前先测体积：python os.walk 汇总各目录大小（du -sh 遇中文/特殊字符目录名易报错）；区分文档/代码全打包 vs 可重下载数据集/第三方模板/无关大模型目录→清单化或排除（实例：资料库内 15.2G 微调模型 + 2.2G 第三方模板不打；某盘 86G 公开数据集用「清单 + 下载来源」替代，占位目录的真数据在项目盘）
• 免费 API key 不提案吊销（用户 9/14"反正是免费的不用管"）：整理/安全审计发现免费档 key（0 元 API、学生档）时隔离+记录即可，不写"建议吊销"待办；只有付费/生产 key 才提吊销

3. 删除/归档前三确认（最重要，用户两次纠正）

• 归属确认：看着"重复/旧"的目录可能是用户活跃工作区——先问再删。实证教训：把 Desktop\code\ 误判为死 clone 提议删除，用户纠正"code 是我自己的工作区，只读别碰"。清理对象必须逐项确认归属与用途；用户划定的只读区（工作 clone）绝不碰
• ⚠️⚠️ 删"软件目录"前查三证据（2026-08-17 <data-drive>:\App 事故：把软件本体当"安装包"删了 11 个软件）：绿色版/便携版软件本体就住在 <data-drive>:\App、<data-drive>:\app 这类目录，注册表 Uninstall 项（UninstallString/InstallLocation）指向它 = 软件本体不是安装包。删前必查：① reg query "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall" /s /f <目录名>（哔哩哔哩案例：UninstallString=<data-drive>:\App\bilibili\卸载.exe，当时未警觉）② Get-Process | ? Path -match '<目录>'（删不掉的"被占用文件"= 正在运行的软件本体，<data-drive>:\App\QQ 39M 残留就是信号）③ 开始菜单/桌面 .lnk 目标（WScript.Shell）。删后速判：大量快捷方式报"路径不存在"= 删错本体；数据目录（Documents/AppData）未动则重装即恢复。磁盘扫描工作流见本技能 scripts/diskscan.py
• md5 去重：删"重复副本"前 md5sum 对比，逐字节相同才删（下载目录里的表 vs 归档目录里的同一张表、分发包 vs 备份包）
• 引用检查：归档/移动目录前 grep -rln "旧路径" 全仓（scripts/ docs/ hermes scripts/ cron 脚本）——hermes scripts 里常藏引用旧路径的调试/验证脚本，归档会打断它们

4. 归档动作

• mv 旧目录 → 归档区\原名_YYYYMMDD\（同盘符 rename，快；含 .venv 也 OK）
• 写 README_迁移说明.md：原路径 / 迁移时间 / 内含物清单 / 复跑指引（旧脚本引用如何替换）
• 只改"当前基线文档"里的失效路径（如决策报告、数据地图，且多份副本要同步改）；历史记录文档（当日任务卡）保持原样
• 数据地图类文档（data/README）同步更新数据新位置

4.5 归位式搬迁：把散落资料集中进一个专用库（2026-09-28 学科库实证）

适用：用户说"这种资料放 X 库"，而资料散在多个盘/多个旧库里（课程资料、素材库、交付件副本）。这是搬迁不是清理——目标是归口，不是删。

1. 先盘点再方案：按主题关键词全机 find（主题名 + 讲义/课件/试题/期末/教材 类词），每个候选给「内容摘要 + 文件数 + 体积」；出「来源 → 目标 | 方式 | 规模」表，并显式列出"不进这个库的"（属于别的项目的资料别混进来：项目资料归各自项目库、工具脚本留原地）
2. 三问用 clarify 收口（推荐项放第一，用户会按你给的选择拍板）：①范围（全部搬含素材/课件大件 vs 只搬文档类）②方式（移动为主 + 交付区只复制 vs 全复制）③要不要建索引页
3. 执行用 `scripts/migrate_verified.py`，别直接 shutil.move 搬：跨盘删源遇到被占用文件会抛异常整批中断，已搬/未搬混在一起进度不明。逐项「复制 → 校验字节 → 删源」（删源失败只登记不中断，附重试+清只读位）
4. 交付区/上传区只复制不移动（mode: copy）：交付路径（网盘上传区之类）是上传留档的唯一真源，移走等于断档
5. 搬完拍平：把源目录整体搬进目标会产生多余同名一层（课件\全部课件\、教材精炼\离散数学\）→ 用 plan 的 flatten 收掉；拍平前后库内文件数/字节数必须相等，相等才算没搬漏
6. "重复"结论必须 md5 逐字节验证才敢说可删：同名同尺寸不同内容很常见（同一份材料两次生成的 PDF）→ 两份都留，只在报告里标"疑似重复 n 项已验证"
7. 收尾两件产物（放库根）：00_索引.md（Obsidian 双链地图：课程 | 体量 | 内容 | 快速入口 + 各目录说明 + 新增规则）、00_搬迁记录_<日期>.md 台账（来源→目标 | 方式 | 文件数 | 体积 + 校验 + 保留清单 + 遗留待办）。有台账，用户下次能自己核对
8. 最后必须问用户：搬空的旧库壳去留、疑似重复件去留、受保护文件（AGENTS.md 等）改动——受保护文件被系统 BLOCKED 时别换路径硬写（terminal/execute_code 绕道会被同样拒绝），把要加的内容讲清楚等批准

8.1 删"空壳"前按文件数复查内容，别只按目录名判断空不空：搬迁后剩下的壳里可能还住着非搬迁内容——find <壳> -type f 列全（实例：学习进度笔记、插件配置这类目录名看不出的小文件），发现即先抢救进库内对应主题目录，再谈删。壳里若住着程序本体（实例：旧学习库里装着本机唯一一份编辑器程序），删壳=删工具：先查注册表/Program Files 无第二份安装、再查运行进程，然后优先"把程序挪到正规安装目录 + 只删壳"，把"删程序"作为并列选项让用户拍板（用户可能只是没意识到壳里有程序） 8.2 受保护指令文件（AGENTS.md 等）改动走"用户手动落盘"：守卫（tools/file_tools_write_guards.py）每次都要真人批、不落任何批准范围，且只认两条通道——gateway 按钮往返 / 交互式 CLI 批准面板；桌面聊天会话两条都不占，用户在对话里说"批准"不生效，自动批准也不绕过。所以别重试、别换路径硬写（terminal/execute_code 绕道同样被拒），改为：

• 把待插入段落写成独立 md（scratch 里），并说明插在哪两个小节之间
• 装剪贴板：powershell -NoProfile -Command "Set-Clipboard -Value ([IO.File]::ReadAllText('<块文件>',[Text.Encoding]::UTF8))"——必须用 PowerShell 读文件装（bash 管道给 clip.exe 会被控制台码页糟蹋中文）；装完自检 $f=[IO.File]::ReadAllText(...).Trim(); $c=(Get-Clipboard -Raw).Trim(); $f -eq $c
• 帮他打开目标文件：Start-Process notepad -ArgumentList '<目标文件>'
• 给 3-5 步点击指引（Ctrl+F 找锚点段→Home→Ctrl+V→Ctrl+S，存前看状态栏是不是 UTF-8，别存成 ANSI→关窗）
• 用户说"好了"后必须回读校验：字节数、无 BOM（前 3 字节非 ef bb bf）、raw.decode('gbk') 应抛异常（能解码=被存成 ANSI，要重存）、段落顺序、内容逐字一致

1. 库组织约定（用户定，新课程/新主题照抄）：按课程名/主题名建一级目录；主题内分 教材精炼/讲义/课件/作业/笔记/试题集/素材；同类课件只留一个文件夹（散落第二份要么合并要么标疑似重复）；工具脚本与作业不混进资料库

5. 路径编辑后字节级验证

• ⚠️ patch 写 Windows 路径会被转义写坏（详见下方 Pitfall ①）——改路径一律用 python runner 字节替换，收尾查 \x08 / 独立 CR / 双反斜杠

6. 收尾：更新索引 + 复验

• 项目根 AGENTS.md 加"本地目录地图"小节（区域表 + 双 clone 分工 + 只读红线），防止再长乱
• 复验关键路径：归档目标存在 / 源消失 / 清理后剩余清单
• 用户要布局全景文档时，写到指定文件夹并报完整绝对路径

Pitfalls

① patch 的 new_string 含 Windows 路径会被转义写坏（2026-08-09 实证）

\r（如 \results）写成回车、\b（如 \bci-engine）写成退格——CRLF 文件里路径被截断成两行。patch 返回的 diff 出现断行即中招。 修复（字节级，不能再走 patch）：

import io
d = io.open(p, 'rb').read()
d = d.replace(b'xxx\r\nesults', b'xxx\\results')  # CRLF 断行
d = d.replace(b'xxx\nesults',   b'xxx\\results')  # LF 断行
io.open(p, 'wb').write(d)

收尾检查：b'\x08'（退格）、独立 0x0D（后非 0x0A）、b'\\\\'（双反斜杠）；repr 确认单反斜杠。 预防：改 Windows 路径一律写 python runner（r-string）执行；patch 后必须字节验证。 相关：python -c 反斜杠/中文易炸（b"(未找到)" 非 ASCII bytes literal 直接 SyntaxError）——复杂脚本 write_file 成 runner 再跑。

② 误判活跃工作区为死文件

"分支落后 N 提交 + 有未提交修改 + 内容分叉" ≠ 死 clone——可能是用户日常 pull 的工作副本（因本地混入大数据只 pull 不 push）。同一仓库双 clone 可能是"同步用 clone + 用户工作 clone"分工，内容允许分叉。删除前必问。

③ 占用文件删不掉

Excel 锁文件（~$ 前缀）存在 = 文件被打开。删除报 "Device or resource busy" → 提示用户关闭后处理，不硬删、不当作失败完事。

④ 文档双写不同步

项目文档与技术库 docs 同号文件（如 19 决策报告）是两份副本——改路径/内容要两份一起改，否则 sync 后仍分叉。

⑤ ls 拼接输出误判文件位置

多段 ls 输出拼一起时（如"用户根 + Downloads"两段无分隔），散件实际可能在第二段（Downloads）——核对位置用带引号的单目录 glob 复查。

⑥ 杀后台 du 后子进程残留

MSYS 后台任务被杀后，du 子进程可能存活继续扫盘（tasklist 里多个 du）——taskkill /F /PID 逐个清，否则继续占磁盘 IO 拖慢后续扫描。

⑦ 大目录清单的中文名乱码

du64 输出中文目录名变 ?????（GBK 控制台），按字符数+输出顺序反推映射（按输出顺序 + 字符数反推，如 5 个 ? 对应一个 5 字目录名），拿不准就用 ls 复核，勿凭猜测写进报告。

⑧ 删不掉≠被占用：可能是 DENY ACL（2026-08-16 联想商店实例）

rm/Remove-Item 报 Permission denied，但 handle64.exe 查"无句柄"、文件属性可写——查 icacls <file>：看到 BUILTIN\Users:(DENY)(DE,WD,AD,WEA,WA) = 软件（联想软件商店等）故意给下载文件加的拒绝删除。修复需提权（UAC 用户点确认）： takeown /f <path> /r /d y && icacls <path> /grant <用户名>:F /t /c && rd /s /q <path> 提权模板：powershell Start-Process cmd -Verb RunAs -Wait -ArgumentList '/c','<脚本.cmd>'；⚠️ Hermes 侧审批可能超时拦截（BLOCKED 提示），重试前必须先问用户确认（用户在场走 clarify，别擅自重试）。

⑨ 清理脚本别放会被清理的 Temp 目录

脚本若位于 AppData\Local\Temp，rm -rf Temp/* 会删掉正在执行的脚本本身（bash 逐行读文件中途失败）。执行脚本放独立目录（如 <data-drive>:\cleanup_scripts\），用完再删。

⑩ 归属判定铁律（用户 8/12×2 + 8/16 三次纠正）

盘点/清理遇到 .reasonix 系目录、Ollama/llama-server、openviking 等本机服务 = Hermes 自家资产/另一 Hermes 进程在用。先查证（父进程链 Get-CimInstance Win32_Process + netstat -ano | grep 端口 找 client PID）再归因，报告只陈述事实；用户说"不用管"就真不动。严禁说成"reasonix 生态/外部系统"。

⑪ 删除保留红线

涉及魔改 eGPU 的驱动安装包（466.77 底座驱动）不删；用途不明的安装包（DDPM/Physics.zip 类）保留并在报告标注原因；删"安装包"前确认对应软件已装（Adobe 看安装版目录结构；Autodesk 共享组件≠已装 AutoCAD——Program Files\Autodesk 无产品本体=未装完，装包删了会丢安装途径，报告里显式提示）。

⑫ 含中文路径的提权 .ps1 必须 UTF-8 带 BOM（2026-08-16 bilibili 清理实证）

write_file 写的是无 BOM UTF-8，PowerShell 5.1 按 ANSI/GBK 读 → 脚本里的中文路径全乱码 → Remove-Item 静默失败（-ErrorAction SilentlyContinue 吞错误，验证才发现残留）。ASCII 路径正常删、只有中文路径残留 = 中招信号。 加 BOM（单引号防 bash 转义；双引号写法实测没写进去）：

python -c 'p=r"%USERPROFILE%\script.ps1"; d=open(p,"rb").read(); open(p,"wb").write(b"\xef\xbb\xbf"+d)'
od -A x -t x1z -N 8 script.ps1   # 首字节应为 ef bb bf

提权执行：powershell Start-Process powershell -Verb RunAs -Wait -ArgumentList '-NoProfile','-ExecutionPolicy','Bypass','-File','<script.ps1>' 删后必验证：用 python 遍历目标清单（os.path.exists / reg query 返回码）输出 已清/残留——别用 PowerShell 直出中文结果（GBK 控制台把"已清/残留"标签打乱无法分辨）。

⑬ 打包排除禁靠 os.walk 子串剪枝（2026-09-14 86G 差点入包实证）

dirs[:] = [d for d in dirs if not any(x in d for x in EXCL)] 只拦名字含排除串的子目录——顶层大目录（如 04_数据）本身名字不含排除串时，os.walk 会整棵遍历（86G 数据全写入 zip，40 分钟后台进程才发现）。

• 排除顶层目录：os.walk 前用 TOP_SKIP = {...} 集合显式跳过，不依赖名字匹配
• 大目录打包先小样 dry-run（前台跑小范围或打印将写入文件清单）确认排除逻辑生效，再后台跑
• 打包后必验 zip：testzip() + 列出最大文件 + grep 排除目录名是否残留（04_数据/t3_out_full/.git/密钥名）
• 后台打包进程若异常久（远超预期体积对应时间）→ process_manage poll + 看输出文件实时大小，疑似误入大目录立即 kill 重写，别等完成

⑭ delegate_task 多任务数组报 "Task N is missing a 'goal'"

goal 字段明明存在却报缺（复杂 goal 字符串数组解析失败，重试同形状仍失败）——拆成单任务多次 delegate_task 调用（同一响应里并行发多个单任务调用），并发不丢，别反复重试数组形态。

⑮ 用户催"加子代理"先诊断瓶颈

磁盘 IO / zip 压缩 / 单文件遍历不是子代理能加速的（子代理共享同一块盘/CPU）——用户催并行时先查后台进程实际卡在哪（process poll + 输出文件大小变化），是 IO 就修算法/排除逻辑而不是加人；加人只对独立只读盘点/独立区域更新类任务有效（盘点 4 区并行、更新 4 组并行都是对的）。

⑯ 子代理并发上限 5 + 共享工作目录互踩（2026-09-27 C 盘清理实证）

• 一次 delegate_task 数组派 6 个 → 第 6 个立刻 HTTP 429: concurrency reached, current: 6, limit: 5；已在跑的兄弟也会被反复掐死（实测 6 个里 3 个半途 failure，其中一个已完成测量、0 字节删除就断了）。
• 纪律：磁盘清理类并发 ≤5；关键批次留主会话自己跑（脚本化 before/after 字节统计 + 安全闸 assert 活跃目录不在清单里），子代理只做可重入的独立区域；子代理失败后先看 transcript 尾部判断「删到哪一步」，再决定接管还是重派。
• 多个子代理共用同一 scratch 工作目录会在同名脚本（如 freespace.ps1）上互踩，write_file 拒覆盖兄弟文件白耗轮次 → 每个子代理分配独立子目录。
• 并发删除时 C 盘 FreeSpace 前后差会大于清单释放量（别的进程/脏页在同期变化）→ 账目以逐项目录字节数为准，FreeSpace 只作旁证。

⑰ 搬迁器只删"目录来源"，文件来源被漏删（2026-09-28 实证）

按 dir/file 分支写 mover 时最容易只在 os.path.isdir(src) 分支里删源——文件型来源（.md/.pdf）复制完就留在原地，而"源已清空"的复核只看目录就发现不了。写完 mover 必做一次源端复核：逐个来源路径重走一遍，报「已不存在 / 已空 / 仍有 N 文件」，有残留人工确认后再删。

⑱ 搬迁后多出一层同名嵌套

"把源目录整体搬进目标目录"= dst/<源目录名>/…，于是出现 课件\全部课件\、教材精炼\离散数学\、期末卷\期末卷\ 这类一层多余嵌套。搬完统一扫「父目录唯一子项仍是目录」的位置拍平（plan 的 flatten），拍平后比对文件数与字节数相等。

• 一次全盘整理实例（扫描结果/清理动作/路径修复对照）：见本文档「实战流程」各条附注。
• 全机磁盘占用调查：快扫工具链 + 各盘大头快照 + 腾空间分级方案（见上文「磁盘占用调查」）。
• 快扫脚本（scandir 版，跳过 junction，自动二级明细）：scripts/diskscan.py
• 核实过的搬迁器（复制→校字节→删源重试 + 拍平多余嵌套 + 报表 + 源端复核）：scripts/migrate_verified.py