filesystem

文件系统

所有文件和目录操作都使用 Claude Code 内置工具。无需 MCP 服务——原生工具速度更快、功能更强，而且空闲时不消耗上下文令牌。

快速参考

文件系统 MCP 工具	替代方案	说明
read_file(path)	Read 工具	支持行偏移量和读取行数限制
read_multiple_files(paths)	多个并行 Read 调用	比顺序执行 MCP 调用更快
write_file(path, content)	Write 工具	覆盖整个文件
edit_file(path, edits)	Edit 工具	精确替换字符串；可精细修改
list_directory(path)	Glob 或 Bash ls	Glob 用于匹配模式，ls 用于简单列出
directory_tree(path)	Bash fd 或 Glob **/*	fd 速度最快；Glob 用于按模式筛选
search_files(pattern, path)	Grep 工具	完整正则表达式、文件类型筛选、上下文行
create_directory(path)	Bash mkdir -p	-p 会创建中间目录
move_file(src, dst)	Bash mv	也可用于重命名
get_file_info(path)	Bash stat 或 Bash ls -la	大小、权限、时间戳
list_allowed_directories	不适用	Claude Code 在工作目录中运行；不受沙盒限制

---

读取文件

读取单个文件

使用 Read 工具并提供绝对路径：

Read: /path/to/file.py

对于大型文件，可使用偏移量和读取行数限制来读取特定部分：

Read: /path/to/file.py (offset: 100, limit: 50)

这会从第 100 行开始读取 50 行。对于有数千行的文件，可使用此方法避免上下文被大量内容占满。

并行读取多个文件

在单次响应中发起多个 Read 调用。Claude Code 会并发执行这些调用：

Read: /path/to/file1.py
Read: /path/to/file2.py
Read: /path/to/file3.py

并行读取比 MCP 的 read_multiple_files 更快，后者内部采用串行处理。

读取图像和 PDF

Read 工具支持二进制格式：

• 图像（PNG、JPG、SVG）：以可视化方式显示
• PDF：提取文本；对于较大的文档，可使用 pages: "1-5"（每次调用最多 20 页）

---

写入和编辑文件

写入新文件

使用 Write 工具创建文件或覆盖现有文件：

Write: /path/to/new-file.py
Content: <full file content>

如果文件已存在，使用 Write 工具前必须先读取该文件。对于新文件，可直接写入。

编辑现有文件

使用 Edit 工具进行精细修改——替换完全匹配的字符串：

Edit: /path/to/file.py
old_string: "def old_function():"
new_string: "def new_function():"

如果 old_string 在文件中不唯一，Edit 工具会失败。请提供足够的周边上下文以确保匹配唯一，或使用 replace_all: true 在整个文件中查找并替换。

对于现有文件，优先使用 Edit 而非 Write。Edit 会保留修改区域之外的所有内容，并显示清晰的差异。Write 会替换整个文件。

---

查找文件

按名称模式查找（Glob）

Glob: **/*.py           → all Python files recursively
Glob: src/**/*.ts       → TypeScript files under src/
Glob: *.md              → Markdown files in current directory
Glob: **/test_*.py      → test files anywhere in the tree

结果按修改时间排序（最新的排在最前）。

按内容搜索（Grep）

Grep: pattern="def process_data" type="py"
Grep: pattern="TODO|FIXME" glob="*.py"
Grep: pattern="class.*Controller" output_mode="content" -C=2

Grep 参数	用途
pattern	要匹配的正则表达式
type	文件类型筛选（py、js、ts、rust、go 等）
glob	Glob 模式筛选（*.tsx、src/**/*.py）
output_mode	files_with_matches（默认）、content、count
-C、-A、-B	上下文行：匹配项周围、之后、之前
-i	不区分大小写的搜索

列出目录

简单列表：

ls -la /path/to/directory

使用 fd 递归显示目录树：

fd . /path/to/directory --type f

限制深度的目录树：

fd . /path/to/directory --type f --max-depth 2

按扩展名筛选：

fd -e py /path/to/directory

---

文件操作

创建目录

mkdir -p /path/to/new/directory

-p 标志会创建所有中间目录。请先使用 ls 确认父路径存在。

移动／重命名

mv /path/to/source.py /path/to/destination.py

重命名文件（同一目录）：

mv /path/to/old-name.py /path/to/new-name.py

移动目录：

mv /path/to/source-dir /path/to/destination-dir

复制

cp /path/to/source.py /path/to/destination.py
cp -r /path/to/source-dir /path/to/destination-dir

删除

rm /path/to/file.py
rm -r /path/to/directory

删除文件或目录前，务必先向用户确认。

文件元数据

stat /path/to/file.py
ls -la /path/to/file.py
wc -l /path/to/file.py

命令	返回内容
stat	大小、权限、时间戳、inode
ls -la	权限、所有者、大小、修改日期
wc -l	行数
file	MIME 类型检测

---

常见工作流

跨文件查找和替换

# Find all files containing the old string
Grep: pattern="old_function_name" type="py" output_mode="files_with_matches"

# Then Edit each file
Edit: /path/to/file1.py (old_string → new_string, replace_all: true)
Edit: /path/to/file2.py (old_string → new_string, replace_all: true)

探索不熟悉的代码库

1. 检查项目结构：fd . --type f --max-depth 2
2. 阅读配置：Read: package.json 或 Read: pyproject.toml
3. 查找入口点：Grep: pattern="def main|if __name__" type="py"
4. 阅读上面找到的关键文件

查找大文件

fd --type f --exec stat -f '%z %N' {} \; | sort -rn | head -20

---

错误处理

错误	原因	解决方法
Read: 找不到文件	路径不正确或文件已删除	使用 ls 或 Glob 验证
Edit: old_string 不唯一	文件中有多个匹配项	添加更多周边上下文，使其唯一
Edit: 找不到 old_string	内容自上次读取后发生了变化	重新读取文件，然后使用当前内容重试
Write: 尚未读取文件	尝试覆盖文件，但未先读取	先读取文件，然后再 Write
权限被拒绝	OS 权限不足	使用 ls -la 检查；必要时使用 chmod
Glob: 未找到文件	模式限制过严	放宽模式；检查路径拼写

---

限制

• Read 默认最多返回 2000 行。对于更大的文件，请使用 offset/limit。
• Read 会截断超过 2000 个字符的行。
• Edit 要求精确匹配字符串——空格和缩进必须完全一致。
• Write 会覆盖整个文件。不支持追加模式。要追加内容，请先读取文件，然后写入合并后的内容。
• Glob 只匹配文件，不匹配目录。使用 Bash ls 或 fd 列出目录。
• PDF 阅读 每次调用最多处理 20 页。对于较大的文档，请指定页码范围。

---

校准规则

1. 先读后编辑。 编辑文件前始终先读取文件。Edit 工具会强制执行此规则。
2. 已有文件优先使用 Edit，而不是 Write。 Edit 可精确修改并显示差异。Write 会完整替换文件——仅用于新文件或完全重写。
3. 搜索文件时优先使用 Glob，而不是 Bash。 Glob 针对模式匹配进行了优化。只有当查询条件无法用 Glob 表达时（如大小筛选、日期筛选），才退而使用 fd 或 find。
4. 搜索内容时优先使用 Grep，而不是 Bash。 Grep 针对基于 ripgrep 的搜索进行了优化，并具备适当的权限。切勿通过 Bash 使用 grep 或 rg。
5. 并行读取多个文件。 在同一条响应中发出所有 Read 调用，以便并发执行。
6. 始终使用绝对路径。 Claude Code 工具要求使用绝对路径。切勿向 Read、Write 或 Edit 传入相对路径。