87 lines
5.3 KiB
Markdown
87 lines
5.3 KiB
Markdown
# 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) |
|
||
| 想看一次 Run 的资源预算如何被门禁控制 | [RunBudget 预算流程时序图](RunBudget预算流程-一次Run的资源门禁时序图.md) |
|
||
| 想复习终态检查与取消广播（checkActive / onCancel） | [Harness 执行控制笔记](Harness执行控制笔记-终态检查与取消广播.md) |
|
||
| 想复习重试机制（分类裁决 / 剩余超时 / 幂等性） | [Retry 重试机制](Retry重试机制-显式可计量的attempt循环.md) |
|
||
| 想看当前组件学习进度与规划 | [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”都是参考手册，不需要从头读，也不需要背。
|