Bash 工具

Bash 工工具用于在持久化 Shell 会话中执行命令。

概述

Bash 工具允许 AI 助手在系统终端中执行命令。它支持：

持久化 Shell 会话
工作目录控制
超时限制
输出截断
Git 特殊处理

定义位置

packages/opencode/src/tool/bash.ts
packages/opencode/src/tool/bash.txt

参数说明

参数名	类型	必填	说明
`command`	string	是	要执行的命令
`workdir`	string	否	工作目录（默认 `${directory}`）

TypeScript 类型定义

export type BashInput = {
  command: string
  workdir?: string // 默认 Instance.directory
}

export type BashOutput = {
  title: string
  output: string
  metadata: {
    command: string
    truncated?: boolean
    outputPath?: string
  }
}

常量

定义位置：packages/opencode/src/tool/bash.ts:59

const DESCRIPTION = `Executes a given bash command in a persistent shell session with optional timeout.

All commands run in ${directory} by default. Use \`workdir\` parameter if you need to run a command in a different directory. AVOID using \`cd <directory> && <command>\` patterns - use \`workdir\` instead.
`
// ...

工作流程

1. 命令执行

const shell = Shell.preferred()
const shellName = platform === 'win32'
  ? path.basename(shell, '.exe').toLowerCase()
  : path.basename(shell)

const command = params.command
const cwd = params.workdir || Instance.directory

// 执行命令
const cmd = $`{shell} -c ${shell === powershell ? `-Command` : `-c"} ${command}`
  .cwd(cwd)
  .timeout(timeout)
  .quiet()
  .nothrow()

2. 输出处理

// 捕获输出
const stdout = cmd.stdout.toString().trim()
const stderr = cmd.stderr.toString().trim()

const output = stdout + (stderr ? `\n[stderr]\n${stderr}` : "")

// 如果输出被截断
if (truncated) {
  output += `\n[output truncated at ${maxBytes} bytes]`
}

典型使用场景

场景 1：运行 npm 命令

await BashTool.execute(
  {
    command: "npm install",
  },
  ctx,
)

场景 2：运行测试

await BashTool.execute(
  {
    command: "npm test",
  },
  ctx,
)

场景 3：在指定目录执行

await BashTool.execute(
  {
    command: "make",
    workdir: "/home/user/project/build",
  },
  ctx,
)

场景 4：Git 操作

await BashTool.execute(
  {
    command: "git status",
  },
  ctx,
)

场景 5：编译项目

await BashTool.execute(
  {
    command: "npm run build",
  },
  ctx,
)

错误处理

命令失败

Error: Command failed with exit code 1

超时错误

Error: Command timed out after 120000ms

限制和注意事项

默认超时

默认 120 秒（2 分钟）
可以通过配置调整

工作目录

默认：Instance.directory
使用 workdir 参数改变目录
不要使用 cd && 模式

输出限制

超出会被截断
截断输出会写入文件

Git 安全协议

来源：packages/opencode/src/tool/bash.txt:51-75

NEVER update git config
NEVER run destructive git commands
NEVER skip hooks
NEVER run force push to main/master
Avoid git commit --amend unless ALL conditions met
CRITICAL: Never amend if commit FAILED
CRITICAL: If already pushed, NEVER amend unless explicitly requested
NEVER commit unless user explicitly asks

最佳实践

1. 使用 workdir 而非 cd

// ✅ 好
await BashTool.execute(
  {
    command: "make",
    workdir: "/path/to/build",
  },
  ctx,
)

// ❌ 差
await BashTool.execute(
  {
    command: "cd /path/to/build && make",
  },
  ctx,
)

2. 并行执行独立命令

const [status, diff] = await Promise.all([
  BashTool.execute({ command: "git status" }, ctx),
  BashTool.execute({ command: "git diff" }, ctx),
])

3. 使用 && 链接依赖命令

await BashTool.execute(
  {
    command: "git add . && git commit -m 'message'",
  },
  ctx,
)

4. 引用带空格的路径

await BashTool.execute(
  {
    command: `cat "path with spaces/file.txt"`,
  },
  ctx,
)

变更历史

版本	变更内容	日期
v1	初始 Bash 工具	-