Bash 工具实现和安全权限设计细节

export const BashTool = buildTool({
  name: BASH_TOOL_NAME,
  searchHint: 'execute shell commands',
  description: getSimplePrompt(),
  inputSchema: z.strictObject({
    command: z.string().describe('要执行的命令'),
    timeout: z.number().optional().describe('可选的超时时间，单位为毫秒'),
    description: z.string().optional().describe('用主动语态简明扼要地描述该命令的作用'),
    //全局禁用后台任务时隐藏
    run_in_background: z.boolean().optional().describe('设置为 true 可在后台运行此命令'), 
    // 危险操作
    dangerouslyDisableSandbox: z.boolean().optional().describe('设置为 true 将强制跳过沙箱模式执行命令'), 
    // 始终对模型隐藏
    _simulatedSedEdit: z.object({ filePath: z.string(), newContent: z.string() }).optional().describe('内部字段：预览阶段预计算的 sed 编辑结果'), 
  }),
  // ... 其他方法如 call、checkPermissions 等
})

import { spawn } from 'child_process';

//使用 Promise 模式
function runWithPromise(command: string, args: string[]): Promise<{ stdout: string;
 code: number }> {
  return new Promise((resolve) => {
    const proc = spawn(command, args);
    let stdout = '';

    // 只要子进程有输出，就拼接到 stdout 字符串里
    proc.stdout.on('data', (chunk) => {
      stdout += chunk.toString();
    });

    // 等子进程完全结束后，一次性 resolve
    proc.on('close', (code) => {
      resolve({ stdout, code: code ?? 0 });
    });
  });
}
const result = await runWithPromise('ping', ['-c', '5', 'google.com']);
console.log("==Promise==")
console.log(result.stdout); // 用户等了 5 秒，然后突然全部刷出来

//使用 Generator 模式
async function* runWithGenerator(command: string, args: string[]) {
  const proc = spawn(command, args);
  let fullOutput = '';

  // 把"下一行输出"包装成一个 Promise
  let resolveNextLine: ((value: string) => void) | null = null;
  proc.stdout.on('data', (chunk) => {
    const text = chunk.toString();
    fullOutput += text;
    if (resolveNextLine) {
      resolveNextLine(text);   // 唤醒 generator
      resolveNextLine = null;
    }
  });

  // 把"进程结束"包装成一个 Promise
  let resolveExit: ((code: number) => void) | null = null;
  proc.on('close', (code) => {
    if (resolveExit) resolveExit(code ?? 0);
  });
  const exitPromise = new Promise<number>((resolve) => {
    resolveExit = resolve;
  });

  // 核心循环：race 等待"新输出"或"进程结束"
  while (true) {
    const nextLinePromise = new Promise<string>((resolve) => {
      resolveNextLine = resolve;
    });

    // 关键：同时监听两个事件，哪个先到就处理哪个
    const winner = await Promise.race([
      nextLinePromise.then(text => ({ type: 'output' as const, text })),
      exitPromise.then(code => ({ type: 'exit' as const, code })),
    ]);

    if (winner.type === 'exit') {
      // 进程结束了，return 最终值
      return { stdout: fullOutput, code: winner.code };
    }

    // 进程还在跑，有新输出，yield 进度
    yield {
      output: winner.text,      // 这次新增的内容
      fullOutput,                // 截至目前全部内容
    };
  }
}
const gen = runWithGenerator('ping', ['-c', '5', 'google.com']);
while (true) {
    const step = await gen.next();
  
    if (step.done) {
      console.log('Exit code:', step.value.code);
      break;
    }
    console.log("==Generator==")
    console.log(step.value.output);
  
    process.stdout.write(step.value.output);
}

// 调用底层 exec（file mode：stdout 直接写文件，不经过 JS data 事件）
const shellCommand = await exec(command, abortController.signal, 'bash', {
    timeout: timeoutMs,
    onProgress(lastLines, allLines, totalLines, totalBytes, isIncomplete) {
        lastProgressOutput = lastLines;
        lastTotalLines = totalLines;
        lastTotalBytes = isIncomplete ? totalBytes : 0;
        // 唤醒 race
        if (resolveProgress) {
        resolveProgress();
        resolveProgress = null;
        }
    },
});

const MAX_INLINE_SIZE = 128 * 1024;      // 128KB：直接返回内容
async function resolveOutput(outputFilePath: string, taskId: string) {
    const stat = await fsStat(outputFilePath);
    const totalBytes = stat.size;
  
    // 1. 小文件：直接返回
    if (totalBytes <= MAX_INLINE_SIZE) {
      const content = await readFile(outputFilePath, 'utf-8');
      return {content,persistedPath: undefined};
    }
  
    // 2. 大文件：读取截断内容，复制文件，最终返回截断内容 + 完整文件路径
    const preview = await readFileRange(outputFilePath, 0, MAX_INLINE_SIZE);
    const dest = getToolResultPath(taskId, false);
    await copyFile(outputFilePath, dest);
    return {
      content:`[Large output (${totalBytes} bytes). ` +`Showing first ${MAX_INLINE_SIZE} bytes. ` +`Use FileRead for full content.]\n${preview}`,
      persistedPath: dest,
    };
  }

const data = {
    stdout: compressedStdout,                    // 核心输出（可能含 stderr 混合内容）
    stderr: stderrForShellReset,                 // 仅用于 cwd 重置提示
    interrupted: wasInterrupted,                 // 是否被中断
    isImage,                                      // 是否是图片输出
    returnCodeInterpretation: interpretationResult?.message,  // 退出码语义解释
    noOutputExpected: isSilentBashCommand(input.command),     // 成功时是否应无输出
    dangerouslyDisableSandbox: input.dangerouslyDisableSandbox,  // 是否绕过沙箱
    persistedOutputPath,                          // 大输出持久化路径
    persistedOutputSize                           // 大输出字节数
};

// web-tree-sitter (WASM) 版本
import { Language, Parser } from 'web-tree-sitter';

async function main() {
  await Parser.init();

  const lang = await Language.load('./tree-sitter-bash.wasm');
  const parser = new Parser();
  parser.setLanguage(lang);

  const command = 'grep -r "foo" . && cat file.txt | wc -l';
  const tree = parser.parse(command);

  // 收集所有 command 节点
  const commands: string[] = [];
  function walk(node: any) {
    if (node.type === 'command') commands.push(node);
    for (const child of node.children) walk(child);
  }
  walk(tree?.rootNode);

  // 提取 argv
  function argv(node: any) {
    return node.children
      .filter((c: any) => ['word', 'string', 'raw_string'].includes(c?.type))
      .map((c: any) => c.text);
  }

  console.log(`Found ${commands.length} command(s):\n`);
  commands.forEach((cmd: any, i: number) => {
    console.log(`[${i + 1}] ${cmd.text.trim()}`);
    console.log(`    argv: ${JSON.stringify(argv(cmd))}\n`);
  });
}

main();

Found 3 command(s):

[1] grep -r "foo" .
    argv: ["-r","\"foo\"","."]

[2] cat file.txt
    argv: ["file.txt"]

[3] wc -l
    argv: ["-l"]

// 匹配控制字符
  const CONTROL_CHAR_RE = /[\x00-\x08\x0B-\x1F\x7F]/
  
  //匹配 Unicode 空白
  const UNICODE_WHITESPACE_RE =/[\u00A0\u1680\u2000-\u200B\u2028\u2029\u202F\u205F\u3000\uFEFF]/
  
  //匹配反斜杠转义空白
  const BACKSLASH_WHITESPACE_RE = /\\[ \t]|[^ \t\n\\]\\\n/

const CONTROL_CHAR_RE = /[\x00-\x08\x0B-\x1F\x7F]/
const UNICODE_WHITESPACE_RE =/[\u00A0\u1680\u2000-\u200B\u2028\u2029\u202F\u205F\u3000\uFEFF]/
const BACKSLASH_WHITESPACE_RE = /\\[ \t]|[^\t\n\\]\\\n/,
这三条正则分别拦截了 tree-sitter 和 bash 的哪几种分词分歧？为什么放在 AST 遍历之前而不是之后？并且举一个实际例子

const DANGEROUS_TYPES = new Set([
    'command_substitution',   // $(cmd) 或 `cmd`
    'process_substitution',   // <(cmd) 或 >(cmd)
    'expansion',              // ${VAR}
    'simple_expansion',       // $VAR
    'brace_expression',       // {a,b,c}
    'subshell',               // (cmd)
    'compound_statement',     // { cmd; cmd; }
    'for_statement',          // for i in ...; do ...; done
    'while_statement',        // while ...; do ...; done
    'until_statement',        // until ...; do ...; done
    'if_statement',           // if ...; then ...; fi
    'case_statement',         // case ... in ... esac
    'function_definition',    // foo() { ... }
    'test_command',           // [[ ... ]]
    'ansi_c_string',          // $'...'
    'translated_string',      // $"..."
    'herestring_redirect',    // <<< ...
    'heredoc_redirect',       // << ...
  ])

export function parseForSecurityFromAst(
    cmd: string,
    root: Node | typeof PARSE_ABORTED,
  ): ParseForSecurityResult {
    // ── AST 遍历：核心安全检查 ──
    // 直接 too-complex，不再进入后续的精细分析。
    if (root.type === 'ERROR' || DANGEROUS_TYPES.has(root.type)) {
      return tooComplex(root)
    }
    
    //.....
    
    // ── 没有命中：结构化提取成功 ──
    return { kind: 'simple', commands }
  }

{
    argv: ['timeout', '5', 'eval', 'rm -rf /'],
    envVars: [],
    redirects: [],
    text: 'timeout 5 eval "rm -rf /"'
  }

let a = cmd.argv
  for (;;) {
    if (a[0] === 'time' || a[0] === 'nohup') {
      a = a.slice(1)
    } else if (a[0] === 'timeout') {
      // 遍历 GNU timeout 的 flag（--foreground, -k, -s...）
      // 跳过 duration（5, 10s, 0.5...）
      // 未知 flag 或无法识别的 duration → 直接拒绝
      a = a.slice(i + 1)  // 从 duration 之后开始
    } else if (a[0] === 'nice') {
      // 跳过 -n N 或 -N，然后 slice
      // 如果参数包含 $((...)) 等 expansion → 直接拒绝
      a = a.slice(...)
    } else if (a[0] === 'env') {
      // 跳过 VAR=val 赋值和已知 flag（-i, -0, -v, -u NAME）
      // 遇到 -S / -C / -P 或任何未知 flag → 直接拒绝
      a = a.slice(i)
    } else if (a[0] === 'stdbuf') {
      // 跳过 -o MODE / --output=MODE 等已知形式
      // 未知 flag → 直接拒绝
      a = a.slice(i)
    } else {
      break  // 不是 wrapper 了，停止剥壳
    }
  }
  const name = a[0]  // 这才是真正要执行的命令名

const name = a[0]

  // 1. 空命令名
  if (name === '') {
    return { ok: false, reason: 'Empty command name — argv[0] may not reflect what
  bash runs' }
  }

  // 2. 占位符命令名
  if (name.includes("__CMDSUB_OUTPUT__") || name.includes("__TRACKED_VAR__")) {
    return { ok: false, reason: 'Command name is runtime-determined (placeholder
  argv[0])' }
  }

  // 3. 片段化命令（以操作符开头）
  if (name.startsWith('-') || name.startsWith('|') || name.startsWith('&')) {
    return { ok: false, reason: 'Command appears to be an incomplete fragment' }
  }

const EVAL_LIKE_BUILTINS = new Set([
    'eval',       // 直接求值字符串
    'source',     // 执行脚本文件
    '.',          // source 的别名
    'exec',       // 替换当前进程执行新程序
    'command',    // 绕过 alias/function 查找
    'builtin',    // 强制调用 builtin
    'fc',         // 编辑/重新执行历史命令
    'coproc',     // 协进程
    'noglob',     // zsh 前缀修饰符
    'nocorrect',  // zsh 前缀修饰符
    'trap',       // 设置信号处理程序
    'enable',     // 加载 .so 作为 builtin
    'mapfile',    // 带回调的数组读取
    'readarray',  // mapfile 的别名
    'hash',       // 污染命令查找缓存
    'bind',       // 绑定键盘回调
    'complete',   // 补全回调
    'compgen',    // 补全生成（可执行 -C 参数）
    'alias',      // 定义别名
    'let',        // 算术求值
  ])
  
  //拦截逻辑：
  if (EVAL_LIKE_BUILTINS.has(name)) {
    // 几个特例放行：
    // - command -v / command -V：只打印路径，不执行
    // - fc -l / fc -ln：列出历史，安全
    // - compgen -c/-f/-v：只列出补全，安全
    // 其余全部拒绝
    return { ok: false, reason: `'${name}' evaluates arguments as shell code` }
  }

//核心代码
  if (hasCd && hasGit) {
    return { behavior: 'ask', reason: '...bare repository attacks' }
  }

export function isDangerousRemovalPath(resolvedPath: string): boolean
   {
    const forwardSlashed = resolvedPath.replace(/[\\/]+/g, '/')

    // 1. 通配符删除当前目录全部内容
    if (forwardSlashed === '*' || forwardSlashed.endsWith('/*')) return
   true

    const normalizedPath =forwardSlashed === '/' ? forwardSlashed :forwardSlashed.replace(/\/$/, '')

    // 2. 根目录
    if (normalizedPath === '/') return true

    // 3. Windows 驱动器根目录
    if (WINDOWS_DRIVE_ROOT_REGEX.test(normalizedPath)) return true

    // 4. 用户主目录
    const normalizedHome = homedir().replace(/[\\/]+/g, '/')
    if (normalizedPath === normalizedHome) return true

    // 5. 根目录的直接子目录（如 /usr, /tmp, /etc）
    const parentDir = dirname(normalizedPath)
    if (parentDir === '/') return true

    // 6. Windows 驱动器的直接子目录（如 C:\Windows）
    if (WINDOWS_DRIVE_CHILD_REGEX.test(normalizedPath)) return true

    return false
  }

{
    "permissions": {
      "allow": ["Bash(git status:*)", "Bash(npm install:*)"],
      "deny": ["Bash(rm:*)", "Bash(rm -rf:*)"],
      "ask": ["Bash(docker:*)"]
    }
}