【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本篇是 learn-harness-engineering 教程中「Project 04: Runtime Feedback and Structural Control」的完整实战指南对应日文版 docs/ja/projects/project-04-incremental-indexing/index.md中文版 projects/project-04/README-CN.md。它承接 Project 03 的知识库应用教你为 Agent 补齐运行时可观测性启动日志、导入/索引日志、错误状态与层级边界约束防越界架构检查并在一个被刻意植入缺陷的索引服务上完成「诊断 → 修复 → 验证」的完整闭环。读完本文你将掌握结构化日志、分层架构护栏脚本、增量索引机制以及一套可复现的「同一任务跑两遍」的 Harness 实验方法。为什么 Agent 需要运行时反馈本项目的核心命题在 Project 0103 中我们已经验证了能力再强的 Agent 也会失败它看不见自己程序的运行时状态只能靠猜测。Project 04 直接把这个痛点做成了一门调试课——给 Agent 配上眼睛结构化日志和边界架构检查脚本再让它去修复一个被植入的运行时缺陷。相关讲义的论证是Agent 的失败常常源于任务边界模糊講義 07与缺乏约束的工作范围講義 08。Project 04 把这两条教训落成具体产物运行时反馈Runtime Feedback服务启动、文档导入、增量索引、QA 问答每个环节都输出机器可解析的 JSON 日志Agent 不再盲修范围控制Scope Control用check-architecture.sh强制 renderer / preload / main / services 四层各守其责Agent 的改动无法越界增量索引Incremental Indexing索引服务按文档粒度增量推进配合index-meta.json记录已索引状态让长任务可以分段收敛。这套组合正是本项目的Harness 机制ランタイムフィードバック スコープ制御 増分インデックス运行时反馈 范围控制 增量索引。任务总览同一份工作跑两遍原文档给出的任务非常明确——同一份工作执行两次第一遍对照组在没有任何日志与架构约束的环境下让 Agent 完成修复观察它要花多久才能抵达根本原因第二遍实验组在配有结构化日志、架构边界文档与检查脚本的环境下让同一 Agent 完成修复对比 logs 与 boundary checks 是否让修复更快、影响范围更小。这种A/B 对照正是 Harness 工程的核心方法论不靠口号判断工具链价值而是用可重复的实验数据说话。合格的解法必须有诊断证据日志输出、检查脚本通过记录而不只是口头声称修好了。动手前需要准备的环境原文档ツール一节工具用途Claude Code 或 Codex作为被测的编码 AgentGit记录变更、回滚实验、对比两遍结果Node.js Electron运行 Electron 知识库应用依赖见 solution/package.json含 react 18、electron 33、vite 6、vitest 2starter 与 solution一个弱信号起点 vs 一个护栏完备的参考实现仓库中项目位于 projects/project-04/包含两个可运行的完整切片目录包含什么实验要对比的量starter/基于 Project 03 的代码诊断信号弱IndexingService中被植入了 indexing 缺陷超过 1000 字符的大文件 chunking 会被破坏没有架构检查脚本在没有运行时信号的情况下Agent 抵达根本原因所需的时间solution/结构化 logger、架构边界文档与检查脚本、已修复的 chunking 逻辑、clean-state-checklist.mdlogs 与 boundary checks 是否让修复更快、影响范围更小两者的差异可以精确对应到具体文件对照 README-CN.md 的任务对应表功能 / 产物starter 状态solution 证据结构化日志无共享 logger 服务仅零散console.logsrc/services/logger.ts 及 main、ipc-handlers、各 services 中的日志调用导入/索引诊断运行输出难以定位失败导入、索引开始/完成、QA 失败路径的结构化日志架构边界无脚本检查 renderer/main/service 越界scripts/check-architecture.sh、docs/ARCHITECTURE.md、AGENTS 边界规则植入的 chunking bug大文件可能产生空 chunk修复后的 src/services/indexing-service.ts干净交接无最终检查清单clean-state-checklist.md提示solution 刻意保持比后续项目更精简的 Harness。按 AGENTS.md 的说明本项目不包含feature_list.json、claude-progress.md、init.sh、session-handoff.md——那些产物在更后面的项目阶段才引入。做本项目时不要臆造这些文件存在。运行时可观测性落地解剖结构化 Logger原文档点名要重点研读 projects/project-04/solution/src/services/logger.ts。它是本项目运行时反馈的基石把原来不可解析的散乱输出统一为带时间戳、分级、可 JSON 解析的日志条目。核心设计如下对照源码逐段解读四个日志级别DEBUG、INFO、WARN、ERRORLogLevel枚举源码 L9-L14并按LEVEL_ORDER定义优先级顺序L26-L31日志条目结构LogEntryL16-L22timestampISO 8601、level、service服务名、message、可选data任意结构化字段Recordstring, unknown级别过滤shouldLog()用级别序号比较低于最小级别默认DEBUG的日志直接丢弃避免噪音淹没信号L37-L41按级别分流输出emit()中ERROR走console.error、WARN走console.warn、其余走console.log且全部输出 JSON 字符串L43-L56保证 stdout/stderr 都能被工具链如grep、jq继续消费服务级子 loggerforService(name)返回ServiceLogger让每个服务只传消息与数据、自动带上服务名L91-L121例如IndexingService内部持有logger.forService(IndexingService)可配置最小级别单例logger从环境变量LOG_LEVEL读取最小级别缺省DEBUGL123-L126意味着可以用LOG_LEVELERROR npm run dev一键压噪或LOG_LEVELDEBUG全量观测。// 实际调用形态摘自 solution 各服务 this.log.info(Indexing document, { docId: doc.id, title: doc.title, contentLength: content.length }); this.log.error(Document content not found, { documentId });这种每条日志都自带 service 结构化 data的做法直接服务于 AGENTS.md 的调试指引排查时检查服务初始化事件、IPC 调用及其参数、索引 chunk 数与内容长度、QA 置信度与 citation 数量。架构约束四层边界与 check-architecture.sh 源码拆解ARCHITECTURE.md 定义的四层模型docs/ARCHITECTURE.md 把 Electron 应用明确划分为四层自顶向下Renderer (React UI) → Preload (contextBridge) → Main Process (IPC Handlers) → Services (Business Logic) → Persistence (Filesystem)每层职责与红线不可越界层职责约束MUST NOTRenderersrc/renderer/渲染 React 组件、处理用户输入、通过window.knowledgeBaseAPI 与主进程通信不得 importfs/path/os/child_process等 Node 核心模块不得直接访问 Electron API不得承载业务逻辑Preloadsrc/preload/用contextBridge.exposeInMainWorld暴露类型化 API映射 IPC 通道名不得包含业务逻辑不得直接 import services只用ipcRenderer.invokeMain Processsrc/main/创建管理 BrowserWindow、注册 IPC handler 并委托给 services不得承载路由之外的业务逻辑不直接访问持久化层Servicessrc/services/实现全部业务逻辑文档管理、索引、QA不得 import Electron APIipcMain、BrowserWindow等不得 import React所有文件系统访问必须经PersistenceService所有 IPC 通信的通道名收敛在 src/shared/types.ts 的IPC_CHANNELS常量单一事实来源例如documents:list、documents:import、indexing:start、indexing:chunks、qa:ask等。数据流方向固定Renderer 调用window.knowledgeBase.*→ Preload 转成ipcRenderer.invoke(channel, ...)→ Main 的 IPC handler 委托给 service → service 经PersistenceService落盘 → 结果沿 IPC 返回渲染层。check-architecture.sh 的三种越界检查scripts/check-architecture.sh 用纯 bash 实现了架构护栏set -euo pipefail保证失败即退出退出码 0 全部通过1 存在违规。它做三件事检查 renderer 是否 import Node 核心模块遍历src/renderer下所有.ts/.tsx用grep -qE import.*\b(fs|path|os|child_process)\b命中即记为违规L21-L33检查 services 是否触碰 Electron遍历src/services下.ts既查import ... from electron也查ipcMain、ipcRenderer、BrowserWindow关键字L36-L56检查 services/main 是否 import React遍历src/services src/main下的.ts命中import ... from react即违规L59-L74。脚本末尾汇总违规数并按结果exit 0/1L78-L85因此它可以无缝挂进 CI 或 Agent 的 pre-commit 流程。这正好把 ARCHITECTURE.md 文档化的规则变成了可执行、可证伪的检查——Agent 想偷偷越界脚本会当场拦下。bash scripts/check-architecture.sh # 期望输出PASS: All architecture boundary checks passed退出码 0植入缺陷分析1000 字符魔咒与增量索引的修复对比starter 中被植入的 bug对比 starter/src/services/indexing-service.ts 与 solution 版本缺陷藏得很自然chunk 生成逻辑里悄悄加了一个条件——当content.length 1000时把 chunk 内容置为空字符串// starter 版本中的缺陷L106-L119 const chunkContent content.length 1000 ? : buffer.trim();后果是任何超过 1000 字符的文件索引后产出的 chunk 全是空内容。空 chunk 会沿检索链向下传导——QA 的关键词匹配拿不到任何命中、citation excerpt 为空、答案置信度骤降。而 starter 只有零散的console.log日志中chunkDocument produced N chunks看起来一切正常Agent 若无运行时信号极难定位到问题出在大文件的分块内容被清空。solution 的修复与增量索引机制solution/src/services/indexing-service.ts 的修复版删除了那个三元条件chunk 内容始终取真实文本分块策略CHUNK_SIZE 500约 500 字符先按/\n\s*\n/空行拆成段落、过滤空白段落再贪心合并段落直至接近 500 字符边界L110-L146每个 chunk 携带元数据createChunk记录charCount与wordCountL148-L159日志里也输出totalChars总和用于校验分块完整性L139-L143增量索引startIndexing()支持按单个documentId增量索引批量模式读取documents-meta.json与index-meta.json只处理尚未记录在chunksMeta中的文档if (chunksMeta[doc.id]) continue;L53-L54索引结果写入chunks/docId.json并把 chunk id 列表登记回index-meta.json——这样重复运行不会重复消费已索引文档长任务天然可断点续跑状态机getStatus()依据已索引数 文档总数推导idle | indexing | ready | error四种状态供 UI 与日志同步展示L75-L89。修复版还在每个关键节点埋了结构化日志批量开始记录 totalDocs / alreadyIndexed、单文档索引记录 contentLength / chunkCount、内容缺失跳过WARN 级让 Agent 从日志就能判断这个文档到底有没有被正确分块。QA 侧的可观测锚点qa-service.ts 是缺陷的受害方也提供了诊断信号检索时按查询词与 chunk 内容的包含关系打分、取 Top 2 作为 citationL66-L98每次回答都记录confidence、citationCount、answerLength到结构化日志L111-L115。当答案置信度低、citation 数量为 0 时日志会直接指向索引层产出异常——这正是运行时反馈驱动定位的完整演示链路。完整复现步骤把两遍实验跑起来按照 README-CN.md 与 AGENTS.md 的启动工作流# 第一遍弱信号环境 cd starter npm install npm run dev # 观察Agent 能否仅凭 console.log 定位 chunking bug # 导入一个大文件1000 字符观察分块结果异常空 chunk # 第二遍带护栏环境 cd ../solution npm install npm run dev # 对比结构化日志如何加速诊断每个会话的标准验证命令solution 内npm run check # tsc 双 tsconfig 类型检查 npm run build # tsc -p tsconfig.node.json vite build bash scripts/check-architecture.sh # 架构边界护栏必须 PASS npm run dev # 启动应用确认结构化日志出现在控制台复现要求修复前后都用长文档各复现一次保留日志证据导入事件、索引 chunk 数、QA 置信度证明诊断证据存在而不只是声称修复通过。干净的交接clean-state-checklist 与 AGENTS 工作流本项目强调Session 结束时仓库必须可重启、可交接。清单 clean-state-checklist.md 按五组核对构建npm run check无类型错误、npm run build成功架构bash scripts/check-architecture.sh零违规、renderer 无 Node 核心模块 import、services 无 Electron IPC、services/main 无 React import运行时应用无错启动、启动时出现结构化日志、文档导入正常日志含 IMPORT_DOCUMENT 事件、各种大小的文档索引正常、QA 返回带 citation 的答案日志含 ASK_QUESTION 事件数据完整性已索引文档无空 chunk用 GET_CHUNKS 验证、QA 历史跨重启持久化、文档元数据与实际文件一致仓库git status 无意外文件、无敏感数据入库、最终总结记录当前状态/验证记录/未决风险、AGENTS.md / ARCHITECTURE.md / 本清单与实际文件保持一致。配套的 AGENTS.md 还定义了长期运行 Agent 的操作纪律动手前先跑启动工作流pwd→ 读 ARCHITECTURE.md →git log --oneline -5→npm install→npm run check→ 架构检查一次只做一个功能不静默改动验证规则优先把结论沉淀为仓库内持久产物而非聊天摘要。其Definition of Done明确要求目标行为已实现 验证确实运行过 证据已记录 仓库可从标准路径重启 架构检查通过这正是避免 Agent 过早宣布胜利对应 講義 09 的主题的工程化落地。关键文件速查关注点路径项目说明与 A/B 任务projects/project-04/README-CN.md结构化日志实现projects/project-04/solution/src/services/logger.ts架构边界文档projects/project-04/solution/docs/ARCHITECTURE.md架构检查脚本projects/project-04/solution/scripts/check-architecture.sh已修复的增量索引projects/project-04/solution/src/services/indexing-service.ts植入缺陷的对照组projects/project-04/starter/src/services/indexing-service.ts检索与 citation 日志锚点projects/project-04/solution/src/services/qa-service.tsIPC 通道与共享类型projects/project-04/solution/src/shared/types.ts会话交接清单projects/project-04/solution/clean-state-checklist.mdAgent 运行纪律projects/project-04/solution/AGENTS.md关联讲义講義 07エージェントのタスク境界を明確に引く · 講義 08機能リストでエージェントの作業を制約する。小结Project 04 用一次可重复的 A/B 实验证明了 Harness 的核心主张——Agent 的修复速度与准确度取决于它能否看见运行时真相、能否被边界约束住。结构化日志提供反馈架构脚本提供约束增量索引提供可控的推进粒度三者合一才是让长运行 Agent 从猜测式编码走向证据驱动修复的最小闭环。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐learn-harness-engineering Project 04 实战用运行时反馈与架构约束修正 Agent 行为learn harness engineering Project 04 实战用运行时反馈与架构约束修正 Agent 行为 本项目Project 04 ·learn-harness-engineering 项目 04用运行时反馈修正 Agent 行为——结构化日志、架构约束与增量索引实战learn harness engineering 项目 04用运行时反馈修正 Agent 行为——结构化日志、架构约束与增量索引实战 本篇技术指南以仓库 dHarness 实战用运行时反馈与架构约束纠正 Agent 行为——learn-harness-engineering Project 04 增量索引调试指南Harness 实战用运行时反馈与架构约束纠正 Agent 行为——learn harness engineering Project 04 增量索引调试指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考