---
url: /wave-agent/specs/ui/tools-selection.md
description: '`--tools` 以逗号名单限定 agent 可用工具集（空串全禁、`default` 复原），含打印模式与 `Exec`/MCP 边界'
---

# 功能规格说明：工具选择

**创建日期**：2026-02-25

## 用户场景与测试 *（必填）*

### 用户故事：选择特定工具（优先级：P1）

作为用户，我希望将 agent 可用的工具限制为特定集合（例如仅"Read"和"Edit"），以便控制 agent 在给定会话中可以执行的操作。

**为什么是这个优先级**：这是请求的核心功能。它允许用户出于安全或专注目的限制 agent 的能力。

**独立测试**：可以通过使用 `--tools "Read,Edit"` 启动 CLI 并验证 agent 仅尝试使用这些工具来进行测试。

**验收场景**：

1. **假设** CLI 使用 `--tools "Read,Edit"` 启动，**当** agent 被要求执行任务时，**则**它应该只能访问"Read"和"Edit"工具。
2. **假设** CLI 使用 `--tools "Bash"` 启动，**当** agent 被要求读取文件时，**则**它应该失败或报告工具不可用。

***

### 用户故事：禁用所有工具（优先级：P2）

作为用户，我希望通过向 `--tools` 参数提供空字符串来禁用所有工具，确保 agent 只能通过文本进行通信。

**为什么是这个优先级**：提供"安全模式"或"仅聊天"模式，这是受限环境中的常见需求。

**独立测试**：使用 `--tools ""` 运行 CLI 并验证没有工具被注册或对 agent 可用。

**验收场景**：

1. **假设** CLI 使用 `--tools ""` 启动，**当** agent 初始化时，**则**提供给底层 SDK 的工具列表应为空。

***

### 用户故事：使用默认工具（优先级：P3）

作为用户，我希望使用"default"关键字显式请求默认工具集，或者完全省略该标志。

**为什么是这个优先级**：确保向后兼容并提供显式方式来重置为标准行为。

**独立测试**：使用 `--tools "default"` 运行 CLI 并验证其行为与不使用该标志运行完全相同。

**验收场景**：

1. **假设** CLI 使用 `--tools "default"` 启动，**当** agent 初始化时，**则**它应该可以访问完整的标准工具套件（Bash、Edit、Read、Glob、Grep 等）。

***

### 用户故事：打印模式工具选择（优先级：P2）

作为用户，我希望将 `--tools` 标志与 `--print`（或 `-p`）选项一起使用，以便控制在打印模式下生成输出时可用的工具。

**为什么是这个优先级**：确保在所有使用 agent 的 CLI 模式中保持一致。

**独立测试**：运行 `wave --print --tools "Read" "some prompt"` 并验证 agent 仅使用"Read"工具。

**验收场景**：

1. **假设** CLI 使用 `--print --tools "Read"` 运行，**当** agent 处理提示时，**则**它应该只能访问"Read"工具。

***

### 边界情况

* **无效工具名称**：当用户提供不存在的工具名称（例如 `--tools "MagicWand"`）时会发生什么？
  * *假设*：系统应该警告用户并忽略无效工具或快速失败。
* **大小写敏感性**：工具名称是否区分大小写（例如"bash"vs"Bash"）？
  * *假设*：为方便用户，工具名称应不区分大小写，但映射到正确的内部名称。
* **冗余输入**：`--tools "Read,Read,Edit"` 会怎样？
  * *假设*：重复项应被去重。
* **与 `Exec` 的关系**：`Exec` 是一个普通内置工具名，因此只有在 `--tools` 中显式列出它时才会注册；未列出时不注册，MCP 工具照常扁平声明（见 `docs/specs/core/exec-tool.md`）。把某个 MCP 工具排除出池不是本标志的职责——那是权限拒绝规则的语义（池与扁平声明走同一条拒绝过滤）。