【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载导读本文围绕 learn-harness-engineering 课程第 11 讲的核心命题展开Agent 运行失败的根源往往不是模型能力不足而是 harness外挂工程系统没有提供足够的可观测性。文章将讲解运行时可观测性与过程可观测性两层体系、sprint contract 与 evaluator rubric 两个核心产物并结合本仓库中的可运行示例代码runtime-logger.ts与配套实战项目Project 06的源码实现帮助读者掌握把 Agent 调试从盲猜变成确定性查找的具体方案。一、没有可观测性时 Agent 会怎样失败你让 Agent 实现一个功能。它运行了 20 分钟改动了一堆文件然后告诉你做完了但有两个测试挂了。你问为什么它说不太确定可能是时序问题你问它改了哪些关键路径它说让我再看看代码……这个场景的根源不是 Agent 能力不足而是 harness 缺乏可观测性。没有可观测性Agent 在不确定性中做决策评估变成主观判断重试变成盲目游荡。OpenAI 与 Anthropic 都把可靠性定义为证据问题harness 必须把运行时行为与评估信号以能够指导下一次决策的形式暴露出来。具体来说缺失可观测性会系统性地引发四类问题无法区分正确与看起来正确代码评审里函数看起来完美——语法正确、逻辑扎实但运行时边界条件处理错误在特定输入下产生错误结果。代码评审只能告诉你写了什么运行时 trace 才能告诉你实际跑的是什么两者缺一不可。评估变成神秘主义没有评分 rubric 与验收标准评估者人或 Agent只能依赖隐含假设同一输出在不同评估者那里可能得到完全不同的结论质量评估不可复现。重试变成盲猜Agent 不知道失败原因时重试方向是随机的可能反复修无关代码路径而忽略真正的根因。每一次盲目的重试都在消耗 token 和时间。会话交接信息断崖未完成任务交给下一个会话时缺乏可观测性意味着新会话必须从头诊断系统状态。Anthropic 对长时运行 Agent 的观察显示这类重复诊断可能消耗总会话时间的 30%–50%。二、核心概念两层可观测性本讲的核心概念框架围绕系统层 过程层两层可观测性展开二者缺一不可概念定义回答的问题运行时可观测性Runtime observability日志、trace、进程事件、健康检查等系统级信号系统做了什么过程可观测性Process observability对 harness 决策产物的可见性——计划、评分 rubric、验收标准这个改动为什么应该被接受任务 traceTask trace从任务开始到完成的完整决策路径记录类似分布式系统的请求追踪Agent 的每一步及其上下文都被记录出问题时可以回放整个过程sprint contract编码开始前协商的短期协议明确任务范围、验证标准、排除项过程可观测性的核心工具evaluator rubric把质量评估从主观判断转变为基于证据的结构化打分让不同评估者对同一输出得出相似结论评估可复现分层可观测性系统层与过程层同时设计、互相强化运行时信号解释行为过程产物解释意图行为 意图分层可观测性的工作流可以用下面的流程图概括开工前先把任务写成契约改什么 / 不碰什么 / 通过标准生成器执行运行时收集日志与健康检查信号评估器逐项对照清单检查功能 / 测试 / 边界最后明确指出哪一项失败、该修哪里并把结论反馈给生成器形成闭环三、为什么 Agent 自己解决不了这个问题你可能会想Agent 自己打印日志不就行了 问题在于Agent 不知道自己不知道什么——它不会主动记录自己意识不到需要的信号没有 harness 层面的约束Agent 只会记录它认为重要的内容而它认为重要的通常不够。日志格式不一致——不同会话用不同日志格式系统性分析无从谈起。过程可观测性无法靠打日志解决——sprint contract 和评分 rubric 是需要 harness 级支持的结构化产物加几行 print 语句远远不够。四、正确做法四个构建步骤1. 把运行时信号采集构建进 harness不要依赖 Agent 自己打日志。harness 应当自动采集以下信号应用生命周期启动startup、就绪ready、运行running、关闭shutdown各阶段状态功能路径执行关键路径的执行记录包括入口点、检查点、出口数据流组件之间数据流动的记录资源利用异常资源使用模式如内存持续增长错误与异常完整的错误上下文而不仅仅是错误消息。仓库中的可运行示例 runtime-logger.ts 演示了两种日志方式的对比。它模拟了一个文档问答管线的五个阶段DocumentLoader → ChunkIndexer → QueryRouter → RetrievalEngine → AnswerGenerator并埋入一个种子故障RetrievalEngine 因向量维度不匹配query embedding dim768 vs index embedding dim1536返回 0 结果而 AnswerGenerator 不崩溃但产出错误答案——这正是看起来成功、实际失败的典型场景。临时拼接的console.log风格输出只显示RetrievalEngine: something went wrong信息模糊、无维度、无输入输出数据、无关联 ID而结构化 JSON 日志把每个阶段的时间戳、级别、组件、动作、耗时、输入、输出、错误和correlationId完整记录配合自动诊断函数可一次性指出根因、延迟尖峰durationMs 1000和空输出级联results: 0。运行方式npx tsx docs/en/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts示例结尾的对比表给出了结论根因是否可识别否/是、输入输出是否可追溯否/是、跨步骤是否可关联否/是、是否机器可解析否/是、诊断耗时手动数分钟 / 自动数秒——结构化日志把调试从猜测变成确定性查找。2. 实现 sprint contract每项任务开始前生成器与评估器可能是同一 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 QA 结果添加可见引用citation完成被明确定义为用户提问 → 应用返回答案 → 至少展示一条引用 → 点击引用在文档视图中打开来源位置。把抽象的做好翻译成可验证的行为序列正是契约的价值所在。3. 建立 evaluator rubric把好不好变成可量化的打分。rubric 定义评估维度以及每个维度的等级描述让不同评估者对同一输出给出相近分数# 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 |配套示例 evaluator-rubric.md 为 Project 06 的应用场景定义了 1–5 分维度Grounding答案是否明确关联导入的源文档、Citation quality引用是否可见且具体、Functionality用户能否走完问答流程、Product coherence工作流是否整体连贯。4. 用 OpenTelemetry 标准化为每个 harness 会话创建一个 trace为每个任务创建一个 span为每个验证步骤创建子 span用标准属性注解关键信息。这样可观测性数据就能与标准工具链Jaeger、Zipkin集成避免各会话日志格式不一致的老问题。五、仓库源码佐证Project 06 中的落地实现本课程把第 11 讲直接落地为实战项目 Project 06: Runtime Observability and Debugging (Capstone)——构建并基准测试一个完整 harness然后用清理循环验证质量与可维护性。项目的 solution 中有多个可直接对照的实现结构化日志模块logger.ts 是完整产品中的结构化日志实现定义DEBUG / INFO / WARN / ERROR四级日志每条日志为单行 JSONtimestamp、level、service、message、可选data并通过forService()创建按服务隔离的子 logger让所有服务输出统一、机器可解析。其设计遵循第 11 讲的日志格式一致性原则——不再依赖各服务各自 console.log 的临时格式。可靠性文档中的日志规范solution/docs/RELIABILITY.md 把日志约定写成工程规范包括日志格式单行 JSON 对象含 timestamp/level/service/message/data级别使用约定DEBUG 用于常规数据访问与文件读取INFO 用于重要事件WARN 用于缺失但非关键的数据ERROR 用于失败各服务埋点清单PersistenceService目录初始化、读写、清理重置、DocumentService导入、删除、元数据更新、文件不存在、超限、IndexingService单/批量索引、进度、吞吐指标、QaService提问处理、答案生成置信度与耗时、反馈提交、IPC Handlers每个通道调用记录运行配置通过环境变量LOG_LEVEL控制输出级别例如LOG_LEVELINFO npm run dev只输出 INFO 及以上默认DEBUG全部输出。同时该文档还配套了 benchmark 脚本与清理扫描器bash scripts/benchmark.sh度量 import/index/query/verify 四类任务耗时如 query 目标 500ms/问题bash scripts/cleanup-scanner.sh检查孤儿内容文件、悬空 chunk 文件、元数据不一致、过期问答历史等把可观测进一步延伸到状态可审计。完整的评估产物solution/evaluator-rubric.md 是课程评估实践的直接产物对 15 个维度构建编译、窗口启动、文档导入、文本索引、grounded QA、结构化日志、清理重置等逐项按 1–5 打分并给出证据备注最终给出总分 5.0/5同时列出 14 个 IPC 通道的日志覆盖情况证明每个通道都有日志这一 harness 完整性要求。这正体现了第 11 讲所说的用证据替代主观判断。六、实际场景一个 3 倍效率差异的对比考虑使用planner-generator-evaluator三角色工作流的 harness执行任务为应用添加暗色模式。没有可观测性时planner 输出模糊描述generator 基于模糊性实现暗色模式结果不符合 planner 的隐含预期evaluator 基于自己的隐含标准拒绝却说不清具体哪里不对——只能说感觉不对generator 基于模糊的拒绝理由盲目重试。循环重复 3–4 次耗时约 45 分钟勉强产出可接受的输出。具备完整可观测性时planner 输出 sprint contract列出要改哪些组件、各自的验证标准、排除项如不处理打印样式generator 按契约实现运行时可观测性记录每个组件的样式加载与应用过程evaluator 用评分 rubric 逐维度打分并引用具体证据如按钮颜色对比度不足WCAG AA 标准 4.5:1实测 2.1:1。一次迭代产出高质量结果耗时约 15 分钟。3 倍的效率差异唯一的变量是可观测性。七、核心要点总结可观测性是 harness 的架构属性——不是事后添加的功能而是必须从一开始就设计进去的核心能力。两层可观测性缺一不可——运行时信号解释发生了什么过程产物解释为什么这样做。sprint contract 前置了对齐——防止 generator 构建出 evaluator 因可预见原因立刻拒绝的东西。评分 rubric 让评估可复现——不同评估者对同一输出给出相似分数。缺失可观测性会浪费 30%–50% 的会话时间在重复诊断上。八、延伸阅读与练习本仓库内可继续深入的材料课程第 11 讲英文版含 Anthropic 三智能体架构实验的分阶段耗时与成本数据课程配套代码目录runtime-logger 演示、sprint contract、evaluator rubric 示例Project 06 实战项目 及其 solution 实现课程第 12 讲为什么每个会话都必须留下干净状态。练习建议可观测性差距分析审计当前 harness 的系统层与过程层可观测性找出现有信号无法区分的系统状态并提出补充方案。sprint contract 实操为真实任务写一份契约让 Agent 按契约执行对比有/无契约时的效率与质量。任务 trace 构建完整记录一次编码任务中 Agent 的每一步用 OpenTelemetry 语义约定注解分析 trace 中的信息瓶颈——哪些步骤缺乏足够的信号支撑其决策。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐让 Agent 的运行时可见在 Harness 中内置可观测性learn-harness-engineering 第 11 讲让 Agent 的运行时可见在 Harness 中内置可观测性learn harness engineering 第 11 讲 导读本讲围绕一个核心问题将可观察性内建到 Harness 中让 Agent 的运行时可观测、可评估、可复现learn-harness-engineering 第 11 讲将可观察性内建到 Harness 中让 Agent 的运行时可观测、可评估、可复现learn harness engineering 第 11 讲 导读让 Agent 运行时可见learn-harness-engineering 第 11 课「可观测性必须内置于 Harness」的完整实践指南让 Agent 运行时可见learn harness engineering 第 11 课「可观测性必须内置于 Harness」的完整实践指南 本课是 lea上一篇Relay记忆系统深度解读从会话记忆到跨会话知识持久化的完整三层设计指南下一篇AMD Ryzen处理器调试终极指南SMUDebugTool完整使用教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考