（六）文件与搜索 - 信息处理的正确姿势

（六）文件与搜索 - 信息处理的正确姿势

一、别再cat/grep了：Agent原生工具才是正解

如果你是后端开发者，一定对这几条命令刻在骨子里：

catconfig.yaml# 看文件内容grep-r"timeout".# 全局搜索sed-i's/foo/bar/g'.# 替换

这些命令很好用，但在Hermes Agent里，有更好的方式。不是说terminal工具集不能用——而是Agent原生的file工具集更聪明、更精准。

1.1 read_file：精确读取

先看对比。如果用terminal去读文件：

Agent思维过程：我要读main.py → 构造"cat main.py"命令 → 执行 → 读输出 → 处理 问题：输出可能被截断、格式混乱、污染上下文

如果用file工具集的read_file：

Agent调用：read_file("main.py", offset=50, limit=100) 直接返回：结构化的文件内容，精确控制读取范围

看起来只是换了个方式，但实际体验差别很大。文件工具集有行号索引、分页读取、智能截断。Agent不需要在大段terminal输出中解析内容，出错概率更低。

用法很简单，直接给指令：

读取 src/main.go 的第50到100行

或者更具体：

找到 config.go 中 DatabaseConfig 结构体的定义

Hermes会自动调用read_file找到对应位置。

1.2 search_files：智能搜索

grep找东西经常遇到几个痛点：

• 搜索结果太多，淹没在无关匹配里
• 递归目录时忽略的.gitignore文件还要手动加–exclude
• 跨文件搜索后要逐一点开看

search_files工具解决了这些问题。它基于ripgrep，但封装得更智能：

# 搜索代码中所有使用timeout的地方search_filestarget=contentpattern="timeout"path="~/projects/myapp"# 按文件类型搜索search_filestarget=contentpattern="func.*Handler"file_glob="*.go"# 只看统计search_filestarget=contentpattern="TODO"path="."output_mode=count

实际场景：

在这个项目中搜索所有返回 error 的函数定义

Hermes会调用search_files，返回带行号的匹配结果，还能进一步钻取到具体文件。

1.3 patch：安全编辑

sed -i直接改文件，改错了就没了。patch工具的工作方式是：

1. Agent先理解你的需求
2. 找到要修改的位置
3. 展示diff给你确认
4. 确认后再写入

把 config/default.yaml 中的 timeout:30改成 timeout:60

Hermes会展示：

即将修改文件: src/config/default.yaml --- a/src/config/default.yaml +++ b/src/config/default.yaml @@ -10,7 +10,7 @@ database: host: localhost port: 5432 - timeout: 30 + timeout: 60 max_connections: 10 确认执行？[Y/n]

你确认后才写入。如果不想被询问：

不用问我确认，直接改

但建议大项目第一次修改时，先看diff再放行。

1.4 安全机制

Hermes做文件修改前有几个安全屏障：

黄金法则：重要文件修改前，让Hermes展示diff。不要相信「直接改」的便利性。

1.5 /undo 拯救手滑

改错了？没事：

/undo

恢复到修改前的状态。

二、批量文件处理：重命名/查找替换/格式化

单个文件操作没什么，批量处理才是Agent真正的威力所在。

2.1 批量重命名

把 src/ 下所有 .js 文件重命名为 .ts 文件 把 images/ 下的 screenshot-*.png 按日期重命名 把测试文件从 *_test.go 统一改为 *_spec.go

Hermes会先列出受影响的文件列表，确认后再执行：

以下 12 个文件将被重命名： src/utils.js → src/utils.ts src/parser.js → src/parser.ts src/validator.js → src/validator.ts ... 确认执行？[Y/n]

2.2 批量查找替换

这是最常用的场景之一：

把所有 Go 文件中的 log.Println 替换为 slog.Info 把 src/ 下所有 .html 文件中href="http://"改成href="https://"只展示会修改的文件列表和统计数，先不改

预览模式很重要：

在 preview 模式下，把 src/ 下所有 .html 文件中href="http://"改成href="https://"只展示会修改的文件列表和统计数，先不改

确认没问题再说：

确认无误，执行修改

2.3 批量格式化

格式化 src/ 下所有 Go 文件 格式化项目中的所有 Python 文件，按 PEP8 标准

三、大项目代码阅读：让Hermes帮你理解陌生代码库

这是Agent最有价值的场景之一：接手一个旧项目。

3.1 快速了解项目结构

cd~/projects/legacy-system hermes

这个项目我完全不了解。帮我做一次快速分析：1. 项目整体架构是什么（MVC？DDD？分层？）2. 主要技术栈3. 核心业务模块和关系4. 数据库表结构5. API 有哪些6. 关键设计模式 输出到 docs/project-analysis.md

3.2 Hermes做项目分析的过程

1. 读取README.md、package.json、go.mod、requirements.txt等入口文件
2. 遍历项目目录结构
3. 读取关键文件：main.py、路由注册、数据库模型
4. 分析核心代码逻辑
5. 综合输出分析报告

你得到的结果：

📋 项目分析报告 ───────────────────────────────────── 项目名称：legacy-system 技术栈： - 后端：Python 3.9 + Flask - 数据库：PostgreSQL 13 + Redis - 消息队列：RabbitMQ - 部署：Docker + K8s 架构模式：三层架构 Controller（api/）→ Service（services/）→ Model（models/） 核心模块： 1. 用户模块 (app/user/) — 注册、登录、权限 2. 订单模块 (app/order/) — 创建、支付、退款 3. 支付模块 (app/payment/) — 三方支付对接 4. 通知模块 (app/notification/) — 邮件、短信 数据库（共 23 张表）： - users（1.2万条） - orders（45万条）— 增长最快 - payments（32万条） ... API 清单（共 47 个接口）： - GET /api/v1/users — 获取用户列表 - POST /api/v1/users — 创建用户 ... 已知问题： - 订单模块缺少单元测试 - 支付模块有 TODO 未完成

3.3 理解关键业务流程

帮我梳理"退款"这个业务流程的完整链路： 从用户点击退款到钱到账，整个流程涉及哪些文件、函数、表 以数据流图的方式输出

3.4 找Bug线索

系统最近出现订单状态不一致的问题（订单显示已支付，但实际未扣款） 帮我查看：1. orders 表的状态流转逻辑2. 支付回调的处理流程3. 有没有并发写的问题4. 事务覆盖是否完整 给出排查方向

四、知识库初体验：从混乱到有序

4.1 为什么需要知识库

作为后端开发者，你的知识分散在：

- 本地：代码注释、README、Wiki、笔记 - 线上：Confluence、Notion、飞书文档 - 大脑：经验、踩过的坑、团队约定 - 对话历史：和 Hermes 的聊天记录

每次遇到问题你需要：回忆 → 搜索 → 翻笔记 → 问同事。

知识库的作用：把Hermes在对话中产生的知识持久化，以后遇到类似问题可以直接参考。

4.2 开启知识库功能

hermes skillenablememory# 查看知识库状态hermes memory status

4.3 让Hermes自动学习

日常使用中，不需要手动告诉它「这个要记住」。Hermes会自动判断哪些信息值得保存。

但有一些信息你希望它必须记住：

记住这个项目的编码规范：1. Go 代码用 error group 处理并发错误2. 日志用结构化日志（logrus）3. 所有 API 返回统一的 JSON 格式4. 数据库迁移用 golang-migrate 以后处理这个项目时自动应用

4.4 手动管理知识库

# 查看存储的知识hermes memory list# 搜索知识hermes memory search"项目编码规范"# 删除过时的知识hermes memory delete<id># 导出知识库hermes memoryexport>knowledge_backup.json

4.5 实战：构建团队知识库

场景：团队有20个微服务，每个服务有不同的部署方式、配置规则、排错方法。

做法：每次排查完一个服务的问题，让Hermes保存排错步骤。

把这次排查保存为知识：payment-service 的 RabbitMQ 连接断开问题 诊断步骤：1. 检查 connection 状态：rabbitmqctl list_connections2. 检查 channel 数是否超限：rabbitmqctl list_channels|wc-l3. 重启顺序：停 consumer → 清队列 → 重启 RabbitMQ → 启 consumer

记住 payment-service 的部署配置： - Docker registry：registry.internal.com/payment-service - 环境变量文件：/etc/payment-service/env - 健康检查：/healthz - 日志路径：/var/log/payment-service/ - 启动命令：docker-compose-fdocker-compose.prod.yml up-d

下次新人接手，直接问Hermes：

payment-service 怎么部署？遇到连接断开怎么排查？

不用翻文档、不用问同事。知识库就是你的「第二大脑」。

五、实操：接手一个旧项目，5分钟理清架构

5.1 场景设定

你刚入职一家公司，被丢到一个运行了3年的旧项目面前。没有文档、没有交接、代码10万行。

5.2 传统做法

1. 打开IDE，看目录结构（10min）
2. 打开入口文件，看路由（10min）
3. 打开数据库模型，看表结构（10min）
4. 打开几个关键服务，看逻辑（30min）
5. 整理笔记（20min）
6. 还有很多细节搞不懂…

总耗时：1-2天，还是一知半解。

5.3 Hermes做法

cd~/projects/legacy-payment-system hermes

我刚刚接手这个项目，完全不了解。帮我做完整分析：1. 项目全貌（架构、技术栈、模块划分）2. 核心业务流程（从请求进来，到返回响应）3. 数据库设计（主要表和关系）4. 依赖和第三方服务5. 部署方式6. 潜在问题（测试覆盖、技术债务）7. 作为新人的「快速上手路线图」 输出一份完整的 docs/onboarding-guide.md 同时保存到我的知识库

5.4 Hermes执行实录

🤖 开始分析项目... [1/5] 读取项目配置... → go.mod: Go 1.21, 主要依赖 gin, gorm, redis, kafka → Dockerfile: 多阶段构建 → docker-compose.yml: 含 PostgreSQL, Redis, Kafka [2/5] 分析目录结构... ├── cmd/ — 入口 ├── internal/ │ ├── api/ — HTTP handler │ ├── service/ — 业务逻辑 │ ├── repository/ — 数据访问 │ ├── model/ — 数据模型 │ ├── middleware/ — 中间件 │ └── config/ — 配置 ├── pkg/ — 公共库 │ ├── logger/ │ ├── kafka/ │ └── redis/ └── migrations/ — 数据库迁移 → 架构风格：整洁架构（Clean Architecture） → 依赖方向：api → service → repository [3/5] 分析模型和数据库... → 共 15 张表，核心：users, merchants, transactions, refunds → 主键全部用 UUID → 有软删除字段 deleted_at → 事务表有分库键 merchant_id [4/5] 分析核心流程... [5/5] 输出分析报告...

5.5 你得到的结果

📘 新手上手指南 ───────────────────────────────────── 第一步：本地开发 1. cp .env.example .env，配置数据库连接 2. make dev-db 启动依赖服务 3. make run 启动项目 4. 访问 http://localhost:8080/swagger 查看 API 第二步：理解核心流程 建议从 API 层开始读： internal/api/handler/payment.go → 支付接口入口 internal/service/payment.go → 支付业务逻辑 internal/repository/payment.go → 数据访问 第三步：关键注意事项 - 事务表按 merchant_id 分库，查询时必须带上 merchant_id - Kafka 消息顺序依赖 partition key - 退款操作有分布式锁，不要手动改数据库 - 生产环境不允许直接连数据库 第四步：排错常用方法 - 日志：kibana.internal.com (app-payment-*) - 监控：grafana.internal.com (payment-service) - 慢查询：在 DBA 平台查看

全过程：4分32秒。

六、高阶技巧

6.1 使用正则做复杂搜索

虽然用自然语言就能搜索，但如果你懂正则，可以更精准：

在这个目录下搜索符合以下正则的所有文件： pattern: func[A-Z]\w+\(.*error 目标：找出所有返回 error 的导出函数

6.2 跨文件重构

方法重命名：把service层的 GetUserByID 重命名为 FetchUserByID 影响这个方法的文件：1. internal/service/user.go — 定义2. internal/api/handler/user.go — 调用3. internal/repository/user.go — 实现4. tests/service/user_test.go — 测试 把4个文件一起更新，确保引用名称统一

6.3 生产环境文件的特殊处理

操作生产环境配置文件时要格外小心：

# ❌ 危险：直接让 Agent 改生产配置文件帮我把生产环境的 nginx.conf 的 worker_connections 改成2048# ✅ 安全：先查看，再备份，再修改1. 先读取 /etc/nginx/nginx.conf 给我看2. 备份到 /etc/nginx/nginx.conf.bak.$(date+%Y%m%d)3. 然后修改 worker_connections

建议在操作生产文件前，先让Hermes制作备份：

在修改任何生产文件前，先创建备份，备份名加日期后缀

6.4 .env和密钥文件的保护

Hermes默认不会读取.env、*.pem、id_rsa等敏感文件。但如果你明确要求，它还是会读。建议在开启新会话时先声明约束：

在这个会话中，不要读取 .env、secret*.yaml、*credentials* 类文件 除非我明确指定文件名

总结

文件操作是后端的日常，而Hermes的file工具集把这部分效率提升了一个量级。核心要点：

• 用read_file代替cat：精确分页读取，带行号
• 用search_files代替grep：智能搜索，按文件类型过滤
• 用patch代替sed：安全编辑，先看diff再写入
• 批量操作先预览再执行，生产文件先备份再修改
• 知识库是你的第二大脑，让每次排查经验都能复用

文件处理的正确姿势，不是更快地cat/grep，而是让Agent帮你做对的事情。