# Harness 工程（二）：六层架构详解

> 本系列共三篇：
> 1. [[harness工程（一）：概念与来源]]
> 2. **六层架构详解**（本篇）：L1~L6 每层解决什么问题、怎么设计
> 3. [[harness工程（三）：落地实践指南]]

---

上一篇讲了 harness 工程的概念：假设模型的一切输出都不可信，用工程化手段约束它、验证它。这一篇把这个思路展开成一套可操作的架构——**六层 harness 架构**。

![harness 六层架构](https://developer.qcloudimg.com/http-save/yehe-10550024/bb4315e495f1aefd7f5ee3f6452e4abf.png)

六层各自回答一个核心问题：

| 层 | 名称 | 核心问题 |
| --- | --- | --- |
| L1 | 引导层 | AI 该遵守什么规则？该怎么做某类特定任务？ |
| L2 | 上下文层 | 模型在每一步推理时，应该看到什么信息？ |
| L3 | 规范层 | 什么算"对"？如何机械化地判定产出是否合格？ |
| L4 | 执行编排层 | 怎么把模型的思考变成稳定执行？（发动机） |
| L5 | 门禁执行层 | AI 的产出合不合格？不合格就拦住 |
| L6 | 可观测层 | Agent 跑了 50 步，到底发生了什么？ |

---

## L1 · 引导层（Guidance）

**核心问题：AI 该遵守什么规则？该怎么做某类特定任务？**

引导层是 agent 启动时注入的"世界观"：项目约定、编码风格、禁忌事项、特定任务的操作手册。典型载体是 AGENTS.md / CLAUDE.md、系统提示词、Skills 文件。

### 关键设计：AGENTS.md 是"地图"，不是"百科全书"

OpenAI 在实践中发现，"一个大而全的 AGENTS.md"方案会失败，原因有四：

1. **上下文是稀缺资源**：巨型指令文件挤占任务和代码的上下文空间，导致 agent 遗漏关键约束；
2. **过多指导等于没有指导**：所有内容都标记为"重要"时，agent 只能局部模式匹配，无法有目的地导航；
3. **立即腐化**：单体手册会变成陈旧规则的坟场，agent 无法判断哪些仍然有效，人类也停止维护；
4. **难以验证**：单一大文件无法做机械检查，漂移不可避免。

他们的方案是：**约 100 行的 AGENTS.md 作为入口地图**，知识库放在结构化的 `docs/` 目录里，作为唯一的系统记录：

```
AGENTS.md                  ← 注入上下文的简短地图，指向深层真相来源
ARCHITECTURE.md            ← 领域与包分层的顶层地图
docs/
├── design-docs/           ← 设计文档（含索引、核心信念）
├── exec-plans/            ← 执行计划（active/ 与 completed/ 分开）
├── generated/             ← 生成的内容（如 db-schema.md）
├── product-specs/         ← 产品规格
└── references/            ← 第三方库参考
```

这就是**渐进式披露（progressive disclosure）**：agent 从小而稳定的入口开始，被告知去哪里找下一步信息，而不是一开始就被信息淹没。

### 引导层的写作原则

- **每一行都对应一个 agent 犯过的真实错误**（Mitchell Hashimoto 的做法）。Ghostty 项目的 AGENTS.md 里每条规则都来自一次坏行为，写完后这些错误几乎全部消失；
- **写"怎么验证"，而不只是"怎么做"**——告诉 agent 做完后跑什么命令确认自己做对了；
- **不要写无法机械执行的空话**。"代码要优雅"是无效引导，"禁止在 Controller 层引用 Mapper"才是。

---

## L2 · 上下文层（Context）

**核心问题：模型在每一步推理时，应该看到什么信息？**

LangChain 有个论断：**"今天的 harness 在很大程度上是良好上下文工程的交付机制。"** 模型的推理质量几乎完全由它当下看到的上下文决定，而上下文是稀缺且会腐烂的资源。

### 三大敌人与对策

**1. 上下文腐烂（Context Rot）**：随着上下文窗口填满，模型推理和任务完成能力明显下降。对策：

- **压缩（Compaction）**：上下文接近上限时，智能地卸载和总结已有上下文，让 agent 能继续工作（否则 API 直接报错）；
- **工具输出卸载（Tool call offloading）**：超大工具输出只保留头尾 token，完整内容落盘到文件系统，需要时再去读——避免噪音污染上下文。

**2. 启动时信息过载**：装太多工具/MCP 服务反而拉低性能。对策：

- **Skills 渐进式披露**：启动时只加载技能的简介（front-matter），模型决定要用某个技能时才加载完整内容。

**3. 跨会话失忆**：模型每次会话从零开始。对策：

- **记忆文件机制**：AGENTS.md、progress.json 等文件在会话间持久化知识——agent 更新文件、harness 下次加载更新版，这是一种低成本的"持续学习"；
- **文件系统即工作台**：长任务产生数百万 token，文件系统把成果持久捕获下来，Git 让新会话能快速重建现场。

### 一句话总结

L2 层的设计目标是：**让宝贵的上下文窗口里装的始终是"对当下这一步最有用的信息"，别的一概不出现。**

---

## L3 · 规范层（Specification）

**核心问题：什么算"对"？如何机械化地判定产出是否合格？**

规范层把"好"的定义从人脑里搬进机器可执行的载体。四类规范：

| 规范类型 | 定义什么 | 落地为 | 谁来维护 |
| --- | --- | --- | --- |
| **代码规范** | 代码该怎么写 | ESLint rules、Checkstyle rules、tsconfig strict | 工程师 |
| **输出规范** | API 返回什么格式 / DTO、VO 怎么定义 | `Result<T>` 包装类 + TypeScript 类型定义 | 工程师 |
| **验收规范** | 什么算"功能完成" | 测试用例（单测 + 集成测试 + E2E 场景） | 工程师 + 业务 |
| **处理规范** | 业务流程怎么走 | Spec-Kit 的 spec/tasks 或 OpenSpec 的 proposal | 产品 + 工程 |

### 关键原则

- **写在 CLAUDE.md 里但不被 lint 执行的规范等于没写。** 规范层必须和门禁层（L5）形成闭环——这是整个六层架构里最重要的一条原则。Agent 不读规范会犯错，但 Agent 不可能不触发 lint。
- **验收规范要和 SDD（Spec-Driven Development）的 acceptance criteria 对齐**——"说清楚要做到什么程度"。
- **处理规范就是 SDD 的核心**：把"帮我做个功能"变成"用户是谁、核心动作是什么、非目标是什么、验收标准是什么"。

### 给规范加上"修复指令"

OpenAI 的一个精巧做法值得单独强调：

> 因为 lint 是自定义的，他们刻意把**错误消息写成给 agent 的修复指令**——agent 读到错误消息的同时，就获得了如何修复的明确指导。

对人类团队来说这些啰嗦的错误消息显得学究气，但对 agent 是**倍增器**：一旦编码进去，就在每一次运行中处处生效。

---

## L4 · 执行编排层（Orchestration）—— 发动机

**核心问题：怎么把模型的思考变成稳定执行？**

这是 harness 的发动机，包含让 agent "跑起来"并且"跑得稳"的全部机制：

| 组件 | 作用 | 场景示例 |
| --- | --- | --- |
| Agent Loop | 核心循环：模型调用 → 工具执行 → 结果回填 → 判断是否继续 | 所有 AI 任务执行的基础（ReAct 模式） |
| 模型路由 | 按任务类型选模型 | 文本→DeepSeek V4 Flash，编码→GLM-5.2，多模态→SeedDance 2.5 |
| 模型降级 | 主模型失败时自动切换 | GLM-5.2 超时/额度耗尽 → DeepSeek V4 Pro fallback |
| 子 Agent 派发 | 把大任务拆给多个子 Agent 并行 | 主 Agent 分配：前端 Agent + 后端 Agent 同时干活，各自隔离上下文 |
| 错误恢复 | 出错后怎么回退、重试、降级 | 文件编辑失败 → 回滚 worktree → 重试 |
| 推理预算分配 | 不同阶段的思考深度不同 | "高-中-高"三明治策略 |
| 会话间记忆 | 跨会话状态持久化 | 读写 progress.json，让下一次会话能接上 |

### 关键原则

**1. 模型路由和降级是这层的内部配置，不是独立的一层。** 它们是发动机的"换挡逻辑"——什么工况用什么挡位，换挡失败要有备用挡位。

**2. "高-中-高"三明治策略**：规划阶段用高推理（充分理解问题），实现阶段用中等推理（节省时间），验证阶段用高推理（捕获错误）。实验中该策略得分 66.5%，显著优于全程高推理的 53.9%——**思考预算花在规划和验证上，比花在执行上回报更高。**

**3. 防死循环**：以 LoopDetectionMiddleware 为代表——追踪每个文件的编辑次数，超过阈值就注入"考虑重新审视你的方案"，防止 agent 在同一个错误上来回打转。

**4. 长时程执行靠复合原语**：LangChain 总结的 Ralph Loop 模式——hook 拦截模型的退出尝试，在干净的上下文窗口里重新注入原始提示词，强制 agent 对照目标继续工作。文件系统让这可行：每次迭代以全新上下文启动，但读取上一次迭代落盘的状态。

---

## L5 · 门禁执行层（Enforcement）

**核心问题：AI 的产出合不合格？不合格就拦住，不许过。**

三层拦截体系，由近及远：

| 拦截层 | 什么时候 | 检查什么 | 拦截力度 |
| --- | --- | --- | --- |
| **Pre-commit Hook** | `git commit` 时 | 受保护文件、secret 泄露、新增依赖、lint、tsc、test | BLOCK（直接失败） |
| **CI 流水线** | push / PR 时 | 全量检查：Checkstyle + SpotBugs + JaCoCo + 架构约束 + 安全扫描 | FAIL（PR 不准合） |
| **Code Review** | 合入前 | 业务逻辑正确性、金额计算、权限校验、边界情况 | 人工判断 |

### 关键原则

**1. Linter 错误消息 = 修复指令**（OpenAI 做法）：不只是说"错了"，还要告诉 AI 怎么修。错误消息是被注入 agent 上下文的——它是 prompt 的一部分。

**2. 架构约束用机械强制**：Controller 不能引用 Mapper（分层违反），由脚本静态检查，不过就 FAIL。OpenAI 的固定分层是 `Types → Config → Repo → Service → Runtime → UI`，只允许向前依赖，横切关注点（认证、遥测、特性开关）只能通过单一的 Providers 接口进入。他们的体会是：

> "这种架构通常要等公司有几百名工程师才会建立。有了编码 agent，它是早期先决条件——约束是让速度不伴随架构漂移的前提。"

**3. 修正很便宜，等待很昂贵**（OpenAI 合并哲学）：在 agent 吞吐量远超人类注意力的系统里，阻塞式门禁越少越好——flaky test 用后续重跑解决，不无限阻塞；PR 生命周期保持短小。注意这个原则有前提：它适用于高吞吐、可快速回滚的环境，低吞吐场景照搬是不负责任的。

**4. 审查也可以 agent 化**：OpenAI 到后期几乎所有 code review 都转成了 agent 对 agent——指示 Codex 本地自审、请求云端额外 agent 审查、循环迭代直到所有 agent 审查者满意，人类只在需要判断时介入。

---

## L6 · 可观测层（Observability）

**核心问题：Agent 跑了 50 步，到底发生了什么？花了多少钱？哪里出了问题？**

| 组件 | 追踪什么 | 工具示例 |
| --- | --- | --- |
| **Trace** | 完整调用链：每一步调了什么模型、执行了什么工具、返回了什么 | LangSmith / OpenTelemetry |
| **Metrics** | 成功率、耗时分布、重试次数、token 消耗、错误类型分布 | Prometheus + Grafana |
| **Alerts** | 错误率飙升、成本超预算、Agent 陷入死循环时自动告警 | AlertManager / Slack 通知 |
| **Cost** | 每次/每天/每个模块的 AI 调用成本 | token × 单价统计 |
| **回滚机制** | 出问题能快速回退 | Git revert + worktree 隔离 |

### 关键原则

**1. 指标要让 Agent 自己也能看到**（OpenAI 做法）。Harness 在 agent 能看到"什么是好的"时改进最快。OpenAI 甚至给每个 worktree 配一套独立的临时可观测栈（Vector + Victoria Logs/Metrics），agent 可以用 LogQL 查日志、用 PromQL 查指标——任务完成后整套栈拆除。有了这些，"确保服务启动在 800ms 内完成"这种提示词才真正变得可执行。

**2. 度量指标体系分五类**：吞吐量、质量、人类注意力、Harness 健康、安全。注意"人类注意力"是一等指标——agent 系统的瓶颈往往不是模型，而是人类的审查带宽。

**3. 可观测性 = 自验证回路的一半**。写代码 → 跑测试 → 查日志 → 修错误，这个闭环要转起来，agent 必须能**观察**到自己行为的后果。截图、DOM 快照、日志查询、测试运行器，都是 agent 的"眼睛"。

---

## 六层之间的关系

一个典型的 agent 任务在六层间的流动：

![示例流程](https://developer.qcloudimg.com/http-save/yehe-10550024/111bf0ec74f2078f091c55507f4371f5.png)

- **L1+L2 决定 agent "想得对不对"**：规则前置、上下文精选；
- **L3 定义"什么算对"**：规范机械化、可判定；
- **L4 决定"跑得快不快、稳不稳"**：循环、路由、恢复；
- **L5 决定"错的能不能拦住"**：三层拦截，机械优先；
- **L6 决定"出了问题能不能看见"**：看得见才能改得掉。

上层（L1~L3）是**事前的约束**，下层（L5~L6）是**事后的防线**，L4 在中间把两者串成持续运转的系统。只做事前约束，错误会漏网；只做事后拦截，agent 会在反复失败中烧光预算。**六层闭环，缺一不可。**

下一篇：[[harness工程（三）：落地实践指南]]——不讲架构讲操作：在"开发 agent"和"日常使用"两条线上，这套东西具体怎么落地。


上一篇讲了 harness 工程的概念：假设模型的一切输出都不可信，用工程化手段约束它、验证它。这一篇把这个思路展开成一套可操作的架构——六层 harness 架构。

harness工程（二）：六层架构详解

L1~L6 每层解决什么问题、怎么设计

架构设计

编程语言

开发工具

Harness工程六层架构详解：L1引导层定义AI规则与操作手册，L2上下文层精选关键信息防腐烂，L3规范层将验收标准机械化，L4执行编排层实现稳定运行与降级恢复，L5门禁层三层拦截不合格产出，L6可观测层追踪全链路状态。核心原则：规范与门禁闭环，错误消息即修复指令，机械约束优先于人工审查。

上下文工程

集成测试

文件系统

代码解释

TypeScript 

LangChain

路由

Agent

2026上云采购 | AI焕新·智启新局

lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

harness工程（二）：六层架构详解-腾讯云开发者社区-腾讯云

harness工程（二）：六层架构详解

harness工程（二）：六层架构详解

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐