# Harness：先从一次诊断请求开始

这不是 Harness 的完整说明，而是一页入门导读。

第一次阅读时，不需要记组件名，不需要看状态枚举，也不需要理解所有边界。先回答一个问题：**为什么 Diagnosis Agent 外面还需要一层 Harness？**

## 1. 如果只有 Agent，会发生什么

假设用户问：

> 为什么支付服务在 10:00 到 10:10 大量超时？

Diagnosis Agent 会自己决定查什么、调用哪些 Tool、什么时候停止，并根据返回结果写出结论。这里有四个不能只靠 Prompt 解决的问题：

- 它可能查询过多，耗尽时间和 Token；
- Tool 原始结果可能包含敏感或超大内容，不能直接交给模型；
- 它引用了某条日志，不代表这条日志真的来自本次查询；
- 它写出了一个看似合理的根因，不代表证据足以支持这个根因。

这些都不是“诊断能力”问题，而是**执行是否受控、结果是否可信**的问题。Harness 就是为此存在的。

## 2. Harness 在一次请求中做了什么

```mermaid
flowchart LR
    Q["用户提出诊断问题"] --> R["给本次执行建立 Run<br/>限制时间和资源"]
    R --> A["Agent 分析问题<br/>选择 Tool"]
    A --> T["Harness 执行 Tool<br/>保存事实，只给 Agent 安全视图"]
    T --> A
    A --> D["Agent 写出诊断草稿"]
    D --> G["Harness 检查<br/>引用是否真实、证据是否支持结论"]
    G --> P["发布报告<br/>或安全地说明证据不足"]
```

顺着这条线看，Harness 只做三类事情：

1. **执行前设边界**：为本次请求建立身份、deadline、预算和取消能力。
2. **执行中管事实**：所有 Tool 经过统一入口，完整事实由系统保管，模型只看到安全、有限的内容。
3. **发布前做验证**：先验证引用，再判断证据是否支持结论；不满足条件就发布 Fallback，而不是让未经验证的结论出去。

Agent 仍然负责“问题的根因是什么”。Harness 不替 Agent 推理，它负责的是：**让这次推理有边界、有证据、能停止。**

## 3. 先建立这个最小心智模型

```mermaid
flowchart TB
    A["Diagnosis Agent<br/>负责业务推理"]
    H["Harness<br/>负责确定性控制"]
    U["用户最终看到的结果"]

    A -->|"提出 Tool 请求和诊断草稿"| H
    H -->|"返回受控的 Tool 观察"| A
    H -->|"验证通过后发布，失败则 Fallback"| U
```

到这里，第一次阅读就可以停下。只要能说清下面这句话，就已经抓住了主干：

> Agent 决定如何诊断，Harness 决定这次诊断可以消耗什么、可以看到什么、何时必须停止，以及什么结果允许发布。

## 4. 需要时再往下读

不要按目录顺序阅读。遇到具体问题时，只进入对应文档：

| 当你想知道 | 再阅读 |
|---|---|
| 准备面试，想用一张图快速复习完整设计 | [Harness 面试速查](Harness面试速查-一张图讲清设计.md) |
| 想看 Harness 如何处理一次真实支付超时诊断 | [支付超时诊断案例](案例-从一次支付超时诊断看Harness如何控制Agent.md) |
| 想知道这套设计如何从多 Agent 和 StateGraph 演进而来 | [Harness 设计演进](Harness设计演进-从多Agent编排到确定性控制边界.md) |
| 想知道异常、停止、降级和最终状态如何对应 | [Harness 失败图谱](Harness失败图谱-异常-停止-降级与终态.md) |
| 想分清 ReactAgent loop 内外异常怎么走、和状态如何对应 | [Loop 内外异常处理](Harness异常处理-Loop内外与状态流.md) |
| 想逐步认识 Harness 的各组组件 | [组件渐进式导读](components/README.md) |
| 为什么选这种控制边界，而不是工作流编排 | [Harness 主设计](Harness设计-非确定性Agent的确定性控制边界.md) |
| 一次请求从开始到结束经历什么 | [生命周期与状态](Harness生命周期与状态.md) |
| Tool 为什么要保存一份事实、给模型另一份视图 | [Tool 双视图](Harness-Tool双视图-从原始结果到可验证证据.md) |
| 如何阻止“引用是真的，但结论是错的” | [证据安全链](Harness证据安全链-从引用真实到结论可发布.md) |
| Agent 为什么不会无限查询 | [信息增益停止](Harness信息增益停止-让无证据诊断正常收敛.md) |
| 某个类属于哪里、负责什么 | [组件全景](Harness组件全景-职责-设计原因与边界.md) |
| 某个名词或状态是什么意思 | [Context 词典](CONTEXT.md) |

如果准备系统学习，建议先读组件渐进式导读的四篇文章。每次只读一篇，读到“先记住这些”就可以停止。

“组件全景”和“Context”都是参考手册，不需要从头读，也不需要背。