kesepain-ke 文件操作 (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_fileedit_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，超限自动截断