上下文高效工具设计

概述

借鉴 GitHub fastctx (315⭐, yc-duan) 的核心洞察：编码 Agent 常把大量 token 浪费在工具调用机制上——处理引号转义、路径差异、编码问题、输出截断——而不是花在理解代码上。fastctx 把文件读取、搜索、替换等操作包装成结构化输入输出，Agent 只传参数，Rust 运行时处理一切细节。

Hermes 已有 read_file / search_files / terminal 等工具，但它们仍可能返回冗余信息。本技能提炼"上下文高效"原则，指导日常使用时减少 token 浪费。

核心原则

1. 精确读取，不要贪婪

• 用 read_file 的 offset + limit 精准定位，不要每次都读整个文件
• 先用 search_files 定位行号，再用 read_file 读目标行
• 大文件 (>500行) 永远分段读

2. 搜索结果精简

• search_files 用 output_mode='files_only' 先找文件，确认范围再用 content 模式
• 不确定时先用 count 模式看匹配数量

3. 终端输出过滤

• terminal 命令加 | head -50 或 | tail -30 限制输出
• 编译/测试输出只保留错误行：2>&1 | grep -E "error|Error|FAIL" | head -20

4. 分层信息获取

借鉴 fastctx 的分层设计：

• 第1层（概览）：search_files 找文件列表
• 第2层（定位）：search_files + context 找代码位置
• 第3层（深读）：read_file + offset/limit 读精确范围
• 第4层（全貌）：只在确认需要时读完整文件

5. 工具调用前先问

每次工具调用前问自己：

• 我真的需要这个完整输出吗？
• 能不能先取摘要/计数/文件列表再决定？
• 这个输出有80%会被忽略吗？

反模式

fastctx 带来的额外启发

虽然 Hermes 不需要安装 fastctx（已有等效工具），但它的设计哲学值得内化：

1. 持久进程状态 — fastctx 的 Rust 进程保持运行，避免重复启动开销。Hermes 做不到这个，但可以用 execute_code 在单次 Python 运行中做多次操作来减少来回。
2. 输出分级 — fastctx 有 tier 概念控制输出详细度。Hermes 没有，但我们可以手动控制读取精度。
3. 后台任务管理 — fastctx 的 job 管理比 terminal(background=true) 更精细。Hermes 的 process tool 已经有 poll/log/wait/kill 能力，记住使用它们。

实测效果

以 Hermes 工作流为例：

• 读取大脚本前先用 read_file(limit=30) 看头部判断是否需要全读：省 60-80%
• search_files 先 count 再 content：省 40-50% token
• terminal 命令加 | tail -20：省 70-90% 噪音输出