Session Handoff 模板实战为跨会话 AI 编码 Agent 建立可恢复的交接机制【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineeringSession Handoff会话交接是 Harness Engineering 中最基础也最关键的状态持久化原语每次会话结束前Agent 把当前已验证了什么、本轮改了什么、什么还坏着、下一步做什么、怎么运行验证写进一个结构化文件让下一个全新会话能在几分钟内无缝接手。本文以 learn-harness-engineering 仓库中的标准交接模板为骨架结合跨会话连续性课程Lecture 05的理论背景、技能包skills/harness-creator/templates/session-handoff.md中的扩展模板以及 project-02、project-03、project-06 中的真实交接文档实例系统讲解交接文件的设计动机、五段式结构、填写方法与工作流嵌入方式。读完你不仅能直接套用该模板还能理解为什么交接内容必须可验证、为什么交接质量直接决定下一会话的重建成本。为什么会话交接文件是不可或缺的AI 编码 Agent 的上下文窗口是有限资源。Lecture 05 明确指出无论窗口声称多大128K、200K 甚至 1M token长任务终究会耗尽上下文耗尽后要么压缩compaction保留做了什么但常常丢失为什么这么做要么重置会话从持久化产物重建干净但依赖交接产物的完整性。这意味着跨会话任务是常态而每个会话边界都会引入一次信息断层。更棘手的是两个叠加效应Drift漂移新会话对代码库的理解与仓库真实状态之间的偏差。每个会话边界都会引入漂移不加以控制就会逐次累积最终实现方向与原需求渐行渐远。Context anxiety上下文焦虑Anthropic 在长运行 Agent 研究中观察到的现象——Agent 感知到上下文将耗尽时会出现仓促收尾行为跳过验证步骤、放弃最优方案改选简单方案。它本质上是一种非理性的资源焦虑压缩并不能消除它只有干净的重置 完整的交接产物才能让新会话不带焦虑地工作。Anthropic 与 OpenAI 的官方文档都强调结构化状态持久化。Anthropic 的长运行 Agent 文档明确推荐handoff files——包含当前状态、已知问题与下一步动作的结构化文档OpenAI 的 Harness Engineering 文章则把仓库视为运行记录operational record要求每个操作的结果都在仓库中留下可追踪的证据。会话交接文件正是这两种理念的最小落地形式。模板总览五段式最小交接结构仓库中的标准模板英文版本仓库另有 中文版、阿拉伯语版 等同构翻译定义了五段结构段落核心问题回答的是Verified Now当前已验证现在明确可用的是什么本轮实际跑过哪些验证状态基线Changed This Session本轮改动新增了哪些代码/行为基础设施或 harness 有什么变化变更范围Broken Or Unverified仍损坏或未验证已知缺陷、未验证路径、对下一会话的风险风险清单Next Best Step下一步最佳动作优先级最高的未完成功能为什么是它怎样才算通过哪部分不能动行动指令Commands命令启动命令、验证命令、定向调试命令分别是什么可复现性五个段落共同回答同一组问题上一会话结束时系统处于什么状态、新会话第一件事该做什么、怎么验证自己没有改坏东西。 这正是 Lecture 05 提出的核心比喻——把 Agent 当成一个每次会话都会被抹掉短期记忆的工程师下班前必须写清楚做了什么、为什么、接下来是什么。逐段详解与填写要点Verified Now只写真的验证过的东西这是交接文件中最容易被敷衍、也最影响可信度的部分。它要求区分我以为能用与我实际验证过——因此模板用两个子条目互相钳制现在明确可用的部分What is currently working这轮实际跑过的验证What verification actually ran。填写原则是验证与结论一一对应。例如projects/project-03/solution/session-handoff.md中写道IndexingService chunking pipeline is fully working随后立刻给出证据链chunkDocument()按段落边界切分约 500 字符的块、每个块带 charCount/wordCount 元数据、块以 JSON 存储于chunks/docId.json。结论必须有对应的验证手段支撑新会话才能信任它并跳过重复验证。Changed This Session锁定变更边界第二段要求记录两类变化代码或行为层面的新增以及基础设施或 harness 层面的变化。后者常被忽略——但正是这些文件决定了下一会话的玩法。projects/project-03/solution/session-handoff.md的 Files Modified 列表示范了完整覆盖共享类型src/shared/types.ts新增DocumentMetadata接口、服务实现document-service.ts的extractMetadata()、indexing-service.ts的切分管道、主进程与预加载桥接、渲染层组件以及 harness 文件本身AGENTS.md新增 one-feature-at-a-time 策略、feature_list.json全部标记为 pass。值得注意的是它还会记录哪些文件没有改如persistence-service.ts: No changes, inherited from P2这能帮新会话缩小排查范围。Broken Or Unverified把风险显式化第三段包含三个子条目已知缺陷、未验证路径、下一会话需要注意的风险。它存在的意义是打破Agent 倾向于把一切说成已完成的默认倾向。docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md中的示例非常直白Import succeeds for.mdbut fails for large.txtfilesThe app starts, but the detail view has not been wired up。这种坦诚的风险记录让下一会话从到处试探变成直奔已知问题。Lecture 05 还提醒上一会话的验证结果哪些测试通过、哪些失败、为什么失败如果不记录新会话就得全部重跑、每次都从零诊断这是最典型的上下文浪费。Next Best Step给出可判定的行动指令第四段是交接文件真正的行动核心包含四个层次的问题最高优先级未完成功能是什么为什么它是下一步而不是别的什么结果才算 passing验收标准必须可判定这一步中哪些东西不要动变更边界约束。最后一条尤其重要——它防止新会话在推进 A 功能时顺手优化掉上一个会话刻意为之的设计决策。Lecture 05 明确指出中间推理步骤里藏着决策的为什么为什么选 A 不选 B、为什么跳过某项优化而压缩策略通常会保留是什么却丢失为什么导致新会话可能把深思熟虑的设计当成冗余代码删掉。交接文件中的不要动清单正是对抗这种丢失的显式手段。Commands让一切可复现第五段要求给出三条命令启动命令、验证命令、定向调试命令。这是可复现性的保障——新会话不需要重新考古 package.json 或文档才能知道怎么跑起来、怎么确认没改坏。仓库中的实践可以印证这一点各项目的package.json定义了标准脚本而 harness 层又通过init.sh如 project-01 的 init.sh、project-06 的 init.sh把初始化与验证流程收敛成单一入口。交接文件里记录的验证命令应当与这些脚本保持一致确保按命令执行 得到与记录一致的结论。更完整的模板变体Verification Evidence 表格skills/harness-creator技能包提供了交接模板的一个更完整变体skills/harness-creator/templates/session-handoff.md在五段结构之上扩展出三个关键增强Verification Evidence验证证据表用四列表格Check / Command / Result / Notes把每项验证与其命令、结果、备注绑定进一步强化验证可复现Current Objective开头即记录目标、当前状态、分支/commit——把交接文件与 Git 检查点直接挂钩Next Session Startup下一会话启动清单给出明确的打卡步骤——先读AGENTS.md再读feature_list.json和progress.md然后审阅本交接文件最后在改动前运行./init.sh或文档化的验证命令。这与 Lecture 05 提出的 Tool 4: init.sh / harness 初始化流程 完全对应在AGENTS.md中规定打卡clock in与下班clock out例程——会话开始读 PROGRESS、跑验证命令确认仓库一致会话结束前更新进度、再跑验证、提交所有完成的工作。真实项目中的交接文档从模板到落地模板的价值在于被真实使用。仓库里三个项目解决方案目录中沉淀了实际填写完成的交接文档project-02/solution/session-handoff.md记录了文档导入流程ImportPanel、DocumentService.importDocument()、持久化机制以及一个重要决策——新增独立的GET_DOCUMENT_CONTENTIPC 通道而非把内容捆绑进GET_DOCUMENT以保持列表视图载荷精简。这正是 DECISIONS 型内容在交接文件中的体现下一会话看到这个决策就不会优化回捆绑方案。project-03/solution/session-handoff.md元数据提取、约 500 字符按段落切分、带引用的 grounded QA、置信度打分有引用 0.85 / 无引用 0.30等全部按每项功能实现→验证→记录的 one-feature-at-a-time 策略推进并明确注明所有 11 个 feature 均为 pass。project-06/solution/session-handoff.md作为收官项目交接文档覆盖结构化 JSON 日志、反馈采集管道、会话历史、clean state 重置、基准脚本等 15 个特性并记录了clean state 使用破坏性 rmSync 而非选择性删除这类实现决策。projects/project-02/README.md还从对比角度给出了模板价值的直接证据starter 起点没有最终交接文件AGENTS.md is minimal and there is no session handoff而 solution 中则补齐了session-handoff.md与扩展的架构/产品文档README 明确指出核心对比指标就是Session B 在存在session-handoff.md时能多快恢复。这正是 Lecture 05 中rebuild cost重建成本概念的工程化落地——好的 harness 应能把新会话达到可执行状态的时间从 15 分钟压缩到 3 分钟。把交接文件嵌入会话生命周期结合模板与仓库实践一套可执行的嵌入方案如下会话开始clock in读取交接文件确认上一会话的当前已验证基线读取feature_list.json确认功能清单状态运行交接文件命令段中的验证命令确认仓库处于一致状态从下一步最佳动作段开始推进严格避开不要动清单。会话结束clock out如实更新当前已验证与本轮改动只写实际跑过的验证显式登记仍损坏或未验证项及其对下一会话的风险给出下一个最佳动作与可判定的 passing 标准确认启动/验证/调试三条命令仍然准确提交 Git 检查点让 commit hash 成为交接文件的锚点。混合策略Lecture 05 提醒并非所有任务都需要跨会话交接——短任务30 分钟以内可在单会话内完成只有当任务预计消耗超过 60% 上下文窗口时才开始准备交接文件。判断标准不是任务多大而是会不会撑爆窗口。关键要点交接文件是跨会话连续性的最小基础设施五段结构已验证 / 本轮改动 / 未验证 / 下一步 / 命令覆盖了状态基线、变更边界、风险、行动与可复现性五个维度。当前已验证必须与实际跑过的验证一一对应结论没有验证支撑就等于没有结论。下一步最佳动作必须包含可判定的 passing 标准与不要动清单前者防含糊后者防回归。验证命令必须真实可执行并与init.sh、package.json脚本保持一致。交接质量直接决定下一会话的 rebuild cost这是衡量 harness 好坏的关键指标也是 Lecture 05 全篇的核心命题。【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Session Handoff 模板实战：为跨会话 AI 编码 Agent 建立可恢复的交接机制
Session Handoff 模板实战为跨会话 AI 编码 Agent 建立可恢复的交接机制【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineeringSession Handoff会话交接是 Harness Engineering 中最基础也最关键的状态持久化原语每次会话结束前Agent 把当前已验证了什么、本轮改了什么、什么还坏着、下一步做什么、怎么运行验证写进一个结构化文件让下一个全新会话能在几分钟内无缝接手。本文以 learn-harness-engineering 仓库中的标准交接模板为骨架结合跨会话连续性课程Lecture 05的理论背景、技能包skills/harness-creator/templates/session-handoff.md中的扩展模板以及 project-02、project-03、project-06 中的真实交接文档实例系统讲解交接文件的设计动机、五段式结构、填写方法与工作流嵌入方式。读完你不仅能直接套用该模板还能理解为什么交接内容必须可验证、为什么交接质量直接决定下一会话的重建成本。为什么会话交接文件是不可或缺的AI 编码 Agent 的上下文窗口是有限资源。Lecture 05 明确指出无论窗口声称多大128K、200K 甚至 1M token长任务终究会耗尽上下文耗尽后要么压缩compaction保留做了什么但常常丢失为什么这么做要么重置会话从持久化产物重建干净但依赖交接产物的完整性。这意味着跨会话任务是常态而每个会话边界都会引入一次信息断层。更棘手的是两个叠加效应Drift漂移新会话对代码库的理解与仓库真实状态之间的偏差。每个会话边界都会引入漂移不加以控制就会逐次累积最终实现方向与原需求渐行渐远。Context anxiety上下文焦虑Anthropic 在长运行 Agent 研究中观察到的现象——Agent 感知到上下文将耗尽时会出现仓促收尾行为跳过验证步骤、放弃最优方案改选简单方案。它本质上是一种非理性的资源焦虑压缩并不能消除它只有干净的重置 完整的交接产物才能让新会话不带焦虑地工作。Anthropic 与 OpenAI 的官方文档都强调结构化状态持久化。Anthropic 的长运行 Agent 文档明确推荐handoff files——包含当前状态、已知问题与下一步动作的结构化文档OpenAI 的 Harness Engineering 文章则把仓库视为运行记录operational record要求每个操作的结果都在仓库中留下可追踪的证据。会话交接文件正是这两种理念的最小落地形式。模板总览五段式最小交接结构仓库中的标准模板英文版本仓库另有 中文版、阿拉伯语版 等同构翻译定义了五段结构段落核心问题回答的是Verified Now当前已验证现在明确可用的是什么本轮实际跑过哪些验证状态基线Changed This Session本轮改动新增了哪些代码/行为基础设施或 harness 有什么变化变更范围Broken Or Unverified仍损坏或未验证已知缺陷、未验证路径、对下一会话的风险风险清单Next Best Step下一步最佳动作优先级最高的未完成功能为什么是它怎样才算通过哪部分不能动行动指令Commands命令启动命令、验证命令、定向调试命令分别是什么可复现性五个段落共同回答同一组问题上一会话结束时系统处于什么状态、新会话第一件事该做什么、怎么验证自己没有改坏东西。 这正是 Lecture 05 提出的核心比喻——把 Agent 当成一个每次会话都会被抹掉短期记忆的工程师下班前必须写清楚做了什么、为什么、接下来是什么。逐段详解与填写要点Verified Now只写真的验证过的东西这是交接文件中最容易被敷衍、也最影响可信度的部分。它要求区分我以为能用与我实际验证过——因此模板用两个子条目互相钳制现在明确可用的部分What is currently working这轮实际跑过的验证What verification actually ran。填写原则是验证与结论一一对应。例如projects/project-03/solution/session-handoff.md中写道IndexingService chunking pipeline is fully working随后立刻给出证据链chunkDocument()按段落边界切分约 500 字符的块、每个块带 charCount/wordCount 元数据、块以 JSON 存储于chunks/docId.json。结论必须有对应的验证手段支撑新会话才能信任它并跳过重复验证。Changed This Session锁定变更边界第二段要求记录两类变化代码或行为层面的新增以及基础设施或 harness 层面的变化。后者常被忽略——但正是这些文件决定了下一会话的玩法。projects/project-03/solution/session-handoff.md的 Files Modified 列表示范了完整覆盖共享类型src/shared/types.ts新增DocumentMetadata接口、服务实现document-service.ts的extractMetadata()、indexing-service.ts的切分管道、主进程与预加载桥接、渲染层组件以及 harness 文件本身AGENTS.md新增 one-feature-at-a-time 策略、feature_list.json全部标记为 pass。值得注意的是它还会记录哪些文件没有改如persistence-service.ts: No changes, inherited from P2这能帮新会话缩小排查范围。Broken Or Unverified把风险显式化第三段包含三个子条目已知缺陷、未验证路径、下一会话需要注意的风险。它存在的意义是打破Agent 倾向于把一切说成已完成的默认倾向。docs/en/lectures/lecture-05-why-long-running-tasks-lose-continuity/code/session-handoff.md中的示例非常直白Import succeeds for.mdbut fails for large.txtfilesThe app starts, but the detail view has not been wired up。这种坦诚的风险记录让下一会话从到处试探变成直奔已知问题。Lecture 05 还提醒上一会话的验证结果哪些测试通过、哪些失败、为什么失败如果不记录新会话就得全部重跑、每次都从零诊断这是最典型的上下文浪费。Next Best Step给出可判定的行动指令第四段是交接文件真正的行动核心包含四个层次的问题最高优先级未完成功能是什么为什么它是下一步而不是别的什么结果才算 passing验收标准必须可判定这一步中哪些东西不要动变更边界约束。最后一条尤其重要——它防止新会话在推进 A 功能时顺手优化掉上一个会话刻意为之的设计决策。Lecture 05 明确指出中间推理步骤里藏着决策的为什么为什么选 A 不选 B、为什么跳过某项优化而压缩策略通常会保留是什么却丢失为什么导致新会话可能把深思熟虑的设计当成冗余代码删掉。交接文件中的不要动清单正是对抗这种丢失的显式手段。Commands让一切可复现第五段要求给出三条命令启动命令、验证命令、定向调试命令。这是可复现性的保障——新会话不需要重新考古 package.json 或文档才能知道怎么跑起来、怎么确认没改坏。仓库中的实践可以印证这一点各项目的package.json定义了标准脚本而 harness 层又通过init.sh如 project-01 的 init.sh、project-06 的 init.sh把初始化与验证流程收敛成单一入口。交接文件里记录的验证命令应当与这些脚本保持一致确保按命令执行 得到与记录一致的结论。更完整的模板变体Verification Evidence 表格skills/harness-creator技能包提供了交接模板的一个更完整变体skills/harness-creator/templates/session-handoff.md在五段结构之上扩展出三个关键增强Verification Evidence验证证据表用四列表格Check / Command / Result / Notes把每项验证与其命令、结果、备注绑定进一步强化验证可复现Current Objective开头即记录目标、当前状态、分支/commit——把交接文件与 Git 检查点直接挂钩Next Session Startup下一会话启动清单给出明确的打卡步骤——先读AGENTS.md再读feature_list.json和progress.md然后审阅本交接文件最后在改动前运行./init.sh或文档化的验证命令。这与 Lecture 05 提出的 Tool 4: init.sh / harness 初始化流程 完全对应在AGENTS.md中规定打卡clock in与下班clock out例程——会话开始读 PROGRESS、跑验证命令确认仓库一致会话结束前更新进度、再跑验证、提交所有完成的工作。真实项目中的交接文档从模板到落地模板的价值在于被真实使用。仓库里三个项目解决方案目录中沉淀了实际填写完成的交接文档project-02/solution/session-handoff.md记录了文档导入流程ImportPanel、DocumentService.importDocument()、持久化机制以及一个重要决策——新增独立的GET_DOCUMENT_CONTENTIPC 通道而非把内容捆绑进GET_DOCUMENT以保持列表视图载荷精简。这正是 DECISIONS 型内容在交接文件中的体现下一会话看到这个决策就不会优化回捆绑方案。project-03/solution/session-handoff.md元数据提取、约 500 字符按段落切分、带引用的 grounded QA、置信度打分有引用 0.85 / 无引用 0.30等全部按每项功能实现→验证→记录的 one-feature-at-a-time 策略推进并明确注明所有 11 个 feature 均为 pass。project-06/solution/session-handoff.md作为收官项目交接文档覆盖结构化 JSON 日志、反馈采集管道、会话历史、clean state 重置、基准脚本等 15 个特性并记录了clean state 使用破坏性 rmSync 而非选择性删除这类实现决策。projects/project-02/README.md还从对比角度给出了模板价值的直接证据starter 起点没有最终交接文件AGENTS.md is minimal and there is no session handoff而 solution 中则补齐了session-handoff.md与扩展的架构/产品文档README 明确指出核心对比指标就是Session B 在存在session-handoff.md时能多快恢复。这正是 Lecture 05 中rebuild cost重建成本概念的工程化落地——好的 harness 应能把新会话达到可执行状态的时间从 15 分钟压缩到 3 分钟。把交接文件嵌入会话生命周期结合模板与仓库实践一套可执行的嵌入方案如下会话开始clock in读取交接文件确认上一会话的当前已验证基线读取feature_list.json确认功能清单状态运行交接文件命令段中的验证命令确认仓库处于一致状态从下一步最佳动作段开始推进严格避开不要动清单。会话结束clock out如实更新当前已验证与本轮改动只写实际跑过的验证显式登记仍损坏或未验证项及其对下一会话的风险给出下一个最佳动作与可判定的 passing 标准确认启动/验证/调试三条命令仍然准确提交 Git 检查点让 commit hash 成为交接文件的锚点。混合策略Lecture 05 提醒并非所有任务都需要跨会话交接——短任务30 分钟以内可在单会话内完成只有当任务预计消耗超过 60% 上下文窗口时才开始准备交接文件。判断标准不是任务多大而是会不会撑爆窗口。关键要点交接文件是跨会话连续性的最小基础设施五段结构已验证 / 本轮改动 / 未验证 / 下一步 / 命令覆盖了状态基线、变更边界、风险、行动与可复现性五个维度。当前已验证必须与实际跑过的验证一一对应结论没有验证支撑就等于没有结论。下一步最佳动作必须包含可判定的 passing 标准与不要动清单前者防含糊后者防回归。验证命令必须真实可执行并与init.sh、package.json脚本保持一致。交接质量直接决定下一会话的 rebuild cost这是衡量 harness 好坏的关键指标也是 Lecture 05 全篇的核心命题。【免费下载链接】learn-harness-engineeringHarness engineering beginner tutorial, from 0 to 1项目地址: https://gitcode.com/gh_mirrors/le/learn-harness-engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考