Harness Engineering工具设计让AI Agent发现并正确使用你的工具CLI vs MCP完整对比【免费下载链接】harness-engineering Ryan Lopopolo’s anthology, field guide, and agent context bundle for harness engineering项目地址: https://gitcode.com/gh_mirrors/har/harness-engineeringHarness Engineering马具工程是一种通过塑造 AI Agent 周围环境来提升其产出的工程实践它的两个外部杠杆是上下文与工具。本文结合开源项目 Harness Engineering 中的工具可读性论述完整对比CLI与MCPModel Context Protocol模型上下文协议两种工具载体给出面向初学者的 AI Agent 工具设计指南如何让 Agent 在需要的那一刻发现你的工具、正确调用、解读结果并在失败后自我修复。为什么 AI Agent 找不到你的工具很多团队给开发者写了漂亮的 CLI却在接入 AI 编码 Agent如 Claude Code、Codex后发现Agent 根本不知道这个工具存在。项目原文一针见血地指出见 sources/raw/hyperbola/tool-discovery.mdxCoding agents like Claude Code and OpenAI Codex dont struggle with terminals; they struggleto discovertools that exist.AI Agent 不缺终端能力缺的是发现工具的能力。一个能力capability要真正可用必须走完这样一个闭环发现 Discover → 选择 Select → 调用 Invoke → 解读 Interpret → 验证 Verify ↘ 修复 Repair ↗每一个环节都在消耗模型的注意力token也都在为下一次决策提供上下文。这套发现—调用—验证循环的完整论述见 docs/tool-legibility/README.md。CLI vs MCP 完整对比一张表看懂 项目的核心观点是熟悉度familiarity与可发现性discovery是两条独立的轴。一个 POSIX 命令可以拥有极强的模型习得先验模型训练时见过无数次但在 Agent 不知道它已安装之前它依然是隐形的反过来MCP 可以立刻向模型广播工具清单但模型仍要学习每个新工具的调用方式和返回结构。对比维度CLI命令行接口MCP模型上下文协议发现机制依赖模型训练数据中的既有先验$PATH中的命令对 Agent 是环境音不广播内建机器可读目录名称、描述、输入 Schema、示例调用自动提示模型熟悉度极高——POSIX/shell 语义已被模型深度习得较低——每次新调用和结果形状都需学习组合能力Unix 管道、man 页天然支持组合与查阅靠 LLM 本身做组合MCP 负责可发现性上下文成本低除非主动暴露目录本身消耗 token但换取首次即对典型适用模型已熟悉的通用操作git、ls、grep 等领域专属能力、私有系统、需要权限收窄的操作一句话总结来自 tool-discovery 原文MCP 是给模型的 tokens——Unix 管道和 man 页曾同时为人类提供组合能力与发现能力而在 Agent 系统中LLM 提供组合能力MCP 提供可发现性与操作暗示affordances。工具目录五要素让 Agent 一次看明白 对于动态的、模型不熟悉的能力Harness Engineering 提倡提供一份紧凑的、模型可见的目录至少包含五要素有意义的名字能暗示用途而非内部代号用途说明何时该用、何时不该用输入形状参数结构结果形状返回什么好让 Agent 预判如何解读第一个有用调用可直接照抄的示例命令同时用渐进式披露progressive disclosure控制成本紧凑地广播是什么、为什么只有在被选中之后才加载详细的 Schema、示例或手册。结果设计把每一次输出都当作上下文 Agent 判断发生了什么、下一步做什么完全依赖你的成功输出、错误、日志与修复提示。项目总结的可用工具行为清单安静的成功quiet success——通过时少说废话有界且稳定的结构——当结果会被机械解析时失败时说明被违反的不变量和受影响的目标存在时给出已知的恢复动作为被省略的细节提供检索路径而不是直接丢一大坨全量日志对高影响操作提供检查/dry-run 模式提供后置条件查询或副作用回执一个反面案例值得新手警惕Agent 预先把cargo test这种昂贵命令通过head/tail截断来节省上下文结果管道中断、退出码丢失、早期证据被丢弃——这就是上下文不安全的命令签名。正确的做法是让工具完整跑一次、保留真实状态与全量输出只返回下一步决策所需的有界结果完整论述见 docs/tool-legibility/README.md 的Design every result as context一节。选 CLI 还是选 MCP四条判断准则 ✅不要教条。项目的决策框架是当熟悉命令能干净地关掉任务时保留它只有当新界面满足以下任一条件时才引入它增加领域能力让原本不可达的系统可被寻址暴露原本不可达的状态收窄权限边界降低上下文成本提供可靠的验证手段一个真实的迁移案例说明了这一点某团队最初通过MCP让 Agent 连接 Electron 应用Chrome DevTools 协议后来一位同事用一个本地 TypeScript 守护进程加一个小 CLI替换了整个 MCP 连接——因为 Agent 实际只需要两三个操作。迁移后 Agent 照常完成任务工作流零中断。启示是载体可以换行为契约不能断要用端到端的任务测试守护这条契约。另外如果替换的是一个模型已习得工具替代实现应当保留其动作名、参数与结果形状、错误、审批行为、取消与生命周期语义让 CLI、MCP 等适配器都只是薄薄一层背后调用同一个类型化的能力包。这部分模型原生语义的详细讨论见 docs/fixed-worker/model-native-semantics.md。给新手的最小行动清单 先问发现你的工具出现在 Agent 的训练集里吗如果没有给它一个模型可见的目录名称 用途 输入 输出 首个示例调用选载体通用操作 → 熟悉的 CLI私有系统 / 权限敏感 / 重复操作 → MCP 或定制工具设计结果成功安静、失败定位、错误可恢复、细节可检索守住最小接口只暴露能关掉任务的最小能力面用完整旅程验证换任何载体前后都跑一遍完整任务测试仓库提供的应用手册见 playbooks/repository-review.md结语Harness Engineering 把工具设计从给人写文档升级为给模型写接口发现性、熟悉度、结果上下文、最小接口四者缺一不可。CLI 与 MCP 不是二选一的战争而是两条轴上的取舍——让 AI Agent 在需要的那一刻找到工具、用对工具、读懂结果你的环境就完成了最后一公里。想继续深入可以从论文索引 docs/README.md 和来源库 sources/README.md 沿线索一路读下去。【免费下载链接】harness-engineering Ryan Lopopolo’s anthology, field guide, and agent context bundle for harness engineering项目地址: https://gitcode.com/gh_mirrors/har/harness-engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考