将可观察性内建到 Harness 中:让 Agent 的运行时可观测、可评估、可复现(learn-harness-engineering 第 11 讲)
将可观察性内建到 Harness 中:让 Agent 的运行时可观测、可评估、可复现(learn-harness-engineering 第 11 讲)
导读:本讲聚焦 AI Agent Harness(代理运行框架)中"可观察性(observability)"的架构设计,核心论点是:Agent 频繁失败、评估主观、重试盲目,根因往往不是模型能力不足,而是 Harness 缺乏运行时与过程的双重可观察性。读完本文,你将掌握运行时信号采集、Sprint Contract(冲刺契约)、评估网格(Scoring Rubric)与 OpenTelemetry 标准化的完整实战方案,并能在当前仓库的代码示例与项目 06 综合实战中落地验证。
一、本讲要解决的问题:Agent 为什么总是"说不出所以然"
你让一个 Agent 实现某个功能。它运行了 20 分钟,改动了一堆文件,然后告诉你:"做完了,但有两个测试失败。"你问为什么失败——"不确定,可能是时序问题。"你问它改了哪些关键路径——"让我再看看代码……"
这个场景极其常见,而其根因并非 Agent 的能力不足,而是 Harness 缺乏可观察性。当 Agent 在看不到真实运行时状态的情况下执行任务时,它的每一个决策本质上都是在猜测。
- 没有可观察性,Agent 在不确定中做决策:无法区分"真的正确"和"看起来正确";
- 没有可观察性,评估变成主观判断:同一个结果,不同评估者会给出天差地别的结论;
- 没有可观察性,重试变成盲目游走:Agent 不知道失败原因,只能随机修正,浪费 token 与时间。
OpenAI 与 Anthropic 都将可靠性定义为"证据问题":Harness 必须以能够真正指导下一步决策的形式,暴露运行时行为与评估信号。这正是本讲(以及对应法文版原文)的核心主题。
二、缺乏可观察性的真实代价
当 Harness 缺乏可观察性时,会出现四类系统性问题。
1. 无法区分"正确"与"看起来正确"
一个函数在代码评审中可能看起来完美无缺——语法正确、逻辑严密。但在运行时,边界条件处理错误会让它在特定输入下产生错误结果。只有运行时 trace 能揭示真实执行路径与预期发生了偏离。代码评审回答"写了什么",运行时追踪回答"实际跑了什么",两者缺一不可。
2. 评估变成玄学
没有评分网格与验收标准,评估者(无论人类还是 Agent)只能依赖隐式假设。同一个输出,不同的评估者可能给出完全不同的结论,质量评估变得不可复现。
3. 重试变成盲猜
当 Agent 不知道某件事为何失败时,它的重试方向是随机的。它可能反复修正无关的代码路径,却忽略真正的根因。每一次盲目的重试都在烧 token 和时间。
4. 会话交接出现信息悬崖
当未完成的工作移交给下一个会话时,缺少可观察性意味着新会话必须从零开始诊断系统状态。Anthropic 对长时运行 Agent 的观察表明,这种冗余诊断可能消耗整个会话时间的 30–50%。
三、分层可观察性:系统信号与过程工件
可观察性不等于"多加日志",它运行在两个层面,且两者缺一不可。这是本讲最重要的架构认知。
flowchart LR
Contract["先定义任务<br/>改哪些文件 / 不碰什么 / 通过标准"] --> Generator["Generator"]
Generator --> Signals["运行时采集<br/>logs / traces / health checks"]
Contract --> Review["逐项对照清单检查<br/>功能 / 测试 / 边界"]
Signals --> Review
Review --> Verdict["指出哪一项失败<br/>以及该在哪里修"]
Verdict --> Generator
- 运行时可观察性(Runtime Observability):系统层信号——日志、trace、进程事件、健康检查。回答"系统做了什么"。
- 过程可观察性(Process Observability):对 Harness 决策工件的可见性——计划、评分网格、验收标准。回答"这个变更为什么应该被接受"。
两者互为支撑:运行时信号解释行为,过程工件解释意图。
核心概念速览
| 概念 | 含义 |
|---|---|
| 运行时可观察性 | 日志、trace、进程事件、健康检查等系统层信号,回答"系统做了什么" |
| 过程可观察性 | 对计划、评分网格、验收标准等 Harness 决策工件的可见性,回答"为何应接受此变更" |
| 任务 trace | 从任务开始到结束的完整决策路径记录,类似分布式系统中的请求追踪;Agent 每一步及其上下文都被记录,出错时可完整回放整个过程 |
| Sprint Contract | 编码前协商的短期协议,规定任务范围、验证标准与排除项;是过程可观察性的核心工具 |
| 评估网格(Evaluator Rubric) | 将质量评估从主观判断转化为基于证据的结构化评分,使不同评估者对同一输出得出相近结论 |
| 分层可观察性 | 系统层与过程层可观察性同时设计、相互增强 |
四、为什么 Agent 自己解决不了这个问题?
你可能会想:"Agent 难道不能自己打印日志吗?"问题在于:
- Agent 不知道自己不知道什么。它不会主动记录自己意识不到需要的信号。没有 Harness 层的约束,Agent 只会记录它认为重要的内容——而它认为重要的往往远远不够。
- 日志格式不一致。不同会话使用不同格式,导致系统性分析不可能实现。
- 过程可观察性无法靠日志解决。Sprint Contract 和评分网格是结构化工件,需要 Harness 层级的支持——加几行 print 语句远远不够。
五、如何正确构建可观察性
1. 把运行时信号采集内建到 Harness
不要指望 Agent 自己打印日志,Harness 应自动采集以下信号:
- 应用生命周期:startup、ready、running、shutdown 各阶段状态;
- 功能路径执行:关键路径的执行记录,包括入口点、检查点与出口;
- 数据流:组件之间流转的数据记录;
- 资源利用率:异常模式,例如内存持续增长;
- 错误与异常:完整的错误上下文,而不仅仅是错误消息。
2. 实施 Sprint Contract
每项任务开始前,generator 与 evaluator(可能是同一 Agent 的两次调用)协商一份契约,明确"要构建什么"以及"'完成'长什么样":
# 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
仓库中提供了一份更贴近本系列课程的契约示例 sprint-contract.md:以"为 grounded Q&A 结果添加可见引用"为冲刺目标,"完成"的定义细化到"用户提问→应用返回答案→至少展示一条引用→点击引用在文档视图中打开源位置"四个可验证步骤。
3. 建立评估网格
把"好不好"转化为可量化的分数:
# 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 |
评估网格示例给出 1–5 分的量化维度:Grounding(答案是否清晰关联导入的源文档)、Citation quality(引用是否可见且具体)、Functionality(用户能否完成问答流程)、Product coherence(工作流是否感觉一体化)。
4. 用 OpenTelemetry 标准化
为每个 Harness 会话创建一个 trace,为每个任务创建一个 span,为每个验证步骤创建子 span,并用标准属性标注关键信息。这样可观察性数据就能接入 Jaeger、Zipkin 等标准工具链。
六、源码级证据:从临时日志到结构化 JSON
本讲代码目录提供了一个可运行的对比演示 runtime-logger.ts,运行方式为:
npx tsx docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts
该演示模拟一条文档 Q&A 流水线(DocumentLoader → ChunkIndexer → QueryRouter → RetrievalEngine → AnswerGenerator),并预置了一个失败场景:RetrievalEngine 因"向量维度不匹配(查询嵌入 dim=768,索引嵌入 dim=1536)"返回 0 条结果,而下游 AnswerGenerator 并未崩溃,只是生成了"我找不到相关信息"的坏答案。
对比十分直观:
- 临时日志(console.log 风格):只输出"DocumentLoader: parse_upload done (45ms)"这类无结构文本,失败时只显示"something went wrong"。没有维度信息、没有输入输出数据、没有关联 ID——诊断只能靠人肉猜测。
- 结构化 JSON 日志:每条记录包含
timestamp、level、component、action、durationMs、input、output、error、correlationId九个字段,可由diagnoseFromStructured()自动完成诊断——先找 ERROR 级条目定位根因,再检查超过 1000ms 的延迟尖峰,最后发现"返回 0 结果"的空输出级联。
脚本末尾的对比表总结:根因可识别(No→Yes)、输入输出可追踪(No→Yes)、跨步骤关联(No→Yes)、机器可解析(No→Yes)、诊断耗时(人工数分钟→自动数秒)。结构化日志把调试从猜测变成确定性的查找。
在项目 06 的解决方案中,这一理念已落地为生产级实现:logger.ts 定义了 DEBUG/INFO/WARN/ERROR 四级日志、timestamp/level/service/message/data 五字段 JSON 结构,并通过 forService() 返回按服务名隔离的子 Logger,全部输出为机器可解析的 JSON 单行。其使用方式为:
import { logger } from './logger';
const log = logger.forService('my-service');
log.info('Operation completed', { documentId: 'abc123', duration: 42 });
// {"timestamp":"2026-03-30T12:00:00.000Z","level":"INFO","service":"my-service","message":"Operation completed","data":{"documentId":"abc123","duration":42}}
项目 06 的评估网格则把"评估可复现"做到极致:对 Build & Compile、Window Launch、Document Import、Text Indexing、Grounded Q&A、Conversation History、Structured Logging、Clean State Reset、Persistence、Benchmark Scripts、Cleanup Scanner 等 15 个维度逐项打分并附证据说明,同时给出 14 个 IPC 通道的完整覆盖清单——这就是"评估网格"在真实 Electron 知识库应用中的完整形态。
七、实战案例对比:3 倍效率差距从何而来
考虑一个使用 planner-generator-evaluator 三角色工作流的 Harness,执行"给应用添加暗色模式"任务:
无可观察性版本:planner 输出模糊描述;generator 基于模糊性实现,结果不符合 planner 的隐式预期;evaluator 依据自己的隐式标准拒绝,却说不清具体哪里不对,只会说"感觉不太对"。generator 在模糊的拒绝理由上盲目重试。循环 3–4 次,耗时约 45 分钟,勉强产出可接受的结果。
完整可观察性版本:planner 输出 sprint contract,列出要修改的组件、每项验证标准与排除项(例如不做打印样式);generator 依契约实现,运行时可观察性记录每个组件的样式加载与应用过程;evaluator 用评分网格逐维度评估并引用具体证据——"按钮颜色对比度不足(WCAG AA 标准 4.5:1,实测 2.1:1)"。一次迭代、约 15 分钟产出高质量结果。
3 倍效率差距,唯一变量就是可观察性。
Anthropic 在 2026 年 3 月发布的 Harness 设计实验中进一步验证了这套架构:同一任务("用 Web Audio API 构建浏览器版 DAW")在三种架构下运行并记录分阶段数据——Planner 阶段 4.7 分钟/$0.46,Build 第 1 轮 2 小时 7 分/$71.08,QA 第 1 轮 8.8 分钟/$3.24,累计 3 小时 50 分/$124.70。每个角色都在可观察性中扮演明确角色:
- Planner:接收 1–4 句用户需求并扩展为完整产品规格,被要求"大胆设定范围""聚焦产品上下文与高层技术设计而非详细技术实现"——因为过早指定细节一旦出错,错误会向下游级联;
- Generator:逐特性、逐 sprint 实现,每次 sprint 前与 evaluator 协商契约,实现后自我评估再交接 QA;
- Evaluator:用 Playwright MCP 像真实用户一样与运行中的应用交互,测试 UI 功能、API 端点与数据库状态,按产品深度、功能性、视觉设计、代码质量四个维度评分,每维设有硬性阈值,任一不达标即判失败并给出详细反馈。
QA 第 1 轮的真实反馈是:"这是一个视觉上令人印象深刻、AI 集成良好的应用,但若干核心 DAW 功能仅停留在展示层、缺乏交互深度:clip 无法拖拽/移动、没有乐器 UI 面板(合成器旋钮、鼓垫)、没有视觉特效编辑器(EQ 曲线、压缩器表头)。"——这不是边界情况,而是决定 DAW 可用性的核心交互。具体、有证据的反馈,而不是"感觉不太对"。
值得注意的是,evaluator 并非一开始就这么犀利:早期版本会识别出合理问题,然后说服自己这些问题不严重,最终批准通过。修复方法是阅读 evaluator 的日志,找到其判断与人类判断分歧的点,更新 QA prompt 逐一解决——经过几轮这样的开发循环,evaluator 的评分才变得可靠。这本身就是"可观察性指导决策"的元实践。
八、与后续实践课程的衔接
本讲不是孤立的理念课,它与项目 06(综合实战:构建完整 Agent Harness)直接对应:用固定多特性任务集覆盖完整产品切片(文档导入、索引、带引用的 Q&A、运行时可观察性、可读可重启的仓库状态),先跑弱 Harness 基线,再跑最强 Harness,然后做清理重跑,最后做 Harness 消融实验——逐个移除组件,看哪些真正起作用。
项目 06 的 starter 与 solution 对比清晰体现了"可观察性是否内建"的差异:starter 只有基础的 AGENTS.md,没有 feature_list.json、没有 session-handoff.md、没有 clean-state 清单;而 solution 具备完整的 AGENTS.md、CLAUDE.md、feature_list.json、init.sh、session-handoff.md、clean-state-checklist.md 以及质量/评估文档与基准脚本。相关配套还有第 12 讲《为什么每个会话都必须留下干净状态》(回答"如何交接"),与本讲(回答"如何观察")共同构成长时运行 Agent 的两大支柱。
九、核心要点
- 可观察性是 Harness 的架构属性,不是事后添加的功能,必须从一开始就设计进来;
- 两层可观察性都不可或缺:运行时信号解释"发生了什么",过程工件解释"为什么这样做";
- Sprint Contract 前置对齐,避免 generator 构建出 evaluator 因可预见理由立即拒绝的东西;
- 评分网格让评估可复现,不同评估者对同一输出给出相近分数;
- 缺失可观察性会让会话时间白白浪费 30–50% 在冗余诊断上。
十、延伸阅读
- Observability Engineering(Charity Majors):现代可观察性工程的理论与实践框架;
- Dapper(Google, Sigelman 等):大规模分布式追踪的开创性实践,任务 trace 的设计即源于此;
- Harness Design(Anthropic):sprint contracts 与评估网格的提出者,也是本讲场景与实验数据的直接来源;
- Site Reliability Engineering(Google):可观察性在生产系统中的系统性应用。
以上均为本讲原文档列出的理论背景资料,可结合中文版讲义对照学习。
十一、练习
- 可观察性差距分析:审计你当前 Harness 的系统层与过程层可观察性,找出用现有信号无法区分的系统状态,并提议补充方案。
- Sprint Contract 实践:为一项真实任务撰写 sprint contract,让 Agent 依契约执行,对比有无契约时的效率与质量差异。
- 任务 trace 构建:记录 Agent 在完整编码任务中的每一步操作,用 OpenTelemetry 语义约定进行标注,分析 trace 中的信息瓶颈——哪些步骤缺少足够的信号支撑其决策。