【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本文以 docs/ja/resources/openai-advanced/repo-template/docs/RELIABILITY.md 为骨架展开。该文件是 learn-harness-engineering 仓库中 Advanced Repo TemplateOpenAI 风格 agent-first 文档表面的核心组成部分用于定义系统正常且可重启这一状态的证明方式。读完本文你将掌握 RELIABILITY.md 的四个标准段落标准路径、运行时信号、黄金旅程、可靠性规则如何填写、如何与仓库内的init.sh、基准脚本、清理扫描器等落地工具互相印证并能在自己的 harness 项目中把可靠性从口头承诺变成可验证的仓库本地证据。一、RELIABILITY.md 在 Advanced Repo Template 中的定位Advanced Repo Template见 repo-template/index.md面向不仅需要最小 harness还需要 OpenAI 风格 agent-first 文档表面的项目。它的复制顺序明确要求将AGENTS.md与ARCHITECTURE.md复制到仓库根目录复制整个docs/目录树首先填写docs/PRODUCT_SENSE.md、docs/QUALITY_SCORE.md、docs/RELIABILITY.md三份文档在docs/exec-plans/active/中添加第一个活跃执行计划入口文件保持短小细节引导到链接文档。也就是说RELIABILITY.md 不是可选的补充材料而是模板初始化的第一批必填项之一。它与 AGENTS.md 的路由映射直接挂钩在 repo-template/AGENTS.md 的路由映射一节中docs/RELIABILITY.md被定义为运行时信号、基准测试与重启预期的权威来源原文ランタイムシグナル、ベンチマーク、再起動の期待値。当 agent 启动时读到 AGENTS.md就会沿路由跳转到 RELIABILITY.md据此判断当前仓库是否处于可继续工作的健康状态。因此RELIABILITY.md 扮演的角色是运行时的系统健康宪法它回答三个问题——系统怎么启动怎么证明它正常出了问题怎么诊断模板用四个段落把这三个问题固化下来。二、标准路径把启动、验证、运行、调试固化成四条命令原文档的标准路径段落给出了四个必须填写的命令槽位- ブートストラップ: [command] - 検証: [command] - アプリまたはサービスの起動: [command] - ランタイムのデバッグまたは検査: [command]即引导bootstrap、验证verification、启动start、运行时调试/检查debug/inspect。这四条路径构成了 agent 会话的标准入口也构成了 repo-template/AGENTS.md 启动工作流第 6 步执行本仓库的标准引导与验证路径的实际内容。任何一次会话开始agent 都应当按这四条命令的顺序把系统拉起来任何一条失败就说明仓库处于不健康状态必须先修复基线再增加新范围AGENTS.md 第 7 步明确要求基线验证失败时先修复基线再扩展范围。仓库中的模板脚本 docs/ja/resources/templates/init.sh 就是这四条路径的可执行载体。其核心结构如下#!/usr/bin/env bash set -euo pipefail ROOT_DIR$(cd $(dirname ${BASH_SOURCE[0]}) pwd) cd $ROOT_DIR # Replace these commands with the correct commands for your repository. INSTALL_CMD(npm install) VERIFY_CMD(npm test) START_CMD(npm run dev) echo Working directory: $PWD echo Syncing dependencies ${INSTALL_CMD[]} echo Running baseline verification ${VERIFY_CMD[]} echo Startup command printf %q ${START_CMD[]} printf \n if [ ${RUN_START_COMMAND:-0} 1 ]; then echo Starting the app exec ${START_CMD[]} fi echo Set RUN_START_COMMAND1 if you want init.sh to launch the app directly.对照 RELIABILITY.md 的四个槽位可以这样映射并填写RELIABILITY.md 槽位init.sh 中的对应实现填写建议引导bootstrapINSTALL_CMD(npm install)依赖同步项目依赖安装/环境初始化命令验证verifyVERIFY_CMD(npm test)基线验证测试、类型检查、lint 的组合命令启动startSTART_CMD(npm run dev)启动命令应用或服务实际启动命令运行时调试/检查debug脚本外补充日志查看、数据目录检查等诊断命令值得注意的三个实现细节set -euo pipefail任何一步失败立即退出保证引导失败被显式暴露而不是静默继续——这正是可靠性可证明的基石RUN_START_COMMAND环境变量默认只打印启动命令而不真正启动避免初始化脚本在 CI 或基准环境下意外拉起长期运行的进程需要真正启动时显式设置RUN_START_COMMAND1。这是一个启动与验证分离的刻意设计从脚本所在目录推导 ROOT_DIR 并cd保证无论从仓库哪个子目录调用命令都作用在仓库根上。在项目实际落地时projects/project-06/solution/docs/RELIABILITY.md 展示了这四条路径的已填写形态应用通过npm run dev启动验证由scripts/benchmark.sh与scripts/cleanup-scanner.sh承担调试则通过结构化日志LOG_LEVEL环境变量完成。三、运行时信号让健康状态可观测、可诊断原文档所需的运行时信号段落列出了四类信号启动与关键流程的结构化日志スタートアップとクリティカルフローの構造化ログ主要服务的健康检查主要サービスのヘルスチェック可用时慢路径的 trace 或计时数据遅いパスのトレースまたはタイミングデータ可恢复故障对用户可见的错误状态回復可能な障害のユーザーに見えるエラー状態这四类信号的共同原则是运行时故障必须能够从仓库本地的信号中诊断出来对应原文档可靠性规则第 2 条。agent 调试时不应当依赖人工猜测或外部黑盒而应当有结构化的、可 grep、可解析的信号。projects/project-06/solution/docs/RELIABILITY.md 给出了结构化日志的完整落地方案可直接作为填写模板的参考。其日志格式为单行 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 } }日志级别与使用场景的对应关系如下级别使用时机示例DEBUG常规数据访问、文件读取Retrieved chunks for documentINFO显著事件Document imported、Batch indexing completeWARN数据缺失但非致命Content not found for documentERROR失败File not found during import日志级别通过LOG_LEVEL环境变量配置LOG_LEVELINFO npm run dev # 仅 INFO、WARN、ERROR LOG_LEVELWARN npm run dev # 仅 WARN 和 ERROR LOG_LEVELERROR npm run dev # 仅 ERROR默认值为DEBUG输出全部消息。在信号覆盖面上project-06 对每个服务都定义了埋点位置PersistenceService覆盖目录初始化、文件读写DEBUG与干净状态重置WARNDocumentService覆盖导入、删除、元数据更新、文件缺失错误与大小限制违规IndexingService覆盖单/批量索引开始、逐文档进度、批量完成吞吐量与内容缺失警告QaService覆盖问题处理开始、带置信度与耗时的答案生成、反馈提交与历史清空IPC Handler 则在启动时注册所有通道并对每次通道调用按变更写 INFO、读取写 DEBUG的规则打日志。这就是启动与关键流程的结构化日志的完整答案每个服务的生命周期事件都有固定的日志点agent 排查哪一步失败时直接按服务名与级别过滤即可。健康检查与慢路径计时则落到下一节的黄金旅程与基准任务中。四、黄金旅程Golden Journey把正常定义成可重复的验证路径原文档黄金旅程段落要求列出若干条旅程[journey 1]、[journey 2]、[journey 3]并强调一条硬性约束各ゴールデンジャーニーには、反復可能な検証パスと明確な失敗シグナルが必要である。即每条黄金旅程都必须同时具备可重复的验证路径和明确的失败信号。这保证了系统正常不是一个主观判断而是一组可以随时重跑、且失败时能立刻定位到具体环节的检查序列。这正是 repo-template/AGENTS.md完成定义中所需验证确实被执行、证据被链接到计划或质量文档的检查对象。仓库中的基准脚本 projects/project-06/solution/scripts/benchmark.sh 就是一个黄金旅程的机械化实现。它以文件级仿真方式对服务层运行四个任务不依赖 Electron 窗口任务度量内容目标import文档导入吞吐3 个文件 1sindex批量索引速度14 个块 1squeryQA 响应延迟每题 500msverify数据完整性检查0 错误运行方式bash scripts/benchmark.sh输出示例 Benchmark Results [import] 3 files: 120ms (25.0 files/sec) [index] 3 documents: 80ms (175.0 chunks/sec) [query] 5 questions: 1250ms (250.0ms avg) [verify] Data integrity: PASS Summary: 4/4 tasks passed 这段输出的关键点在于每个任务都有可量化的失败判据。脚本用PASS_COUNT/FAIL_COUNT统计并通过Summary: N/4 tasks passed给出总体结论这就是明确的失败信号——任一任务未达标即视为该黄金旅程失败。同时脚本通过mktemp -d创建隔离工作目录、从data/sample-documents读取样本保证每次运行起点一致即可重复的验证路径。解释基准结果时仓库文档给出了对应排查方向导入慢检查文件大小与磁盘 I/O索引慢检查分块大小与段落边界查询慢检查块数量与关键词匹配验证失败运行scripts/cleanup-scanner.sh定位问题。把这四个任务写进 RELIABILITY.md 的黄金旅程段落时就应明确写出每条旅程的验证命令如bash scripts/benchmark.sh、通过标准如[import] 3 files 1s、失败信号如Summary: N/4 tasks passed中 N 4。五、四条可靠性规则把可靠性变成硬性约束原文档可靠性规则段落给出了四条规则这是 RELIABILITY.md 的灵魂。下面逐条展开并结合仓库证据说明如何落地。规则 1系统不能干净重启功能就不算完成システムがクリーンに再起動できない場合、機能は完了とはみなされない。这条规则把可重启提升为完成的必要条件。repo-template/AGENTS.md 的完成定义完整列举了五项条件目标行为已实现、所需验证已实际执行、证据已链接到计划或质量文档、受影响文档已更新、仓库能从标准启动路径干净重启。最后一项就是规则 1 的直接体现。对应的可执行检查清单见 docs/ja/resources/templates/clean-state-checklist.md# クリーン状態チェックリスト - [ ] 標準起動パスがまだ機能する。 - [ ] 標準検証パスがまだ実行される。 - [ ] 現在の進捗が進捗ログに記録されている。 - [ ] 機能状態が実際に合格しているものと未検証のものを反映している。 - [ ] 半完了のステップが未記録のまま残っていない。 - [ ] 次のセッションが手動修復なしに継続できる。翻译过来即标准启动路径仍可用、标准验证路径仍可执行、进度已记录、功能状态如实反映通过与未验证、没有未记录的半完成步骤、下一会话无需人工修复即可继续。任何一项不满足功能完成都不成立。这与 docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md 中的干净状态五维度构建、测试、进度、工件、启动相互印证构建可编译、全部测试通过包括会话前已有的测试、进度以机器可读工件记录、无残留临时工件、标准启动路径可用。讲稿还指出这次没时间清理、下次再说实际上等于永远不清理——因为下一个会话不知道你留下了什么只能看到混乱的代码与不确定的状态。规则 2运行时故障应能从仓库本地信号诊断ランタイム障害はリポジトリローカルのシグナルから診断可能であるべきである。这条规则要求诊断证据必须沉淀在仓库内而不是依赖 agent 的记忆或外部工具。projects/project-06/solution/scripts/cleanup-scanner.sh 是这一规则的最佳范例。该脚本扫描数据目录检查六类不一致工件检查项说明孤立内容文件无对应元数据的 content 文件悬空分块文件无对应索引条目的 chunk 文件缺失内容文件元数据存在但 content 文件缺失元数据不一致标记为已索引但没有 chunk 文件空数据文件本应有数据的 JSON 文件为空数组过期 QA 历史引用了已删除文档的历史条目运行方式支持传入数据目录参数bash scripts/cleanup-scanner.sh # 使用默认路径 bash scripts/cleanup-scanner.sh ./my-data # 显式指定数据目录输出示例 Cleanup Scanner [OK] No orphaned content files [OK] No dangling chunk files [OK] No missing content files [OK] All indexed documents have chunk files [OK] No stale QA references Result: CLEAN (0 issues) 每一条[OK]/[FAIL]就是仓库本地信号agent 在会话开始时运行它几秒钟内就能判断数据层是否健康无需人工排查。把这类脚本的路径写进 RELIABILITY.md 的调试/检查槽位就完整满足了规则 2。规则 3反复出现的故障模式应固化为基准或护栏繰り返される障害モードが現れた場合、ベンチマークまたはガードレールを追加する。这条规则要求把经验沉淀为机制。repo-template/AGENTS.md 的工作契约中有一致表述反复出现的审查反馈不要在聊天里重新解释而要提升为机械规则、检查或 linter。基准benchmark与护栏guardrail就是两类常见的固化形态基准把故障场景固化为可量化任务例如 projects/project-06/solution/scripts/benchmark.sh 的四个任务。当查询慢反复出现时query任务的 500ms 目标就是防止回退的护栏护栏把质量标准固化为评分与判定。见 docs/ja/resources/templates/evaluator-rubric.md它在实现完成后、最终批准前使用对准确性、验证、范围纪律、可靠性结果无需修复即可重启/重跑、可维护性、交接就绪六个类别逐项打分0–2并给出批准 / 修正 / 阻止三档判定。其中可靠性一栏直接对应 RELIABILITY.md 的主题结果是否经受得住重启与重跑。repo-template/docs/QUALITY_SCORE.md 则用 A–D 分级持续追踪各领域与各架构层的质量并附带基准快照表日期、harness 变体、完成率、重试次数、审查前缺陷数与简化日志表——这些表格正是规则 3 中护栏的长期记录载体。规则 4清理是可靠性的一部分而非独立的关注点クリーンアップは信頼性の一部であり、別個の関心事ではない。这条规则纠正了一个常见误区清理不是功能完成之后的附加工作而是可靠性的构成部分。docs/ja/lectures/lecture-12-why-every-session-must-leave-a-clean-state/index.md 给出了两种互补模式即时清理每次会话结束时清理会话中产生的临时工件、更新功能列表状态、确认构建与测试通过——引用计数型清理定期清理每周全系统扫描处理积累的结构性问题、更新质量文档、运行基准测试检测漂移——追踪型清理。同时清理操作必须是幂等的重复执行产生相同结果从而保证失败重试时清理依然安全。讲稿给出了幂等清理的示例# Idempotent cleanup operations rm -f /tmp/debug-*.log # -f ensures no error when files dont exist git checkout -- .env.local # Restore to known state npm run test # Verify cleanup didnt break anything注本仓库为只读镜像示例中的文件操作请在你自己的可写工作副本中执行。在 project-06 中清理能力的核心机制是RESET_DATAIPC 通道它删除整个数据目录knowledge-base-data/、重建目录结构、返回成功响应随后渲染进程清空 React 状态并刷新。文档明确给出了使用时机运行基准之前、调试会话之后、测试新功能之前、数据目录损坏时——全部是可靠性流程的中间环节而不是事后的额外步骤。六、模板落地三份文档的联动与初始化顺序RELIABILITY.md 不是孤立文件。在 repo-template/index.md 规定的初始化顺序中它与PRODUCT_SENSE.md、QUALITY_SCORE.md一起被要求首先填写。三者构成闭环PRODUCT_SENSE.md回答系统应该做什么产品行为与验收标准见 repo-template/docs/product-specs/index.md 的定位说明QUALITY_SCORE.md回答系统当前做得怎么样随时间追踪各领域评分与基准快照RELIABILITY.md回答系统是否健康、能否重启、如何诊断标准路径、信号、黄金旅程、规则。在 repo-template/AGENTS.md 的启动工作流中agent 的固定动作是确认仓库根目录 → 读ARCHITECTURE.md获取系统地图与依赖规则 → 读QUALITY_SCORE.md找出最弱领域 → 读PLANS.md打开活跃计划 → 读相关产品规格 →执行标准引导与验证路径→ 若基线验证失败则先修基线。其中执行标准引导与验证路径的内容来自 RELIABILITY.md而找出最弱领域来自 QUALITY_SCORE.md两者在会话一开始就决定 agent 的工作优先级。因此当你把 repo-template/docs/RELIABILITY.md 复制到自己的仓库时建议按以下顺序填写先写标准路径把真实的bootstrap、verify、start、debug四条命令填入并确保它们可由 docs/ja/resources/templates/init.sh 这类脚本一键串联执行再列运行时信号逐个服务枚举结构化日志点、健康检查端点、慢路径计时与用户可见错误状态参考 project-06 的日志格式与LOG_LEVEL方案然后定义黄金旅程写出 2–3 条覆盖主流程的验证路径每条附可重复的命令与明确的失败信号参考benchmark.sh的四任务模式最后落实四条可靠性规则把干净重启纳入完成定义对照 clean-state-checklist.md把诊断脚本、基准与护栏对照 evaluator-rubric.md的路径写进文档让清理成为可靠性流程的一部分。七、自检清单你的 RELIABILITY.md 是否合格写完之后可以用下面这份清单自检对应原文档四段落与四规则的完整覆盖标准路径四条命令都填了真实命令且能被 agent 原样执行引导失败时脚本能显式报错如set -euo pipefail运行时信号每个服务有固定的结构化日志点存在健康检查手段慢路径有计时或 trace可恢复故障对用户可见黄金旅程至少一条主流程旅程每条都有可重复的验证命令 明确的失败判据规则 1完成定义包含标准启动路径干净重启并有对应检查清单规则 2所有常见故障都能从仓库本地脚本/日志信号定位无需人工猜测规则 3反复出现的故障模式已固化为基准任务或评分护栏且记录在 QUALITY_SCORE.md 的基准快照中规则 4清理操作幂等已纳入会话结束与定期维护流程而非事后附加。对照 projects/project-06/solution/docs/RELIABILITY.md 可以看到这份已填写形态正是从模板出发把结构化日志、干净状态管理、基准测试与清理扫描器四大块完整落地的结果。它以 docs/ja/resources/openai-advanced/repo-template/docs/RELIABILITY.md 的四段框架为纲用仓库内真实的脚本与检查清单填充了全部细节——这也是你在自己项目中填写 RELIABILITY.md 时应当达到的完成度让系统正常且可重启不再是一句口号而是任何 agent 或人类都能按文档一步步验证、并随时从仓库本地信号诊断的硬事实。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐learn-harness-engineering 可靠性文档RELIABILITY.md编写指南如何让 Agent 系统自证健康与可重启learn harness engineering 可靠性文档RELIABILITY.md编写指南如何让 Agent 系统自证健康与可重启 导读 本指南以learn-harness-engineering 可靠性文档设计用 RELIABILITY.md 模板构建可证明健康、可重启的 Agent 工程体系learn harness engineering 可靠性文档设计用 RELIABILITY.md 模板构建可证明健康、可重启的 Agent 工程体系 导读RELIABILITY.md 实战指南为 Agent 优先仓库构建可证明健康、可重启的可靠性基座RELIABILITY.md 实战指南为 Agent 优先仓库构建可证明健康、可重启的可靠性基座 导读 本文围绕 learn harness engine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考