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

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

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

bash 复制代码

cat config.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输出中解析内容，出错概率更低。

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

bash 复制代码

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

或者更具体：

bash 复制代码

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

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

1.2 search_files：智能搜索

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

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

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

bash 复制代码

# 搜索代码中所有使用timeout的地方
search_files target=content pattern="timeout" path="~/projects/myapp"

# 按文件类型搜索
search_files target=content pattern="func.*Handler" file_glob="*.go"

# 只看统计
search_files target=content pattern="TODO" path="." output_mode=count

实际场景：

bash 复制代码

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

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

1.3 patch：安全编辑

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

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

bash 复制代码

把 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]

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

bash 复制代码

不用问我确认，直接改

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

1.4 安全机制

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

操作	风险	Agent处理	你的检查点
读文件	低	直接读	确认没读敏感文件
写文件	中	显示diff，确认后写入	仔细看diff
删文件	高	需要确认	确认文件名正确
批量修改	高	逐个展示diff	抽查几个结果
执行命令	中	自动风险评估	确认命令无害

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

1.5 /undo 拯救手滑

改错了？没事：

bash 复制代码

/undo

恢复到修改前的状态。

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

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

2.1 批量重命名

bash 复制代码

把 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 批量查找替换

这是最常用的场景之一：

bash 复制代码

把所有 Go 文件中的 log.Println 替换为 slog.Info

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

预览模式很重要：

bash 复制代码

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

确认没问题再说：

bash 复制代码

确认无误，执行修改

2.3 批量格式化

bash 复制代码

格式化 src/ 下所有 Go 文件

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

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

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

3.1 快速了解项目结构

bash 复制代码

cd ~/projects/legacy-system
hermes

bash 复制代码

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

3.2 Hermes做项目分析的过程

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

你得到的结果：

复制代码

📋 项目分析报告
─────────────────────────────────────

项目名称：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 理解关键业务流程

bash 复制代码

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

3.4 找Bug线索

bash 复制代码

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

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

4.1 为什么需要知识库

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

复制代码

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

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

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

4.2 开启知识库功能

bash 复制代码

hermes skill enable memory

# 查看知识库状态
hermes memory status

4.3 让Hermes自动学习

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

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

bash 复制代码

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

以后处理这个项目时自动应用

4.4 手动管理知识库

bash 复制代码

# 查看存储的知识
hermes memory list

# 搜索知识
hermes memory search "项目编码规范"

# 删除过时的知识
hermes memory delete <id>

# 导出知识库
hermes memory export > knowledge_backup.json

4.5 实战：构建团队知识库

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

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

bash 复制代码

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

bash 复制代码

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

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

bash 复制代码

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

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

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

5.1 场景设定

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

5.2 传统做法

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

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

5.3 Hermes做法

bash 复制代码

cd ~/projects/legacy-payment-system
hermes

bash 复制代码

我刚刚接手这个项目，完全不了解。帮我做完整分析：
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 使用正则做复杂搜索

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

bash 复制代码

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

6.2 跨文件重构

bash 复制代码

方法重命名：把 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 生产环境文件的特殊处理

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

bash 复制代码

# ❌ 危险：直接让 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制作备份：

bash 复制代码

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

6.4 .env和密钥文件的保护

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

bash 复制代码

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

总结

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

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

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