引言：为什么你的 Agent 只能写 Demo？

过去一年，Vibe Coding 让无数开发者体验到了凭借直觉与 AI 快速构建 Demo 的乐趣。然而，当这些 Demo 试图走向企业级生产环境时，团队往往会遭遇“硬着陆”——AI 记不住项目规范、长对话后期出现“注意力漂移”、生成的代码因隐藏缺陷被 PR 退回。

这些痛点揭示了一个核心事实：Demo 惊艳不等于产线可用。AI 编程的瓶颈已不再是模型本身的智力，而是工程化能力。2025 年我们见证了 Vibe Coding 的繁荣，而 2026 年，企业真正需要的是 Harness Engineering。

Agent = Model + Harness

在深入技术细节之前，我们需要厘清一个核心公式：

Agent = Model + Harness

Harness 一词的原意为“马具”——马匹力大无穷，但若没有缰绳的控制与牵引，便无法拉动车辆。大语言模型也是如此，它本身只是一个具备理解与生成能力的“智力引擎”，而 Harness 则是包裹在模型外层的一切工程化基础设施：上下文管理、工具调度、事件拦截、状态持久化、安全治理等。

行业实测已证实一个关键规律：

同一模型在不同 Harness 下的表现差异，远大于不同模型在同一 Harness 下的差距。

在 TerminalBench 基准测试中，仅通过对 Harness 层的优化，就使同一个模型的能力从基线以下跃升至 Top 5。

Vercel 团队发现，主动剔除 80% 的 Agent 工具后，流程更精简，Token 消耗骤降，响应速度反而更快。

因此，调教 Harness 才是释放 AI 真实工程效能的真正变量。

Harness 的核心架构：ETCLOVG 七层框架

学术界与工业界对 Harness 的解读不断深入。CMU、Yale、Amazon 等联合发表的综述《Agent Harness Engineering: A Survey》提出了一个实用的七层分类框架——ETCLOVG，覆盖了 Agent 生产运行所需的所有维度：

层级英文核心职责

执行环境ExecutionAgent 在哪里跑？本地、容器、浏览器、远程沙箱？边界在哪里？ 工具接口Tooling工具怎么描述、发现、调用？如何防止模型乱选工具？ 上下文与记忆Context短期上下文、会话状态、长期记忆如何管理？ 生命周期编排Lifecycle单轮还是多轮？单 Agent 还是多角色分工？ 可观测性Observability每次调用、工具执行、报错、重试、成本都要能追踪。 验证与评估Verification结果对不对？失败原因是模型、工具、上下文还是环境？ 治理与安全GovernanceAgent 有什么权限？哪些操作需要人工审批？如何审计？

这七层合在一起，才是一个能跑长任务的 Agent 系统。很多人理解 Agent 还停在“模型 + 工具调用”，但工具调用只是其中一层。真正的 Agent 产品，要有执行环境、上下文、编排、监控、验证和治理——否则它很容易变成一个“会动的 Demo”。

第一关：如何让 AI 读懂巨型代码库？

痛点：AI 记不住项目规范，大库读不完

每次新建会话都要重新给 AI 解释项目背景，且由于上下文窗口限制，面对百万行级别的代码库，AI 常常“读了后面忘前面”。

解法：五层记忆体系 + 上下文分诊

#### 1. 建立分层的记忆架构

不能把所有的规范都塞进同一个配置文件。应该构建一个五层记忆体系：

Enterprise 级：企业全局规则，写入不可绕过的安全与合规策略（如：严禁将代码发送至外部 API、禁止硬编码密钥）。

User 级：个人编码偏好（如交流语言、快捷指令映射）。

Project 级：团队共享的项目级规范（如明确使用 Fastify 框架和 pnpm 包管理）。Anthropic 官方建议该文件控制在 200~300 行以内，每一行都应是真金白银的规则。

Rules 级：将细分领域规范（如前端组件规范、数据库迁移规范）拆解为独立文件，利用 YAML Frontmatter 的 paths 字段声明 Glob 模式进行条件化加载。例如，只有当 AI 操作 tests/** 路径时，才激活测试规范。

Local 级：个人临时备忘，自动纳入 .gitignore，不提交到代码库。

#### 2. 上下文分诊：类比操作系统调度

LLM 是 CPU，Context 是内存，文件系统是磁盘。我们无法把磁盘一股脑堆进内存中，需要引入类似 OS 虚拟内存管理器的“上下文分诊”机制，将候选信息分为四个等级（P0 ~ P3）：

P0（始终在线）：项目核心规则、安全策略。

P1（高频访问）：当前任务相关的 API 文档、关键模块结构。

P2（按需加载）：特定功能的实现细节、历史对话摘要。

P3（归档检索）：已完成的旧任务记录、低频参考。

通过这种分诊调度，在排查“订单扣款失败”问题时，AI 仅调入 3 段核心日志（P0/P1）与 5 段历史工单句柄（P3），将上下文体积从 18K 压缩至 2K Token，信噪比大幅提升，定位准确度反而更高。

第二关：如何控制 AI 的幻觉？

痛点：AI 给出看起来对、实际是错的代码

在长会话中，Claude Code 在 95% 容量时会自动触发上下文压缩。如果它把一段 487-token 的“连接池耗尽”错误堆栈压缩成一句简单的 a database error occurred，AI 就丢失了反馈回路，接下来可能花费数小时重试已被堆栈排除掉的错误方案。

解法：结构化上下文 + Hooks 质量门禁

#### 1. 结构化输入，注入而非生成

减少幻觉的关键在于让 AI 基于已有代码进行“注入修改”，而不是“凭空创造”。向 AI 下达任务时，应提供结构化信息：

反例：帮我优化这个函数。

正例：优化 src/utils/parser.ts 的 parseConfig 函数，瓶颈在第 42 行的循环。

#### 2. Stop Hook 作为契约：将控制交回确定性工程

“Prompt 是请求，Hook 是契约。”我们不需要在 Prompt 里哀求 AI “请不要胡思乱想”，而是要用确定性的 Hook 门禁把不靠谱的产出挡在门外。

通过在扩展层配置 Stop Hook（在 AI 完成响应并生成完代码之后、准备交付之前触发），让系统自动静默运行单元测试与代码静态检查：

json
{
  "hooks": {
    "Stop": [
      {
        "matcher": "All",
        "command": "pnpm lint && pnpm test",
        "blocking": true
      }
    ]
  }
}

如果测试未通过，系统直接阻断本次提交并报错，把结果喂回给 AI，让其自己修改，直到自愈通过后再交付。

第三关：如何实现经验复用？

痛点：好 Prompt 锁在个人脑子里，无法团队共享

每个开发者都在自己的终端里重复写着类似的代码审查、测试生成等 Prompt，新人上手慢，全队重复造轮子。

解法：从 Prompt 到声明式 Skill

在 Claude Code 的设计中，支持将好用的 Prompt 封装为 .claude/skills/ 目录下的 Skill 资产，并通过 Git 进行版本控制。新人克隆代码库时就能瞬间继承整个团队沉淀的 AI 编程能力。

一个 Skill 实质上是一个包含 SKILL.md 的目录。为了节省 Token，Claude 采用了渐进式披露的设计：

启动阶段：仅加载每个 Skill 顶部的 name 和 description（约 100 tokens 的元数据）。

匹配阶段：当用户的输入命中该 Skill 的语义（如提到“审查代码”），系统才会展开完整的 SKILL.md 主文件。

执行阶段：只有在真正需要动作时，才动态调用挂载的 bundled 脚本/外部资源。

通过这种“只在翻开书的对应章节时才看内容”的设计，在运行多 Skill 系统时，Token 空间可节省达 98% 左右。

第四关：算力贵、用量不透明？探寻 Token 经济学

痛点：一次任务烧了多少钱说不清，长对话越到后面越贵

解法：反向选型、多层路由与 Talker-Reasoner 架构

#### 1. 建立模型选择矩阵

在企业实际部署中，全跑高档的 Opus 往往会造成极大的资金浪费。经过对真实业务复杂度分布的统计发现，多达 41% 的查询只是简单的 SQL 模板填空，只需要最便宜的 Haiku 模型即可胜任。

通过在 Harness 中配置三层路由机制：

Haiku (60%) → Sonnet (30%) → Opus (10%)

在保障产出质量的前提下，月账单可以从 48 万骤降至 12 万，综合成本下降达 65%~75%。

#### 2. 反向选型：在受限模型下选择“模式”

当预算和部署环境是硬约束，只能在本地部署开源便宜模型（如 Qwen-32B）时，该如何提升准确率？此时模式的选择才是设计的核心：

单次调用 Opus：价格高昂，面对边缘 case 依然可能出错。

Haiku 便宜模型 + 迭代自愈：让 Haiku 写代码，另一个 Haiku 做 Code Review，循环迭代 2 轮。其综合算力成本依然远低于单次调用顶级模型，但最终产出质量反而实现了反超。

#### 3. Talker-Reasoner 双系统

针对实时对话/Voice 等高频交互场景，长时间的思考延迟（如 reasoning 模型动辄等待 24 秒）会导致用户以为系统卡死。借鉴 Kahneman 双系统理论，可将架构重构为：

Talker：采用 200ms 的极速便宜模型（如 Haiku），负责立即回复用户、边聊边等。

Reasoner：采用慢速但聪明的模型（如 Opus/reasoning），在后台进行深度推理，将推理出的 belief state 源源不断地供给 Talker。

这样成功地把思考延迟在用户的感知里“藏”了起来。

第五关：约束与放手

痛点：AI 改对了 Bug，却顺手改了三处不该改的安全逻辑

解法：约束行动而不是约束思考，引入 HITL 人工审核

在治理 AI 的行动边界时，很多技术负责人会陷入一个误区：试图在 Prompt 里细化 AI 的每一个思考步骤。这反而会束缚模型的推理自由。

“约束限定的是行动的边界，而不是思考的自由。约束不是能力的保障，而是能力的容器。”

合理的工程约束应该放置在动作发生、产生副作用的地方：

只读/低爆炸半径操作（如查代码、看文档）：自动放行，不中断流程。

可写/中等影响操作：留痕放行，记录全链路的 Keyed log，事后支持完整 replay 溯源。

高爆炸半径/不可逆操作：强制触发阻断，并在控制台弹出 HITL 人工审核面板，人手点下确认后，AI 才能继续往下执行。

第六关：复杂的编排载体该如何抉择？

痛点：SubAgent、Skill、Workflow、Agent Team 概念混淆，不知道怎么组织

解法：一张四方图厘清边界

在 Harness 设计中，这四种编排载体并不是竞争关系，而是分别映射了现实世界中的四种工作实体：

Skill = 岗位操作手册：静态的、跨任务复用的知识包与 SOP 模板，代表了 Agent 的职业能力。

SubAgent = 专职员工：具备独立的、被隔离的上下文空间，执行完特定任务（如跑个测试、搜个关键字）后即刻销毁，实现防污染。

Workflow = SOP 流程图：将控制流显式、确定性地冻结在代码或脚本中，适用于多步、有着明确目标的长期自动化流程（如 nightly build 代码自动修复）。

Agent Team = 持续协作的虚拟团队：维持长期的、多人的对话交互，各个 Mate 角色拥有持久化 Session。

在成熟的企业项目中，这四者通常是互补、嵌套使用的，共同组合为一套业务流水线。

第七关：如何防止长任务状态漂移？

痛点：复杂的长任务跑着跑着就偏离了目标

解法：三平面分立架构 + 草稿纸看板

针对长任务中的目标漂移问题，可以引入三平面分立架构：

执行平面：Agent 实际执行任务的空间，包含代码修改、工具调用等。

监控平面：持续追踪执行进度与目标偏差，记录关键决策点。

干预平面：当检测到显著偏离时，触发回滚或人工介入。

同时，引入“草稿纸看板”机制——让 Agent 在独立的 scratchpad 中记录中间推理过程，而不是直接修改主上下文。这样即使某一步出错，也能从看板中恢复，避免整个上下文被污染。

动态工作流：让 Harness 自我进化

传统静态工作流需预先编写、通用性强却无法个性化。Anthropic 在 Claude Code 中上线了动态工作流功能——Claude 可以根据任务实时定制专属运行框架，支持保存、复用与分享。

动态工作流的核心模式

动态工作流执行一个包含特殊函数的 JavaScript 文件，这些函数帮助生成和协调子智能体。常见模式包括：

分类与行动：使用分类器智能体决定任务类型，然后路由到不同的智能体或行为。

分布并合成：将一个任务拆分为多个小步骤，在每个步骤上运行一个智能体，然后综合结果。

对抗验证：对于每个生成的智能体，运行一个独立的生成智能体，对抗性地验证其输出。

生成与过滤：生成多个想法，通过评分标准筛选，仅返回质量最高的。

锦标赛：让多个智能体用不同方法尝试同一任务，然后成对评估直到出现赢家。

循环直到完成：不断生成循环智能体，直到满足停止条件。

何时使用动态工作流

动态工作流特别适用于以下场景：

需要深度研究的任务（如 /deep-research）

大规模代码重构与迁移

多维度假设排查故障根因

海量简历/工单排序

产品命名、方案设计等多轮评比择优

但要注意，动态工作流通常消耗更多 Token，因此需要按需启用。对于简单编程任务，默认的 Claude Code 框架已经足够。

从 Agent Framework 到 Agent Platform

如果只看工具生态，一个明显的趋势是：Agent 正在从 Framework 走向 Platform。

Framework 解决的是局部抽象：agent、tool、memory、loop。

Platform 要解决的是完整生产系统：durable workspace、managed sandbox、identity、billing、observability、evaluation、governance、human handoff。

早期大家拼的是：谁能最快搭一个 Agent loop。现在拼的是：谁能让这个 loop 长期可靠运行。

所以 Agent 平台的竞争，不会只发生在模型层，也不会只发生在开发框架层，而会发生在整套 Harness 能力上。谁的执行环境更稳，谁的工具协议更清晰，谁的上下文更不容易漂，谁的 trace 更好用，谁的验证更接近真实任务，谁的权限和审计更可控——谁就更可能把 Agent 送进真实生产流程。

结语：少即是多

最后，一个重要的提醒：Agent 工程不是越复杂越好。

随着模型变强，Harness 也要重新评估。每一个 wrapper、reset、verifier、planner、memory rule、permission gate，本质上都代表一个假设：模型自己做不好，所以我在外面加一层控制。但如果模型能力变了，这些控制可能就不再必要，甚至会拖后腿。

Anthropic 的一个例子：在长时间应用开发任务中，某些 context reset 对旧模型有用，但对更强模型已经可以去掉，去掉之后成本下降，质量没有变差。

好 Harness 不只是会加控制，还要知道什么时候删控制。

FAQ

Agent Harness 和 Agent Framework 有什么区别？ Harness 是 Agent 内部的执行层，负责调用模型、处理工具调用、决定停止时机；Framework 是更上层的抽象，提供 agent、tool、memory 等组件的定义和组装方式。Harness 更关注运行时，Framework 更关注开发时。

动态工作流和静态工作流哪个更好？ 没有绝对优劣。静态工作流预先编写、通用性强，适合确定性的多步流程；动态工作流由 AI 现场定制，灵活度更高，适合探索性、非结构化的任务。动态工作流通常消耗更多 Token，需按需启用。

如何评估一个 Agent Harness 的好坏？ 不能只看最终成功率。需要从多个维度评估：结果正确性、执行路径合理性、Token 成本、延迟、失败原因可追溯性、安全合规性。建议采用 trace-native 评估，记录完整执行轨迹并逐层分析。

Harness 工程中最容易忽视的环节是什么？ 可观测性和治理。很多团队先把 Agent 跑起来，再补日志和权限。但在生产环境中，没有可观测性，Agent 失败了你不知道为什么；没有治理，Agent 成功了你也不一定敢用。这两个环节应该从一开始就纳入设计。

小团队如何快速上手 Harness 工程？ 建议从 Claude Code 等成熟工具入手，先掌握 CLAUDE.md 配置、Hooks 和 Skills 等基础功能。然后逐步引入 SubAgent 进行上下文隔离，最后根据业务需求定制动态工作流。不要一开始就追求完整的七层架构。

参考资源

AI Agent 与多智能体

Claude 模型与 Harness 工程

Workflow 与任务编排