Files

T

zhuyongxin 7844bcea40 docs(harness): annotate progress core classes and add code-level learning notes

- Annotate DiagnosisProgressTracker, HarnessToolInterceptor, DiagnosisProgressProjector,
  DiagnosisReleaseUseCase, ToolBoundary, ToolBoundaryResult, CanonicalToolInvocation
- Add progress code learning note: interceptor gates, tracker state machine,
  canonical lifecycle, execution gate, projection/release pipeline
- Update learning roadmap: progress marked as deeply learned, next is tool domain

2026-08-03 18:37:23 +08:00

11 KiB

Raw Blame History

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

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

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

0.1 目标

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

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

逐域学习：按学习主线顺序，一次一个职责域；进度见第 1 节。
讲解顺序固定：设计动机（为什么重试权归 Harness）→ 实现细节（真实代码）→ 面试话术。
用户会用自己的话复述理解（「我理解下...」）——AI 需逐条核对：基本正确就确认 + 精修表述；有偏差要明确指出并给出修正后的说法。
用户会追问（「为什么...」「如果...那...」）——AI 必须基于源码事实回答（src/main/java/com/superbiz/agent/harness），先读代码再答，不凭印象。
概念分不清时用户会要求回到底层概念（如「副作用幂等是什么」）——用类比 + 具体例子讲透再回到主线。
每学完一个主题沉淀成 mermaid 文档，放本目录 mvp/engineering/harness/（与已有笔记同风格：用途/图/表/面试话术/代码位置），并更新本路线图。
终端对话中不输出 mermaid（用户终端显示不了，用 ASCII 树/表格）；落地文档中用 mermaid。
回复用中文、不用 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（设计+代码双视角，含 ToolBoundary/canonical/Release 衔接）。当前停在「progress ✅ 已完成，下一步 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 / 状态枚举，防字符串漂移	⬜ 部分	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）、重复检测、饱和停止（预算之外的第二套停止机制）	✅ 深入	设计动机、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 生命周期 / 门禁 / 投影发布 / 易错点 / 面试话术	✅ 已沉淀（代码视角）

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

progress ✅ 已完成（设计+代码双视角笔记沉淀，代码核心类全部加注释）

下一个：tool（49 个文件，按四层理解：Boundary → Canonical → Projector → Adapter）
  —— 已在 progress 学习中顺带摸过 ToolBoundary / CanonicalInvocationStore / Adapter / Projector
  —— 正式系统学时按四层主线走，把投影器、JPA store、MySQL 沙箱补齐

之后顺序：
  guard（15 个文件：EvidenceGuard + SemanticGuard）
  release（6 个文件，小而关键：唯一发布点——已接触 DiagnosisReleaseUseCase）
  补 application（路由/执行器/SSE 收尾）和 audit（Trace 回放）
  最后状态流（RunState ↔ ReleaseOutcome ↔ SseOutcome 正交全景）

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

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

6. 参考资料索引

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

11 KiB Raw Blame History Unescape Escape