Skip to content
Back to search

unlock-file

SkillWorks with Claude CodeGitHub

写入/替换文件失败并报 PermissionError、WinError 32、"另一个程序正在使用此文件"、EBUSY,或需要修改正被 Excel/Word/WPS 打开的 xlsx/docx/pptx 时使用。自动定位占用进程,优雅关闭文档窗口(不会静默丢失未保存修改),再重试写入。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/xiaohudasb--unlock-file/badge.svg)](/listings/xiaohudasb--unlock-file)

HTML

<a href="/listings/xiaohudasb--unlock-file"><img src="/api/listings/xiaohudasb--unlock-file/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

前置要求

- Windows 10 / 11 - Python 3.8+(已在 PATH 中) - 可选:`pywin32`(用于 COM 精确判断与关闭,缺失时自动退化为窗口消息)

  python -m pip install pywin32

方式一:安装脚本

git clone https://github.com/xiaohudasb/unlock-file.git
cd unlock-file
powershell -ExecutionPolicy Bypass -File .\install.ps1

默认安装到 Claude Code 的用户技能目录:

%USERPROFILE%\.claude\skills\unlock-file

安装到其他 Agent Skills 客户端时,用 `-Dest` 指定该客户端的技能目录:

powershell -ExecutionPolicy Bypass -File .\install.ps1 -Dest "C:\path\to\skills\unlock-file"

`-Dest` 的最后一级目录必须是 `unlock-file`,因为 Agent Skills 规范要求技能名与父目录同名。

方式二:手动安装

以 Claude Code 为例:

git clone https://github.com/xiaohudasb/unlock-file.git
cd unlock-file
$dest = "$env:USERPROFILE\.claude\skills\unlock-file"
New-Item -ItemType Directory -Force -Path $dest | Out-Null
Copy-Item -Force .\SKILL.md $dest
Copy-Item -Recurse -Force .\scripts $dest

其他客户端:把仓库根目录(包含 `SKILL.md` 和 `scripts/`)复制或克隆到该客户端的技能目录,并确保最后一级目录名是 `unlock-file`。不同客户端使用不同的技能目录,具体位置请查阅对应客户端文档。

安装后重新打开客户端会话;是否自动出现在可用技能列表中,由客户端实现决定。

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 87 lines
  1. ---
  2. name: unlock-file
  3. description: 写入/替换文件失败并报 PermissionError、WinError 32、"另一个程序正在使用此文件"、EBUSY,或需要修改正被 Excel/Word/WPS 打开的 xlsx/docx/pptx 时使用。自动定位占用进程,优雅关闭文档窗口(不会静默丢失未保存修改),再重试写入。
  4. license: MIT
  5. compatibility: Windows 10/11; Python 3.8+; pywin32 optional (COM route is more precise)
  6. ---
  7. # 解除文件占用
  8. ## 何时使用
  9. 出现以下任一情况时,先用本技能解除占用,再执行原本的写入/覆盖操作:
  10. - 写文件、编辑文件或脚本保存时(例如 Python 的 `openpyxl.save()`、`shutil.move()`)报 `PermissionError`、`[WinError 32]`、"另一个程序正在使用此文件"、`EBUSY`
  11. - 目标文件旁存在 `~$文件名` 临时锁文件
  12. - 已知用户正开着 Excel / Word / WPS 且需要改写该文件
  13. ## 安全红线(必须遵守)
  14. 1. **默认只做优雅关闭**:发送窗口关闭消息,等价于点右上角 ×。有未保存修改时,应用会自己弹「是否保存」,不会静默丢数据。
  15. 2. **绝不擅自 `--force-kill`**。只有用户明确说"强杀/结束进程/放弃修改",才可加这个参数;执行前再确认一次。
  16. 3. **绝不删除 `~$` 锁文件**。应用还开着时删锁文件可能损坏文档,脚本只报告、不处理。
  17. 4. **`needs_decision` / `needs_save_confirm` 必须交还给用户**:使用当前客户端提供的提问/选择界面,让用户选「保存并关闭 / 放弃修改并关闭 / 取消」。如果客户端没有这类工具,就在回复中列出三个选项并等待用户选择;不要自己替用户决定。
  18. 5. 被关闭的是**用户正在编辑的文档**,操作前先说明一句"检测到该文件正被 xxx 打开,我先帮你关掉",让用户有预期。
  19. ## 标准流程
  20. 本技能的所有命令都以 `SKILL.md` 所在目录为技能根目录。先解析出该目录,再执行:
  21. ```bash
  22. python scripts/unlock_file.py "<文件绝对路径>" --json
  23. ```
  24. 不要假定技能安装在某个固定路径(例如 `~/.claude/skills`);不同客户端的技能目录不同。如果你的运行环境不会自动把工作目录切到技能根目录,请先 `cd` 到本 `SKILL.md` 所在目录,或使用客户端提供的技能目录变量。
  25. 1. 执行上面的检测命令(默认就会尝试优雅关闭)。
  26. 2. 按返回的 `status` 处理:
  27. | status | 含义 | 下一步 |
  28. |---|---|---|
  29. | `not_locked` | 没被占用 | 直接重试原写入操作 |
  30. | `closed` | 已关闭,锁已释放 | 重试原写入操作,并告知用户文档已关闭 |
  31. | `needs_decision` | COM 能读到文档,但**有未保存修改** | 询问用户:保存并关闭 / 放弃修改关闭 / 取消 |
  32. | `needs_save_confirm` | 已发关闭请求,但仍锁着——多半弹了保存对话框 | 告诉用户在 WPS/Office 里点一下「保存」或「不保存」,然后重试 |
  33. | `locked_unknown` | 找不到可关的窗口(后台进程/其他软件占用) | 报告占用进程;询问用户是否允许 `--force-kill` |
  34. | `locked` | `--no-close` 模式下的检测结果 | 仅报告,不做处理 |
  35. | `not_found` | 路径不对 | 核对路径 |
  36. 3. 写入成功后,简要汇报:关掉了哪个文档、写入是否成功。
  37. ## 常用命令
  38. ```bash
  39. # 默认:检测 + 优雅关闭(推荐)
  40. python scripts/unlock_file.py "D:/x/报告.xlsx" --json
  41. # 只检测,不做任何关闭动作
  42. python scripts/unlock_file.py "D:/x/报告.xlsx" --no-close --json
  43. # 用户已同意“保存后关闭”(仅对 COM 能读到的文档有效)
  44. python scripts/unlock_file.py "D:/x/报告.xlsx" --save --json
  45. # 用户明确同意强杀(最后手段,会丢未保存修改)
  46. python scripts/unlock_file.py "D:/x/报告.xlsx" --force-kill --json
  47. ```
  48. 退出码:`0` 已解除/未占用,`2` 需要用户决定,`3` 无法安全解除,`1` 脚本错误。
  49. ## 实现说明(排障用)
  50. - **占用检测**:以写模式打开文件,捕获共享冲突。
  51. - **占用进程识别**:Windows Restart Manager API(`rstrtmgr.dll`),能识别 WPS 的 `et.exe` / `wps.exe` 等子进程。
  52. - **优雅关闭**:
  53. - 优先走 COM(`Excel.Application` / `KET.Application` / `Word.Application` / `KWps.Application` / `KWPP.Application`),能精确判断 `Saved` 状态并只关目标文档;
  54. - COM 不可用时按**窗口标题里的文件名**找窗口发 `WM_CLOSE`(WPS 是多进程架构,窗口进程 ≠ 持锁进程,按 PID 找会失败)。
  55. - **强杀**:`taskkill /F /PID`,仅在用户明确授权时使用。
  56. ## 典型场景
  57. > 用户:帮我把台账加上这两笔,但是 Excel 开着改不了。
  58. >
  59. > 助手:检测到文件正被 WPS 打开,我先帮你关掉再写。
  60. > → 执行脚本 → `closed` → 用 openpyxl 写入 → 回报"已关闭 WPS 中的台账并写入成功,重新打开即可看到"。
  61. > 返回 `needs_decision`(`modified: true`)
  62. >
  63. > 助手:台账里有未保存的修改,你要「保存并关闭」还是「放弃修改并关闭」?
README.md · README · 268 lines
  1. # unlock-file
  2. **让 AI agent 在写文件失败时,自动解除 Windows 文件占用。**
  3. 一个按 [Agent Skills](https://agentskills.io) 开放格式组织的技能:当 AI 改 Excel / Word / WPS 文件时报 `PermissionError`、`[WinError 32]`、`另一个程序正在使用此文件`,它会定位占用进程并**优雅关闭**文档,然后重试写入——不静默丢数据,不无脑强杀。
  4. > Windows 10 / 11 · Python 3.8+ · Excel / Word / WPS 均可
  5. >
  6. > 任何支持 Agent Skills 格式的客户端都可以加载;Claude Code 是其中之一。
  7. ---
  8. ## 痛点
  9. ```
  10. PermissionError: [WinError 32] 另一个程序正在使用此文件,进程无法访问。
  11. ```
  12. 你让 AI 往台账里加两行,但你正好开着 Excel 或 WPS。AI 写不进去,你也得手动关窗口、再让 AI 重试。每次都要来回一轮。
  13. 这个技能把这一轮自动化掉。
  14. ## 特性
  15. - **按需加载**:客户端根据 `description` 判断任务是否相关;是否自动调用由客户端决定
  16. - **三层定位**:写锁检测 → Restart Manager 查持锁进程 → COM / 窗口消息精准关闭
  17. - **WPS 适配**:处理 WPS 多进程架构(窗口进程 ≠ 持锁进程)的坑
  18. - **数据安全**:关闭前能读到 `Saved` 状态;有未保存修改时拒绝擅自关闭,改为询问用户
  19. - **零网络**:纯本地操作,不发任何请求、不上传任何内容
  20. ## 工作原理
  21. ```mermaid
  22. flowchart TD
  23. A[写入失败 / 文件被占用] --> B{能否以写模式打开?}
  24. B -- 能 --> Z[直接写入]
  25. B -- 不能 --> C[Restart Manager 定位持锁进程]
  26. C --> D{COM 能找到该文档?}
  27. D -- 能 --> E{有未保存修改?}
  28. E -- 无 --> F[COM 精确关闭该文档]
  29. E -- 有 --> G[返回 needs_decision<br/>由助手询问用户]
  30. D -- 不能 --> H[按窗口标题匹配文档窗口<br/>发送 WM_CLOSE]
  31. H --> I{锁已释放?}
  32. I -- 是 --> Z
  33. I -- 否 --> J[提示用户处理保存对话框]
  34. G --> F
  35. ```
  36. | 步骤 | 使用的能力 | 作用 |
  37. |---|---|---|
  38. | 1. 检测 | `open(path, "a+b")` | 捕获共享冲突,判断是否被占用 |
  39. | 2. 定位 | Restart Manager(`rstrtmgr.dll`) | 拿到持锁进程 PID 与应用名,WPS 子进程也能识别 |
  40. | 3. 关闭 | COM(Excel/Word/WPS)/ `WM_CLOSE` | 优先精确关闭单个文档;COM 不可用时退化为点击 × 的等价操作 |
  41. ## 安装
  42. ### 前置要求
  43. - Windows 10 / 11
  44. - Python 3.8+(已在 PATH 中)
  45. - 可选:`pywin32`(用于 COM 精确判断与关闭,缺失时自动退化为窗口消息)
  46. ```powershell
  47. python -m pip install pywin32
  48. ```
  49. ### 方式一:安装脚本
  50. ```powershell
  51. git clone https://github.com/xiaohudasb/unlock-file.git
  52. cd unlock-file
  53. powershell -ExecutionPolicy Bypass -File .\install.ps1
  54. ```
  55. 默认安装到 Claude Code 的用户技能目录:
  56. ```text
  57. %USERPROFILE%\.claude\skills\unlock-file
  58. ```
  59. 安装到其他 Agent Skills 客户端时,用 `-Dest` 指定该客户端的技能目录:
  60. ```powershell
  61. powershell -ExecutionPolicy Bypass -File .\install.ps1 -Dest "C:\path\to\skills\unlock-file"
  62. ```
  63. `-Dest` 的最后一级目录必须是 `unlock-file`,因为 Agent Skills 规范要求技能名与父目录同名。
  64. ### 方式二:手动安装
  65. 以 Claude Code 为例:
  66. ```powershell
  67. git clone https://github.com/xiaohudasb/unlock-file.git
  68. cd unlock-file
  69. $dest = "$env:USERPROFILE\.claude\skills\unlock-file"
  70. New-Item -ItemType Directory -Force -Path $dest | Out-Null
  71. Copy-Item -Force .\SKILL.md $dest
  72. Copy-Item -Recurse -Force .\scripts $dest
  73. ```
  74. 其他客户端:把仓库根目录(包含 `SKILL.md` 和 `scripts/`)复制或克隆到该客户端的技能目录,并确保最后一级目录名是 `unlock-file`。不同客户端使用不同的技能目录,具体位置请查阅对应客户端文档。
  75. 安装后重新打开客户端会话;是否自动出现在可用技能列表中,由客户端实现决定。
  76. ## 使用
  77. ### 在 Agent Skills 客户端中
  78. 支持自动加载的客户端会在任务匹配时读取本技能;不支持自动加载的客户端需要你手动触发,或把技能内容加入对话。核心命令相同,**在 `SKILL.md` 所在目录执行**:
  79. ```bash
  80. python scripts/unlock_file.py "D:/项目/台账.xlsx" --json
  81. ```
  82. 例如在 Claude Code 中,技能通常位于 `~/.claude/skills/unlock-file`:
  83. ```bash
  84. cd "$HOME/.claude/skills/unlock-file"
  85. python scripts/unlock_file.py "D:/项目/台账.xlsx" --json
  86. ```
  87. 也可以直接说:
  88. > 「台账被 WPS 占用了,帮我关掉再写」
  89. ### 命令行
  90. 以下命令在仓库根目录执行:
  91. ```bash
  92. # 默认:检测 + 优雅关闭
  93. python scripts/unlock_file.py "D:/项目/台账.xlsx" --json
  94. # 只检测,不关闭任何文件
  95. python scripts/unlock_file.py "D:/项目/台账.xlsx" --no-close --json
  96. # 有未保存修改时保存后关闭(仅 COM 路线有效)
  97. python scripts/unlock_file.py "D:/项目/台账.xlsx" --save --json
  98. # 强杀占用进程(最后手段,未保存修改会丢失)
  99. python scripts/unlock_file.py "D:/项目/台账.xlsx" --force-kill --json
  100. ```
  101. | 参数 | 说明 |
  102. |---|---|
  103. | `--json` | 输出机器可读 JSON |
  104. | `--no-close` | 只检测,不执行任何关闭动作 |
  105. | `--save` | 文档有未保存修改时先保存再关闭 |
  106. | `--force-kill` | `taskkill /F` 结束占用进程(危险,需人工确认) |
  107. ### 输出与退出码
  108. ```json
  109. {
  110. "file": "D:\\项目\\台账.xlsx",
  111. "status": "closed",
  112. "locked": false,
  113. "lock_files": ["D:\\项目\\~$台账.xlsx"],
  114. "owners": [
  115. { "pid": 13624, "process": "et.exe", "app": "WPS Spreadsheets" }
  116. ],
  117. "message": "已关闭文档窗口(若弹出过保存提示,说明已按提示处理)",
  118. "actions": ["WM_CLOSE -> 台账.xlsx - WPS Office"]
  119. }
  120. ```
  121. | 退出码 | 含义 |
  122. |---|---|
  123. | `0` | 未被占用 / 已成功解除 |
  124. | `2` | 需要用户决定(有未保存修改,或弹出了保存对话框) |
  125. | `3` | 被占用但无法安全自动解除 |
  126. | `1` | 脚本或环境错误 |
  127. ### status 对照
  128. | status | 含义 | 建议处理 |
  129. |---|---|---|
  130. | `not_locked` | 未被占用 | 直接重试写入 |
  131. | `closed` | 已关闭,锁已释放 | 重试写入 |
  132. | `needs_decision` | 有未保存修改 | 询问用户:保存并关闭 / 放弃修改 / 取消 |
  133. | `needs_save_confirm` | 已请求关闭但仍锁着 | 让用户在应用里点「保存 / 不保存」 |
  134. | `locked_unknown` | 找不到可关闭的窗口 | 报告进程;确认后再考虑 `--force-kill` |
  135. | `locked` | `--no-close` 的检测结果 | 仅参考 |
  136. | `not_found` | 路径不存在 | 核对路径 |
  137. ## 安全设计
  138. 这是本技能最看重的部分——**它操作的是你正在编辑的文档**:
  139. 1. **默认只做优雅关闭**:发送 `WM_CLOSE`,等价于点右上角 ×。应用自己决定是否弹保存提示,不会静默丢弃修改。
  140. 2. **有修改不擅自动手**:COM 能读到 `Saved == False` 时,脚本直接返回 `needs_decision`,由助手询问你。
  141. 3. **强杀需明确授权**:`--force-kill` 不会自动使用。
  142. 4. **不删除 `~$` 锁文件**:应用运行时删锁文件可能损坏文档,脚本只报告。
  143. 5. **不碰无关进程**:窗口匹配要求标题含目标文件名,且限制在已知 Office/WPS 窗口类;定位不到就停下报告。
  144. ## 兼容性
  145. ### 客户端
  146. | 客户端 | 说明 |
  147. |---|---|
  148. | Claude Code | `install.ps1` 默认安装到 `%USERPROFILE%\.claude\skills\unlock-file`;技能会自动加载 |
  149. | 其他支持 Agent Skills 的客户端 | 把仓库根目录复制到该客户端的技能目录;是否自动触发由客户端决定 |
  150. ### 系统与应用
  151. | 项目 | 支持情况 |
  152. |---|---|
  153. | Windows 10 / 11 | ✅ 已测试 |
  154. | Microsoft Excel / Word / PowerPoint | ✅ COM 路线 |
  155. | WPS 表格 / 文字 / 演示 | ✅ 已测试(COM + 窗口消息双路线) |
  156. | 其他占用文件的程序 | ⚠️ 能定位并报告进程,无法自动关闭 |
  157. | macOS / Linux | ❌ 依赖 Windows API(Restart Manager / `WM_CLOSE`) |
  158. > 开发环境:Windows 11 26200、WPS Office、Python 3.x、pywin32。不同 Office 版本的对象模型可能存在细微差异,欢迎提 Issue。
  159. ## 已知限制
  160. - **保存对话框需要人工确认**:文档有未保存修改且 COM 不可达时,WPS/Office 会弹窗等待点击,脚本只能提示你处理。
  161. - **WPS 的 COM 不稳定**:WPS 常常不注册到 ROT,`GetActiveObject` 会失败;此时自动退化为窗口消息路线(仍安全,但无法提前判断修改状态)。
  162. - **云文档 / 同步盘**:OneDrive、WPS 云文档可能在关闭后重新加锁。
  163. - **同名的多个窗口**:按标题匹配可能选中另一个同名文档,使用前请确认目标路径唯一。
  164. ## 目录结构
  165. ```
  166. unlock-file/
  167. ├── SKILL.md # Agent Skill 说明(触发条件、安全规则、工作流)
  168. ├── scripts/
  169. │ └── unlock_file.py # 检测与解除占用脚本
  170. ├── README.md
  171. ├── LICENSE
  172. ├── .gitignore
  173. └── install.ps1 # Windows 安装脚本
  174. ```
  175. ## 开发与测试
  176. ```bash
  177. # 1. 造一个被占用的测试文件
  178. python -c "import openpyxl; w=openpyxl.Workbook(); w.save('test.xlsx')"
  179. powershell -c "Start-Process test.xlsx" # 用 WPS/Excel 打开
  180. # 2. 只检测
  181. python scripts/unlock_file.py test.xlsx --no-close --json # 期望 exit=3, status=locked
  182. # 3. 解除
  183. python scripts/unlock_file.py test.xlsx --json # 期望 exit=0, status=closed
  184. # 4. 验证可写
  185. python -c "import openpyxl; w=openpyxl.load_workbook('test.xlsx'); w.save('test.xlsx')"
  186. ```
  187. ## English
  188. A portable Agent Skill for Windows that automatically releases file locks (Excel / Word / WPS) before an AI agent edits a file. It detects the lock, identifies the owning process via the Windows Restart Manager, and gracefully closes only the target document window. Unsaved changes are never discarded silently: the tool reports `needs_decision` so the user can choose. Force-kill is opt-in only. No network access.
  189. It follows the [Agent Skills](https://agentskills.io) open format (`SKILL.md` plus optional scripts) and can be loaded by any compatible client. Claude Code is one supported client.
  190. Install with `install.ps1` (defaults to Claude Code's `%USERPROFILE%\.claude\skills\unlock-file`), or copy this repository into your client's skills directory. The folder must be named `unlock-file`.
  191. ## License
  192. [MIT](LICENSE)
  193. ---
  194. 如果这个技能帮你省了几次「关窗口再重试」,欢迎点个 ⭐。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.