【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载导读本篇文章聚焦 learn-harness-engineering 课程中第十二讲《为什么每次会话都必须留下干净状态》的核心技术主题。你将学会如何把清洁状态clean state从一句口号变成可执行、可检查、可度量的 Harness 机制——包括五维退出检查清单、双模式清理策略、质量文档、幂等清理脚本以及由 benchmark-runner.ts 与 cleanup-scanner.ts 构成的可运行参考实现并结合 Project 06 完整工作环境 中的真实配置逐项落地。问题一个不干净的会话交接会吃掉下一个会话的前 30 分钟Agent 跑了一整个下午改了 20 个文件提交了代码然后会话结束。下一个会话启动时立刻发现构建坏了、测试红了、临时调试文件散落各处、功能清单和进度记录没有更新、进度完全不可见。新会话的前 30 分钟全部耗在搞清楚上一个会话到底做了什么上。OpenAI 与 Anthropic 都明确表达了同一结论长期可靠性取决于操作纪律而不是单次运行的成功。每次会话结束时的状态质量直接决定下一次会话的效率。这一讲要回答的问题就是如何让每个会话在退出时留下干净状态让下一个会话可以立刻开始干活。为什么熵增是默认状态Lehman 的软件演化定律指出一个持续变更的系统如果没有人主动管理复杂性必然增加。对 AI 编码 agent 来说这尤其成立——每次会话都会引入变更如果不在退出时清理技术债务会指数级累积。OpenAI 在 5 个月的 Codex 实验中观察到两个关键现象模式复制导致漂移agent 会复制仓库中已有的模式哪怕那些模式本身不一致或次优。第一个人放了一个杯子在公共区第二个人心想反正已经乱了也放一个一周后桌上堆满杯子——代码库的退化完全同构。人工清理不可扩展OpenAI 团队最初每周五花 20% 的工作时间手动清理 AI slop显然不可持续。他们最终沉淀出三管齐下的系统性方案把黄金规则写进仓库例如优先使用共享工具包不要手写 ad-hoc 辅助函数不要瞎猜数据结构查类型定义或使用类型安全的 SDK。这些规则必须是具体的、机械的、可自动检查的。建立周期性清理工作流一组后台 Codex 任务定期扫描偏离规则的代码、更新质量评分、自动开定向重构 PR大多数 PR 在一分钟内可审查并自动合并。把人类品味捕获一次持续执行评审意见、重构 PR、用户报告的 bug全部转化为文档更新或直接编码进检查工具文档不够用时把规则提升为可自动检查的代码。一句话总结技术债是高息贷款持续小额还款几乎总是好过攒成一次性爆雷。清洁状态远不止代码能编译构建通过只是底线。完整的清洁状态由五个维度组成缺一不可维度要求构建npm run build通过下一个会话不必先修别人的构建错误测试所有测试通过包括会话开始前就存在的旧测试验证必须发生在 CI不是在我机器上能过进度以机器可读工件记录三类信息已完成的子任务及通过标准、进行中但未完成的子任务及当前卡点、尚未开始的子任务工件调试日志、临时文件、注释掉的代码、TODO 标记全部清理干净启动标准启动路径可用环境初始化、代码库加载、上下文获取、任务选择任何一条断了新会话都无法自行启动原文档给出了两条互为镜像的流程图值得原样保留作为会话内审阅的检查标准干净交接的检查流功能工作完成 → 构建通过→ 测试通过→ 更新功能清单与进度 → 清理临时工件/调试代码 → 标准启动路径可用→ 干净交接任一环节失败则先修好再退出并回到构建正反两种会话结局的反馈回路脏退出 → 下个会话先诊断 → 在乱仓库上继续改 → 更乱 → 更脏干净退出 → 下个会话直接开写 → 无需救火 → 更稳定在五个维度里进度记录与临时工件这两条最容易偷懒也最伤下一个会话好的进度记录可以减少 60%80% 的会话启动诊断时间而一堆console.log(debug)和// 临时方案回头改会显著增加下一个会话的认知负担。六个核心概念清洁状态Clean state会话退出时必须同时满足五条件——构建通过、测试通过、进度已记录、无过时工件、启动路径可用。缺一个都不算做完。会话完整性Session integrity类比数据库事务——要么全部完成并留下清洁状态要么回滚到上一个一致状态不存在做了一半但还行的中间地带。质量文档Quality document持续记录每个模块质量评分的活动工件是追踪代码库在变强还是变弱的仪表盘而非一次性评估。清理循环Cleanup loop定期执行的维护会话系统性降低代码库熵。属于常规保养像定期换机油不属于紧急修复。Harness 简化Harness simplification随着模型能力提升定期移除不再必要的组件——今天必须的约束三个月后可能只是开销。幂等清理Idempotent cleanup清理操作无论执行多少次结果都一样保证失败重试时依然安全。以后再清理等于永远不清理最常见的心理陷阱是这次来不及了下次再弄。但下次的 agent 不知道你留下了什么它必须花大量时间推断哪些代码是有意的、哪些是临时的。更糟的是新会话有自己的任务目标它不会清理旧账而是直接在混乱之上开始新工作再引入更多混乱——这是熵增的正反馈循环。原文档给出的 12 周实测对比使用 agent 持续开发的项目两组配置完全相同唯一变量是有无清理策略无清洁策略时间构建通过率测试通过率新会话启动时间第 1 周100%100%5 分钟第 4 周95%92%15 分钟第 8 周82%78%35 分钟第 12 周68%61%60 分钟有清洁策略时间构建通过率测试通过率新会话启动时间第 1 周100%100%5 分钟第 12 周97%95%9 分钟12 周后两组构建通过率相差 29 个百分点测试通过率相差 34 个百分点新会话启动时间相差 85%。这些数字来自原文档所述的实际观察并非理论推演。怎么做六步落地清洁状态1. 把清洁状态写进完成的定义在 Harness 里明确定义会话完成 任务通过验证 AND 清洁状态检查通过。在 CLAUDE.md 或 AGENTS.md 中写下退出检查清单## Session Exit Checklist - [ ] Build passes (npm run build) - [ ] All tests pass (npm test) - [ ] Feature list updated - [ ] No debug code remaining (console.log, debugger, TODO) - [ ] Standard startup path available (npm run dev)仓库给出了一个远超五行的生产级范例projects/project-06/solution/clean-state-checklist.md 把检查项展开为八个板块——Build、Architecture、Runtime、Logging、Data Integrity、Performance、Repository、Scripts——总计约 40 个可勾选项例如Build 板块要求npm run check无类型错误、npm run build成功、无未使用变量/导入告警Architecture 板块要求 renderer 代码src/renderer/不得导入fs/path、服务代码不得出现 Electron IPC、所有 IPC channel 定义在src/shared/types.tsRepository 板块要求feature_list.json反映真实功能状态、session-handoff.md在会话结束时更新、claude-progress.md记录当前状态Scripts 板块要求cleanup-scanner.sh报告无过时工件、benchmark.sh跑完全部任务套件、init.sh通过全部验证。为什么必须有功能清单feature list功能清单是一份机器可读文件记录每个功能项的三列信息——这个功能做什么、用什么命令验证、当前状态未开始/进行中/已阻塞/已通过。调度器靠它选下一个工作验证器靠它判断做完没有交接器靠它生成进度报告。没有清单agent 会用自己那套几乎必然更低的标准判断完成。仓库中的真实样例见 projects/project-06/solution/feature_list.json每个条目包含id、name、description、statuspass/in-progress/blocked/not-started、evidence与testedAt时间戳例如window-launch的 evidence 写明main.ts 创建 1200x800 BrowserWindowcontextIsolationtrue、nodeIntegrationfalse让下个会话无需重新考古。2. 双模式清理策略把清理拆成两种模式配合使用即时清理每个会话结束时清掉本次会话创建的临时文件、更新功能清单状态、确保构建和测试全绿。原则是用完就清像引用计数一样谁产生的垃圾谁负责。定期清理每周一次全面系统扫描处理累积的结构性问题、更新质量文档、跑基准测试检测漂移。原则是定期全身体检不让小问题拖成大病。原文档的 cleanup-loop.md 给出了清理循环的任务清单扫描过时文档、扫描结构违规、更新质量评分、开定向清理 PR、清理后重跑固定基准切片。这五步正是定期清理的落地骨架。3. 维护质量文档质量文档是持续更新的评分文件新会话一打开就知道每个模块的健康状况并优先处理评分最低的模块。模板# Quality Document ## User Authentication Module (Quality: A) - Verification passing: Yes - Agent understandable: Yes - Test stability: Stable - Architecture boundaries: Compliant - Code conventions: Followed ## Payment Module (Quality: C) - Verification passing: Partial (payment callback untested) - Agent understandable: Difficult (logic spread across 3 files) - Test stability: Unstable (2 flaky tests) - Architecture boundaries: Violations present - Code conventions: Partially followed质量文档本质上是 Harness 可观测性的一部分——它把 agent 的运行结果在代码库层面变得可见对应第十一讲的主题。4. 定期简化 HarnessHarness 里每个组件的存在都源于模型在某个方面还无法独立完成模型能力演进后这些前提会过时。Anthropic 的实验是直接证据最初为了 Sonnet 4.5 而引入的 sprint 拆分机制在 Opus 4.6 能自主做工作分解后就成了多余开销移除后 builder agent 反而能连续工作两小时以上不跑偏。但 evaluator 是反例——即便 Opus 4.6 能力更强当任务逼近模型能力边界时evaluator 仍能抓住缺失功能和 stub 实现。结论是要不要保留某组件取决于任务难度与模型能力的相对位置而不是一刀切。推荐做法每月挑一个 Harness 组件暂时禁用跑基准任务。结果不退化就永久移除退化就恢复或换更轻量的替代。更深层的原则是模型变强Harness 中有趣的组合没有减少而是在位移——旧问题被模型吸收新能力边界又打开新的设计空间。5. 清理操作必须幂等清理失败时你会重跑一遍因此清理脚本必须幂等执行一次与执行一百次结果相同。# 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 anything6. 高吞吐量下调整合并哲学当 agent 每天开出 3.5 个甚至更多 PR 时减少阻塞型合并门禁是正确选择PR 应当短命测试 flake 用后续运行修正而不是无限期卡住进度。判断标准是修 bug 的平均成本 vs 等待人工审查的平均成本——当前者低于后者时快合并 快修复优于慢确认。注意前提这条规则只在高产出环境成立低吞吐环境里快速合并没有意义。参考实现一benchmark-runner.ts —— 用固定基准切片检测漂移原文档配套代码 benchmark-runner.ts 提供了一个可直接运行的基准执行器用于支撑清理后重跑固定基准切片与练习 2 的对照实验。它模拟执行一组基准任务并输出对比报告核心结构如下任务定义BenchmarkTask接口包含id、name、category、passCriteria通过标准数组、expectedDurationMs期望耗时与模拟的actualDurationMs/actualPass。内置 8 条任务覆盖四类场景文档导入管道markdown/PDF 导入、QA 管道含无相关文档时的优雅降级、安全并发用户隔离、API 限流与可靠性重启后会话连续性。执行模拟executeBenchmark()把每条任务映射为BenchmarkResult统计criteriaPassed/criteriaTotal、计算durationDelta实际-期望耗时差。报告输出表格列出每条任务的 ID/名称/类别/通过与否/标准达成数/期望与真实耗时/偏差对失败任务单独输出failureReason例如 PDF text extraction failed on page 3 -- encoding issue、Model hallucinated a citation instead of saying no results、跨用户数据泄露 超 SLA最后按类别聚合通过率并给出总体通过率。运行方式仓库内相对路径npx tsx docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/benchmark-runner.ts这套切片的用法契合第十二讲的核心实践把关键路径编码为带通过标准与期望耗时的固定任务集每次清理循环后重跑任何actualPass: false或耗时漂移都是代码库在退化的早期信号。配套的 benchmark-comparison-template.md 给出了两种 Harness 配置的对照模板completion rate、average retries、bugs caught before human review并提示回答两个问题哪个 Harness 改变了结果哪个 Harness 改变了获得结果的成本参考实现二cleanup-scanner.ts —— 过期工件与违规扫描器配套的 cleanup-scanner.ts 是即时清理与定期清理共用的扫描器用 Node 原生fs/path实现无需第三方依赖。它把扫描项组织为八类检查每项带严重级别critical/warning/info与描述类别检查项严重级Stale Artifacts*.tmp/*.bak/*.swp/~临时文件warningStale Artifacts源码目录src/、lib/、app/中的.log调试文件warningDead Codesrc/lib/app中.ts/.tsx/.js文件前 50 行内的TODO:/FIXME:/HACK:/XXX:标记infoStructural Violations缺少.gitignorewarningStructural Violationssrc/dist、src/build等编译产物混入源码criticalStructural Violationssrc/lib/app/test下的嵌套node_modulescriticalSession CleanlinessWIP.md/IN_PROGRESS.md/scratch.ts/debug.ts/temp.ts等未完成会话痕迹infoSession Cleanliness空的src/lib/app/test/docs目录infoConfiguration源码中的.env/.env.local/.env.production/.env.staging可能含密钥critical扫描器实现要点findFiles()递归遍历时限制深度depth 4即停止并跳过node_modules/.git/dist/build/.next/coveragescanForPatterns()只读 TS/TSX/JS 文件且只看前 50 行避免把正文里提到 TODO误报。最终输出表格报告与汇总Critical/Warnings/Info/Clean 计数若存在 critical 问题会打印 ACTION REQUIRED全部干净则输出 Project is in a clean state.。# 默认扫描当前目录 npx tsx docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts # 或指定目录 npx tsx docs/en/lectures/lecture-12-why-every-session-must-leave-a-clean-state/code/cleanup-scanner.ts /path/to/project注意这是仓库为第十二讲提供的教学参考实现模拟执行 启发式扫描实际项目落地时建议把同样逻辑写入 CI 或项目脚本。生产级对照Project 06 的完整 Harness 面第十二讲不是孤立的理论——它直接支撑了 Project 06搭建一套完整的 agent 工作环境Capstone 项目。该项目的 solution 目录把本讲所有概念都变成了真实文件clean-state-checklist.md上文已拆解的生产级退出检查清单feature_list.json机器可读功能清单每个功能带 status/evidence/testedAtcleanup-scanner.sh面向应用数据目录的真实一致性扫描器检查五类问题——孤儿内容文件有 content 无 metadata、悬空 chunk 文件有 chunks 无 index 条目、缺失内容文件有 metadata 无 content、不一致元数据statusindexed 但无 chunk 文件、过期 QA 引用历史记录引用已删除文档。脚本输出 CLEAN 或 ISSUES FOUND后者给出推荐动作用应用内 Reset 清空数据 → 从data/sample-documents/重新导入 → 重跑扫描验证另有 benchmark.sh、check-architecture.sh 支撑构建/架构/性能维度以及 session-handoff.md 承载交接报告。与之对照starter 目录刻意只保留基础 AGENTS.md没有feature_list.json、没有session-handoff.md、没有清洁状态清单、也没有基准脚本——这正是第十二讲要展示的弱 Harness基线。你可以用两个脚本bash scripts/benchmark.sh与bash scripts/cleanup-scanner.sh跑出证据对比质量文档里的评分差异。核心要点清洁状态是会话完成的必要条件——它是完成定义的一部分不是可选的额外家务。五个维度缺一不可构建、测试、进度、工件、启动每一条都要在退出时显式检查不能靠感觉应该没问题。功能清单让 agent 知道做完的标准——没有清单agent 用自己的标准判断完成那个标准几乎一定更低。质量文档让代码库健康可追踪——知道哪里在退化才能主动修复不知道问题在哪就只能等它爆发。定期简化 Harness每月挑一个组件禁用后跑基准结果不退化就永久移除。以后再清理等于永远不清理熵增是默认方向只有主动清理能对抗它。每次多花五分钟是长期回报最高的投资。练习建议设计清洁状态检查表为你的代码库设计涵盖五个维度的会话退出检查表连续 5 个会话坚持执行记录每个维度的违反次数。基准对比实验用固定任务集分别跑要求清洁状态与不要求两种 Harness比较完成率、重试次数与漏网 bug 数可直接复用 benchmark-runner.ts 和 benchmark-comparison-template.md。Harness 简化实践禁用某个 Harness 组件跑基准决定保留、移除还是替换。质量文档入门为 35 个核心模块打分A/B/C/D并标注扣分原因连续 4 周每周更新观察质量走势。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐learn-harness-engineering 实战构建会话级清理循环Cleanup Loop让每个 Agent 会话都从干净状态开始learn harness engineering 实战构建会话级清理循环Cleanup Loop让每个 Agent 会话都从干净状态开始 本篇文章以绝区零一条龙自动化工具智能游戏辅助的完整解决方案绝区零一条龙自动化工具智能游戏辅助的完整解决方案 绝区零一条龙ZenlessZoneZero OneDragon是一款专为《绝区零》游戏设计的全自动辅助工构建 Harness 清理循环Cleanup Loop让每次 Agent 会话都从干净状态起步构建 Harness 清理循环Cleanup Loop让每次 Agent 会话都从干净状态起步 导读 本篇文章基于 learn harness engin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考