> ## Documentation Index
> Fetch the complete documentation index at: https://platform.stepfun.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 内置工具

Step Code 的内置工具覆盖读取、写入、修改、命令执行和文件搜索。配置层（`defaultTools` / `--tools`）使用 `read`、`bash` 等白名单名称，模型侧使用 `read_file`、`run_command` 等名称。

## 工具总表

| 配置名称                | 用途            | 模型侧名称            |
| ------------------- | ------------- | ---------------- |
| `read`              | 读取文本和图片       | `read_file`      |
| `write`             | 创建或覆盖文件       | `write_file`     |
| `edit`              | 精确替换文件内容      | `edit_file`      |
| `bash`、`powershell` | 执行 Shell 命令   | `run_command`    |
| `grep`              | 搜索文件内容        | `search_files`   |
| `find`              | 按文件名或 glob 查找 | `find_files`     |
| `ls`                | 列出目录内容        | `list_directory` |

`bash` / `powershell` 对应不同平台的 Shell。工具配置使用左列名称；扩展和 MCP 还可提供其他工具。

## read

支持文本文件和 JPG、PNG、GIF、WebP、BMP 图片。超长文本按行数或 KB 上限截断，先到为准，使用 `offset` / `limit` 分段读取。

图片作为附件进入模型请求，默认压缩到 2,000 px 以内。

## bash（Windows 为 powershell）

命令在当前工作目录运行，输出流式返回。可通过 `shellPath` 和 `shellCommandPrefix` 配置运行环境。

模型通过 `run_command` 的 `run_in_background` 参数后台执行时，命令分离启动，立即返回 PID 与日志文件。读取日志判断就绪，使用 `kill` 停止；会话结束时仍在运行的进程会被清理。该能力不同于输入框的 `!` 前缀。

Shell 与启动 Step Code 的账户拥有相同的系统权限。执行命令前请检查工作目录、凭据和可能的副作用。

## edit

对单个文件进行精确文本替换。每处 `oldText` 必须唯一匹配，多处修改不能重叠；相邻改动应合并为一处。匹配失败时先重新读取文件，避免根据过期内容修改。

## write

创建或完整覆盖文件，并按需创建父目录。需要保留原有内容时，应选择局部编辑，或在写入前确认完整目标内容。

## grep

参数包括 `pattern`、`path`、`ignoreCase`、`literal` 和 `glob`，支持字面量或正则搜索。后端顺序为 ripgrep（自动下载或系统）> `git grep`（在 Git 仓库内时）> POSIX `grep`，全部不可用时报错。

工具缓存和网络排查见[数据路径](/docs/zh/step-code/configuration/data-paths#内置工具缓存)。

## find

按文件名或 glob 查找匹配文件，支持点文件。返回路径后，可继续使用读取工具查看内容。

## ls

按字母序列出目录内容，目录带 `/` 后缀，包含点文件。超长输出自动截断，可缩小目录范围继续查看。

## 工具开关

```toml theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
defaultTools = ["read", "grep", "find", "ls"]
```

`defaultTools` 控制内置工具白名单，空数组只保留扩展工具。启动参数可对单次会话覆盖配置：

| 参数                   | 作用       |
| -------------------- | -------- |
| `--tools`            | 所有工具的白名单 |
| `--exclude-tools`    | 排除指定工具   |
| `--no-builtin-tools` | 仅关闭内置工具  |
| `--no-tools`         | 关闭全部工具   |

Bypass 跳过普通调用的逐项审批，不等于工具不会修改磁盘或访问网络。审批策略详见[交互与输入](/docs/zh/step-code/guides/interaction#审批流程)。

## 下一步

* [`step` 命令](/docs/zh/step-code/reference/cli)
* [斜杠命令](/docs/zh/step-code/reference/slash-commands)
* [键盘快捷键](/docs/zh/step-code/reference/keyboard-shortcuts)
* [交互与输入](/docs/zh/step-code/guides/interaction)