eve-agent-optimisation

Eve Agent 优化

目标：让 Agent 以最少的工具调用、最少的 token、最短的时间达成目标。找出它浪费精力的地方并消除浪费。

硬性规则：只给建议，不做更改

**未经用户事先同意，绝不更改执行框架、模型、推理力度或权限策略。**这些都是成本与能力方面的决策，应由项目负责人决定。进行诊断、说明权衡并提出建议，然后等待批准。

分析重点

分析 Agent 执行日志，找出：

1. 走错方向——Agent 尝试了行不通的方法，不得不回头。
2. 徒劳探索——Agent 花费 token 探索与目标无关的内容。
3. 不必要的工具调用——Agent 读取了不需要的文件、运行了没有提供有效信息的命令，或只做细微调整便重复调用。
4. 上下文缺失——Agent 通过反复试错才发现本应在 SKILL.md 或任务说明中明确的信息。
5. 工具不合适——Agent 使用了速度慢或不稳定的工具，而更快的原生替代方案明明存在（例如，在大模型可原生读取 PDF 时，却通过 shell 调用 pdftotext）。
6. 阅读过量——Agent 读取了大型文件的全文，而它实际只需查看其中一个章节；或者为了查找某项内容读取了许多文件，而定向搜索就能找到答案。
7. 输出冗长——任务只需要简洁结果，Agent 却长篇解释推理过程。
8. 重试循环——Agent 反复执行同一失败操作，寄希望于结果会有所不同。

诊断工作流

第 1 步：获取执行记录

eve job diagnose <job-id>          # Full timeline, routing, errors
eve job show <job-id> --verbose    # Phase, attempts, harness, agent
eve job receipt <job-id>           # Token usage + cost

关键指标：

• 输入 token——Agent 读取了多少内容。数值高 = 阅读过多。
• 输出 token——Agent 写了多少内容。数值高 = 输出冗长或推理过多。
• 尝试次数——大于 1 表示 Agent 崩溃或超时。
• 耗时——与专注工作的 Agent 应达到的耗时进行比较。

第 2 步：流式查看或重放日志

eve job follow <job-id>            # Real-time (if still active)
eve job logs <job-id>              # Historical

按顺序阅读日志。针对每次工具调用，思考：

• **这是否推进了目标？**如果没有，就是浪费。
• **这能否避免？**如果 SKILL.md 告诉了 Agent 去哪里查找，它是否就能跳过这一步？
• **工具是否合适？**换一种方法能否更快获取相同信息？
• **范围是否恰当？**Agent 是否读取了整个文件，而它实际只需要查看其中 10 行？

第 3 步：梳理关键路径

确定实现目标所需的最少工具调用：

1. 哪些文件实际发挥了作用？
2. 哪些命令实际产生了有用的输出？
3. 哪些决策第一次就做对了？

其余都是浪费。量化：关键路径上的工具调用占总调用次数的多少？有多少比例的 token 用在了有效工作上？

第 4 步：找出根本原因

针对每类浪费，追溯其根本原因：

浪费	根本原因	修复方法
Agent 查找了错误的文件	SKILL.md 没有说明该去哪里查找	在 SKILL.md 中添加具体文件路径或搜索模式
Agent 一开始就采用了错误的方法	SKILL.md 没有说明首选方法	添加明确指示：“做 X，不要做 Y”
Agent 读取了不需要的文件	作业描述过于模糊	缩小描述范围；明确指定具体范围
Agent 重试失败的命令	没有错误处理指南	在 SKILL.md 中添加故障处理指示
Agent 为文件类型使用了错误的工具	SKILL.md 没有提及原生功能	添加文件类型路由：“PDF：原生读取。图像：直接查看。”
Agent 读取了整个大型文件	没有针对性阅读的指引	添加指示：“只读取第 1-50 行”或“搜索 X”
Agent 的输出冗长	没有指定输出格式	指定确切格式：JSON 架构、附件名称、简洁摘要
Agent 缺少决策所需的上下文	缺少资源引用或环境变量	附加合适的资源；确保已配置 with_apis
Agent 重新发现已知事实	没有持久化记忆策略	使用组织文档、KV 存储或附件来保留知识
Agent 因资源配置而变慢	资源过多、克隆内容过大、不必要的工具链	精简资源引用，配置浅克隆，移除未使用的工具链

修复方法几乎总是 SKILL.md

SKILL.md 是最具优化价值的目标。精准的 SKILL.md 可以消除整类浪费的工具调用。

提高效率

1. 用一句话说明目标。 Agent 应在开始操作前确切了解要实现什么。

2. 指出具体文件和路径。 “检查身份验证配置”会浪费工具调用来搜索。“读取 src/config/auth.ts 的第 1-30 行”只需一次工具调用。

3. 明确说明方法。 “使用 Read 工具原生读取 PDF——不要调用命令行转换工具”，可以避免 Agent 尝试错误的路径。

4. 说明哪些事不要做。 如果存在常见的错误做法，就明确禁止。“不要读取整个测试套件；只读取失败的测试文件。”

5. 定义输出格式。 “创建一个名为 findings.json 的 JSON 附件，架构为 {issues: [{file, line, severity, message}]}。”这样就无需斟酌格式。

6. 告诉 Agent 它具备哪些上下文。 “.eve/resources/index.json 中的资源索引列出了所有附加文档及其 mime_type。先读取该文件，以确定处理策略。”

7. 针对不同分支提供决策树。 不要只说“根据不同文件类型采用适当处理方式”：

   Check mime_type in resource index:
   - application/pdf → read natively, use page ranges for >10 pages
   - text/* → read directly
   - image/* → view directly (multimodal)
   - other → describe and note for human review
   

8. 保持简短。 Agent 读取的每个词都会消耗输入 token。删掉赘词。多用表格和列表，少用散文。

测试 SKILL.md

重写后，再运行同一项任务并进行比较：

• 工具调用是否更少？
• token 是否更少？
• 完成速度是否更快？
• 是否首次尝试就得到正确结果？

eve job compare <old-job-id> <new-job-id>   # Compare receipts

SKILL.md 之外的优化项

如果仅更改 SKILL.md 还不够，可以考虑以下调整项（均需用户批准后才能更改）：

执行框架和模型

如果 Agent 一直表现为：

• 对任务来说太慢 → 建议使用更快的模型（例如，从 sonnet 切换到 haiku）。
• 能力不足 → 建议使用能力更强的模型（例如，从 sonnet 切换到 opus）。
• 消耗过多思考 token → 建议降低推理力度。
• 思考不足 → 建议提高推理力度。

说明其中的权衡（速度、成本和质量），由用户决定。

权限策略

如果 Agent 每次编辑文件都要等待批准而受阻：

• 对自动化批处理工作，建议使用 yolo。
• 对有人监督的编码工作，建议使用 auto_edit。
• 说明相关的安全影响。

资源引用

如果配置速度很慢：

• 移除 Agent 实际上不会使用的资源引用。
• 将可选上下文标记为 required: false。
• 传递 mime_type，这样 Agent 就不需要探测文件类型。

Git 控制

如果 Agent 在 Git 操作上浪费时间：

• commit: auto + push: on_success 可省去手动 Git 操作。
• create_branch: if_missing 可避免创建分支失败。
• ref_policy: auto 可尽量缩小克隆范围。

任务范围

如果 Agent 在一个任务中处理过多内容：

• 通过编排将工作拆分为目标明确的子任务。
• 每个子任务都采用狭窄的范围和专门的 SKILL.md。
• 简单的子任务使用成本更低的模型；仅在需要时使用能力更强的模型。

团队协作

如果子 Agent 重复劳动：

• 确保技能在启动时读取 .eve/coordination-inbox.md。
• 为顺序执行的步骤配置 depends_on。
• 使用附件（而非文字）在任务之间传递数据。

优化报告模板

分析 Agent 的执行情况后，按以下格式呈现发现：

## Agent Optimisation Report: <job-id>

**Goal:** <what the agent was trying to do>
**Result:** <succeeded/failed> in <duration> using <tokens> tokens (<cost>)

### Efficiency Score
- Total tool calls: N
- Productive tool calls: M (X%)
- Wasted tool calls: N-M (Y%)

### Waste Categories
1. <category>: N calls, ~X tokens wasted
   - Example: <specific wasteful action from logs>
   - Fix: <specific SKILL.md or config change>

### Recommended Changes
- [ ] SKILL.md: <specific edit> — eliminates <category> waste
- [ ] SKILL.md: <specific edit> — eliminates <category> waste
- [ ] (Requires approval) Model: <current> → <recommended> — <reason>
- [ ] (Requires approval) Reasoning: <current> → <recommended> — <reason>

### Expected Improvement
- Estimated tool calls: N → M
- Estimated tokens: X → Y
- Estimated time: A → B

快速参考：常见浪费模式

模式	日志中的信号	修复方法
查找文件	多次对不同文件调用 Read	在 SKILL.md 中注明目标文件
Grep 级联	使用不同模式进行多次搜索	提供合适的搜索词
反复试错	工具调用失败后，Agent 更换参数重试	记录正确做法
过度读取	对 5000 行以上的文件使用 Read 工具	指定行范围，或告知 Agent 先搜索
不必要的探索	Agent 读取 README、CHANGELOG 等	明确说明哪些内容不应读取
斟酌格式	助手花费较长时间轮次决定输出结构	在 SKILL.md 中指定输出格式
重复验证	Agent 重新检查已确认的内容	将 SKILL.md 组织成线性流程
未利用原生能力	LLM 可以直接处理，却调用 CLI 工具	明确说明原生能力
重新发现上下文	Agent 每次运行都重新了解项目结构	使用组织文档或 KV 存储保存持久上下文
审批阻塞	Agent 暂停等待许可	建议用户使用 yolo 或 auto_edit

相关技能

• eve-job-debugging — 用于监控和诊断任务的 CLI 命令。
• eve-orchestration — 将工作拆分为并行子任务。
• eve-agent-memory — 用于跨任务持久化的存储原语。
• eve-skill-distillation — 将学到的模式编码为可复用技能。
• eve-read-eve-docs — 平台参考文档（CLI、清单、任务、执行框架）。