文件操作是 WorkBuddy 最基础也最核心的能力。所有"动手"任务的第一步几乎都是读取文件，最后一步则是写入或修改文件。WorkBuddy 提供三个精准分工的工具：Read（读取）、Write（写入）、Edit（编辑），覆盖从查看到创建到修改的完整链路。

📖Read 工具详解

Read 工具用于读取文件内容，是 WorkBuddy 理解项目现状的"眼睛"。

支持格式

Read 工具支持 50+ 种文件格式，涵盖：

• 代码文件：.js .ts .py .java .go .rs .vue .jsx .tsx .c .cpp .rb .php .sh .ps1 等
• 标记/配置：.md .html .css .json .yaml .yml .toml .xml .ini .env
• 数据文件：.csv .tsv .sql
• 文档格式：.txt .log .diff .patch
• 二进制文件：.png .jpg .gif .svg .pdf（以元信息或 OCR 方式读取）

核心参数

Read({
  file_path: string,     // 必填，文件的绝对路径
  offset?: number,       // 可选，起始行号（1-indexed），默认 1
  limit?: number         // 可选，读取行数，默认全部
})

使用示例

# 读取整个文件
> 帮我读一下 /project/src/main.py

# 读取前 50 行
> 看一下 README.md 的前 50 行

# 读取指定范围（第 100-150 行）
> 读 config.yaml 的第 100 到 150 行

# 读取图片信息
> 看看这张图片 /assets/logo.png 是什么内容

返回格式

Read 返回的内容会以行号前缀格式展示，方便定位：

1: import os
2: import sys
3: 
4: def main():
5:     print("Hello, WorkBuddy!")
...

✍️Write 工具详解

Write 工具用于创建新文件或完整覆写文件。当你需要从零创建文件，或完全替换文件内容时使用。

核心参数

Write({
  file_path: string,     // 必填，目标文件的绝对路径
  content: string        // 必填，要写入的完整内容
})

行为特征

• 自动建目录：如果目标路径的父目录不存在，Write 会自动创建所有中间目录
• 完整覆写：如果文件已存在，Write 会完全替换原有内容（不是追加）
• 编码处理：默认 UTF-8，自动处理 BOM 和换行符

使用示例

# 创建新文件
> 在 /project/scripts/ 下创建一个 deploy.sh，内容是部署脚本

# 创建配置文件
> 帮我创建 docker-compose.yml，包含 nginx 和 redis 两个服务

# 创建多级目录下的文件
> 创建 /project/src/utils/helpers.py，写入常用工具函数

🔧Edit 工具详解

Edit 工具是 WorkBuddy 文件操作的精锐武器——它能在文件中精确替换指定内容，而不影响其他部分。这是日常最常用的文件操作工具。

核心参数

Edit({
  file_path: string,        // 必填，目标文件绝对路径
  old_string: string,       // 必填，要被替换的原文本（精确匹配）
  new_string: string,       // 必填，替换后的新文本
  replace_all?: boolean     // 可选，是否替换所有匹配项，默认 false
})

精确替换

Edit 的工作原理是字符串精确匹配：它在文件中查找 old_string 的精确出现位置，替换为 new_string。

# 修改配置项
> 把 config.json 里的 "port": 3000 改成 "port": 8080

# 修改函数实现
> 把 main.py 里 def hello() 函数的实现改成打印当前时间

# 修复拼写错误
> 把 README.md 里所有的 "Workbuddy" 改成 "WorkBuddy"

批量操作

当 replace_all 设为 true 时，Edit 会替换文件中所有匹配的 old_string：

# 全局替换变量名
> 把 app.js 里所有的 getUserData 改成 fetchUserProfile

# 批量修改缩进
> 把 style.css 里所有的 2空格缩进改成 4空格缩进

匹配规则

• 精确匹配：old_string 必须与文件中的内容完全一致（包括缩进、空格、换行）
• 唯一性检查：当 replace_all 为 false 时，如果 old_string 在文件中出现多次，Edit 会报错而非随机替换一个
• 上下文建议：为避免歧义，建议在 old_string 中包含足够的上下文行（surrounding lines）

⚖️三者对比

🔄典型工作流

文件操作的标准工作流是 Read → 分析 → Edit/Write：

# 工作流示例：修改 API 端口配置

Step 1: Read → 读取当前配置
  > 读一下 config/production.json

Step 2: 分析 → 确认修改位置
  （WorkBuddy 自动识别 "port": 3000 在第 12 行）

Step 3: Edit → 精确修改
  > 把 "port": 3000 改成 "port": 8080

Step 4: Read → 验证修改结果
  > 再读一下确认改对了

🎯最佳实践

1. 大文件分段读取

超过 500 行的文件，不要一次读完。先读前 50 行了解结构，再定向读取关键部分：

> 先读 README.md 的前 30 行，了解项目概述
> 再读 package.json，看依赖列表
> 最后读 src/index.ts 的入口逻辑

2. Edit 优于 Write

只要不是创建新文件，优先使用 Edit。Write 的覆写行为风险更高，容易丢失文件中的其他内容。

3. 修改前先备份

对重要配置文件的修改，建议先复制一份备份：

> 先把 nginx.conf 复制一份为 nginx.conf.bak，再修改

4. 批量修改用 replace_all

需要全局替换时，显式说明"所有的"或"全部"：

> 把 utils.js 里所有的 callback 改成 async/await 风格

5. 路径用绝对路径

WorkBuddy 的工作目录可能不是你预期的目录，始终使用绝对路径可以避免路径歧义：

# 好的做法
> 读 /home/project/src/main.py

# 不推荐
> 读 ./main.py

❓常见问题

Q1：Edit 报具报错"old_string not found"怎么办？

原因：old_string 与文件中的实际内容不匹配（可能缩进或空格不同）。解决：先用 Read 查看文件实际内容，复制精确文本作为 old_string。

Q2：Edit 报具报错"Found multiple matches"怎么办？

原因：old_string 在文件中出现多次，且 replace_all 为 false。解决：在 old_string 中加入更多上下文行使其唯一，或明确说明"替换所有的"。

Q3：Read 读取二进制文件会怎样？

图片文件会以 OCR 或元信息方式返回（尺寸、格式、OCR 文字）；PDF 会提取文字内容；其他二进制文件会提示"无法以文本方式读取"。

Q4：Write 创建文件时目录不存在怎么办？

Write 会自动创建所有不存在的中间目录，无需手动 mkdir。例如写入 /a/b/c/file.txt 时，/a/、/a/b/、/a/b/c/ 都会自动创建。

Q5：能否追加内容到文件末尾？

可以。用 Edit 工具，将 old_string 设为文件最后一行的内容，new_string 设为最后一行加上追加内容。或者直接告诉 WorkBuddy："在文件末尾追加以下内容"。