bash tool

BashTool 是 Claude Code 中最复杂的工具之一，负责安全地执行 Shell 命令。

设计挑战

Shell 命令执行面临的挑战：

安全风险 - 恶意命令可能破坏系统
权限控制 - 需要细粒度的权限检查
平台差异 - Windows/Linux/macOS 的命令不同
长时间运行 - 某些命令需要后台执行

核心实现

输入 Schema

const BashInputSchema = z.object({
  command: z.string(),
  cwd: z.string().optional(),
  explanation: z.string().optional(),
  timeout: z.number().optional(),
});

执行流程

async execute(input: BashInput, context: ToolContext) {
  // 1. 命令分类
  const classification = classifyCommand(input.command);
  
  // 2. 权限检查
  const permission = await checkBashPermission(
    input.command,
    classification,
    context
  );
  
  if (!permission.allowed) {
    return {
      success: false,
      error: `Permission denied: ${permission.reason}`,
    };
  }
  
  // 3. 执行命令
  const result = await executeCommand(input.command, {
    cwd: input.cwd || context.cwd,
    timeout: input.timeout || 30000,
  });
  
  return {
    success: true,
    output: result.stdout + result.stderr,
  };
}

权限检查

命令分类

2600+ 行的权限检查逻辑：

// src/tools/BashTool/bashPermissions.ts

function classifyCommand(command: string): CommandClassification {
  // 危险命令
  if (/rm\s+-rf\s+\//.test(command)) {
    return { level: 'dangerous', reason: 'Deletes root directory' };
  }
  
  // 写操作
  if (/^(echo|cat)\s+>/.test(command)) {
    return { level: 'write', reason: 'Writes to file' };
  }
  
  // 只读操作
  if (/^(ls|cat|grep|find)/.test(command)) {
    return { level: 'read', reason: 'Read-only operation' };
  }
  
  // 网络操作
  if (/^(curl|wget|ssh)/.test(command)) {
    return { level: 'network', reason: 'Network access' };
  }
  
  // 未知命令
  return { level: 'unknown', reason: 'Unknown command' };
}

权限决策

async function checkBashPermission(
  command: string,
  classification: CommandClassification,
  context: ToolContext
): Promise<PermissionResult> {
  const mode = context.state.permissions.mode;
  
  // Auto 模式
  if (mode === 'auto') {
    if (classification.level === 'read') {
      return { allowed: true };
    }
    if (classification.level === 'write') {
      // 使用分类器判断
      return await classifierApprove(command, context);
    }
    if (classification.level === 'dangerous') {
      return { allowed: false, reason: 'Dangerous command' };
    }
  }
  
  // Manual 模式
  if (mode === 'manual') {
    return await askUser(command, classification);
  }
  
  // Supervised 模式
  if (mode === 'supervised') {
    const result = await executeDryRun(command);
    return await askUserWithPreview(command, result);
  }
}

命令执行

基本执行

async function executeCommand(
  command: string,
  options: ExecOptions
): Promise<ExecResult> {
  return new Promise((resolve, reject) => {
    const child = spawn(command, {
      shell: true,
      cwd: options.cwd,
      timeout: options.timeout,
    });
    
    let stdout = '';
    let stderr = '';
    
    child.stdout.on('data', data => {
      stdout += data.toString();
    });
    
    child.stderr.on('data', data => {
      stderr += data.toString();
    });
    
    child.on('close', code => {
      resolve({ code, stdout, stderr });
    });
    
    child.on('error', reject);
  });
}

后台执行

// controlPwshProcess 工具
async function startBackgroundProcess(
  command: string,
  cwd: string
): Promise<string> {
  const terminalId = generateId();
  
  const child = spawn(command, {
    shell: true,
    cwd: cwd,
    detached: true,
  });
  
  // 保存进程引用
  backgroundProcesses.set(terminalId, {
    pid: child.pid,
    command: command,
    startTime: Date.now(),
  });
  
  return terminalId;
}

平台适配

Windows 支持

function adaptCommandForWindows(command: string): string {
  // 替换 Unix 命令为 Windows 等价命令
  return command
    .replace(/^ls\b/, 'dir')
    .replace(/^cat\b/, 'type')
    .replace(/^rm\b/, 'del')
    .replace(/&&/g, ';');  // PowerShell 使用分号
}

Shell 检测

function detectShell(): 'bash' | 'zsh' | 'fish' | 'powershell' {
  if (process.platform === 'win32') {
    return 'powershell';
  }
  
  const shell = process.env.SHELL || '';
  if (shell.includes('zsh')) return 'zsh';
  if (shell.includes('fish')) return 'fish';
  return 'bash';
}

特殊处理

sed 命令

sed 在不同平台上行为不同：

function handleSedCommand(command: string): string {
  if (process.platform === 'darwin') {
    // macOS 需要 -i '' 而不是 -i
    return command.replace(/sed\s+-i\b/, 'sed -i ""');
  }
  return command;
}

管道命令

function parsePipelineCommand(command: string): string[] {
  // 分解管道命令
  return command.split('|').map(cmd => cmd.trim());
}

async function executePipeline(commands: string[]): Promise<string> {
  let output = '';
  
  for (const cmd of commands) {
    output = await executeCommand(cmd, { input: output });
  }
  
  return output;
}

安全措施

命令白名单

const SAFE_COMMANDS = new Set([
  'ls', 'cat', 'grep', 'find', 'head', 'tail',
  'git status', 'git log', 'git diff',
  'npm list', 'npm outdated',
]);

function isSafeCommand(command: string): boolean {
  const base = command.split(' ')[0];
  return SAFE_COMMANDS.has(base) || SAFE_COMMANDS.has(command);
}

危险命令黑名单

const DANGEROUS_PATTERNS = [
  /rm\s+-rf\s+\//,           // 删除根目录
  /chmod\s+777/,             // 修改权限
  /sudo\s+/,                 // 提权
  /curl\s+.*\|\s*bash/,      // 下载并执行
  />\s*\/dev\/sd[a-z]/,      // 直接写入磁盘
];

function isDangerous(command: string): boolean {
  return DANGEROUS_PATTERNS.some(pattern => pattern.test(command));
}

沙箱执行

async function executeSandboxed(
  command: string,
  cwd: string
): Promise<ExecResult> {
  // 使用 Docker 容器隔离
  const sandboxCommand = `
    docker run --rm \
      -v ${cwd}:/workspace \
      -w /workspace \
      --network none \
      alpine:latest \
      sh -c "${escapeCommand(command)}"
  `;
  
  return executeCommand(sandboxCommand);
}

输出处理

截断长输出

const MAX_OUTPUT_SIZE = 50000;

function truncateOutput(output: string): string {
  if (output.length <= MAX_OUTPUT_SIZE) {
    return output;
  }
  
  const head = output.slice(0, MAX_OUTPUT_SIZE * 0.8);
  const tail = output.slice(-MAX_OUTPUT_SIZE * 0.2);
  
  return `${head}\n\n[... ${output.length - MAX_OUTPUT_SIZE} characters truncated ...]\n\n${tail}`;
}

智能裁剪

function intelligentPrune(
  output: string,
  explanation: string
): string {
  // 根据 explanation 保留相关内容
  const keywords = extractKeywords(explanation);
  const lines = output.split('\n');
  
  const relevant = lines.filter(line =>
    keywords.some(kw => line.includes(kw))
  );
  
  if (relevant.length < lines.length * 0.3) {
    // 相关内容太少，返回完整输出
    return output;
  }
  
  return relevant.join('\n');
}

下一步

了解权限系统的详细规则
探索 AgentTool 的实现
查看其他核心工具

Previousagent tool NextREADME

hashtag设计挑战

hashtag核心实现

hashtag输入 Schema

hashtag执行流程

hashtag权限检查

hashtag命令分类

hashtag权限决策

hashtag命令执行

hashtag基本执行

hashtag后台执行

hashtag平台适配

hashtagWindows 支持

hashtagShell 检测

hashtag特殊处理

hashtagsed 命令

hashtag管道命令

hashtag安全措施

hashtag命令白名单

hashtag危险命令黑名单

hashtag沙箱执行

hashtag输出处理

hashtag截断长输出

hashtag智能裁剪

hashtag下一步

设计挑战

核心实现

输入 Schema

执行流程

权限检查

命令分类

权限决策

命令执行

基本执行

后台执行

平台适配

Windows 支持

Shell 检测

特殊处理

sed 命令

管道命令

安全措施

命令白名单

危险命令黑名单

沙箱执行

输出处理

截断长输出

智能裁剪

下一步