zhuyongxin
074d1aa5a9
- Add MySQL sandbox note: three defense layers (semantic/connection/output), fail-closed validation, allowlist, parameterization, cancellation, redaction - Mark tool domain complete in roadmap; next: guard
12 KiB
12 KiB
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（设计+代码双视角）→ 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 / 状态枚举，防字符串漂移 | ⬜ 部分 | 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 只读沙箱 | ✅ 深入 | 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 对照 | ✅ 已沉淀 |
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. 下一步规划
tool 域 ✅ 完成（49 文件全注释 + 5 篇笔记：注册执行链路 / Tool 调用链 / RAG 检索体系 / MySQL 沙箱）
下一个：guard（15 个文件：EvidenceGuard + SemanticGuard）
—— 证据安全链核心：机械验引用真实性 + 语义判结论支持度
—— 面试高频：如何防止 Agent 编造证据
之后顺序：
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 的确定性控制边界 | 设计主文档（决策总表、不变量） |