inspired-by-atmosphere/ops-troubleshooting-skills/windows-file-lock-debugging

Windows 文件占用排查（File in use / Permission denied）

排查"文件被另一个程序占用导致无法删除/覆盖/写入"这一类问题：先分清是转换/脚本问题还是文件被锁，再用 Restart Manager 精确锁定持有进程，确认无可见窗口后才安全结束。实战沉淀（实测环境：WPS + 云同步客户端 + 频繁 md→docx/pdf 转换重跑）。

When to Use

文件删不掉/覆盖写不进（Permission denied / [WinError 32]）需要找出占用进程时；判定"转换失败"还是"文件被锁"时；本技能配套脚本 scripts/find_file_lock.py 一键查持有者。

触发场景

• 重跑 md_convert.py / pandoc / 任何覆盖写文件时报 Permission denied、withBinaryFile: permission denied、[WinError 32] 另一个程序正在使用此文件
• 删不掉/改不了文件，想知道是谁占着
• 判据：wkhtmltopdf stderr 已出现 Done 但 pandoc 报写文件 permission denied → 输出文件被别的进程持有句柄，不是转换问题（转换本身成功了）

常见持有者（本机实测）

排查步骤

1. 精确找持有者（不要靠猜/全量 tasklist）：

python <skill>/scripts/find_file_lock.py '<Windows原生路径>' → Restart Manager（Rstrtmgr.dll）查询，输出 PID + 进程名 + 类型

1. 确认无可见窗口再结束：

powershell -NoProfile -Command "(Get-Process -Id <PID>).MainWindowHandle" → 0：残留后台进程，Stop-Process -Id <PID> -Force 安全（不打断用户正在看的东西） → 非 0：用户正开着窗口，让用户手动关闭后再重试

1. 删除旧文件后重跑：md_convert.py 幂等，重跑即覆盖旧版
2. Restart Manager 返回空但文件仍锁：按序排查——①你自己的 shell cwd 在不在里面（最常见的空目录删不掉原因，cd 出去即可）②是不是已跑着的程序本体（Get-Process | ? Path -match '<目录>'，此时删=删工具，先问用户）③系统服务或锁刚释放，等几秒重查

查"某程序在不在运行"时的编码坑

tasklist /FI "IMAGENAME eq X.exe" 在中文控制台的输出是 GBK：python subprocess.run(..., capture_output=True, text=True) 会在 reader 线程抛 UnicodeDecodeError（异常发生在后台线程，主流程看起来只是"没结果"）→ 不要加 `text=True`，直接字节判断 b"X.exe" in proc.stdout。要看输出时用 encoding='gbk', errors='replace'。

Restart Manager API 坑位（脚本已封装）

• 签名：RmGetList(h, &pnProcInfoNeeded, &pnProcInfo, rgAffectedApps, &lpdwRebootReasons)
• 参数2 = 输出需要的进程数；参数3 = in/out 缓冲容量/实际数量
• 第一次传空缓冲拿 needed；返回码 234 (ERROR_MORE_DATA) 是正常信号（需要更大缓冲），分配 needed 个元素后二次调用
• 参数顺序写反会拿到 0 或空结果（本会话踩过）
• strAppName 是 WCHAR[]，直接 print 中文会撞 surrogate 编码错 → p.strAppName.encode('utf-8','replace').decode('utf-8')
• RmRegisterResources 传入路径用 c_wchar_p 数组 + cast(..., POINTER(c_void_p))

验证

• 脚本输出持有者 PID/进程名与 Restart Manager 一致
• 结束残留进程后旧文件可删除、重转成功
• 全程未结束任何有可见窗口的进程

相关

• 该坑常出现在 md→docx/pdf 交付重跑场景：md-export 技能（user-owned，若需并入建议 hermes curator adopt md-export）
• 中文路径/编码类 Windows 坑 → windows-cn-env-quirks（user-owned）