@kepoai/ai-file-tools

专业的 AI Agent 文件操作工具集 - 从 Gemini CLI 提取并增强，具备 AI 增强功能。

为你的 AI Agent 提供完整的工具包，用于探索、分析和修改代码库。为生产环境构建，完美集成 AI SDK v5。

English | 简体中文

📖 文档

• README.zh-CN.md - 你在这里！中文主文档
• README.md - 英文主文档
• TOOLS_REFERENCE.zh-CN.md - 所有 8 个工具的完整指南
• AI_CORRECTION.md - AI 辅助编辑纠错功能
• MIGRATION.md - 从 Gemini CLI 迁移指南
• DEVELOPMENT.md - 贡献和开发指南
• CHANGELOG.md - 版本历史
• docs/archive/ - 历史文档

特性

• 🗂️ 文件操作：通过 AI 辅助读取、写入和编辑文件
• 🔍 搜索与发现：列出目录、查找文件、搜索内容
• 🤖 AI 增强：内置 AI 纠错功能用于编辑操作
• 🔒 安全：基于工作区的路径验证，支持 .gitignore 和 .geminiignore
• ⚡ 高性能：LRU 缓存优化 AI 纠错性能
• 📦 轻量级：依赖少，API 简洁
• 🔌 灵活：支持 AI SDK v5 和 OpenRouter

安装

# 使用 pnpm（推荐）
pnpm add @kepoai/ai-file-tools

# 使用 npm
npm install @kepoai/ai-file-tools

# 使用 yarn
yarn add @kepoai/ai-file-tools

快速开始

import { createOpenRouter } from '@openrouter/ai-sdk-provider';
import {
  createFileTools,
  createToolSchemas,
} from '@kepoai/ai-file-tools';
import { generateText } from 'ai';

// 1. 初始化 AI 客户端
const openrouter = createOpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
});
const model = openrouter('anthropic/claude-3.5-sonnet');

// 2. 创建文件工具
const fileTools = createFileTools({
  workspaceDirs: ['/path/to/project'],  // 项目路径
  aiClient: model,                       // AI 客户端
  enableAiCorrection: true,              // 启用 AI 纠错
});

// 3. 创建工具 schemas
const toolSchemas = createToolSchemas(fileTools);

// 4. 使用 AI SDK
const result = await generateText({
  model,
  tools: toolSchemas,
  prompt: '查找 src/ 目录下所有包含 TODO 注释的 TypeScript 文件',
});

console.log(result.text);

可用工具

文件操作（5 个工具）

📄 read_file - 读取文件

支持多种文件格式的读取：

• 文本文件：JavaScript、TypeScript、Python、JSON、YAML 等
• 图片：PNG、JPG、GIF、WEBP、SVG、BMP（嵌入为内联数据）
• PDF：自动提取文本内容
• 大文件：支持分页读取（offset/limit）

✏️ write_file - 写入文件

写入或覆盖整个文件内容：

• 应用更改前显示 diff 预览
• 自动创建父目录
• 返回统计信息（添加/删除的行数）
• 支持所有文本编码

🔄 replace (EditTool) - 精确替换

具有 AI 纠错能力的精确文本替换：

• 带上下文的精确字符串匹配
• AI 自动纠错处理格式问题（空格、缩进）
• LRU 缓存提升性能
• 支持单文件多次替换

🎯 smart_edit (SmartEditTool) - 智能编辑

使用自然语言指令进行语义化代码编辑：

• 使用 AI 理解编辑意图
• 自动生成精确的 old_string/new_string
• 适合复杂的重构任务
• 结合 AI 推理与可靠的文本替换

📚 read_many_files - 批量读取

高效批量读取多个文件：

• Glob 模式匹配（**/*.ts、src/**/*.{js,jsx}）
• 递归目录遍历
• 文件过滤（遵循 .gitignore/.geminiignore）
• 一次调用返回所有文件内容

搜索与发现（3 个工具）

📁 list_directory - 列出目录

智能过滤的目录内容列表：

• 文件和目录信息（大小、类型、修改时间）
• 遵循 .gitignore 和 .geminiignore
• 自定义忽略模式
• 排序输出（目录优先，然后按字母顺序）

🔍 glob - 文件搜索

按名称模式查找文件：

• 完整的 glob 语法支持（**/*、*.{ts,tsx}、src/**/test_*.py）
• 跨工作区搜索
• 文件过滤（排除 node_modules、.git 等）
• 结果按修改时间排序

🔎 search_file_content - 内容搜索

使用正则表达式搜索文件内容：

• 不区分大小写的模式匹配
• 文件类型过滤（*.ts、*.py）
• 行号和上下文
• 性能限制（避免搜索大型二进制文件）

配置

interface ToolConfig {
  workspaceDirs: string[];           // 必需：工作区目录
  aiClient?: LanguageModelV1;        // 可选：AI SDK v5 客户端（AI 纠错需要）
  enableAiCorrection?: boolean;      // 可选：启用 AI 纠错（默认：提供 aiClient 时为 true）
  maxCacheSize?: number;             // 可选：缓存大小（默认：50）
  fileFiltering?: {
    respectGitIgnore?: boolean;      // 默认：true - 遵循 .gitignore 规则
    respectGeminiIgnore?: boolean;   // 默认：true - 遵循 .geminiignore 规则
  };
}

AI 辅助编辑纠错

当编辑操作无法精确匹配文本时，内置的 AI 纠错器会自动：

1. 检测常见问题（空格、转义、缩进）
2. 调用轻量级 LLM 建议纠正方案
3. 缓存结果以提升性能
4. 使用纠正后的参数重试

这极大提高了 AI 生成编辑的成功率。

📖 查看完整的 AI 纠错文档

Electron 集成示例

// main.ts (Electron 主进程)
import { ipcMain } from 'electron';
import { createOpenRouter } from '@openrouter/ai-sdk-provider';
import { createFileTools } from '@kepoai/ai-file-tools';
import { generateText } from 'ai';
import * as path from 'path';

// 初始化工具（只需一次）
const openrouter = createOpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
});
const model = openrouter('anthropic/claude-3.5-sonnet');

const fileTools = createFileTools({
  workspaceDirs: [path.join(app.getPath('documents'), 'MyProject')],
  aiClient: model,
  enableAiCorrection: true,
});

// 处理来自渲染进程的 IPC 请求
ipcMain.handle('ai-edit-file', async (event, prompt: string) => {
  const result = await generateText({
    model,
    tools: {
      read_file: readFileSchema(fileTools.readFile),
      replace: editSchema(fileTools.edit),
    },
    prompt,
  });
  
  return result;
});

高级用法

自定义工具配置

const fileTools = createFileTools({
  workspaceDirs: [
    '/path/to/project',
    '/path/to/another/workspace',
  ],
  aiClient: model,
  
  // 禁用 AI 纠错以加快执行速度
  enableAiCorrection: false,
  
  // 增加缓存大小以提升性能
  maxCacheSize: 100,
  
  // 自定义文件过滤
  fileFiltering: {
    respectGitIgnore: true,
    respectGeminiIgnore: false,
  },
});

单独使用工具

import { ReadFileTool, EditTool, ToolsConfig } from '@kepoai/ai-file-tools';

const config = new ToolsConfig({
  workspaceDirs: ['/path/to/project'],
  aiClient: model,
});

const readTool = new ReadFileTool(config);
const editTool = new EditTool(config);

// 直接使用工具
const fileContent = await readTool.execute({
  absolute_path: '/path/to/project/config.ts',
});

const editResult = await editTool.execute({
  file_path: '/path/to/project/config.ts',
  old_string: 'port: 3000',
  new_string: 'port: 8080',
});

实际使用案例

示例 1：自动化代码重构

import { createFileTools, createToolSchemas } from '@kepoai/ai-file-tools';
import { generateText } from 'ai';

const tools = createFileTools({ workspaceDirs: ['/my-project'] });
const schemas = createToolSchemas(tools);

const result = await generateText({
  model,
  tools: schemas,
  prompt: `
    查找 src/ 目录下所有使用旧 'getUserData' API 的函数，
    并将它们重构为使用新的 'fetchUserProfile' API。
  `,
});

示例 2：批量修复文件

const result = await generateText({
  model,
  tools: schemas,
  prompt: `
    搜索 src/ 目录下所有包含 'console.log' 的文件，
    并将它们替换为正确的 logger.debug() 调用。
  `,
});

示例 3：生成新功能

const result = await generateText({
  model,
  tools: schemas,
  prompt: `
    分析 src/features/ 的项目结构，
    创建一个名为 'notifications' 的新功能模块，
    遵循现有功能的相同模式。
  `,
});

常见问题

问：必须提供 AI 客户端吗？

答：aiClient 是可选的。只有在启用 AI 辅助编辑纠错时才需要。如果不提供，所有工具都能正常工作，但不会自动修复 replace 和 smart_edit 操作中的格式问题。

问：支持哪些 AI 模型？

**答：**支持任何兼容 AI SDK v5 的模型。已测试：

• Anthropic Claude (3.5 Sonnet, 3 Opus)
• OpenAI GPT-4
• Google Gemini (通过 OpenRouter)
• 任何 OpenRouter 支持的模型

问：文件过滤如何工作？

**答：**默认情况下，工具遵循 .gitignore 和 .geminiignore 规则。这意味着：

• node_modules/、.git/、dist/ 会自动排除
• 你可以在 .geminiignore 中添加自定义模式
• 可以按工具或全局配置禁用过滤

问：可以不使用 AI SDK 吗？

**答：**可以！你可以直接使用工具：

import { ReadFileTool, EditTool, ToolsConfig } from '@kepoai/ai-file-tools';

const config = new ToolsConfig({ workspaceDirs: ['/project'] });
const readTool = new ReadFileTool(config);

const result = await readTool.execute({ 
  absolute_path: '/project/src/index.ts' 
});
console.log(result.llmContent);

问：在生产环境中使用安全吗？

**答：**是的。该包包含：

• ✅ 工作区路径验证（防止访问指定目录之外的文件）
• ✅ 文件过滤（遵循 .gitignore/.geminiignore）
• ✅ 无文件删除功能
• ✅ 写入操作的 diff 预览
• ✅ TypeScript 类型安全

问：replace 和 smart_edit 有什么区别？

答：

• replace：你提供精确的 old_string 和 new_string。如果精确匹配失败（如格式问题），AI 纠错会提供帮助。
• smart_edit：你提供自然语言 instruction。AI 会判断要替换什么并生成两个字符串。

对于精确、可预测的编辑使用 replace。对于需要 AI 推理的复杂重构使用 smart_edit。

贡献

我们欢迎贡献！请查看 Gemini CLI 贡献指南。

开发

# 克隆仓库
git clone https://github.com/google-gemini/gemini-cli.git
cd gemini-cli/ai-file-tools

# 安装依赖
pnpm install

# 构建
pnpm run build

# 运行测试
pnpm test

# 类型检查
pnpm run typecheck

支持与问题

• 问题反馈：GitHub Issues
• npm 包：@kepoai/ai-file-tools
• 源代码：GitHub 仓库

状态

✅ 生产就绪 (v1.0.0)

| 功能 | 状态 | |------|------| | 文件操作 | ✅ 完成 | | 搜索与发现 | ✅ 完成 | | AI 纠错 | ✅ 完成 | | 文件过滤 (.gitignore/.geminiignore) | ✅ 完成 | | AI SDK v5 集成 | ✅ 完成 | | TypeScript 支持 | ✅ 完成 | | 文档 | ✅ 完成 |

路线图

已完成 ✅

• [x] 核心文件操作（8 个工具）
• [x] AI SDK v5 集成
• [x] OpenRouter 支持
• [x] AI 增强编辑纠错
• [x] 文件过滤（.gitignore/.geminiignore）
• [x] 搜索和发现工具
• [x] 集成测试套件（ai-correction、real-ai、e2e、proof 测试）

进行中 🚧

• [ ] 单元测试覆盖率（部分完成）

未来增强 🔮

• [ ] 性能基准测试
• [ ] 文件删除/重命名工具
• [ ] 直接 RipGrep 集成（可选）
• [ ] 大文件流式支持

许可证

Apache 2.0 - 从 Gemini CLI 提取并增强

版权所有 2025 Google LLC（原始 Gemini CLI 代码）
版权所有 2025 Kepo AI（增强和打包）

致谢

本包基于 Google Gemini CLI 团队的出色工作构建。我们提取并增强了核心文件操作工具，使其作为独立包提供给 AI agent 开发社区。

用 ❤️ 制作 by Kepo AI