# File

> 文件操作工具集 — 读取、按行读取、写入、追加、精确编辑、列目录、目录树、文件信息、搜索、复制、移动、创建目录、删除文件。默认受沙箱保护，环境变量可放开沙箱外路径。

- Skill: `kesepain-ke/file` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add kesepain-ke/file`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kesepain-ke/file/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kesepain-ke (https://skillmd.com/u/kesepain-ke)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kesepain-ke/file

---


# 文件操作 (File)

`file` 提供本地文件系统操作。路径解析保留，可通过环境变量放开沙箱外路径。

## 插件路径

`plugins/file/`

## 注册工具

| 工具 | 用途 |
|------|------|
| `read_file` | 读取整个文件，支持 UTF-8 / UTF-8 BOM / GBK 回退，无大小限制 |
| `read_file_range` | 按行读取，支持 `start_line/end_line` 或 `tail` 读取日志尾部 |
| `write_file` | 完整覆盖写入文件，自动创建父目录 |
| `append_file` | 追加写入文件，不存在则创建 |
| `edit_file` | 精确编辑：`insert` / `replace_line` / `replace_range` / `replace_text`，默认创建 `.bak` 备份 |
| `list_dir` | 列出目录内容，文件夹置前排序 |
| `tree_dir` | 输出目录树，默认跳过 `.git`、`node_modules`、`.venv`、`dist`、`build` 等大目录 |
| `stat_file` | 查看文件或目录类型、大小、创建时间、修改时间 |
| `search_files` | 搜索文件名、文件内容或代码定义，支持 `scope`、`context_lines` 和 `fd/rg` 加速 |
| `copy_file` | 复制文件，目标必须是完整文件路径，默认不覆盖 |
| `move_file` | 移动或重命名文件，目标必须是完整文件路径，默认不覆盖 |
| `make_dir` | 创建目录，默认递归创建父目录 |
| `delete_file` | 删除文件，严格禁止删除目录 |

## 关键参数说明

### edit_file

| 参数 | 说明 |
|------|------|
| `mode` (enum) | `insert` / `replace_line` / `replace_range` / `replace_text` |
| `text` | 插入内容、新行内容或替换后的文本 |
| `line` / `column` | 起始行号 / 列号（1-based） |
| `end_line` / `end_column` | 结束行号 / 列号（replace_range 模式） |
| `old_text` | replace_text 模式下要替换的原文 |
| `expected_count` | 期望匹配次数，默认 1；设为 -1 跳过检查 |
| `create_backup` | 是否创建 `.bak` 备份，默认 true |

### read_file_range

| 参数 | 说明 |
|------|------|
| `start_line` / `end_line` | 行号范围（1-based），`end_line=0` 按 `max_lines` 截断 |
| `tail` | 读取末尾 N 行；大于 0 时优先于行号范围 |
| `max_lines` | 最大返回行数，默认 500，上限 50000 |

### search_files

| 参数 | 说明 |
|------|------|
| `mode` (enum) | `file` / `name`（文件名）/ `text` / `content`（内容）/ `code`（代码定义） |
| `scope` (enum) | `workspace` / `user` / `both` |
| `root` | 搜索根目录，非空时优先于 scope |
| `file_glob` | 文件名 glob 过滤，如 `*.py` |
| `max_results` | 最大结果数，默认 50，上限 5000 |
| `context_lines` | 匹配行上下文行数，默认 0，上限 100 |
| `regex` | query 是否按正则处理 |

## 路径解析环境变量

路径解析保留（兼容相对路径和绝对路径）。以下环境变量可选地控制路径访问范围：

| 环境变量 | 效果 |
|----------|------|
| `VOTX_FILE_OUTSIDE_SANDBOX=1` | 允许所有 file 工具操作沙箱外路径 |
| `VOTX_FILE_READ_OUTSIDE_SANDBOX=1` | 允许 `read_file`、`read_file_range`、`list_dir`、`tree_dir`、`stat_file`、`search_files` 访问沙箱外路径 |
| `VOTX_FILE_EDIT_OUTSIDE_SANDBOX=1` | 允许 `write_file`、`append_file`、`edit_file`、`copy_file`、`move_file`、`make_dir` 操作沙箱外路径 |
| `VOTX_FILE_WRITE_OUTSIDE_SANDBOX=1` | 同上，作为写入类操作的别名 |
| `VOTX_FILE_DELETE_OUTSIDE_SANDBOX=1` | 允许 `delete_file` 删除沙箱外文件 |

不设置时默认允许项目根和用户目录；设置后允许全路径访问。

## 结果说明

- `read_file` / `read_file_range`：返回文件内容文本（`read_file_range` 带行号前缀和文件头信息）
- `write_file` / `append_file` / `edit_file` / `copy_file` / `move_file`：返回工具结果 JSON（含文件 artifact）
- `list_dir` / `tree_dir`：返回目录列表/树形结构文本
- `stat_file`：返回文件/目录元信息（类型、大小、修改/创建时间）
- `delete_file` / `make_dir`：返回 `OK:` 前缀的成功消息
- `search_files`：返回匹配结果列表
- 失败：返回 `ERROR:` 前缀的错误信息

## 常见规范

- 读大文件或日志时优先用 `read_file_range` 的 `tail` 或行号范围，不用 `read_file` 全量读取
- 小片段修改优先用 `edit_file` 的 `replace_text`，并设置 `expected_count=1` 确保精准匹配
- 文件名、内容或代码定义检索统一使用 `search_files`
- `copy_file` 和 `move_file` 的目标路径必须是完整文件路径；目标是目录时会报错
- `delete_file` 只删除文件，拒绝删除目录

## 常见处理办法

- **路径越权**：设置对应的环境变量放开沙箱，或确认路径在项目根/用户目录内
- **编码错误**：`read_file` 支持 UTF-8 → UTF-8 BOM → GBK 自动回退；如仍失败，指定 `encoding="gbk"`
- **edit_file 匹配失败**：检查 `old_text` 是否与文件内容完全一致（包括空格、换行），调整 `expected_count`
- **search_files 无结果**：确认 `scope` 包含目标目录；尝试 `include_hidden=true` 或调整 `file_glob`

## 常见教训

- `write_file` 是完整覆盖写入，不是追加；追加用 `append_file`
- `edit_file` 的 `replace_text` 模式默认 `expected_count=1`，如果原文出现多次会报错；设为 `-1` 跳过检查
- `tree_dir` 默认跳过 `.git`、`node_modules` 等大目录，需要查看时设 `include_hidden=true` 或 `max_depth` 更大
- `search_files` 的 `max_results` 上限 5000，`context_lines` 上限 100，超限自动截断