【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址https://gitcode.com/gh_mirrors/le/learn-harness-engineering点击查看免费下载本篇文章以 learn-harness-engineering 仓库中《Лекция 05. Сохраняйте контекст между сессиями》第 05 讲为什么长时间运行的任务会失去连续性及其配套代码为骨架展开。核心主题是上下文窗口是有限资源多会话长任务必然丢失为什么信息导致 Agent 重复劳动、方向漂移甚至返工解决之道不是更大的窗口而是结构化的状态保存——用 PROGRESS.md、DECISIONS.md、Git 检查点与 AGENTS.md 交接流程把 Agent 当成患有失忆症的天才工程师让每个会话都能像阅读施工日志一样在三分钟内恢复工作状态。读完本文你将掌握一套可直接落地的多会话连续性方案handoff 模式并看到它在仓库配套模拟器与 Project 03 实战项目中的完整实现。为什么上下文窗口是有限的越大越不够用本讲的核心论断非常直接上下文窗口是有限资源而且这个问题无法靠升级模型解决。即使窗口扩大到 1M token复杂任务依然会把它耗尽。原因在于Agent 在任务中消耗上下文的不只是生成代码这一件事它要阅读和理解整个代码库要追踪自己历史决策的来龙去脉要处理大量工具调用返回的输出还要维持与用户对话的上下文。这些信息的增长速度远远超过窗口容量的扩展速度。更深层的问题在于Agent 产生的信息重要程度并不等价。中间推理步骤承载着决策的为什么——为什么选择方案 B 而不是方案 A、为什么用这个库而不是另一个、为什么跳过某项优化而最终产出只包含是什么——也就是代码本身。常用的上下文压缩compaction策略通常保留后者而丢掉前者。于是下一场会话能看到代码却不知道为什么代码写成这样它可能就会把一个深思熟虑的设计决策当作可以随意优化的东西。更糟的是Anthropic 在长时运行 Agent 的研究中发现了一个有趣现象当 Agent 感觉上下文即将耗尽时会出现过早收敛premature convergence的行为——急于收尾当前工作、跳过验证步骤、用简单方案替代最优方案。这就像考试时发现时间快到了开始对剩下的选择题乱猜。Anthropic 称之为**上下文焦虑context anxiety**。会话连续性的两种流向在没有连续性工件continuity artifacts的情况下每一场新会话都是一场灾难。本讲用一张流程图描述了这个循环而有了连续性工件之后新会话可以快速接续工作这两张图就是本文全部内容的高度浓缩左边是无日志施工的混沌右边是有日志施工的秩序。关键概念本讲的术语表上下文窗口是有限的Context windows are finite无论标称多大128K、200K、1M长任务迟早会把它耗尽。耗尽之后只有两条路压缩有信息损失或重置开新会话。两者都会丢失某些东西。连续性工件Continuity artifacts持久化的状态文件让新会话能明确无误地从上一会话停下的位置继续。基本形态是进度日志 验证记录 后续动作清单。这就是施工日志本身。恢复成本Recovery cost新会话进入可工作状态所需的时间。好的 harness 能把它从 15 分钟压缩到 3 分钟。漂移DriftAgent 的理解与仓库真实状态之间的落差。每一个会话边界都会引入漂移不加控制就会累积。上下文焦虑Context anxietyAnthropic 观察到的现象——Agent 在接近感知到的上下文上限时表现出过早收敛为了避免丢失信息而过早结束任务。这是一种非理性的资源焦虑。压缩 vs 重置Compaction vs reset压缩在同一会话内对早期对话做摘要保留是什么可能丢失为什么重置则是开新会话、从保存的状态中恢复干净但依赖工件的完整性。当连续性被破坏时会发生什么上一会话花了大量上下文预算分析三个方案并选定了方案 B而当前会话对此一无所知就可能基于不完整信息重新决策——甚至选择方案 A。这就是那个失忆大师的寓言他不记得当初为什么选红砖今天看着蓝砖觉得更漂亮就拆了昨天的墙重砌。更糟糕的是重复劳动。Agent 不确定某项工作是否已经完成于是再做一遍或者做了一半发现与已有实现冲突被迫返工。工地上两支施工队不会同时砌一堵墙但没有进度记录时新来的施工队根本不知道已经有人在砌了。经过多个会话实现方向会不知不觉偏离原始需求。每个新会话都对项目目标有稍许不同的理解就像传话游戏传十次之后帮我买杯咖啡可能变成帮我买台咖啡机。此外还有验证缺口verification gap。上一会话的验证结果——哪些测试通过、哪些失败、为什么失败——没有被记录下来新会话不得不重新跑一遍全部验证才能搞清楚当前状态。每场会话都从零开始诊断每次都消耗宝贵的上下文。OpenAI 和 Anthropic 都在各自的文档中强调结构化状态保存的重要性。OpenAI 的 harness engineering 文章把仓库视为操作日志每次操作的结果都要在仓库中留下可追踪的痕迹。Anthropic 的长时运行 Agent 文档则明确推荐使用handoff 文件——包含当前状态、已知问题与后续动作的结构化文档。这正是本讲方案的理论依据。为失忆大师准备的日志四个核心工具本讲的中心方法论把 Agent 当作一位患有失忆症的天才工程师。在下班之前它必须把关键信息写下来让下一班接班的 Agent 能快速接续工作。工具 1进度文件PROGRESS.md最基本的连续性工件是日志的核心。它要能回答四个问题现在做到哪了、已完成什么、正在做什么、下一步做什么# Project Progress ## Current State - Latest commit: abc1234 (feat: add user preferences endpoint) - Test status: 42/43 passing (test_pagination_edge_case failing) - Lint: passing ## Completed - [x] User model and database migration - [x] Basic CRUD endpoints - [x] Auth middleware integration ## In Progress - [ ] Pagination feature (90% - edge case test failing) ## Known Issues - test_pagination_edge_case returns 500 on empty result sets - Need to confirm whether deleted users should appear in listings ## Next Steps 1. Fix pagination edge case bug 2. Add include deleted users query parameter 3. Update API documentation注意 Current State 里记录的是可验证的客观状态commit hash、测试通过数而不是主观描述这是新会话能快速确认仓库到底处于什么状态的关键。工具 2决策日志DECISIONS.md记录重要的设计决策及其原因。不需要详细的设计文档只要什么决策、为什么、什么时候三要素就够了——这是日志里的备忘条# Design Decisions ## 2024-01-15: Use Redis for user preferences caching - Reason: High read frequency (every API call), small data size - Rejected alternative: PostgreSQL materialized view (high change frequency makes maintenance cost not worthwhile) - Constraint: Cache TTL of 5 minutes, active invalidation on write注意这个条目里既有选择了什么也有否定了什么被拒绝的备选方案及其理由还有约束条件。被否定的方案同样重要它能防止新会话在不知情的情况下重新引入已经被评估过的坏方案。工具 3Git 提交作为检查点每完成一个原子工作单元就提交一次。提交信息要说明做了什么和为什么。这是免费的、自动版本化的状态快照——git 本身就是最可靠的连续性工件基础设施。工具 4init.sh 或 harness 初始化流程写在 AGENTS.md 里在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 work混合策略不是所有任务都需要跨会话并非每个任务都需要重置上下文。**短任务少于 30 分钟**可以在单会话内完成**长任务跨多个会话**则必须使用进度文件和决策日志来保证连续性。判断标准如果任务预计会消耗超过 60% 的窗口就要开始准备 handoff。深入上下文焦虑与两种对策Anthropic 在 2026 年 3 月的研究《Harness design for long-running application development》中揭示了上下文焦虑的具体表现在 Sonnet 4.5 上当上下文接近窗口上限时Agent 会表现出明显的过早收敛行为——就像考试时间快结束时的乱猜。两种对策各有取舍压缩Compaction在同一会话内对早期对话做摘要。优点保持连续性Agent 仍能看到是什么。缺点为什么常常在摘要中丢失——为什么选 B 不选 A、为什么跳过某项优化。更关键的是压缩无法消除上下文焦虑——Agent 知道自己曾经的上下文很大心理上仍然急于收尾。重置上下文Context reset清空上下文、开新会话、从保存的工件中恢复。优点精神状态干净新会话没有时间快不够了的焦虑。缺点完全依赖 handoff 工件的完整性——如果日志里缺了关键信息新会话可能朝错误方向浪费时间。Anthropic 给出的真实数据是对 Sonnet 4.5 而言上下文焦虑严重到仅靠压缩不够上下文重置成为 harness 设计中不可或缺的组件但对 Opus 4.5这种行为显著减弱压缩就能管理上下文、无需依赖重置。这意味着harness 的设计必须针对具体的目标模型来定制而不是套用一个万能模板。仓库中的落地证据配套代码与 Project 03本讲的主题并不只是理论仓库里既有配套的模拟器代码也有完整的实战项目实现。配套模拟器session-simulator.tscode 目录的 session-simulator.ts 用一段可运行的 TypeScript 模拟了两种场景simulateNoHandoff 中会话 B 没有 handoff 文件、从步骤 1 重做重复了会话 A 已完成的 3 个步骤simulateWithHandoff 中会话 B 读取 handoff 文件后从步骤 4 继续重复步骤为 0。任务被定义为一个六步流水线读项目结构 → 理解现有 auth 模块 → 设计搜索端点 → 实现 → 写集成测试 → 更新文档每步有固定耗时。在仓库根目录运行路径以本文对应的俄文版为例npx tsx docs/ru/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-simulator.ts脚本末尾的 printComparison 会输出对比表。根据源码中的步骤耗时可以精确复现无 handoff 时总工作量 会话 A步骤 1-3190ms 会话 B步骤 1-6400ms 590ms有 handoff 时 190ms 会话 B步骤 4-6210ms 400mshandoff 节省了 190ms 的重复工作。这个量化对比直观地证明了文章标题的论断连续性工件消除的是纯粹的浪费。配套示例handoff 模板与连续性检查清单code/session-handoff.md 是一个迷你 handoff 模板只含三节已完成Сделано、损坏或未验证Сломано или не проверено、下一个最佳步骤Следующий лучший шаг。注意它诚实地记录了导入对 .md 有效但对大 .txt 文件会失败这类不完美状态——handoff 的价值正在于记录真实状态而非粉饰太平。code/continuity-checklist.md 则给出四连问式的自检清单一个新 Agent 能否在五分钟内确定最近的工作当前稳定的启动路径是否已文档化未完成的工作是否被明确标注不看旧聊天日志是否就能看到下一个最佳任务这四条可以作为任何项目交付 handoff 前的验收标准。实战项目Project 03 Multi-Session ContinuityProject 03 实战项目对应项目代码在 projects/project-03/solution把上述工具全部落到了真实代码上。它的 AGENTS.md 定义了启动规则读 AGENTS.md → 读 ARCHITECTURE.md → 读 PRODUCT.md →npm install npm run check→ 读 feature_list.json和一次只做一个功能策略并在末尾明确了会话交接规则恢复工作时读 session-handoff.md结束会话时更新它做了什么、还剩什么、阻塞项与决策、修改过的文件。projects/project-03/solution/session-handoff.md 是该项目的真实交接文档包含上一会话2026-03-30已完成工作4 项功能逐条列出剩余工作做出的决策元数据在导入时提取而非懒加载、按段落感知切分等修改的文件清单精确到 src/shared/types.ts、src/services/qa-service.ts 等阻塞项无下一步进入 Project 04。可以看到这正是本讲 PROGRESS.md DECISIONS.md 模式的生产级实例。projects/project-03/solution/claude-progress.md 则提供了会话级时间线每个功能标注了起止时间、实现内容、验证方式npm run check 行为验证以及 feature_list.json 状态更新——每完成一个功能就提交、记录、再开始下一个严格贯彻 AGENTS.md 中的纪律。这种功能粒度的会话日志让任何新会话都能从 claude-progress.md 快速重建上一场会话到底干了什么、验证到什么程度。实战案例对比一个博客系统的 12 个功能本讲给出了一个贯穿性的案例让 Agent 实现一个带用户认证的博客系统共 12 个功能预估需要 5 场会话。无日志的基准场景会话 1 实现了用户模型和基础路由会话 2 对 auth-middleware 的接口约定毫无记忆花了约 15 分钟重建之前的设计意图到会话 3累积的漂移让 Agent 开始重做已完成的功能到会话 5仓库里充斥着冗余代码而关键的认证功能仍然过不了端到端测试。最终只完成 12 个功能中的 7 个其中 3 个还藏着正确性问题——就像从不写日志的大师到第五天工地一片混乱有些墙砌了两遍有些压根没开工。有日志的场景使用进度文件、决策日志、验证记录和 git 检查点每场会话结束时自动更新状态报告。会话 2 的恢复成本降到约 3 分钟。到会话 5全部 12 个功能完成并通过验证。量化对比来自本讲的案例数据恢复时间缩短约 78%功能完成率从 58% 提升到 100%隐藏缺陷率从 43% 降到 8%。大师依然失忆但有了日志每一天都从昨天的终点开始而不是从零开始。主要结论上下文窗口是有限资源。长任务必然跨越多个会话而会话会丢失信息——就像每天失忆的大师这是客观现实。解法不在更大的窗口而在更好的状态保存。进度文件 决策日志 git 检查点——给失忆的大师一本可靠的日志。把 Agent 当作失忆的工程师在下班前记下做了什么、为什么、下一步是什么。恢复成本是关键指标。好的 harness 应该让新会话在 3 分钟内进入可工作状态。采用混合策略短任务在单会话内完成长任务借助结构化连续性工件跨会话推进。配套练习测量连续性损失选一个至少需要 3 场会话的开发任务。在没有连续性工件的情况下在每场会话开始时记录 Agent 花多少上下文去理解上次发生了什么。每场会话结束时创建进度文件让下一场会话从它开始。对比有/无进度文件两种情况下的恢复成本。设计 handoff 模板设计一个仅含四个字段的最小 handoff 模板仓库状态commit hash、运行时状态测试通过比例、阻塞项、后续动作。让一个全新的 Agent 会话仅凭这个模板恢复项目状态。记录恢复过程中出现的不确定性迭代改进模板。混合策略实验在一个需要 5 场会话的任务上对比三种策略(a) 总是新会话 进度文件(b) 尽量在单会话内做完上下文压缩(c) 混合策略短任务在会话内长任务跨会话 进度文件。比较恢复时间、功能完成率和决策一致性。延伸阅读本讲还推荐了若干外部资料不在本文输出链接仅列标题供检索Anthropic《Effective Harnesses for Long-Running Agents》、OpenAI《Harness Engineering》、《Lost in the Middle: How Language Models Use Long Contexts》、Claude Code 官方文档以及 HumanLayer《Harness Engineering for Coding Agents》。仓库内部的延伸材料本文对应的俄文版讲座正文与中文版讲座、Project 03 实战项目文档以及上一讲《为什么仓库必须成为系统事实源》等系列课程共同构成了从为什么连续会断到如何用 harness 接住它的完整知识链。赞分享【免费下载链接】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 文档修复长任务的跨会话连续性 导读在 Learn Harness En会话交接文件Session Handoff用最小化状态工件解决长时任务的跨会话连续性——learn-harness-engineering 第 05 讲实战解析会话交接文件Session Handoff用最小化状态工件解决长时任务的跨会话连续性——learn harness engineering 第 05 讲实Learn Harness Engineering 实战Session Handoff 会话交接文件——让跨会话长任务不再丢失连续性Learn Harness Engineering 实战Session Handoff 会话交接文件——让跨会话长任务不再丢失连续性 本篇技术指南以 lear上一篇Chameleon Ultra GUI用户指南Slot管理、卡片保存与高级设置详解下一篇road-to-yuzu-without-switch核心功能解析从prod.keys配置到游戏加载全流程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
