147 lines
9.6 KiB
Markdown
147 lines
9.6 KiB
Markdown
# Harness 组件学习路线（进度追踪）
|
||
|
||
**用途**：记录面试准备过程中已了解的 Harness 组件，标记进度，规划下一步。每次学完一个职责域后更新本表。
|
||
**依据**：`mvp/engineering/harness/Harness组件全景-职责-设计原因与边界.md`（10 个职责域、189 个文件）
|
||
|
||
## 0. 学习交流方式与衔接说明（新会话请先读本节）
|
||
|
||
### 0.1 目标
|
||
|
||
为**面试准备**深入理解 Harness：不只是知道有哪些组件，要能讲清「为什么这样设计」——每个设计点都有动机（问题）→ 决策 → 代价 → 面试话术。
|
||
|
||
### 0.2 交流模式（用户与 AI 的协作方式）
|
||
|
||
1. **逐域学习**：按[学习主线](#3-一次请求的完整学习主线)顺序，一次一个职责域；进度见[第 1 节](#1-进度总览)。
|
||
2. **讲解顺序固定**：设计动机（为什么重试权归 Harness）→ 实现细节（真实代码）→ 面试话术。
|
||
3. **用户会用自己的话复述理解**（「我理解下...」）——AI 需逐条核对：基本正确就确认 + 精修表述；有偏差要明确指出并给出修正后的说法。
|
||
4. **用户会追问**（「为什么...」「如果...那...」）——AI 必须基于源码事实回答（`src/main/java/com/superbiz/agent/harness`），先读代码再答，不凭印象。
|
||
5. **概念分不清时用户会要求回到底层概念**（如「副作用幂等是什么」）——用类比 + 具体例子讲透再回到主线。
|
||
6. **每学完一个主题沉淀成 mermaid 文档**，放本目录 `mvp/engineering/harness/`（与已有笔记同风格：用途/图/表/面试话术/代码位置），并更新本路线图。
|
||
7. **终端对话中不输出 mermaid**（用户终端显示不了，用 ASCII 树/表格）；落地文档中用 mermaid。
|
||
8. 回复用中文、不用 emoji、重要内容（代码/表/推理）不截断。
|
||
|
||
### 0.3 新会话衔接步骤
|
||
|
||
```text
|
||
1. 读本路线图：第 0 节（交流方式）+ 第 1 节（进度）+ 第 4 节（下一步）
|
||
2. 读「已产出笔记」里的文档，了解已学内容的深度（尤其是 core / retry）
|
||
3. 从第 4 节「下一步规划」继续，保持 0.2 的交流模式
|
||
```
|
||
|
||
### 0.4 当前会话的起始上下文（供追溯）
|
||
|
||
本次学习从 Harness 入口文档开始，已完整走过：入口导读 → 面试速查 → RunContext → 执行控制（budget/cancel/lifecycle/checkActive）→ 取消广播与打断机制 → RunBudget 深挖 → retry（设计+实现+超时+幂等性）→ 状态流预备（枚举归属）。当前停在「执行控制面已闭环，下一步 progress」的位置。
|
||
|
||
### 0.5 面试准备策略（学习目标）
|
||
|
||
**学每个域的达标标准**（不只是「看懂了」）：
|
||
|
||
```text
|
||
1. 能 2 分钟讲清该域：为什么存在 → 核心机制 → 边界/代价
|
||
2. 能接住 3 个追问：动机追问（为什么这样）→ 细节追问（怎么实现）→ 边界追问（什么不做）
|
||
3. 有一句背得出的面试话术（每篇笔记都有「面试话术」章节）
|
||
```
|
||
|
||
**每个域的面试讲法模板（固定叙事结构）**：
|
||
|
||
```text
|
||
① 动机：不这么做会出什么问题（问题驱动，不要先报组件名）
|
||
② 决策：选了什么方案、放弃了什么（对比）
|
||
③ 实现：关键机制 + 代码事实（一句话带过实现细节）
|
||
④ 边界：明确不做什么、代价是什么（诚实）
|
||
⑤ 话术：一段 30 秒可背诵的回答
|
||
```
|
||
|
||
**高频追问地图**（面试被问到时先答哪篇）：
|
||
|
||
| 面试问题 | 答案指向 |
|
||
|---|---|
|
||
| 什么是 Harness？30 秒讲清 | [面试速查](Harness面试速查-一张图讲清设计.md) §1-2 |
|
||
| 为什么不用多 Agent？ | [设计演进](Harness设计演进-从多Agent编排到确定性控制边界.md) |
|
||
| RunContext 为什么要显式传递？ | [执行控制笔记](Harness执行控制笔记-终态检查与取消广播.md) §2 |
|
||
| 取消是强杀吗？ | [执行控制笔记](Harness执行控制笔记-终态检查与取消广播.md) §6-8 |
|
||
| 预算和 Ledger 有什么区别？ | [RunBudget 时序图](RunBudget预算流程-一次Run的资源门禁时序图.md) §5 |
|
||
| FALLBACK 算成功还是失败？ | 状态流（未沉淀，学完后补） |
|
||
| 重试为什么归 Harness 管？ | [Retry 重试机制](Retry重试机制-显式可计量的attempt循环.md) §2 |
|
||
| 为什么 Agent/Tool 不重试？ | [Retry 重试机制](Retry重试机制-显式可计量的attempt循环.md) §9 |
|
||
| 如何防止 Agent 编造证据？ | 证据安全链（tool/guard 学完后补） |
|
||
|
||
**面试总复习路径**（面试前一天）：
|
||
|
||
```text
|
||
1. 30 秒电梯陈述 + 一张图（面试速查 §1-2）
|
||
2. 默画三张白板图：主链路、职责迁移、数据三层（面试速查 §2）
|
||
3. 过一遍六个易错点（面试速查 §8）
|
||
4. 2 分钟真实案例（支付超时）
|
||
5. 每篇笔记的「面试话术」章节快速背诵
|
||
```
|
||
|
||
## 1. 进度总览
|
||
|
||
| 职责域 | 作用摘要 | 状态 | 已深入了解 | 对应文档 |
|
||
|---|---|---|---|---|
|
||
| `core` | **执行控制**：身份 / deadline / 预算 / 取消 / 唯一终态，checkActive 三道闸 | ✅ 深入 | RunContext、budget、cancel、lifecycle、checkActive、termination | [执行控制笔记](Harness执行控制笔记-终态检查与取消广播.md)、[RunBudget 时序图](RunBudget预算流程-一次Run的资源门禁时序图.md) |
|
||
| `retry` | **显式可计量重试**：分类裁决（技术/业务）、次数/时间/成本三重封顶、attempt 可审计 | ✅ 深入 | 设计动机、分类裁决、剩余超时、幂等性、SDK 关闭 | [Retry 重试机制](Retry重试机制-显式可计量的attempt循环.md) |
|
||
| `contract` | **跨层类型化语言**：Draft / PublishedResult / SafeFallback / 状态枚举，防字符串漂移 | ⬜ 部分 | RunState / ReleaseOutcome / SseOutcome / PublishedResult（只摸过枚举） | 状态流（未系统学） |
|
||
| `agent` | **框架 ReAct 接入**：拦截器把预算/审计/停止协议挂到框架循环上，不复制 loop | ⬜ 部分 | HarnessModelInterceptor（预算/Token 记账） | — |
|
||
| `audit` | **可观测账本**：Trace 事件回放、Token 对账、metadata-only（不存敏感正文） | ⬜ 部分 | ModelCallLedger / ModelCallAuditor | — |
|
||
| `application` | **Run 应用所有者**：创建 Run / 路由意图 / 执行分支 / 持久化 / SSE 输出 | ⬜ 部分 | ChatApplicationUseCase 入口（cancel 链路） | — |
|
||
| `guard` | **验证分离**：EvidenceGuard 机械验引用真实性 + SemanticGuard 隔离判结论支持度 | ⬜ 部分 | GuardModelCall（预算/超时/取消订阅） | — |
|
||
| `release` | **唯一发布点**：SUCCESS / FALLBACK 裁决，EvidenceRepair 只修引用，SafeFallback 确定性构造 | ⬜ 部分 | DiagnosisReleaseResult（结果类型） | — |
|
||
| `tool` | **证据边界**：ToolBoundary 统一执行规则、canonical 保存真相、projector 有界投影、MySQL 只读沙箱 | ⬜ 空白 | JdbcMysqlReadOnlyExecutor（取消订阅） | — |
|
||
| `progress` | **收敛控制**：信息增益（GAINED/NO_GAIN）、重复检测、饱和停止（预算之外的第二套停止机制） | ⬜ 空白 | — | — |
|
||
|
||
图例：✅ 深入 = 已完整学透，能面试讲 2 分钟；⬜ 部分 = 接触过但没系统学；⬜ 空白 = 未开始
|
||
|
||
## 2. 已产出笔记
|
||
|
||
| 文档 | 内容 | 状态 |
|
||
|---|---|---|
|
||
| [Harness 执行控制笔记-终态检查与取消广播](Harness执行控制笔记-终态检查与取消广播.md) | RunContext / checkActive / 两个 CAS / 取消广播 / 打断机制 | ✅ 已沉淀 |
|
||
| [RunBudget 预算流程-一次 Run 的资源门禁时序图](RunBudget预算流程-一次Run的资源门禁时序图.md) | RunBudget 时序图 / 字段组件 / 异常终态 / 三要素 | ✅ 已沉淀 |
|
||
| [Retry 重试机制-显式可计量的 attempt 循环](Retry重试机制-显式可计量的attempt循环.md) | Retry 设计动机 / 分类裁决 / 剩余超时 / 幂等性 | ✅ 已沉淀 |
|
||
|
||
## 3. 一次请求的完整学习主线
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A["core<br/>执行控制 ✅"] --> B["retry<br/>重试 ✅"]
|
||
B --> C["progress<br/>信息增益 ⬜"]
|
||
C --> D["tool<br/>事实边界 ⬜"]
|
||
D --> E["guard<br/>验证 ⬜"]
|
||
E --> F["release<br/>发布 ⬜"]
|
||
F --> G["application + audit<br/>收尾 ⬜"]
|
||
G --> H["contract<br/>类型化语言 ⬜"]
|
||
```
|
||
|
||
## 4. 下一步规划
|
||
|
||
```text
|
||
下一个：progress（信息增益停止）——14 个文件，小而独立
|
||
和刚学完的预算组成"双停止机制"：预算管"能不能花"，信息增益管"继续查有没有价值"
|
||
|
||
之后顺序：
|
||
tool（49 个文件，按四层理解：Boundary → Canonical → Projector → Adapter）
|
||
guard（15 个文件：EvidenceGuard + SemanticGuard）
|
||
release（6 个文件，小而关键：唯一发布点）
|
||
补 application（路由/执行器/SSE 收尾）和 audit（Trace 回放）
|
||
最后状态流（RunState ↔ ReleaseOutcome ↔ SseOutcome 正交全景）
|
||
```
|
||
|
||
## 5. 建议每次学完一个域后更新
|
||
|
||
```text
|
||
1. 把本表"状态"从 ⬜ 改为 ✅/⬜
|
||
2. 在"已深入了解"列补充该域的关键类
|
||
3. 如产出笔记，加入"已产出笔记"表
|
||
```
|
||
|
||
## 6. 参考资料索引
|
||
|
||
| 文档 | 用途 |
|
||
|---|---|
|
||
| [Harness 面试速查-一张图讲清设计](Harness面试速查-一张图讲清设计.md) | 面试主叙事（30 秒回答、三大决策、易错点） |
|
||
| [Harness 组件全景-职责-设计原因与边界](Harness组件全景-职责-设计原因与边界.md) | 全部组件的参考手册（需要查类时用） |
|
||
| [components/README.md](components/README.md) | 组件渐进式导读入口（02-04 对应 progress/tool/guard+release） |
|
||
| [Harness 设计-非确定性 Agent 的确定性控制边界](Harness设计-非确定性Agent的确定性控制边界.md) | 设计主文档（决策总表、不变量） |
|