zhuyongxin
da18fdf4e1
- Add agent note: factory assembly, dual interceptors (model budget/token audit, tool five gates), use case loop shell, controlled stop recovery, dual-view projection - Mark agent domain complete in roadmap (all nine domains done)
Harness：先从一次诊断请求开始
这不是 Harness 的完整说明，而是一页入门导读。
第一次阅读时，不需要记组件名，不需要看状态枚举，也不需要理解所有边界。先回答一个问题：为什么 Diagnosis Agent 外面还需要一层 Harness？
1. 如果只有 Agent，会发生什么
假设用户问：
为什么支付服务在 10:00 到 10:10 大量超时？
Diagnosis Agent 会自己决定查什么、调用哪些 Tool、什么时候停止，并根据返回结果写出结论。这里有四个不能只靠 Prompt 解决的问题：
- 它可能查询过多，耗尽时间和 Token；
- Tool 原始结果可能包含敏感或超大内容，不能直接交给模型；
- 它引用了某条日志，不代表这条日志真的来自本次查询；
- 它写出了一个看似合理的根因，不代表证据足以支持这个根因。
这些都不是“诊断能力”问题，而是执行是否受控、结果是否可信的问题。Harness 就是为此存在的。
2. Harness 在一次请求中做了什么
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 只做三类事情：
- 执行前设边界：为本次请求建立身份、deadline、预算和取消能力。
- 执行中管事实：所有 Tool 经过统一入口，完整事实由系统保管，模型只看到安全、有限的内容。
- 发布前做验证：先验证引用，再判断证据是否支持结论；不满足条件就发布 Fallback，而不是让未经验证的结论出去。
Agent 仍然负责“问题的根因是什么”。Harness 不替 Agent 推理，它负责的是：让这次推理有边界、有证据、能停止。
3. 先建立这个最小心智模型
flowchart TB
A["Diagnosis Agent<br/>负责业务推理"]
H["Harness<br/>负责确定性控制"]
U["用户最终看到的结果"]
A -->|"提出 Tool 请求和诊断草稿"| H
H -->|"返回受控的 Tool 观察"| A
H -->|"验证通过后发布，失败则 Fallback"| U
到这里，第一次阅读就可以停下。只要能说清下面这句话，就已经抓住了主干：
Agent 决定如何诊断，Harness 决定这次诊断可以消耗什么、可以看到什么、何时必须停止，以及什么结果允许发布。
4. 需要时再往下读
不要按目录顺序阅读。遇到具体问题时，只进入对应文档：
| 当你想知道 | 再阅读 |
|---|---|
| 准备面试，想用一张图快速复习完整设计 | Harness 面试速查 |
| 想看一次 Run 的资源预算如何被门禁控制 | RunBudget 预算流程时序图 |
| 想复习终态检查与取消广播（checkActive / onCancel） | Harness 执行控制笔记 |
| 想复习重试机制（分类裁决 / 剩余超时 / 幂等性） | Retry 重试机制 |
| 想看当前组件学习进度与规划 | Harness 组件学习路线 |
| 想看 Harness 如何处理一次真实支付超时诊断 | 支付超时诊断案例 |
| 想知道这套设计如何从多 Agent 和 StateGraph 演进而来 | Harness 设计演进 |
| 想知道异常、停止、降级和最终状态如何对应 | Harness 失败图谱 |
| 想分清 ReactAgent loop 内外异常怎么走、和状态如何对应 | Loop 内外异常处理 |
| 想逐步认识 Harness 的各组组件 | 组件渐进式导读 |
| 为什么选这种控制边界，而不是工作流编排 | Harness 主设计 |
| 一次请求从开始到结束经历什么 | 生命周期与状态 |
| Tool 为什么要保存一份事实、给模型另一份视图 | Tool 双视图 |
| 如何阻止“引用是真的，但结论是错的” | 证据安全链 |
| Agent 为什么不会无限查询 | 信息增益停止 |
| 某个类属于哪里、负责什么 | 组件全景 |
| 某个名词或状态是什么意思 | Context 词典 |
如果准备系统学习，建议先读组件渐进式导读的四篇文章。每次只读一篇，读到“先记住这些”就可以停止。
“组件全景”和“Context”都是参考手册，不需要从头读，也不需要背。