Back to Details

eve-agent-optimisation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Eve Agent Optimisation

Eve Agent 优化

The goal: get the agent to its objective in the fewest tool calls, fewest tokens, shortest time. Find where it wastes effort and eliminate it.
目标：让Agent以最少的工具调用、最少的Token消耗、最短的时间达成任务目标。找出其无效消耗的环节并加以消除。

Hard Rule: Recommend, Don't Change

硬性规则：仅推荐，不修改

Never change the harness, model, reasoning effort, or permission policy without asking the user first. These are cost and capability decisions that belong to the project owner. Diagnose, explain the tradeoff, and recommend — then wait for approval.
**未经用户事先许可，绝不能修改工具框架、模型、推理强度或权限策略。**这些涉及成本与能力的决策属于项目所有者。你需要做的是诊断问题、解释权衡利弊并给出建议，然后等待用户批准。

What You're Looking For

排查方向

Analyse agent execution logs to identify:
  1. Wrong turns — agent tried an approach that couldn't work and had to backtrack.
  2. Blind alleys — agent spent tokens exploring something irrelevant to the goal.
  3. Unnecessary tool calls — agent read files it didn't need, ran commands that gave no useful information, or repeated calls with slight variations.
  4. Missing context — agent had to discover something through trial and error that should have been stated in the SKILL.md or job description.
  5. Wrong tool for the job — agent used a slow or fragile tool when a faster/native alternative exists (e.g., shelling out to 
    pdftotext
    when the LLM reads PDFs natively).
  6. Excessive reading — agent read entire large files when it only needed a section, or read many files looking for something that could have been found with a targeted search.
  7. Verbose output — agent explained its reasoning at length when the task only needed a concise result.
  8. Retry loops — agent repeated the same failing operation, hoping for a different result.
分析Agent执行日志，识别以下问题：
  1. 错误路径——Agent尝试了无法成功的方法，不得不回溯。
  2. 无用探索——Agent消耗Token探索与目标无关的内容。
  3. 不必要的工具调用——Agent读取了不需要的文件、执行了无法提供有用信息的命令，或重复调用仅存在细微差异的操作。
  4. 缺失上下文——Agent本应从SKILL.md或任务描述中获取的信息，却只能通过反复试错来发现。
  5. 工具误用——Agent使用了缓慢或不稳定的工具，而存在更快/原生的替代方案（例如：当LLM可原生读取PDF时，却调用
    pdftotext
    命令）。
  6. 过度读取——Agent读取了整个大文件，而实际上只需要其中一部分；或读取大量文件来查找本可通过定向搜索找到的内容。
  7. 冗余输出——任务仅需要简洁结果时，Agent却详细阐述其推理过程。
  8. 重试循环——Agent重复执行相同的失败操作，期望得到不同结果。

Diagnostic Workflow

诊断流程

Step 1: Get the Execution Record

步骤1：获取执行记录

bash
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
Key numbers:
  • Input tokens — how much the agent read. High = reading too much.
  • Output tokens — how much it wrote. High = verbose or excessive reasoning.
  • Attempt count — more than 1 means the agent crashed or timed out.
  • Duration — compare against what a focused agent should take.
bash
eve job diagnose <job-id>          # 完整时间线、路由、错误信息
eve job show <job-id> --verbose    # 阶段、尝试次数、工具框架、Agent信息
eve job receipt <job-id>           # Token使用量及成本
关键指标：
  • 输入Token——Agent读取的内容量。数值过高意味着读取过多。
  • 输出Token——Agent生成的内容量。数值过高意味着输出冗余或推理过度。
  • 尝试次数——超过1次意味着Agent崩溃或超时。
  • 耗时——与专注执行任务的Agent应耗时进行对比。

Step 2: Stream or Replay the Logs

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

bash
eve job follow <job-id>            # Real-time (if still active)
eve job logs <job-id>              # Historical
Read the log sequentially. For each tool call, ask:
  • Did this advance the goal? If not, it's waste.
  • Could this have been avoided? If the SKILL.md had told the agent where to look, would it have skipped this?
  • Was this the right tool? Could a different approach have gotten the same information faster?
  • Was the scope right? Did the agent read an entire file when it needed 10 lines?
bash
eve job follow <job-id>            # 实时查看（若任务仍在运行）
eve job logs <job-id>              # 查看历史日志
按顺序阅读日志。针对每个工具调用，思考：
  • **这是否推进了目标？**如果没有，就是无效消耗。
  • **这是否可以避免？**如果SKILL.md明确告知Agent查找位置，它是否会跳过此操作？
  • **这是否是正确的工具？**是否有其他方法能更快获取相同信息？
  • **范围是否合适？**Agent是否读取了整个文件，而实际上只需要10行内容？

Step 3: Map the Critical Path

步骤3：梳理关键路径

Identify the minimum set of tool calls needed to achieve the goal:
  1. What files actually mattered?
  2. What commands actually produced useful output?
  3. What decisions were correct on first attempt?
Everything else is waste. Quantify: how many tool calls were on the critical path vs total? What percentage of tokens were spent on productive work?
识别达成目标所需的最小工具调用集合：
  1. 哪些文件是真正重要的？
  2. 哪些命令真正产生了有用输出？
  3. 哪些决策是首次尝试就正确的？
其余所有操作都是无效消耗。量化统计：关键路径上的工具调用数占总调用数的比例是多少？有多少百分比的Token用于有效工作？

Step 4: Identify Root Causes

步骤4：识别根本原因

For each category of waste, trace back to the root cause:
WasteRoot CauseFix
Agent explored wrong filesSKILL.md doesn't say where to lookAdd specific file paths or search patterns to SKILL.md
Agent tried wrong approach firstSKILL.md doesn't state the preferred approachAdd explicit instructions: "Do X, not Y"
Agent read files it didn't needJob description too vagueNarrow the description; specify exact scope
Agent retried failing commandNo error handling guidanceAdd failure mode instructions to SKILL.md
Agent used wrong tool for file typeSKILL.md doesn't mention native capabilitiesAdd file-type routing: "PDFs: read natively. Images: view directly."
Agent read entire large fileNo guidance on targeted readingAdd instructions: "Read only lines 1-50" or "Search for X"
Agent verbose in outputNo output format specifiedSpecify exact format: JSON schema, attachment name, concise summary
Agent lacks context for decisionsMissing resource refs or env varsAttach the right resources; ensure 
with_apis
is configured
Agent re-discovers known factsNo persistent memory strategyUse org docs, KV store, or attachments to carry forward knowledge
Agent slow due to provisioningToo many resources, large clone, unnecessary toolchainsTrim resource refs, configure shallow clone, remove unused toolchains
针对每类无效消耗，追溯其根本原因：
无效操作类型根本原因修复方案
Agent探索错误文件SKILL.md未指定查找位置在SKILL.md中添加具体文件路径或搜索模式
Agent首先尝试了错误方法SKILL.md未指定推荐方法添加明确指令：“执行X，不要执行Y”
Agent读取了不需要的文件任务描述过于模糊缩小描述范围；明确指定精确任务边界
Agent重试失败命令缺乏错误处理指引在SKILL.md中添加故障模式处理说明
Agent针对文件类型使用了错误工具SKILL.md未提及原生能力添加文件类型路由规则：“PDF：原生读取。图片：直接查看。”
Agent读取了整个大文件缺乏定向读取指引添加指令：“仅读取第1-50行”或“搜索内容X”
Agent输出冗余未指定输出格式指定精确格式：JSON schema、附件名称、简洁摘要
Agent缺乏决策上下文缺失资源引用或环境变量附加正确资源；确保
with_apis
配置正确
Agent重复发现已知事实无持久化记忆策略使用组织文档、KV存储或附件来传递知识
Agent因资源配置缓慢资源过多、克隆体积大、工具链冗余精简资源引用，配置浅克隆，移除未使用的工具链

The Fix Is Almost Always the SKILL.md

修复方案几乎都在SKILL.md中

The SKILL.md is the highest-leverage optimisation target. A precise SKILL.md eliminates entire categories of wasted tool calls.
SKILL.md是优化效果最显著的目标文件。一份精准的SKILL.md可以消除整类无效工具调用。

Write for Efficiency

为效率而编写

  1. State the goal in one sentence. The agent should know exactly what it's trying to achieve before doing anything.
  2. Name specific files and paths. "Check the auth config" wastes tool calls searching. "Read 
    src/config/auth.ts
    lines 1-30" is one tool call.
  3. State the approach explicitly. "Use native PDF reading via the Read tool — do NOT shell out to conversion tools" prevents the agent from trying the wrong path.
  4. Specify what NOT to do. If there's a common wrong turn, block it. "Do not read the entire test suite; only read the failing test file."
  5. Define the output format. "Write a JSON attachment named 
    findings.json
    with schema 
    {issues: [{file, line, severity, message}]}
    ." This eliminates formatting deliberation.
  6. Tell the agent what context it has. "The resource index at 
    .eve/resources/index.json
    lists all attached documents with mime_type. Read it first to determine processing strategy."
  7. Provide decision trees for branches. Instead of "handle different file types appropriately":
    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. Keep it short. Every word the agent reads consumes input tokens. Cut filler. Use tables and lists over prose.
  1. 用一句话明确目标。Agent在执行任何操作前，应清楚知道自己要达成什么。
  2. 指定具体文件和路径。“检查认证配置”会导致Agent浪费工具调用进行搜索。“读取
    src/config/auth.ts
    第1-30行”只需一次工具调用。
  3. 明确指定方法。“通过Read工具使用原生PDF读取——不要调用转换工具”可防止Agent尝试错误路径。
  4. 说明禁止操作。如果存在常见的错误路径，直接阻止。“不要读取整个测试套件；仅读取失败的测试文件。”
  5. 定义输出格式。“编写名为
    findings.json
    的JSON附件，遵循schema 
    {issues: [{file, line, severity, message}]}
    。”这可消除格式决策的消耗。
  6. 告知Agent已有的上下文。“
    .eve/resources/index.json
    中的资源索引列出了所有附加文档的mime_type。先读取它来确定处理策略。”
  7. 为分支场景提供决策树。不要写“适当处理不同文件类型”，而是：
    查看资源索引中的mime_type：
- application/pdf → 原生读取，超过10页时使用页码范围
- text/* → 直接读取
- image/* → 直接查看（多模态）
- 其他 → 描述并标记供人工审核
  8. 保持简洁。Agent读取的每个词都会消耗输入Token。删除冗余内容。优先使用表格和列表而非散文。

Test the SKILL.md

测试SKILL.md

After rewriting, run the same job again and compare:
  • Fewer tool calls?
  • Fewer tokens?
  • Faster completion?
  • Correct result on first attempt?
bash
eve job compare <old-job-id> <new-job-id>   # Compare receipts
重写后，再次运行相同任务并对比：
  • 工具调用是否减少？
  • Token消耗是否减少？
  • 完成速度是否更快？
  • 是否首次尝试就得到正确结果？
bash
eve job compare <old-job-id> <new-job-id>   # 对比执行记录

Beyond the SKILL.md

超出SKILL.md的优化方向

When SKILL.md changes aren't sufficient, look at these levers (all require user approval to change):
当修改SKILL.md不足以解决问题时，可考虑以下调整（所有调整都需要用户批准）：

Harness and Model

工具框架与模型

If the agent is consistently:
  • Too slow for the task → recommend a faster model (e.g., sonnet → haiku).
  • Not capable enough → recommend a more capable model (e.g., sonnet → opus).
  • Using too many thinking tokens → recommend lower reasoning effort.
  • Not thinking enough → recommend higher reasoning effort.
Present the tradeoff (speed vs cost vs quality) and let the user decide.
如果Agent持续出现以下情况：
  • 速度过慢 → 推荐更快的模型（例如：sonnet → haiku）。
  • 能力不足 → 推荐更强大的模型（例如：sonnet → opus）。
  • 推理Token消耗过多 → 推荐降低推理强度。
  • 推理不足 → 推荐提高推理强度。
向用户说明权衡关系（速度vs成本vs质量），由用户决定。

Permission Policy

权限策略

If the agent is blocked waiting for approvals on every file edit:
  • Recommend 
    yolo
    for automated batch work.
  • Recommend 
    auto_edit
    for supervised coding.
  • Explain the security implications.
如果Agent每次文件编辑都因等待批准而被阻塞：
  • 为自动化批量任务推荐
    yolo
    模式。
  • 为监督式编码推荐
    auto_edit
    模式。
  • 解释安全影响。

Resource Refs

资源引用

If provisioning is slow:
  • Remove resource refs the agent doesn't actually use.
  • Mark optional context as 
    required: false
    .
  • Thread 
    mime_type
    so the agent doesn't need to probe file types.
如果资源配置缓慢：
  • 移除Agent实际未使用的资源引用。
  • 将可选上下文标记为
    required: false
    。
  • 传递
    mime_type
    ，避免Agent探测文件类型。

Git Controls

Git控制

If the agent wastes time on git operations:
  • commit: auto
    + 
    push: on_success
    eliminates manual git ceremony.
  • create_branch: if_missing
    avoids branch creation failures.
  • ref_policy: auto
    minimises clone scope.
如果Agent在Git操作上浪费时间：
  • commit: auto
    + 
    push: on_success
    可消除手动Git操作流程。
  • create_branch: if_missing
    可避免分支创建失败。
  • ref_policy: auto
    可最小化克隆范围。

Job Scope

任务范围

If the agent is doing too much in one job:
  • Split into focused children via orchestration.
  • Each child gets a narrow scope and specialised SKILL.md.
  • Cheaper models for simpler children; capable models only where needed.
如果Agent在一个任务中处理过多内容：
  • 通过编排将任务拆分为多个专注的子任务。
  • 每个子任务拥有狭窄的范围和专门的SKILL.md。
  • 简单子任务使用低成本模型；仅在需要时使用强大模型。

Team Coordination

团队协作

If child agents duplicate work:
  • Ensure skills read 
    .eve/coordination-inbox.md
    at startup.
  • Wire 
    depends_on
    for sequential steps.
  • Use attachments (not prose) for passing data between jobs.
如果子Agent重复工作：
  • 确保技能在启动时读取
    .eve/coordination-inbox.md
    。
  • 为顺序步骤配置
    depends_on
    。
  • 使用附件（而非散文）在任务间传递数据。

Optimisation Report Template

优化报告模板

After analysing an agent's execution, present findings in this format:
undefined
分析Agent执行后，按以下格式呈现结果：
undefined

Agent Optimisation Report: <job-id>

Agent优化报告: <job-id>

Goal: <what the agent was trying to do> Result: <succeeded/failed> in <duration> using <tokens> tokens (<cost>)
目标: <Agent要完成的任务> 结果: <成功/失败>，耗时<duration>，消耗<tokens> Token（成本<cost>）

Efficiency Score

效率评分

  • Total tool calls: N
  • Productive tool calls: M (X%)
  • Wasted tool calls: N-M (Y%)
  • 总工具调用数: N
  • 有效工具调用数: M (X%)
  • 无效工具调用数: 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>
  1. <分类>: N次调用，约X Token被浪费
    • 示例: <日志中的具体无效操作>
    • 修复方案: <具体的SKILL.md或配置修改建议>

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>
  • SKILL.md: <具体修改内容> — 消除<分类>无效消耗
  • SKILL.md: <具体修改内容> — 消除<分类>无效消耗
  • [ ]（需批准）模型: <当前模型> → <推荐模型> — <原因>
  • [ ]（需批准）推理强度: <当前设置> → <推荐设置> — <原因>

Expected Improvement

预期改进

  • Estimated tool calls: N → M
  • Estimated tokens: X → Y
  • Estimated time: A → B
undefined
  • 预估工具调用数: N → M
  • 预估Token消耗: X → Y
  • 预估耗时: A → B
undefined

Quick Reference: Common Waste Patterns

快速参考：常见无效消耗模式

PatternSignal in LogsFix
File huntingMultiple 
Read
calls to different files		Name the target file in SKILL.md
Grep cascadeMultiple searches with different patternsProvide the right search term
Trial and errorTool call fails, agent retries with variationDocument the correct approach
Over-readingRead tool on 5000+ line fileSpecify line ranges or tell agent to search first
Unnecessary explorationAgent reads README, CHANGELOG, etc.Explicitly say what NOT to read
Format deliberationLong assistant turns deciding output structureSpecify output format in SKILL.md
Redundant validationAgent re-checks things it already confirmedStructure the SKILL.md as a linear flow
Native capability missShell out to CLI tool when LLM can process directlyState native capabilities explicitly
Context re-discoveryAgent re-learns project structure every runUse org docs or KV store for persistent context
Approval blockingAgent pauses waiting for permissionRecommend 
yolo
or 
auto_edit
to user
模式日志信号修复方案
文件搜索多次对不同文件调用
Read
在SKILL.md中指定目标文件
多次Grep搜索使用不同模式多次搜索提供正确的搜索关键词
反复试错工具调用失败，Agent尝试变体操作记录正确方法
过度读取对5000+行文件调用Read工具指定行范围或告知Agent先搜索
不必要探索Agent读取README、CHANGELOG等明确说明禁止读取的内容
格式决策Agent花费大量时间决定输出结构在SKILL.md中指定输出格式
重复验证Agent重复检查已确认的内容将SKILL.md设计为线性流程
未使用原生能力调用CLI工具，而LLM可直接处理明确说明原生能力
上下文重发现Agent每次运行都重新学习项目结构使用组织文档或KV存储实现持久化上下文
权限阻塞Agent因等待权限而暂停向用户推荐
yolo
或
auto_edit
模式

Related Skills

相关技能

  • eve-job-debugging
    — CLI commands for monitoring and diagnosing jobs.
  • eve-orchestration
    — decomposing work into parallel children.
  • eve-agent-memory
    — storage primitives for persistence across jobs.
  • eve-skill-distillation
    — encoding learned patterns into reusable skills.
  • eve-read-eve-docs
    — platform reference docs (CLI, manifest, jobs, harnesses).
  • eve-job-debugging
    — 用于监控和诊断任务的CLI命令。
  • eve-orchestration
    — 将工作分解为并行子任务。
  • eve-agent-memory
    — 跨任务持久化存储原语。
  • eve-skill-distillation
    — 将学习到的模式编码为可复用技能。
  • eve-read-eve-docs
    — 平台参考文档（CLI、清单、任务、工具框架）。