10.2 文件系统工具

模型: claude-opus-4-6 (anthropic/claude-opus-4-6) 生成日期: 2026-02-17

---

OpenCode 的文件系统模块（file/）为 Agent 提供了文件读取、搜索、列表、变更监控等底层能力。本节将解析这个模块的五个子文件。

10.2.1 file/index.ts：文件操作核心

file/index.ts（584 行）是文件系统模块的核心，它提供了文件读取、目录列表、模糊搜索和 Git 状态查询等功能。

文件读取

File.read() 是 Read 工具的底层实现，它处理了多种文件类型：

export async function read(file: string): Promise<Content> {
  const full = path.join(Instance.directory, file)

  // 安全检查：防止路径逃逸
  if (!Instance.containsPath(full)) {
    throw new Error("Access denied: path escapes project directory")
  }

  // 图片文件：base64 编码
  if (isImageByExtension(file)) {
    const buffer = await bunFile.arrayBuffer()
    return { type: "text", content: Buffer.from(buffer).toString("base64"),
             mimeType: getImageMimeType(file), encoding: "base64" }
  }

  // 已知二进制文件：返回空内容
  if (isBinaryByExtension(file)) {
    return { type: "binary", content: "" }
  }

  // 文本文件：读取内容 + 附带 git diff
  const content = await bunFile.text()

  if (project.vcs === "git") {
    let diff = await $`git diff ${file}`.text()
    if (!diff.trim()) diff = await $`git diff --staged ${file}`.text()
    if (diff.trim()) {
      const original = await $`git show HEAD:${file}`.text()
      const patch = structuredPatch(file, file, original, content, "old", "new", {
        context: Infinity, ignoreWhitespace: true,
      })
      return { type: "text", content, patch, diff: formatPatch(patch) }
    }
  }
  return { type: "text", content }
}

关键设计点：

1. 路径安全检查：Instance.containsPath() 防止 Agent 通过 ../../etc/passwd 等路径逃逸出项目目录。

2. 二进制文件智能处理：维护了一个庞大的扩展名集合（binaryExtensions），涵盖可执行文件、音视频、压缩包、字体等 100+ 种格式。二进制文件不读取内容，避免填充无意义的数据到 LLM 上下文。

3. 图片特殊处理：图片文件以 base64 编码返回，支持 LLM 的多模态理解能力。

4. Git diff 附带：对于 Git 管理下的文件，如果有未提交的更改，返回值中会附带结构化的 diff 和 patch 信息——这让 LLM 不仅知道文件当前的内容，还知道"哪些部分是新修改的"。

文件搜索

File.search() 提供了基于 fuzzysort 的模糊文件搜索：

export async function search(input: {
  query: string;
  limit?: number;
  dirs?: boolean;
  type?: "file" | "directory"
}) {
  const result = await state().then(x => x.files())

  // 隐藏文件排序策略：除非查询以 "." 开头，否则将隐藏文件排到后面
  const preferHidden = query.startsWith(".") || query.includes("/.")

  // 使用 fuzzysort 进行模糊匹配
  const sorted = fuzzysort.go(query, items, { limit: searchLimit })
    .map(r => r.target)

  return output
}

衍生解释：模糊搜索（Fuzzy Search）

模糊搜索是一种允许近似匹配的搜索算法。当用户输入 "indx" 时，模糊搜索能匹配到 "index.ts"——即使有拼写错误或缺少字符。fuzzysort 是一个高性能的 JavaScript 模糊搜索库，它使用基于最长公共子序列（LCS）的评分算法来对结果排序。

文件列表通过 Ripgrep（下文介绍）在后台预加载，搜索时直接在内存中进行，保证了亚毫秒级的响应速度。

10.2.2 file/ignore.ts：忽略规则

FileIgnore 模块定义了 OpenCode 在扫描文件时应该跳过的目录和文件：

export namespace FileIgnore {
  const FOLDERS = new Set([
    "node_modules", "bower_components", ".pnpm-store",  // JavaScript
    "vendor",                                            // PHP/Go
    "dist", "build", "out", ".next",                     // 构建输出
    "target",                                            // Rust/Java
    ".git", ".svn", ".hg",                               // 版本控制
    ".vscode", ".idea",                                  // IDE
    "__pycache__", ".pytest_cache",                       // Python
    // ...共 30+ 个目录
  ])

  const FILES = [
    "**/*.swp", "**/*.swo",        // Vim 交换文件
    "**/*.pyc",                     // Python 字节码
    "**/.DS_Store", "**/Thumbs.db", // 操作系统
    "**/logs/**", "**/tmp/**",      // 日志和临时文件
    "**/coverage/**",               // 测试覆盖率
  ]

  export function match(filepath: string, opts?) {
    // 1. 白名单优先（如果匹配白名单则不忽略）
    for (const glob of opts?.whitelist || []) {
      if (glob.match(filepath)) return false
    }
    // 2. 路径中是否包含被忽略的目录名
    const parts = filepath.split(sep)
    for (let i = 0; i < parts.length; i++) {
      if (FOLDERS.has(parts[i])) return true
    }
    // 3. 文件名是否匹配被忽略的模式
    for (const glob of [...FILE_GLOBS, ...extra]) {
      if (glob.match(filepath)) return true
    }
    return false
  }
}

这个模块被 FileWatcher 用来过滤不需要监听的文件变化，避免 node_modules 等庞大目录的变更事件淹没系统。

10.2.3 file/ripgrep.ts：ripgrep 集成

Ripgrep（rg）是一个极快的文件搜索工具，OpenCode 使用它来完成文件列表枚举、内容搜索和目录树生成。

自动安装

如果系统中没有安装 ripgrep，OpenCode 会自动下载并安装到全局 bin 目录：

const state = lazy(async () => {
  // 1. 优先使用系统安装的 rg
  const system = Bun.which("rg")
  if (system) return { filepath: system }

  // 2. 否则下载预编译二进制
  const filepath = path.join(Global.Path.bin, "rg")
  if (!(await file.exists())) {
    const version = "14.1.1"
    const url = `https://github.com/BurntSushi/ripgrep/releases/download/${version}/${filename}`
    const response = await fetch(url)
    // ... 解压并安装
  }
  return { filepath }
})

支持的平台包括 macOS（arm64/x64）、Linux（arm64/x64）和 Windows（x64），分别对应不同的预编译包格式。

文件列表枚举

Ripgrep.files() 使用 rg --files 枚举项目中的所有文件：

export async function* files(input: { cwd: string; glob?: string[]; ... }) {
  const args = [await filepath(), "--files", "--glob=!.git/*"]
  if (input.hidden !== false) args.push("--hidden")
  // ...

  const proc = Bun.spawn(args, { cwd: input.cwd, stdout: "pipe" })
  const reader = proc.stdout.getReader()

  // 流式读取，逐行 yield
  while (true) {
    const { done, value } = await reader.read()
    if (done) break
    buffer += decoder.decode(value, { stream: true })
    const lines = buffer.split(/\r?\n/)
    buffer = lines.pop() || ""
    for (const line of lines) {
      if (line) yield line
    }
  }
}

这是一个 异步生成器（async generator）——它不会一次性将所有文件名加载到内存中，而是以流的方式逐行产出。这对大型项目（数万个文件）非常重要，避免了内存峰值。

目录树生成

Ripgrep.tree() 根据文件列表构建一个压缩的目录树字符串：

export async function tree(input: { cwd: string; limit?: number }) {
  const files = await Array.fromAsync(Ripgrep.files({ cwd: input.cwd }))

  // 构建树结构
  const root: Node = { name: "", children: new Map() }
  for (const file of files) {
    if (file.includes(".opencode")) continue  // 跳过 OpenCode 自身的文件
    const parts = file.split(path.sep)
    let node = root
    for (const part of parts.slice(0, -1)) {
      node = dir(node, part)  // 逐级创建目录节点
    }
  }

  // BFS 遍历并截断
  const lines: string[] = []
  // ... 广度优先遍历，超出 limit 则截断
  if (total > used) lines.push(`[${total - used} truncated]`)
  return lines.join("\n")
}

这个目录树是 OpenCode System Prompt 中"项目结构"部分的数据来源——它让 LLM 在第一轮对话中就能了解项目的整体目录布局。

10.2.4 file/watcher.ts：文件变更监听

FileWatcher 使用 @parcel/watcher（一个高性能的跨平台文件系统监听库）来实时监控文件变化：

export namespace FileWatcher {
  export const Event = {
    Updated: BusEvent.define("file.watcher.updated", z.object({
      file: z.string(),
      event: z.union([z.literal("add"), z.literal("change"), z.literal("unlink")]),
    })),
  }

  const state = Instance.state(async () => {
    // 根据平台选择最优的文件监听后端
    const backend = (() => {
      if (process.platform === "win32") return "windows"
      if (process.platform === "darwin") return "fs-events"
      if (process.platform === "linux") return "inotify"
    })()

    // 监听项目目录
    const sub = await w.subscribe(Instance.directory, subscribe, {
      ignore: [...FileIgnore.PATTERNS, ...cfgIgnores],
      backend,
    })

    // 同时监听 .git 目录的 HEAD 文件（检测分支切换）
    if (vcsDir) {
      const gitDirContents = await readdir(vcsDir)
      const ignoreList = gitDirContents.filter(entry => entry !== "HEAD")
      await w.subscribe(vcsDir, subscribe, {
        ignore: ignoreList,  // 只监听 HEAD 变化
        backend,
      })
    }
  })
}

衍生解释：文件系统监听技术

不同操作系统提供了不同的文件系统事件通知机制：

• macOS：FSEvents——Apple 的文件系统事件框架，可以高效地监听整个目录树的变化。

• Linux：inotify——Linux 内核的文件监听接口，需要为每个目录单独注册监听。

• Windows：ReadDirectoryChangesW——Windows API 的目录变更通知。

@parcel/watcher 封装了这些平台特定的接口，提供了统一的跨平台 API。

文件变更事件通过 Bus 发布，被其他模块（如 TUI）订阅：

const subscribe = (err, evts) => {
  for (const evt of evts) {
    if (evt.type === "create") Bus.publish(Event.Updated, { file: evt.path, event: "add" })
    if (evt.type === "update") Bus.publish(Event.Updated, { file: evt.path, event: "change" })
    if (evt.type === "delete") Bus.publish(Event.Updated, { file: evt.path, event: "unlink" })
  }
}

10.2.5 file/time.ts：文件时间戳管理

FileTime 模块实现了一个"读后写"的安全检查机制——确保 Agent 在修改文件之前已经读取过最新版本：

export namespace FileTime {
  // 记录每个 Session 中每个文件的最后读取时间
  export function read(sessionID: string, file: string) {
    read[sessionID] = read[sessionID] || {}
    read[sessionID][file] = new Date()
  }

  // 在写入前断言文件未被外部修改
  export async function assert(sessionID: string, filepath: string) {
    const time = get(sessionID, filepath)
    if (!time) {
      throw new Error("You must read file before overwriting it. Use the Read tool first")
    }
    const stats = await Bun.file(filepath).stat()
    if (stats.mtime.getTime() > time.getTime()) {
      throw new Error(
        `File ${filepath} has been modified since it was last read.\n` +
        `Last modification: ${stats.mtime.toISOString()}\n` +
        `Last read: ${time.toISOString()}\n\n` +
        `Please read the file again before modifying it.`
      )
    }
  }

  // 文件锁：串行化对同一文件的并发写入
  export async function withLock<T>(filepath: string, fn: () => Promise<T>): Promise<T> {
    const currentLock = current.locks.get(filepath) ?? Promise.resolve()
    let release: () => void
    const nextLock = new Promise<void>(resolve => { release = resolve })
    current.locks.set(filepath, currentLock.then(() => nextLock))
    await currentLock  // 等待前一个写入完成
    try {
      return await fn()
    } finally {
      release!()  // 释放锁，允许下一个写入
    }
  }
}

这个模块解决了两个关键的并发安全问题：

1. 过期读取检测：如果用户在 Agent 读取文件之后、Agent 写入之前手动修改了文件，assert() 会抛出错误，防止 Agent 覆盖用户的修改。

2. 并发写入串行化：withLock() 确保对同一文件的多个并发写入操作被串行执行，避免内容交错。

---

本节小结

OpenCode 的文件系统模块由五个子文件组成：index.ts 提供文件读取（支持二进制/图片/文本的智能分流和 Git diff 附带）和模糊搜索；ignore.ts 定义了 30+ 个应被忽略的目录和文件模式；ripgrep.ts 集成了 ripgrep 工具用于高性能文件枚举和内容搜索（含自动下载安装）；watcher.ts 使用 @parcel/watcher 实现跨平台文件变更监听；time.ts 通过读取时间戳和文件锁保证了并发安全。