Rufus' ink

万字长文｜一文弄懂 Harness Engineering

Wed, 29 Jul 2026 00:00:00 GMT

前言

✏️ 针对现在层出不穷的 AI 新概念，拒绝「错失恐惧症」，也就是我们常说的 Fomo！请先对自己默念：拒绝 Fomo ！拒绝 Fomo ！拒绝 Fomo ！重要的事情说三遍呀！

Harness 并不是 AI 圈子凭空发明的新概念。作者在此前的 AI 实践中，一直在尝试总结一套完整的方法论，但发现无论是 Prompt Engineering 还是 Context Engineering，都无法很好地囊括全部实践。于是，作为前端工程师，索性自己造了个新词："AI 工程化"或"AI 基建设计"。

Harness Engineering 这个词的出现，不过是用一个更形象、更生动的词语，对这类现有实践做了一次系统性的汇总和命名。

本文的部分内容来源于作者多次模型评测和工程实践中的思考，行文风格可能与常见的技术文章有所不同。如有不当之处，还请大家不吝指正。在正式阅读这篇文章之前，我也给大家准备了一份术语说明，如果你在阅读过程中有任何不清楚的地方，欢迎随时查看。

| 术语 | 专业释义 | 类比说明 | | ----------------------------- | ------------------------------------------------- | ------------------------------------------------ | | Harness Engineering | 围绕 AI 智能体构建约束、反馈与控制系统的工程学科，旨在将模型的智能转化为可靠的生产力。 | 一支能力超群但缺乏纪律的施工队，设计一套包含图纸、建材标准、质检流程和安全规范的工程管理体系。 | | AI Agent | 一个能基于环境感知、进行自主规划、并执行一系列动作以达成特定目标的 AI 程序。 | 一个配备了传感器、大脑和工具箱的自主机器人，能够独立完成从"打扫房间"到"组装家具"等复杂任务。 | | Context Engineering | 在任务执行的恰当时机，为 AI Agent 精确提供所需信息的工程实践，强调"少即是多"和结构化。 | 扮演一名高效的手术室护士，在外科医生需要时，准确递上相应的手术器械，而不是把整个工具车推过去。 | | Architectural Constraints | 通过自动化工具强制执行的一系列编码和设计规则，用于维护系统架构的一致性与健康度。 | 城市交通系统中的红绿灯、单行线和道路护栏，它们共同确保了车流的有序与安全。 | | Self-Verification | AI Agent 在完成任务的某个阶段后，自主运行测试或检查清单来验证其产出是否符合预期的过程。 | 学生在交卷前，自己逐题检查答案、验算结果，以确保没有疏漏或计算错误。 | | Ralph Loop | 一种强制 AI Agent 不断迭代、直至其产出通过客观验证标准才允许终止的执行循环机制。 | 一个设定了"必须命中靶心才能结束"的射箭练习。只要没射中，就必须重射，直到成功为止。 | | Entropy / 熵 | 在软件系统中，指随着时间推移和持续修改，系统逐渐积累的混乱、无序和技术债务。 | 一个书架，如果只放书不整理，久而久之就会变得杂乱无章，难以快速找到想要的书。 |

废话不多说，正文开始～

一、Harness Engineering 是什么？

📷 文章配图

2026 年，继提示词工程（Prompt Engineering）与上下文工程（Context Engineering）之后，软件工程领域迎来了一个新的关键词：Harness Engineering。这个概念由 HashiCorp 联合创始人 Mitchell Hashimoto 提出，并因 OpenAI 的一篇报告而广为人知。

其核心隐喻："马与缰绳"：生动地描绘了它的使命：为强大但方向不定的"野马"（例如 AI Agent 或任何复杂的软件系统）套上名为"Harness"的"缰绳"，通过约束、引导并纠正其行为，确保它能沿着预设的轨道稳定、可靠地前行。

我们通过一个形象的比喻，相信你会更加清楚：AI Agent = SOTA 的模型（野马） + Harness（驾驭系统） = 千里马

AI Agent 如同一匹潜力无限的"野马"，而 Harness Engineering 则是那套能将其驯化为"千里马"的完整驾驭体系。它不是去改变马的基因（模型本身），而是为它设计一套专业的马具和训练方法。

🌳 Harness 就是：除了 LLM 本身之外，让 Agent 真正能干活的一切基础设施。Harness Engineering 不是"更好的提示词（Prompt）"，也不是"更强的模型"，而是优化模型运行的环境与机制。它的本质是**优化模型运行所需的环境、机制与基础设施的总和，**它是一套将 AI 的"智能"转化为可靠、可控、可规模化"生产力"的工程哲学与实践框架。

再次明确这一点：Harness Engineering 不是一个需要焦虑追捧的全新发明，而是对一系列现有工程实践的系统性总结与命名。正如本文开篇所说，它更像是一套"AI 工程化的驾驭体系"，旨在解决一个核心问题：当 AI 成为我们团队的一员时，我们该如何管理这位"超级实习生"？

概念已经明晰，那么下一个自然而然的问题是：我们为什么需要它？

二、为什么需要 Harness Engineering？

随着 AI 从单一的"应答机器"向能够自主规划和执行复杂任务的智能体（AI Agent）演进，工程师的角色正在发生根本性的转变。Harness Engineering 的出现，正是为了应对这一转变带来的全新挑战。其必要性主要体现在以下几个方面：

构建更可靠的 Agent 系统

为了让 Agent 从**"有趣的玩具"变为"可靠的工具"**，它必须满足四个核心目标，我们可以将其概括为 R.E.S.T 模型：

可靠性（Reliability）

定义：系统在面对各种预期和非预期的输入、环境变化和内部故障时，能够持续、稳定地提供服务，并完成其既定任务的能力。
关键要求：
- 失败可恢复：任务中断后能自动从检查点恢复。
- 操作幂等性：关键的写操作可安全重试，不会弄脏状态。
- 行为一致性：在相同输入下，行为应是可预测的。

效率（Efficiency）

定义：在满足功能和可靠性的前提下，系统使用计算、存储、网络等资源的有效性，直接关系到服务的成本和可扩展性。
关键要求：
- 资源可控：对 Token 消耗、API 调用、计算时间有精确的预算控制。
- 低延迟响应：在交互式场景中，快速给出有意义的反馈。
- 高吞吐量：在批处理场景中，单位时间内能处理更多任务。

安全性（Security）

定义：保护系统及其数据免受未经授权的访问、使用、泄露或破坏的能力。对于能自主行动的 Agent，安全性是不可逾越的红线。
关键要求：
- 最小权限：仅授予完成当前子任务所必需的权限。
- 沙盒执行：所有不授信的代码或指令必须在严格隔离的沙盒中执行。
- 输入/输出过滤：防止指令注入、敏感信息泄露和有害内容生成。

可观测性（Traceability / 可追溯性）

定义：系统提供足够的数据（日志、指标、追踪），使开发和运维人员能够理解其内部状态、决策过程和行为轨迹的能力。
关键要求：
- 全链路追踪：从请求到结果，每一个环节的调用链都清晰可追溯。
- 决策可解释：Agent 的每一个关键决策（如选择哪个工具）都应有明确的归因记录。
- 状态可审计：系统在任意历史时间点的完整状态都应可查询和审计。

Agent-First 时代对工程师的必然要求

工程复杂性持续攀升：随着 AI 能力的不断增强，人们对应用场景的复杂度和预期也水涨船高。编程场景早已不再是贪吃蛇、俄罗斯方块等 Vibe Coding 小 Demo，而是从简单的程序跃迁为复杂的工程实践。
从"执行者"到"设计者"的角色跃迁：当 AI 承担起代码编写等具体任务时，人类工程师的核心价值便从"动手执行"转向"系统设计"。我们不再是逐行编码的工人，而是设计蓝图、定义规则、验收最终成果的架构师：正如系列文章前文提到的 Spec Coding 理念。当然，仅靠给 AI 制定 Prompt 规则这种"软约束"是远远不够的。

也是 Harness Engineering 爆火的起因：https://openai.com/zh-Hans-CN/index/harness-engineering/

| | 传统工程师 | Harness 时代工程师 | | -------- | --------- | ------------------ | | 价值 | 写代码的速度和质量 | 设计系统的能力 | | 核心技能 | 编码 | 约束设计、反馈回路设计、控制系统设计 | | 产出 | 代码 | Agent 可靠运行的环境 | | 关注点 | 代码本身 | 支撑结构（工具、抽象、反馈回路） |

🌳 一个令人瞩目的行业实验印证了这一趋势：一个仅三人的小型团队，在几乎不手写任何代码的情况下，通过引导 AI Agent，于短短五个月内构建了一个百万行代码级别的复杂产品，期间累计合并了约 1,500 个 Pull Request。这一实践有力地证明了一个趋势：当 AI 成为主要的"生产力"时，传统的工程管理模式已不再适用。我们不再是逐行编码的工人，而是绘制蓝图、定义规则、最终验收成果的架构师。

仅通过提示词（Prompt）下达指令这种"软约束"远远不够，我们需要一套"硬约束"的工程体系"来保障最终产物的质量、可靠性与可维护性：这正是 Harness Engineering 的用武之地。

简而言之，Harness Engineering 的核心理念是：当模型遇到问题时，通过一套工程化的 Harness 机制，从根本上避免同类问题再次发生。

它是这个时代的产物：随着模型的持续迭代，更多基础能力将被内化至模型本身，部分 Harness 也将随之退出历史舞台；与此同时，新的应用场景不断涌现，也必将催生新的 Harness 实践。

明确了"为什么"之后，让我们进一步拆解 Harness Engineering 到底包含哪些具体内容。

三、Harness Engineering 包含什么

在当前基于 Transformer 和自回归的 LLM 架构下，模型的原始输出本质上是随机且无序的。

而 Harness Engineering 的作用，正是通过有序的约束来驾驭无序的算力，从而完成更加复杂的工程实践。

要理解它"包含什么"，我们首先需要理解 Agent 是如何运作的。一个完备的 Agent 系统，其核心运行机制可抽象为一个持续循环的四阶段过程：感知（Perception）、规划（Planning）、行动（Action）、以及反思（Feedback / Reflection）。

| 环节 | 英文全称 | 核心内容 | |-|-|-| | P - 感知 | Perception | Agent 通过 "传感器" 或接口，从外部环境和内部状态采集信息，包括用户指令、外部 API 返回数据、系统监控指标、历史对话记录等。感知的全面性、准确性和结构化程度直接决定 Agent 决策的上限。 | | P - 规划 | Planning | 在感知基础上，由 LLM 担当的 "大脑" 理解当前状态与最终目标的差距，将复杂任务分解为可执行的子任务或步骤，核心是决策，涉及路径选择、资源分配、工具筛选及潜在风险预判。 | | A - 行动 | Action | 规划完成后，Agent 通过 "效应器" 与外部世界互动，可调用 API、执行代码、向用户返回信息或与其他系统交互，行动的精确性和可靠性是实现目标的关键执行环节。 | | F - 反思 | Feedback/Reflection | 行动结果作为反馈被系统捕获，Agent 比较行动结果与预期目标的差异并反思，可能触发新规划（如纠正错误、调整策略），或存入记忆影响下一轮感知和规划，形成持续学习和优化的闭环。 |

Harness Engineering 将 Agent 的工程化体系解构为四个核心维度，每个维度都与 PPAF 闭环的一个或多个环节紧密耦合。这四个维度共同构成了一个完整的 Agent "马具"（Harness），用于驾驭、约束和提升 Agent 这匹"智能之马"。

为了更系统地理解不同类型 Agent 的能力边界和工程挑战，我们可以构建一个二维的战略分析矩阵。该模型从"认知循环"和"上下文效率"两个维度对 Agent 应用进行划分。

横轴：AI 认知循环（Cognitive Loop）
- 被动响应（React）：Agent 的行为主要由外部单次触发驱动，执行预定义的、确定性的任务，缺乏自主规划和反思能力。
- 主动规划与反思（Proactive Plan & Reflect）：Agent 能够基于长期目标，自主进行多步规划、执行、并根据结果进行反思和动态调整。
纵轴：环境系统上下文处理效率（Context Efficiency）
- 低效（人工/单点投喂）：Agent 运行所需的大部分上下文依赖人工手动提供，或只能通过有限的、低效的接口获取。
- 高效（沙盒化/全自动注入）：Agent 运行在一个高度集成和自动化的环境中，所需上下文能够通过系统级接口（如文件系统、API 网关、状态引擎）被高效、全面地自动捕获和注入。

这个矩阵清晰地揭示了 Harness Engineering 的价值所在：Harness 的成熟度，直接决定了 Agent 应用能否从低效的、被动的第三、四象限，跃迁至高效的、主动的第一、二象限。

理解了 Harness Engineering 的组成部分后，下一步自然要问：它是如何被设计出来的？

四、Harness Engineering 是如何设计的

理论框架为我们指明了方向，现在让我们深入工程实践，探讨如何一步步构建起一个稳健的 Harness 系统。

4.1. 顶层抽象：Harness 作为带边界控制的 REPL 容器

在架构层面，Harness 的本质可以被抽象为一个带有边界控制、工具路由与确定性反馈的 REPL（Read-Eval-Print Loop）容器。它包裹在 LLM 这个非确定性的"大脑"之外，负责管理从"感知"到"行动"再到"反思"的完整生命周期，从而将 LLM 的推理能力接入到确定性的工程世界。

💡 Harness 作为 REPL 容器的核心逻辑

Read（读取）：Harness 通过上下文管理器（Context Manager），将外部世界（用户输入、API 状态）和内部记忆"翻译"成 LLM 可理解的、高度结构化的 Prompt。这实现了对"感知"环节的工程化管理。

Eval（评估/执行）：当 LLM 生成一个规划（如 Function Calling）时，Harness 通过**调用拦截器（Call Interceptor）**捕获该意图，并将其路由到正确的工具执行器。执行过程被严密监控，包括超时、资源配额和错误捕获。

Print（打印/反馈）：工具执行的结果（成功数据或异常信息）被**反馈汇编器（Feedback Assembler）**捕获，并组装成结构化的"观测结果"，重新注入到上下文中，供 LLM 进行下一轮的"反思"与"规划"。

Loop（循环）：这个"读取-评估-打印"的过程不断循环，直到 Agent 达到目标状态或触发终止条件，构成了 PPAF 的核心驱动力。

4.2. 底层转换机制：在无限状态与有限 Token 间架起桥梁

Agent 的智能涌现，建立在对海量状态信息的理解之上。然而，LLM 的核心，也就是 Transformer 架构：操作的是一个有限的、线性的 Token 序列。

🌳 因此，Harness 的核心挑战之一，就是在"无限"的外部世界状态与"有限"的 LLM 上下文 Token 之间，建立一套高效、可靠的双向映射和转化机制。

4.2.1. 上下文管理：从"无限状态"到"有限 Token"

Agent 的上下文（Context）是其感知的全部来源，它包含了任务目标、历史交互、工具定义、当前状态等海量信息。如何将这些信息有效"压缩"到 LLM 的 Token 窗口内，是规划质量的生命线。

💡 工程决策：规约规则与注入边界 上下文管理本质上是一系列**规约规则（Reduction Rules）**的集合。Harness 必须定义清晰的规则，来决定在 Token 预算紧张时，哪些信息应该被牺牲、哪些被保留。同时，**注入边界（Injection Boundary）**也至关重要，它定义了外部信息（如 RAG 结果）应在 Prompt 的哪个位置（前、中、后）注入，以达到最佳效果，避免出现"大海捞针（Lost in the Middle）"问题。

4.2.2. Function Calling：从"文本预测"到"物理执行"

Function Calling（FC）是连接 LLM 规划与物理世界行动的桥梁。这个过程看似简单，实则包含了一个严密且脆弱的生命周期闭环：

Schema 序列化：Harness 将可用的工具（函数）列表及其参数定义（JSON Schema）序列化为特定格式的文本，注入到 Prompt 中。这是 LLM 理解其"能力边界"的唯一途径。
触发生成：LLM 在其庞大的参数空间中进行"模式匹配"，当它认为某个工具能满足当前规划步骤时，会生成一段遵循特定语法的文本，其中包含工具名称和参数值。
确定性反序列化：Harness 捕获这段文本，并尝试将其反序列化为一个结构化的调用请求。这是最脆弱的环节，因为 LLM 的生成可能不完全符合语法（如 JSON 格式错误、参数类型错误）。
观测注入：Harness 执行该调用，并将执行结果（成功或失败）封装成一段"观测"文本，再次注入 Prompt，完成闭环。

失败面与降级路径

由于 LLM 生成的非确定性，Function Calling 的每一步都可能失败。稳健的 Harness 必须为这些失败设计降级路径：

反序列化失败：
- 重试：向 LLM 提供错误信息（如 "Invalid JSON format"），并要求其重新生成。
- 回退到文本：放弃 FC，转而要求 LLM 生成自然语言指令，由更传统的解析器处理。
执行失败：
- 交互式补充：若因参数缺失导致失败，可向用户请求补充信息。
- 反思与重规划：将详细的错误信息注入上下文，引导 Agent 在下一轮反思失败原因并选择其他路径。

💡 核心架构决策：状态分离原则 必须将 LLM 严格视为一个无状态的计算单元（CPU），而将所有需要跨轮次保持一致性的状态（如用户会话、任务进度）存储在 **Harness 控制的外部上下文状态管理器或其他持久化引擎（内存/硬盘）**中。反模式：试图通过 Prompt Engineering 让 LLM 在长对话中自行维护复杂状态，这会导致系统行为混乱、不可预测且难以调试。

4.3. 核心约束与设计原则

在构建 Harness 时，我们必须直面三大核心约束，并以六大设计原则作为应对之道。

三大核心约束

六大设计原则

💡

为失败而设计（Design for Failure）：将异常和失败视为系统运行的常态，而非个例。所有组件和服务都应具备容错、重试和优雅降级的能力。

契约优先（Contract-First）：所有系统内外的交互都必须由明确的、机器可读的契约（Schema， API， Event）来定义，这是实现模块化、可测试性和系统演进的基石。

默认安全（Secure by Default）：安全不是事后添加的功能，而是系统设计的出发点。遵循最小权限、零信任和纵深防御原则。

决策与执行分离（Separation of Concerns: Decision vs. Execution）：将"决定做什么"（规划）与"如何做"（执行）在逻辑和物理上解耦，提升系统的灵活性和可扩展性。

万物皆可度量（Everything is Measurable）：系统的每一个行为、每一次决策、每一次资源消耗都应该是可度量的。没有度量，就没有分析和优化。

数据驱动进化（Data-driven Evolution）：将 Agent 的每一次运行都视为一次学习机会。建立从数据采集、标注、回流到模型/知识更新的闭环，是实现系统长期智能增长的唯一路径。

4.4. 关键工程位点

为了实现上述 REPL 闭环并落地设计原则，Harness 需要在架构中部署一系列关键组件（或称"工程位点"）。

Harness Engineering 本身只是大模型工程的工程手段的总称不管是 AI SDK、Agent 实现、还是应用方的 skill 以及各种插件，本身就是尝试约束模型不在同一个问题反复摔跤，随着模型能力的逐渐提升和相关工程化的演进，各种 Harness 也在被不断内化或不断更替，讲明白了 Harness 是如何设计的，我们来聊聊具体是如何实现的。

五、Harness Engineering 是如何实现的

上文更多站在"概念 + 框架"的层面理解 Harness Engineering。对于负责落地平台和基础设施的工程同学，还可以把 Harness 进一步视作一个完整的运行系统，从架构分层、关键机制、运行治理和度量演进四个角度来审视。

5.1 系统架构总览：控制平面与数据平面

一个成熟的 Harness 通常会拆分为 控制平面（Control Plane） 与 数据平面（Data Plane）：

控制平面负责"决定做什么"：任务调度、资源配额、行为规划、策略与权限。
数据平面负责"如何去做"：实际的 Agent 运行实例、状态存储、记忆存储和沙盒执行环境。

在此之上，可以进一步抽象出四个功能层级：

在具体落地时，你可以把 Harness 看成是对现有 AI 环境的一层"智能胶水"：上接模型 API Gateway，下接沙盒和各类服务，以工程的方式串联各个基建。

5.2 核心运行机制：循环、记忆与 Token 转化

5.2.1 Agent 核心循环

原始材料中将 Agent 的行为抽象为一个持续的"观察 → 思考 → 行动"循环：

观察（Observe）：感知当前世界状态，包括用户输入、工具结果、历史对话、任务进度等。
思考（Think）：基于观察信息，由规划器更新目标、拆解任务、选择下一步行动。
行动（Act）：执行内部操作（更新记忆、结束任务）或外部操作（调用工具、发出回复），行动结果反过来进入下一轮观察。

💡 工程提醒：核心循环不是一个简单的 while (true)。 在生产环境中，它通常需要与工作流引擎或状态机框架集成，支持暂停/恢复、幂等重试、并发事件处理以及长周期任务管理，因此也就衍生出了很多工程化手段解决上下文焦虑的问题。

5.2.2 记忆分层与 Token 转化

为了在有限的上下文窗口内承载尽可能多的有效信息，多数 Agent 通过各种外挂 memory 的方式进行实现。

在三层记忆之上，Harness 还需要一条 Token 转化流水线（Token Transformation Pipeline），在每轮调用前，把多源信息规约成一个可控的 Prompt：

信息源收集：聚合用户问题、短期记忆、长期知识检索结果等。
相关性排序：基于时间、语义相似度等指标，对候选信息打分。
压缩与摘要：对冗长低密度内容做摘要或结构化提炼。
预算分配：按照预设 Token 预算，为不同信息类别分配额度。
模板组装：使用结构化模板（例如显式标注 [user_request]、[tool_output] 等）拼装最终 Prompt。

💡 关键思想：把注意力管理变成一个外部工程问题。 与其指望模型"自己想清楚该关注什么"，不如通过 Token 转化机制主动构建上下文，把有限的窗口留给真正重要的信息。

5.3 规划模式与执行策略

在"行为规划器"这一层，通常实践中根据复杂程度包含以下几种：

💡 实践建议：默认用 Plan-and-Execute，按需叠加重规划与多 Agent。 对大多数企业级场景，用结构化计划配合"异常触发重规划"已经足够稳健；只有在特别开放、长期的任务中，才需要引入多层规划与多 Agent 协作。

5.4 运行与治理：沙盒、安全与成本

5.4.1 沙盒执行框架

为了让 Agent 可以"动手做事"而不破坏系统，因此需要给 Agent 一个安全的环境让他独立运行。

Level 1 进程级隔离：使用 chroot / Linux namespaces / seccomp-bpf 限制系统调用，启动快但仍共享内核，适用于可信内部工具。
Level 2 容器级隔离：Docker / containerd 等，生态成熟，是大多数工具执行的默认选择。
Level 3 轻量级虚拟机：如 Firecracker 等提供独立虚拟内核，适合多租户或执行不可信代码。
Level 4 完整虚拟机：KVM / QEMU，安全性最高但成本最大，只在极少数特殊任务中使用。

💡 推荐策略：默认采用容器级隔离（Level 2），配合严格的系统安全内核与只读根文件系统；对不可信代码或高敏感数据，引入轻量级虚拟机（Level 3）作为加强版沙盒。

5.4.2 资源管理与弹性策略

在资源与成本控制方面，原始材料强调了几类关键机制：

预算与配额：为 Token、外部 API 调用次数、CPU 时间分别设置配额，并支持按"平台 / 租户 / Agent / 单任务"多层级配置。
超时控制：所有网络请求和工具执行都必须设置合理超时时间，避免因下游卡死拖垮整个 Agent。
重试策略：对可恢复的临时错误使用带退避的重试，对明显的永久性错误快速失败并上报。
熔断机制：当某个依赖连续失败时暂时熔断，防止出现级联故障。
优雅降级：关键能力不可用时，自动降级为"弱但安全"的模式，例如从"可执行代码"退回到"只读 + 建议"。

5.4.3 安全与合规：策略门控

除了沙盒本身，Harness 还需要一个位于"规划器 → 执行层"之间的 策略门控（Policy Gateway），负责在每一次行动前做最后的安全与合规检查，包括：

权限检查：基于 RBAC/ABAC 判定某个 Agent 是否有权访问目标资源或执行敏感操作。
敏感数据过滤：对参数和返回结果做 PII/密钥检测与脱敏。
指令注入防御：识别潜在恶意的 Prompt/命令拼接，禁止危险模式进入执行层。
审计日志：记录每一次"谁在何时尝试做什么、结果如何"，便于事后追溯和合规审计。

5.5 度量与演进：让 Harness 在数据中成长

最后，有效合理的评测用来衡量 Agent 系统是否"跑在正确的轨道上"：

任务效能（Task Effectiveness）
- 任务成功率（Task Success Rate）
- 指令遵循度（Instruction Following Rate）
- 工具使用有效性（Tool Use Effectiveness）
服务质量（Quality of Service）
- 端到端延迟（End-to-End Latency）
- 首次响应延迟（Time to First Action）
- 错误率（Error Rate）
资源效率（Resource Efficiency）
- 平均 Token 消耗（Avg. Token Consumption）
- 平均工具调用次数（Avg. Tool Calls）
安全与合规（Security & Compliance）
- 策略拒绝率（Policy Denial Rate）
- 安全事件数（Number of Security Incidents）

这些指标不是为了"凑一张大表"，而是用来反向驱动 Harness 的演进：当你发现任务成功率上不去时，很可能需要回到规划器和上下文策略；当错误率和成本居高不下时，多半需要反查沙盒、资源配额和熔断策略是否设计合理。

写在最后

Harness Engineering 从来不是又一个需要顶礼膜拜的"银弹"，而是一套生于实践、归于实践的工程哲学。

🌳 当 AI 的代码生成能力一次次突破想象，当整个行业都在狂热地谈论"颠覆"与"取代"，这套方法论冷静地提醒我们：工程师的核心职责从未消失，而是完成了一次关键的升华：从代码的创作者，变成了创造过程的守护者。

构建一套可靠的 Harness 系统，本质上是在软件世界的"混沌"与"秩序"之间寻找那个微妙的平衡点。我们从不奢望 AI 永远正确，正如我们从不指望人类永不犯错。真正的工程智慧，在于构建一个能够从错误中持续学习、在不确定性中稳健前行的系统。

这套"缰绳"的终极目的，从来不是束缚，而是为了更安全、更彻底地释放，或许不远的将来，模型会逐渐挣脱一层层基础束缚。

原文链接：万字长文｜一文弄懂 Harness Engineering 作者：咸鱼（TRAE 开发者用户）

如何让你的 Agent 更准确：MCP 工具设计技巧（上）

Tue, 28 Jul 2026 00:00:00 GMT

参考Trae的技术文章，学习应用MCP工具

越来越多的开发者开始为 AI Agent 开发工具，无论是通过 MCP（Model Context Protocol）、Skills 脚本、还是直接使用 OpenAI/Claude 的 function calling。但很快大家发现了一个令人困惑的现象：技术上实现完全正确的工具，Agent 却用不好。 工具能跑通，schema 定义正确，API 调用成功，但是 Agent 总是选错工具，传错参数，或者在明明应该调用工具的时候却回复「我无法完成这个任务」。

问题出在哪里？

问题在于：我们用写 API 的思维在写 Agent 工具。

当你为人类设计 API 时，你可以假设他们会阅读文档、理解上下文、在出错后调试代码，但 Agent 不一样：

它只能通过工具的名称、描述和参数 schema 来「理解」这个工具能做什么
它「试错」的代价很高，每次调用都消耗 token，都可能影响用户体验
它需要在可能几十上百个工具中，瞬间做出选择
它有一定的试错能力，但是成本高且不稳定

这意味着，给 Agent 开发工具的真正挑战不是技术实现，而是设计出 Agent 能用好的工具接口，这也是我们在开发 TRAE 过程中一直在思考和解决的一个问题。

核心理念：Agent 工具是 Agent 的用户界面

这里有一个关键的思维转换：Agent 工具是 AI Agent 的用户界面（User Interface），不是已有 REST API 的封装

传统 REST API 是为人类开发者设计的，我们假设开发者会阅读文档、理解上下文、在出错后调试代码，但 Agent 是完全不同的「用户」，它不会主动查阅文档，不擅长从上下文中推断隐含信息，每次调用都需要从头开始理解工具的用途。

换句话说：你不是在写 API，你是在教会一个智能体如何与这个世界交互。

这个智能体（LLM）有着独特的长处与局限性：

它擅长理解自然语言、推理意图、组合信息
它不擅长精确计算、记住长上下文、从模糊描述中猜测正确参数
它看不到你的代码实现，只能看到你暴露的 schema 和描述
它只具备有限的上下文，并且随着上下文被打满工具调用性能会明显下降

只有理解这个智能体的特性，你才能设计出它真正能用好的工具。本文将以 MCP 为主要切入点，因为它正在成为 Agent 工具开发的主流方式，但文中的设计原则适用于所有 Agent 工具开发场景。

LLM Tool Calling：完整的调用链路

要设计好 Agent 工具，首先需要理解它是如何被 Agent 调用的，这条调用链路决定了你的设计将如何被「消费」。

LLM 原生的 Tool Calling 机制

让我们从最底层开始：LLM 本身是如何调用工具的？

一个关键的认知：LLM 本身不会「执行」任何函数。 它只做一件事：生成文本，所谓的「function calling」或「tool calling」本质上是 LLM 与应用程序之间的一个多轮对话协议：

┌─────────────┐                              ┌─────────────┐
│             │  ① 发送请求 + 工具定义         │             │
│             │ ─────────────────────────────▶│             │
│             │                              │             │
│             │  ③ 返回「工具调用请求」         │             │
│   应用程序   │ ◀─────────────────────────────│     LLM     │
│             │                              │             │
│             │  ⑤ 返回工具执行结果            │             │
│             │ ─────────────────────────────▶│             │
│             │                              │             │
│             │  ⑥ 生成最终回复（或继续调用）    │             │
│             │ ◀─────────────────────────────│             │
└──────┬──────┘                              └─────────────┘
       │
       │ ④ 执行实际的函数调用
       ▼
┌─────────────┐
│  外部工具    │
│ (API/DB/..) │
└─────────────┘

② LLM 分析用户请求，决定是否需要调用工具

第一步：定义工具

以 OpenAI API 为例，工具通过 tools 参数传递给模型。每个工具定义包含三个核心部分：

tools = [
    {
        "type": "function",
        "name": "get_weather",                    # 工具名称
        "description": "获取指定城市的当前天气",    # 工具描述 - LLM 理解工具用途的关键
        "parameters": {                           # 参数的 JSON Schema
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "城市名称，如：深圳、北京"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "温度单位"
                }
            },
            "required": ["location"]
        }
    }]

这三个部分：name、description、parameters，就是 LLM「看到」的工具的全部信息。它看不到你的代码实现，不知道函数内部做了什么。

第二步：LLM 决策与返回工具调用

当用户说「深圳今天天气怎么样？」时，LLM 会分析这个请求，发现需要调用 get_weather 工具。但它不会执行任何代码，而是返回一个结构化的「工具调用请求」：

{
  "id": "fc_12345xyz",
  "type": "function_call",
  "name": "get_weather",
  "arguments": "{\"location\": \"深圳\", \"unit\": \"celsius\"}"
}

注意 arguments 是一个 JSON 字符串，LLM 本质上只是在「生成文本」，只不过这段文本遵循了特定的结构化格式，存在返回非法 JSON 格式的可能。

第三步：应用程序执行函数

应用程序解析 LLM 返回的工具调用请求，执行实际的函数，这里以 Python 代码进行示例：

import json

# 解析 LLM 返回的工具调用
tool_call = response.output[0]  # 获取第一个工具调用
args = json.loads(tool_call.arguments)

# 执行实际的函数（这是你的代码，不是 LLM 执行的）
weather_result = get_weather(args["location"], args.get("unit", "celsius"))

# 返回: {"temperature": 14, "condition": "晴", "humidity": 65}

第四步：将结果返回给 LLM

执行结果需要通过 function_call_output 类型的消息返回给 LLM：

# 将工具执行结果添加到对话中
input_messages.append({
    "type": "function_call_output",
    "call_id": tool_call.call_id,  # 关联到具体的工具调用
    "output": json.dumps(weather_result)
})

# 再次调用 LLM，让它基于结果生成最终回复
final_response = client.responses.create(
    model="gpt-4",
    tools=tools,
    input=input_messages
)

第五步：LLM 生成最终回复

LLM 收到工具执行结果后，会生成用户可读的最终回复：

"深圳今天天气晴朗，当前气温 14°C，湿度 65%。"

工具定义如何被 LLM「看到」？

这是一个容易被忽视但非常重要的细节，要理解工具设计的约束，我们需要从 LLM 实现的角度来看工具调用是如何工作的。

1. JSON 只是中间格式，不是 LLM 真正「看到」的东西

当你通过 API 传入 JSON 格式的工具定义时，LLM 提供商通常会将其转换为一种内部优化的格式。这是因为 JSON 对 LLM 来说并不是一个友好的格式：

边界模糊：JSON 使用 {}、[]、" 等通用符号标记结构，这些符号在普通文本中也会频繁出现，容易产生歧义
严格的语法要求：少一个逗号、多一个引号就会导致解析失败，而 LLM 生成文本时很容易犯这类错误
字符串转义的噩梦：JSON 字符串中的引号需要转义为 \"，反斜杠需要转义为 \\，换行需要转义为 \n。当参数内容包含代码片段时（这在 coding agent 中极为常见），LLM 需要正确处理代码中的所有引号、反斜杠和换行符，这是一个极易出错的环节
远距离依赖：嵌套结构中，匹配的括号可能相隔很远，LLM 需要「记住」开始标记才能正确闭合
缺乏显式结束标记：JSON 只依赖括号匹配，没有像 </function> 这样语义明确的结束信号

相比之下，许多 LLM 提供商内部使用类 XML 的格式来表示工具调用，相比 JSON 格式有以下优势：

明确的边界：开始标签和结束标签清晰地标记了工具调用的范围
自描述性：标签名本身携带语义信息，比 JSON 的键值对更不容易与内容混淆
训练数据丰富：LLM 在预训练时见过大量 HTML/XML 文档，对这种格式更「熟悉」
容错性更好：即使内容中包含类似符号，也不容易与结构标记产生冲突

实际上，不同提供商采用了不同的内部格式和特殊 token。这些格式在模型训练时就被专门优化过，使模型能够更准确地识别「何时应该调用工具」以及「如何正确构造调用参数」。

一些 LLM 提供商（如 OpenAI 的 Strict Mode）使用了 Constrained Decoding 技术来保证输出一定是合法的 JSON 结构。这种技术在解码时动态限制下一个 token 的候选集，确保生成的序列符合预定义的 schema。但这种约束并非没有代价：它可能影响生成速度，在某些边界情况下也可能影响模型的表达能力。

2. 工具定义是 System Prompt 的一部分

工具定义会被注入到 LLM 的 system prompt 中，占用宝贵的 context window。这带来两个重要影响：

上下文占用：工具定义占用的 token 越多，留给实际对话内容的空间就越少
Prompt Caching：现代 LLM API 通常会缓存 system prompt 的 KV cache 来加速推理。如果你动态修改工具列表，就会导致缓存失效，显著增加延迟和成本。

3. 为什么要用原生的 Function Calling？

LLM 在训练过程中已经对原生的工具调用格式进行了专门的优化。使用原生格式，模型更容易准确识别何时应该调用工具、正确选择要调用的工具、生成符合 schema 的参数。这也是为什么主流 Agent 框架都直接使用各 LLM 提供商原生的 function calling 机制。

4. 工具数量对模型效果的影响

| 工具数量 | Token 消耗 | |---------|-----------| | 10 个工具 | 2,500-3,000 tokens | | 20 个工具 | 5,000-6,000 tokens | | 50 个工具 | 12,500-15,000 tokens | | 100 个工具 | 25,000-30,000 tokens |

当工具数量增加到几十甚至上百个时，模型会面临选择困难、注意力稀释、Prompt 拥挤等问题。OpenAI 官方建议：尽量将工具数量控制在 20 个以内。

MCP 的定位：标准化的工具协议层

MCP（Model Context Protocol）并没有改变 tool calling 机制，它解决的是另一个问题：如何标准化地定义和暴露工具。在 MCP 出现之前，你需要为每个 LLM 单独适配工具 schema，这就是经典的 N×M 问题。MCP 引入标准化中间层，MCP Server 只需按协议暴露工具，MCP Client 负责转换成各 LLM 能理解的格式。

MCP 工具的命名约定与潜在问题

MCP 工具通常添加前缀：mcp_<server-name>_<tool-name>。这会带来：

与自带工具的冲突或歧义aa
工具名过长（如 TRAE 有 60 字符限制）
工具数量爆炸（多个 MCP Server 可累计超过 20 个建议上限）
命名空间污染（多个 search 工具描述相似）
Schema 兼容性问题（不同 LLM 对 JSON Schema 支持差异大）
LLM 参数传递的不确定性（类型错误、格式不符、必填字段缺失等）

设计建议：尽量使用简单、扁平的 schema 结构，做好防御性编程。

Agent 如何「看」工具？

Agent 眼中的工具：三元组

每个工具就是一个简单的三元组：工具 = (名称, 描述, 参数 Schema)。没有代码实现，没有注释，没有文档链接。

Agent 依赖显式语义，而非隐含上下文

# ❌ 依赖隐含上下文
def get_user(id):
    """获取用户信息"""
    pass

# ✅ 显式语义化
def get_user_by_uuid(user_uuid: str):
    """
    根据 UUID 获取用户信息。
    参数：user_uuid: 用户的唯一标识符，格式为 'usr_xxxxxxxx'
    返回：用户信息的 JSON 对象，包含 name、email、created_at 等字段
    """
    pass

设计 Agent 工具的核心原则：防呆式语义化，假设 Agent 会完全按字面意义理解你的工具，不会做任何「显然」的推断。

Agent 的「试错」成本

Agent 需要尽量一次做对，因为成本高昂、用户体验差、上下文被污染、且没有跨会话记忆复用。

上下文窗口：稀缺的认知资源

工具数量要克制（1-5 个精心设计的工具 > 20 个随意堆砌的工具）
描述要精准而简洁
参数要必要且充分

如何命名：让工具「自解释」

动词优先：create_github_issue、send_slack_message
命名即分类：使用一致前缀帮助 Agent 快速筛选
长度适中：保持工具名在 30-50 字符以内

描述的艺术：精准的契约

好的工具描述应回答四个问题：做什么？什么时候用？有什么限制？返回什么？

参数描述善用示例、标注必填/可选、说明默认值和失败情况、引导工具选择顺序。

关键洞察

设计工具的本质，是在设计 Agent 的认知体验。好的工具设计，就是不断减少 Agent 的认知负担。

原文链接：如何让你的 Agent 更准确：MCP 工具设计技巧（上）作者：小夏，TRAE 技术专家

XianyuFlip手册

Thu, 16 Jul 2026 00:00:00 GMT

🏕️ 专为闲鱼平台打造的AI值守解决方案，实现闲鱼平台7×24小时自动化值守，支持多专家协同决策、智能议价和上下文感知对话。

实际效果展示

设置代理IP

电商类的平台一般都会有风控，需要避免跨区域登陆。所以建议使用前先接入一个IP代理。

🔗 快代理 - 企业级HTTP代理IP云服务

推荐使用快代理，购买自己常用地点的固定IP地址。

比如我的设备都放在杭州购买完成后，进入我的独享代理，复制IP地址、端口、秘钥，填写到XianyuFlip后台点击检测，显示连接正常，即可使用

⚠️ 如果触发了风控，需要在浏览器登录闲鱼，手动过滑块并填写新的Cookie。当前版本正常使用还是比较稳定的。

登陆闲鱼账号

账号管理中已经支持扫码登陆，建议直接采用扫码登陆即可。要开启自动回复，还需要绑定一个AI回复方案。请参考下一节设置

设置AI回复

大模型设置

推荐使用小米MIMO、DEEPSEEK，便宜效果好。

🔗 小米MIMO
🔗 DeepSeek Platform

完成模型的充值购买后，在大模型后台创建一个APIkey 填写基础URL和APIkey到XianyuFlip后台

deepseek：https://api.deepseek.com
XiaomiMIMO：https://api.xiaomimimo.com/v1

填写后点击获取模型列表即可获取该服务商的全部模型，选取合适的使用即可。

帖子主导/知识库主导

帖子主导： 大模型会基于商品帖子中的内容以及标价和用户沟通；

知识库主导： 根据用户发送的消息（以及图片）中的型号等关键词，先匹配知识库中的商品，以知识库中的信息为准。

常规业务，帖子可以覆盖产品信息和报价，设置帖子主导即可；复杂实物交易，如充电机等，可以采用知识库主导。

AI回复逻辑

意图分类提示词：判断用户当前的对话意图，分配给以下专家进行具体对话
价格专家提示词
技术专家提示词
默认回复提示词

提示词均可根据需求自行修改，优质提示词可以参考下方提示词参考章节。

响应图片消息

如果业务场景中用户经常通过图片来提供产品型号，可以打开 支持图形识别 按钮

（注意图片上需要带型号的文字，本质是文字识别）

产品知识库

模版知识库

如果你的产品满足以下情况：

报价逻辑比较复杂
涉及多sku、多品相
客户来咨询的时候，并不会按照帖子里面的内容来咨询

建议开启知识库功能，目前只支持飞书多维表格作为知识库。目前已经提供三电知识库，可以直接使用新能源汽配知识库

名称：任意填写
BaseURL：https://my.feishu.cn/base/XdhGbKR2baOoK0s86XucR9F8nDg
APP ID：cli_aac0100744389bee
APP secret：eu0jPSscMpFgcpD6y9zs4nn7SJ00nLtr
产品表ID：tblzbTYAzbHfVjl2
SKU报价表ID：tblDxJxsTvZABY6L

创建自己的知识库

可以参考知识库案例来制作自己的知识库。

在飞书开放平台创建应用，添加多维表格读写权限，然后复制APP ID和APP secret。根据模板创建自己的多维表格，然后复制BaseURL和两张表格的ID。在XianyuFlip后台填写，保存后即可生效。

消息通知

当发生异常情况，用户下单、退款的时候，都会通过飞书去进行消息提醒。

两步即可实现：

创建一个飞书群聊并在里面添加一个机器人
把机器人的webhook填写到XianyuFlip后台

提示词参考

🏖️ 这里收集适合各行各业的提示词，欢迎大家贡献

三电提示词

Using MDX

Sun, 01 Jun 2025 00:00:00 GMT

This theme comes with the @astrojs/mdx integration installed and configured in your astro.config.ts config file. If you prefer not to use MDX, you can disable support by removing the integration from your config file.

Why MDX?

MDX is a special flavor of Markdown that supports embedded JavaScript & JSX syntax. This unlocks the ability to mix JavaScript and UI Components into your Markdown content for things like interactive charts or alerts.

If you have existing content authored in MDX, this integration will hopefully make migrating to Astro a breeze.

Example

Here is how you import and use a UI component inside of MDX.
When you open this page in the browser, you should see the clickable button below.

import { Button } from 'astro-pure/user'

Click Me

Markdown 语法支持

Wed, 26 Jul 2023 08:00:00 GMT

基本语法

Markdown 是一种轻量级且易于使用的语法，用于为您的写作设计风格。

标题

文章内容较多时，可以用标题分段：

# 标题 1

## 标题 2

## 大标题

### 小标题

标题预览会打乱文章的结构，所以在此不展示。

粗斜体

_斜体文本_

**粗体文本**

**_粗斜体文本_**

预览：

斜体文本

粗体文本

粗斜体文本

链接

文字链接 [链接名称](http://链接网址)

预览：

文字链接链接名称

行内代码

这是一条 `单行代码`

预览：

这是一条 行内代码

代码块

```js
// calculate fibonacci
function fibonacci(n) {
  if (n <= 1) return 1
  return fibonacci(n - 1) + fibonacci(n - 2)
}
```

预览：

// calculate fibonacci
function fibonacci(n) {
  if (n <= 1) return 1
  return fibonacci(n - 1) + fibonacci(n - 2)
}

当前使用 shiki 作为代码高亮插件，支持的语言请参考 shiki / languages。

行内公式

这是一条行内公式 $e^{i\pi} + 1 = 0$

预览：

这是一条行内公式 $e^{i\pi} + 1 = 0$

公式块

$$
\hat{f}(\xi) = \int_{-\infty}^{\infty} f(x) e^{-2\pi i x \xi} \, dx
$$

预览：

$$ \hat{f}(\xi) = \int_{-\infty}^{\infty} f(x) e^{-2\pi i x \xi} , dx $$

当前使用 KaTeX 作为数学公式插件，支持的语法请参考 KaTeX Supported Functions。

图片

![CWorld](https://gravatar.loli.net/avatar/1ffe42aa45a6b1444a786b1f32dfa8aa?s=200)

预览：

删除线

~~删除线~~

预览：

~~删除线~~

列表

普通无序列表

- 1
- 2
- 3

预览：

普通有序列表

1. GPT-4
2. Claude Opus
3. LLaMa

预览：

GPT-4
Claude Opus
LLaMa

列表里可以继续嵌套语法

引用

> 枪响，雷鸣，剑起。繁花血景。

预览：

枪响，雷鸣，剑起。繁花血景。

引用里也可以继续嵌套语法。

换行

markdown 分段落是需要空一行的。

如果不空行
就会在一段

第一段

第二段

预览：

如果不空行就会在一段

第一段

第二段

分隔符

如果你有写分割线的习惯，可以新起一行输入三个减号--- 或者星号 ***。当前后都有段落时，请空出一行：

---

预览：

高级技巧

行内 HTML 元素

目前只支持部分段内 HTML 元素效果，包括 <kdb>  ，如

键位显示

使用 <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>Del</kbd> 重启电脑

预览：

使用 Ctrl + Alt + Del 重启电脑

粗斜体

<b> Markdown 在此处同样适用，如 _加粗_ </b>

预览：

Markdown 在此处同样适用，如加粗

其他 HTML 写法

折叠块

<details><summary>点击展开</summary>它被隐藏了</details>

预览：

表格

| 表头1 | 表头2 |
| ----- | ----- |
| 内容1 | 内容2 |

预览：

| 表头1 | 表头2 | | ----- | ----- | | 内容1 | 内容2 |

注释

在引用的地方使用 [^注释] 来添加注释。

然后在文档的结尾，添加注释的内容（会默认于文章结尾渲染之）。

[^注释]: 这里是注释的内容

预览：

在引用的地方使用 ^注释来添加注释。

然后在文档的结尾，添加注释的内容（会默认于文章结尾渲染之）。

To-Do 列表

- [ ] 未完成的任务
- [x] 已完成的任务

预览：

[ ] 未完成的任务
[x] 已完成的任务

符号转义

如果你的描述中需要用到 markdown 的符号，比如 _ # * 等，但又不想它被转义，这时候可以在这些符号前加反斜杠，如 \_ \# \* 进行避免。

\_不想这里的文本变斜体\_

\*\*不想这里的文本被加粗\*\*

预览：

_不想这里的文本变斜体_

**不想这里的文本被加粗**

内嵌 Astro 组件

See User Components and Advanced Components for details.