npm package: @kepoai/ai-file-tools
Description: File operation tools for AI agents, extracted from Gemini CLI
Author: Kepo AI
Latest version: 1.2.1

# @kepoai/ai-file-tools

[![npm version](https://badge.fury.io/js/@kepoai%2Fai-file-tools.svg)](https://www.npmjs.com/package/@kepoai/ai-file-tools)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)

> **专业的 AI Agent 文件操作工具集** - 从 [Gemini CLI](https://github.com/google-gemini/gemini-cli) 提取并增强，具备 AI 增强功能。

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

[English](./README.md) | 简体中文

## 📖 文档

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

## 特性

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

## 安装

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

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

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

## 快速开始

```typescript
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`）
- 行号和上下文
- 性能限制（避免搜索大型二进制文件）

## 配置

```typescript
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 纠错文档](./AI_CORRECTION.md)**

## Electron 集成示例

```typescript
// 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;
});
```

## 高级用法

### 自定义工具配置

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

### 单独使用工具

```typescript
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：自动化代码重构

```typescript
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：批量修复文件

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

### 示例 3：生成新功能

```typescript
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 吗？

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

```typescript
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 贡献指南](https://github.com/google-gemini/gemini-cli/blob/main/CONTRIBUTING.md)。

### 开发

```bash
# 克隆仓库
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](https://github.com/google-gemini/gemini-cli/issues)
- **npm 包**：[@kepoai/ai-file-tools](https://www.npmjs.com/package/@kepoai/ai-file-tools)
- **源代码**：[GitHub 仓库](https://github.com/google-gemini/gemini-cli/tree/main/ai-file-tools)

---

## 状态

### ✅ 生产就绪 (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](https://github.com/google-gemini/gemini-cli) 提取并增强

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

---

## 致谢

本包基于 Google [Gemini CLI](https://github.com/google-gemini/gemini-cli) 团队的出色工作构建。我们提取并增强了核心文件操作工具，使其作为独立包提供给 AI agent 开发社区。

---

**用 ❤️ 制作 by [Kepo AI](https://github.com/kepoai)**