【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本篇技术指南聚焦 Learn Harness Engineering 课程的收官项目Capstone——project-06-runtime-observability-and-debugging。项目要求把前五个项目积累的 harness 组件初始化、特征清单、会话交接、干净状态、运行时反馈组装成一个完整、可观测、可维护的 Agent 工作台用固定任务集完成弱 harness 基线、完整 harness、cleanup 循环与消融实验四阶段对比。读完本文你将掌握如何用AGENTS.md、feature_list.json、init.sh、session-handoff.md、clean-state-checklist.md、结构化日志与基准/清理脚本构建一个可量化评估、可反复验证的 Agent 工程环境并能独立复跑仓库内projects/project-06的完整实验流程。一、项目定位为什么 Capstone 要“可观测 可调试”project-06与前面五个项目最大的区别在于产品代码已经基本完整真正的战场是代码之外的“操作系统”——harness 表面。项目描述德文项目文档明确写道这是收尾项目Abschlussprojekt你要把前五个项目学到的所有机制组装起来运行一次完整基准测试然后做一轮 cleanup验证质量是否可维护wartbar bleibt。它对应的两讲理论课是Lektion 11. Runtime beobachtbar machen让 Agent 运行时可观测Lektion 12. Sauberes Handoff am Ende jeder Session每次会话结束留下干净交接状态核心思想一句话如果 harness 对自身的运行状态不可观测、对跨会话状态不可恢复那么再强的 Agent 也会在长任务中失控。本项目的任务集固定覆盖一个完整产品切片文档导入、索引、带引用的 QA、运行时可观测性、以及一个可读可恢复wiederaufnehmbar的仓库状态。二、实验设计基线 → 完整 harness → 清理 → 消融原文档给出的实验路径是明确且固定的弱 harness 基线运行schwacher harness-Baseline-Lauf先用被刻意弱化的 harness 表面跑一遍任务集最强 harness 运行换上完整 harness 再跑同样的任务集Cleanup 与重跑Cleanup und erneuter Lauf执行清理扫描、修复问题、再次运行确认消融实验Ablationsexperiment每次移除一个 harness 组件观察哪个组件真正决定成败。这样的设计让结论可归因不是“Agent 变强了”而是“某一块 harness 组件带来了可度量的改进”。三、仓库对照starter 与 solution 的差距即 harness 的差距原文档用一张表格概括了两个目录的分工仓库根路径下对应实现为projects/project-06/starter与projects/project-06/solution目录内容对比观察点starter/产品代码基本完整但 harness 表面被刻意削弱只有基础版AGENTS.md没有feature_list.json、没有session-handoff.md、没有干净状态清单、没有基准/清理脚本用弱 harness 做手动基线观察solution/完整 harnessAGENTS.md、CLAUDE.md、feature_list.json、init.sh、session-handoff.md、clean-state-checklist.md、质量/评估者文档与脚本运行scripts/benchmark.sh和scripts/cleanup-scanner.sh对比质量证据项目英文 README 中的 “Exact Task Contract” 给出了更精确的差距表领域starter 状态solution 证据产品行为导入、索引、QA、历史、反馈、重置基本齐全相同功能 更强的校验与持久化证据Harness 文件仅基础AGENTS.md无 feature_list、无 handoff、无干净状态清单AGENTS.md、CLAUDE.md、feature_list.json、init.sh、session-handoff.md、clean-state-checklist.md质量跟踪只有初始quality-document.md高评分quality-document.md、evaluator-rubric.md基准测试无基准/清理脚本scripts/benchmark.sh、scripts/cleanup-scanner.sh、scripts/check-architecture.sh可靠性文档文档极简docs/ARCHITECTURE.md、docs/PRODUCT.md、docs/RELIABILITY.md结论很直接starter 与 solution 的产品功能几乎相同差距全部集中在“围绕代码的操作系统”上。不要指望 starter 里会出现 solution 才有的基准命令——弱 harness 运行要用人工记录基线观察solution 运行则使用检入的脚本。四、环境与工具清单按照原文档的 “Werkzeuge” 部分完成本项目需要AI Coding AgentClaude Code 或 Codex也可用 Cursor、Trae 等见项目总览Git管理仓库状态与版本Node.js Electron产品是 TypeScript React 的 Electron 桌面应用见projects/project-06/solution/package.json依赖 React 18、Electron 33、Vite 6、Vitest 2质量文档模板对应 solution 中的quality-document.md评估者 Rubric对应evaluator-rubric.md前五个项目的全部 harness 组件初始化、特征清单、交接、干净状态、运行时反馈等机制。五、完整 Harness 的组成9 个关键文件逐个拆解solution 目录的顶层就是完整的 harness 资产。下面按“Agent 会话生命周期”顺序逐一说明其作用与源码证据。5.1 AGENTS.md启动规则与边界约定AGENTS.md定义了 Agent 开工前的强制顺序完整读本文件 → 读CLAUDE.md速查 → 读docs/ARCHITECTURE.md→ 读docs/PRODUCT.md→ 读docs/RELIABILITY.md→ 运行bash init.sh验证构建 → 读feature_list.json查看特征现状。它还规定了 Electron 四层边界主进程src/main/BrowserWindow 生命周期与 IPC 注册所有文件系统访问Preloadsrc/preload/唯一的主-渲染桥用contextBridge.exposeInMainWorld暴露类型化 API渲染进程src/renderer/React TypeScript只通过window.knowledgeBase通信绝不导入 Node.js 模块服务层src/services/主进程内的纯 TypeScript 业务逻辑构造函数注入PersistenceService全部使用logger.forService()输出结构化 JSON。“Definition of Done” 要求TypeScript 编译零错误npm run check、窗口可见、特征在feature_list.json中标记pass且有证据、遵守层边界、结构化日志覆盖所有服务操作、更新对应文档、clean-state-checklist.md全部通过。5.2 CLAUDE.md速查表与 14 条 IPC 通道CLAUDE.md是给 Claude Code 的快速参考包含构建命令npm install/npm run check/npm run build/npm run dev/npm test、关键文件索引和完整的 IPC 通道表。通道命名遵循namespace:action模式全部集中在src/shared/types.ts的IPC_CHANNELS常量中作为单一事实来源通道方向用途documents:list/documents:import/documents:get/documents:deleteR → M文档列表、导入、按 ID 获取、删除indexing:start/indexing:status/indexing:chunksR → M开始索引、索引状态、取某文档的 chunksqa:ask/qa:history/qa:clear-historyR → M提问、历史、清空历史feedback:submit/feedback:listR → M提交反馈、列出反馈app:resetR → M重置全部数据app:statusR → M获取应用状态对应实现见src/main/ipc-handlers.ts14 个 handler 全部带日志写操作用 INFO、读操作用 DEBUG与src/preload/preload.ts暴露documents、indexing、qa、feedback、app五个命名空间。5.3 feature_list.json15 项特征的可量化证据feature_list.json记录了 15 项特征window-launch、document-list、document-import、document-detail、text-indexing、grounded-qa、conversation-history、feedback-collection、structured-logging、clean-state-reset、persistence、status-bar、benchmark-scripts、cleanup-scanner、full-harness每项都有status: pass与具体的evidence字段。例如text-indexingIndexingService.chunkDocument()按段落边界切分CHUNK_SIZE500grounded-qaQaService.ask()对问题分词、按关键词重叠打分、返回 top 2 引用有引用时置信度 0.85、无引用 0.30内置 8 条 mock 答案模式见src/services/qa-service.tsstructured-logginglogger.ts提供 DEBUG/INFO/WARN/ERROR 四级、JSON.stringify 输出、forService()子日志工厂5 个服务全部接入。5.4 init.sh开工前的五步验证init.sh在克隆或恢复工作时运行五步依次为npm install→npm run check类型检查→npm run build→ 验证 harness 文件存在AGENTS.md、CLAUDE.md、feature_list.json、clean-state-checklist.md、session-handoff.md、evaluator-rubric.md、quality-document.md、三份 docs、三个脚本→ 验证示例数据data/sample-documents/下三个文件。任何缺失都会以退出码 1 告警。5.5 session-handoff.md跨会话的可恢复状态session-handoff.md记录了上次会话2026-03-30完成的工作结构化日志模块、反馈管线、对话历史组件、干净状态重置、基准脚本与完整 harness 装配同时记录决策如“clean state 使用破坏性的 rmSync 而非选择性删除”“基准脚本用 bash 实现零依赖”与被修改的文件清单。这正是 Lektion 12 “每次会话留下干净交接状态”的落地产物。5.6 clean-state-checklist.md30 项检查清单clean-state-checklist.md覆盖七个类别共 30 项构建npm run check/build通过、架构渲染进程无fs/path导入、服务层无 Electron IPC、无 React 混入、运行时窗口启动、日志出现、导入/批索引/问答事件日志、日志JSON 可解析、含 timestamp/level/service/message、关键操作带 data、数据完整性无空 chunk、历史与反馈跨重启持久、性能3 个文件 1 秒内导入、示例数据 1 秒内完成索引、单问延迟 1 秒与仓库卫生无敏感数据、dist/不入库、交接文档更新。六、运行时可观测性结构化日志是第一等公民原文档把“Runtime-Beobachtbarkeit运行时可观测性”列为任务集核心能力之一solution 的实现证据集中在src/services/logger.ts与docs/RELIABILITY.md。6.1 日志格式与级别每条日志是单行 JSON 对象{ 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 } }级别使用规则logger.ts内部用LEVEL_ORDER数组实现过滤ERROR 走console.error、WARN 走console.warn、其余走console.log级别何时使用示例DEBUG例行数据访问、文件读取Retrieved chunks for documentINFO重要事件Document imported、Batch indexing completeWARN缺失但非致命数据Content not found for documentERROR失败File not found during import6.2 日志级别配置通过环境变量LOG_LEVEL控制默认 DEBUG见logger.ts末尾的new Logger((process.env.LOG_LEVEL as LogLevel) ?? LogLevel.DEBUG)LOG_LEVELINFO npm run dev # 仅 INFO、WARN、ERROR LOG_LEVELWARN npm run dev # 仅 WARN、ERROR LOG_LEVELERROR npm run dev # 仅 ERROR6.3 可观测点覆盖按docs/RELIABILITY.md的约定DocumentService 记录导入含 size 与元数据、删除含剩余数量、大小超限IndexingService 记录单文档/批量索引进度与吞吐指标QaService 记录答案生成confidence、citationCount、durationMs与反馈提交IPC handlers 记录每次通道调用并在启动时登记全部通道。这意味着从第一条日志就能重建整个文档生命周期——这正是“可调试”的基础。七、基准测试benchmark.sh 的四个任务scripts/benchmark.sh用零依赖的 bash 实现对服务层做文件级模拟无需启动 Electron 窗口set -euo pipefail严格模式四个任务Import把data/sample-documents/三个样例文件复制到临时目录并计时要求 ≥3 个文件Index按双换行切段估算 ~500 字符 chunk 数要求总 chunk ≥5Query对 5 个固定问题“What is the system architecture?” 等做关键词匹配计数并计时Verify核对三个样例文件导入前后字节数一致。最终输出 Summary: N/4 tasks passed 全部通过则exit 0并打印ALL BENCHMARKS PASSED否则exit 1。docs/RELIABILITY.md给出了预期目标导入 3 文件 1s、索引 14 chunks 1s、单问 500ms、数据完整性 0 错误quality-document.md记录的样例实测为导入 3 文档 200ms、批量索引 100ms、带引用的查询 300ms、干净状态重置 20ms。八、Cleanup 扫描cleanup-scanner.sh 的五项一致性检查scripts/cleanup-scanner.sh用于检测数据目录默认~/.config/knowledge-base/knowledge-base-datamacOS 为~/Library/Application Support/knowledge-base/knowledge-base-data也可传参指定中的陈旧/不一致产物检查内容孤儿内容文件有 content 文件但无对应文档元数据悬空 chunk 文件有 chunk 文件但无索引条目缺失内容文件元数据中存在但 content 文件缺失元数据不一致标记indexed却无 chunk 文件陈旧 QA 引用历史记录引用了已删除文档全部通过输出Result: CLEAN (0 issues found)发现问题时给出建议动作使用应用内 Reset 按钮 → 从data/sample-documents/重新导入 → 重跑扫描验证。配套的scripts/check-architecture.sh则用 grep 自动校验三层边界渲染进程无 Node 核心模块导入、服务层无 Electron IPC、services/main 无 React 导入。九、干净状态机制可重复实验的前提docs/ARCHITECTURE.md描述了数据目录布局documents-meta.json、content/doc-id.txt、documents/原始文件副本、chunks/doc-id.json、index/index-meta.json、qa-history.json、feedback.json。app:reset通道调用PersistenceService.resetAll()删除整个knowledge-base-data/并重建目录结构随后渲染进程清空 React 状态并刷新。docs/RELIABILITY.md明确何时必须用干净状态跑基准前、调试会话后、测试新功能前、数据目录损坏时。十、消融实验怎么判断哪个组件真正重要消融Ablation是原文档点名要求的收官动作在完整 harness 基础上每次只移除一个组件重跑同一套任务集与基准对比quality-document.md分数变化。可移除的候选组件按前文 5 类划分feature_list.json特征可见性、session-handoff.md跨会话连续性、clean-state-checklist.md质量门禁、init.sh启动验证、基准/清理脚本可量化反馈。例如移除cleanup-scanner.sh后残留的孤儿文件会在下一次基准的 Verify 任务中暴露移除feature_list.json后Agent 将失去对 15 项特征完成度的显式追踪倾向“过早宣布胜利”对应 Lektion 09 的主题。这正是把 harness 从“感觉有用”变成“证据可归因”的实验手段。十一、运行与复现步骤在仓库根目录按以下顺序复现实验npm run dev必须从projects/project-06/solution下执行它会先构建主进程与渲染进程再打开 Electron若构建报错先修复 TypeScript/Vite 错误窗口空白但无构建错误通常是缺少桌面会话的显示环境问题而非产品故障# 1) 弱 harness 基线手动观察 cd projects/project-06/starter npm install # 运行应用人工记录弱 harness 行为基线starter 故意不含 benchmark.sh / cleanup-scanner.sh # 2) 完整 harness安装并跑同一套基准 cd ../solution npm install npm run dev # 构建并启动 Electron 应用 # 3) 启动验证init.sh 五步检查 bash init.sh # 4) 架构边界检查 bash scripts/check-architecture.sh # 5) 干净状态检查 bash scripts/cleanup-scanner.sh # 6) 性能基准 bash scripts/benchmark.sh # 7) 对比 quality-document.md 分数变化每一步都应记录日志输出最终把feature_list.json的状态、quality-document.md的评分与evaluator-rubric.md当前 solution 记录为 5.0/5、15/15 特征 pass作为“完整 harness 优于弱 harness”的证据链。十二、结果解读与质量证据quality-document.md是 solution 的最终质量证据14 个维度中 13 项 A、测试覆盖 B总评 Aevaluator-rubric.md给出 5.0/5 总分并逐项核对了 9 个 harness 文件、3 份文档、14 条 IPC 通道。注意这些分数是仓库内检入的历史评估记录日期 2026-03-30复现时应以你自己的实测为准——这恰恰是 harness 的价值质量不再靠感觉而是靠可重复的检查清单、可解析的日志与可对比的基准分数。综上Project 06 用一套“完整 harness 可观测性 消融研究”的机制回答了课程的核心问题Agent 的可靠性上限不取决于提示词技巧而取决于围绕它构建的、可观测、可恢复、可量化、可维护的工程环境。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐Project 06 运行时可观测性与调试构建 Agent 完整 Harness 的 Capstone 实战指南learn-harness-engineeringProject 06 运行时可观测性与调试构建 Agent 完整 Harness 的 Capstone 实战指南learn harness engineerProject 06 终结项目实战为 Agent 构建可观测、可调试、可复现的完整 HarnessRuntime Observability Debugging CapstoneProject 06 终结项目实战为 Agent 构建可观测、可调试、可复现的完整 HarnessRuntime Observability Debuglearn-harness-engineering 终极项目实战构建带运行时可观测性与调试能力的完整 Agent HarnessCapstonelearn harness engineering 终极项目实战构建带运行时可观测性与调试能力的完整 Agent HarnessCapstone 本文是创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考