filesystem

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Filesystem

All file and directory operations use Claude Code's built-in tools. No MCP server needed — native tools are faster, more capable, and cost zero context tokens when idle.

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

Quick Reference

快速参考

Filesystem MCP Tool	Replacement	Notes
`read_file(path)`	`Read` tool	Supports line offset and limit
`read_multiple_files(paths)`	Multiple parallel `Read` calls	Faster than sequential MCP calls
`write_file(path, content)`	`Write` tool	Overwrites entire file
`edit_file(path, edits)`	`Edit` tool	Exact string replacement; surgical edits
`list_directory(path)`	`Glob` or `Bash ls`	Glob for patterns, ls for simple listing
`directory_tree(path)`	`Bash fd` or `Glob */`	fd is fastest; Glob for pattern filtering
`search_files(pattern, path)`	`Grep` tool	Full regex, file type filters, context lines
`create_directory(path)`	`Bash mkdir -p`	`-p` creates intermediate directories
`move_file(src, dst)`	`Bash mv`	Also handles renames
`get_file_info(path)`	`Bash stat` or `Bash ls -la`	Size, permissions, timestamps
`list_allowed_directories`	N/A	Claude Code operates in the working directory; no sandbox restrictions

Filesystem MCP Tool	替代方案	说明
`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在工作目录下运行，无沙箱限制

Reading Files

读取文件

Read a Single File

读取单个文件

Use the

Read

tool with an absolute path:

Read: /path/to/file.py

For large files, use offset and limit to read specific sections:

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

This reads 50 lines starting from line 100. Use this for files with thousands of lines to avoid flooding context.

使用带绝对路径的

Read

工具：

Read: /path/to/file.py

对于大文件，可使用offset和limit读取指定部分：

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

这会从第100行开始读取50行。针对数千行的大文件可使用该方式避免占用过多上下文。

Read Multiple Files in Parallel

并行读取多个文件

Issue multiple

Read

calls in a single response. Claude Code executes them concurrently:

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

Parallel reads are faster than the MCP's

read_multiple_files

which serialized internally.

在单次响应中发起多个

Read

调用，Claude Code会并发执行这些请求：

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

并行读取比MCP内部串行执行的

read_multiple_files

速度更快。

Read Images and PDFs

读取图片和PDF

The

Read

tool handles binary formats:

Images (PNG, JPG, SVG): displayed visually
PDFs: extracted text; use
```
pages: "1-5"
```
for large documents (max 20 pages per call)

Read

工具支持二进制格式：

图片（PNG、JPG、SVG）：可视化展示
PDFs：提取文本内容，大文档可使用
```
pages: "1-5"
```
指定页码范围（单次调用最多读取20页）

Writing and Editing Files

写入与编辑文件

Write a New File

写入新文件

Use the

Write

tool to create a file or overwrite an existing one:

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

The

Write

tool requires reading the file first if it already exists. For new files, write directly.

使用

Write

工具创建文件或覆盖已有文件：

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

如果文件已存在，使用

Write

工具前需要先读取文件。新建文件可直接写入。

Edit an Existing File

编辑已有文件

Use the

Edit

tool for surgical modifications — replace exact string matches:

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

The

Edit

tool fails if

old_string

is not unique in the file. Provide enough surrounding context to make the match unique, or use

replace_all: true

for find-and-replace across the entire file.

Prefer Edit over Write for existing files. Edit preserves everything outside the changed region and shows a clear diff. Write replaces the entire file.

使用

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会保留修改区域外的所有内容并展示清晰的 diff，Write会替换整个文件。

Finding Files

查找文件

By Name Pattern (Glob)

按名称模式查找（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

Results are sorted by modification time (most recent first).

Glob: **/*.py           → 递归查找所有Python文件
Glob: src/**/*.ts       → 查找src/目录下的TypeScript文件
Glob: *.md              → 查找当前目录下的Markdown文件
Glob: **/test_*.py      → 查找目录树中任意位置的测试文件

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

By Content (Grep)

按内容查找（Grep）

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

Grep Parameter	Purpose
`pattern`	Regex pattern to match
`type`	File type filter (py, js, ts, rust, go, etc.)
`glob`	Glob pattern filter ( `.tsx` , `src//.py` )
`output_mode`	`files_with_matches` (default), `content` , `count`
`-C` , `-A` , `-B`	Context lines: around, after, before matches
`-i`	Case-insensitive search

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`	忽略大小写搜索

Directory Listing

目录列表

Simple listing:

bash

ls -la /path/to/directory

Recursive tree with

fd

bash

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

Tree with depth limit:

bash

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

Filter by extension:

bash

fd -e py /path/to/directory

简单列表：

bash

ls -la /path/to/directory

使用

fd

生成递归目录树：

bash

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

带深度限制的目录树：

bash

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

按后缀名过滤：

bash

fd -e py /path/to/directory

File Operations

文件操作

Create Directory

创建目录

bash

mkdir -p /path/to/new/directory

The

-p

flag creates all intermediate directories. Always verify the parent path exists first with

ls

bash

mkdir -p /path/to/new/directory

-p

参数会创建所有中间层级目录。请始终先使用

ls

验证父路径是否存在。

Move / Rename

移动/重命名

bash

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

Rename a file (same directory):

bash

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

Move a directory:

bash

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

bash

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

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

bash

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

移动目录：

bash

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

Copy

复制

bash

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

bash

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

Delete

删除

bash

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

Always confirm with the user before deleting files or directories.

bash

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

删除文件或目录前请务必征得用户确认。

File Metadata

文件元数据

bash

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

Command	Returns
`stat`	Size, permissions, timestamps, inode
`ls -la`	Permissions, owner, size, modification date
`wc -l`	Line count
`file`	MIME type detection

bash

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类型检测结果

Common Workflows

常用工作流

Find and Replace Across Files

跨文件查找替换

bash

undefined

bash

undefined

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)

undefined

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

undefined

Explore an Unfamiliar Codebase

探索陌生代码库

Check project structure:
```
fd . --type f --max-depth 2
```
Read configuration:
```
Read: package.json
```
or
```
Read: pyproject.toml
```

Find entry points:

Grep: pattern="def main|if __name__" type="py"

Read key files identified above

检查项目结构：
```
fd . --type f --max-depth 2
```
读取配置文件：
```
Read: package.json
```
或
```
Read: pyproject.toml
```

查找入口点：

Grep: pattern="def main|if __name__" type="py"

读取上述步骤识别出的核心文件

Find Large Files

查找大文件

bash

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

bash

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

Error Handling

错误处理

Error	Cause	Resolution
Read: file not found	Path incorrect or file deleted	Verify with `ls` or `Glob`
Edit: old_string not unique	Multiple matches in the file	Add more surrounding context to make it unique
Edit: old_string not found	Content changed since last read	Re-read the file, then retry with current content
Write: file not read first	Attempting to overwrite without reading	Read the file first, then Write
Permission denied	Insufficient OS permissions	Check with `ls -la` ; use `chmod` if appropriate
Glob: no files found	Pattern too restrictive	Broaden the pattern; check path spelling

错误	原因	解决方案
Read: file not found	路径错误或文件已删除	使用 `ls` 或 `Glob` 验证路径
Edit: old_string not unique	文件中有多个匹配项	增加更多上下文内容确保匹配唯一
Edit: old_string not found	上次读取后内容已变更	重新读取文件，使用当前内容重试
Write: file not read first	尝试未读取直接覆盖文件	先读取文件，再执行写入
Permission denied	操作系统权限不足	使用 `ls -la` 检查权限，必要时使用 `chmod` 调整
Glob: no files found	模式限制过严	放宽匹配模式，检查路径拼写

Limitations

限制

Read returns up to 2000 lines by default. Use offset/limit for larger files.
Read truncates lines longer than 2000 characters.
Edit requires exact string matching — whitespace and indentation must match precisely.
Write overwrites the entire file. No append mode. To append, read first, then write the combined content.
Glob only matches files, not directories. Use
```
Bash ls
```
or
```
fd
```
to list directories.
PDF reading is limited to 20 pages per call. Specify page ranges for large documents.

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

Calibration Rules

校准规则

Read before Edit. Always read a file before editing it. The Edit tool enforces this.
Edit over Write for existing files. Edit is surgical and shows diffs. Write is a full replacement — use it only for new files or complete rewrites.
Glob over Bash for file search. Glob is optimized for pattern matching. Only fall back to
```
fd
```
or
```
find
```
for queries Glob cannot express (size filters, date filters).
Grep over Bash for content search. Grep is optimized for ripgrep-based search with proper permissions. Never use
```
grep
```
or
```
rg
```
via Bash.
Parallel reads for multiple files. Issue all Read calls in a single response for concurrent execution.
Always use absolute paths. Claude Code tools require absolute paths. Never pass relative paths to Read, Write, or Edit.

编辑前先读取。编辑文件前请务必先读取文件，Edit工具会强制执行该规则。
编辑已有文件优先使用Edit而非Write。Edit是精准修改且会展示diff，Write是全量替换——仅适用于新建文件或完全重写的场景。
文件搜索优先使用Glob而非Bash。Glob针对模式匹配做了优化，仅当Glob无法满足查询需求时（大小过滤、日期过滤）才使用
```
fd
```
或
```
find
```
。
内容搜索优先使用Grep而非Bash。Grep针对基于ripgrep的搜索做了优化，且权限处理更合理，请勿通过Bash使用
```
grep
```
或
```
rg
```
。
多文件读取使用并行调用。在单次响应中发起所有Read调用以实现并发执行。
始终使用绝对路径。Claude Code工具要求使用绝对路径，请勿向Read、Write或Edit传递相对路径。