Glob 工具

Glob 工具用于使用模式匹配查找文件。

概述

Glob 工具允许 AI 助手在文件系统中搜索文件。它支持：

  • Unix shell 风格模式匹配
  • 递归目录搜索
  • 排除特定模式

定义位置

  • packages/opencode/src/tool/glob.ts
  • packages/opencode/src/tool/glob.txt

参数说明

参数名类型必填说明
patternstring是文件匹配模式（如 **/*.ts）

TypeScript 类型定义

export type GlobInput = {
  pattern: string // 支持 *, ?, [], {} 等模式
}

export type GlobOutput = {
  title: string // 搜索路径
  output: string // 匹配文件列表（每行一个）
  metadata: {
    count: number // 匹配的文件数量
  }
}

工作流程

1. 模式解析

const pattern = params.pattern

2. 文件搜索

const files = await fs.readdir(".", { recursive: true })

3. 模式匹配

const matches = files.filter((file) => {
  return minimatch(file, pattern, {
    dot: true, // 包含以 . 开头的文件
    nocase: true, // 不区分大小写
  })
})

4. 结果返回

const result = matches.join("\n")

return {
  title: ".",
  output: result,
  metadata: {
    count: matches.length,
  },
}

典型使用场景

场景 1：查找所有 TypeScript 文件

await GlobTool.execute(
  {
    pattern: "**/*.ts",
  },
  ctx,
)

// 输出：
src / app.ts
src / utils / helpers.ts
src / components / Button.ts

场景 2：递归查找

await GlobTool.execute(
  {
    pattern: "src/**/*.json",
  },
  ctx,
)

// 输出：
src / config.json
src / subconfig / config.json
src / data / users.json

场景 3：单层匹配

await GlobTool.execute(
  {
    pattern: "src/*.ts",
  },
  ctx,
)

场景 4：通配符模式

await GlobTool.execute(
  {
    pattern: "*.{js,ts}", // 匹配 .js 或 .ts
  },
  ctx,
)

支持的模式

模式说明示例
*匹配任意字符*.ts
?匹配单个字符file?.js
[]匹配字符集合*.[js,ts]
{}匹配嵌套模式（递归）**/*.ts
**匹配任意层级目录src/**/config.json
!排除模式!node_modules/**

错误处理

无匹配结果

// 返回空输出
output: ""
metadata: {
  count: 0
}

限制和注意事项

搜索限制

  • 默认从当前工作目录搜索
  • 支持递归搜索（使用 ** 模式）
  • 包含隐藏文件（以 . 开头）

性能考虑

  • 大型目录可能需要较长时间
  • 考虑使用更具体的模式减少匹配数量

权限要求

权限类型说明
read列出目录和文件的权限

最佳实践

1. 使用具体模式

// ✅ 好：具体模式
await GlobTool.execute(
  {
    pattern: "src/components/**/*.tsx",
  },
  ctx,
)

// ❌ 差：太宽泛
await GlobTool.execute(
  {
    pattern: "**",
  },
  ctx,
)

2. 组合使用

场景： 先找到文件，再读取

Glob (查找配置文件) → Read (读取内容)

3. 避免常见目录

// 排除 node_modules
await GlobTool.execute(
  {
    pattern: "src/**/*.ts",
  },
  ctx,
)
// 手动过滤 node_modules 中的文件

相关文档

变更历史

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