mcp-read-file-server 1.5.0 → 1.8.0

package/README.md

@@ -4,6 +4,10 @@
 
 加密环境文件操作工具。当 Node.js 是加密软件白名单进程时，通过 fs 模块自动解密读写文件明文，替代 AI Agent 内置文件工具，解决加密环境下读到密文的问题。适用于任何支持 MCP 协议的 AI Agent。
 
+**v1.7.0 环境自适应**：自动探测本机加密策略（哪些扩展名会被透明加密、哪些进程可用），对「会被加密且无法解密」的扩展名（如部分机器上的 `.scss`/`.css`）自动走 safeWrite 中转落盘明文，无需任何手工配置，换电脑自动重新探测。详见下文「环境自适应」。
+
+**v1.8.0 写入后实时重分类**：启动探测只给出先验分类，且 Node.js 白名单读回无法区分「真受控（TSD 管控文档）」与「伪受控」。1.8.0 起所有直写路径完成后，用外部进程读取目标文件磁盘原始字节实测：发现密文（命中 `%TSD` 魔数）自动将该扩展名重分类为 encrypted 并立即用 safeWrite 重写为明文；实测明文则重分类为 safe。对需要**保持加密**的扩展名（如 `.java`），用 `mark_extension` 手动标注 protected 后，写入直写保持加密且跳过自动纠正。
+
 ## 适用场景
 
 电脑安装了文件加密软件（如天锐绿盾、IP-Guard、亿赛通、深信服等），磁盘上的文件是密文。AI Agent（Claude Code、Cursor、Windsurf、Cline 等）是独立进程，内置文件工具不在白名单内，只能读到密文。而 Node.js 进程在白名单内，通过 MCP Server 提供的替代工具可以正常读写明文。
@@ -31,6 +35,66 @@
 AI Agent  --(MCP/stdio)-->  Node.js MCP Server  --(fs.readFileSync)-->  读取明文
 ```
 
+## 环境自适应（v1.7.0+）
+
+### 解决的问题
+
+加密软件对「写入是否透明加密」是**按目标文件扩展名**决定的，且每台电脑的策略不同：
+
+| 扩展名分类 | 含义 | 直写后果 | 本工具策略 |
+|-----------|------|---------|-----------|
+| **safe** | 写入后磁盘是明文 | 正常 | 直接写（原始行为） |
+| **protected** | 写入后磁盘是密文，但 Node.js 白名单读回自动解密 | 本机正常 | 直接写（保持加密保护） |
+| **unsafe** | 写入后被加密，但该类型不在保护列表，**任何进程都无法解密** | 磁盘密文乱码，文件损坏 | 自动走 safeWrite |
+
+### safeWrite 原理
+
+对 unsafe 扩展名目标，写入流程自动切换为：
+
+```
+1. fs.writeFileSync 写入 目标路径+安全扩展名 的临时文件（安全类型 → 磁盘明文）
+2. 用探测到的可用外部进程（powershell/cmd/robocopy/cscript 等）复制临时文件到目标路径
+   （外部进程不在白名单内，复制动作不触发透明加密 → 目标落盘为明文）
+3. 校验目标文件磁盘字节为明文
+4. 清理临时文件
+5. 失败则遍历全部「安全扩展名 × 可用进程」组合重试；全部失败回退直写并明确告警
+```
+
+### 探测与缓存
+
+- **首次启动（或缓存失效）自动探测**：依次用候选扩展名写入临时文件，通过「外部进程读磁盘原始字节 + 物理大小对比 + Node 读回对比」三重交叉验证分类；再探测可用的外部进程并做复制交叉验证
+- **探测全程在系统临时目录进行**，不污染用户目录；对未在候选清单中的扩展名，首次写入时按需即时探测（在目标文件所在目录进行，兼容按目录生效的策略）
+- **缓存位置**：`~/.mcp-encryption-profile.json`，按 machineId（hostname+username 哈希）绑定，**换电脑/换用户自动重新探测**；缓存有效期 30 天
+- **查看/刷新**：用 `encryption_profile` 工具查看当前探测结果；加密策略变更后用 `refresh_profile` 强制重探
+- **无外部进程可用时**（如进程被策略禁止 spawn）：自动降级为大小+读回对比探测，unsafe 写入回退直写并告警，不影响其他功能
+
+### 写入后实时重分类（v1.8.0+）
+
+启动探测的分类结论是先验的（在系统临时目录采样），且 Node.js 白名单读回无法区分「真受控文档」与「伪受控」——两者在白名单进程里都能读到明文。1.8.0 起引入**写入后实测**兜底：
+
+```
+写入完成 → 外部进程读目标文件磁盘前 16 字节
+  ├─ 与写入内容前缀一致 → 磁盘明文 → 扩展名重分类为 safe
+  ├─ 命中 %TSD 魔数     → 磁盘密文 → 扩展名重分类为 encrypted，
+  │                        并立即用 safeWrite 重写为明文（自动纠正）
+  └─ 检测不可用          → 保持原分类（无任何副作用）
+```
+
+- **首次写入新扩展名**：先直写，实测发现加密 → 自动重分类 + 立即纠正为明文，并提示已切换策略；第二次起该扩展名直接走 safeWrite
+- **目录级策略差异**：已知 safe/protected 的扩展名在写入后也会复测，策略被管理员调整或按目录生效时可自动纠正误分类
+- **用户标注优先**：`mark_extension` 标注为 protected 的扩展名保持加密直写，跳过自动纠正（适合 `.java` 这类需要保持加密状态的受控文档）；标注为 unsafe 的扩展名强制走 safeWrite 保持明文
+- **缓存结构 v2**：新增 `encryptedExtensions`（写入后实测密文的扩展名）与 `userProtectedExtensions`（用户标注），旧版缓存自动作废重探
+
+### mark_extension 手动标注
+
+当自动分类不符合预期时手动干预（标注优先级高于一切自动分类）：
+
+| 场景                                         | 调用 | 效果 |
+|----------------------------------------------|------|------|
+| `.java` 需要保持 TSD 加密（company受控文档） | `mark_extension(".java", "protected")` | 直写保持加密，Notepad 打开正常，跳过写入后自动纠正 |
+| `.scss` 必须保持明文（自动误判为 protected） | `mark_extension(".scss", "unsafe")` | 强制走 safeWrite 保持明文 |
+| 恢复自动分类                                 | `mark_extension(".java", "clear")` | 清除手动标注 |
+
 ## 文件结构
 
 ```
@@ -39,7 +103,7 @@ mcp-read-file-server/
 ├── SKILL.md          # 配套 Skill（可选，让 AI 学会自动选用本工具）
 ├── index.js          # MCP Server 主程序（含 shebang，可作可执行入口）
 ├── package.json      # 包配置（bin/files/依赖声明，可 npm publish）
-├── .gitignore        # Git 忽略规则
+├── .gitignore        # Git 忽略规则
 └── node_modules/     # 依赖（@modelcontextprotocol/sdk、zod，不随包发布）
 ```
 
@@ -181,17 +245,20 @@ claude mcp list
 | `read_file` | Read | 读取单个文件明文（超大文件自动截断） | `path` |
 | `read_files` | 多次 Read | 批量读取多个文件明文（数组或逗号分隔字符串） | `paths` |
 | `read_file_partial` | Read（局部） | 局部读取文件（前N字符 / 指定行范围） | `path`、`mode`、`charCount`、`startLine`、`endLine` |
-| `write_file` | Write | 写入文件（支持追加模式 / 行尾风格 / BOM 保留） | `path`、`content`、`mode`、`eol` |
-| `edit_file` | Edit/MultiEdit | 精确字符串/正则替换后写回（CRLF/LF 自动兼容、BOM 保留、正则默认多行模式） | `path`、`oldString`、`newString`、`useRegex`、`replaceAll`、`ignoreCase` |
+| `write_file` | Write | 写入文件（支持追加模式 / 行尾风格 / BOM 保留；unsafe 扩展名自动 safeWrite 明文落盘） | `path`、`content`、`mode`、`eol` |
+| `edit_file` | Edit/MultiEdit | 精确替换后写回（CRLF/LF 自动兼容、BOM 保留、正则多行模式、`edits` 批量原子编辑、失败附相似行诊断；unsafe 扩展名自动 safeWrite） | `path`、`oldString`、`newString`、`edits`、`useRegex`、`replaceAll`、`ignoreCase` |
 | `search_files` | Grep | 递归搜索文件内容（支持 `**` 目录通配、跳过二进制/超大文件） | `pattern`、`path`、`include`、`exclude`、`ignoreCase`、`onlyMatching`、`maxResults` |
 | `find_files` | Glob | 按文件名 glob 递归查找（如 `**/*.test.js`） | `pattern`、`path`、`maxResults` |
 | `list_directory` | LS | 列出目录内容（类型/大小/时间） | `path`、`showHidden` |
-| `copy_path` | bash cp | 复制文件/目录（递归；加密环境必须经白名单进程） | `source`、`destination` |
-| `move_path` | bash mv | 移动/重命名（跨盘符自动回退复制+删除） | `source`、`destination` |
+| `copy_path` | bash cp | 复制文件/目录（递归；加密环境必须经白名单进程；unsafe 目标自动 safeCopy） | `source`、`destination` |
+| `move_path` | bash mv | 移动/重命名（跨盘符自动回退复制+删除；unsafe 目标自动明文落盘） | `source`、`destination` |
 | `remove_path` | bash rm | 删除文件/目录（默认递归，谨慎使用） | `path`、`recursive` |
 | `create_directory` | - | 递归创建目录 | `path` |
 | `file_info` | - | 查询文件/目录信息（含明文大小、符号链接） | `path` |
-| `check_status` | - | 检查运行状态（可实测解密能力） | `path`（可选） |
+| `check_status` | - | 检查运行状态（可实测解密能力，输出含环境探测概要） | `path`（可选） |
+| `encryption_profile` | - | 查看环境探测结果（扩展名三分类、可用进程、最佳组合、缓存位置） | 无 |
+| `refresh_profile` | - | 强制重新探测环境并更新缓存（加密策略变更后使用） | 无 |
+| `mark_extension` | `extension`, `category` | 手动标注扩展名写入策略：protected=保持加密直写，unsafe=强制 safeWrite 明文，clear=清除标注 | 无 |
 
 ### `read_file_partial` 参数详解
 
@@ -220,8 +287,10 @@ Windows 下文件多为 CRLF 换行，而 AI Agent 生成的多行 `oldString`
 - **提示信息**：触发换行适配时，返回结果会附 `ℹ️ 换行符已自动适配` 说明，方便排查
 - **BOM 自动处理**：UTF-8 BOM 读取时自动剥离、写回时自动补回，`oldString` 无需关心 BOM
 - **正则模式默认多行**：`useRegex=true` 时自动附加 `m` 标志，`^xxx` / `xxx$` 按行锚定
+- **批量原子编辑（edits 数组）**：一次调用完成多处修改，按序应用；**任一条目失败则整体不写盘**，不会产生「半改状态」。条目按文件现状顺序构造（前面条目的结果参与后续条目匹配）
+- **失败附相似行诊断**：字符串匹配失败时返回「可能相关的行」及相似度，直接对照排查空白/缩进差异，无需盲目重试
 
-注意：该兼容仅针对换行符差异，空格、缩进等其他空白字符仍需与原文完全一致。
+注意：该兼容仅针对换行符差异，空格、缩进等其他空白字符仍需与原文完全一致。含反引号 `` ` `` 与 `${}` 的内容直接原样传参（JSON 传输无 JS 模板字面量转义问题）。
 
 ### 其他内置保护
 
@@ -236,6 +305,52 @@ Windows 下文件多为 CRLF 换行，而 AI Agent 生成的多行 `oldString`
 
 配置好后，在 Agent 中直接说需求即可。Agent 会自动调用 MCP 工具读写文件明文。
 
+## 推荐提示词（Prompt）
+
+把下面这段提示词放入 Agent 的系统提示/记忆文件（Claude Code 放 `CLAUDE.md`，Cursor 放 `.cursor/rules`，其他 Agent 放对应的全局指令位置），可让 Agent 在加密环境下**始终正确地**使用本工具，避免误用内置工具读到密文或写出不可解密的乱码文件：
+
+```markdown
+# 文件操作强制规则（加密软件环境）
+
+本机装有文件加密软件（天锐绿盾/TSD/IP-Guard/亿赛通等），磁盘文件为密文。
+所有文件操作必须使用 mcp__read-file-server__* 工具，严禁使用内置
+Read/Write/Edit/MultiEdit/Grep/LS 及 Bash 的 cat/sed/grep/cp/mv/rm
+（内置工具不在加密软件白名单内，会读到密文或产出任何进程都无法解密的乱码文件）。
+find_files 之外的文件名查找也优先用 MCP 工具。
+
+## 工具映射
+- 读单个文件      → mcp__read-file-server__read_file
+- 读多个文件      → mcp__read-file-server__read_files（批量，一次调用）
+- 局部读取        → read_file_partial（大文件分页：mode=chars 或 mode=lines）
+- 新建/覆盖写     → write_file
+- 修改文件        → edit_file（多处修改必须用 edits 数组一次提交，禁止逐条调用）
+- 搜索内容        → search_files（include 限定类型，maxResults 控制数量）
+- 按文件名查找    → find_files
+- 列目录          → list_directory
+- 复制/移动/删除  → copy_path / move_path / remove_path
+- 建目录/查信息   → create_directory / file_info
+
+## 使用规则
+1. 会话开始先调 check_status 确认白名单解密正常；环境不明时调
+   encryption_profile 查看本机扩展名分类（safe/protected/unsafe/encrypted）与可用进程。
+2. 写任何扩展名的文件都不用关心加密细节：write_file/edit_file/copy_path/
+   move_path 已内置环境自适应与写入后实时检测——写入后磁盘为密文的扩展名
+   会被自动识别并立即重写为明文，后续同类文件自动走 safeWrite。
+3. 需要保持加密状态的扩展名（如受控的 .java 文档）：用
+   mark_extension(".java", "protected") 标注一次即可，之后写入直写保持加密；
+   反之若某扩展名被误判导致写入后变密文，用 mark_extension(".ext", "unsafe")
+   强制保持明文。标注一次永久生效（缓存在本机）。
+4. edit_file 前必须先 read_file 拿原文，oldString 从原文原样复制
+   （含空格与缩进；CRLF/LF 换行差异会自动兼容，无需手工处理）。
+5. 路径一律使用绝对路径。
+6. 若写工具返回「safeWrite 失败/回退直接写入」告警，先调 refresh_profile
+   重新探测环境，再重试写入；仍失败则把告警原文报告给用户。
+7. edit_file 匹配失败时，按返回的「可能相关的行」诊断修正 oldString，
+   不要盲目重试。
+```
+
+> 该提示词与 `SKILL.md` 二选一即可：Agent 支持 Skill 机制（Claude Code 等）时装 SKILL.md；不支持或想要更强约束时，直接把上面的提示词写进全局指令。
+
 ## 配套 Skill（可选）
 
 本工具附带一份 Skill：`SKILL.md`，位于本目录根下。
@@ -330,6 +445,18 @@ cd mcp-read-file-server && npm install
 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 等文件后显示乱码（密文）
+
+该扩展名在本机属于 unsafe 类型（加密但不自动解密）。v1.7.0+ 会自动走 safeWrite 规避；若仍出现乱码：
+
+1. 调 `refresh_profile` 强制重新探测（策略可能变更或缓存过期）
+2. 调 `encryption_profile` 确认该扩展名已被正确识别为 unsafe、且存在可用外部进程与 bestCombo
+3. 若显示「可用外部进程: （无）」，说明 MCP Server 进程被策略禁止 spawn 子进程，需联系管理员放行 powershell/cmd，或接受直写加密后由白名单应用打开
+
+### 写工具返回「safeWrite 失败，已回退直接写入」告警
+
+说明所有「安全扩展名 × 外部进程」组合都验证失败（常见原因：外部进程对目标目录无写权限）。处理：调 `refresh_profile` 重探；检查目标目录权限；换目录重试。回退写入的文件在本机可能显示乱码，建议删除后重新写入。
+
 ### Agent 连不上 MCP Server
 
 包本身正常但 Agent 连不上时，按以下顺序排查：
@@ -347,3 +474,7 @@ echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":
    npx -y mcp-read-file-server   # 能启动=包没问题，问题在 Agent 配置/环境
    ```
    能启动并卡住等输入，说明包正常，需检查 Agent 的配置 JSON 格式与 `command` 写法。
+
+
+---
+[![MCP Badge](https://lobehub.com/badge/mcp/hebulin-mcp-read-file-server)](https://lobehub.com/mcp/hebulin-mcp-read-file-server)

package/SKILL.md

@@ -40,6 +40,9 @@ description: 在文件加密软件（天锐绿盾 / IP-Guard / 亿赛通 / 深
 | 创建目录 | （无） | `mcp__read-file-server__create_directory` |
 | 查文件信息 | （无） | `mcp__read-file-server__file_info` |
 | 健康检查 | （无） | `mcp__read-file-server__check_status` |
+| 查看环境探测结果 | （无） | `mcp__read-file-server__encryption_profile` |
+| 重新探测环境（策略变更后） | （无） | `mcp__read-file-server__refresh_profile` |
+| 手动标注扩展名保持加密/明文 | （无） | `mcp__read-file-server__mark_extension` |
 
 > **强约束**：在加密环境下，**禁止使用** `Read/Write/Edit/MultiEdit/Grep/Glob/LS` 内置工具与 `Bash` 的 `cp/mv/rm` 文件操作--它们会读到密文、写出密文或破坏加密结构。
 
@@ -85,8 +88,10 @@ description: 在文件加密软件（天锐绿盾 / IP-Guard / 亿赛通 / 深
 ```
 1. mcp__read-file-server__read_file 读取明文
 2. 分析内容
-3. mcp__read-file-server__edit_file 修改
-   - oldString 必须从第 1 步读到的内容里**原样复制**（含空格、缩进；换行风格差异会自动兼容）
+3. 修改：
+   - 单处修改 -> mcp__read-file-server__edit_file（oldString/newString）
+   - 多处修改 -> mcp__read-file-server__edit_file 的 edits 数组（原子：失败整体不写盘）
+   - oldString 从第 1 步读到的内容里**原样复制**（含空格、缩进；换行风格差异会自动兼容）
 4. 必要时再 read_file 验证修改结果
 ```
 
@@ -120,30 +125,42 @@ description: 在文件加密软件（天锐绿盾 / IP-Guard / 亿赛通 / 深
 | 参数 | 类型 | 必填 | 默认 | 说明 |
 |------|------|------|------|------|
 | `path` | string | ✅ | - | 文件绝对路径 |
-| `oldString` | string | ✅ | - | 要替换的原内容，必须**精确匹配** |
-| `newString` | string | ✅ | - | 替换后的新内容 |
-| `useRegex` | boolean | ❌ | false | true 时 oldString 当正则，可用 `$1 $2` 引用捕获组 |
+| `oldString` | string | 单次模式✅ | - | 要替换的原内容，必须**精确匹配**（换行风格差异已自动兼容） |
+| `newString` | string | 单次模式✅ | - | 替换后的新内容 |
+| `edits` | array | 批量模式✅ | - | 批量原子编辑：`[{oldString, newString, replaceAll?}]` 按序应用，**任一条目失败则整体不写盘**（不会产生半改状态）。一次完成多处修改必须用它，不要逐条调用 |
+| `useRegex` | boolean | ❌ | false | true 时 oldString 当正则（单次模式），可用 `$1 $2` 引用捕获组；默认启用多行模式（`^`/`$` 按行锚定） |
 | `replaceAll` | boolean | ❌ | false | true 时替换所有匹配项；false 时仅替换第一处 |
 | `ignoreCase` | boolean | ❌ | false | 是否忽略大小写（仅字符串模式生效） |
 
 ### 常见用法
 - **单点替换**：`useRegex=false, replaceAll=false`（默认）
 - **批量替换**：`useRegex=true, replaceAll=true`（如改命名）
+- **多处修改**：`edits` 数组（如重命名+改值+删行一次完成，失败自动整体回滚）
 - **正则提取后重组**：`useRegex=true, newString` 里用 `$1` `$2`
 
+### 实战避坑（来自真实使用反馈）
+
+1. **换行差异已自动兼容，无需关心 CRLF/LF**：oldString 用 LF 匹配 CRLF 文件（或相反）均可命中，newString 行尾自动跟随文件风格。**不要**再为此绕道写 Node 补丁脚本手工归一
+2. **oldString 含反引号 `` ` `` 与 `${}` 直接原样传入**：MCP 参数走 JSON 传输，无 JS 模板字面量的转义层级问题；同样不要绕道脚本（脚本里转义极易写错）
+3. **多处修改必须用 `edits` 批量模式**：逐条调用时若中途失败，前面条目已写盘会产生「半改状态」，后续按原内容构造的 oldString 必然失配；`edits` 原子模式要么全成要么不动。**批量条目按序应用**：前面条目的 newString 会成为后续条目的匹配环境，请按文件现状顺序构造（如 A 改为 B 后，后条可用 B 做锚点）
+4. **oldString 带足上下文保证唯一**：短 oldString 命中多处时工具会警告（如 `替换 1/2 处`），此时加长上下文（含前后行）唯一定位；超长行（如记忆表格行）优先选行内独有片段做锚点
+5. **匹配失败看诊断**：失败信息会附「可能相关的行」及相似度，直接对照检查空白/缩进/字符差异，不要盲目重试；正则模式报错时注意 oldString 正则里 `$` 需写成 `\$`（如匹配字面 `$1`），而 newString 里的 `$1` 是捕获组引用原样保留
+
 ---
 
 ## 六、注意事项
 
-1. **路径**：用**绝对路径**最稳（如 `D:/AiJiamiToolsPlugins/...`），相对路径以 MCP Server 启动目录为基准
-2. **`edit_file` 前必读**：必须先 `read_file` 拿到明文，再从原文里**原样复制** `oldString`，否则会因为空格/缩进不匹配而失败
-3. **换行风格无需担心**：文件是 CRLF 而 `oldString` 是 LF（或相反）时，`edit_file` 会自动归一换行后匹配；`newString` 行尾也会自动跟随文件主导风格，不会产生混行
-4. **`write_file` 是覆盖写**：会清空原文件再写入，重要文件修改前建议先 `read_file` 备份内容
-5. **`search_files` / `find_files` 自动跳过**：`node_modules`、`.git`、`target`、`build`、`dist`、`.svn`、`bin`、`obj`、`out`、`vendor` 与 `.` 开头的隐藏文件/目录；`search_files` 另跳过二进制与超过 5MB 的文件
-6. **大批量搜索**：用 `maxResults` 控制返回数量，避免一次性返回过多结果
-7. **工具调用顺序**：复杂任务先 `check_status`（可传 path 实测解密）确认 MCP 正常，再正式操作
-8. **`remove_path` 不可恢复**：递归删除前建议先 `list_directory` 确认内容
-9. **`read_files` 路径含逗号时必须传数组**：Windows 路径可合法包含英文逗号，逗号分隔字符串形式会被错误切分
+1. **环境自适应（v1.7.0+）**：写工具（write_file/edit_file/copy_path/move_path）已内置扩展名分类感知，unsafe 扩展名（直写会变不可解密密文的类型，如部分机器的 .scss/.css）自动走 safeWrite 明文落盘，**无需任何特殊处理**；策略变更或换电脑后探测缓存自动失效重探，也可手动调 `refresh_profile`
+2. **写入后实时重分类（v1.8.0+）**：直写完成后会用外部进程实测磁盘字节，发现密文自动重分类该扩展名并立即重写为明文（返回中会有「已自动重分类」提示）；已知 safe/protected 扩展名也会复测，目录级策略差异可自动纠正。需要**保持加密**的扩展名（如公司受控的 .java），用 `mark_extension(".java", "protected")` 标注后直写保持加密并跳过自动纠正
+3. **路径**：用**绝对路径**最稳（如 `D:/AiJiamiToolsPlugins/...`），相对路径以 MCP Server 启动目录为基准
+4. **`edit_file` 前必读**：必须先 `read_file` 拿到明文，再从原文里**原样复制** `oldString`，否则会因为空格/缩进不匹配而失败
+5. **换行风格无需担心**：文件是 CRLF 而 `oldString` 是 LF（或相反）时，`edit_file` 会自动归一换行后匹配；`newString` 行尾也会自动跟随文件主导风格，不会产生混行
+6. **`write_file` 是覆盖写**：会清空原文件再写入，重要文件修改前建议先 `read_file` 备份内容
+7. **`search_files` / `find_files` 自动跳过**：`node_modules`、`.git`、`target`、`build`、`dist`、`.svn`、`bin`、`obj`、`out`、`vendor` 与 `.` 开头的隐藏文件/目录；`search_files` 另跳过二进制与超过 5MB 的文件
+8. **大批量搜索**：用 `maxResults` 控制返回数量，避免一次性返回过多结果
+9. **工具调用顺序**：复杂任务先 `check_status`（可传 path 实测解密）确认 MCP 正常，再正式操作
+10. **`remove_path` 不可恢复**：递归删除前建议先 `list_directory` 确认内容
+11. **`read_files` 路径含逗号时必须传数组**：Windows 路径可合法包含英文逗号，逗号分隔字符串形式会被错误切分
 
 ---
 
@@ -151,6 +168,9 @@ description: 在文件加密软件（天锐绿盾 / IP-Guard / 亿赛通 / 深
 
 | 现象 | 可能原因 | 解决方案 |
 |------|----------|----------|
+| 写入 .scss/.css 后文件显示乱码（密文） | 该扩展名为 unsafe 且 safeWrite 未生效（缓存过期/策略变更） | 调 `refresh_profile` 重探后重写；用 `encryption_profile` 确认分类与可用进程；1.8.0+ 写入后会自动实测纠正，若仍乱码用 `mark_extension(".scss", "unsafe")` 强制明文 |
+| 写入 .java 后被自动转明文（需要保持加密） | 1.8.0+ 写入后检测发现密文自动纠正为明文 | 用 `mark_extension(".java", "protected")` 标注保持加密，后续直写不再自动纠正 |
+| 写工具提示「safeWrite 失败，已回退直接写入」 | 无可用外部进程或全部组合验证失败 | 调 `refresh_profile`；确认 MCP Server 进程可 spawn powershell/cmd；删除乱码文件后重写 |
 | 读到的还是密文/乱码 | Node.js 不在加密软件白名单 | 联系管理员把 `node.exe` 加入白名单 |
 | `mcp__read-file-server__*` 工具全部不可见 | MCP Server 未配置或未启动 | 见 `README.md` 配置 `.mcp.json` |
 | `edit_file` 报"未找到匹配内容" | `oldString` 拼写、缩进不对（换行 CRLF/LF 差异与 BOM 已自动兼容） | 重新 `read_file` 复制原文，**不要凭记忆写**；重点检查空格与缩进 |