path: root/packages/web/src/content/docs/zh-cn/modes.mdx

---
title: 模式
description: 不同的模式适用于不同的用例。
---

:::caution
现在通过opencode配置中的`agent`选项配置模式。这
`mode` 选项现已废弃。 [了解更多](/docs/agents)。
:::

opencode 中的模式允许自定义不同的示例行为、工具和提示。

它具有两种内置模式：**构建**和**计划**。您可以定制
这些或通过 opencode 配置配置您自己的。

您可以在会话期间在模式之间切换或在配置文件中配置它们。

---

## 内置

opencode 有两种内置模式。

---

### 构建

构建是启用所有工具的**默认**模式。这是开发工作的标准模式，您需要完全访问文件操作和系统命令。

---

### 计划

专为规划和分析而设计的受限模式。在计划模式下，默认情况下禁用以下工具：

- `write` - 无法创建新文件
- `edit` - 无法修改现有文件，位于 `.opencode/plans/*.md` 的用于详细说明计划本身的文件另外
- `patch` - 无法应用补丁
- `bash` - 无法执行 shell 命令

当您希望人工智能分析代码、建议更改或创建计划而不对代码库进行任何实际修改时，此模式非常有用。

---

## 切换

您可以在会话期间使用 _Tab_ 键在模式之间切换。或者您配置的 `switch_mode` 键绑定。

另请参见：[格式化程序](/docs/formatters)相关代码配置的信息。

---

## 配置

您可以自定义内置模式或通过配置创建自己的模式。可以通过两种方式配置模式：

### JSON 配置

在 `opencode.json` 配置文件中配置模式：

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "mode": {
    "build": {
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    }
  }
}
```

### Markdown 配置

您还可以使用 Markdown 文件定义模式。将它们放入：

- 全球：`~/.config/opencode/modes/`
- 项目：`.opencode/modes/`

```markdown title="~/.config/opencode/modes/review.md"
---
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

You are in code review mode. Focus on:

- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.
```

Markdown 文件名成为模式名称（例如，`review.md` 创建`review` 模式）。

让我们详细看看这些配置选项。

---

### 模型

使用`model`配置覆盖此模式的默认模型。对于使用针对不同任务优化的不同模型很有帮助。例如，更快的规划模型、更强大的实施模型。

```json title="opencode.json"
{
  "mode": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}
```

---

### 温度

使用`temperature`配置控制AI响应的随机性和创造。较低的值使响应更加集中和确定，而较高的值则增加创造力和可变性。

```json title="opencode.json"
{
  "mode": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}
```

温度值范围通常为 0.0 到 1.0：

- **0.0-0.2**：响应更集中、确定性更高，适合代码分析和规划
- **0.3-0.5**：平衡型响应，兼顾稳定性与创造力
- **0.6-1.0**：响应更有创意和多样性，适合头脑风暴和探索

```json title="opencode.json"
{
  "mode": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}
```

如果未指定温度，opencode将使用特定于模型的默认值（大多数模型通常为0，Qwen模型为0.55）。

---

### 提示词

使用 `prompt` 配置为模式指定自定义系统提示文件。提示文件应包含特定于该模式用途的指令。

```json title="opencode.json"
{
  "mode": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}
```

该路径是相对于配置文件所在位置的。所以这适用于
全局opencode配置和项目特定配置。

---

### 工具

使用 `tools` 配置控制模式下可用的工具。您可以通过将特定工具设置为 `true` 或 `false` 来启用或禁用特定工具。

```json
{
  "mode": {
    "readonly": {
      "tools": {
        "write": false,
        "edit": false,
        "bash": false,
        "read": true,
        "grep": true,
        "glob": true
      }
    }
  }
}
```

如果未指定任何工具，则默认启用所有工具。

---

#### 可用工具

这里是所有可以通过模式配置控制的工具。

| 工具        | 描述             |
| ----------- | ---------------- |
| `bash`      | 执行shell命令    |
| `edit`      | 修改现有文件     |
| `write`     | 创建新文件       |
| `read`      | 读取文件内容     |
| `grep`      | 搜索文件内容     |
| `glob`      | 按模式查找文件   |
| `list`      | 上市目录内容     |
| `patch`     | 对文件应用补丁   |
| `todowrite` | 管理待办事项列表 |
| `todoread`  | 阅读待办事项列表 |
| `webfetch`  | 获取网页内容     |

---

## 自定义模式

您可以通过将自定义模式添加到配置来创建自己的自定义模式。以下是使用这两种方法的示例：

### 使用 JSON 配置

```json title="opencode.json" {4-14}
{
  "$schema": "https://opencode.ai/config.json",
  "mode": {
    "docs": {
      "prompt": "{file:./prompts/documentation.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": false,
        "read": true,
        "grep": true,
        "glob": true
      }
    }
  }
}
```

### 使用 Markdown 文件

在`.opencode/modes/`中为项目特定模式创建模式文件，在`~/.config/opencode/modes/`中为全局模式创建模式文件：

```markdown title=".opencode/modes/debug.md"
---
temperature: 0.1
tools:
  bash: true
  read: true
  grep: true
  write: false
  edit: false
---

You are in debug mode. Your primary goal is to help investigate and diagnose issues.

Focus on:

- Understanding the problem through careful analysis
- Using bash commands to inspect system state
- Reading relevant files and logs
- Searching for patterns and anomalies
- Providing clear explanations of findings

Do not make any changes to files. Only investigate and report.
```

```markdown title="~/.config/opencode/modes/refactor.md"
---
model: anthropic/claude-sonnet-4-20250514
temperature: 0.2
tools:
  edit: true
  read: true
  grep: true
  glob: true
---

You are in refactoring mode. Focus on improving code quality without changing functionality.

Priorities:

- Improve code readability and maintainability
- Apply consistent naming conventions
- Reduce code duplication
- Optimize performance where appropriate
- Ensure all tests continue to pass
```

---

### 使用案例

以下是不同模式的一些常见用例。

- **构建模式**：启用所有工具的完整开发工作
- **计划模式**：分析和计划，无需更改
- **审阅模式**：使用只读访问权限和文档工具进行代码审阅
- **调试模式**：专注于启用bash和读取工具的调查
- **文档模式**：使用文件操作但不使用系统命令的文档编写

您可能还会发现不同的模型适用于不同的用例。