# 工具参考

> CodeBuddy Code 可用工具的完整参考，包括权限要求。

CodeBuddy Code 内置一系列工具来帮助理解和修改代码库。下表中的工具名称即为[权限规则](iam.md#工具特定的权限规则)、[子代理工具列表](sub-agents.md)和 [Hook 匹配器](hooks.md)中使用的标识符。

| 工具 | 说明 | 需要权限 |
| :--- | :--- | :------- |
| `Agent` | 生成具有独立上下文窗口的[子代理](sub-agents.md)来处理任务 | 否 |
| `AskUserQuestion` | 向用户提出多选问题，收集需求或澄清歧义 | 是 |
| `Bash` | 在你的环境中执行 Shell 命令。参见 [Bash 工具行为](#bash-工具行为) | 是 |
| `CronCreate` | 在当前会话内调度定时或一次性任务（退出后失效）。参见[定时任务](scheduled-tasks.md) | 否 |
| `CronDelete` | 按 ID 取消定时任务 | 否 |
| `CronList` | 列出当前会话中所有定时任务 | 否 |
| `DeferExecuteTool` | 执行通过 `ToolSearch` 发现的延迟加载工具 | 否 |
| `Edit` | 对文件进行精确的字符串替换编辑 | 是 |
| `EnterPlanMode` | 切换到计划模式，在编码前设计实现方案 | 否 |
| `EnterWorktree` | 创建隔离的 [git worktree](worktree.md) 并切换到其中 | 是 |
| `ExitPlanMode` | 提交计划供用户审批并退出计划模式 | 是 |
| `Glob` | 基于 glob 模式查找文件 | 否 |
| `Grep` | 在文件内容中搜索正则表达式模式 | 否 |
| `ImageEdit` | 基于文本指令编辑或修改已有图片 | 是 |
| `ImageGen` | 根据文本描述生成图片 | 是 |
| `LeaveWorktree` | 退出 worktree 会话并返回原始目录 | 是 |
| `ListMcpResources` | 列出已连接 [MCP 服务器](mcp.md)暴露的所有资源/模板，可选按服务器名过滤 | 否 |
| `LSP` | 通过语言服务器提供代码智能。文件编辑后自动报告类型错误和警告。还支持跳转定义、查找引用、获取类型信息、列出符号、查找实现、追踪调用层级等导航操作。需要[代码智能插件](plugins.md)及其语言服务器二进制文件 | 否 |
| `MultiEdit` | 在单个原子操作中对同一文件执行多步编辑 | 是 |
| `NotebookEdit` | 修改 Jupyter notebook 单元格内容 | 是 |
| `NotebookRead` | 读取 Jupyter notebook 单元格内容，可指定 `cell_id` 读单个 cell | 否 |
| `PowerShell` | 在 Windows 上执行 PowerShell 命令。仅 Windows 可用，参见 [PowerShell 工具行为](#powershell-工具行为) | 是 |
| `Read` | 读取文件内容，支持图片、PDF 和 Jupyter notebook | 否 |
| `ReadMcpResource` | 按 server + URI 读取指定 MCP 资源的内容，配合 `ListMcpResources` 使用 | 是 |
| `SendMessage` | 在 [Agent 团队](agent-teams.md)中向队友发送消息 | 否 |
| `Skill` | 在主对话中执行 [Skill 技能](skills.md) | 否 |
| `SlashCommand` | 执行自定义[斜杠命令](slash-commands.md) | 是 |
| `StructuredOutput` | 返回符合 JSON Schema 的结构化输出 | 否 |
| `TaskCreate` | 创建新任务到任务列表 | 否 |
| `TaskGet` | 获取特定任务的完整详情 | 否 |
| `TaskList` | 列出所有任务及其当前状态 | 否 |
| `TaskOutput` | 获取后台任务或子代理的输出 | 否 |
| `TaskStop` | 按 ID 终止正在运行的后台任务 | 否 |
| `TaskUpdate` | 更新任务状态、依赖、详情或删除任务 | 否 |
| `TeamCreate` | 创建 [Agent 团队](agent-teams.md)以协调多个代理协作 | 否 |
| `TeamDelete` | 删除 Agent 团队及其任务目录 | 否 |
| `ToolSearch` | 搜索并加载延迟加载的工具，支持内置工具和 [MCP 工具](mcp.md#延迟加载-defer_loading) | 否 |
| `WaitForMcpServers` | 等待指定的 MCP 服务器完成连接（默认等所有 pending 的服务器），最长 5 秒 | 否 |
| `WebFetch` | 获取指定 URL 的内容并进行 AI 分析 | 是 |
| `WebSearch` | 执行网络搜索 | 是 |
| `Workflow` | 启动 [Dynamic Workflow](workflows.md) 异步运行，立刻返回 runId 并在后台执行；通过 `TaskOutput` 拉取结果 | 是 |
| `Write` | 创建或覆盖文件 | 是 |

权限规则可通过 `/permissions` 命令或在[权限设置](settings.md#权限设置)中配置。另请参阅[工具特定的权限规则](iam.md#工具特定的权限规则)。

## 工具别名

部分工具拥有别名，可在权限规则中互换使用：

| 工具 | 别名 |
| :--- | :--- |
| `TaskOutput` | `BashOutput` |
| `TaskStop` | `KillShell` |
| `PowerShell` | `pwsh`、`ps` |

## Bash 工具行为

Bash 工具在独立进程中执行每条命令，具有以下持久化特性：

* **工作目录**在命令间保持不变。设置 `CODEBUDDY_BASH_MAINTAIN_PROJECT_WORKING_DIR=1` 可在每次命令后重置到项目目录。
* **环境变量不会持久化**。一条命令中的 `export` 不会在下一条命令中生效。

在启动 CodeBuddy Code 前激活你的 virtualenv 或 conda 环境。要使环境变量在 Bash 命令间持久化，启动前设置 [`CODEBUDDY_ENV_FILE`](env-vars.md) 指向一个 shell 脚本，或使用 [SessionStart Hook](hooks.md) 动态填充。

### 沙箱模式

Bash 工具支持[沙箱隔离](bash-sandboxing.md)，可限制文件系统和网络访问。启用沙箱时，命令在受限环境中执行，防止未授权的系统访问。

通过 `dangerouslyDisableSandbox` 参数可逐条命令绕过沙箱（需要用户审批）。

### 后台执行

通过 `run_in_background` 参数可将命令在后台运行，使用 `TaskOutput` 工具读取输出。适用于长时间运行的构建、测试等场景。

## PowerShell 工具行为

PowerShell 工具仅在 Windows 上可用，提供原生 PowerShell 命令执行能力。

### 与 Bash 工具的关系

* **有 Git Bash 时**：Bash 工具和 PowerShell 工具同时可用，模型根据场景选择合适的工具
* **无 Git Bash 时**：Bash 工具自动禁用，PowerShell 工具成为唯一的 shell 工具
* macOS/Linux 上 PowerShell 工具不可用

### 版本适配

PowerShell 工具自动检测 PowerShell 版本，优先使用 PowerShell 7+（pwsh），其次使用 Windows PowerShell 5.1。prompt 中的语法指导会根据版本差异自动调整（如 `&&` 操作符仅 7+ 支持）。

### 安全检查

PowerShell 工具内置安全检查器，覆盖代码注入、下载执行、提权操作、系统破坏等危险模式。危险命令（如 `Invoke-Expression`、`Add-Type`）会被阻止，系统修改类命令需要用户确认。

### 环境变量

| 环境变量 | 说明 |
|---------|------|
| `CODEBUDDY_POWERSHELL_PATH` | 显式指定 PowerShell 路径（优先于自动检测） |
| `CODEBUDDY_USE_POWERSHELL_TOOL` | 设为 `0` 禁用 PowerShell 工具 |

## 延迟加载工具

部分工具（如通过 [MCP 服务器](mcp.md)提供的工具）采用延迟加载机制。这些工具不会在初始工具列表中出现，需要通过 `ToolSearch` 发现和激活。一旦激活，工具在会话剩余时间内保持可用。

## 另请参阅

* [身份和访问管理](iam.md)：权限系统、规则语法和工具特定规则
* [子代理](sub-agents.md)：为子代理配置工具访问权限
* [Hooks 钩子系统](hooks-guide.md)：在工具执行前后运行自定义命令
* [MCP 集成](mcp.md)：通过 MCP 服务器扩展可用工具
* [定时任务](scheduled-tasks.md)：使用 CronCreate 调度自动化任务
* [Agent 团队](agent-teams.md)：多代理协作的团队系统
