SuperBizAgent-java/mvp/engineering/harness/Harness组件学习路线-进度追踪.md

# 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（设计+代码双视角）→ tool 域（49 文件全注释 + 注册调用执行链路 + Tool 调用链旅程）→ RAG 检索体系（lookup_knowledge 后端：L0/多路召回+RRF/qualityScore/降级/契约/审计/离线评测，已闭环）。当前停在「tool 域只差 MySQL 沙箱线，下一步 tool 收尾」的位置。

### 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 / 状态枚举，防字符串漂移 | ✅ 深入 | 11 个状态枚举五层全景、四个正交轴（RunState⊥ReleaseOutcome、InvocationStatus⊥EvidenceStatus）、纵向映射链、SseOutcome 未接线发现 | [状态流笔记](Harness%20contract%20状态流学习笔记-11个状态枚举的正交全景.md) |
| `agent` | **框架 ReAct 接入**：拦截器把预算/审计/停止协议挂到框架循环上，不复制 loop | ✅ 深入 | 装配（Factory 粘合点）、双拦截器（Model：预算+Token 审计；Tool：五道门）、UseCase 循环外壳（字节/预算限制）、受控停止（异常栈捞回可控信号）、双视图投影（模型观察 vs 控制视图）、串行工具 | [agent 域学习笔记](Harness%20agent%20域学习笔记-从框架%20ReAct%20接入到受控停止.md) |
| `audit` | **可观测账本**：Trace 事件回放、Token 对账、metadata-only（不存敏感正文） | ✅ 深入 | trace 时序线（15 帧真实数据）、Ledger 分账、模型步审计 hook、RunConclusionExtractor、DiagnosisTraceService 三级回放 | [application+audit 笔记](Harness%20application+audit%20学习笔记-从%20Run%20编排到可回放审计.md) |
| `application` | **Run 应用所有者**：创建 Run / 路由意图 / 执行分支 / 持久化 / SSE 输出 | ✅ 深入 | 六步编排、取消句柄（CoreRunControl）、统一失败出口、多轮记忆有界化、PublishedResultPolicy 落库 | [application+audit 笔记](Harness%20application+audit%20学习笔记-从%20Run%20编排到可回放审计.md) |
| `guard` | **验证分离**：EvidenceGuard 机械验引用真实性 + SemanticGuard 隔离判结论支持度 | ✅ 深入 | 20 个违规码、三层校验（结构/验真/重读投影）、语义不变性、守卫模型受控调用、全栈衔接 | [证据安全链笔记](Harness%20证据安全链学习笔记-从收敛控制到唯一发布点.md) |
| `release` | **唯一发布点**：SUCCESS / FALLBACK 裁决，EvidenceRepair 只修引用，SafeFallback 确定性构造 | ✅ 深入 | 三分支决策树、fail closed、终态透传、EvidenceRepair 语义不变性、SafeFallbackFactory 五种降级 | [证据安全链笔记](Harness%20证据安全链学习笔记-从收敛控制到唯一发布点.md) |
| `tool` | **证据边界**：ToolBoundary 统一执行规则、canonical 保存真相、projector 有界投影、MySQL 只读沙箱 | ✅ 深入 | 49 文件全注释、Boundary/Contract/Projection/Store/Adapter/注册链、RAG 后端（L0/RRF/qualityScore/降级）、MySQL 沙箱（Validator/Executor/Projector 三层防线） | [tool 域注册调用执行链路](Harness%20tool%20域代码学习笔记-工具的注册调用与执行链路.md)、[Tool 调用链旅程](Harness%20Tool%20调用链-一次工具调用的完整旅程.md)、[RAG 检索体系](Harness%20RAG%20检索体系学习笔记-从%20query%20到可验证证据.md)、[MySQL 沙箱](Harness%20MySQL%20沙箱学习笔记-从%20SQL%20校验到脱敏投影.md) |
| `progress` | **收敛控制**：信息增益（GAINED/NO_GAIN）、重复检测、饱和停止（预算之外的第二套停止机制） | ✅ 深入 | 设计动机、Tracker 双计数/pending/软硬停止、拦截器五道门、canonical 生命周期、Projector 投影、Release 消费 | [代码学习笔记](Harness progress 代码学习笔记-从拦截器五道门到唯一发布点.md)（与[设计视角](Harness信息增益停止-让无证据诊断正常收敛.md)配套） |

图例：✅ 深入 = 已完整学透，能面试讲 2 分钟；⬜ 部分 = 接触过但没系统学；⬜ 空白 = 未开始

## 2. 已产出笔记

| 文档 | 内容 | 状态 |
|---|---|---|
| [Harness 执行控制笔记-终态检查与取消广播](Harness执行控制笔记-终态检查与取消广播.md) | RunContext / checkActive / 两个 CAS / 取消广播 / 打断机制 | ✅ 已沉淀 |
| [RunBudget 预算流程-一次 Run 的资源门禁时序图](RunBudget预算流程-一次Run的资源门禁时序图.md) | RunBudget 时序图 / 字段组件 / 异常终态 / 三要素 | ✅ 已沉淀 |
| [Retry 重试机制-显式可计量的 attempt 循环](Retry重试机制-显式可计量的attempt循环.md) | Retry 设计动机 / 分类裁决 / 剩余超时 / 幂等性 | ✅ 已沉淀 |
| [Harness 信息增益停止-让无证据诊断正常收敛](Harness信息增益停止-让无证据诊断正常收敛.md) | progress 设计视角：双停止机制 / 三方判断权 / 状态机 / 协议 / 真实问题 | ✅ 已沉淀（设计视角） |
| [Harness progress 代码学习笔记-从拦截器五道门到唯一发布点](Harness%20progress%20代码学习笔记-从拦截器五道门到唯一发布点.md) | progress 代码视角：类地图 / 五道门 / Tracker 状态机 / canonical 生命周期 / 门禁 / 投影发布 / 易错点 / 面试话术 | ✅ 已沉淀（代码视角） |
| [Harness tool 域代码学习笔记-工具的注册调用与执行链路](Harness%20tool%20域代码学习笔记-工具的注册调用与执行链路.md) | tool 域：装配/注册（bridge/callbacks）/调用/执行（ToolBoundary）/返回全链路 + 面试话术 | ✅ 已沉淀 |
| [Harness Tool 调用链-一次工具调用的完整旅程](Harness%20Tool%20调用链-一次工具调用的完整旅程.md) | 动态时序：模型决定 → 拦截器 → invoke → Adapter → ToolBoundary → 返回 → 模型观察 | ✅ 已沉淀 |
| [Harness RAG 检索体系学习笔记-从 query 到可验证证据](Harness%20RAG%20检索体系学习笔记-从%20query%20到可验证证据.md) | RAG 后端：L0/多路召回+RRF/qualityScore/去重判级/降级/契约/审计/离线评测/讨论沉淀 | ✅ 已沉淀 |
| [Harness MySQL 沙箱学习笔记-从 SQL 校验到脱敏投影](Harness%20MySQL%20沙箱学习笔记-从%20SQL%20校验到脱敏投影.md) | MySQL 工具：三层防线（语义/连接/输出）/白名单/参数化强制/取消联动/脱敏/与 RAG 对照 | ✅ 已沉淀 |
| [Harness 证据安全链学习笔记-从收敛控制到唯一发布点](Harness%20证据安全链学习笔记-从收敛控制到唯一发布点.md) | progress→guard→release 联动：双通道验证架构/六层状态流转与映射/关键字段来源与使用/设计要点/面试话术 | ✅ 已沉淀 |
| [Harness application+audit 学习笔记-从 Run 编排到可回放审计](Harness%20application+audit%20学习笔记-从%20Run%20编排到可回放审计.md) | application 六步编排/取消句柄/持久化策略；audit 域层次（trace 子体系/Ledger/审计表）；**audit vs trace 区别**（真实数据对照）/三级回放 | ✅ 已沉淀 |
| [Harness contract 状态流学习笔记-11个状态枚举的正交全景](Harness%20contract%20状态流学习笔记-11个状态枚举的正交全景.md) | 五层状态/四正交轴/纵向映射链/真实数据案例/面试叙事模板与追问应对 | ✅ 已沉淀 |
| [Harness 面试复习笔记-五步复习与白板图沉淀](Harness%20面试复习笔记-五步复习与白板图沉淀.md) | **详细版**：30 秒陈述展开/三张白板图/九域五段式讲法（动机→决策→实现→边界→话术）/六易错点带原因/追问应对大全/支付超时案例/纠正认知清单/面试 Checklist | ✅ 已沉淀 |
| [Harness agent 域学习笔记-从框架 ReAct 接入到受控停止](Harness%20agent%20域学习笔记-从框架%20ReAct%20接入到受控停止.md) | agent 域：装配（Factory 粘合点）/双拦截器（Model 预算+Token 审计、Tool 五道门）/UseCase 循环外壳/受控停止/双视图投影/串行工具 | ✅ 已沉淀 |

## 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
主线九域全部 ✅（含 agent 域收尾）+ 面试五步复习 ✅（共沉淀 14 篇笔记）

面试前一天建议：
  1. 重读「面试速查」§1-2 + §8（30 秒陈述 / 一张图 / 六易错点）
  2. 默画三张白板图（复习笔记 §3）
  3. 背诵每域 30 秒话术（复习笔记 §5）
  4. 过一遍纠正的认知清单（复习笔记 §6，最容易踩的坑）
  5. 2 分钟支付超时案例（复习笔记 §7）

可选深化（不阻塞面试）：
  1. audit 域深化：RagLookupAuditEnricher 检索审计明细
  2. 按需深入：模型步 hook 细节 / DiagnosisChatExecutor 恢复路径 / SSE 序列化
```

## 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) | 设计主文档（决策总表、不变量） |