一、 简介

@smai-kit/file-utils 是一个文件工具包，提供文件读取、写入、编辑、代码搜索、文件查找和命令执行能力，目前包含以下工具：

| 工具 | 名称 | 说明 | 详细文档 | |------|------|------|----------| | Grep | Grep | 基于 ripgrep 的代码搜索工具，支持正则表达式、多种输出模式、上下文行、分页、文件类型过滤等 | docs/grep.md | | Read | Read | 文件读取工具，支持文本、图片（jpeg/jpg/png/gif/webp）、PDF、Jupyter Notebook，支持分段读取、token 估算与限制、文件去重等 | docs/read.md | | Glob | Glob | 基于 ripgrep 的文件名模式匹配工具，支持 glob 语法、按修改时间排序、结果截断、隐藏文件与 gitignore 控制等 | docs/glob.md | | Write | Write | 文件写入工具，支持全量写入、父目录自动创建、staleness 检测、编码保持、原子写入、差异补丁生成等 | docs/write.md | | Edit | Edit | 文件编辑工具，支持精确字符串替换、批量替换、引号归一化、编码与行尾符保持、staleness 检测、原子写入等 | docs/edit.md | | Bash | Bash | Shell 命令执行工具，支持超时控制、后台任务管理、安全验证、权限规则匹配、路径验证、破坏性命令警告等 | docs/bash.md |

二、 安装

1. 从 npm 安装

npm install @smai-kit/file-utils

2. 本地安装（不发布到 npm）

在消费项目的 package.json 中添加：

{
  "dependencies": {
    "@smai-kit/file-utils": "file:../file-utils"
  }
}

然后执行 npm install。

三、 本地调试

以下三种方式均无需将包发布到 npm，适合开发调试场景。

1. file 协议安装

以安装 npm 包的形式将本地包安装到消费项目中，安装后与正式 npm 包体验完全一致。

# 1. 构建 file-utils
cd file-utils
npm install
npm run build

# 2. 在消费项目中安装本地包
cd your-project
npm install ../file-utils

安装后，包会出现在 node_modules/@smai-kit/file-utils/ 目录下。

修改 file-utils 源码后，重新构建并安装即可更新：

cd file-utils
npm run build

cd ../your-project
npm install ../file-utils

2. npm link

通过全局符号链接实现实时调试，修改源码并重新构建后，消费项目立即生效，无需重复安装。

# 1. 在 file-utils 目录创建全局链接
cd file-utils
npm link

# 2. 在消费项目目录链接全局包
cd ../your-project
npm link @smai-kit/file-utils

修改源码后只需重新构建，消费项目自动生效：

cd file-utils
npm run build

取消链接：

cd your-project
npm unlink @smai-kit/file-utils

cd ../file-utils
npm unlink

3. npm pack 离线安装

将本地包打包为 .tgz 文件后安装，适合在无网络环境或需要固定版本的场景下使用。

# 1. 构建 file-utils
cd file-utils
npm run build

# 2. 打包为 tgz
npm pack
# 生成 smai-kit-file-utils-1.0.0.tgz

# 3. 在消费项目中安装 tgz
cd ../your-project
npm install ../file-utils/smai-kit-file-utils-1.0.0.tgz

4. 三种方式对比

| 特性 | file 协议 | npm link | npm pack | |------|-----------|----------|----------| | 安装形式 | 完整包复制到 node_modules | 符号链接 | tgz 文件安装 | | 源码修改后 | 需重新 npm install | 仅需 npm run build | 需重新打包并安装 | | 实时性 | 每次需重装 | 实时生效 | 每次需重打包 | | 适合场景 | 稳定引用 | 开发调试 | 离线/版本固定 |

四、 快速开始

1. Grep 代码搜索

import { grep } from '@smai-kit/file-utils';

// 搜索包含 "function" 的文件
const result = await grep({
  pattern: 'function\\s+\\w+',
  path: './src',
});

console.log(result.filenames); // 输出匹配文件列表

2. Read 文件读取

import { read } from '@smai-kit/file-utils';

// 读取文本文件
const result = await read({
  file_path: './src/index.ts',
});

console.log(result.file.content); // 输出带行号的文件内容

3. Glob 文件查找

import { glob } from '@smai-kit/file-utils';

// 查找所有 TypeScript 文件
const result = await glob({
  pattern: '**/*.ts',
  path: './src',
});

console.log(result.filenames); // 输出匹配文件列表

4. Write 文件写入

import { write, read } from '@smai-kit/file-utils';

// 创建新文件（父目录不存在时自动创建）
const result = await write({
  file_path: '/path/to/new-file.txt',
  content: 'This is a new file.\nSecond line.\n',
});

console.log(result.type); // "create"

// 更新已有文件前必须先调用 read()
await read({ file_path: '/path/to/existing.txt' });
const updateResult = await write({
  file_path: '/path/to/existing.txt',
  content: 'New content.\n',
});
console.log(updateResult.type); // "update"

5. Edit 文件编辑

import { read, edit } from '@smai-kit/file-utils';

// 编辑前必须先读取文件
await read({ file_path: '/path/to/file.txt' });

// 精确字符串替换
const result = await edit({
  file_path: '/path/to/file.txt',
  old_string: 'Hello, World!',
  new_string: 'Hello, TypeScript!',
});

console.log(result.structuredPatch); // 差异补丁

// 批量替换
await read({ file_path: '/path/to/file.txt' });
await edit({
  file_path: '/path/to/file.txt',
  old_string: 'foo',
  new_string: 'bar',
  replace_all: true,
});

6. Bash 命令执行

import { bash } from '@smai-kit/file-utils';

// 执行命令
const result = await bash({ command: 'echo "hello world"' });
console.log(result.stdout); // hello world

// 工作目录在多次调用间持久化
await bash({ command: 'cd /tmp' });
const pwd = await bash({ command: 'pwd' });
console.log(pwd.stdout); // /tmp

// 后台执行
import { waitForBackgroundTask } from '@smai-kit/file-utils';
const bgResult = await bash({
  command: 'sleep 2 && echo done',
  run_in_background: true,
});
if (bgResult.backgroundTaskId) {
  const final = await waitForBackgroundTask(bgResult.backgroundTaskId);
  console.log(final?.stdout); // done
}

更多用法请参考 docs/grep.md、docs/read.md、docs/glob.md、docs/write.md、docs/edit.md 和 docs/bash.md，完整示例位于 examples/ 目录。

五、 npm 脚本

| 脚本 | 说明 | |------|------| | npm run build | 编译 TypeScript 源码到 out/ 目录 | | npm run build:examples | 编译示例代码 | | npm run clean | 清理 out/ 构建产物 | | npm run start | 运行 out/index.js | | npm run format:check | 检查 src/ 目录代码格式 | | npm run format:fix | 格式化 src/ 目录代码 | | npm run pack:dry-run | 模拟 npm pack，查看打包文件列表 | | npm run pack:tgz | 生成 .tgz 打包产物 | | npm run pack:list | 列出 .tgz 包内容 | | npm run test:read | 运行 Read 工具测试 | | npm run test:write | 运行 Write 工具测试 | | npm run test:glob | 运行 Glob 工具测试 | | npm run test:edit | 运行 Edit 工具测试 | | npm run test:bash | 运行 Bash 工具测试 | | npm run test:all | 运行全部测试 |

六、 环境要求

• Node.js >= 16（推荐 18+）
• 支持平台：Linux、macOS、Windows
• Grep 工具：通过 @vscode/ripgrep 自动下载 ripgrep 二进制文件，无需手动安装
• Glob 工具：通过 @vscode/ripgrep 自动下载 ripgrep 二进制文件，无需手动安装
• Read 工具（可选依赖）：
  • 图片处理：sharp 库（安装时自动编译原生依赖）
  • PDF 页面提取：poppler-utils（pdftoppm 和 pdfinfo 命令）
    • macOS：brew install poppler
    • Debian/Ubuntu：apt-get install poppler-utils
• Bash 工具：需要 shell 环境（bash 或 zsh）

本文档由 markdowncli 技能辅助生成