【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载导读本文以 learn-harness-engineering 仓库中「为什么可观测性应当内置于 harness」一讲为核心系统讲解如何为 AI Agent 的运行时建立系统层与进程层两层可观测性使其从「盲猜式重试」转向「证据驱动的确定性诊断」。你将掌握运行时信号自动采集、冲刺契约Sprint Contract、评估准则Evaluator Rubric与 OpenTelemetry 标准化落地方法并能在 projects/project-06-runtime-observability-and-debugging 对应的实战项目中直接应用。为什么 Agent 会「自信地失败」可观测性缺失的四种系统性代价当 Agent 被要求实现一个功能时它常常会运行二十分钟、修改大量文件然后报告「完成了但有两个测试失败」。追问失败原因时得到的答复往往是「不确定可能是时序问题」追问修改了哪条关键路径时回答是「我去看看代码……」。这不是 Agent 能力不足而是 harness 没有提供足够的可观测性。没有可观测性Agent 只能在不确定中做决策评估沦为主观判断重试沦为盲猜。具体而言可观测性缺失会系统性引发四类问题无法区分「正确」与「看起来正确」一个在代码评审层面看似完美的函数可能在特定输入的边界条件下于运行时返回错误结果。实际执行路径偏离预期这一事实只有运行时 trace 才能揭示。评估变成神秘主义没有评分准则和验收标准时评估者无论是人类还是 Agent只能依赖隐含假设。同一份输出在不同评估者手中可能得出截然不同的结论质量评估不可复现。重试变成盲目猜测不知道失败原因重试方向就接近随机可能忽略真正根因而反复修补无关代码路径。每一次盲目重试都在消耗 token 和时间。会话交接的信息断崖未完成的工作交接给下一个会话时如果缺乏可观测性新会话必须从零开始重新诊断系统状态。来自 Anthropic 的长期 Agent 观察表明这种重复诊断可能消耗会话时间的 30-50%。从源码结构看这个仓库正是为了消除上述代价而设计的讲义的配套代码 code/ 目录下同时提供了 评估准则示例、冲刺契约示例 与可运行的 runtime-logger.ts 演示脚本三者分别对应进程可观测性、契约对齐与运行时信号采集。核心概念两层可观测性本讲提出并区分了两层可观测性二者必须同时设计、相互补强层级回答的问题信号来源代表产物运行时可观测性Runtime Observability「系统做了什么」日志、trace、进程事件、健康检查等系统级信号结构化日志、任务 trace进程可观测性Process Observability「为什么应该接受这个变更」计划、评分准则、验收标准等 harness 判断产物冲刺契约、评估准则任务 traceTask Trace从任务开始到完成的完整决策路径记录类似于分布式系统中的请求 trace。它记录 Agent 的每一步动作与上下文是还原「当时为什么这么做」的关键证据。冲刺契约Sprint Contract在编码开始前达成一致的短期契约明确任务范围、验证标准与排除项是进程可观测性的核心工具。评估准则Evaluator Rubric将质量评估从主观判断转变为基于证据的结构化评分使不同评估者面对同一输出能得到接近的分数。分层可观测性Layered Observability运行时信号解释「行为」进程产物解释「意图」二者共同构成完整的证据链。讲义用一张流程图概括了完整闭环先写任务明确改什么、不改什么、合格标准→ Generator 执行并收集应用日志、trace、健康检查 → 按条款逐项评审行为/测试/边界→ 给出失败检查项与修复位置 → 反馈给 Generator 进入下一轮迭代。运行时信号为什么不能依赖 Agent 自己打日志有人会问「让 Agent 自己输出日志不就行了」本讲明确指出三条不可行理由Agent 不知道自己不知道什么因此不会自发记录所需信号日志格式不统一每次会话格式各异无法进行系统性分析进程可观测性无法只靠日志解决冲刺契约和评分准则都是需要 harness 级支持的结构化产物。因此harness 应当自动采集以下五类运行时信号而不是依赖 Agent 自觉应用生命周期启动startup、就绪ready、运行中running、关闭shutdown各状态功能路径执行关键路径的入口、检查点、出口记录数据流组件之间流转的数据记录资源使用如内存持续增长等异常使用模式错误与异常完整上下文而不仅仅是错误消息。源码实证Ad-hoc 日志 vs 结构化日志讲义配套的 runtime-logger.ts 是一个可运行的 TypeScript 演示通过一个模拟的文档问答流水线直观对比两种日志形态。运行方式npx tsx docs/lectures/lecture-11-why-observability-belongs-inside-the-harness/code/runtime-logger.ts流水线包含五个阶段DocumentLoader解析上传文档输出 47 个 chunk→ChunkIndexer嵌入并存储embedding 维度 1536→QueryRouter路由查询→RetrievalEngine语义检索→AnswerGenerator带引用的答案生成。代码中植入了一个典型故障见 runtime-logger.tsRetrievalEngine因查询向量维度768与索引向量维度1536不匹配而返回 0 条结果但AnswerGenerator并不会崩溃只是产出了「I could not find relevant information.」的低质量回答——这正是「看起来正常、实则失败」的隐蔽故障形态。Ad-hoc 日志版本printAdHocLog只输出类似RetrievalEngine: something went wrong的模糊信息没有维度、没有输入输出数据、没有关联 ID。面对这样的日志诊断只能靠猜。结构化日志版本printStructuredLog则为每个阶段生成 JSON 条目其核心结构如下interface StructuredLogEntry { timestamp: string; level: info | warn | error | debug; component: string; action: string; durationMs?: number; input?: unknown; output?: unknown; error?: string; correlationId: string; }每个字段都有明确作用timestamp提供时间轴level区分严重程度componentaction精确定位失败位置input/output记录上下文数据durationMs暴露延迟异常correlationId把一次任务的各个阶段串联成可追踪的整体脚本用req- 随机串生成。基于结构化日志脚本的 diagnoseFromStructured 函数还能自动诊断错误定位按level error过滤直接输出RetrievalEngine.semantic_search: Vector dimension mismatch...延迟尖峰按durationMs 1000过滤捕获AnswerGenerator的 1500ms 异常耗时级联失败检测output.results 0的空输出识别「检索为空 → 答案生成器拿到空上下文 → 产出低质量答案」的级联链下游影响追踪AnswerGenerator接收的空上下文与 0 引用数完整还原故障的传播路径。最终脚本输出一张对比表清楚展示了两种日志形态的差距指标Ad-hoc 日志结构化日志根因可识别否是输入/输出可追踪否是跨步骤关联否是机器可解析否是诊断耗时分钟级人工秒级自动这个演示的结论是结构化日志把调试从「猜谜」变成「确定性查找」。进程可观测性一用冲刺契约在编码前对齐认知冲刺契约是进程可观测性的核心工具在任务开始前由 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排除项尤其重要它把「评估者因不可预见的原因立刻否决 generator 产出」这类内耗降到最低。仓库配套代码中的 sprint-contract.md 给出了另一种更轻量的写法——以「有据可依的 QA 结果附加可见引用」为目标把「完成」定义为四个可验证行为用户提问 → 应用返回回答 → 至少显示一条引用 → 点击引用在文档视图中打开源位置。这种「行为式完成定义」把抽象目标翻译成了可检查的动作序列。进程可观测性二用评估准则把「好坏」变成可复现的分数评估准则是进程可观测性的另一支柱将「好还是不好」转化为定量评分使不同评估者人类或 Agent面对相同输出能给出相近分数让评估从主观判断走向可复现。讲义提供的评分准则模板讲义原文按维度组织每个维度给出 A/B/C/D 四级锚点# 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 分量表本篇主题关联文档 code/evaluator-rubric.md 提供的是另一种经典形态——每个维度采用 1-5 分制评分Grounding依据性回答是否明确关联到导入的源文档Citation quality引用质量来源引用是否可见且具体Functionality功能性用户能否完成完整的问答流程Product coherence产品一致性整个工作流是否感觉浑然一体这四个维度恰好覆盖了 RAG/知识库类应用评估的关键面既考察答案与来源的绑定关系Grounding、Citation quality又考察端到端可用性与产品体验Functionality、Product coherence。实战延伸Project 06 中的完整评估准则本讲对应的实战项目 project-06-runtime-observability-and-debugging 的解决方案目录中提供了这份准则在真实项目上的完整落地版本 solution/evaluator-rubric.md。它展示了如何把抽象维度映射到可核验的工程事实Build Compile构建编译TypeScript 编译零错误零警告Window Launch / Document Import / Document Detail / Text IndexingElectron 窗口、文档导入、详情展示、段落感知分块与索引等逐项功能核验Grounded QA有据问答关键词检索、带摘录的引用、置信度评分、8 种回答模式Structured Logging结构化日志JSON 格式、日志级别、服务标签、数据负载、全服务覆盖——直接对应 runtime-logger.ts 演示的采集标准Clean State Reset / Persistence / Status Bar数据重置幂等性、持久化与状态展示Benchmark Scripts / Cleanup Scanner / Harness Completeness脚本化基准、孤儿数据扫描、9 个 harness 文件的完整性检查。该文档还给出了 IPC 通道覆盖清单14 个通道全部带日志documents:list/import/get/delete、indexing:start/status/chunks、qa:ask/history/clear-history、feedback:submit/list、app:reset、app:status并给出总体评分 5.0/5。这种「每个维度都有可检查证据」的写法正是进程可观测性的目标——评估结论可以追溯到具体文件与行为。用 OpenTelemetry 标准化观测数据为了让采集到的观测数据不局限于某个 harness 或工具链本讲建议用 OpenTelemetry 标准化每个 harness 会话对应一个 trace每个任务对应一个 span每个验证步骤对应一个 sub-span并用标准属性为关键信息打注解。这样观测数据可以平滑接入 Jaeger、Zipkin 等标准工具链实现跨会话、跨任务的统一查询与分析。这一建议的核心价值在于结构化日志解决了「可读、可解析」而 OpenTelemetry 的 trace/span 模型进一步解决了「可关联、可聚合」——把分布式系统的请求追踪思想参考 Google Dapper 的经典实践迁移到 Agent 会话与任务维度。完整案例planner-generator-evaluator 工作流中的可观测性收益本讲用「给应用添加暗色模式」任务在 planner-generator-evaluator 三角色工作流下对比两种结局无可观测性版本planner 给出模糊描述 → generator 基于模糊性实现 → evaluator 凭隐含标准否决却说不清具体问题 → generator 凭模糊理由盲猜重试。3-4 轮迭代、约 45 分钟产出勉强可接受。完整可观测性版本冲刺契约明确范围、验证标准与排除项运行时 trace 记录每个组件的样式加载与应用过程评分准则提供逐维度的结构化评估与证据引用1 轮迭代即产出高质量结果约 15 分钟。效率相差约 3 倍而唯一的变量就是可观测性。此外讲义引用 Anthropic 的观察指出可观测性缺失会让会话时间的 30-50% 消耗在重复诊断上——这部分时间既不产生代码也不产生决策是纯损耗。关键要点与上手路径可观测性是 harness 的架构属性不是事后追加的功能应在设计阶段就纳入考量两层可观测性缺一不可运行时信号回答「发生了什么」进程产物回答「为什么这么做」冲刺契约在编码前对齐认知避免「generator 产出 → evaluator 以不可预见理由立即否决」的内耗循环评分准则让评估可复现不同评估者对同一输出应给出相近分数可观测性缺失会浪费 30-50% 的会话时间在重复诊断上。上手练习路径讲义原文的实操建议可观测性差距分析用系统层与进程层两个维度审计当前 harness找出现有信号无法区分的系统状态并给出补充方案冲刺契约练习为真实任务编写冲刺契约让 Agent 按契约执行对比有/无契约时的效率与质量任务 trace 构建完整记录一次编码任务中 Agent 的全部操作用 OpenTelemetry semantic conventions 打注解分析哪些步骤缺少决策所需信号。配套代码与项目资源评估准则示例见 code/evaluator-rubric.md冲刺契约示例见 code/sprint-contract.md结构化日志演示见 code/runtime-logger.ts综合实战项目见 project-06 解决方案 及其配套的AGENTS.md、feature_list.json、claude-progress.md、session-handoff.md、clean-state-checklist.md等 9 个 harness 文件它们共同构成一个完整的、可观测的 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 讲 导读Cherry Studio 迷你应用沙箱机制解析不透明 Origin、默认拒绝网络与宿主能力替代方案Cherry Studio 迷你应用沙箱机制解析不透明 Origin、默认拒绝网络与宿主能力替代方案 Cherry Studio 的迷你应用mini appVoltAgent Scorers 评分器包为 Agent 与 RAG 系统构建可复用、可观测的 LLM 评估体系VoltAgent Scorers 评分器包为 Agent 与 RAG 系统构建可复用、可观测的 LLM 评估体系 导读 voltagent/scorers人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
