mcp-read-file-server 1.9.1 → 2.1.0

package/README.md

@@ -4,11 +4,26 @@
 
 加密环境文件操作工具。当 Node.js 是加密软件白名单进程时，通过 fs 模块自动解密读写文件明文，替代 AI Agent 内置文件工具，解决加密环境下读到密文的问题。适用于任何支持 MCP 协议的 AI Agent。
 
-**v1.7.0 环境自适应**：自动探测本机加密策略（哪些扩展名会被透明加密、哪些进程可用），对「会被加密且无法解密」的扩展名自动走 safeWrite 中转落盘明文，无需任何手工配置，换电脑自动重新探测。详见下文「环境自适应」。
+## 最新版本：2.1.0（相对 1.0）
 
-**v1.9.0 可回滚写入与目录级策略**：全部文本修改改为「完整载荷 → 独占暂存 → 独立指纹校验 → 原文件备份 → 提交 → 最终校验」事务流程，失败自动回滚，回滚失败保留 `recoveryPath`；加密策略按「目标目录 × 扩展名」实时探测，人工标注（`mark_extension`）独立持久化到 `.mcp-file-policies/`，刷新探测/重启/TTL 过期均不丢失；safeWrite 失败不再回退直写（保护原文）；复制/移动目录逐文件执行相同策略；所有工具返回统一 `structuredContent`（ok/code/changed/data/warnings）。
+本节以仓库 `v1.0` 标签（包版本 `1.0.0`）为基线，汇总当前版本的变化，不再逐条保留中间版本的更新说明。
 
-**v1.9.1 边界修复**：目录复制/移动拒绝双向祖先重叠，避免覆盖未读取的源文件；回滚失败和部分删源正确保留 `changed` / `partial`；行分页无法容纳首行时明确报错，到达请求结束行即停止解析，避免被范围外长行影响。Hono 间接依赖更新至 4.13.5。
+| 方面 | 1.0 | 2.1.0 |
+|------|-----|-------|
+| 文件写入 | 由 Node 直接读改写，依赖本机透明加密行为 | 统一暂存、备份、提交及终验；失败回滚，恢复失败保留 `recoveryPath` |
+| 加密策略 | 没有按原文件状态选择写入策略 | `auto` 比较原文件的 Node 与外部读取视图：原明文继续验证明文，原受保护文件保留受控写入；新建文件不凭 Node 可读就自动加密 |
+| 工具范围 | 8 个基础读写、搜索及目录工具 | 18 个工具，增加分页、列目录、文件查找、复制/移动/删除和 4 个策略诊断/管理工具 |
+| 编辑准确性 | 单次字符串或正则替换 | 批量原子编辑、CRLF/LF 适配、BOM 保留、预览、预期匹配数和 hash 冲突保护 |
+| 读取与性能 | 同步文件操作和基础搜索 | 异步 I/O、流式分页、有界输出；正则与字面量计算在可终止 worker 中执行；glob 累计预算并让出主线程 |
+| 并发与异常 | 基础异常返回 | 跨实例路径/子树锁；目录逐文件校验；部分完成、源保留、回滚和清理错误分别报告 |
+| 边界保护 | 主要依赖进程文件权限 | 可配置允许根、只读和禁删；识别真实路径/链接及受保护根；拒绝目录双向祖先重叠 |
+| 分发与验证 | 本地脚本启动，无仓库测试套件 | npm CLI 入口、模块化源码、结构化响应、回归/真实 stdio/Windows 适配测试及 CI；最低 Node.js 20 |
+
+**本次重点修复**：原始明文文件经 MCP 编辑后出现加密内容，而 Node 读回正常、IDEA 却显示密文。修复基于每个文件的写入前状态，适用于所有扩展名、未知后缀、无扩展名和点文件；不对 SCSS 做特殊判断。文本工具仍只接受有效 UTF-8，二进制文件通过复制/移动使用相同的提交保护。
+
+**累计修复与优化**：拒绝非法 UTF-8、UTF-16 和 NUL 文本的破坏性编辑；修复分页边界、换行匹配、复制移动重叠、并发追加及部分失败状态；安全中转失败不再回退直写；锁和临时文件清理失败不会掩盖主操作结果；工作线程和扫描预算防止复杂表达式阻塞服务。依赖锁定与 overrides 用于复现已验证的依赖树。
+
+**升级行为变化**：显式 `writePolicy` 优先，其次是持久人工策略，再由 `auto` 观察文件状态。Windows 的 `auto` 缺少可用外部读取器时返回 `DISK_UNVERIFIED`，不会猜测后继续写入；需要新建受保护文件时明确指定 `preserve` 或配置人工 `protected`。更新后重启全部 MCP 实例，并用 `check_status` 确认运行版本为 `2.1.0`。本地修改不会自动发布到 npm。
 
 ## 适用场景
 
@@ -40,45 +55,50 @@ AI Agent  --(MCP/stdio)-->  Node.js MCP Server(index.js)  --(lib/ 模块)-->  fs
 - `index.js` 仅负责 stdio 启动与正则 worker 回收
 - `lib/encryption.js` 目录级加密探测、写入策略决策、safeWrite 组合与独立指纹校验
 - `lib/files.js` 路径边界、跨实例锁、可回滚提交（暂存→备份→rename→终验）、目录逐文件复制/移动
+- `lib/locks.js` 登记路径及子树占用；`lib/cleanup.js` 保留主操作结果并收集清理错误
 - `lib/text.js` 严格 UTF-8 增量解码与流式分页
 - `lib/patterns.js` 无回溯 glob 与保留原索引的字符串替换
-- `lib/regex.js` / `lib/regex-worker.js` 用户正则在可终止 worker 中执行（默认 1 秒预算）
+- `lib/regex.js` / `lib/regex-worker.js` 用户正则与字面量编辑在可终止 worker 中执行（单次计算默认最多 1 秒，并受请求总预算约束）
 - `lib/server.js` 注册全部 18 个 MCP 工具，统一 structuredContent 与超时/只读包装
 
-## 环境自适应（v1.7.0+）
+## 环境自适应
 
 ### 解决的问题
 
-加密软件对「写入是否透明加密」是**按目标文件扩展名**决定的，且每台电脑的策略不同：
+加密行为可能随目录、文件类型和进程变化。Node 能读到明文，并不表示 IDEA 或其他编辑器也能解密。新建探测样本的分类只描述进程观察，不能替代原文件的状态：
 
-| 扩展名分类 | 含义 | 直写后果 | 本工具策略 |
-|-----------|------|---------|-----------|
-| **safe** | 写入后磁盘是明文 | 正常 | 直接写（原始行为） |
-| **protected** | 写入后磁盘是密文，但 Node.js 白名单读回自动解密 | 本机正常 | 直接写（保持加密保护） |
-| **unsafe** | 写入后被加密，但该类型不在保护列表，**任何进程都无法解密** | 磁盘密文乱码，文件损坏 | 自动走 safeWrite |
+| 探测分类 | 实际观察 | 新建文件的 auto 策略 |
+|----------|----------|----------------------|
+| **safe** | Node 和外部读取视图均与探测载荷一致 | 允许先写暂存文件，暂存及最终路径仍须通过明文校验 |
+| **protected** | Node 读回正确，外部读取视图不同 | 不推断其他编辑器可解密，使用安全中转并验证明文 |
+| **unsafe** | Node 读回已经与探测载荷不同 | 使用安全中转并验证明文 |
+| **unknown** | 无法取得外部读取结果 | 不能宣称安全；有读取器时只允许通过严格明文校验后提交 |
+
+已有文件的状态不缓存、不按后缀共享：每次 `auto` 都比较该文件的 Node 指纹与外部进程指纹。两者一致时要求明文提交；两者不同时走受控写入，并检查外部视图没有意外变成预期明文。复制/移动覆盖已有目标时参考目标状态，新目标参考源文件状态；目录内逐文件执行。
 
 ### safeWrite 原理
 
-对 unsafe 扩展名目标，写入流程自动切换为：
+明文暂存写入出现内容不一致、目录探测不适合直接写入，或明确要求安全中转时，流程切换为：
 
 ```
-1. 写入 目标目录下 .mcp-safe-<uuid><安全扩展名> 的随机临时文件（安全类型 → 磁盘明文）
-2. 用探测到的可用外部进程（powershell/pwsh/cmd/robocopy/cscript）复制临时文件到目标路径
-   （外部进程不在白名单内，复制动作不触发透明加密 → 目标落盘为明文）
-3. 用独立读取器（PowerShell 流式 SHA256+size）校验目标文件磁盘指纹为明文
+1. 写入目标目录下 .mcp-safe-<uuid><候选扩展名> 的随机临时文件，并验证其内容
+2. 用可用外部进程（powershell/pwsh/cmd/robocopy/cscript）复制到 .mcp-stage-<uuid><目标扩展名>
+3. 用Node和外部读取器（PowerShell 流式 SHA256+size）验证暂存文件与预期载荷一致
 4. 清理临时文件
 5. 失败则遍历全部「安全扩展名 × 可用进程」组合重试；
-   v1.9.0 起全部失败直接报错（SAFE_WRITE_FAILED），原文件保持不变，不再回退直写
+   全部失败直接报错（SAFE_WRITE_FAILED），不再回退未经验证的写入
 ```
 
+暂存成功后仍需 rename 提交及最终路径校验，最终校验失败会回滚。外部进程是否会加密、是否会自动解密均不能仅凭进程名称判断；上述校验是进程可见字节对照，不是绕过驱动读取原始磁盘。
+
 ### 探测与缓存
 
-- **首次启动（或缓存失效）自动探测**：在系统临时目录用候选扩展名写入探测样本，通过「Node 读回对比 + 独立进程读磁盘指纹」分类；再探测可用的外部进程并做复制交叉验证
-- **目录级实时探测（v1.9.0）**：具体写入前按「目标目录 × 扩展名」在该目录内创建随机探测样本（`.mcp-probe-<uuid><ext>`，写完即删）实时分类，结果缓存在内存 scopes 中——加密策略按目录生效时结果也准确
-- **自动缓存位置**：`~/.mcp-encryption-profile.json`（结构 v3），按 machineId（hostname+username 哈希）绑定，**换电脑/换用户自动重新探测**；缓存有效期 30 天；v1/v2 旧缓存自动作废（v2 中的人工 protected 标注会一次性迁移到独立策略目录）
+- **首次需要自动策略（或缓存失效）时探测**：在系统临时目录用候选扩展名写入样本，通过 Node 与外部进程指纹对照分类，并探测可用复制进程
+- **目录级探测**：无原文件或复制源状态可参考的新建路径，按「目标目录 × 扩展名」创建随机样本（`.mcp-probe-<uuid><ext>`，写完即删），观察缓存在内存 scopes 中。已有文件优先逐文件观察，不受旧目录分类覆盖
+- **自动缓存位置**：`~/.mcp-encryption-profile.json`（结构 v3），按 machineId（hostname+username 哈希）绑定，换电脑/换用户重新探测；有效期 30 天。兼容有效的 v2/v3 缓存，丢弃旧 scopes；v2 人工 protected 一次性迁移到独立策略目录
 - **人工策略独立存储**：`~/.mcp-file-policies/` 每个扩展名一个文件，刷新探测、TTL 过期、服务重启都不会删除人工标注
 - **查看/刷新**：用 `encryption_profile` 工具查看当前探测结果与人工策略；加密策略变更后用 `refresh_profile` 强制重探（只刷新自动探测，不动人工策略）；`inspect_write_strategy` 可预览某个目标路径将采用的写入策略而不修改目标文件
-- **无外部进程可用时**（如进程被策略禁止 spawn）：普通写入仍以 Node 侧指纹校验内容一致；强制 `writePolicy=plaintext` 时会明确报 `DISK_UNVERIFIED` 而不会谎称已落盘明文
+- **无外部读取器时**：Windows 的 auto 返回 `DISK_UNVERIFIED`；非 Windows 且没有该后缀的加密观察时保留 Node 内容校验，返回 unknown 并告警。显式 plaintext 在所有平台都必须有可用外部读取器。配置过的读取器临时失败时不得降级为成功
 
 ### 写入策略（writePolicy）
 
@@ -86,21 +106,23 @@ write_file / edit_file / copy_path / move_path 均支持 `writePolicy` 参数：
 
 | 值 | 语义 |
 |----|------|
-| `auto`（默认） | 人工标注优先；否则按目标目录实时探测：safe 直写、protected 直写保持加密、unsafe 走 safeWrite |
-| `preserve` | 显式保持受控加密直写（等同人工标注 protected 的当次效果） |
-| `plaintext` | 强制磁盘明文：必须经 safeWrite 且由独立读取器验证完整磁盘指纹，验证失败则中止并保留原文件 |
+| `auto`（默认） | 人工标注优先；否则原明文要求明文终验，原受保护文件保留受控写入；新文件要求明文，不自动沿用探测样本的加密状态 |
+| `preserve` | 显式受控写入，经暂存替换并校验 Node 内容；不保证原来的明文状态，也不保证其他编辑器能解密 |
+| `plaintext` | 显式安全中转，必须验证暂存及最终路径的外部指纹与预期明文一致；失败中止或回滚 |
+
+返回的 `strategy.basis` 区分 `explicit`（本次显式策略）、`override`（人工标注）、`target`（原目标）、`source`（新复制目标的源）、`new_file`（全新文件）和 `unverified`。`originalState` 记录自动决策依据；`category` 描述观察结果，不是编辑器兼容性认证。`user_unsafe` 在显式 plaintext 下也会返回，不表示新增了永久标注。
 
 ### mark_extension 手动标注
 
-当自动分类不符合预期时手动干预（标注优先级高于一切自动分类，独立持久化，重启/刷新不丢失）：
+当需要固定某类文件的写入方式时手动标注（本次显式 writePolicy 优先，其次人工标注，再次自动状态判断；标注持久化，重启/刷新不丢失）：
 
 | 场景 | 调用 | 效果 |
 |------|------|------|
-| `.java` 需要保持 TSD 加密（受控文档） | `mark_extension(".java", "protected")` | auto 策略下直写保持加密，Notepad 打开正常 |
-| `.scss` 必须保持明文（自动误判） | `mark_extension(".scss", "unsafe")` | auto 策略下强制走 safeWrite 保持明文 |
+| `.java` 需要受控写入 | `mark_extension(".java", "protected")` | auto 采用 preserve；仍需确认实际使用的编辑器能正常读取 |
+| `.custom` 需要固定明文写入 | `mark_extension(".custom", "unsafe")` | auto 强制使用安全中转及明文校验 |
 | 恢复自动分类 | `mark_extension(".java", "clear")` | 写入墓碑清除标注，恢复实时探测 |
 
-## 写入保证（v1.9.0）
+## 写入保证
 
 所有文本修改（write_file / edit_file）与文件复制/移动都经过统一的可回滚提交流程：
 
@@ -109,16 +131,22 @@ write_file / edit_file / copy_path / move_path 均支持 `writePolicy` 参数：
   → 同目录随机独占暂存 .mcp-stage-<uuid><ext>（外部进程中转时经安全扩展名）
   → fsync 刷盘 → 再次比对改前指纹（防并发改动）
   → 原文件 rename 为 .mcp-backup-<uuid><ext> → 暂存 rename 到位
-  → 独立指纹终验（SHA256+size；有独立读取器时含磁盘原始字节）
+  → 指纹终验（SHA256+size；自动状态策略同时检查外部读取视图）
   → 成功删除备份；任一步失败自动回滚，回滚失败返回 recoveryPath（备份不得删除）
 ```
 
 - **完整载荷**：追加模式先在内存合成「原内容+新增」完整内容再走事务，纠正/重写不会丢原文与 BOM
 - **safeWrite 失败即中止**：不再回退直写破坏原文（SAFE_WRITE_FAILED，changed=false）
-- **跨实例锁**：同一路径的并发写入经 `.mcp-file-locks/` 互斥（等待 5 秒超时 FILE_BUSY）；`expectedHash` 可检测其他编辑器造成的版本变化（CONFLICT）
+- **跨实例锁**：使用同一 `MCP_PROFILE_DIR` 的实例经 `.mcp-file-locks/` 登记整组路径，同路径及祖先/后代相互排斥，无关路径可并行（等待 5 秒超时 FILE_BUSY）；`expectedHash` 可检测其他编辑器造成的版本变化（CONFLICT）。升级时应重启全部 MCP 实例，避免旧进程继续执行旧的锁和写入策略
+- **清理状态**：提交或锁清理失败会附带 `cleanupErrors`；主操作已成功时保留成功结果和真实 `changed`，错误时保留原错误及 `recoveryPath`。不要因清理告警重复追加内容
+- **递归删除**：逐项执行，失败时返回 `changed`、`partial`（最多100项）、`removedCount`、`partialTruncated`、`failedPath`；受一万项和128层预算限制，不是整树事务
 - **断电/强杀残留**：两次 rename 之间的极端崩溃可能留下 `.mcp-backup-*` 与 `.mcp-stage-*`，先核对内容与时间再人工恢复，禁止直接批量清理
 - **复制/移动目录**：逐文件执行相同策略；移动先复制并二次比对指纹后再删除已验证的源文件；失败返回 `partial` 与 `sourceRetained`，不静默回退；符号链接明确拒绝；源和最终目标存在任一方向的祖先关系时拒绝，相同路径保持不变。回滚失败时 `changed=true`，`partial` 包含当前失败目标，原备份通过 `recoveryPath` 返回
-- **diskState 三态**：`plaintext`（独立进程验证磁盘明文）、`preserved`（保持加密直写）、`unknown`（内容已校验但无独立读取器证明磁盘状态——不能当作「已证明明文」）
+- **移动失败的源变化**：`sourceRetained` 表示本次是否尚未删除任何源文件或源目录；`removedSourceCount`、`removedSourcePaths`（最多100项）、`removedSourcePathsTruncated` 报告已经删除的源项。失败仍保留已完成子项的 `cleanupErrors`
+- **策略探测互斥**：`inspect_write_strategy` 持有目标父目录锁，创建和清理探测样本完成后才允许该目录被复制、移动或删除
+- **glob总预算**：生产搜索与查找使用异步匹配，合并重复模式和分支；一次请求的展开后累计长度最多10万，编译和全部路径匹配共用5000万工作单元预算。约每16384工作单元让出事件循环，检查取消与截止时间；超过限额返回 `GLOB_LIMIT`，超时返回 `TIMEOUT`
+- **diskState 三态**：`plaintext`（Node 与外部视图均匹配预期明文）、`preserved`（Node 内容通过受控写入校验，不保证其他编辑器可解密）、`unknown`（仅内容校验，不能声称已验证明文）。自动保留原保护状态还返回 `protectionObserved:true`，表示外部视图仍不同，并非密钥或加密完整性认证
+- **校验边界**：如果外部读取器也被透明解密，两种视图一致仍不能证明原始磁盘未加密。上线前用真实驱动及目标编辑器验收；已经损坏或已经加密的异常文件不会因升级而自动修复
 
 ## 文件结构
 
@@ -381,23 +409,23 @@ find_files 之外的文件名查找也优先用 MCP 工具。
 - 建目录/查信息   → create_directory / file_info
 
 ## 使用规则
-1. 会话开始先调 check_status 确认白名单解密正常；环境不明时调
+1. 会话开始先调 check_status 确认服务版本与运行状态；它不自动证明解密正常。环境不明时调
    encryption_profile 查看本机扩展名分类与人工策略；
    写入前可用 inspect_write_strategy 预览目标路径的写入策略。
-2. 写任何扩展名的文件都不用关心加密细节：write_file/edit_file/copy_path/
-   move_path 默认 writePolicy=auto，按目标目录实时探测并自动选择直写或
-   safeWrite；需要保持加密用 writePolicy=preserve，需要强制磁盘明文用
-   writePolicy=plaintext（失败会中止并保留原文件，不会回退直写）。
+2. write_file/edit_file/copy_path/move_path 默认 writePolicy=auto：
+   原明文文件保持明文校验，原受保护文件保持受控写入，新文件默认要求明文。
+   明确需要受控写入用 preserve，明确需要明文用 plaintext。
+   preserved 不证明 IDEA 等其他程序能解密；Windows 缺少外部读取器时 auto 拒绝写入。
 3. 需要长期保持加密/明文的扩展名：用 mark_extension(".java", "protected")
-   或 mark_extension(".scss", "unsafe") 标注一次永久生效（独立存储，
+   或 mark_extension(".custom", "unsafe") 标注一次永久生效（独立存储，
    重启与刷新探测不丢失）；mark_extension(".ext", "clear") 恢复自动。
 4. edit_file 前必须先 read_file 拿原文，oldString 从原文原样复制
    （含空格与缩进；CRLF/LF 换行差异会自动兼容，无需手工处理）；
    重要修改先 dryRun=true 预览；可用 expectedHash 防止覆盖他人改动。
 5. 路径一律使用绝对路径。
 6. 写工具返回 isError 时先看 structuredContent 的 code：
-   SAFE_WRITE_FAILED/DISK_MISMATCH 说明明文落盘失败（原文件未动），
-   先调 refresh_profile 重新探测再重试；出现 recoveryPath 说明回滚
+   SAFE_WRITE_FAILED/DISK_MISMATCH 表示写入校验失败；检查 changed 和恢复信息，
+   不要改用普通 shell 覆盖。出现 recoveryPath 说明回滚
    也失败，保留该备份并报告用户，禁止盲目重试或删除备份。
 7. edit_file 匹配失败时，按返回的「可能相关的行」诊断修正 oldString，
    不要盲目重试。
@@ -489,15 +517,15 @@ npm test         # 仓库内回归/协议/适配测试（Node 内置 test runner
 npm audit --omit=dev
 ```
 
-测试位于 `test/`（regression/protocol/adapters 三个套件，模拟磁盘错误与真实 stdio 协议分离，不触碰真实 profile）；CI 覆盖 Windows/Linux × Node 20/22/24。运行依赖：MCP SDK 1.30.0、Zod 4.4.3（间接依赖 fast-uri/qs 通过 overrides 限定修复版本）。
+测试位于 `test/`，包含基础回归、真实 stdio、Windows 适配器、边界/并发修复以及 `write-policy.test.js` 通用写入状态回归；模拟读取视图与真实驱动验收分开，不触碰真实 profile。可通过 `MCP_TEST_ROOT` 指定独立测试目录。CI 配置覆盖 Windows/Linux × Node 20/22/24。运行依赖：MCP SDK 1.30.0、Zod 4.4.3，间接依赖 fast-uri/qs/Hono 通过 overrides 限定修复版本。
+
+本次自动化验收计划见 `test/write-policy-plan.md`。真实加密电脑需分别检查原始明文样本及原受保护样本；先确认基线，再用 auto 编辑并从磁盘重新打开，核对实际编辑器结果。模拟测试通过不等于真实驱动全部兼容。
 
 ## 故障排查
 
 ### 读取到的仍是密文
 
-说明 Node.js 未被加密软件列为白名单。解决方法：
-- 联系加密软件管理员，将 `node.exe` 加入白名单
-- 确认加密软件的受信任进程列表中包含 Node.js
+可能是 Node.js 未被授权解密，也可能是该文件类型、路径或原文件状态不满足解密条件。先保留原文件，确认运行入口与实际 `node.exe` 路径，再核对加密软件配置；不能只凭“程序在白名单”就认定所有文件均可解密。
 
 ### MCP Server 无法启动
 
@@ -510,21 +538,26 @@ cd mcp-read-file-server && npm ci
 echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node index.js
 ```
 
-### 写入 .scss/.css 等文件后显示乱码（密文）
+### MCP 返回成功，但编辑器打开显示密文
 
-该扩展名在本机属于 unsafe 类型（加密但不自动解密）。v1.7.0+ 会自动走 safeWrite 规避；若仍出现乱码：
+Node 可读不等于其他编辑器可读，不能只凭锁图标判断状态。当前版本对所有文件类型统一处理原明文状态，不需要为 SCSS 等后缀写特例。若仍出现异常：
 
-1. 调 `refresh_profile` 强制重新探测（策略可能变更或缓存过期）
-2. 调 `encryption_profile` 确认该扩展名分类与可用外部进程；或对该扩展名直接 `mark_extension(".scss", "unsafe")` 强制明文
-3. 若显示「可用外部进程: （无）」，说明 MCP Server 进程被策略禁止 spawn 子进程，需联系管理员放行 powershell/cmd，或接受直写加密后由白名单应用打开
+1. 用 `check_status` 确认实际服务为 2.1.0，保留异常文件和当次完整响应，不直接覆盖修复。
+2. 查看 `strategy.basis/originalState`、`diskState/diskVerified` 和 warnings，确认是否有显式 preserve 或人工 protected 覆盖自动决策。
+3. 使用独立副本验证所需策略，并检查外部读取器是否同样被透明解密。已经异常的受保护文件不会被 auto 自动解密；需要恢复时先核对原始备份。
 
 ### 写工具返回 SAFE_WRITE_FAILED / DISK_MISMATCH
 
-v1.9.0 起 safeWrite 失败**不再回退直写**（保护原文件，返回 `changed:false`）。说明所有「安全扩展名 × 外部进程」组合都验证失败（常见原因：外部进程对目标目录无写权限，或独立读取器验证磁盘指纹不一致）。处理：调 `refresh_profile` 重探；检查目标目录权限；确认 powershell/cmd 可被执行；换目录重试。
+safeWrite 全部组合失败返回 `SAFE_WRITE_FAILED`；最终路径校验不一致返回 `DISK_MISMATCH` 并尝试回滚。不回退未经验证的写入，是否恢复成功以 `changed/recoveryPath/rollbackError` 为准。检查目标目录权限、外部进程可用性和实际读取视图；环境已发生变化时再考虑 `refresh_profile` 重探。
+
+### 写工具返回 DISK_UNVERIFIED / PROTECTION_MISMATCH
+
+- `DISK_UNVERIFIED`：无法取得所需外部读取视图。Windows auto 不能据此猜测原文件状态；检查读取器可用性，不要为了通过测试盲目切到 preserve。
+- `PROTECTION_MISMATCH`：自动保留受保护文件时，暂存或最终目标的外部视图变成了预期明文；为避免静默改变保护状态而中止或回滚。确实需要明文时应明确指定 plaintext，并用独立样本验证。
 
 ### 写工具返回 FILE_BUSY / CONFLICT
 
-- `FILE_BUSY`：另一个 MCP 实例正在写同一路径（锁位于 `~/.mcp-file-locks/`）。确认对方进程结束后重试；仅当确认锁属主进程已退出时才可人工删除残留锁文件
+- `FILE_BUSY`：另一个 MCP 实例正在操作同一路径、父目录或子路径（锁位于 `~/.mcp-file-locks/`）。确认对方进程结束后重试；异常退出时仅在核对记录中的 PID 后处理残留 `.lock` 或 `.registry-guard`。`LOCK_CLEANUP_FAILED` 和 `cleanupErrors` 会给出未清理路径，不应直接清空整个锁目录
 - `CONFLICT`：传入的 `expectedHash` 与文件当前指纹不一致——文件在您读取后被其他进程改过。重新 read_file 后再编辑
 
 ### 回滚失败返回 recoveryPath

package/SKILL.md

@@ -5,7 +5,7 @@ description: 在Node.js为加密软件白名单进程的环境中，使用文件
 
 # 加密环境文件操作
 
-使用前确认Node.js受信任，并配置read-file-server。版本1.9.0提供18个工具，最低Node20。
+使用前确认Node.js受信任，并配置read-file-server。版本2.1.0提供18个工具，最低Node20。
 
 ## 工具选择
 
@@ -20,8 +20,8 @@ description: 在Node.js为加密软件白名单进程的环境中，使用文件
 ## 必须理解的结果
 
 1. 优先读取structuredContent的ok、code、changed、data和warnings，不能只看人类文本。
-2. isError=true时可能存在目录操作部分目标；查看partial/sourceRetained。单文件回滚失败时查看recoveryPath并保留备份。
-3. contentVerified表示Node可见内容一致；diskVerified才表示独立读取器的完整磁盘指纹一致。unknown不能声称已落盘明文。
+2. isError=true时可能存在目录操作部分目标；查看changed/partial/sourceRetained。递归删除还需查看removedCount/partialTruncated/failedPath。单文件回滚失败时查看recoveryPath并保留备份。cleanupErrors只是清理诊断，成功修改后不得因清理告警重复追加。
+3. contentVerified表示Node可见内容一致；diskVerified表示外部进程可见字节也与预期载荷一致，不是绕过透明解密读取原始磁盘。preserved不保证IDEA等其他程序能解密，unknown不能声称已验证明文。
 4. check_status基础调用不探测环境。文件可读取也不能直接推断解密正常，可信expectedHash匹配才提供明确内容对照。
 5. 文本工具只支持有效UTF8；UTF16、GBK、非法字节或NUL被拒绝时，必须先明确转换编码，不能强制按UTF8写回。
 
@@ -29,7 +29,11 @@ description: 在Node.js为加密软件白名单进程的环境中，使用文件
 
 - mark_extension(category=protected)永久记录保持受控写入，等价于默认使用preserve；unsafe要求验证磁盘明文；clear可清除两者。
 - refresh_profile只更新自动观察，不删除手工策略。
-- writePolicy=auto按目标目录探测；protected保持受控写入，unsafe安全中转。显式plaintext必须验证成功，失败保留原文件。
+- writePolicy=auto在没有人工覆盖时逐文件观察原状态：原明文保持明文校验，原受保护文件保持受控写入；新文件默认要求明文，不凭探测样本的protected分类自动加密。所有扩展名及无后缀文件使用同一规则。
+- 复制/移动覆盖已有目标参考目标原状态；新目标参考源状态。目录逐文件判断，不能拿一个后缀的探测结果代替所有文件的基线。
+- 显式writePolicy优先于人工标注；preserve只校验Node内容并告警，不保证原明文状态或编辑器可读。plaintext要求外部明文验证，失败中止或回滚。
+- strategy.basis说明explicit/override/target/source/new_file/unverified；originalState记录auto观察到的基线，文件状态不缓存。user_unsafe也可能只是当次显式plaintext，不代表新增永久标注。
+- Windows auto缺少外部读取器时返回DISK_UNVERIFIED；已配置读取器但本次读取失败也中止。PROTECTION_MISMATCH表示原受保护文件将意外变为明文；不得绕过错误继续写入。
 - 旧v2人工unsafe和自动encrypted记录无法区分；升级后需要永久强制明文的后缀应重新标注unsafe。protected会迁移。
 - 使用绝对路径；相对路径以MCP_BASE_DIR或服务启动目录为基准。
 

package/lib/cleanup.js

@@ -0,0 +1,34 @@
+/** 清理只收集自身错误，不覆盖主操作结果或恢复信息。 */
+const fs = require('node:fs/promises');
+const { READ_LIMIT, safeEnd } = require('./text');
+
+/** 尝试删除全部指定临时文件，并返回有界的清理诊断。 */
+async function cleanupFiles(paths) {
+  const errors = [];
+  for (const file of paths) {
+    try { await fs.rm(file, { force: true }); }
+    catch (error) { errors.push({ path: file, code: error.code || 'CLEANUP_FAILED', message: error.message }); }
+  }
+  return errors;
+}
+
+/** 失败保留主异常，成功则附加清理告警；兼容文件结果与MCP响应。 */
+function finishCleanup(value, failure, errors) {
+  if (failure) {
+    if (errors.length) failure.cleanupErrors = [...(failure.cleanupErrors || []), ...errors].slice(0, 100);
+    throw failure;
+  }
+  if (!errors.length) return value;
+  const response = value.structuredContent;
+  const data = response ? response.data : value;
+  data.cleanupErrors = [...(data.cleanupErrors || []), ...errors].slice(0, 100);
+  const warning = '操作已完成，但有临时文件或锁未能清理；请查看cleanupErrors，不要重复提交已完成的修改';
+  if (response) {
+    response.warnings = [...response.warnings, warning];
+    const body = value.content.find(item => item.type === 'text');
+    if (body) body.text = body.text.slice(0, safeEnd(body.text, READ_LIMIT)) + '\n注意：' + warning;
+  } else value.warnings = [...(value.warnings || []), warning];
+  return value;
+}
+
+module.exports = { cleanupFiles, finishCleanup };

package/lib/encryption.js

@@ -48,7 +48,7 @@ function execute(exe, args, options = {}) {
   });
 }
 
-/** 流式计算磁盘原始字节指纹；外部进程不可用时返回未知，不认证明文。 */
+/** 流式计算外部进程可见字节指纹；普通文件读取仍可能受透明解密影响。 */
 async function inspectDisk(proc, file, options = {}) {
   if (!proc) return null;
   const code = "$ErrorActionPreference='Stop';$f=[IO.File]::OpenRead(" + quote(file) + ');try{' +
@@ -235,25 +235,60 @@ function createEncryption(options = {}) {
     return fresh;
   }
 
-  /** 解析显式策略与人工覆盖；未知目录在写入前用独立样本探测。 */
-  async function strategy(file, requested = 'auto', context = {}) {
+  /** 比较同一文件的Node与外部读取视图，并拒绝读取期间发生的内容变化。 */
+  async function observe(file, expected, profile, context) {
+    const external = await reader(profile.byteReader, file, context);
+    checkBudget(context.signal, context.deadline);
+    if (!external) throw fault('DISK_UNVERIFIED', '无法确认写入前的文件状态，未提交修改');
+    const current = await fingerprint(file, context);
+    if (current.hash !== expected.hash || current.size !== expected.size) throw fault('CONFLICT', '文件在状态检查期间已改变，未提交修改');
+    return external.hash === expected.hash && external.size === expected.size ? 'plaintext' : 'protected';
+  }
+
+  /** 显式策略优先；auto按原文件状态决策，新复制目标参考源文件，新建文件要求明文校验。 */
+  async function strategy(file, requested = 'auto', context = {}, reference = {}) {
     const ext = path.extname(file).toLowerCase();
     const override = await getOverride(ext);
-    if (requested === 'preserve' || (requested === 'auto' && override === 'protected')) return { mode: 'preserve', category: 'user_protected', extension: ext };
-    if (requested === 'plaintext' || (requested === 'auto' && override === 'unsafe')) return { mode: 'plaintext', category: 'user_unsafe', extension: ext };
+    const basis = requested === 'auto' ? 'override' : 'explicit';
+    if (requested === 'preserve' || (requested === 'auto' && override === 'protected')) return { mode: 'preserve', category: 'user_protected', extension: ext, basis };
+    if (requested === 'plaintext' || (requested === 'auto' && override === 'unsafe')) return { mode: 'plaintext', category: 'user_unsafe', extension: ext, basis };
     const p = await getProfile(context);
     const dir = await fs.realpath(path.dirname(file));
+    if (!p.byteReader) {
+      // Windows透明加密环境中，缺少外部视图时不能猜测原文件状态并继续写入。
+      if (process.platform === 'win32' || p.unsafeExtensions.includes(ext) || p.encryptedExtensions.includes(ext) || p.protectedExtensions.includes(ext)) {
+        throw fault('DISK_UNVERIFIED', 'auto需要可用的外部读取器判断文件状态；请检查环境或明确指定writePolicy');
+      }
+      return { mode: 'auto', category: 'unknown', extension: ext, scope: dir, basis: 'unverified', originalState: 'unknown' };
+    }
+    let original = reference.target;
+    if (original === undefined) {
+      try {
+        if (!(await fs.stat(file)).isFile()) throw fault('NOT_FILE', '目标不是普通文件');
+        original = await fingerprint(file, context);
+      } catch (error) { if (error.code !== 'ENOENT') throw error; original = null; }
+    }
+    const source = !original && reference.source;
+    const expected = original || source?.fingerprint;
+    if (expected) {
+      const originalState = await observe(source ? source.file : file, expected, p, context);
+      return { mode: originalState === 'plaintext' ? 'plaintext' : 'preserve',
+        verifyMode: originalState === 'plaintext' ? 'plaintext' : 'protected',
+        allowDirect: true, category: originalState === 'plaintext' ? 'safe' : 'protected',
+        extension: ext, scope: dir, basis: source ? 'source' : 'target', originalState };
+    }
     const key = dir + '|' + ext;
     let category = p.scopes[key];
     if (!category) {
-      category = await classify(ext || '.mcp-noext', dir, p, context);
+      category = await classify(ext, dir, p, context);
       if (category === 'unknown' && (p.unsafeExtensions.includes(ext) || p.encryptedExtensions.includes(ext))) category = 'unsafe';
       p.scopes[key] = category;
     }
-    return { mode: category === 'unsafe' ? 'plaintext' : category === 'protected' ? 'preserve' : 'auto', category, extension: ext, scope: dir };
+    // 新建样本中的Node可读不代表IDEA等其他程序也可读，不能据此自动选择preserve。
+    return { mode: 'plaintext', allowDirect: category === 'safe', category, extension: ext, scope: dir, basis: 'new_file', originalState: 'missing' };
   }
 
-  /** 校验 Node 可见内容和原始磁盘状态，unknown 从不声称已验证明文。 */
+  /** 校验进程可见内容；自动保留受保护状态时还要求外部视图保持不同，不能证明其他编辑器可解密。 */
   async function verify(file, expected, mode, context = {}) {
     const own = await fingerprint(file, context);
     if (own.hash !== expected.hash || own.size !== expected.size) throw fault('CONTENT_MISMATCH', '写入内容校验不一致');
@@ -261,19 +296,25 @@ function createEncryption(options = {}) {
     const p = await getProfile(context);
     const raw = await reader(p.byteReader, file, context);
     if (!raw) {
-      if (mode === 'plaintext' || p.byteReader) throw fault('DISK_UNVERIFIED', '无法验证磁盘明文状态，保留原文件');
+      if (mode === 'plaintext' || mode === 'protected' || p.byteReader) throw fault('DISK_UNVERIFIED', '无法验证外部读取视图，保留原文件');
       return { contentVerified: true, diskState: 'unknown', diskVerified: false };
     }
+    if (mode === 'protected') {
+      if (raw.hash === expected.hash && raw.size === expected.size) throw fault('PROTECTION_MISMATCH', '原受保护文件的外部读取视图变为明文，已拒绝提交');
+      return { contentVerified: true, diskState: 'preserved', diskVerified: false, protectionObserved: true };
+    }
     if (raw.hash !== expected.hash || raw.size !== expected.size) throw fault('DISK_MISMATCH', '磁盘字节与预期明文不一致');
     return { contentVerified: true, diskState: 'plaintext', diskVerified: true };
   }
 
   /** 为目标生成可校验的暂存文件；所有候选失败即中止，禁止回退破坏原文。 */
   async function prepare(stage, write, expected, decision, context = {}) {
-    if (decision.mode !== 'plaintext') {
+    if (decision.mode !== 'plaintext' || decision.allowDirect) {
       await write(stage);
-      try { return await verify(stage, expected, decision.mode, context); }
-      catch (error) { if (error.code !== 'DISK_MISMATCH' || decision.mode === 'preserve') throw error; }
+      try { return await verify(stage, expected, decision.verifyMode || decision.mode, context); }
+      catch (error) {
+        if (decision.mode === 'preserve' || !['DISK_MISMATCH', 'CONTENT_MISMATCH'].includes(error.code)) throw error;
+      }
       await fs.rm(stage, { force: true });
     }
     const p = await getProfile(context);

package/lib/files.js

@@ -4,18 +4,9 @@ const nativeFs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { pipeline } = require('node:stream/promises');
-const { setTimeout: delay } = require('node:timers/promises');
-const { performance } = require('node:perf_hooks');
 const { fault, fingerprint, payloadFingerprint, checkBudget } = require('./text');
-
-/** 对 Windows 文件路径统一大小写，用于同一路径和锁键比较。 */
-function pathKey(file) { return process.platform === 'win32' ? path.resolve(file).toLowerCase() : path.resolve(file); }
-
-/** 判定 candidate 是否等于 base 或位于其子树，避免字符串前缀误判。 */
-function inside(base, candidate) {
-  const rel = path.relative(pathKey(base), pathKey(candidate));
-  return rel === '' || (!rel.startsWith('..' + path.sep) && rel !== '..' && !path.isAbsolute(rel));
-}
+const { createLocker, pathKey, inside } = require('./locks');
+const { cleanupFiles, finishCleanup } = require('./cleanup');
 
 /** 从最近存在的祖先解析真实路径，识别目录符号链接和 junction 越界。 */
 async function canonical(file) {
@@ -41,6 +32,8 @@ function createFiles(encryption, options = {}) {
   const configuredRoots = options.allowedRoots ?? (process.env.MCP_ALLOWED_ROOTS ? JSON.parse(process.env.MCP_ALLOWED_ROOTS) : []);
   if (!Array.isArray(configuredRoots) || !configuredRoots.every(x => typeof x === 'string' && path.isAbsolute(x))) throw fault('INVALID_CONFIG', 'MCP_ALLOWED_ROOTS 必须是绝对路径 JSON 数组');
   const rootsPromise = Promise.all(configuredRoots.map(canonical));
+  const locked = createLocker(encryption.stateDir);
+  let realBasePromise;
 
   /** 在操作前解析路径并执行服务端权限范围检查，删除链接时只解析其父目录。 */
   async function resolve(value, { write = false, leaf = false, destructive = false } = {}) {
@@ -50,40 +43,16 @@ function createFiles(encryption, options = {}) {
     const real = leaf ? path.join(await canonical(path.dirname(absolute)), path.basename(absolute)) : await canonical(absolute);
     const roots = await rootsPromise;
     if (roots.length && !roots.some(root => inside(root, real))) throw fault('PATH_OUTSIDE_ROOTS', '路径不在允许的根目录内');
-    if (destructive && (pathKey(real) === pathKey(path.parse(real).root) || pathKey(real) === pathKey(baseDir) || roots.some(root => pathKey(root) === pathKey(real)))) {
-      throw fault('PROTECTED_ROOT', '不能删除或移动盘符根、工作目录或配置根目录本身');
+    if (destructive) {
+      // 同时保护配置别名和真实工作根；其他链接仍按leaf语义只删除链接本身。
+      const realBase = await (realBasePromise ||= canonical(baseDir));
+      if ([path.parse(real).root, baseDir, realBase, ...roots].some(root => inside(real, root))) {
+        throw fault('PROTECTED_ROOT', '不能删除或移动盘符根、工作目录、配置根目录或包含这些根的祖先目录');
+      }
     }
     return real;
   }
 
-  /** 为多个路径按稳定顺序获取独占锁，避免多实例覆盖和死锁。 */
-  async function locked(files, action, context = {}) {
-    const dir = path.join(encryption.stateDir, '.mcp-file-locks');
-    await fs.mkdir(dir, { recursive: true });
-    const held = [];
-    const deadline = Math.min(context.deadline ?? Infinity, performance.now() + 5000);
-    try {
-      for (const file of [...new Set(files.map(pathKey))].sort()) {
-        const lock = path.join(dir, crypto.createHash('sha256').update(file).digest('hex') + '.lock');
-        while (true) {
-          checkBudget(context.signal, context.deadline);
-          try {
-            const handle = await fs.open(lock, 'wx', 0o600);
-            held.push(lock);
-            try { await handle.writeFile(JSON.stringify({ pid: process.pid, file, createdAt: new Date().toISOString() })); }
-            finally { await handle.close(); }
-            break;
-          } catch (error) {
-            if (error.code !== 'EEXIST') throw error;
-            if (performance.now() > deadline) throw fault('FILE_BUSY', '文件正被其他操作占用；若进程异常退出，请核对锁文件: ' + lock);
-            await delay(30);
-          }
-        }
-      }
-      return await action();
-    } finally { for (const lock of held.reverse()) await fs.rm(lock, { force: true }); }
-  }
-
   /** 取得文件修改前指纹，不把目录或特殊设备当作普通文件写入。 */
   async function previous(file, context) {
     const stat = await statMaybe(file);
@@ -98,17 +67,25 @@ function createFiles(encryption, options = {}) {
     if (current?.hash !== before?.hash) throw fault('CONFLICT', '文件在操作期间已改变，未覆盖新内容');
   }
 
+  /** 将校验范围明确告知调用者，Node可读不能代替其他编辑器的解密验收。 */
+  function verificationWarnings(verified) {
+    if (verified.diskState === 'unknown') return ['内容已校验，但没有外部读取器确认文件存储状态'];
+    if (verified.diskState === 'preserved') return ['仅确认Node可见内容；preserved不保证IDEA等其他程序能够解密'];
+    return [];
+  }
+
   /** 暂存、校验、备份、提交、再校验；异常时恢复原目标或保留可恢复备份。 */
   async function commit(file, writer, expected, options = {}) {
     const before = await previous(file, options);
     if (options.expectedHash !== undefined && options.expectedHash !== (before?.hash ?? null)) throw fault('CONFLICT', 'expectedHash 与当前文件不一致');
     if (before && options.overwrite === false) throw fault('ALREADY_EXISTS', '目标已存在，overwrite=false');
     await fs.mkdir(path.dirname(file), { recursive: true });
-    const decision = await encryption.strategy(file, options.writePolicy, options);
+    const decision = await encryption.strategy(file, options.writePolicy, options, { target: before, source: options.sourceSnapshot });
+    const verifyMode = decision.verifyMode || decision.mode;
     if (before?.hash === expected.hash) {
       try {
-        const verified = await encryption.verify(file, expected, decision.mode, options);
-        return { changed: false, hash: expected.hash, ...verified };
+        const verified = await encryption.verify(file, expected, verifyMode, options);
+        return { changed: false, hash: expected.hash, ...verified, strategy: decision, warnings: verificationWarnings(verified) };
       } catch (error) { if (error.code !== 'DISK_MISMATCH') throw error; }
     }
     const suffix = path.extname(file);
@@ -118,6 +95,8 @@ function createFiles(encryption, options = {}) {
     let backedUp = false;
     let installed = false;
     let retainBackup = false;
+    let outcome;
+    let failure;
     try {
       const prepared = await encryption.prepare(stage, writer, expected, decision, options);
       // Windows FlushFileBuffers需要可写句柄，刷盘后再恢复原权限。
@@ -129,9 +108,9 @@ function createFiles(encryption, options = {}) {
       if (before) { await fs.rename(file, backup); backedUp = true; }
       await fs.rename(stage, file);
       installed = true;
-      const verified = await encryption.verify(file, expected, prepared.via ? 'plaintext' : decision.mode, options);
+      const verified = await encryption.verify(file, expected, prepared.via ? 'plaintext' : verifyMode, options);
       if (backedUp) { await fs.rm(backup); backedUp = false; }
-      return { changed: true, hash: expected.hash, size: expected.size, ...verified, strategy: decision, ...(prepared.via ? { via: prepared.via } : {}), warnings: verified.diskState === 'unknown' ? ['内容已校验，但没有独立读取器证明磁盘为明文'] : [] };
+      outcome = { changed: true, hash: expected.hash, size: expected.size, ...verified, strategy: decision, ...(prepared.via ? { via: prepared.via } : {}), warnings: verificationWarnings(verified) };
     } catch (error) {
       // 回滚不受已取消的请求预算影响，优先恢复原始文件。
       try {
@@ -145,11 +124,10 @@ function createFiles(encryption, options = {}) {
         error.recoveryPath = backedUp ? backup : null;
         error.rollbackError = rollbackError.message;
       }
-      throw error;
-    } finally {
-      await fs.rm(stage, { force: true });
-      if (!retainBackup && backedUp) await fs.rm(backup, { force: true });
+      failure = error;
     }
+    const cleanupErrors = await cleanupFiles([stage, ...(!retainBackup && backedUp ? [backup] : [])]);
+    return finishCleanup(outcome, failure, cleanupErrors);
   }
 
   /** 提交文本载荷，写入者使用独占创建防止临时名冲突。 */
@@ -165,7 +143,7 @@ function createFiles(encryption, options = {}) {
     const targetStat = await statMaybe(destination);
     if (pathKey(source) === pathKey(destination) || (targetStat && sourceStat.dev === targetStat.dev && sourceStat.ino === targetStat.ino)) return { changed: false, sameFile: true };
     const expected = await fingerprint(source, settings);
-    const result = await commit(destination, target => pipeline(nativeFs.createReadStream(source), nativeFs.createWriteStream(target, { flags: 'wx', mode: sourceStat.mode }), { signal: settings.signal }), expected, settings);
+    const result = await commit(destination, target => pipeline(nativeFs.createReadStream(source), nativeFs.createWriteStream(target, { flags: 'wx', mode: sourceStat.mode }), { signal: settings.signal }), expected, { ...settings, sourceSnapshot: { file: source, fingerprint: expected } });
     return { ...result, sourceHash: expected.hash };
   }
 
@@ -185,6 +163,12 @@ function createFiles(encryption, options = {}) {
       const createdDirectories = [];
       const sourceDirectories = [];
       let removedSources = 0;
+      const removedSourcePaths = [];
+      /** 文件和目录仅在真实删除成功后计数，保留有界的源变化清单。 */
+      function recordSourceRemoval(file) {
+        removedSources++;
+        if (removedSourcePaths.length < 100) removedSourcePaths.push(file);
+      }
       /** 逐项遍历，不跟随符号链接，避免跨根和意外递归。 */
       async function visit(src, dst) {
         checkBudget(settings.signal, settings.deadline);
@@ -223,30 +207,73 @@ function createFiles(encryption, options = {}) {
           for (const item of completed) {
             if ((await fingerprint(item.source, settings)).hash !== item.sourceHash) throw fault('CONFLICT', '源文件在删源前被修改，已保留');
             await fs.unlink(item.source);
-            removedSources++;
+            recordSourceRemoval(item.source);
+          }
+          for (const dir of sourceDirectories.reverse()) {
+            checkBudget(settings.signal, settings.deadline);
+            await fs.rmdir(dir);
+            recordSourceRemoval(dir);
           }
-          for (const dir of sourceDirectories.reverse()) await fs.rmdir(dir);
         }
-        return { changed: move || completed.some(x => x.changed) || createdDirectories.length > 0, source, destination, files: completed.length, moved: move, warnings: completed.flatMap(x => x.warnings || []).slice(0, 10) };
+        const cleanupErrors = completed.flatMap(x => x.cleanupErrors || []).slice(0, 100);
+        return { changed: move || completed.some(x => x.changed) || createdDirectories.length > 0, source, destination, files: completed.length, moved: move, ...(cleanupErrors.length ? { cleanupErrors } : {}), warnings: completed.flatMap(x => x.warnings || []).slice(0, 10) };
       } catch (error) {
         error.changed = !!error.changed || removedSources > 0 || completed.some(x => x.changed) || createdDirectories.length > 0;
         error.partial = [...new Set([...(error.partial || []), ...completed.map(x => x.destination)])].slice(0, 100);
         error.sourceRetained = removedSources === 0;
+        if (move) {
+          error.removedSourceCount = removedSources;
+          error.removedSourcePaths = removedSourcePaths;
+          error.removedSourcePathsTruncated = removedSources > removedSourcePaths.length;
+        }
+        const cleanupErrors = [...completed.flatMap(x => x.cleanupErrors || []), ...(error.cleanupErrors || [])].slice(0, 100);
+        if (cleanupErrors.length) error.cleanupErrors = cleanupErrors;
         throw error;
       }
     }, settings);
   }
 
-  /** 删除单个文件、链接或目录；空目录非递归删除使用 rmdir。 */
+  /** 逐项删除并记录实际完成项，部分失败不再报告为未修改。 */
   async function remove(value, settings = {}) {
     if (!allowDelete) throw fault('DELETE_DISABLED', '服务已禁用删除工具');
     const file = await resolve(value, { write: !settings.dryRun, leaf: true, destructive: true });
     return locked([file], async () => {
       const st = await fs.lstat(file);
       if (settings.dryRun) return { changed: false, dryRun: true, path: file, type: st.isDirectory() ? 'directory' : st.isSymbolicLink() ? 'symlink' : 'file' };
-      if (st.isDirectory() && settings.recursive === false) await fs.rmdir(file);
-      else await fs.rm(file, { recursive: st.isDirectory(), force: false });
-      return { changed: true, path: file };
+      const removed = [];
+      let removedCount = 0;
+      let visited = 0;
+      let failedPath = file;
+      /** 不跟随链接，逐层检查预算；只在系统删除成功后计数。 */
+      async function erase(target, depth = 0) {
+        failedPath = target;
+        checkBudget(settings.signal, settings.deadline);
+        if (++visited > 10000) throw fault('ITEM_LIMIT', '删除超过一万项预算');
+        if (depth > 128) throw fault('DEPTH_LIMIT', '删除目录深度超过128层');
+        await resolve(target, { write: true, leaf: true, destructive: true });
+        const current = await fs.lstat(target);
+        if (current.isDirectory()) {
+          if (settings.recursive !== false) {
+            const handle = await fs.opendir(target);
+            for await (const entry of handle) await erase(path.join(target, entry.name), depth + 1);
+          }
+          failedPath = target;
+          checkBudget(settings.signal, settings.deadline);
+          await fs.rmdir(target);
+        } else await fs.unlink(target);
+        removedCount++;
+        if (removed.length < 100) removed.push(target);
+      }
+      try { await erase(file); }
+      catch (error) {
+        error.changed = removedCount > 0;
+        error.partial = removed;
+        error.removedCount = removedCount;
+        error.partialTruncated = removedCount > removed.length;
+        error.failedPath = failedPath;
+        throw error;
+      }
+      return { changed: true, path: file, removedCount };
     }, settings);
   }
 

package/lib/locks.js

@@ -0,0 +1,88 @@
+/** 跨进程登记路径占用；祖先与后代互斥，无关路径可并行。 */
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { setTimeout: delay } = require('node:timers/promises');
+const { performance } = require('node:perf_hooks');
+const { fault, checkBudget } = require('./text');
+const { cleanupFiles, finishCleanup } = require('./cleanup');
+
+/** 对Windows路径统一大小写，供路径关系和占用记录比较。 */
+function pathKey(file) { return process.platform === 'win32' ? path.resolve(file).toLowerCase() : path.resolve(file); }
+
+/** 按路径段判断同路径或后代，避免相似前缀误判。 */
+function inside(base, candidate) {
+  const rel = path.relative(pathKey(base), pathKey(candidate));
+  return rel === '' || (!rel.startsWith('..' + path.sep) && rel !== '..' && !path.isAbsolute(rel));
+}
+
+/** 创建使用同一状态目录的跨实例锁管理器。 */
+function createLocker(stateDir) {
+  const dir = path.join(stateDir, '.mcp-file-locks');
+  const guard = path.join(dir, '.registry-guard');
+
+  /** 在短临界区内检查并原子登记整组路径，等待期间不持有其他路径锁。 */
+  async function locked(files, action, context = {}) {
+    await fs.mkdir(dir, { recursive: true });
+    const wanted = [...new Set(files.map(pathKey))].sort();
+    const deadline = Math.min(context.deadline ?? Infinity, performance.now() + 5000);
+    let lease = null;
+    let value;
+    let failure;
+    try {
+      while (!lease) {
+        checkBudget(context.signal, context.deadline);
+        if (performance.now() > deadline) throw fault('FILE_BUSY', '路径或其子树正被其他操作占用；异常退出后请核对锁目录: ' + dir);
+        let guarding = false;
+        let attemptError;
+        try {
+          const handle = await fs.open(guard, 'wx', 0o600);
+          guarding = true;
+          try { await handle.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })); }
+          finally { await handle.close(); }
+          let conflict = false;
+          for (const entry of await fs.readdir(dir)) {
+            checkBudget(context.signal, context.deadline);
+            if (!entry.endsWith('.lock')) continue;
+            let record;
+            try { record = JSON.parse(await fs.readFile(path.join(dir, entry), 'utf8')); }
+            catch (error) {
+              // 持有者可在临界区外释放记录；已删除的记录不再冲突。
+              if (error.code === 'ENOENT') continue;
+              throw fault('FILE_BUSY', '锁记录不可读取，请核对后处理: ' + path.join(dir, entry));
+            }
+            const occupied = record?.files || (record?.file ? [record.file] : null);
+            if (!Array.isArray(occupied) || !occupied.length || !occupied.every(x => typeof x === 'string' && path.isAbsolute(x))) throw fault('FILE_BUSY', '锁记录无效，请核对: ' + path.join(dir, entry));
+            if (wanted.some(a => occupied.some(b => inside(a, b) || inside(b, a)))) { conflict = true; break; }
+          }
+          if (!conflict) {
+            const candidate = path.join(dir, crypto.randomUUID() + '.lock');
+            const handle = await fs.open(candidate, 'wx', 0o600);
+            lease = candidate;
+            try { await handle.writeFile(JSON.stringify({ pid: process.pid, files: wanted, createdAt: new Date().toISOString() })); }
+            finally { await handle.close(); }
+          }
+        } catch (error) {
+          if (guarding || error.code !== 'EEXIST') attemptError = error;
+        } finally {
+          if (guarding) {
+            try { await fs.rm(guard, { force: true }); }
+            catch (error) {
+              const diagnostic = { path: guard, code: error.code, message: error.message };
+              if (!attemptError) attemptError = fault('LOCK_CLEANUP_FAILED', '锁登记临界区无法释放，请核对: ' + guard);
+              attemptError.cleanupErrors = [...(attemptError.cleanupErrors || []), diagnostic];
+            }
+          }
+        }
+        if (attemptError) throw attemptError;
+        if (!lease) await delay(30);
+      }
+      checkBudget(context.signal, context.deadline);
+      value = await action();
+    } catch (error) { failure = error; }
+    return finishCleanup(value, failure, await cleanupFiles(lease ? [lease] : []));
+  }
+  return locked;
+}
+
+module.exports = { createLocker, pathKey, inside };

package/lib/patterns.js

@@ -1,5 +1,9 @@
 /** glob 解析及保持原始位置的字符串编辑。 */
-const { fault, normalizeEol, detectEol } = require('./text');
+const { setImmediate: yieldLoop } = require('node:timers/promises');
+const { fault, normalizeEol, detectEol, EDIT_BYTES, checkBudget } = require('./text');
+const GLOB_COMPILE_LIMIT = 100000;
+const GLOB_WORK_LIMIT = 50000000;
+const GLOB_YIELD_INTERVAL = 16384;
 
 /** 按顶层逗号分隔旧版模式列表，保留花括号内的逗号。 */
 function splitPatterns(value) {
@@ -65,6 +69,59 @@ function globMatcher(patterns) {
   return relative => !matchers.length || matchers.some(m => m.alternatives.some(tokens => matchTokens(tokens, m.basename ? relative.split('/').at(-1) : relative)));
 }
 
+/** 为一次完整扫描累计编译和匹配工作量，定期让出主线程处理心跳/取消。 */
+function globBudget(options) {
+  let work = 0;
+  let sinceYield = 0;
+  /** 先扣减总预算再执行对应计算，返回是否需要让出事件循环。 */
+  function spend(units) {
+    checkBudget(options.signal, options.deadline);
+    work += units;
+    sinceYield += units;
+    if (work > GLOB_WORK_LIMIT) throw fault('GLOB_LIMIT', '本次扫描的glob累计计算超过预算，请缩小模式或扫描范围');
+    return sinceYield >= GLOB_YIELD_INTERVAL;
+  }
+  /** 允许其他MCP请求及取消事件运行，恢复后再次检查绝对截止时间。 */
+  async function pause() {
+    await yieldLoop();
+    sinceYield = 0;
+    checkBudget(options.signal, options.deadline);
+  }
+  return { spend, pause };
+}
+
+/** 生产扫描使用异步glob；预算贯穿编译、全部分支及所有路径，不随文件重置。 */
+async function globMatcherAsync(patterns, options = {}) {
+  const budget = globBudget(options);
+  const matchers = [];
+  let compiled = 0;
+  budget.spend(0);
+  for (const pattern of new Set(splitPatterns(patterns))) {
+    if (pattern.length > 1024) throw fault('INVALID_GLOB', 'glob模式过长');
+    const normalized = pattern.replace(/\\/g, '/');
+    if (budget.spend(normalized.length)) await budget.pause();
+    const alternatives = [];
+    for (const expanded of new Set(expandBraces(normalized))) {
+      compiled += expanded.length;
+      if (compiled > GLOB_COMPILE_LIMIT) throw fault('GLOB_LIMIT', 'glob展开后的累计长度超过10万，请减少模式与分支');
+      if (budget.spend(expanded.length)) await budget.pause();
+      alternatives.push(tokenizeGlob(expanded));
+    }
+    matchers.push({ basename: !normalized.includes('/'), alternatives });
+  }
+  /** 每次匹配继续消耗同一扫描的预算，并保持已有basename/相对路径语义。 */
+  return async function matches(relative) {
+    budget.spend(0);
+    const basename = relative.split('/').at(-1);
+    for (const matcher of matchers) {
+      for (const tokens of matcher.alternatives) {
+        if (await matchTokensAsync(tokens, matcher.basename ? basename : relative, budget)) return true;
+      }
+    }
+    return !matchers.length;
+  };
+}
+
 /** 有上限地展开花括号；不将用户模式交给可能回溯的JS正则。 */
 function expandBraces(pattern, depth = 0) {
   if (depth > 8) throw fault('INVALID_GLOB', 'glob嵌套超过上限');
@@ -99,20 +156,35 @@ function tokenizeGlob(pattern) {
   return tokens;
 }
 
-/** 动态规划匹配glob，复杂度有明确上限，不存在灾难性回溯。 */
+/** 计算一个token的动态规划行，供同步对照和异步生产匹配共用。 */
+function advanceToken(previous, token, value) {
+  const current = new Uint8Array(value.length + 1);
+  let reachable = false;
+  for (let j = 0; j <= value.length; j++) {
+    if (token.type === 'star' || token.type === 'all') current[j] = previous[j] || (j > 0 && current[j - 1] && (token.type === 'all' || value[j - 1] !== '/')) ? 1 : 0;
+    else if (token.type === 'dirs') { current[j] = previous[j] || (j > 0 && value[j - 1] === '/' && reachable) ? 1 : 0; reachable ||= !!previous[j]; }
+    else if (j > 0) current[j] = previous[j - 1] && (token.type === 'one' ? value[j - 1] !== '/' : value[j - 1] === token.value) ? 1 : 0;
+  }
+  return current;
+}
+
+/** 同步匹配保留给兼容调用与语义对照，生产工具使用异步入口。 */
 function matchTokens(tokens, value) {
+  if (tokens.length * value.length > 1000000) throw fault('GLOB_LIMIT', 'glob匹配超过计算预算');
+  let previous = new Uint8Array(value.length + 1);
+  previous[0] = 1;
+  for (const token of tokens) previous = advanceToken(previous, token, value);
+  return !!previous[value.length];
+}
+
+/** 逐行计算并共享请求总预算；一次同步片段最多一行加一个让出间隔。 */
+async function matchTokensAsync(tokens, value, budget) {
   if (tokens.length * value.length > 1000000) throw fault('GLOB_LIMIT', 'glob匹配超过计算预算');
   let previous = new Uint8Array(value.length + 1);
   previous[0] = 1;
   for (const token of tokens) {
-    const current = new Uint8Array(value.length + 1);
-    let reachable = false;
-    for (let j = 0; j <= value.length; j++) {
-      if (token.type === 'star' || token.type === 'all') current[j] = previous[j] || (j > 0 && current[j - 1] && (token.type === 'all' || value[j - 1] !== '/')) ? 1 : 0;
-      else if (token.type === 'dirs') { current[j] = previous[j] || (j > 0 && value[j - 1] === '/' && reachable) ? 1 : 0; reachable ||= !!previous[j]; }
-      else if (j > 0) current[j] = previous[j - 1] && (token.type === 'one' ? value[j - 1] !== '/' : value[j - 1] === token.value) ? 1 : 0;
-    }
-    previous = current;
+    if (budget.spend(value.length + 1)) await budget.pause();
+    previous = advanceToken(previous, token, value);
   }
   return !!previous[value.length];
 }
@@ -163,13 +235,26 @@ function applyLiteral(original, edit, ignoreCase = false) {
   if (!matches.count) throw fault('NO_MATCH', '未找到匹配内容；请检查空格、缩进和原文版本');
   if (edit.expectedMatches !== undefined && matches.count !== edit.expectedMatches) throw fault('MATCH_COUNT_MISMATCH', '实际匹配数与 expectedMatches 不一致', { matched: matches.count });
   const chosen = matches.selected;
-  let updated = original;
-  for (const match of chosen.reverse()) {
+  const spans = [];
+  let bytes = Buffer.byteLength(original);
+  const replacementBytes = Buffer.byteLength(replacement);
+  for (const match of chosen) {
     const start = map ? map(match.index) : match.index;
     const end = map ? map(match.index + match[0].length) : match.index + match[0].length;
-    updated = updated.slice(0, start) + replacement + updated.slice(end);
+    bytes += replacementBytes - Buffer.byteLength(original.slice(start, end));
+    spans.push({ start, end });
+  }
+  if (bytes > EDIT_BYTES) throw fault('FILE_TOO_LARGE', '编辑结果超过16MB预算');
+  // 预先核对输出体量，再按原文位置一次拼接，避免逐匹配复制整个文件。
+  const parts = [];
+  let cursor = 0;
+  for (const { start, end } of spans) {
+    parts.push(original.slice(cursor, start), replacement);
+    cursor = end;
   }
+  parts.push(original.slice(cursor));
+  const updated = parts.join('');
   return { updated, matched: matches.count, replaced: chosen.length, eolAdapted: !!map };
 }
 
-module.exports = { splitPatterns, escapeRegex, globToRegex, globMatcher, applyLiteral };
+module.exports = { splitPatterns, escapeRegex, globToRegex, globMatcher, globMatcherAsync, applyLiteral };

package/lib/regex-worker.js

@@ -1,8 +1,10 @@
 /** 将用户正则隔离在可终止线程，主线程保持 MCP 心跳响应。 */
 const { parentPort } = require('node:worker_threads');
+const { applyLiteral } = require('./patterns');
 
 /** 执行有限输出的匹配或编辑，超时由父线程终止整个 worker。 */
 function execute(task) {
+  if (task.operation === 'literal_edit') return applyLiteral(task.text, task.edit, task.ignoreCase);
   const regex = new RegExp(task.pattern, 'gm' + (task.ignoreCase ? 'i' : ''));
   if (task.operation === 'edit') {
     let count = 0;
@@ -39,5 +41,5 @@ function execute(task) {
 
 parentPort.on('message', message => {
   try { parentPort.postMessage({ id: message.id, result: execute(message.task) }); }
-  catch (error) { parentPort.postMessage({ id: message.id, error: error.message }); }
+  catch (error) { parentPort.postMessage({ id: message.id, error: { code: error.code || (message.task.operation === 'literal_edit' ? 'EDIT_FAILED' : 'INVALID_REGEX'), message: error.message } }); }
 });

package/lib/regex.js

@@ -1,7 +1,8 @@
-/** 复用正则 worker；每个调用独立截止，超时后重建线程。 */
+/** 正则与字面量编辑共用有界计算线程；主线程负责取消和截止时间。 */
 const { Worker } = require('node:worker_threads');
 const path = require('node:path');
-const { fault } = require('./text');
+const { performance } = require('node:perf_hooks');
+const { fault, checkBudget } = require('./text');
 let worker = null;
 let serial = 0;
 const pending = new Map();
@@ -26,7 +27,8 @@ function ensureWorker() {
     pending.delete(message.id);
     clearTimeout(job.timer);
     job.cleanup();
-    if (message.error) job.reject(fault('INVALID_REGEX', message.error));
+    if (performance.now() > job.deadline) job.reject(fault('TIMEOUT', '计算结果到达时已超过操作预算'));
+    else if (message.error) job.reject(fault(message.error.code, message.error.message));
     else job.resolve(message.result);
     if (!pending.size) current.unref();
   });
@@ -35,21 +37,33 @@ function ensureWorker() {
   return current;
 }
 
-/** 运行有硬超时和队列上限的正则任务。 */
-function runRegex(task, options = {}) {
-  if (task.pattern.length > 4096) return Promise.reject(fault('INVALID_REGEX', '正则超过 4096 字符'));
+/** 分派有硬超时和队列上限的计算任务，连同排队时间一起计入预算。 */
+function runTask(task, options = {}) {
   if (pending.size >= 16) return Promise.reject(fault('BUSY', '正则队列已满，请缩小搜索范围'));
   if (options.signal?.aborted) return Promise.reject(fault('CANCELLED', '操作已取消'));
   return new Promise((resolve, reject) => {
+    checkBudget(options.signal, options.deadline);
     const current = ensureWorker();
     current.ref();
     const id = ++serial;
     const abort = () => stop(fault('CANCELLED', '正则任务已取消'));
-    const timer = setTimeout(() => stop(fault('REGEX_TIMEOUT', '正则计算超过预算；请简化正则或使用字面量模式')), options.timeoutMs ?? 1000);
+    const deadline = Math.min(options.deadline ?? Infinity, performance.now() + (options.timeoutMs ?? 1000));
+    const timer = setTimeout(() => stop(task.operation === 'literal_edit' ? fault('TIMEOUT', '字面量编辑超过时间预算') : fault('REGEX_TIMEOUT', '正则计算超过预算；请简化正则或使用字面量模式')), Math.max(1, deadline - performance.now()));
     options.signal?.addEventListener('abort', abort, { once: true });
-    pending.set(id, { resolve, reject, timer, cleanup: () => options.signal?.removeEventListener('abort', abort) });
+    pending.set(id, { resolve, reject, timer, deadline, cleanup: () => options.signal?.removeEventListener('abort', abort) });
     current.postMessage({ id, task });
   });
 }
 
-module.exports = { runRegex, stop };
+/** 限制用户正则长度后交给工作线程执行。 */
+function runRegex(task, options = {}) {
+  if (task.pattern.length > 4096) return Promise.reject(fault('INVALID_REGEX', '正则超过 4096 字符'));
+  return runTask(task, options);
+}
+
+/** 字面量保留原始索引、换行和替换语义，同样具备线程取消能力。 */
+function runLiteral(text, edit, ignoreCase, options = {}) {
+  return runTask({ operation: 'literal_edit', text, edit, ignoreCase }, options);
+}
+
+module.exports = { runRegex, runLiteral, stop };

package/lib/server.js

@@ -6,8 +6,8 @@ const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
 const { z } = require('zod');
 const pkg = require('../package.json');
 const text = require('./text');
-const { globMatcher, applyLiteral, escapeRegex } = require('./patterns');
-const { runRegex } = require('./regex');
+const { globMatcherAsync, escapeRegex } = require('./patterns');
+const { runRegex, runLiteral } = require('./regex');
 const { createEncryption } = require('./encryption');
 const { createFiles, statMaybe } = require('./files');
 const IGNORE = new Set(['node_modules', '.git', 'target', 'build', 'dist', '.idea', '.vscode', '.svn', 'bin', 'obj', 'out', 'vendor']);
@@ -52,9 +52,8 @@ function createServer(options = {}) {
         return await action(args, context);
       } catch (error) {
         return result('操作失败：' + error.message, { changed: !!error.changed,
-          ...(error.recoveryPath ? { recoveryPath: error.recoveryPath, rollbackError: error.rollbackError } : {}),
-          ...(error.partial ? { partial: error.partial, sourceRetained: error.sourceRetained } : {}),
-        }, { ok: false, code: error.code || 'INTERNAL_ERROR' });
+          ...Object.fromEntries(['recoveryPath', 'rollbackError', 'partial', 'sourceRetained', 'removedSourceCount', 'removedSourcePaths', 'removedSourcePathsTruncated', 'removedCount', 'partialTruncated', 'failedPath', 'cleanupErrors'].filter(key => error[key] !== undefined).map(key => [key, error[key]])),
+        }, { ok: false, code: error.code || 'INTERNAL_ERROR', warnings: error.cleanupErrors?.length ? ['部分临时文件未能清理，详见cleanupErrors'] : [] });
       }
     };
     handlers[name] = handler;
@@ -127,7 +126,9 @@ function createServer(options = {}) {
       let matched = 0;
       for (const item of args.edits || [args]) {
         text.checkBudget(context.signal, context.deadline);
-        const change = args.useRegex ? await runRegex({ operation: 'edit', text: updated, pattern: item.oldString, replacement: text.normalizeEol(item.newString, text.detectEol(updated)), replaceAll: item.replaceAll === true, ignoreCase: args.ignoreCase }, { ...context, timeoutMs: Math.max(1, Math.min(1000, context.deadline - performance.now())) }) : applyLiteral(updated, item, args.ignoreCase);
+        const computeBudget = { ...context, timeoutMs: Math.max(1, Math.min(1000, context.deadline - performance.now())) };
+        const change = args.useRegex ? await runRegex({ operation: 'edit', text: updated, pattern: item.oldString, replacement: text.normalizeEol(item.newString, text.detectEol(updated)), replaceAll: item.replaceAll === true, ignoreCase: args.ignoreCase }, computeBudget) : await runLiteral(updated, item, args.ignoreCase, computeBudget);
+        text.checkBudget(context.signal, context.deadline);
         if (!change.matched) throw text.fault('NO_MATCH', '未找到匹配内容，文件未修改');
         if (item.expectedMatches !== undefined && item.expectedMatches !== change.matched) throw text.fault('MATCH_COUNT_MISMATCH', '实际匹配数与expectedMatches不一致');
         updated = change.updated;
@@ -137,6 +138,7 @@ function createServer(options = {}) {
       }
       const payload = (original.hasBom ? '\uFEFF' : '') + updated;
       const details = { matched, replaced, originalHash: before.hash, proposedHash: text.payloadFingerprint(payload).hash, preview: preview(original.content, updated) };
+      text.checkBudget(context.signal, context.deadline);
       if (args.dryRun) return result('编辑预览完成，文件未修改', { changed: false, dryRun: true, ...details });
       const data = await files.write(file, payload, { ...context, expectedHash: before.hash, writePolicy: args.writePolicy });
       return result('编辑成功: ' + file + '\n实际替换 ' + replaced + ' 处，共匹配 ' + matched + ' 处', { ...data, ...details }, { warnings: data.warnings || [] });
@@ -176,7 +178,7 @@ function createServer(options = {}) {
     ...scanShape, pattern: z.string().max(4096), include: patternsSchema, ignoreCase: z.boolean().optional(), onlyMatching: z.boolean().optional(), mode: z.enum(['regex', 'literal']).optional(), contextLines: z.number().int().min(0).max(10).optional(),
   }, true, async (args, context) => {
     const root = await files.resolve(args.path);
-    const include = globMatcher(args.include);
+    const include = await globMatcherAsync(args.include, context);
     const errors = [];
     const skipped = { binary: 0, large: 0, unreadable: 0 };
     const results = [];
@@ -186,7 +188,7 @@ function createServer(options = {}) {
     let truncated = false;
     const exclude = Array.isArray(args.exclude) ? args.exclude : (args.exclude || '').split(',').filter(Boolean);
     for await (const entry of walk(root, { ...args, exclude }, errors, context)) {
-      if (entry.type !== 'file' || !include(entry.relative)) continue;
+      if (entry.type !== 'file' || !(await include(entry.relative))) continue;
       if (results.length >= limit || budget <= 0) { truncated = true; break; }
       let content;
       try {
@@ -211,23 +213,25 @@ function createServer(options = {}) {
       }
       if (found.truncated || truncated) { truncated = true; break; }
     }
+    text.checkBudget(context.signal, context.deadline);
     const warnings = errors.length ? ['部分文件/目录未能扫描，详见errors和skipped；无匹配不代表这些文件没有内容'] : [];
     return result('找到 ' + results.length + ' 处匹配（扫描 ' + scanned + ' 个文件）\n' + results.map(hit => hit.path + ':' + hit.line + ':' + hit.text).join('\n') + (truncated ? '\n结果已截断，请缩小范围' : ''), { results, scanned, skipped, errors, truncated }, { warnings, ok: scanned > 0 || !errors.length, code: scanned === 0 && errors.length ? 'SCAN_INCOMPLETE' : 'OK' });
   });
   register('find_files', '按glob递归查找，支持花括号、字面括号路径、隐藏项及默认忽略开关。', { ...scanShape, pattern: z.string().min(1).max(1024) }, true, async (args, context) => {
     const root = await files.resolve(args.path);
-    const matches = globMatcher([args.pattern]);
+    const matches = await globMatcherAsync([args.pattern], context);
     const entries = [];
     const errors = [];
     let truncated = false;
     let budget = text.READ_LIMIT;
     const exclude = Array.isArray(args.exclude) ? args.exclude : (args.exclude || '').split(',').filter(Boolean);
     for await (const entry of walk(root, { ...args, exclude }, errors, context)) {
-      if (!matches(entry.relative)) continue;
+      if (!(await matches(entry.relative))) continue;
       budget -= entry.file.length + entry.relative.length + 64;
       if (entries.length >= (args.maxResults ?? 500) || budget < 0) { truncated = true; break; }
       entries.push(entry);
     }
+    text.checkBudget(context.signal, context.deadline);
     return result(entries.map(entry => entry.type.toUpperCase() + ' ' + entry.file).join('\n') || '未找到匹配项', { entries, errors, truncated }, { warnings: errors.length ? ['部分目录未能扫描'] : [], ok: !!entries.length || !errors.length, code: !entries.length && errors.length ? 'SCAN_INCOMPLETE' : 'OK' });
   });
   register('list_directory', '列目录的文件/目录/链接类型与元数据，支持分页。', { path: pathSchema, showHidden: z.boolean().optional(), offset: z.number().int().min(0).max(1000000).optional(), maxResults: z.number().int().min(1).max(2000).optional() }, true, async (args, context) => {
@@ -257,11 +261,13 @@ function createServer(options = {}) {
     if (st.isFile() && args.calculateHash !== false) { const fp = await text.fingerprint(file, context); data.sizeReadable = fp.size; data.sizePlaintext = fp.size; data.hash = fp.hash; }
     return result(JSON.stringify(data, null, 2), data);
   });
-  register('create_directory', '递归创建目录，受只读模式与allowedRoots约束。', { path: pathSchema }, false, async args => {
+  register('create_directory', '递归创建目录，受只读模式与allowedRoots约束。', { path: pathSchema }, false, async (args, context) => {
     const dir = await files.resolve(args.path, { write: true });
-    const existed = !!(await statMaybe(dir));
-    await fs.mkdir(dir, { recursive: true });
-    return result('目录已创建: ' + dir, { path: dir, changed: !existed });
+    return files.locked([dir], async () => {
+      const existed = !!(await statMaybe(dir));
+      await fs.mkdir(dir, { recursive: true });
+      return result('目录已创建: ' + dir, { path: dir, changed: !existed });
+    }, context);
   });
   const transferShape = { source: pathSchema, destination: pathSchema, overwrite: z.boolean().optional(), writePolicy: policySchema, timeoutMs: timeoutSchema };
   register('copy_path', '逐文件复制和验证。目标已有目录时放入其下；失败返回部分目标并保留源，不自动跟随链接。', transferShape, false, async (args, context) => {
@@ -304,10 +310,12 @@ function createServer(options = {}) {
     const data = await encryption.mark(args.extension, args.category);
     return result('策略已更新: ' + data.extension + ' = ' + data.category, { ...data, changed: true });
   });
-  register('inspect_write_strategy', '检查有效写入策略；在已存在目标目录创建并清理随机探测样本，不修改目标文件。', { path: pathSchema, writePolicy: policySchema, timeoutMs: timeoutSchema }, false, async (args, context) => {
+  register('inspect_write_strategy', '检查写入策略：已有文件比较Node与外部读取视图，新建路径可在父目录创建探测样本；不修改目标文件。', { path: pathSchema, writePolicy: policySchema, timeoutMs: timeoutSchema }, false, async (args, context) => {
     const file = await files.resolve(args.path);
-    const data = await encryption.strategy(file, args.writePolicy, context);
-    return result(JSON.stringify(data, null, 2), data);
+    return files.locked([path.dirname(file)], async () => {
+      const data = await encryption.strategy(file, args.writePolicy, context);
+      return result(JSON.stringify(data, null, 2), data);
+    }, context);
   });
   return { server, handlers, encryption, files };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-read-file-server",
-  "version": "1.9.1",
+  "version": "2.1.0",
   "description": "加密环境文件操作 MCP 工具。当 Node.js 是加密软件白名单进程时，通过 fs 模块自动解密读写文件明文，替代 AI Agent 内置文件工具，适用于任何支持 MCP 协议的 Agent。",
   "type": "commonjs",
   "main": "index.js",
@@ -16,7 +16,7 @@
   ],
   "scripts": {
     "start": "node index.js",
-    "test": "node --test --test-reporter=tap --test-concurrency=1 test/regression.test.js test/protocol.test.js test/adapters.test.js test/review-fixes.test.js",
+    "test": "node --test --test-reporter=tap --test-concurrency=1 test/regression.test.js test/protocol.test.js test/adapters.test.js test/review-fixes.test.js test/resilience.test.js test/followup-fixes.test.js test/write-policy.test.js",
     "check": "node scripts/check.js"
   },
   "keywords": [