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

六文件与搜索 - 信息处理的正确姿势一、别再cat/grep了Agent原生工具才是正解如果你是后端开发者一定对这几条命令刻在骨子里catconfig.yaml# 看文件内容grep-rtimeout.# 全局搜索sed-is/foo/bar/g.# 替换这些命令很好用但在Hermes Agent里有更好的方式。不是说terminal工具集不能用——而是Agent原生的file工具集更聪明、更精准。1.1 read_file精确读取先看对比。如果用terminal去读文件Agent思维过程我要读main.py → 构造cat main.py命令 → 执行 → 读输出 → 处理 问题输出可能被截断、格式混乱、污染上下文如果用file工具集的read_fileAgent调用read_file(main.py, offset50, limit100) 直接返回结构化的文件内容精确控制读取范围看起来只是换了个方式但实际体验差别很大。文件工具集有行号索引、分页读取、智能截断。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_filestargetcontentpatterntimeoutpath~/projects/myapp# 按文件类型搜索search_filestargetcontentpatternfunc.*Handlerfile_glob*.go# 只看统计search_filestargetcontentpatternTODOpath.output_modecount实际场景在这个项目中搜索所有返回 error 的函数定义Hermes会调用search_files返回带行号的匹配结果还能进一步钻取到具体文件。1.3 patch安全编辑sed -i直接改文件改错了就没了。patch工具的工作方式是Agent先理解你的需求找到要修改的位置展示diff给你确认确认后再写入把 config/default.yaml 中的 timeout:30改成 timeout:60Hermes会展示即将修改文件: 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做文件修改前有几个安全屏障操作风险Agent处理你的检查点读文件低直接读确认没读敏感文件写文件中显示diff确认后写入仔细看diff删文件高需要确认确认文件名正确批量修改高逐个展示diff抽查几个结果执行命令中自动风险评估确认命令无害黄金法则重要文件修改前让Hermes展示diff。不要相信「直接改」的便利性。1.5 /undo 拯救手滑改错了没事/undo恢复到修改前的状态。二、批量文件处理重命名/查找替换/格式化单个文件操作没什么批量处理才是Agent真正的威力所在。2.1 批量重命名把 src/ 下所有 .js 文件重命名为 .ts 文件 把 images/ 下的 screenshot-*.png 按日期重命名 把测试文件从 *_test.go 统一改为 *_spec.goHermes会先列出受影响的文件列表确认后再执行以下 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 文件中hrefhttp://改成hrefhttps://只展示会修改的文件列表和统计数先不改预览模式很重要在 preview 模式下把 src/ 下所有 .html 文件中hrefhttp://改成hrefhttps://只展示会修改的文件列表和统计数先不改确认没问题再说确认无误执行修改2.3 批量格式化格式化 src/ 下所有 Go 文件 格式化项目中的所有 Python 文件按 PEP8 标准三、大项目代码阅读让Hermes帮你理解陌生代码库这是Agent最有价值的场景之一接手一个旧项目。3.1 快速了解项目结构cd~/projects/legacy-system hermes这个项目我完全不了解。帮我做一次快速分析1. 项目整体架构是什么MVCDDD分层2. 主要技术栈3. 核心业务模块和关系4. 数据库表结构5. API 有哪些6. 关键设计模式 输出到 docs/project-analysis.md3.2 Hermes做项目分析的过程读取README.md、package.json、go.mod、requirements.txt等入口文件遍历项目目录结构读取关键文件main.py、路由注册、数据库模型分析核心代码逻辑综合输出分析报告你得到的结果 项目分析报告 ───────────────────────────────────── 项目名称legacy-system 技术栈 - 后端Python 3.9 Flask - 数据库PostgreSQL 13 Redis - 消息队列RabbitMQ - 部署Docker K8s 架构模式三层架构 Controllerapi/→ Serviceservices/→ Modelmodels/ 核心模块 1. 用户模块 (app/user/) — 注册、登录、权限 2. 订单模块 (app/order/) — 创建、支付、退款 3. 支付模块 (app/payment/) — 三方支付对接 4. 通知模块 (app/notification/) — 邮件、短信 数据库共 23 张表 - users1.2万条 - orders45万条— 增长最快 - payments32万条 ... 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 status4.3 让Hermes自动学习日常使用中不需要手动告诉它「这个要记住」。Hermes会自动判断哪些信息值得保存。但有一些信息你希望它必须记住记住这个项目的编码规范1. Go 代码用 error group 处理并发错误2. 日志用结构化日志logrus3. 所有 API 返回统一的 JSON 格式4. 数据库迁移用 golang-migrate 以后处理这个项目时自动应用4.4 手动管理知识库# 查看存储的知识hermes memory list# 搜索知识hermes memory search项目编码规范# 删除过时的知识hermes memory deleteid# 导出知识库hermes memoryexportknowledge_backup.json4.5 实战构建团队知识库场景团队有20个微服务每个服务有不同的部署方式、配置规则、排错方法。做法每次排查完一个服务的问题让Hermes保存排错步骤。把这次排查保存为知识payment-service 的 RabbitMQ 连接断开问题 诊断步骤1. 检查 connection 状态rabbitmqctl list_connections2. 检查 channel 数是否超限rabbitmqctl list_channels|wc-l3. 重启顺序停 consumer → 清队列 → 重启 RabbitMQ → 启 consumer记住 payment-service 的部署配置 - Docker registryregistry.internal.com/payment-service - 环境变量文件/etc/payment-service/env - 健康检查/healthz - 日志路径/var/log/payment-service/ - 启动命令docker-compose-fdocker-compose.prod.yml up-d下次新人接手直接问Hermespayment-service 怎么部署遇到连接断开怎么排查不用翻文档、不用问同事。知识库就是你的「第二大脑」。五、实操接手一个旧项目5分钟理清架构5.1 场景设定你刚入职一家公司被丢到一个运行了3年的旧项目面前。没有文档、没有交接、代码10万行。5.2 传统做法打开IDE看目录结构10min打开入口文件看路由10min打开数据库模型看表结构10min打开几个关键服务看逻辑30min整理笔记20min还有很多细节搞不懂…总耗时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帮你做对的事情。