调教AI Agent总差点意思？试试从工具设计下手——来自24万星仓库的避坑指南

你有没有这种感觉——调教 AI Agent 的时候，工具写了一堆，但模型就是不用、或者用了效果很差？

问题往往不在模型本身，而在于工具设计得太糙。

今天挖到一个来自 ECC 超大杯仓库的 Skill：Agent Harness Construction。ECC 整个仓库现在有 24 万星，是 GitHub上当之无愧的顶流 Agent 开发框架，而这个 Skill 是它旗下专门讲”怎么设计 Agent 工具集”的精华。

这个 Skill 在解决什么问题

一句话：让你的 AI Agent 少废话、多干活。

它把 Agent 输出质量拆成四层来看：

• Action Space（行动空间）——你的工具定义得合理不合理
• Observation Space（观测空间）——工具返回的结果格式清不清楚
• Recovery Quality（恢复质量）——出错了模型知不知道怎么救
• Context Budget（上下文预算）——你给模型的上下文值不值

大多数 Agent 调不好，都是第一层就埋了雷。

几个核心设计原则，说人话版

工具要”小而专”，不要”大而全”

比如不要写一个 do_everything_tool，把查天气、写文案、发邮件全塞进去。工具粒度越细，模型越知道什么时候该调用什么。ECC 建议高风险操作（部署、删库）用微工具，常见操作（读文件、搜索）用中工具，只有往返开销是主要成本时才用宏工具。

工具返回值必须有结构，不能只返回一个字符串

好的工具返回值要长这样：

{
  "status": "success",
  "summary": "文件已更新，共修改 3 处",
  "next_actions": ["运行测试", "提交 PR"],
  "artifacts": ["/path/to/file.md"]
}

有这个结构，模型才能真正”理解”结果、决定下一步。纯文本返回等于让模型瞎猜。

错误恢复要写清楚”怎么救”，不是只报个错

反面典型：{"error": "权限不足"}
正面典型：

{"error": "权限不足",
 "hint": "检查是否登录，token 是否过期",
 "retry": "用 --login 重新认证",
 "stop_condition": "连续失败3次则停止"}

模型看到后者才能真的自我修复，否则只会一直重试同一个错误。

适用场景

• 你在给 Claude Code / Cursor / Co-Agent 写自定义工具
• 你的 Agent 经常”工具用了但没做对”
• 你在设计一个新的多 Agent 系统，不知道怎么拆分工具
• 你在优化现有 Agent，想找系统性的方法而不是靠玄学调 prompt

怎么用

把这个 Skill 的提示词直接作为你开发 Agent 工具时的 checklist。它不长（不到 100 行），但每一条都是工程级的经验总结，对照着检查能少走很多弯路。

GitHub 链接也贴出来，感兴趣可以直接去看原始 SKILL.md：

Agent Harness Construction – GitHub

总体来说，这是一个偏底层、偏开发者的 Skill——不是给你一个能直接用的 Agent，而是教你怎么把 Agent 造得更结实。如果你正在做 Agent 开发或者选型，这个 Skill 值得在书签栏占一个位置。

GitHub: https://github.com/affaan-m/ECC/tree/main/skills/agent-harness-construction