让 Agent 运行时可见:learn-harness-engineering 第 11 课「可观测性必须内置于 Harness」的完整实践指南
让 Agent 运行时可见:learn-harness-engineering 第 11 课「可观测性必须内置于 Harness」的完整实践指南
本课是 learn-harness-engineering 课程体系中关于"运行时可观测性"的核心一讲,对应仓库中的 第 11 课原文。当 Agent 跑完 20 分钟、改完一堆文件却只留下一句"不确定,可能是 timing 问题"时,问题往往不在 Agent 能力,而在 harness 没有提供足够的可观测性。读完本文,你将掌握系统层(runtime signals)与过程层(sprint contract、evaluation rubric)双层可观测性的设计方法,并能结合仓库中的 runtime-logger.ts 演示代码 与 Project 06 全栈落地案例,把 Agent 调试从"盲猜"变成"确定性查找"。
课程背景:没有可观测性时发生了什么
你让一个 Agent 实现某个功能。它运行了 20 分钟,修改了大量文件,然后告诉你:"完成了,但有两个测试挂了。"你问为什么挂,它回答:"不太确定,可能是 timing 问题。"你问哪些关键路径被改动了,它说:"让我再看看代码……"
这不是 Agent 能力不足,而是你的 harness 没有提供足够的可观测性。没有可观测性,Agent 在不确定性下做决策,评估变成主观判断,重试变成盲目试错。 OpenAI 和 Anthropic 都把可靠性当作"证据问题"来处理:harness 必须以能指导下一步决策的方式,暴露运行时行为与评估信号。
核心概念:一套可观测性的共同语言
本课定义了六组互相咬合的核心概念,是后续所有实践的地基:
- 运行时可观测性(Runtime observability):系统级信号,包括日志、trace、进程事件、health check。回答的问题是"系统做了什么"。
- 过程可观测性(Process observability):对 harness 决策产物的可见性,例如计划(plan)、评分卡(rubric)、验收标准(acceptance criteria)。回答的问题是"这个改动为什么应该被接受"。
- 任务 trace(Task trace):从开始到结束的完整决策路径记录,类比分布式系统中的请求 tracing。Agent 的每一步都连同其上下文被记录下来。
- Sprint contract:编码前由各方短期协商的协议,明确范围、验证标准与排除项。它是过程可观测性的核心工具。
- 评估评分卡(Evaluation rubric):把质量评估从主观判断转化为基于证据的结构化打分,使不同评估者对同一输出产生相似结论。
- 分层可观测性(Layered observability):系统层与过程层可观测性必须一起设计、互相支撑——运行时信号解释"行为",过程工件解释"意图"。
分层可观测性:两条信息流如何汇合
原课给出了核心工作流图,它同时是本章的骨架:先写任务契约,generator 执行并采集运行时信号,reviewer 依据契约逐点复核,最终 verdict 指出失败项与修复位置,再反馈回 generator 形成闭环。
flowchart LR
Contract["Escribir primero la tarea<br/>qué cambiar / qué no cambiar / criterios de aprobación"] --> Generator["Generator"]
Generator --> Signals["Recoger logs, trazas<br/>y health checks durante la ejecución"]
Contract --> Review["Revisar el resultado punto por punto<br/>comportamiento / tests / límites"]
Signals --> Review
Review --> Verdict["Señalar el check fallido<br/>y dónde corregirlo"]
Verdict --> Generator
可以把它翻译成实现语言:契约(sprint contract)先于编码存在,它同时喂养 Generator(做什么)与 Reviewer(按什么标准验收);运行时信号(logs/traces/health checks)在 Generator 执行期间被 harness 自动采集并旁路给 Reviewer;Reviewer 输出带证据的判决,失败项与修复位置作为下一轮 Generator 的输入。 两层信号在这个循环里缺一不可:只有契约没有运行时信号,验收就是纸面审查;只有信号没有契约,信号就无法被解读成"该不该接受"。
为什么可观测性必须内置于 harness
无观测的四个系统性代价
当一个 harness 没有可观测性时,会系统性出现四类问题:
- 无法区分"正确"与"看起来正确":一段代码在 code review 中可能无懈可击——语法正确、逻辑合理,但运行时某个 edge case 在特定输入下产生错误结果。只有运行时 trace 能暴露真实执行路径偏离了预期。
- 评估变成玄学:没有评分卡与验收标准,评估者(无论人类还是 Agent)都依赖隐式假设。同一输出可能得到截然不同的评价,质量无法复现。
- 重试变成盲猜:Agent 不知道失败原因时,重试方向是随机的——可能修一堆无关代码,却忽略根因。每一次盲目重试都在烧 token 和时间。
- 交接时的信息悬崖:把未完成的工作交给下一 session 时,缺乏可观测性意味着要从零开始诊断系统状态。Anthropic 的观察显示,这种重复诊断可能消耗整个 session 总时长的 30%–50%。
一个贴近现实的场景:planner-generator-evaluator 跑"给应用加 dark mode"
原课用一个三角色 workflow 做了对照实验,值得完整复述:
无可观测性:planner 产出模糊描述 → generator 基于模糊描述实现 dark mode,与 planner 的隐式期望不符 → evaluator 按自己的隐式标准拒绝,却说不清哪里不对 → generator 盲目重试。循环重复 3–4 次,耗时约 45 分钟,产出"勉强可用"的结果。
完整可观测性:planner 产出 sprint contract,列出要改的组件、验证标准与排除项 → generator 按契约实现 → 运行时可观测性记录每个组件如何加载和应用样式 → evaluator 用带证据的评分卡按维度打分。一次迭代即可产出高质量结果,耗时约 15 分钟。
效率差 3 倍,唯一变量就是可观测性。
为什么 Agent 自己解决不了
你可能会想:"Agent 不能自己打日志吗?"原课给出了三个反驳:
- Agent 不知道自己不知道什么——它不会记录自己没意识到需要的信号;
- 日志格式不一致——不同 session 用不同格式,无法做系统性分析;
- 过程可观测性不是日志能解决的——sprint contract 和评分卡是结构化工件,必须由 harness 层面提供支撑。
如何正确落地:四步实践
1. 把运行时信号采集集成进 harness,而不是依赖 Agent 自觉
harness 应自动采集以下五类信号,而不是指望 Agent 自己 print:
- 应用生命周期:startup、ready、running、shutdown 各状态;
- 函数路径执行:关键路径的入口点、checkpoint、出口记录;
- 数据流:组件之间流转的数据记录;
- 资源使用:异常模式,例如内存无限增长;
- 错误与异常:完整上下文,而不是只有错误消息。
仓库里恰好有一个可直接运行的结构化日志演示:runtime-logger.ts。它模拟了一个文档 Q&A 流水线(DocumentLoader → ChunkIndexer → QueryRouter → RetrievalEngine → AnswerGenerator),并人为埋入了一个故障:RetrievalEngine 因"query embedding dim=768 vs index embedding dim=1536"维度不匹配返回 0 条结果,而 AnswerGenerator 并不崩溃、只是产出一条坏答案——这正是"看起来成功、实则失败"的经典形态。
运行方式(README 中注明使用 npx tsx):
npx tsx docs/es/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts
演示对比了两种输出:
- Ad-hoc 日志:
RetrievalEngine: something went wrong——只能告诉你"出了点事",没有维度、没有输入输出、没有关联 ID,诊断完全靠猜(源码见 printAdHocLog); - 结构化 JSON 日志:每条记录带
timestamp、level、component、action、durationMs、input、output、error、correlationId(类型定义见 StructuredLogEntry),脚本还能自动完成三类诊断——错误定位、延迟尖峰检测、空输出级联检测(见 diagnoseFromStructured)。
该演示的结论被脚本直接打印出来:结构化日志让"根因可识别、输入输出可追溯、跨步骤可关联、机器可解析"全部为 Yes,诊断时间从"人工数分钟"降为"自动数秒"——调试从猜测变成了确定性查找。
2. 实施 Sprint Contract:编码前把"验收"谈清楚
原课给出了一个可直接套用的 dark mode 契约模板,内容如下:
# Sprint Contract: Dark Mode Support
## Scope
- Modify the theme toggle component
- Update global CSS variables
- Add dark mode tests
## Verification Standards
- Visual regression tests pass for each component
- Main flow end-to-end tests pass
- No flash of unstyled content (FOUC)
## Exclusions
- Not handling print styles
- Not handling third-party component dark mode
三个区块分别回答三个问题:Scope(做什么)、Verification Standards(做到什么程度算完成)、Exclusions(明确不做什么)。Exclusions 尤其重要——它把"以后再说"从隐式期望变成显式契约,避免 evaluator 拿排除项当缺陷打回。
仓库的课程代码目录里还提供了一个更精炼的示例 sprint-contract.md:它把目标定为"给 grounded Q&A 结果加可见引文",并把 Definition of Done 拆成四条可逐条勾选的验收条件(用户提问 → 应用返回答案 → 显示至少一条引文 → 点击引文跳转到文档中的源位置)。注意它的写法:"Hecho significa"("完成"意味着)之后每一条都是可验证的端到端行为,而不是含糊的形容词——这正是契约与需求文档的分界线。
3. 建立评估评分卡:把"好不好"变成可打分
原课的评分卡模板把"是否 OK"转化为量化评分:
# Scoring Rubric
| Dimension | A | B | C | D |
|---|---|---|---|---|
| Code correctness | All tests pass | Main flow passes | Partial pass | Build fails |
| Architecture compliance | Fully compliant | Minor deviations | Obvious deviations | Serious violations |
| Test coverage | Main + edge cases | Main flow only | Only skeleton | No tests |
关键设计是每格都写可观察的证据,而不是"好/中/差":A 档意味着"所有测试通过",D 档意味着"构建失败",评估者只需对照事实落格。仓库中的 evaluator-rubric.md 则是 1–5 分制变体,四个维度为:Fundamentación(回答是否明确关联到导入的源文档)、Calidad de citación(引文是否可见且具体)、Funcionalidad(用户能否走完问答流程)、Coherencia del producto(整体工作流是否自洽)。
评分卡在 Project 06 中有完整的生产级实例:projects/project-06/solution/evaluator-rubric.md。它把 15 个维度(构建编译、窗口启动、文档导入、文本索引、grounded Q&A、会话历史、反馈采集、结构化日志、干净状态重置、持久化、状态栏、基准脚本、清理扫描器、harness 完整度等)逐一打 1–5 分并附 Notes 证据,最终给出 5.0/5 总分——每个分数后面都跟着可复核的事实描述,这正是"评估可复现"的工程化形态。
4. 用 OpenTelemetry 标准化:让 trace 可对接 Jaeger/Zipkin
原课的建议是:为每个 harness session 建一条 trace,为每个 task 建一个 span,为每个验证步骤建 sub-span,并用标准属性标注关键信息,使可观测性数据能对接 Jaeger、Zipkin 等既有工具。
仓库的 runtime-logger.ts 虽然没引入完整 OTel SDK,但已经体现了两个关键实践:全局 correlationId(req- + 随机串,贯穿整条流水线的所有日志,把跨组件步骤串成一条可追踪的任务链),以及语义化的结构化字段(component/action/durationMs/input/output/error),这两点正是 OTel semantic conventions 的雏形。真实项目中可以把 correlationId 演进为 W3C traceparent,把 component.action 演进为 service.name + span.name,即可无缝接入 OTel Collector。
仓库里的全栈落地佐证:Project 06 如何把本课变成可运行系统
如果说 code/ 目录是"最小演示",那么 Project 06: Runtime Observability and Debugging(Capstone) 就是把本课理论做成完整产品的收官项目:同一份产品代码,一套被刻意削弱的 starter(只有基础 AGENTS.md,没有 feature_list.json、session handoff、clean-state checklist),一套满载 harness 工件的 solution(9 个顶层 harness 文件 + 3 份文档 + benchmark/cleanup 脚本),对比"弱 harness"与"强 harness"下的可观测性差距。README 中明确它关联的两课正是 Lecture 11(本课英文版) 与 Lecture 12: 每个 session 必须留下干净状态。
Solution 中的核心实现与运行时信号采集一一对应:
- 结构化日志模块 logger.ts:定义
DEBUG/INFO/WARN/ERROR四级(见 LogLevel),每条日志输出为单行 JSON,含timestamp、level、service、message、data(见 LogEntry);forService()为每个服务创建带服务标签的子 logger(见 forService),最小日志级别由process.env.LOG_LEVEL控制(见 logger 单例)——这直接落实了"系统级信号由 harness 统一采集,而非 Agent 随意 print"。 - QA 服务 qa-service.ts:展示信号如何覆盖关键路径——
ask()在入口记录问题与长度(见 qa-service.ts 第 73 行)、检索命中时逐条记录 citation 分数(见 第 112-116 行)、无索引时记录 WARN(见 第 119 行)、返回前记录 confidence/citationCount/answerLength/durationMs(见 第 136-141 行)——每一段都有可查的耗时与上下文,正是"函数路径执行 + 数据流 + 错误上下文"三类信号的代码级体现。 - 基准脚本 benchmark.sh:把可观测性外推到"可测量的验收"——对导入(≥3 个文件)、索引(≥5 个 chunk)、查询(5 条预置 query)、数据完整性(文件尺寸校验)四类任务计时并判 PASS/FAIL,产出结构化汇总,让"质量"有了数字基准。
- 质量文档 quality-document.md:记录结构化日志覆盖了所有 IPC channel 调用(导入记录 documentId/filename/sizeBytes、索引记录 chunkCount/durationMs/throughput、Q&A 记录 confidence/citationCount/answerLength/durationMs、clean state reset 以 WARN 级记录),并用 sample data 基准数据佐证各操作耗时——这是"可观测性 → 可评估 → 可复现"链条的最终产物。
实战案例对比:同一任务,两种结局
原课的收尾案例完整对照如下:
不可观测版本:3–4 轮盲目重试,耗时 45 分钟,结果勉强可用。evaluator 只能说"感觉不对劲"却无法说清原因,generator 在错误方向上反复消耗时间。
完全可观测版本:
- sprint contract 提前澄清范围、标准与排除项;
- 运行时 trace 记录每个组件加载样式的全过程;
- 评分卡给出按维度的结构化评估;
- 一次迭代产出高质量结果,耗时 15 分钟。
结论是 3 倍效率提升、更稳定的质量与可复现的评估。需要注意,这个 3x 与 30%–50% 数据来自课程/业界观察(Anthropic 的观察),属于课程陈述的参考数据,落地时应以自己 harness 的实测为准——仓库的 benchmark.sh 正是为此而生的测量工具。
关键要点
- 可观测性是 harness 的架构属性,不是最后补上去的功能——它决定 Agent 的每一步决策是否有证据支撑。
- 两层可观测性缺一不可:运行时信号回答"发生了什么",过程工件回答"为什么这么做"。
- Sprint contract 提前对齐,避免 generator 造出 evaluator 因可预见理由而拒绝的东西。
- 评分卡让评估可复现,不同评估者对同一输出给出相近分数。
- 可观测性缺失会让 session 时长的 30%–50% 浪费在重复诊断上。
练习建议
- 可观测性差距分析(Gap analysis):审计你现有 harness 的系统层与过程层,找出用现有信号无法区分的状态,为它们设计新信号。
- Sprint contract 实践:为一项真实任务写一份契约,让 Agent 分别在有/无契约下执行,对比效率与质量。
- 任务 trace 构建:用 OpenTelemetry 语义约定为 Agent 在一整次编码任务中的每一步打点记录,分析哪些决策点信号不足。
延伸阅读可关注课程同源的 第 12 课:为什么每个 session 必须留下干净状态(与交接信息悬崖直接相关)、第 13 课 loop-engineering 与 第 14 课 graph-engineering(把本课的循环与证据链进一步结构化为图模型);原课推荐阅读的 Observability Engineering、Google Dapper(分布式 tracing 先驱实践)、Anthropic 的 Harness Design 一文以及 Google SRE Book,均可在对应官方渠道检索获取,这里不再列出外部链接。