工具参考
CodeBuddy Code 可用工具的完整参考，包括权限要求。
CodeBuddy Code 内置一系列工具来帮助理解和修改代码库。下表中的工具名称即为权限规则、子代理工具列表和 Hook 匹配器中使用的标识符。
| 工具 | 说明 | 需要权限 |
|---|---|---|
Agent | 生成具有独立上下文窗口的子代理来处理任务 | 否 |
Artifact | 将本地单个 HTML 或 Markdown 文件发布为 artifact 并返回可分享的公网链接（Markdown 由服务端渲染为样式化页面）。传入 existingShareLink 可原地更新同一链接（仅刷新内容，不改动权限）。默认开启，可用 CODEBUDDY_ARTIFACT_ENABLED 或云端 productFeatures.Artifact 关闭（旧开关 CODEBUDDY_SHARE_LINK_ENABLED / productFeatures.ShareLink 仍兼容）。原名 ShareLink，旧名仅在权限规则（allow/deny、disallowedTools）中仍可匹配；hooks 的 matcher 与 --tools 白名单只认新名，需自行更新配置。参见环境变量 | 是 |
ArtifactControl | 对 Artifact 发布的 artifact 执行控制动作，当前仅支持取消发布（unpublish）：将公开链接设为私密。HTML 页面链接走取消发布；Markdown 文档链接会关闭公开访问并移除协作人。接受完整链接或裸 nodeId。原名 ShareLinkUnpublish（兼容范围同 Artifact） | 是 |
AskUserQuestion | 向用户提出多选问题，收集需求或澄清歧义 | 是 |
AskUserForStructuredInput | 让客户端把一段受限 JSON Schema 渲染成表单，收集结构化答复（多字段、每字段独立控件）。适合"多个 MCP 授权 / 多字段表单"等超出单/多选表达能力的场景。需 env CODEBUDDY_ENABLE_ASK_USER_FOR_STRUCTURED_INPUT=1 且客户端声明 elicitation.form capability，否则模型看不到该工具 | 是 |
Bash | 在你的环境中执行 Shell 命令。参见 Bash 工具行为 | 是 |
CronCreate | 调度定时或一次性任务。默认仅当前会话有效（退出后失效）；传 durable: true 会写盘并在专属任务会话中持续执行，此时需要一次授权。参见定时任务 | durable 任务需要 |
CronDelete | 按 ID 取消定时任务 | 否 |
CronList | 列出当前会话中所有定时任务 | 否 |
DeferExecuteTool | 执行通过 ToolSearch 发现的延迟加载工具 | 否 |
Edit | 对文件进行精确的字符串替换编辑 | 是 |
EnterPlanMode | 切换到计划模式，在编码前设计实现方案 | 否 |
EnterWorktree | 创建隔离的 git worktree 并切换到其中 | 是 |
ExitPlanMode | 提交计划供用户审批并退出计划模式 | 是 |
Glob | 基于 glob 模式查找文件 | 否 |
Grep | 在文件内容中搜索正则表达式模式 | 否 |
ImageGen | 根据文本描述生成图片，支持文生图和图生图 | 是 |
LeaveWorktree | 退出 worktree 会话并返回原始目录 | 是 |
ListMcpResources | 列出已连接 MCP 服务器暴露的所有资源/模板，可选按服务器名过滤 | 否 |
LSP | 通过语言服务器提供代码智能。文件编辑后自动报告类型错误和警告。还支持跳转定义、查找引用、获取类型信息、列出符号、查找实现、追踪调用层级等导航操作。需要代码智能插件及其语言服务器二进制文件 | 否 |
MultiEdit | 在单个原子操作中对同一文件执行多步编辑 | 是 |
NotebookEdit | 修改 Jupyter notebook 单元格内容 | 是 |
NotebookRead | 读取 Jupyter notebook 单元格内容，可指定 cell_id 读单个 cell | 否 |
PowerShell | 在 Windows 上执行 PowerShell 命令。仅 Windows 可用，参见 PowerShell 工具行为 | 是 |
PushNotification | 发送终端/桌面通知，用于长任务或后台任务完成时提醒用户。延迟加载工具，参见环境变量 | 否 |
Read | 读取文件内容，支持图片、PDF 和 Jupyter notebook | 否 |
REPL | 在隔离沙箱中执行 JavaScript 编排工具调用。PTC / 极简模式下这是模型面唯一直连工具；沙箱内 Bash 返回 { stdout, stderr, exitCode, signal }，Agent 返回 { taskId }，TaskOutput 返回 { status, taskId, content }。受 CODEBUDDY_REPL_ENABLED 控制，参见环境变量 | 是 |
ReadMcpResource | 按 server + URI 读取指定 MCP 资源的内容，配合 ListMcpResources 使用 | 是 |
ReportFindings | 将代码审查发现的问题以结构化字段（文件、摘要、失败场景、可选分类）提交，渲染为专门的列表组件而非纯文本。延迟加载工具，参见环境变量 | 否 |
SendMessage | 在 Agent 团队中向队友发送消息 | 否 |
SendUserMessage | 向用户发送面向阅读的消息（支持 markdown、附件、status 意图标签）。仅在 Brief 模式（--brief 或 CODEBUDDY_BRIEF）下可见，参见环境变量 | 否 |
Skill | 在主对话中执行 Skill 技能 | 否 |
SlashCommand | 执行自定义斜杠命令 | 是 |
StructuredOutput | 返回符合 JSON Schema 的结构化输出 | 否 |
TaskCreate | 创建新任务到任务列表 | 否 |
TaskGet | 获取特定任务的完整详情 | 否 |
TaskList | 列出所有任务及其当前状态 | 否 |
TaskOutput | 获取后台任务或子代理的输出。参数：task_id（必需）、block（默认 true）、timeout（默认 60000ms）。REPL 中返回 { status, taskId, content }；running 不是完成 | 否 |
TaskStop | 按 ID 终止正在运行的后台任务 | 否 |
TaskUpdate | 更新任务状态、依赖、详情或删除任务 | 否 |
TeamCreate | 创建 Agent 团队以协调多个代理协作 | 否 |
TeamDelete | 删除 Agent 团队及其任务目录 | 否 |
VideoGen | 根据文本描述或输入图片生成视频，支持文生视频和图生视频 | 是 |
ToolSearch | 搜索并加载延迟加载的工具，支持内置工具和 MCP 工具；可结合 Defer(...)/NoDefer(...) 修饰符 按需调整工具的延迟加载状态 | 否 |
WaitForMcpServers | 等待指定的 MCP 服务器完成连接（默认等所有 pending 的服务器），最长 5 秒 | 否 |
WebFetch | 获取指定 URL 的内容并进行 AI 分析 | 是 |
WebSearch | 执行网络搜索 | 是 |
Workflow | 启动 Dynamic Workflow 异步运行，立刻返回 runId 并在后台执行；通过 TaskOutput 拉取结果 | 是 |
Write | 创建或覆盖文件 | 是 |
权限规则可通过 /permissions 命令或在权限设置中配置。另请参阅工具特定的权限规则。
工具别名
部分工具拥有别名，可在权限规则中互换使用（仅适用于权限规则 allow/deny/ask 与 disallowedTools；hooks 的 matcher 与 --tools 白名单只按工具真实名匹配）：
| 工具 | 别名 |
|---|---|
TaskOutput | BashOutput |
TaskStop | KillShell |
PowerShell | pwsh、ps |
Artifact | ShareLink（更名前的旧名） |
ArtifactControl | ShareLinkUnpublish（更名前的旧名） |
Bash 工具行为
Bash 工具在独立进程中执行每条命令，具有以下持久化特性：
- 工作目录在命令间保持不变。设置
CODEBUDDY_BASH_MAINTAIN_PROJECT_WORKING_DIR=1可在每次命令后重置到项目目录。 - 环境变量不会持久化。一条命令中的
export不会在下一条命令中生效。
在启动 CodeBuddy Code 前激活你的 virtualenv 或 conda 环境。要使环境变量在 Bash 命令间持久化，启动前设置 CODEBUDDY_ENV_FILE 指向一个 shell 脚本，或使用 SessionStart Hook 动态填充。
沙箱模式
Bash 工具支持沙箱隔离，可限制文件系统和网络访问。启用沙箱时，命令在受限环境中执行，防止未授权的系统访问。
通过 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 服务器提供的工具，以及少数内置工具如 PushNotification、ReportFindings）采用延迟加载机制。这些工具不会在初始工具列表中出现，需要通过 ToolSearch 发现和激活。一旦激活，工具在会话剩余时间内保持可用。