【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载导读本仓库第 05 讲docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/index.md回答了一个所有 AI 编程 Agent 团队都会遇到的核心问题为什么一个能干 30 分钟的 Agent 在下一次会话中会失忆、重复劳动甚至推翻之前的正确设计本篇文章以该讲配套的 会话交接示例 为骨架完整讲解交接文件handoff file的结构、原理与落地方式读完你将掌握如何用已完成 / 已损坏或未验证 / 下一步最佳行动三段式模板加上 PROGRESS.md、DECISIONS.md、Git 检查点与初始化脚本把新会话的恢复成本从 15 分钟压缩到 3 分钟并结合本仓库 project-03 的真实实现验证这套方法。一、为什么长时任务必然丢失连续性先理解问题再谈解决方案。本仓库第 05 讲开篇用一个类比切入想象一位每天早上醒来就失忆的工匠——他得重新认识整座工地哪面墙没砌完、为什么选红砖而不是蓝砖、水管修到了哪一步更糟的是他可能因为不记得昨天已经装好了窗户而把它拆掉。AI Agent 在跨会话的长任务中正是处于这种状态。1.1 上下文窗口是有限资源上下文窗口再大也是有限的。即便窗口扩大到 1M token复杂任务依然会耗尽它因为 Agent 消费上下文的速度远超窗口扩容的速度它要读代码库、追踪自己的决策历史、处理工具输出、维持对话上下文。第 05 讲明确指出窗口耗尽之后只有两条路压缩compaction在同一会话内对早期对话做摘要。它保住了做了什么what但常常丢掉为什么这么做why——为什么选方案 B 而不是 A、为什么跳过某个优化。下一会话看到代码却不懂代码背后的意图可能把一次深思熟虑的设计决策优化掉。重置reset清空上下文、开新会话从保存的状态工件中恢复。它带来干净的心理状态但完全依赖交接工件是否完整。1.2 连续性断裂的四种典型代价第 05 讲总结了没有连续性工件时每个新会话都会遭遇的问题决策重复上一会话花了大量上下文比较三个方案才选中 B新会话对此一无所知基于残缺信息重新决策可能改选 A——就像失忆的工匠看着蓝砖觉得更好看把昨天的红砖墙拆了重砌。工作重复Agent 不确定某项工作是否已完成于是再做一遍或者做了一半才发现与现有实现冲突被迫返工。方向漂移drift每个新会话对项目目标的理解都略有偏差几个会话之后实现方向已经悄悄偏离原始需求如同传话游戏里帮我买杯咖啡传成帮我买台咖啡机。验证空白上一会话的验证结果哪些测试通过、哪些失败、为什么失败没有被记录新会话只能从头重跑全部验证来理解现状每个会话都在消耗宝贵的上下文做重复诊断。二、核心工件最小交接文件 session-handoff.md解决之道不是更大的窗口而是更好的状态保存。第 05 讲把思路概括为一句话把 Agent 当作天才但失忆的工程师——它在下班前必须写下关键信息让下一个接班的 Agent 能快速接手。而最基础的接班记录就是交接文件。本仓库在 code/session-handoff.md 里提供了一个最小化交接文件示例俄语原文完整内容如下# Пример Session Handoff 会话交接示例 ## Сделано 已完成 - Добавлена поддержка импорта markdown 新增了 markdown 导入支持 - Добавлен базовый список документов в renderer 在 renderer 中加入了基础文档列表 ## Сломано или не проверено 已损坏或未验证 - Импорт работает для .md, но падает на больших .txt файлах 导入对 .md 可用但大 .txt 文件会崩溃 - Приложение запускается, но детальное представление не подключено 应用能启动但详情视图尚未接入 ## Следующий лучший шаг 下一步最佳行动 - Починить путь импорта .txt 修复 .txt 导入路径 - Проверить импорт сквозно 端到端验证导入流程 - Затем добавить панель деталей документа 随后添加文档详情面板2.1 三段式结构的用意这个例子虽然只有 17 行却精准对应了新会话接管工作所需的全部信息章节回答的问题对下一会话的价值已完成Сделано上次会话做完了什么避免重复劳动新会话可直接判断自己该从哪接手已损坏或未验证Сломано или не проверено哪里是坏的、哪里还没验证提供已知问题清单防止新会话误把半成品当成品也防止它在不知道细节视图未接入的情况下假设它已可用下一步最佳行动Следующий лучший шаг现在最该做什么新会话无需读旧聊天日志即可获得明确的行动指令直接开工注意示例中的措辞非常克制写的是导入对 .md 可用但大 .txt 文件会崩溃事实陈述而不是修复导入含糊的目标下一步行动被拆成了可逐一验证的小步骤。这正是交接文件与普通会议纪要的本质区别——交接文件的每一行都必须能驱动一个可执行的、可验证的动作。2.2 为什么这三段刚好够用从第 05 讲的连续性框架看三段恰好覆盖了新会话重建上下文所需的三个维度已完成对应进展progress让新会话知道墙砌到哪了已损坏或未验证对应验证verification让新会话知道哪些测试可能红、哪些功能只是半成品下一步最佳行动对应行动action让新会话不必从零规划。如果新会话只拿到代码本身它看到的只有什么而交接文件补上了为什么做到这一步和接下来去哪。三、用仿真验证交接文件的价值session-simulator.ts为了量化交接文件的作用本仓库在 code/session-simulator.ts 中提供了一个可直接运行的 TypeScript 仿真。它模拟一个六步任务读项目结构 → 理解 auth 模块 → 设计搜索端点 → 实现搜索端点 → 写集成测试 → 更新文档在无交接文件和有交接文件两种情况下对比两个会话的产出。运行方式仓库已配置 tsx直接执行即可npx tsx docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts3.1 Run 1无交接文件会话 A 完成第 13 步后上下文耗尽。会话 B 没有任何上下文只能从第 1 步重新开始把 A 已完成的 3 步又做了一遍代码中用sessionB.duplicatedSteps 3标记重复工作然后才走到第 6 步。3.2 Run 2有交接文件会话 A 完成第 13 步并写入交接文件。会话 B 读取交接文件后从第 4 步开始runSession(Session B, 4, 6)重复工作为 0。3.3 输出对比表仿真脚本会打印一张对比表核心指标如下各步骤耗时见源码taskSteps定义50/80/60/100/70/40ms总计 400ms指标无交接文件有交接文件会话 A 完成步骤数33会话 B 完成步骤数63重复步骤数30总工作量ms590400交接节省时间ms—190仿真的结论写在脚本最后一行交接文件消除重复工作并确保跨会话连续性A handoff file eliminates duplicate work and ensures continuity across sessions。这个 190ms 的差距在真实项目中会被放大成第 05 讲案例里的数字恢复成本从约 15 分钟降到约 3 分钟特性完成率从 58% 提升到 100%。四、配套自检continuity-checklist.md交接文件写得好不好需要用检查清单来度量。第 05 讲的 code/continuity-checklist.md 给出了四个问题任何一个回答否都意味着交接不完整一个全新 Agent 能否在五分钟内搞清楚最近的工作——衡量恢复成本的下限当前稳定的启动路径是否已记录——防止新会话在怎么把应用跑起来上浪费时间未完成的工作是否被明确标出——对应交接文件的第二段不读旧聊天日志就能看到下一步最佳任务吗——对应交接文件的第三段也是会话间依赖的终极目标。这四个问题其实是把恢复成本 ≤ 5 分钟这个目标翻译成了可自检的验收标准。本仓库 project-03 的 clean-state-checklist.md 进一步把这一思想扩展为完整的干净状态检查构建验证npm install/npm run check/npm run build全部通过、特性验证14 项 UI 与功能逐条勾选、范围控制feature_list.json 全部为 pass 且有证据、代码质量与文档完整性session-handoff.md 与 claude-progress.md 必须已填写。五、真实落地project-03 中的完整交接体系理论要落到可运行的代码上才有说服力。本仓库 projects/project-03/solution/ 就是一个把交接思想贯彻到底的多会话项目示例对应文档 docs/projects/project-03-multi-session-continuity/index.md。它的交接体系由四个文件协同构成5.1 session-handoff.md生产级交接模板projects/project-03/solution/session-handoff.md 在最小模板之上扩展为七段结构每一段都能在最小模板中找到对应关系Last Session上次会话时间2026-03-30为交接文件增加时间维度What Was Accomplished完成了什么对应已完成段。例如第 4 条记录了 Grounded QA 的实现细节——关键词检索、Top 2 分块作为引用、置信度 0.85/0.30、问答历史持久化到 qa-history.jsonWhat Remains还剩什么对应已完成段的边界。这里明确写出Project 03 无剩余特性feature_list.json 中 11 个特性全部为 passDecisions Made做出的决策对应第 05 讲的为什么维度例如元数据在导入时提取而非惰性提取以确保始终可用、分块采用段落感知切分双换行以避免切断句子Files Modified修改的文件逐文件列出改动src/shared/types.ts、src/services/document-service.ts 等让新会话能精确聚焦 diffBlockers阻塞项显式声明无Next Steps下一步对应下一步最佳行动直接指向 Project 04。注意其中每项特性一次只实现一个one-feature-at-a-time的决策记录——这正是 AGENTS.md 中约定的策略它保证了交接文件里的每一条都对应一次已完成的、可验证的增量而不是一坨无法描述的大改动。5.2 claude-progress.md会话级日志claude-progress.md 把单个交接文件扩展成了按会话、按特性组织的历史日志Session 12026-03-30 10:00-13:00逐条记录了 metadata-extraction、document-chunking、indexing-status-ui、grounded-qa 四个特性的实现时间窗口、改动位置、验证命令npm run check与 feature_list.json 状态更新。它回答了第 05 讲中验证记录的诉求每个特性的验收结果如导入文档后确认详情视图出现元数据都留在仓库里新会话不必重跑验证。5.3 init.sh交接的打卡仪式init.sh 用set -euo pipefail保证任何一步失败即中止顺序执行三件事npm install装依赖→npm run check类型检查→npm run build构建最后提示npm run dev启动应用。这正是第 05 讲建议写进 AGENTS.md 的上班打卡clock in程序——新会话只需跑一次 init.sh就能确认仓库处于一致状态然后放心地读交接文件继续工作。同理下班打卡clock out程序是更新 PROGRESS.md → 运行 make check 确认状态一致 → 提交所有已完成的工作。第 05 讲给出的 AGENTS.md 打卡/交班示例模板如下可直接对照实现## At session start (clock in) 1. Read PROGRESS.md for current state 2. Read DECISIONS.md for important decisions 3. Run make check to confirm repo is in consistent state 4. Continue from PROGRESS.md Next Steps section ## Before session end (clock out) 1. Update PROGRESS.md 2. Run make check to confirm consistent state 3. Commit all completed work5.4 feature_list.json交接的验收锚点feature_list.json 记录了 11 个特性的 pass 状态与证据。它与交接文件互为印证交接文件说明做了什么、怎么做的feature_list.json 证明这些特性确实通过了验收。这让新会话可以在交接文件声称完成与验收记录证明完成之间交叉验证把主观陈述变成可审计的事实。六、从交接文件到完整的连续性工具箱交接文件是最小可行方案第 05 讲还给出了让它真正发挥作用的四个配套工具PROGRESS.md进度文件交接文件的常驻形态记录当前状态最新提交哈希、测试通过率 42/43、lint 状态、已完成、进行中90% 分页特性、边界用例测试失败、已知问题、下一步三步清单DECISIONS.md决策日志只记录什么决策、为什么、何时三要素例如2024-01-15用户偏好缓存选用 Redis——理由高频读、数据量小被否方案PostgreSQL 物化视图——变更频率高导致维护成本不划算约束缓存 TTL 5 分钟、写时主动失效Git 检查点每完成一个原子工作单元就提交提交信息写清做了什么、为什么这是零成本、自动版本化的状态快照初始化脚本 AGENTS.md 交班协议把上班打卡 / 下班打卡固化成可执行流程见 5.3。6.1 混合策略不是所有任务都要交接第 05 讲特别强调混合策略短任务少于 30 分钟应尽量在单会话内完成不需要重置上下文长任务跨多个会话则必须使用进度文件与决策日志。判断阈值是如果任务预计消耗超过 60% 的上下文窗口就应开始准备交接文件。6.2 关于上下文焦虑的模型差异第 05 讲转述 Anthropic 的研究指出Agent 感知到上下文接近上限时会出现过早收敛行为——仓促收尾、跳过验证步骤、选简单方案而不是最优方案这被称为上下文焦虑。两种应对策略各有适用场景压缩保留连续性但常丢为什么且无法消除焦虑Agent 知道上下文曾很大心理上仍想尽快收尾重置 交接新会话没有时间快没了的焦虑但完全依赖交接工件的完整性。据第 05 讲转述的研究结论不同模型的焦虑程度差异显著如 Sonnet 4.5 严重到仅靠压缩不够、必须依赖上下文重置而某些模型压缩即可管理——这意味着 harness 的设计应针对具体的目标模型定制而不是套用通用模板。这正好强化了交接文件的价值无论采用哪种策略结构化的状态工件都是可复用的基础设施。七、第 05 讲的实践练习如果你想在自己的项目里验证这套方法第 05 讲末尾给出了三个可直接执行的实验测量连续性损失选一个至少需要 3 个会话的开发任务。不用交接工件在每会话开头记录 Agent 花多少上下文搞清楚上次发生了什么之后改为每会话结尾写进度文件对比恢复成本。设计最小交接模板只保留四个字段——仓库状态提交哈希、运行时状态测试通过率、阻塞项、下一步行动。让一个完全新鲜的 Agent 会话仅凭该模板恢复项目记录恢复过程中出现的歧义并迭代模板。混合策略对照实验在 5 会话任务中分别用a每次新会话 进度文件、b单会话内尽量压缩、c混合策略对比恢复时间、特性完成率与决策一致性。结论回到第 05 讲的核心论断上下文窗口是有限资源长任务必然跨会话而会话天然会丢失信息——解决方案不是更大的窗口而是更好的状态保存。本仓库的 session-handoff.md 示例 证明了交接文件可以小到只有三段、17 行session-simulator.ts 用可复现的数据证明了它能把重复工作降为零project-03/solution 则展示了它在真实多会话项目中的完整形态。把 Agent 当作失忆的天才工程师在下班前写好交接文件让每个新会话都从昨天结束的地方而不是零开始——这就是多会话 harness 设计的基石。更多概念定义与完整讲义可继续阅读第 05 讲正文 index.md。赞分享【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载相关推荐Learn Harness Engineering 实战Session Handoff 会话交接文件——让跨会话长任务不再丢失连续性Learn Harness Engineering 实战Session Handoff 会话交接文件——让跨会话长任务不再丢失连续性 本篇技术指南以 learLearn Harness Engineering用 Session Handoff 文档修复长任务的跨会话连续性Learn Harness Engineering用 Session Handoff 文档修复长任务的跨会话连续性 导读在 Learn Harness En会话交接文件实战用 Session Handoff 对抗长期任务上下文断层——learn-harness-engineering 多会话连续性核心实践会话交接文件实战用 Session Handoff 对抗长期任务上下文断层——learn harness engineering 多会话连续性核心实践 导读上一篇TinyGSM与Blynk平台集成创建可视化物联网仪表板下一篇Flutter Windows 相机插件 camera_windows 开发指南版本演进、错误码规范与平台能力边界创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
