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

Harness 组件学习路线（进度追踪）

用途：记录面试准备过程中已了解的 Harness 组件，标记进度，规划下一步。每次学完一个职责域后更新本表。 依据：mvp/engineering/harness/Harness组件全景-职责-设计原因与边界.md（10 个职责域、189 个文件）

0. 学习交流方式与衔接说明（新会话请先读本节）

0.1 目标

为面试准备深入理解 Harness：不只是知道有哪些组件，要能讲清「为什么这样设计」——每个设计点都有动机（问题）→ 决策 → 代价 → 面试话术。

0.2 交流模式（用户与 AI 的协作方式）

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 新会话衔接步骤

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 面试准备策略（学习目标）

学每个域的达标标准（不只是「看懂了」）：

1. 能 2 分钟讲清该域：为什么存在 → 核心机制 → 边界/代价
2. 能接住 3 个追问：动机追问（为什么这样）→ 细节追问（怎么实现）→ 边界追问（什么不做）
3. 有一句背得出的面试话术（每篇笔记都有「面试话术」章节）

每个域的面试讲法模板（固定叙事结构）：

① 动机：不这么做会出什么问题（问题驱动，不要先报组件名）
② 决策：选了什么方案、放弃了什么（对比）
③ 实现：关键机制 + 代码事实（一句话带过实现细节）
④ 边界：明确不做什么、代价是什么（诚实）
⑤ 话术：一段 30 秒可背诵的回答

高频追问地图（面试被问到时先答哪篇）：

面试问题	答案指向
什么是 Harness？30 秒讲清	面试速查 §1-2
为什么不用多 Agent？	设计演进
RunContext 为什么要显式传递？	执行控制笔记 §2
取消是强杀吗？	执行控制笔记 §6-8
预算和 Ledger 有什么区别？	RunBudget 时序图 §5
FALLBACK 算成功还是失败？	状态流（未沉淀，学完后补）
重试为什么归 Harness 管？	Retry 重试机制 §2
为什么 Agent/Tool 不重试？	Retry 重试机制 §9
如何防止 Agent 编造证据？	证据安全链（tool/guard 学完后补）

面试总复习路径（面试前一天）：

1. 30 秒电梯陈述 + 一张图（面试速查 §1-2）
2. 默画三张白板图：主链路、职责迁移、数据三层（面试速查 §2）
3. 过一遍六个易错点（面试速查 §8）
4. 2 分钟真实案例（支付超时）
5. 每篇笔记的「面试话术」章节快速背诵

1. 进度总览

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

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

2. 已产出笔记

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

3. 一次请求的完整学习主线

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. 下一步规划

主线九域全部 ✅（含 agent 域收尾）+ 面试五步复习 ✅（共沉淀 14 篇笔记）

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

可选深化（不阻塞面试）：
  1. audit 域深化：RagLookupAuditEnricher 检索审计明细（已覆盖大半）
  2. LLM Judge 设计（已沉淀：面试问答 + 追问应对）
  3. 整体架构补充（已沉淀：装配/入口/记忆体系/知识库写入）

5. 建议每次学完一个域后更新

1. 把本表"状态"从 ⬜ 改为 ✅/⬜
2. 在"已深入了解"列补充该域的关键类
3. 如产出笔记，加入"已产出笔记"表

6. 参考资料索引

文档	用途
Harness 面试速查-一张图讲清设计	面试主叙事（30 秒回答、三大决策、易错点）
Harness 组件全景-职责-设计原因与边界	全部组件的参考手册（需要查类时用）
components/README.md	组件渐进式导读入口（02-04 对应 progress/tool/guard+release）
Harness 设计-非确定性 Agent 的确定性控制边界	设计主文档（决策总表、不变量）