跳到主要内容

文件操作

📖 适合谁:开发者 / 运维 / 内容编辑 / 平台管理员 —— 想让 AI 在工作空间里直接读写、编辑、搜索、批量处理多种格式文件(纯文本、Office、PDF、图片)的人

📖 阅读时长:4 分钟

📖 一句话:YingClaw 一整套文件操作工具,覆盖读取/写入/编辑/搜索/批量处理,支持纯文本、Office、PDF、图片。工作空间内安全运行,提供大文件分块读取、精确字符串编辑、ripgrep 跨文件搜索、Office/PDF 结构化解析。对话中随时调用,无独立菜单,全员可访问。

一、核心价值​

价值说明
多格式覆盖一套工具搞定纯文本、Office、PDF、图片 — 不用为不同格式学不同命令
精确编辑字符串级别精确替换(file_edit),old_string 唯一匹配才会改,避免误伤
高效搜索ripgrep 内核的 content_search 跨文件正则搜索,千级文件秒级返回
批量处理glob_search + content_search 组合,轻松做"找一类文件 + 改一段内容"的批处理
大文件友好支持 limit / offset 分块读取、字节偏移、PDF 自动分页(200K 字符上限)

二、主要能力​

1. 多格式读取​

  • 纯文本:txt / md / json / yaml / xml / csv / log 等 — file_read 按行号展示
  • Office 文档:docx 段落级提取 · xlsx 单元格/Sheet 级访问 · pptx 幻灯片结构
  • PDF:pdf_read 纯文本提取(支持大文档分页,最多 200K 字符)
  • 图片:image_info 读尺寸/格式/大小,可选 base64 编码

2. 写入与覆盖​

  • file_write 创建或覆盖 文件,自动建父目录
  • 支持任意文本内容(代码、配置、Markdown、长文本)
  • 写入二进制需先 base64 编码(图片/PDF 等)

3. 精确编辑(字符串级)​

  • file_edit 通过 完全匹配 替换一段文本 — 唯一匹配才会执行
  • 适合改一处不改其他地方的场景(改函数名、修文档错别字、调配置参数)
  • 避免「全量重写」带来的格式丢失 / 误删风险

4. glob 文件搜索​

  • glob_search 按通配符找文件路径(如 **/*.md 找所有 markdown)
  • 支持 ** 跨目录、 *.ext 扩展名匹配、? 单字符
  • 返回按路径排序的文件列表,适合"先找文件再处理"

5. 内容搜索(ripgrep 内核)​

  • content_search 按正则表达式跨文件搜索内容
  • 千级文件秒级返回,自动跳过 .git / node_modules 等目录
  • 支持 case-sensitive 切换、文件类型过滤、上下文输出

6. 大文件分块读取​

  • file_read 支持 offset 起始行 + limit 最大行数
  • 大日志(GB 级)可分页读,避免一次性塞满上下文
  • pdf_read 同样支持 max_chars 限制(默认 50K,最大 200K)
  • 配合 content_search 定位后,再用 file_read 精读关键片段

7. PDF 提取与分析​

  • pdf_read 纯文本提取(光栅化扫描版 PDF 不支持文字提取)
  • 大文档自动按页读取,可指定 max_chars 控制单次返回
  • 适合:合同审查 / 论文摘要 / 报告分析 / 法规检索

8. 图片元数据​

  • image_info 读图片 格式、尺寸、大小,可选 base64 编码
  • 多模态模型可直接看图(理解图内容、提取图中文本)
  • 适合:截图解读 / OCR 替代 / 视觉问答 / 图像分类

三、典型应用场景​

场景 1:读 PDF 找答案 —「告诉我这份合同第三章讲了什么」​

# 1. 提取 PDF 文本
text = pdf_read("contract.pdf", max_chars=50000)
# 2. 配合搜索定位章节
result = content_search("第三章", include="*.pdf", path="contracts/")
# 3. 多模态模型可读图扫描版 PDF(图片型 PDF)

YingClaw 会自动定位章节位置、摘要关键内容、标注页码,3 步内出答案,无需自己翻 50 页。

场景 2:Excel 按部门拆分 —「把这份 Excel 按部门列拆成多个 sheet」​

# 1. 读取 Excel
import openpyxl
wb = openpyxl.load_workbook("employees.xlsx")
ws = wb.active
# 2. 按部门分组
groups = {}
for row in ws.iter_rows(min_row=2, values_only=True):
    dept = row[2]
    groups.setdefault(dept, []).append(row)
# 3. 每个部门一个 sheet
for dept, rows in groups.items():
    new_ws = wb.create_sheet(dept)
    for row in rows:
        new_ws.append(row)
wb.save("employees_by_dept.xlsx")

YingClaw 会自动完成读 → 分组 → 写 流程,输出每个 sheet 的行数 / 部门名列表,几秒搞定一份多 sheet 报表。

场景 3:跨文件搜索 —「搜索 workspace 里所有包含 TODO 的文件」​

# 内容搜索(ripgrep 内核)
content_search("TODO", path="src/", include="*.py", output_mode="files_with_matches")
# 输出:每个含 TODO 的文件路径 + 行号 + 上下文

支持正则 + 文件类型过滤,千级文件秒级返回,定位效率远超手翻。

场景 4:精确编辑 —「把这份 md 里所有的 oldName 改成 newName」​

# 1. 读全文
text = file_read("doc.md")
# 2. 全量替换
new_text = text.replace("oldName", "newName")
# 3. 覆盖写回
file_write("doc.md", new_text)

或用更安全的 file_edit 工具:每次只匹配一处,确认后再改,适合不确定替换范围的场景。

场景 5:图片元数据与解读 —「这张图多大?是什么格式?」​

# 读元数据
image_info("screenshot.png", include_base64=False)
# 输出:format=PNG, size=1920x1080, file_size=345KB
# 多模态理解(直接看图)
# 配 vision 模型:image_info + base64 → "这张图是产品首页截图,顶部导航栏有 5 个菜单..."

从基础元数据(尺寸/格式)到深度理解(图内容/OCR/视觉问答),一套工具全覆盖。

四、使用指南​

第 1 步:读取文件 — 简单文本用 file_read("path/to/file.md"),按行号展示;大文件加 limit=200 offset=100 分块读;PDF 用 pdf_read;Office 用对应库(系统会自动调用)。

第 2 步:编辑文件 — 精确改用 file_edit("path", old_string="原内容", new_string="新内容"),old_string 必须在文件里唯一;大改用 file_write 全量覆盖(慎用)。

第 3 步:搜索文件 — 按文件名找用 glob_search("**/*.py");按内容找用 content_search("TODO", include="*.py");支持正则、case-sensitive、上下文行数。

第 4 步:处理 PDF — pdf_read("doc.pdf", max_chars=100000) 抽文本,光栅化扫描版需先 OCR 或用多模态模型读图;大文档分段读,配合 content_search 找关键章节。

第 5 步:处理 Office — docx 按段落读 · xlsx 按 sheet/单元格读 · pptx 按幻灯片读;写入用 openpyxl / python-docx 等库(YingClaw 自动装)。

第 6 步:批量任务 — 复杂批处理(全公司文档改个抬头、几千个文件统一改名)用 shell-command + file-operations 组合,YingClaw 会自动用 todo 列表拆解,逐步执行并汇报进度。

五、最佳实践​

  • 大文件必分块 — 超过 1000 行 / 50KB 的文件用 limit + offset 分块读,避免一次性塞满上下文
  • 优先 file_edit 而非全量重写 — 改一处用 file_edit(精确、可回滚),改多处用 file_write 但要先读全文
  • file_edit 必须 old_string 唯一 — 不唯一就补上下文(前后几行)再匹配;否则会拒绝执行
  • 搜索优先用 content_search — ripgrep 内核比手翻快千倍,千级文件秒级返回
  • 跨格式统一接口 — 读 PDF / Word / Excel 都用自然语言描述需求,不用记具体 API,YingClaw 会自动选工具
  • 改前先读 — 编辑/覆盖任何文件前,先 file_read 看一遍现状,避免改错或覆盖已有内容
  • 删除前备份 — 重要文件删除/覆盖前先复制一份(cp file file.bak),出错了能恢复
  • 大文件不返回 base64 — 读图片默认只返回元数据;确实需要 base64 才显式加 include_base64=True,避免上下文雪崩
  • PDF 优先抽文本,扫描版再 OCR — 文字版 PDF 抽文本快准;扫描版需走多模态(成本高),按需选择
  • 批量操作前先 dry-run — find ... -delete / 全量重写前,先加 -print 或「找出所有要改的文件」打印,确认无误再真跑