URL: /built-in/file_read

---
title: file_read — 读取文件内容
description: 读取本地文件系统中的文件内容，支持指定行号范围
---

读取本地文件系统中的文件内容，支持指定行号范围。适用于查看源代码文件、读取配置文件、分析日志文件等场景。

## 参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `file_path` | string | 是 | 要读取的文件的绝对路径 |
| `offset` | integer | 否 | 起始行号（从 1 开始），默认 1。仅大文件需要分段读取时使用 |
| `limit` | integer | 否 | 要读取的行数，默认 2000。仅大文件需要分段读取时使用 |

## 约束与限制

| 限制项 | 值 |
|--------|:----:|
| 最大文件大小 | 256 KB（超过需分段读取） |
| 输出最大字符数 | 100,000 字符（超出返回错误） |
| 默认读取行数上限 | 2000 行 |
| 支持的文件类型 | 纯文本文件（UTF-8 编码） |

## 输出格式

```text
文件 /path/to/file (共 150 行, 显示 1-100 行)

1	第一行内容
2	第二行内容
...
```

支持分页提示：

```text
文件 /path/to/file (共 500 行, 显示 1-200 行)

1	内容
...

---
[显示 200/500 行，使用 offset=201 查看后续内容]
```

## 安全机制

| 防护项 | 说明 |
|--------|------|
| 文件不存在 | 返回明确的错误信息 |
| 目录读取 | 提示应使用 `ls` 命令 |
| 设备文件拦截 | 字符设备（如 `/dev/null`）和块设备不允许读取 |
| 文件过大 | 超过 256KB 返回错误，提示使用 offset/limit 分段读取 |
| 二进制检测 | 扫描文件开头 8KB，含 null byte 则判定为二进制文件 |
| 非 UTF-8 编码 | 非 UTF-8 文本文件返回错误 |

## 错误场景

| 错误类型 | 说明 |
|----------|------|
| 缺少 `file_path` | 未提供必填参数 |
| 文件不存在 | 指定的路径无文件 |
| 路径是目录 | 读取目录不被允许 |
| 设备文件 | 字符/块设备文件不允许读取 |
| 文件过大 | 超过 256KB 限制 |
| 二进制文件 | 检测到 null byte |
| 非 UTF-8 文本 | 文件编码不是 UTF-8 |

## 与 file_search 的配合

> **file_search** 用于在文件中搜索特定内容（需知道搜索目标）。  
> **file_read** 用于直接查看文件内容（需知道文件路径和行号范围）。  
> AI Agent 会自动组合两者：先用 `file_search` 定位相关代码行，再用 `file_read` 查看具体上下文。

## 使用示例

```bash
zapmyco run '读取 src/main.rs 的内容'
zapmyco run '查看 Cargo.toml 的前 30 行'
zapmyco run '读取 src/config/settings.rs 的第 50-100 行'
```

## 相关文档

- [内置工具目录](/guide/built-in-tools) — 查看所有工具
- [file_search](/built-in/file_search) — 搜索文件内容
- [file_find](/built-in/file_find) — 按名称查找文件