📄 文件操作

YingClaw 提供完整的文件读、写、编辑、搜索能力，覆盖日常开发和运维中的各种文件处理场景。

核心工具

file_read — 读取文件

读取任意文本文件内容，支持分段读取和 PDF 自动提取。

参数	类型	说明
path	string	文件路径（相对于工作空间）
offset	number	起始行号（1-based），可选
limit	number	最大读取行数，可选

# 读取完整文件
file_read path="config.toml"

# 分段读取（从第 100 行开始读 50 行）
file_read path="app.log" offset=100 limit=50

file_write — 写入/创建文件

创建新文件或覆盖已有文件，自动创建不存在的父目录。

参数	类型	说明
path	string	文件路径
content	string	要写入的完整内容

# 创建 README.md
file_write path="docs/guide.md" content="# 使用指南\n\n..."

file_edit — 精确替换

在文件中查找唯一匹配的字符串并替换为新内容。

参数	类型	说明
path	string	要编辑的文件路径
old_string	string	待替换的原始字符串（必须唯一匹配）
new_string	string	替换后的新字符串

注意：old_string 必须在文件中恰好出现一次，否则编辑失败。建议包含足够的上下文以确保唯一性。

glob_search — 文件搜索

按通配符模式匹配文件路径。

# 搜索所有 Rust 源文件
glob_search pattern="**/*.rs"

# 搜索 src 目录下的所有模块文件
glob_search pattern="src/**/mod.rs"

content_search — 内容搜索

使用正则表达式搜索文件内容，底层基于 ripgrep。

# 搜索所有 .ts 文件中包含 'useState' 的行
content_search pattern="useState" include="*.ts"

# 搜索并显示匹配计数
content_search pattern="TODO" output_mode="count"

使用场景

场景	推荐工具
代码审查	file_read + content_search
配置修改	file_read → file_edit
日志分析	content_search + file_read（分段）
文档生成	file_write
数据提取	file_read + glob_search
批量重构	glob_search → file_edit

最佳实践

大文件处理策略

文件大小	策略
< 50KB	直接使用 file_read 完整读取
50KB ~ 500KB	使用 offset + limit 分段读取
> 500KB	禁止完整读取，仅使用 content_search 搜索关键内容

先搜索，再精读

对于大型项目，建议先用 glob_search 定位目标文件，再用 content_search 找到关键行，最后用 file_read 精读相关段落。

编辑前先读取

修改文件前务必先 file_read 确认当前内容，构造精确的 old_string，避免误改。

特殊格式支持

• PDF 文件：file_read 可自动提取 PDF 文本内容（需 rag-pdf 特性）
• 代码文件：自动识别语言并保留语法高亮所需的上下文
• 配置文件：JSON / YAML / TOML 等格式的结构化读取

下一步

掌握文件操作后，继续了解 🧠 记忆系统，让 YingClaw 记住你的偏好。