> 项目背景：从吴恩达 aisuite 仓库里孵化拆分出的 OpenWorker 项目，同时又是 aisuite 最大的下游应用程序。如果你想搭自己的 agent 框架而不是用它的桌面应用，应该去看 aisuite。
>
> 分析对象：`openworker-main/coworker/tools/search.py`（184 行）+ `coworker/tools/files.py`（113 行）
> 定位：agent 的"眼睛"——两个只读工具：`grep`（搜索定位）与 `read_file`（带行号读取）
> 读者：agent 开发学习者
> 姊妹篇：《Agent之Tools模块分析｜shell.py复盘.md》（agent 的"手"）；本文是"眼"

---

## 一、只读工具的需求，不止『能读文件就行』

agent 干活的第一步永远是**看**：看代码、看配置、看数据。内置工具库（aisuite）本来就有 read_file / search_files，但 OpenWorker 偏要自己重写这两个工具——为什么？站在设计师角度，给 LLM 用的"眼睛"至少要满足以下需求：

- **R1 读取文件内容**：模型能读到工作区内的文本文件。
- **R2 大文件不炸**：几万行的文件不能一读就报错或塞爆上下文，要能分段读、能续读。
- **R3 位置可引用**：返回内容要带行号，模型才能说出"`foo.py:42` 有问题"这种话。
- **R4 快速定位**：先搜索找到相关位置再细读，而不是把文件一个个盲读一遍。
- **R5 跳过噪音目录**：`node_modules`、`.git`、`dist` 这类目录永远不该出现在结果里。
- **R6 输出大小可控**：超长行、超多条目都要有上限，且截断不丢关键信息。
- **R7 工作区边界**：模型传入 `../../etc/passwd` 这类路径必须被拦下。
- **R8 出错可感知**：文件不存在、路径越界、正则写错，都要以结构化错误返回，喂回模型自我纠正。
- **R9 环境差异兜底**：有没有装 ripgrep 都要能用，且行为一致。
- **R10 只读免审批**：读操作零副作用，不该打扰用户，且应能被引擎并发执行。

两个文件对每条需求的实现位置（这张表也是全文的导览）：

| 需求 | 解法 | 位置 |
|---|---|---|
| R1 读取内容 | `read_file`：打开文件逐行读 | files.py L76-86 |
| R2 大文件窗口化 | `start_line`/`max_lines` 分页；返回值带 `note` 教模型续读 | files.py L58-64、L96-100 |
| R3 行号引用 | 每行格式化为 `cat -n` 风格 `"   12\ttext"` | files.py L84 |
| R4 快速定位 | `grep` 工具：正则搜索返回 file:line:text | search.py L73-115 |
| R5 跳过噪音 | ripgrep 尊重 .gitignore；两条路径都再叠一份硬编码 `_IGNORE_DIRS` | search.py L19-33、L104-105、L164 |
| R6 输出可控 | 单行截 500 字符；匹配条数默认 100、硬顶 1000；匹配行截 300 字符 | files.py L17、L82-83；search.py L79-80、L147 |
| R7 边界防护 | `resolve()` 后 `relative_to(root)` 校验，越界返回 error | files.py L65-69；search.py L81-85 |
| R8 错误可感知 | 一律 `{"error": ...}` 返回，不抛异常 | files.py L69/71/86；search.py L85/110/112/161 |
| R9 双引擎兜底 | `shutil.which("rg")` 探测：有 rg 走子进程，没有走纯 Python walk | search.py L87-115 |
| R10 只读免审批 | `risk_level="low", requires_approval=False` | files.py L105-111；search.py L119-125 |

---

## 二、术语约定

- **workspace（工作区）**：agent 被允许触碰的目录范围。两个工具都把传入路径解析后校验"必须在工作区内"——这是文件类工具的边界，越界即拒绝。
- **ripgrep（rg）**：Rust 写的高性能搜索工具，默认尊重 `.gitignore`。本模块的首选引擎。
- **窗口化读取（windowed read）**：大文件不一次读完，而是按 `start_line + max_lines` 读一个"窗口"，下次从断点继续——类似分页。
- **只读工具（read-only tool）**：不改变任何文件状态的工具。权限体系里归为最低风险级，免审批；引擎对这类工具还会**并发执行**（见 6.1）。

---

## 三、源码总览

两个文件结构完全一致，都是"一个 schema + 一个工厂函数"的极简形态：

```
files.py (113 行)                     search.py (184 行)
├─ _SCHEMA            (L19-47)        ├─ _IGNORE_DIRS      (L19-33)   硬编码排除目录
├─ file_tools(ws)     (L50-113)       ├─ _SCHEMA           (L35-67)
│   └─ read_file 闭包                 ├─ search_tools(ws)  (L70-127)
└─ return [read_file]                 │   └─ grep 闭包（双引擎分发）
                                      ├─ _parse_rg()       (L137-152) 解析 rg 输出
                                      ├─ _py_grep()        (L155-184) 纯 Python 兜底引擎
                                      └─ return [grep]
```

**两个文件各只做一件事：包装出一个 LLM 可调用的只读 tool**——`files.py` 导出 `[read_file]`，`search.py` 导出 `[grep]`。包装方式与 shell.py 同一套拳：闭包绑定 workspace → 手工挂 `__aisuite_tool_metadata__` 和 `__coworker_schema__` → 列表返回，由 `catalog.py` 组装、`build_engine()` 注册。

还有一个关键背景写在 `catalog.py:56-66`：这两个自研工具是**替代品**——组装 Code agent 的工具时，aisuite 自带的 `search_files`、`read_file`、`read_file_lines` 会被从列表里剔除，换上这两个自研版本。为什么替换，files.py 的文件头注释（L1-6）写得很直白：

> aisuite 的 `read_file` 返回原始文本（模型想引用 `path:line` 得自己数行），大文件直接抛异常（模型只能报错然后瞎猜）。这个版本返回 `cat -n` 风格的带行号文本，大文件改为窗口化，还会告诉模型怎么继续读。

——**替代的理由不是原版有 bug，而是原版不是为 LLM 的使用方式设计的**。这句话是理解这两个文件的钥匙。

---

## 四、代码分析

### 4.1 `read_file`（files.py L50-113）—— 一行为模型着想的读取器

执行流程：参数钳制（L58-64）→ 路径解析 + 工作区校验（L65-69）→ 逐行读取并格式化（L76-86）→ 组装结果 + 续读提示（L88-101）。

四个为 LLM 而生的细节：

1. **行号格式化**（L84）：`f"{i:>6}\t{text}"`——右对齐 6 位行号 + tab。模型看到 `"   42\tdef foo():"`，之后就能精确说出 `foo.py:42`，编辑工具也能按行定位。这是 R3 的全部实现，只有一行代码。
2. **单行截断**（L82-83）：超过 500 字符的行截断并标注 `"… (line truncated)"`——minified JS、base64 数据行不会污染上下文（R6）。
3. **窗口化 + 续读教学**（L96-100）：没读完时在结果里加一个 `note` 字段：

   ```
   "showing lines 1-2000 of 5430; call again with start_line=2001 to continue"
   ```

   这和 shell.py 后台任务返回的 `note` 是同一个手法——**返回值里直接写下一步该怎么调**，模型读到就知道续读，不需要预训练知识去猜。
4. **错误即数据**（L69/71/86）：路径越界、不是文件、读取失败，全部返回 `{"error": ...}`——模型把错误当工具输出读到，换个路径再试，而不是整个回合炸掉（R8）。

### 4.2 `grep`（search.py L70-127）—— 一函数双引擎

`grep` 闭包的本体是**引擎分发**（L87-115）：

```
shutil.which("rg") 探测
  ├─ 有 ripgrep → 组命令行 → 子进程跑 → _parse_rg 解析    (L88-113)
  └─ 没有     → _py_grep 纯 Python 遍历                    (L115)
```

**ripgrep 路径**（L88-113）：

- 命令行参数逐个有讲究：`--line-number`（要行号，R3）、`--no-heading` + `--color=never`（输出机器可解析）、`--max-count`（数量上限，R6）、`-e`（显式标记 pattern，防止以 `-` 开头的正则被当成选项——注入防护的小细节）。
- **排除规则放最后**（L101-105）：ripgrep 遇到冲突的 glob 规则时"后来者赢"，所以硬编码的 `!**/node_modules/**` 等排除 glob 追加在参数末尾，确保即使用户的 `.gitignore` 没配，噪音目录也必被跳过（R5）。这段逻辑有三行注释解释"为什么顺序重要"——顺序本身就是正确性。
- **退出码白名单**（L111-112）：rg 的 0=有匹配、1=无匹配都算正常；只有其他退出码才算错误。对比 shell.py"exit code 原样交模型解读"——这里更进了一步：**把工具特定的退出码语义翻译掉**，模型不用知道 rg 的规矩。
- 30 秒超时（L108）：搜索也不能卡死回合（shell.py R5 精神的延续）。

**Python 兜底路径**（`_py_grep`，L155-184）：`os.walk` 遍历，`dirs[:] = ...` 原地过滤噪音目录（L164，这是 `os.walk` 剪枝的标准用法），逐文件逐行正则匹配，凑够 n 条提前返回。正则写错时返回 `{"error": "invalid regex: ..."}`（L160-161）——模型的正则错误被翻译成可读的修正提示。

**结果解析**（`_parse_rg`，L137-152）：把 `file:line:text` 按冒号最多切 3 段（路径里可能有冒号），文本截 300 字符。

两个引擎返回**完全相同的形状**，外加一个 `engine` 字段（L113/115）标明这次用的是 `"ripgrep"` 还是 `"python"`——对模型无意义，对调试和日志有意义：可观测性藏在一个字段里。

---

## 五、Schema 数据结构分析

### 5.1 两份手写 schema

两个 schema（files.py L19-47；search.py L35-67）都是手写 OpenAI function 格式，与 shell.py 同一惯例。看 description 的教学性：

- `read_file`：`"returning numbered lines ('   12\ttext') so code can be referenced as path:line. Large files are windowed: pass start_line to continue..."`——把 R2/R3 的行为承诺直接写进描述，模型一看就知道有行号、大文件要传 `start_line`。
- `grep`：`"Prefer this over reading files blindly to locate code."`——这句不是描述功能，是**指导行为**：告诉模型"找代码先 grep 再读文件"，把 R4 的最佳实践写进了工具描述。

参数设计上，`grep` 的四个参数（pattern / path / glob / max_results）只有 `pattern` 必填，其余都有保守默认——**必填项最少化**：模型用最简单的方式就能调用成功，精细控制留给需要时。

### 5.2 元数据：只读工具的"特权身份证明"

```python
# 两个工具完全相同的三行（files.py L105-111；search.py L119-125）
risk_level="low"
capabilities=["read"] / ["search"]
requires_approval=False
```

这三行的意义远超字面（对应 R10）：

1. **免审批**：读操作零副作用，interactive 模式下也不打扰用户；
2. **可并发**：引擎的调度规则是"低风险且免审批的调用用 `asyncio.gather` 并发执行"（engine.py `_handle_tool_calls`）——模型一次返回 3 个 grep + 2 个 read_file，会**同时**跑。agent 的探索阶段因此快数倍；
3. **对比**：shell.py 的 `run_shell` 是 `high + requires_approval=True`，一次只能串行一个。眼睛的特权正是手的限制换来的。

### 5.3 返回值结构

```python
# read_file → 窗口 + 内容 + 续读提示
{"path", "start_line", "end_line", "total_lines", "content", "note"?}

# grep → 引擎标识 + 结构化匹配列表
{"engine": "ripgrep"|"python", "count": N,
 "matches": [{"file", "line", "text"}, ...]}
```

注意两者都返回**结构化 dict 而非纯文本**：`total_lines` 让模型判断"还要读几次"，`matches` 的 file/line 字段让模型可以直接把结果拼成 `path:line` 引用喂给下一个工具——**工具之间的接力靠结构化字段，不靠模型解析文本**。

---

## 六、设计思想总结

### 6.1 只读是特权，也是杠杆

这两个工具是全系统调用频率最高的工具（agent 干任何事都要先看），它们的设计回报也最大：免审批（不打扰用户）+ 可并发（探索快）+ 输出结构化（接力准）。反过来想 shell.py：写操作必须审批、串行、限超时。**风险分级不是安全摆设，它直接决定了用户体验的流畅度**——`risk_level="low"` 三个词，换来的是 agent 探索阶段的丝滑。

### 6.2 为 LLM 的使用方式重写，而不是将就能用的

aisuite 原版的读取/搜索"对人够用"，但 OpenWorker 选择替换（catalog.py:60 的剔除名单），替换理由全部指向模型：要能引用行号、大文件不能炸、要知道怎么续读、结果要结构化可接力。**给 LLM 设计工具和给人设计 API 是两件事**——人能从错误里恢复、会自己翻页、认得命令行输出格式；模型需要把这些"常识"写进返回值和描述里。这两个文件是"面向 LLM 的接口设计"最干净的样本（比 shell.py 更纯粹，因为没有进程管理的噪音）。

### 6.3 优雅降级：功能不因环境缺斤短两

ripgrep 在就用它的速度和 .gitignore 智能，不在就退回纯 Python——**同一个 schema、同一个返回形状、同一份噪音目录黑名单**（L104-105 注释专门解释为什么 rg 路径也要叠加硬编码排除：不能只依赖工作区的 .gitignore）。降级降的是性能，不是行为。`engine` 字段把"这次走了哪条路"暴露出来，排查问题时不用猜。

### 6.4 小文件的纪律性

297 行，两个工具，却一处不漏地做到了：路径越界防护、参数钳制（max_results 硬顶 1000）、输出双重截断（行 500 / 匹配 300 字符）、子进程 30s 超时、正则错误翻译、`-e` 防选项注入。**工具越小，越要把边界情况全部钉死**——因为调用它的是会犯一切错误的模型。这些防护任何一处缺失，都会变成线上某个回合的诡异失败。

### 6.5 眼睛与手的分工，回答了一个架构问题

读这两个文件时会意识到：搜索和读取完全可以用 `run_shell`（`grep -r`、`cat`）实现，为什么还要专门工具？答案在权限和输出两层：shell 是 EXEC 级高危操作，每次都要审批——如果看文件也要审批，agent 就没法用了；而且 shell 输出是无结构文本，模型还要解析。专用只读工具 = **精确的权限分类 + 结构化的输出 + 零注入面**。这也呼应了《shell.py复盘》的结论：一个强通用工具 + 少量高频专用工具，是性价比最高的配比。

### 一句话总结

**这两个文件的本质 = "把'看'这件事从 shell 里解放出来"：用不到 300 行代码做出两个只读、免审批、可并发、输出结构化的工具，它们示范了面向 LLM 设计工具接口的全部要点——行号可引用、窗口可续读、错误可自纠、行为写进描述。**


项目背景：从吴恩达 aisuite 仓库里孵化拆分出的 OpenWorker 项目，同时又是 aisuite 最大的下游应用程序。如果你想搭自己的 agent 框架而不是用它的桌面应用，应该去看 aisuite。

Agent之Tools模块分析｜OpenWorker search.py与files.py复盘

编程语言

OpenWorker项目重写read_file和grep工具，专为LLM设计，支持行号引用、大文件分页读取、结构化错误处理，并实现双引擎搜索（ripgrep/Python）。这些只读工具免审批、可并发，优化了AI代理的代码阅读体验。

数据结构

代码解释

Python

Agent

2026上云采购 | AI焕新·智启新局

tcap

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Agent之Tools模块分析｜OpenWorker search.py与files.py复盘-腾讯云开发者社区-腾讯云

Agent之Tools模块分析｜OpenWorker search.py与files.py复盘

Agent之Tools模块分析｜OpenWorker search.py与files.py复盘

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐