【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本文围绕 learn-harness-engineering 仓库中 docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/index.md 展开并结合仓库内的代码示例与 Project 06 综合项目 的源码实现系统讲解「为什么可观测性必须内置于 harness 架构」这一核心命题。导读本讲解决一个几乎每个 agent 工程实践者都会遇到的痛点agent 跑 20 分钟、改了一堆文件然后告诉你「做完了但有两个测试失败」你追问失败原因它说「不太确定可能是时序问题」你追问改了哪些关键路径它说「让我看看代码……」。这并非 agent 能力不足而是harness 缺乏可观测性当运行时行为与评估信号无法以可指导下一步决策的形式被暴露时agent 只能在不确定状态下做决策评估沦为主观判断重试沦为盲目摸索。读完本文你将掌握双层可观测性的设计框架、冲刺合同与评估评分标准两大过程观测工件、OpenTelemetry 标准化接入方式以及如何在 harness 中内置运行时信号采集。一、为什么可观测性必须属于 harness 的架构属性OpenAI 与 Anthropic 都把可靠性定义为「证据问题」一个结论只有在有证据支撑时才算可靠。对 agent 系统而言证据来自两层运行时信号系统层日志、追踪、进程事件、健康检查回答「系统做了什么」过程工件过程层计划、评分标准、验收条件回答「为什么这个变更应该被接受」。可观测性不是事后补的监控而是 harness 设计时必须考虑的核心能力——这与仓库 Project 06 中把RELIABILITY.md提升为与ARCHITECTURE.md、PRODUCT.md并列的顶层文档见 projects/project-06/solution/docs/RELIABILITY.md的思路完全一致可观测性是产品的一等公民而非附属品。二、缺乏可观测性的四类系统性成本当 harness 没有可观测性时四类问题会系统性出现无法区分「正确」与「看似正确」一个函数在代码审查时看起来完全正确——语法对、逻辑通但运行时可能因边界条件处理错误在特定输入下产生错误结果。代码审查看的是「写了什么」运行时追踪才能揭示「实际跑了什么」两者缺一不可。评估变成玄学没有评分标准与验收条件时评估者无论人或 agent只能依赖隐式假设。同一份输出不同评估者可能给出截然不同的结论质量评估不可复现。重试变成盲猜agent 不知道失败原因时重试方向是随机的可能在错误方向上反复尝试修复不相关的代码路径而忽略真正的故障根源。每次盲重试都消耗 token 与时间。会话交接的信息断崖未完成的工作移交给下一会话时缺乏可观测性意味着新会话必须从零诊断系统状态。Anthropic 对长期运行 agent 的观察表明这种重复诊断可能占会话总时间的30-50%。三、双层可观测性运行时与过程相互补强可观测性不是「多打几行日志」它分两层缺一不可。本讲给出了如下闭环工作流闭环的逻辑是冲刺合同Contract在任务开始前对齐预期运行时信号Signals在执行中记录事实评估Review依据合同与信号逐项核对最后给出带定位的裁决Verdict并回流到生成器。运行时信号解释行为过程工件解释意图两者互相印证才能支撑可靠决策。核心概念清单运行时观测性系统层信号包括日志、追踪、进程事件、健康检查回答「系统做了什么」。过程观测性harness 决策工件计划、评分标准、验收条件的可见性回答「为什么这个变更应该被接受」。任务轨迹Task Trace一个任务从开始到完成的完整决策路径记录类似分布式系统中的请求追踪agent 的每一步操作及其上下文都被记录出错时可回放完整过程。冲刺合同Sprint Contract编码开始前协商的短期协议明确任务范围、验证标准、排除项是过程观测性的核心工具。评估评分标准Evaluator Rubric把质量评估从主观判断变成基于证据的结构化评分使不同评估者对同一输出产生相似结论。双层可观测性系统层与过程层同时设计、相互增强。四、为什么「让 agent 自己打日志」行不通一个自然的疑问是「agent 不能自己记录吗」问题在于三点agent 不知道它不知道什么它不会主动记录自己未意识到的信号。没有 harness 层约束它只会记录自己认为重要的东西而它认为重要的往往不够。日志格式不统一不同会话使用不同格式无法做系统化分析。过程观测性不是日志能解决的冲刺合同与评分标准是结构化工件需要 harness 层支持不是多print几行能搞定的。五、正确做法一在 harness 内置运行时信号采集不要依赖 agent 自报日志harness 应自动采集以下信号应用生命周期启动、就绪、运行、关闭各阶段状态功能路径执行关键路径的入口、检查点与出口记录数据流数据在组件间的流转记录资源利用异常模式如内存持续增长错误与异常完整错误上下文而非仅错误消息。仓库中 docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts 直接演示了这一点。它模拟一个文档 QA 流水线DocumentLoader → ChunkIndexer → QueryRouter → RetrievalEngine → AnswerGenerator并植入了一个真实故障RetrievalEngine因向量维度不匹配query 768 维 vs 索引 1536 维返回 0 结果而下游AnswerGenerator不崩溃但给出无引用回答。运行它对比两种日志风格npx tsx docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.tsAd-hoc 版console.log风格只输出RetrievalEngine: something went wrong没有维度、输入输出数据、关联 ID根因不可定位结构化 JSON 版每条日志包含timestamp、level、component、action、durationMs、input、output、error、correlationId脚本随后自动给出诊断根因RetrievalEngine.semantic_search、延迟尖峰、空输出的级联影响AnswerGenerator收到空 context。演示结论直指要害结构化日志把调试从猜测变成确定性查找correlationId把一次任务的所有步骤串成一条可回放的任务轨迹。仓库级落地Project 06 的 logger 实现理论在 Project 06 中被实现为可复用的模块 projects/project-06/solution/src/services/logger.ts定义DEBUG / INFO / WARN / ERROR四级日志按级别阈值过滤shouldLog通过LEVEL_ORDER索引比较实现每条日志输出为单行 JSON{timestamp,level,service,message,data}提供logger.forService(serviceName)创建服务级子日志器保证全应用统一格式级别由LOG_LEVEL环境变量控制默认DEBUG。实际服务层的调用方式以 projects/project-06/solution/src/services/document-service.ts 为例const SERVICE document-service; private log logger.forService(SERVICE); this.log.info(Starting document import, { filePath }); this.log.error(File not found during import, { filePath }); this.log.warn(Document not found, { documentId: id }); this.log.debug(Listing documents, { count });关键事件导入成功、删除、更新记 INFO例行数据访问记 DEBUG缺失但非关键数据记 WARN失败记 ERROR——这与 projects/project-06/solution/docs/RELIABILITY.md 中规定的日志级别语义一一对应级别使用场景示例DEBUG例行数据访问、文件读取Retrieved chunks for documentINFO显著事件Document imported、Batch indexing completeWARN缺失但非关键数据Content not found for documentERROR失败File not found during import生产级日志格式示例摘自 RELIABILITY.md{ timestamp: 2026-03-30T12:00:00.000Z, level: INFO, service: document-service, message: Document imported successfully, data: { documentId: abc-123, filename: design-notes.md, sizeBytes: 2048 } }运行时调整级别LOG_LEVELINFO npm run dev # 仅 INFO、WARN、ERROR LOG_LEVELWARN npm run dev # 仅 WARN、ERROR LOG_LEVELERROR npm run dev # 仅 ERROR六、正确做法二实施冲刺合同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合同的三个组成部分各有分工Scope划定改动边界Verification Standards给出可执行的通过标准Exclusions明确排除项以防 agent 过度延伸。仓库示例 docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md 展示了一个更贴近实际产品的合同目标是「为有根据的 QA 结果添加可见引用」「完成」定义为用户提问 → 应用返回回答 → 至少显示一个引用 → 点击引用在文档视图中打开来源位置。注意「完成」被拆成了可逐条验收的用户可感知行为这正是合同可被评估的关键。七、正确做法三建立评估评分标准Evaluator 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 |每格都是可观测、可判定的具体条件如「所有测试通过」「编译失败」而非「感觉不错」。仓库示例 docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/evaluator-rubric.md 采用 1-5 分制并按维度拆解根植性回答是否明确绑定导入的源文档、引用质量引用是否可见且具体、功能性用户能否完成问答流程、产品一致性工作流是否感觉融为一体。这一理念在 Project 06 落地为 projects/project-06/solution/evaluator-rubric.md每个维度给 1-5 分并附证据注释例如 Build Compile 记 5 分并注明「无错误、无警告的 TypeScript 编译」Structured Logging 记 5 分并注明「JSON 格式、日志级别、服务标签、数据载荷、覆盖全部服务」。评分与证据绑定任何人复核都能得到相同结论。八、正确做法四用 OpenTelemetry 标准化为每个 harness 会话创建一个 trace每个任务创建一个 span每个验证步骤创建子 span用标准属性标注关键信息。这样观测数据可无缝接入 Jaeger、Zipkin 等标准工具链任务轨迹即可被跨会话回放与检索。九、实战对照可观测性带来 3 倍效率差用「计划者-生成者-评估者」三角色 workflow 执行「为应用添加暗色模式」任务无可观测性计划者输出模糊描述 → 生成者按模糊描述实现但偏离隐式预期 → 评估者基于隐式标准拒绝且只说「感觉不太对」→ 生成者盲重试。循环 3-4 次总耗时约 45 分钟勉强产出。完整可观测性计划者输出冲刺合同明确组件、验证标准、排除项→ 生成者按合同实现 → 运行时记录每个组件的样式加载与应用过程 → 评估者按评分标准逐维度评估并附证据引用如「按钮对比度不足WCAG AA 要求 4.5:1实测 2.1:1」。一次迭代产出高质量结果约 15 分钟。效率差 3 倍唯一变量是可观测性。Anthropic 在「Harness design for long-running application development」中报告的三 agent 架构实验Planner 负责把 1-4 句话的需求扩成产品规格、Generator 按 sprint 逐个实现、Evaluator 用 Playwright MCP 像用户一样点击应用并按四个维度评分印证了同一结论具体的、有证据的反馈「剪辑不能拖拽」「没有乐器 UI 面板」而不是「感觉不对」才构成可执行的重试指令。实验中 evaluator 也不是一开始就强早期它会识别出合理问题然后说服自己不严重、最终放行调校方式是读取 evaluator 日志、找出其判断与人类判断分叉处并更新 QA 的 prompt——这本身就是把「评估」也纳入观测循环的实践。十、核心要点可观测性是 harness 的架构属性是设计时必须考虑的核心能力不是事后添加的功能。双层可观测性缺一不可运行时信号解释「发生了什么」过程工件解释「为什么这样做」。冲刺合同前置对齐防止「生成者做了、评估者因可预见原因立即拒绝」的浪费。评分标准让评估可复现不同评估者对同一输出产生相似评分。可观测性缺失会让 30-50% 的会话时间浪费在重复诊断上。十一、动手练习可观测性差距分析审查你当前的 harness分别评估系统层与过程层可观测性找出无法从现有信号区分的系统状态并提出补充方案。冲刺合同实践为一个真实任务写冲刺合同参考 docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/sprint-contract.md让 agent 按合同执行对比有/无合同的效率与质量差异。任务轨迹构建记录一个完整编码任务中 agent 的每一步操作用 OpenTelemetry 语义约定标注分析轨迹中的信息瓶颈——哪些步骤的决策缺乏足够信号支持。结构化日志对照实验运行 docs/ja/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts对比 ad-hoc 与结构化日志的定位耗时体会correlationId串联任务轨迹的价值。更完整的综合演练可参考仓库中的 Project 06Runtime Observability and Debugging 综合项目其 solution 目录 内的 AGENTS.md、RELIABILITY.md 与 evaluator-rubric.md 构成了一个把本讲全部理念落地的完整 harness 范本。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐将可观察性内建到 Harness 中让 Agent 的运行时可观测、可评估、可复现learn-harness-engineering 第 11 讲将可观察性内建到 Harness 中让 Agent 的运行时可观测、可评估、可复现learn harness engineering 第 11 讲 导读Power Automate 数据变换 Action 模式实战FlowStudio 构建数组操作、HTTP 调用与解析管线Power Automate 数据变换 Action 模式实战FlowStudio 构建数组操作、HTTP 调用与解析管线 导读 本文是 FlowStudioCherry Studio 迷你应用沙箱机制解析不透明 Origin、默认拒绝网络与宿主能力替代方案Cherry Studio 迷你应用沙箱机制解析不透明 Origin、默认拒绝网络与宿主能力替代方案 Cherry Studio 的迷你应用mini app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
