企业官网建设流程全解析

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-engineering

Harness Engineering（马具工程）是一种通过塑造 AI Agent 周围环境来提升其产出的工程实践，它的两个外部杠杆是上下文与工具。本文结合开源项目 Harness Engineering 中的工具可读性论述，完整对比CLI与MCP（Model Context Protocol，模型上下文协议）两种工具载体，给出面向初学者的 AI Agent 工具设计指南：如何让 Agent 在需要的那一刻发现你的工具、正确调用、解读结果并在失败后自我修复。

为什么 AI Agent 找不到你的工具？🔍

很多团队给开发者写了漂亮的 CLI，却在接入 AI 编码 Agent（如 Claude Code、Codex）后发现：Agent 根本不知道这个工具存在。

项目原文一针见血地指出（见 sources/raw/hyperbola/tool-discovery.mdx）：

Coding agents like Claude Code and OpenAI Codex don't 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 可以立刻向模型广播工具清单，但模型仍要学习每个新工具的调用方式和返回结构。

一句话总结（来自 tool-discovery 原文）：MCP 是"给模型的 tokens"——Unix 管道和 man 页曾同时为人类提供组合能力与发现能力；而在 Agent 系统中，LLM 提供组合能力，MCP 提供可发现性与操作暗示（affordances）。

工具目录五要素：让 Agent 一次看明白 🧭

对于动态的、模型不熟悉的能力，Harness Engineering 提倡提供一份紧凑的、模型可见的目录，至少包含五要素：

1. 有意义的名字（能暗示用途，而非内部代号）
2. 用途说明（何时该用、何时不该用）
3. 输入形状（参数结构）
4. 结果形状（返回什么，好让 Agent 预判如何解读）
5. 第一个有用调用（可直接照抄的示例命令）

同时用渐进式披露（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。

给新手的最小行动清单 🚀

1. 先问发现：你的工具出现在 Agent 的训练集里吗？如果没有，给它一个模型可见的目录（名称 + 用途 + 输入 + 输出 + 首个示例调用）
2. 选载体：通用操作 → 熟悉的 CLI；私有系统 / 权限敏感 / 重复操作 → MCP 或定制工具
3. 设计结果：成功安静、失败定位、错误可恢复、细节可检索
4. 守住最小接口：只暴露能"关掉任务"的最小能力面
5. 用完整旅程验证：换任何载体前后，都跑一遍完整任务测试（仓库提供的应用手册见 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