| name | encryption-file-ops |
| description | 在文件加密软件（天锐绿盾 / IP-Guard / 亿赛通 / 深信服等）环境下，使用 MCP Server 提供的替代工具（read_file / write_file / edit_file / search_files 等）替代 AI Agent 内置 Read/Write/Edit/Grep 工具读写明文。当内置工具返回密文/乱码，或用户提到"加密、绿盾、密文、白名单、读不到文件"等关键词时激活。 |
加密环境文件操作 Skill
本 Skill 负责"教策略"，MCP Server 负责"执行"。
本 Skill 不替代任何 MCP 工具，仅提供使用指引。前提是 mcp-read-file-server 已按项目 README 配置到你的 Agent 中。
一、适用场景与触发条件
满足任一即激活本 Skill：
- 内置
Read/Write/Edit/Grep 工具返回密文、十六进制乱码、%TSD-Header-###% 文件头
- 用户提到关键词：天锐、绿盾、TSD、IP-Guard、亿赛通、深信服、加密软件、白名单、密文、解密失败
- 项目文件头出现
%TSD-Header-###% 等加密标识
前置条件（必须满足）：
- Node.js 进程已被加密软件列为白名单（受信任进程）
mcp-read-file-server MCP Server 已配置并正常运行（在 Agent 的 MCP 列表中能看到 read-file-server）
二、工具映射表
以下工具名以 MCP 协议原始名称为准。不同 Agent 可能对 MCP 工具有不同的命名规则：
- Claude Code / Cursor / Cline 等大多数 Agent：直接使用工具名，如
read_file
- OpenClaw / 部分平台：可能自动添加前缀，如
mcp__read-file-server__read_file
请根据你的 Agent 实际显示的工具名调用，以下表格使用通用名称。
| 场景 | 内置工具（禁用 ❌） | MCP 工具（用这个 ✅） |
|---|
| 读单个文件 | Read | read_file |
| 读 ≥2 个文件 | 多次 Read | read_files |
| 写文件 | Write | write_file |
| 精确编辑 | Edit / MultiEdit | edit_file |
| 搜索内容 | Grep | search_files |
| 创建目录 | （无） | create_directory |
| 查文件信息 | （无） | file_info |
| 健康检查 | （无） | check_status |
强约束：在加密环境下，禁止使用 Read/Write/Edit/MultiEdit/Grep 内置工具——它们会读到密文或破坏加密结构。
三、哪些工具在加密环境下安全可用
| 工具类型 | 可用？ | 说明 |
|---|
内置 Read / Write / Edit / Grep | ❌ 禁用 | 独立进程通常不在白名单，读到密文或破坏加密 |
终端 shell 原生命令（cat/sed/grep） | ⚠️ 慎用 | shell 进程通常不在白名单，同样读到密文 |
MCP Server 提供的工具（read_file 等） | ✅ 主用 | Node.js 进程在白名单，可正常解密读写 |
node -e 直接调用 fs 模块 | ✅ 可用 | Node.js 进程在白名单，效果等同于 MCP 工具 |
仅列文件名的操作（如 ls、文件树浏览） | ✅ 可用 | 不读文件内容，加密不影响 |
| 网络工具（HTTP 请求、网页抓取） | ✅ 可用 | 与本地加密无关 |
Shell 命令特别注意：终端 shell 进程通常不在加密软件白名单，cat/sed/grep 等命令读文件时得到的是密文。如需在终端读取明文，应通过 node -e "fs.readFileSync(...)" 走 Node.js 白名单进程。
四、决策树
需要读文件
├─ 单个 → read_file
└─ 多个（≥2）→ read_files（批量更高效）
需要修改文件
├─ 已读过 → 直接 edit_file
└─ 未读过 → 先 read_file 拿到明文 → 再 edit_file
需要新建/覆盖文件
└─ write_file
需要搜索内容
└─ search_files
├─ 限定文件类型 → 用 include（如 "*.java,*.xml"）
└─ 控制返回数量 → 用 maxResults
需要创建目录
└─ create_directory
需要判断文件是否存在 / 查大小
└─ file_info
工具异常 / 不确定是否生效
└─ check_status
五、典型工作流
流程 1：读取并修改文件
1. read_file 读取明文
2. 分析内容
3. edit_file 修改
- oldString 必须从第 1 步读到的内容里原样复制（含空格、缩进、换行）
4. 必要时再 read_file 验证修改结果
流程 2：批量读多个相关文件
1. read_files
- paths 参数用英文逗号分隔，如 "D:/proj/A.java,D:/proj/B.java"
2. 统一分析（输出会带 "========== 文件: xxx ==========" 分隔）
流程 3：在项目中搜索特定代码
1. search_files
- pattern: 正则表达式（如 "function\s+\w+"、"@GetMapping"）
- path: 搜索根目录
- include: 文件名过滤（可选）
2. 根据返回的 file:line 定位，用 read_file 读取具体文件
流程 4：从零创建新模块
1. create_directory 建目录
2. write_file 逐个创建文件
3. read_file 验证（可选）
六、edit_file 参数详解
| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|
path | string | ✅ | - | 文件绝对路径 |
oldString | string | ✅ | - | 要替换的原内容，必须从 read_file 原文中精确复制 |
newString | string | ✅ | - | 替换后的新内容 |
useRegex | boolean | ❌ | false | true 时 oldString 当正则，可用 $1 $2 引用捕获组 |
replaceAll | boolean | ❌ | false | 替换所有匹配项；false 时仅替换第一处 |
ignoreCase | boolean | ❌ | false | 是否忽略大小写（仅字符串模式生效） |
常见模式
- 单点替换：
useRegex=false, replaceAll=false（默认）
- 批量替换：
useRegex=true, replaceAll=true（如统一改名）
- 正则提取重组：
useRegex=true, newString 里用 $1 $2
七、注意事项
- 路径用绝对路径最稳（如
D:/proj/file.java），相对路径以 MCP Server 启动目录为基准
edit_file 前必须 read_file：从原文精确复制 oldString（含空格、缩进、换行），不要凭记忆写write_file 是覆盖写：会清空原文件再写入，重要文件修改前建议先 read_file 备份内容search_files 自动跳过：node_modules、.git、target、build、dist、.idea、.vscode- 大批量搜索：用
maxResults 控制返回数量（默认 200），避免一次性返回过多结果
- 工具调用顺序：复杂任务先
check_status 确认 MCP Server 正常运行，再正式操作
八、故障排查
| 现象 | 可能原因 | 解决方案 |
|---|
| 读到的还是密文/乱码 | Node.js 不在加密软件白名单 | 联系管理员把 node.exe 加入白名单 |
| MCP 工具全部不可见 | MCP Server 未配置或未启动 | 检查 Agent 的 MCP 列表命令（如 claude mcp list），确认 read-file-server 在列表中 |
edit_file 报"未找到匹配内容" | oldString 拼写/缩进/换行不匹配 | 重新 read_file 复制原文，不要凭记忆写 |
edit_file 报"匹配到 N 处" | 文件中存在重复内容 | 加更长/更唯一的 oldString 唯一定位，或 replaceAll=true |
search_files 报"正则表达式无效" | 正则语法错误 | 检查 pattern 是否需要转义特殊字符 |
write_file 报权限错误 | 文件被占用或目录无写权限 | 关闭占用进程 / 检查目录权限 |
| 工具调用超时 | 文件过大 | 改用 search_files 定位后只 read_file 关键段 |
